@mcpcloud/runtime 0.7.0 → 0.12.0

package/dist/sandbox/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The sandbox's public shapes: what you may configure, and what you get back.
+ *
+ * Kept separate from the implementation so callers (and the dispatch worker,
+ * which will only ever hold a result) can import the types without pulling in
+ * the engine.
+ */
+/**
+ * Ceilings applied to a single execution. Every one is required — there is no
+ * "unlimited" default, because an unbounded sandbox running agent-authored code
+ * is the thing this module exists to prevent.
+ */
+export interface SandboxLimits {
+    /**
+     * Interrupt-handler ticks before the execution is killed.
+     *
+     * This is the primary control and the metering unit (§3): it is deterministic,
+     * reproducible, and independent of how loaded the machine is — unlike
+     * wall-clock, which is neither.
+     */
+    opcodeBudget: number;
+    /** Guest heap ceiling, well inside the 128 MB isolate limit. */
+    memoryBytes: number;
+    /** Guards runaway recursion, which memory alone does not catch quickly. */
+    stackBytes: number;
+    /**
+     * Wall-clock backstop, in milliseconds.
+     *
+     * Deliberately secondary. On workerd — our primary host — `Date.now()` does
+     * not advance during synchronous execution, so a deadline cannot fire in the
+     * middle of a tight loop. Opcodes catch that case; this catches an execution
+     * that is slow because it is waiting, once tool calls exist in P2.
+     */
+    wallClockMs: number;
+    /**
+     * Upstream calls one execution may make.
+     *
+     * Not a cost control — §9.4's "10,000 calls costs $0.15" bounds the COST of a
+     * runaway, not the HARM. This bounds how much an injected or mistaken agent
+     * can do in one request, which is the thing that actually matters (§7.4).
+     */
+    maxToolCalls: number;
+}
+/** Which ceiling an execution hit. Named so a caller can retry narrower. */
+export type SandboxBudget = 'opcodes' | 'memory' | 'stack' | 'wall_clock'
+/** One execution can issue thousands of upstream calls from a loop (§6). */
+ | 'tool_calls';
+/**
+ * Why an execution failed.
+ *
+ * `budget_exhausted` is separated from `runtime_error` on purpose: they call for
+ * opposite responses. A guest exception means the code is wrong; a budget means
+ * the code may be fine and the input too large. §8.3 turns on that distinction —
+ * naming the budget lets an agent retry with a narrower query instead of
+ * rewriting working code.
+ */
+export type SandboxFailureKind = 'syntax_error' | 'runtime_error' | 'budget_exhausted' | 'timeout'
+/**
+ * A tool call was refused by policy — not a code defect.
+ *
+ * Separate from `runtime_error` because §7.2's classes exist to drive opposite
+ * responses: a refusal means stop and escalate, while a runtime error means
+ * rewrite. Reporting a refusal as a code bug invites the agent to rewrite
+ * code that was fine, which is the expensive failure the taxonomy exists to
+ * prevent.
+ */
+ | 'policy_denied';
+/** One tool call the guest made, as the failure digest will render it (§7.3). */
+export interface SandboxSpan {
+    /** Tool name as the guest called it. */
+    name: string;
+    /**
+     * Arguments, recorded as VALUES rather than shapes. They are small and
+     * agent-authored — the guest wrote them, so echoing them back leaks nothing
+     * it did not already know, and they are what a corrected call needs.
+     */
+    args: unknown;
+    durationMs: number;
+    /** Structure of what came back. Never the content — see shape.ts. */
+    resultShape?: string;
+    /** Distributional facts about the result, when it is an array of records. */
+    facts?: string[];
+    error?: string;
+    /**
+     * Payload size either side of the tool's JMESPath projection, when it has
+     * one. Present only if a projection ran, so an unprojected tool adds no noise.
+     * Feeds the same savings telemetry the direct-call path already reports.
+     */
+    preProjectionBytes?: number;
+    postProjectionBytes?: number;
+    /**
+     * Whether this call may have changed anything upstream. Unknown resolves to
+     * true: misclassifying a mutation as a read is the one error with
+     * irreversible consequences (§7.4).
+     */
+    mutates: boolean;
+}
+/**
+ * One `console.*` call the guest made (§7.5).
+ *
+ * Kept in the trace always, surfaced inline only when the execution failed — a
+ * successful run returned what was asked for, and its logs in context would
+ * reintroduce the cost Code Mode removes.
+ */
+export interface SandboxLogEntry {
+    level: string;
+    /**
+     * Already rendered: strings literal and capped, everything else summarized to
+     * a SHAPE. A logged object is usually a tool result the agent is inspecting,
+     * which is the content the token wall exists to keep out.
+     */
+    message: string;
+}
+export interface SandboxSuccess {
+    ok: true;
+    /** Whatever the guest returned, marshalled through JSON. */
+    value: unknown;
+    /** Interrupt ticks consumed. The metering read (§3). */
+    opcodesUsed: number;
+    /** One per tool call, in call order. */
+    spans: SandboxSpan[];
+    /** `console.*` output, in call order. Never surfaced on success. */
+    logs: SandboxLogEntry[];
+}
+export interface SandboxFailure {
+    ok: false;
+    kind: SandboxFailureKind;
+    message: string;
+    /** Present only when `kind` is `budget_exhausted`. */
+    budget?: SandboxBudget;
+    /** Guest stack, when the engine produced one. Harness frames are stripped. */
+    stack?: string;
+    opcodesUsed: number;
+    /**
+     * Calls made before the failure. These are the partial results: the agent can
+     * see what already ran and write a follow-up that skips it, which is cheaper
+     * and more flexible than resuming a heap (§7.7).
+     */
+    spans: SandboxSpan[];
+    /** `console.*` output, in call order — the mid-execution view (§7.5). */
+    logs: SandboxLogEntry[];
+}
+export type SandboxResult = SandboxSuccess | SandboxFailure;

package/dist/server.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { CallerContext, RuntimeConfig, RuntimeEnv, ServerIdentity } from './config';
+import type { CodeModeOptions } from './sandbox/codeModeTool';
 import type { PromptDefinition, ResourceDefinition, ToolDefinition } from './types';
 export type ToolHandler = (input: unknown, config: RuntimeConfig, caller: CallerContext) => Promise<CallToolResult>;
 export interface RegisteredTool {
@@ -16,6 +17,18 @@ export interface DefineServerOptions {
     prompts?: PromptDefinition[];
     /** Resources served via `resources/list` / `resources/read` (#78). */
     resources?: ResourceDefinition[];
+    /**
+     * Code Mode. Registers `codemode_execute` ALONGSIDE whatever discoveryMode
+     * already exposes — the search/execute pair the design is modelled on, not a
+     * replacement for either.
+     *
+     * Needs both a non-`off` mode and an engine. Codegen emits the mode from the
+     * server's setting; the host supplies the engine. A server whose operator
+     * turned Code Mode on still registers nothing on a host that cannot run it,
+     * which is the honest outcome — but it is also why the setting alone is not
+     * yet enough to make the tool appear on the Workers edge.
+     */
+    codeMode?: CodeModeOptions;
 }
 export interface GeneratedServer {
     /** Build a fresh McpServer (per request — handler closures are isolation-safe). */