@qduc/term2 0.20.0 → 0.22.0

package/dist/tools/system/run-code/run-code-telemetry.js

@@ -0,0 +1,189 @@
+import { createHash } from 'node:crypto';
+/**
+ * Structured completion telemetry for one `run_code` invocation.
+ *
+ * One event per invocation, written through the application logger so it lands
+ * in the same durable JSONL app log as every other structured event. It exists
+ * to answer the question that gates the type-checked TypeScript slice
+ * (docs/plans/run-code-typescript.md): do statically preventable nested-call
+ * failures actually cause retries, false completion, or replay? The answer is
+ * derived by querying these events, not by re-reading conversations, so the
+ * event carries the join keys (sessionId, sourceDigest, outcome, timestamp) as
+ * well as the counts.
+ *
+ * Emitted at `info`: the default log level is `info`, so the older
+ * `run_code execution finished` line, which is `debug`, is absent from default
+ * app logs and cannot be counted.
+ *
+ * Privacy: every emitted value is a number, an enum drawn from a closed set, or
+ * a source digest. The script source, its arguments, the failure messages, tool
+ * names, workspace paths, and the model-authored `description` are deliberately
+ * never emitted — nested failure text routinely carries paths and arguments, and
+ * an unknown member name is arbitrary model-authored text. Failure attribution
+ * reads those messages in-process and emits only a class.
+ */
+export const RUN_CODE_COMPLETION_EVENT = 'tool.run_code.completion';
+export const RUN_CODE_COMPLETION_MESSAGE = 'run_code completed';
+const SOURCE_DIGEST_CHARS = 16;
+/**
+ * Stable identity for a script's source, so repetition and replay are visible
+ * by joining events instead of storing the source itself.
+ */
+const digestSource = (code) => createHash('sha256').update(code, 'utf8').digest('hex').slice(0, SOURCE_DIGEST_CHARS);
+const NESTED_BUCKET_BY_OUTCOME = {
+    ok: 'ok',
+    error: 'otherFailures',
+    approval_required: 'approvalDenied',
+    unknown_policy: 'otherFailures',
+    policy_error: 'otherFailures',
+    interceptor_denied: 'otherFailures',
+    unknown_tool: 'unknownTool',
+    invalid_params: 'invalidParams',
+    prohibited: 'prohibited',
+    describe: 'schemaLookups',
+};
+const summarizeNestedCalls = (calls) => {
+    const counts = {
+        calls: 0,
+        schemaLookups: 0,
+        ok: 0,
+        unknownTool: 0,
+        invalidParams: 0,
+        approvalDenied: 0,
+        prohibited: 0,
+        otherFailures: 0,
+    };
+    for (const call of calls) {
+        const bucket = NESTED_BUCKET_BY_OUTCOME[call.outcome];
+        if (bucket === 'schemaLookups') {
+            counts.schemaLookups += 1;
+            continue;
+        }
+        counts.calls += 1;
+        counts[bucket] += 1;
+    }
+    return counts;
+};
+const summarizeEffectReceipts = (receipts) => {
+    const counts = { applied: 0, notApplied: 0, failed: 0, unknown: 0 };
+    for (const receipt of receipts) {
+        if (receipt.outcome === 'applied')
+            counts.applied += 1;
+        else if (receipt.outcome === 'not_applied')
+            counts.notApplied += 1;
+        else if (receipt.outcome === 'failed')
+            counts.failed += 1;
+        else
+            counts.unknown += 1;
+    }
+    return counts;
+};
+/**
+ * The namespace binding prefixes a refused nested call with `tools.<member>
+ * failed: ` and the capability's own message after it (host-worker.ts, pinned by
+ * sandboxed-code-host.test.ts). That prefix is the only host-side signal that
+ * separates a failure the script caused from one a nested call rejected, until
+ * Stage 3A gives the refusal a typed envelope.
+ */
+const FAILED_CALL_MARKER = ' failed: ';
+const NAMESPACE_PREFIX = 'tools.';
+const UNKNOWN_TOOL_PREFIX = 'Unknown tool "';
+const INVALID_PARAMS_PREFIX = 'Invalid parameters for "';
+const nestedRejectionDetail = (message) => {
+    if (!message.startsWith(NAMESPACE_PREFIX))
+        return null;
+    const marker = message.indexOf(FAILED_CALL_MARKER);
+    if (marker <= NAMESPACE_PREFIX.length)
+        return null;
+    return message.slice(marker + FAILED_CALL_MARKER.length);
+};
+/**
+ * Attribution is message-based, so a script that throws the same text itself is
+ * misattributed as a nested rejection. That approximation is bounded to the
+ * failure class: the host code, the ledgers, and the counts stay exact.
+ */
+const classifyNestedFailure = (message) => {
+    if (message.startsWith(UNKNOWN_TOOL_PREFIX))
+        return 'unknown-tool';
+    const detail = nestedRejectionDetail(message);
+    if (detail === null)
+        return 'nested-call';
+    if (detail.startsWith(UNKNOWN_TOOL_PREFIX))
+        return 'unknown-tool';
+    if (detail.startsWith(INVALID_PARAMS_PREFIX))
+        return 'parameter-shape';
+    return 'nested-call';
+};
+const isNestedRejection = (message) => message.startsWith(UNKNOWN_TOOL_PREFIX) || nestedRejectionDetail(message) !== null;
+const assertNeverHostCode = (code) => {
+    throw new Error('Unhandled host error code: ' + String(code));
+};
+const classifyRunCodeCompletion = (result) => {
+    if (result.ok)
+        return { outcome: 'success' };
+    const { code, message } = result.error;
+    switch (code) {
+        case 'syntax_error':
+            return { outcome: 'parse', hostErrorCode: code };
+        case 'runtime_error':
+            return isNestedRejection(message)
+                ? { outcome: 'nested-validation', hostErrorCode: code, failureClass: classifyNestedFailure(message) }
+                : { outcome: 'runtime', hostErrorCode: code };
+        case 'invalid_output':
+            return { outcome: 'return-serialization', hostErrorCode: code };
+        case 'timeout':
+        case 'deadline':
+            return { outcome: 'timeout', hostErrorCode: code };
+        case 'cancelled':
+            return { outcome: 'cancelled', hostErrorCode: code };
+        case 'code_too_large':
+            return { outcome: 'input-rejected', hostErrorCode: code };
+        case 'sandbox_unavailable':
+            return { outcome: 'host-unavailable', hostErrorCode: code };
+        case 'limit_exceeded':
+            return { outcome: 'nested-validation', hostErrorCode: code, failureClass: 'budget' };
+        case 'approval_required':
+            return { outcome: 'nested-validation', hostErrorCode: code, failureClass: 'approval-denied' };
+        default:
+            // Exhaustive over HostErrorCode: a new code fails to compile here rather
+            // than reaching a silent fallback.
+            return assertNeverHostCode(code);
+    }
+};
+/**
+ * The event's fields. Exported for tests; the emit path below is the only
+ * caller in production.
+ */
+export const buildRunCodeCompletionMeta = (input) => {
+    const classification = classifyRunCodeCompletion(input.result);
+    return {
+        eventType: RUN_CODE_COMPLETION_EVENT,
+        // Not imported from run-code.ts: that module imports this one.
+        toolName: 'run_code',
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(input.runId ? { runId: input.runId } : {}),
+        outcome: classification.outcome,
+        ...(classification.hostErrorCode ? { hostErrorCode: classification.hostErrorCode } : {}),
+        ...(classification.failureClass ? { failureClass: classification.failureClass } : {}),
+        durationMs: Math.max(0, Math.round(input.durationMs)),
+        timeoutMs: input.timeoutMs,
+        sourceBytes: Buffer.byteLength(input.code, 'utf8'),
+        sourceLines: input.code.length === 0 ? 0 : input.code.split('\n').length,
+        sourceDigest: digestSource(input.code),
+        nested: summarizeNestedCalls(input.calls),
+        effectReceipts: summarizeEffectReceipts(input.receipts),
+    };
+};
+/**
+ * Record one completion. Telemetry is diagnostic: a failure to build or write
+ * the event must never change what the script did or what the caller receives.
+ */
+export function emitRunCodeCompletionTelemetry(loggingService, input) {
+    try {
+        loggingService.info(RUN_CODE_COMPLETION_MESSAGE, buildRunCodeCompletionMeta(input));
+    }
+    catch {
+        // Intentionally ignored. See above.
+    }
+}
+//# sourceMappingURL=run-code-telemetry.js.map

