prd phase 2.3 callable functions

PRD: Phase 2.3 — Callable-function scripts

Status: not started. Research: research-phase-2.3-sandbox.md. Technical design: to be written (design-phase-2.3-callable-functions.md) before implementation, per the feature-development workflow.

Problem Statement

Some capabilities an agent needs are not available as MCP servers — they live behind cloud-vendor HTTP APIs (e.g. a document-translation API, an OCR service, an image generator, a proprietary search endpoint). Today there is no way to expose those to an agent tool through Harness Nexus: the proxy only aggregates upstream MCP servers. An admin who wants to give agents access to a vendor API has no in-product path and must run a separate MCP wrapper server. There needs to be a way for an admin to author a small function that calls the vendor API and expose it as an MCP tool, running safely on the Harness Nexus host.

Solution

Admin-authored JavaScript functions, stored and managed in Harness Nexus, compiled and executed in a sandbox, and exposed as MCP tools alongside upstream tools through the same profile-based proxy. The sandbox has no filesystem or subprocess access and can only make network calls to an admin-specified host allowlist, mediated by a host-injected ctx.fetch. Functions are bundled into profiles like MCP servers, so an agent tool connecting with ?profile=<id> sees both upstream tools and callable-function tools in one aggregated surface.

User Stories

1. As an admin, I want to author a JS function that calls a vendor API, so that agents can use it without a separate MCP server.
2. As an admin, I want the function's network calls restricted to a host allowlist, so that a buggy or malicious script can't exfiltrate data.
3. As an admin, I want the sandbox to have no filesystem or subprocess access, so that the host is protected.
4. As an admin, I want to define the function's input schema, so that agents know what arguments to pass.
5. As an admin, I want to set a per-call timeout, so that a hung vendor API doesn't block the proxy.
6. As an admin, I want to bind a credential to a callable-function, so that it can authenticate to the vendor without the script seeing the secret.
7. As an admin, I want to test-run a function from the UI before publishing, so that I can verify it works.
8. As an admin, I want to disable a function without deleting it, so that I can take a broken tool offline temporarily.
9. As a user, I want callable-functions included in a profile alongside MCP servers, so that my agent sees one unified tool set.
10. As an agent tool, I want to call a callable-function the same way I call an upstream tool, so that the transport is transparent.
11. As an admin, I want only admins to author functions, so that untrusted users can't run arbitrary sandboxed code.
12. As an operator, I want each invocation audited, so that I can investigate sensitive API calls.
13. As a developer, I want callable-functions to plug into the existing proxy without changing the upstream connection pool, so that the McpRegistry stays focused.
14. As an admin, I want input validated before entering the sandbox, so that the script never sees malformed arguments.
15. As an operator, I want a callable-function crash isolated, so that one bad script doesn't take down the proxy.

Implementation Decisions

• Sandbox: isolated-vm (V8 native Isolate) — chosen over node:vm (escapable), vm2 (deprecated), and worker_threads (not a security boundary). Keeps V8 performance; fatal errors don't crash the host. Backup option: quickjs-emscripten if native builds are a hard blocker. See research-phase-2.3-sandbox.md.
• Dedicated CallableFunction entity (not reuse of the deferred Resource module). Carries source, inputSchema, allowedHosts, timeoutMs, scope, ownerId, status. ResourceKind = 'command' left as a forward-compat slot.
• ToolSource abstraction: an interface (listTools, callTool) with two implementations — McpRegistry (existing upstream pool) and a new CallableRegistry (sandboxed scripts). The proxy merges both; callTool routes by namespace prefix (<server>__ → McpRegistry, fn__ → CallableRegistry). McpRegistry's connection semantics stay untouched.
• Network via injected ctx.fetch: the script receives only a host-proxied fetch that enforces allowedHosts. The real fetch never enters the sandbox. Credentials are decrypted host-side and added to outgoing headers by the proxy, so plaintext secrets stay outside the sandbox.
• Host-side input validation: args validated against inputSchema (zod) before the sandbox runs; script-internal validation is not trusted.
• Admin-only authoring: creation/mutation restricted to admins (consistent with the established 2.3 constraint). Scope still global/personal for profile referencing.
• Profile integration: profileEntryInputSchema extended to accept callable-function entries; profileEntriesFor() returns callable-function ids alongside serverIds; buildSession registers them on the same per-session SdkMcpServer.
• Config: new env fields sandboxTimeoutMs, callableFunctionAllowedHosts (instance-level default), following the existing config.ts pattern.
• Migration: a new SQLite table for callable-functions.

Testing Decisions

• HTTP smoke tests: callable-function CRUD (admin-only), profile entry with a callable-function, the function exposed as a tool via the proxy, ctx.fetch allowlist enforcement (blocked host → error), timeout enforcement, crash isolation (one bad function doesn't break others).
• Sandbox behavior tested at the API seam (call the tool, assert the response/error), not by inspecting sandbox internals.
• Prior art: the Phase 2.2 smoke tests for profile routing and /mcp proxy gating.

Out of Scope

• A full code editor with syntax checking in the UI (a textarea + test-run is sufficient for 2.3).
• Non-admin authoring of functions.
• Functions that need filesystem or subprocess access (deliberately impossible).
• Reusing the Resource aggregate / building the generic Resource module.
• Sharing callable-functions via the ECC/Superpower import pipeline.
• Per-call credential selection beyond a single bound credential.

Further Notes

• Suggested sub-phasing: 2.3.1 core (entity + CRUD + executor + ToolSource integration + smoke tests, no UI) then 2.3.2 UI (management page + profile picker). Confirm scope when starting.
• The full technology comparison (isolated-vm vs QuickJS-WASM vs others) and the network-access design are in research-phase-2.3-sandbox.md.