@mcpcloud/runtime 0.7.1 → 0.12.0

package/dist/sandbox/types.d.ts

@@ -32,9 +32,19 @@ export interface SandboxLimits {
      * 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';
+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.
  *
@@ -44,13 +54,73 @@ export type SandboxBudget = 'opcodes' | 'memory' | 'stack' | 'wall_clock';
  * 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';
+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;
@@ -61,5 +131,13 @@ export interface SandboxFailure {
     /** 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). */