package/dist/tools/system/run-code/run-code-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-code-telemetry.js","sourceRoot":"","sources":["../../../../source/tools/system/run-code/run-code-telemetry.ts"],"names":[],"mappings":"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"}

package/dist/tools/system/run-code/run-code.d.ts

@@ -0,0 +1,98 @@
+import type { ExecutionContext } from '../../../services/execution-context.js';
+import { z } from 'zod';
+import type { ILoggingService } from '../../../services/service-interfaces.js';
+import type { ToolApprovalPolicyRegistry } from '../../../services/approval/tool-approval-policy-registry.js';
+import type { NestedApprovalOwner } from '../../../services/approval/nested-approval-owner.js';
+import { type AnyToolDefinition, type FormatCommandMessage, type SchemaToolDefinition, type ToolRegistry } from '../../types.js';
+export declare const TOOL_NAME_RUN_CODE = "run_code";
+export declare const TOOL_NAME_DESCRIBE = "describe";
+/**
+ * Script-shaped limits. They are deliberately not the workflow's: a workflow
+ * spawns a handful of agents, while a script's whole point is looping over many
+ * cheap tool calls.
+ */
+export declare const RUN_CODE_LIMITS: {
+    /** Total `tools.*` calls one script may make. */
+    readonly maxCalls: 200;
+    /** Parallel-safe calls that may overlap; others take a serial lane of one. */
+    readonly maxConcurrency: 8;
+    /** Per-result cap. A larger result is truncated with an explicit marker. */
+    readonly maxResultChars: 100000;
+    /** Maximum raw bytes in one media attachment retained outside the script. */
+    readonly maxMediaBytes: number;
+    /** Maximum raw bytes and attachment count retained for one script run. */
+    readonly maxMediaTotalBytes: number;
+    readonly maxMediaAttachments: 32;
+    readonly maxCodeBytes: 65536;
+    readonly maxOutputBytes: 262144;
+    readonly maxConsoleBytes: 262144;
+};
+/**
+ * Tools a script may never call.
+ *
+ * `run_code` excludes itself because each run owns its own call budget, and
+ * nesting would let one run spend many. The rest are the workflow's prohibited
+ * set: `run_subagent` in particular spawns agents outside any run budget, so a
+ * script could loop on it indefinitely. Shell tools are excluded because their
+ * complete approval state also lives in the interactive batch coordinator.
+ */
+export declare const RUN_CODE_PROHIBITED_TOOLS: ReadonlySet<string>;
+export declare const runCodeParametersSchema: z.ZodObject<{
+    code: z.ZodString;
+    include_console: z.ZodOptional<z.ZodBoolean>;
+    timeout_ms: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    description: z.ZodString;
+}, z.core.$strip>;
+export type RunCodeParams = z.infer<typeof runCodeParametersSchema>;
+/**
+ * Terminal semantic outcome of one observed nested action call, derived
+ * host-side from the raw executor result. Promise fulfillment alone is never
+ * success: only the per-tool adapter maps a resolved value to `applied`.
+ */
+export type RunCodeActionOutcome = 'applied' | 'not_applied' | 'failed' | 'unknown';
+/**
+ * One host-observed nested action receipt. The ledger is host-private: script
+ * code has no write path to it, so a script cannot catch, relabel, or
+ * contradict its way out of an observed outcome.
+ */
+export interface RunCodeActionReceipt {
+    /** Stable call identity (`<bridgeRunId>:<callId>`, or `:rejected-<seq>` pre-admission). */
+    callId: string;
+    tool: string;
+    outcome: RunCodeActionOutcome;
+    reason?: string;
+}
+/** One `tools.*` call observed during a run, for the user-facing summary. */
+export interface RunCodeCallRecord {
+    tool: string;
+    outcome: 'ok' | 'error' | 'approval_required' | 'unknown_policy' | 'policy_error' | 'interceptor_denied' | 'unknown_tool' | 'invalid_params' | 'prohibited' | 'describe';
+    durationMs: number;
+    directlyCallable?: boolean;
+}
+export interface CreateRunCodeToolOptions {
+    loggingService: ILoggingService;
+    /**
+     * Resolves the tools exposed to the script. Supplying it directly is a test
+     * seam; in production {@link bindRunCodeRegistry} installs the wrapped
+     * registry, so scripts go through the same policy layer as a direct call.
+     */
+    getToolRegistry?: () => ToolRegistry;
+    /** Policy authority used for out-of-band script calls. */
+    approvalPolicyRegistry: ToolApprovalPolicyRegistry;
+    getCwd?: () => string;
+    executionContext?: ExecutionContext;
+    nestedApprovalOwner?: NestedApprovalOwner;
+    sessionAccess?: import('../../../services/session/session-access-state.js').SessionAccessState;
+    nestedCompatibility?: import('../../../services/session/nested-tool-compatibility-state.js').NestedToolCompatibilityState;
+}
+/** Installs the wrapped registry into any `run_code` definition in `tools`. */
+export declare function bindRunCodeRegistry(tools: ToolRegistry): void;
+export declare function bindRunCodeNestedApprovalOwner(tools: ToolRegistry, owner: NestedApprovalOwner): void;
+/**
+ * Direct calls are the tools a script structurally cannot reach, including
+ * `run_code` itself. Visibility does not depend on `canRequireApproval`.
+ */
+export declare function isDirectlyCallable(tool: Pick<AnyToolDefinition, 'name'>): boolean;
+export declare const formatRunCodeCommandMessage: FormatCommandMessage;
+export declare function createRunCodeToolDefinition(options: CreateRunCodeToolOptions): SchemaToolDefinition<typeof runCodeParametersSchema>;
+//# sourceMappingURL=run-code.d.ts.map

package/dist/tools/system/run-code/run-code.d.ts.map

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