@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/tool-mode-run.d.ts

@@ -0,0 +1,310 @@
+/**
+ * The ONE authorized program-execution pipeline (CODE-02, CODE-03, CODE-08, ARCH-05).
+ *
+ * THE DEFECT THIS FIXES, found by adversarial review rather than by a test:
+ * `ptc-authority.ts` and `ptc-runtime.ts` had **zero callers outside tests**. Everything in
+ * them was correct and thoroughly covered — `buildToolBindings`, the guarded mount,
+ * `mayExposeToClients()` — and none of it ran in production. `tool_mode_run` did not exist,
+ * the mount guard never executed, and the exposure gate guarded nothing because there was
+ * no caller to refuse.
+ *
+ * A security control with no callers is not a control; it is a symbol. This module is the
+ * caller.
+ *
+ * The wiring enforces three things the directive requires and nothing else did:
+ *
+ * 1. **ONE pipeline.** Native PTC and any external `tool_mode_run` reach tools through the
+ *    SAME `buildToolBindings` call, so authorization cannot differ between the two doors.
+ * 2. **The grant is the grant.** The requested names are intersected with the host's own
+ *    `allowedTools` and the live registry, and the whole request is refused if anything is
+ *    unattainable.
+ * 3. **The exposure gate has a caller.** `mayExposeToClients()` returning false now
+ *    actually refuses something, with the reason attached.
+ *
+ * @module @try-works/dsh-tool-mode/tool-mode-run
+ */
+import { PTC_SERVICE, type PtcHostContext } from './ptc-runtime.ts';
+import type { ToolBinding } from './ptc-authority.ts';
+/** The runtime surface this module needs, narrowed so it is testable. */
+export interface ProgramRuntime {
+    resolve(request: Record<string, unknown>): unknown;
+    run(spec: unknown): Promise<{
+        readonly value?: unknown;
+        readonly logs?: readonly string[];
+        readonly error?: {
+            readonly kind?: string;
+            readonly message?: string;
+        };
+    }>;
+}
+/** How to reach the tools a program may call. */
+export interface RunnerEnvironment {
+    /** The host's context, for the guarded mount. */
+    readonly context: PtcHostContext;
+    /**
+     * The backend plugin, or undefined when it could not be resolved. May be a
+     * thunk: the host resolves the backend LAZILY so a deployment without the
+     * package still loads the plugin, and `prepare()` materializes it at most once.
+     */
+    readonly backend: unknown | (() => Promise<unknown>);
+    /**
+     * The grant a program's sub-calls authorize against, READ PER RUN.
+     *
+     * A FUNCTION rather than a value because of SEC-04's composition rule: an
+     * external client's `tool_mode_run` call must compose under the CLIENT's grant,
+     * not the host's — otherwise a client granted only `tool_mode_run` could reach
+     * every host-granted tool through a program. The host wires this to an
+     * {@link ExternalGrantContext}, which returns the caller's grant when the run
+     * happens inside an external call and the host's own grant otherwise.
+     */
+    readonly grant: () => readonly string[];
+    /** The tool names currently registered, read at RUN time so late registrations are visible. */
+    readonly visible: () => readonly string[];
+    /** Tool names blocked by the operator confidentiality policy (MCP-11), read per run. */
+    readonly confidential?: () => readonly string[];
+    /** Resolves one authorized name to its implementation. */
+    readonly resolve: (name: string) => ToolBinding | undefined;
+    /** The runtime, once mounted. */
+    readonly runtime: () => ProgramRuntime | undefined;
+    /** Whether the OPERATOR granted hosted code execution (CODE-10), read at check time. */
+    readonly operatorGranted: () => boolean;
+    /** ROOT budgets for one program (CODE-11): shared by every nested call. */
+    readonly budgets?: {
+        readonly maxToolCalls?: number;
+        readonly maxHarnessModelCalls?: number;
+        readonly isHarnessTool?: (name: string) => boolean;
+    };
+}
+/**
+ * The per-call external grant carrier (SEC-04, composition).
+ *
+ * `AsyncLocalStorage` rather than a module global: the context travels with the
+ * async chain of ONE call, so two concurrent external clients cannot see each
+ * other's grants, and the native/interactive path (no context) reads the host's
+ * own grant — unchanged behavior.
+ */
+export interface ExternalGrantContext {
+    /** Run work with an external client's grant in force. */
+    run<T>(grant: readonly string[], work: () => Promise<T>, profiles?: readonly string[], remoteDestinations?: readonly string[]): Promise<T>;
+    /** The grant in force, or undefined on the host/interactive path. */
+    current(): readonly string[] | undefined;
+    /** Allowed harness profiles for the caller in force, or undefined on the host path. */
+    currentProfiles(): readonly string[] | undefined;
+    /** Approved remote destinations for the caller in force, or undefined on the host path. */
+    currentRemoteDestinations(): readonly string[] | undefined;
+}
+/** Create the per-call external grant carrier. */
+export declare function createExternalGrantContext(): ExternalGrantContext;
+/** A request to run a program. */
+export interface ProgramRequest {
+    /** The program source. */
+    readonly program: string;
+    /** The tool names the program declares it will call. */
+    readonly requested: readonly string[];
+    /** Structured program data exposed as `input`; never interpolated into source. */
+    readonly input?: unknown;
+    /** Cancellation, propagated to the runtime. */
+    readonly signal?: AbortSignal;
+    /** A requested budget, CLAMPED rather than honoured. */
+    readonly timeoutMs?: number | null;
+    readonly cwd?: string;
+}
+/** The outcome of a run. */
+export type ProgramOutcome = {
+    readonly ok: true;
+    readonly value: unknown;
+    readonly logs: readonly string[];
+    readonly toolCalls: number;
+    /** Bounded trace of the sub-calls, in dispatch order (CODE-02). */
+    readonly calls: readonly ProgramCall[];
+} | {
+    readonly ok: false;
+    readonly code: 'unavailable' | 'unauthorized' | 'cancelled' | 'failed';
+    readonly message: string;
+};
+/**
+ * One sub-call a program made, as the run reports it.
+ *
+ * The trace exists so a reader (and the chat card) can see WHICH tools a program combined,
+ * in order. It is BOUNDED and PREVIEWED: a program may call a tool 500 times or pass a
+ * 4 MB vector, and the report is provenance rather than a data dump.
+ */
+export interface ProgramCall {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly elapsedMs: number;
+    /** First {@link PREVIEW_CHARS} characters of the arguments, JSON-encoded. */
+    readonly argumentsPreview: string;
+    /** First {@link PREVIEW_CHARS} characters of the result; absent on failure. */
+    readonly resultPreview?: string;
+    /** The failure message when the sub-call threw. */
+    readonly error?: string;
+}
+/** The runner the host uses. */
+export interface ProgramRunner {
+    /** Mount the backend at most once, through the guard. */
+    prepare(): Promise<{
+        readonly mounted: boolean;
+        readonly reason?: string;
+    }>;
+    /** Run one program through the authorized pipeline. */
+    run(request: ProgramRequest): Promise<ProgramOutcome>;
+    /** Whether an EXTERNAL caller may be served generated-code execution (CODE-08). */
+    externalExposurePermitted(): boolean;
+    /** Why not, when it is not. */
+    externalExposureReason(): string;
+}
+/**
+ * Create the runner.
+ *
+ * @param environment - how to reach tools and the runtime.
+ * @returns the runner.
+ */
+export declare function createProgramRunner(environment: RunnerEnvironment): ProgramRunner;
+/**
+ * The refusal an EXTERNAL caller receives (CODE-08).
+ *
+ * A separate function so the gate has a single enforcement point rather than a condition
+ * repeated at each call site — the shape that let the original gate go unused.
+ * @param runner - the runner.
+ * @returns the refusal, or undefined when exposure is permitted.
+ */
+export declare function externalRefusal(runner: ProgramRunner): {
+    readonly message: string;
+} | undefined;
+/** The service key the runner depends on, re-exported so a caller need not import both. */
+export { PTC_SERVICE };
+/** What the CODE-02 tool returns for one run. */
+export interface RunReport {
+    readonly result: unknown;
+    readonly logs: readonly string[];
+    readonly meta: {
+        readonly receiptId: string;
+        readonly elapsedMs: number;
+        readonly toolCalls: number;
+        /** The bounded sub-call trace, in dispatch order: which tools combined, and how. */
+        readonly calls: readonly ProgramCall[];
+        readonly catalogRevision: string;
+        readonly warnings: readonly string[];
+        /** TypeScript bindings for exactly the authorized tool set (CODE-03). */
+        readonly typescript: string;
+    };
+}
+/**
+ * The `tool_mode_run` MCP contract, in the ToolContract shape (CODE-02).
+ *
+ * ONE definition serves the MCP export surface and the conformance test, so the
+ * two cannot drift the way an inline object at the export site would: the test
+ * validates this shape's MCP projection against the pinned schema before it ever
+ * ships on a live tools/list.
+ */
+export declare const TOOL_MODE_RUN_CONTRACT: {
+    readonly contract: "hosted.tool_mode_run";
+    readonly version: "1.0.0";
+    readonly toolName: "tool_mode_run";
+    readonly description: "Run a program that calls Tool Mode tools (CODE-02).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["code", "tools"];
+        readonly properties: {
+            readonly description: {
+                readonly type: "string";
+            };
+            readonly code: {
+                readonly type: "string";
+            };
+            readonly input: {};
+            readonly tools: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly timeout_ms: {
+                readonly type: "integer";
+            };
+        };
+    };
+    readonly outputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly result: {};
+            readonly logs: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            /**
+             * The meta envelope is declared CLOSED with every field the run reports. The host's
+             * output validator treats an object without an explicit `additionalProperties` as
+             * closed, so the sub-call trace must be named here or every run fails its own
+             * schema with `value.meta.calls is not a declared property`.
+             */
+            readonly meta: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly receiptId: {
+                        readonly type: "string";
+                    };
+                    readonly elapsedMs: {
+                        readonly type: "number";
+                    };
+                    readonly toolCalls: {
+                        readonly type: "number";
+                    };
+                    readonly catalogRevision: {
+                        readonly type: "string";
+                    };
+                    readonly warnings: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly typescript: {
+                        readonly type: "string";
+                    };
+                    readonly calls: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: true;
+                        };
+                    };
+                };
+            };
+        };
+    };
+    readonly semantics: {
+        readonly deterministic: false;
+        readonly readsInputs: true;
+    };
+    readonly limits: {};
+    readonly unsupported: readonly ["no access to management or installer bindings"];
+};
+/**
+ * Serve one CODE-02 request through the authorized pipeline (CODE-02/04).
+ *
+ * This is the `tool_mode_run` served path: the caller's arguments are validated
+ * into the CODE-02 shape, the program runs through the SAME runner native PTC
+ * uses, and the report carries the receipt, elapsed time, call count, catalog
+ * revision and warnings the interface promises.
+ *
+ * `input` is refused when the pinned runtime cannot bind it structurally: CODE-04
+ * forbids string interpolation into source, and the current PTC runtime has no
+ * data-global path, so an input-bearing program gets a precise refusal naming
+ * that limitation rather than a silently interpolated program.
+ * @param args - the caller's arguments.
+ * @param runner - the prepared runner.
+ * @param report - the report-shaped facts the host owns (receipt id, revision).
+ * @returns the report.
+ */
+export declare function serveProgram(args: Record<string, unknown>, runner: ProgramRunner, report: {
+    readonly receiptId: string;
+    readonly catalogRevision: string;
+}): Promise<RunReport>;
+//# sourceMappingURL=tool-mode-run.d.ts.map

package/lib/tool-mode-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-mode-run.d.ts","sourceRoot":"","sources":["../src/tool-mode-run.ts"],"names":[],"mappings":"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"}