@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/tools/ask_user.d.ts

@@ -10,9 +10,11 @@ import { Tool } from './types.js';
 export interface AskUserOption {
     label: string;
     description: string;
+    /** Optional short explanation of what happens after this option is chosen. */
+    preview?: string;
     /**
      * Marks the option you would pick. At most one option per question may set
-     * this; the TUI badges it and starts the cursor on it.
+     * this; it appears first and the TUI badges it and starts the cursor on it.
      */
     recommended?: boolean;
 }

package/dist/agent/tools/ask_user.js

@@ -83,6 +83,12 @@ function validateOptionsArray(options) {
         if (opt.label.length > MAX_LABEL_LENGTH || opt.description.length > MAX_LABEL_LENGTH) {
             return `option label/description exceeds ${MAX_LABEL_LENGTH} character limit.`;
         }
+        if (opt.preview !== undefined && typeof opt.preview !== 'string') {
+            return 'option preview must be a string when provided.';
+        }
+        if (opt.preview !== undefined && opt.preview.length > MAX_LABEL_LENGTH) {
+            return `option preview exceeds ${MAX_LABEL_LENGTH} character limit.`;
+        }
         // Accept the boolean and its string spelling, keep the first recommended
         // option, and drop duplicates instead of failing the whole call.
         const isRecommended = !recommendedSeen && (opt.recommended === true || opt.recommended === 'true');
@@ -91,10 +97,14 @@ function validateOptionsArray(options) {
         normalized.push({
             label: String(opt.label),
             description: String(opt.description),
+            ...(opt.preview !== undefined ? { preview: opt.preview } : {}),
             ...(isRecommended ? { recommended: true } : {}),
         });
     }
-    return normalized;
+    const recommendation = normalized.findIndex(option => option.recommended === true);
+    return recommendation > 0
+        ? [normalized[recommendation], ...normalized.filter((_option, index) => index !== recommendation)]
+        : normalized;
 }
 function parseOptions(raw) {
     let parsed;
@@ -117,7 +127,15 @@ function normalizeOptions(raw) {
         return 'options_json must be an array of {label, description} options, not a single object.';
     return parseOptions(String(raw ?? ''));
 }
+function registrationFailure(message) {
+    const detail = message.trim();
+    return detail
+        ? `Error: ${detail}`
+        : 'Error: The interactive question could not be registered. Retry when question input is available.';
+}
 export const askUserTool = {
+    // Validation and UI registration failures must use the runtime's failure path.
+    isErrorResult: (content) => /^Error[: ]/u.test(content),
     definition: {
         name: 'ask_user',
         description: `Ask the user one or more questions with predefined options. Use this to get user preferences, clarify requirements, or confirm approach before proceeding.
@@ -132,11 +150,12 @@ Use "questions_json" to ask multiple questions at once. This is more efficient t
 
 ### options_json format
 JSON array of objects with "label" and "description" fields.
-Add "recommended": true to the single option you would pick; it is badged and pre-selected for the user. Never mark more than one option per question.
-Example: [{"label": "Option A", "description": "Use approach A", "recommended": true}, {"label": "Option B", "description": "Use approach B"}]
+Put the option you would pick first and add "recommended": true; it is badged and pre-selected for the user. Never mark more than one option per question.
+Optionally add "preview" (a short string, maximum 500 characters) to explain what happens next after choosing that option. The highlighted option shows this separately as "Next:". Keep descriptions about the choice and previews about its next step.
+Example: [{"label": "Option A", "description": "Use approach A", "recommended": true, "preview": "Run the checks, then apply approach A"}, {"label": "Option B", "description": "Use approach B"}]
 
 ### questions_json format
-JSON array of question objects, each with "question" (string) and "options" (same format as options_json).
+JSON array of question objects, each with "question" (string) and "options" (same format as options_json, including optional recommended and preview fields).
 Example: [{"question": "Which framework?", "options": [{"label": "React", "description": "Use React", "recommended": true}, {"label": "Vue", "description": "Use Vue"}]}, {"question": "Which database?", "options": [{"label": "Postgres", "description": "PostgreSQL"}, {"label": "SQLite", "description": "SQLite"}]}]`,
         parameters: {
             type: 'object',
@@ -147,11 +166,11 @@ Example: [{"question": "Which framework?", "options": [{"label": "React", "descr
                 },
                 options_json: {
                     type: 'string',
-                    description: 'JSON array of options for single question mode. Each with "label" (1-5 words) and "description", plus "recommended": true on the one option you suggest (at most one per question). Provide 2-4 options.',
+                    description: 'JSON array of options for single question mode. Each with "label" (1-5 words) and "description"; put the one recommended option first and mark "recommended": true (at most one per question). Optional "preview" (string, max 500 characters) briefly explains what happens next. Provide 2-4 options.',
                 },
                 questions_json: {
                     type: 'string',
-                    description: 'JSON array of question objects for multi-question mode. Each has "question" (string) and "options" (array of {label, description, recommended?}). Use this to ask 2+ questions at once.',
+                    description: 'JSON array of question objects for multi-question mode. Each has "question" (string) and "options" (array of {label, description, recommended?, preview?}); recommended option first, optional preview is a string of at most 500 characters. Use this to ask 2+ questions at once.',
                 },
                 allow_other: {
                     type: 'boolean',
@@ -169,7 +188,7 @@ Example: [{"question": "Which framework?", "options": [{"label": "React", "descr
         debugLog('execute called:', { hasQuestion: !!question, hasOptionsJson: !!optionsJson, hasQuestionsJson: !!questionsJson, alreadyCalled: askUserCalledThisTurn });
         if (!askUserCallback) {
             debugLog('ERROR: no callback registered');
-            return 'ask_user is not available in this context.';
+            return 'Error: ask_user is not available in this context. Use an interactive ZTC session with question input enabled.';
         }
         // If ask_user was already called this turn (parallel tool calls), the questions
         // were merged via the callback. Return a dedup message so the LLM doesn't re-ask.
@@ -228,8 +247,8 @@ Example: [{"question": "Which framework?", "options": [{"label": "React", "descr
                 questions.push({ question: q.question, options: opts, allow_other: allowOther });
             }
             const error = askUserCallback(questions);
-            if (error)
-                return error;
+            if (error !== null)
+                return registrationFailure(error);
             const wasDuplicate = askUserCalledThisTurn;
             askUserCalledThisTurn = true;
             if (wasDuplicate) {
@@ -253,8 +272,8 @@ Example: [{"question": "Which framework?", "options": [{"label": "React", "descr
             return `Error: ${parsed}`;
         }
         const error = askUserCallback([{ question, options: parsed, allow_other: allowOther }]);
-        if (error)
-            return error;
+        if (error !== null)
+            return registrationFailure(error);
         const wasDuplicate = askUserCalledThisTurn;
         askUserCalledThisTurn = true;
         if (wasDuplicate) {

package/dist/agent/tools/background.js

@@ -47,6 +47,7 @@ export const spawnBackgroundAgentTool = {
             const taskId = registry.spawn(task, {
                 maxIterations,
                 cwd: context?.cwd || process.cwd(),
+                onUsage: context?.onUsage,
             });
             return `Background agent spawned (${taskId}). I'll continue working while it runs. You'll be notified when it completes.`;
         }

package/dist/agent/tools/benchmark_cpu.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const benchmarkCPUTool: Tool;

package/dist/agent/tools/benchmark_cpu.js

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto';
+import { cpus, release } from 'node:os';
+import { join } from 'node:path';
+import { CPU_CHECKER_SHA256, CPU_HOST_INSTANCE_ID, CPU_PROGRAM_SHA256, CPU_RECIPE_SHA256, integerSumOracle, parseCPUWorkload, runCPUWorkload } from '../runtime/cpu_benchmark.js';
+import { parseBenchmarkVerifierDecision } from '../runtime/benchmark_contract.js';
+import { ToolCapability } from '../runtime/capabilities.js';
+import { captureVerifierInputs } from '../runtime/verifier_capture.js';
+import { parseCommandVerificationReceipt, parseVerificationRequest } from '../runtime/source_verification_contract.js';
+export const benchmarkCPUTool = Object.freeze({
+    capabilities: Object.freeze([ToolCapability.FILE_READ, ToolCapability.SHELL_EXEC]), effect: 'write',
+    definition: { name: 'benchmark_cpu',
+        description: 'Execute the registered bounded CPU integer-sum benchmark using immutable captured JSON data and config, actual monotonic measurements and an independent exact oracle. Input is1–1024 integers with absolute value≤1000000. Config: {schema_version:1,variant:"for_loop"|"array_reduce",iterations:1–2048,warmup:0–4,samples:3|5|7|9}. Admits only this fixture; never project code, reported scores, generic command results, production/GPU performance or a plateau. Local execution and exact source-read permissions required; guarded remote sessions cannot use this adapter. Each file≤65536B.',
+        parameters: { type: 'object', additionalProperties: false, properties: {
+                adapter_id: { type: 'string', enum: ['cpu_integer_sum'] }, input_path: { type: 'string' }, config_path: { type: 'string' },
+            }, required: ['adapter_id', 'input_path', 'config_path'] } },
+    execute: async (args, context) => {
+        if (!context)
+            throw new Error('benchmark_cpu requires a host execution context');
+        if (Object.keys(args).some(key => !['adapter_id', 'input_path', 'config_path'].includes(key)) || args.adapter_id !== 'cpu_integer_sum') {
+            throw new TypeError('benchmark_cpu accepts only the registered CPU adapter and input/config paths');
+        }
+        const request = parseVerificationRequest({ purpose: 'benchmark', scope: 'benchmark:cpu_integer_sum',
+            source_paths: [args.input_path, args.config_path], instrumentation: 'production' });
+        if (!request)
+            throw new TypeError('benchmark_cpu requires two distinct bounded relative input/config paths');
+        const captured = await captureVerifierInputs(context, request.source_paths);
+        const processors = cpus();
+        if (processors.length === 0)
+            throw new Error('The benchmark CPU execution conditions are unavailable');
+        const receipt = { schema_version: 1, receipt_id: randomUUID(), source: captured.source,
+            end_source: null, purpose: 'benchmark', scope: 'benchmark:cpu_integer_sum', command_sha256: CPU_RECIPE_SHA256,
+            command_kind: 'host_verifier', build_identity: CPU_RECIPE_SHA256, instrumentation: 'unknown',
+            environment: { platform: process.platform, arch: process.arch, node_version: process.version, declared_id: null },
+            process_outcome: 'unknown', source_binding: 'unknown', qualification: 'unverified', artifact_refs: [] };
+        const input = captured.documents.get(String(args.input_path));
+        const config = captured.documents.get(String(args.config_path));
+        const binding = input !== undefined && config !== undefined && !context.signal?.aborted ? 'immutable_bytes' : 'unknown';
+        const workload = binding === 'immutable_bytes' ? parseCPUWorkload(input, config) : null;
+        let decision = { schema_version: 1, adapter_id: 'cpu_integer_sum', recipe_version: 1,
+            execution: 'host_node_subprocess', recipe_sha256: CPU_RECIPE_SHA256, receipt_id: receipt.receipt_id, source_id: receipt.source.source_id,
+            scope: 'benchmark:cpu_integer_sum', input_path: String(args.input_path), config_path: String(args.config_path), input_binding: binding,
+            outcome: 'unknown', checks_total: 0, checks_passed: 0, reason: 'Complete supported immutable input/config data was unavailable.',
+            benchmark_eligibility: 'unknown', variant: workload?.config.variant ?? null,
+            program_sha256: workload ? CPU_PROGRAM_SHA256[workload.config.variant] : null, checker_sha256: CPU_CHECKER_SHA256,
+            conditions: { host_instance_id: CPU_HOST_INSTANCE_ID, cpu_model: processors[0].model, logical_cpus: processors.length, os_release: release() },
+            workload: workload ? { id: 'cpu_integer_sum/v1', input_sha256: captured.source.files.find(row => row.path === args.input_path).sha256,
+                length: workload.values.length, iterations: workload.config.iterations, warmup: workload.config.warmup, samples: workload.config.samples } : null,
+            measurement: null };
+        if (workload) {
+            const run = await runCPUWorkload(workload, context);
+            receipt.process_outcome = run.outcome;
+            receipt.environment.declared_id = run.executionPolicyId;
+            decision.reason = 'The actual registered process did not produce a complete supported measured result.';
+            decision.benchmark_eligibility = 'ineligible';
+            if (run.outcome === 'passed') {
+                let output;
+                try {
+                    output = JSON.parse(run.output);
+                }
+                catch {
+                    output = null;
+                }
+                const row = output;
+                if (row && typeof row === 'object' && !Array.isArray(row)
+                    && Object.keys(row).length === 8 && row.schema_version === 1 && row.variant === workload.config.variant
+                    && Number.isSafeInteger(row.pid) && Number(row.pid) > 0
+                    && row.node_version === process.version && row.platform === process.platform && row.arch === process.arch
+                    && Array.isArray(row.samples_ms) && row.samples_ms.length === workload.config.samples
+                    && row.samples_ms.every(value => typeof value === 'number' && Number.isFinite(value) && value > 0 && value <= 60000)
+                    && Array.isArray(row.checksums) && row.checksums.length === workload.config.samples
+                    && row.checksums.every(value => typeof value === 'number' && Number.isSafeInteger(value))) {
+                    const expected = integerSumOracle(workload.values) * workload.config.iterations;
+                    receipt.instrumentation = 'production';
+                    const passed = row.checksums.filter(value => value === expected).length;
+                    const samples = row.samples_ms;
+                    decision = { ...decision, outcome: passed === workload.config.samples ? 'passed' : 'failed',
+                        checks_total: workload.config.samples, checks_passed: passed,
+                        benchmark_eligibility: passed === workload.config.samples ? 'eligible' : 'ineligible',
+                        reason: passed === workload.config.samples ? 'Every measured checksum matched the independent integer oracle.' : 'A measured checksum failed the independent integer oracle.',
+                        measurement: { samples_ms: samples, value_ms: [...samples].sort((a, b) => a - b)[Math.floor(samples.length / 2)],
+                            unit: 'ms', timing_domain: 'node_performance_now', scope: 'integer_sum_kernel', rank: 0, world_size: 1 } };
+                }
+            }
+        }
+        receipt.end_source = (await captureVerifierInputs(context, request.source_paths)).source;
+        receipt.source_binding = receipt.source.coverage === 'complete' && receipt.end_source.coverage === 'complete'
+            && receipt.source.source_id === receipt.end_source.source_id ? 'observed_endpoints' : 'unknown';
+        receipt.artifact_refs = receipt.source.files.filter(file => file.kind === 'file').map(file => ({ origin: 'local',
+            path: join(receipt.source.cwd, file.path), sha256: file.sha256 }));
+        if (decision.benchmark_eligibility === 'eligible' && receipt.source_binding !== 'observed_endpoints') {
+            decision.benchmark_eligibility = 'ineligible';
+            decision.reason = 'Inputs/configuration changed or became unavailable during the measured run.';
+        }
+        const admitted = parseBenchmarkVerifierDecision(decision, receipt);
+        if (!admitted || !parseCommandVerificationReceipt(receipt))
+            throw new Error('The CPU adapter produced an invalid bounded decision');
+        context.onVerificationReceipt?.(receipt);
+        if (!context.signal?.aborted)
+            context.onHostVerifier?.(receipt, admitted);
+        return JSON.stringify({ verification: receipt, verifier: admitted });
+    },
+});

package/dist/agent/tools/compare_benchmarks.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const compareBenchmarksTool: Tool;

package/dist/agent/tools/compare_benchmarks.js

@@ -0,0 +1,53 @@
+import { parseBenchmarkVerifierDecision } from '../runtime/benchmark_contract.js';
+import { compareRegisteredBenchmarks, parseBenchmarkComparisonDecision } from '../runtime/benchmark_comparison.js';
+import { ToolCapability } from '../runtime/capabilities.js';
+import { parseCommandVerificationReceipt } from '../runtime/source_verification_contract.js';
+async function observed(id, context) {
+    const row = context.toolResponseStore.evidence.getSnapshot().records.find(record => record.id === id);
+    if (!row || row.kind !== 'observation' || row.partial || row.isError || row.availability === 'unavailable'
+        || row.source.origin !== 'host_receipt' || row.source.toolName !== 'benchmark_cpu' || !row.source.toolCallId)
+        return null;
+    const receipt = parseCommandVerificationReceipt(row.source.verification);
+    const decision = receipt && parseBenchmarkVerifierDecision(row.source.verifier, receipt);
+    if (!receipt || !decision)
+        return null;
+    try {
+        const original = await context.toolResponseStore.getChunk(row.source.toolCallId, { cursor: 0, maxBytes: 32768 });
+        if (!original || original.totalBytes > 65536 || original.observationId !== row.id || original.sha256 !== row.resultSha256)
+            return null;
+        if (!original.complete) {
+            const tail = await context.toolResponseStore.getChunk(row.source.toolCallId, { cursor: original.nextCursor, maxBytes: 32768 });
+            if (!tail || !tail.complete || tail.observationId !== row.id || tail.sha256 !== row.resultSha256)
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return { id: row.id, receipt, decision };
+}
+export const compareBenchmarksTool = Object.freeze({
+    capabilities: Object.freeze([ToolCapability.FILE_READ]), effect: 'read', parallelSafe: true,
+    definition: { name: 'compare_benchmarks',
+        description: 'Compare two retained host-admitted benchmark_cpu observations by their original observation IDs. Require independent measured runs with the same captured input/workload, checker, runner and declared host/runtime/measurement conditions; registered program/source identities may differ. Copied JSON, generic command output, incomplete or unavailable records cannot admit eligibility. Returns only the scoped historical CPU-fixture comparison; a measured delta never proves a causal win, production/GPU performance or a plateau.',
+        parameters: { type: 'object', additionalProperties: false, properties: {
+                observation_ids: { type: 'array', items: { type: 'string' }, minItems: 2, maxItems: 2, uniqueItems: true },
+            }, required: ['observation_ids'] } },
+    execute: async (args, context) => {
+        if (!context)
+            throw new Error('compare_benchmarks requires a host evidence context');
+        const ids = args.observation_ids;
+        if (Object.keys(args).length !== 1 || !Array.isArray(ids) || ids.length !== 2
+            || ids.some(id => typeof id !== 'string' || !id.trim() || Buffer.byteLength(id) > 256 || /[\u0000-\u001f\u007f]/u.test(id))
+            || ids[0] === ids[1])
+            throw new TypeError('compare_benchmarks requires two distinct bounded original observation IDs');
+        const baseline = await observed(ids[0], context);
+        const candidate = await observed(ids[1], context);
+        const decision = parseBenchmarkComparisonDecision(compareRegisteredBenchmarks(baseline, candidate));
+        if (!decision)
+            throw new Error('The host comparator produced an invalid bounded decision');
+        if (!context.signal?.aborted)
+            context.onHostBenchmarkComparison?.(decision);
+        return JSON.stringify(decision);
+    },
+});

package/dist/agent/tools/deferred.js

@@ -14,6 +14,7 @@
 export const CORE_DISCOVERY_TOOL_NAMES = new Set([
     'tool_search',
     'recall_tool_response',
+    'session_evidence',
 ]);
 export const ALWAYS_LOADED_TOOL_NAMES = new Set([
     // Core file + shell + search (analogues of claw-code's shell/read/write/edit/glob/grep)

package/dist/agent/tools/delegate.js

@@ -5,6 +5,7 @@
  * The sub-agent runs in isolation and only returns a summary, keeping the
  * main agent's context clean.
  */
+import { randomUUID } from 'node:crypto';
 import { ToolCapability } from '../runtime/capabilities.js';
 import { getWorkerExecutor } from '../../worker/index.js';
 import { renderPrompt } from '../../utils/template.js';
@@ -24,7 +25,8 @@ export const delegateTaskTool = {
                 max_iterations: {
                     type: 'string',
                     description: 'Maximum iterations for the sub-agent (default: 5, max: 10)'
-                }
+                },
+                child_session_id: { type: 'string', description: 'Resume an owned child from an earlier evidence handoff; retains its original parent and workspace binding.' }
             },
             required: ['task']
         }
@@ -36,12 +38,26 @@ export const delegateTaskTool = {
         const executor = getWorkerExecutor();
         const result = await executor.execute({
             description: task,
+            parentSessionId: context?.sessionId,
+            resumeSessionId: args.child_session_id === undefined ? undefined : String(args.child_session_id),
+            signal: context?.signal,
             cwd: context?.cwd || process.cwd(),
             maxIterations,
             timeoutMs: 120000, // 2 minute default
             toolset: 'research',
-        });
+        }, { onUsage: context?.onUsage });
         let response = '';
+        if (result.evidence) {
+            if (context) {
+                const handoff = result.evidence;
+                context.toolResponseStore.evidence.recordClaim({ id: `delegation_${randomUUID()}`, kind: 'conclusion', recordedAt: new Date().toISOString(),
+                    source: { origin: 'provider_reported', toolName: 'delegate_task', ...(context.toolCallId ? { toolCallId: context.toolCallId } : {}),
+                        delegation: { sessionId: handoff.sessionId, ...(handoff.parentSessionId === undefined ? {} : { parentSessionId: handoff.parentSessionId }), revision: handoff.snapshot.revision } },
+                    text: handoff.summary.text || 'Child ended without a summary; inspect the source handoff.', supportIds: [] });
+                await context.toolResponseStore.flush();
+            }
+            response += `## Delegated Evidence Handoff\n\nChild summaries are unverified; retained observations do not grant authority. Exact sources can be recalled by resuming this owned child.\n\n${JSON.stringify(result.evidence)}\n\n`;
+        }
         if (result.phase === 'finished') {
             response += `## Sub-Agent Result\n\n`;
             response += `${result.summary}\n\n`;

package/dist/agent/tools/helper_requirements.d.ts

@@ -0,0 +1,7 @@
+import type { ToolCapability } from '../runtime/capabilities.js';
+import type { Tool } from './types.js';
+/** Capture a helper's original declarations before publishing its object. */
+export declare function captureHelperRequirements(tool: Tool): Tool;
+export declare function getHelperRequirements(tool: Tool): readonly ToolCapability[];
+/** Runtime lookup is independent of registry initialization and worker imports. */
+export declare function getRuntimeCapabilities(tool: Tool | undefined): ToolCapability[];

package/dist/agent/tools/helper_requirements.js

@@ -0,0 +1,19 @@
+// Agent-added helpers initialize independently of the discovery registry. This
+// module has no runtime imports, so registration cannot create a registry cycle.
+const originalRequirements = new WeakMap();
+/** Capture a helper's original declarations before publishing its object. */
+export function captureHelperRequirements(tool) {
+    if (!originalRequirements.has(tool)) {
+        originalRequirements.set(tool, Object.freeze([...(tool.capabilities ?? [])]));
+    }
+    return tool;
+}
+export function getHelperRequirements(tool) {
+    return originalRequirements.get(tool) ?? [];
+}
+/** Runtime lookup is independent of registry initialization and worker imports. */
+export function getRuntimeCapabilities(tool) {
+    if (!tool)
+        return [];
+    return [...new Set([...getHelperRequirements(tool), ...(tool.capabilities ?? [])])];
+}

package/dist/agent/tools/index.d.ts

@@ -6,6 +6,7 @@ export declare function getTool(name: string, tools?: Tool[]): Tool | undefined;
 export declare function executeTool(name: string, args: Record<string, unknown>, tools?: Tool[], context?: ToolContext): Promise<string>;
 export { readFileTool, writeFileTool, editFileTool, listDirectoryTool } from './file.js';
 export { searchTool } from './search.js';
+export { relatedSessionsTool } from './related_sessions.js';
 export { listSkillsTool, invokeSkillTool } from './skills.js';
 export { runCommandTool } from './shell.js';
 export { zergQueryTool, zergTaskStatusTool, zergListTool } from './zerg.js';

package/dist/agent/tools/index.js

@@ -2,6 +2,7 @@ import { defaultTools as baseDefaultTools } from './registry.js';
 import { sendMessageTool, askZtcPaneTool, contactExternalTool } from './bus_message.js';
 import { toolSearchTool } from './tool_search.js';
 import { recallToolResponseTool } from './recall_tool_response.js';
+import { sessionEvidenceTool } from './session_evidence.js';
 import { proposeWorldMutationTool } from './world_mutation.js';
 import { adaptationRunTool } from './adaptation.js';
 // --- Tool Registry ---
@@ -9,6 +10,7 @@ export const defaultTools = [
     ...baseDefaultTools,
     toolSearchTool,
     recallToolResponseTool,
+    sessionEvidenceTool,
     adaptationRunTool,
 ];
 export function getToolDefinitions(tools = defaultTools) {
@@ -26,6 +28,7 @@ export async function executeTool(name, args, tools = defaultTools, context) {
 }
 export { readFileTool, writeFileTool, editFileTool, listDirectoryTool } from './file.js';
 export { searchTool } from './search.js';
+export { relatedSessionsTool } from './related_sessions.js';
 export { listSkillsTool, invokeSkillTool } from './skills.js';
 export { runCommandTool } from './shell.js';
 export { zergQueryTool, zergTaskStatusTool, zergListTool } from './zerg.js';

package/dist/agent/tools/measurement_report.d.ts

@@ -0,0 +1,22 @@
+import { type MeasurementComparison, type MeasurementCompatibility, type MeasurementCompletion, type MeasurementReason, type MeasurementReport } from '../runtime/measurements.js';
+import type { Tool } from './types.js';
+export interface MeasurementSourceLink {
+    observationId: string;
+    toolCallId: string;
+    resultSha256: string;
+    jobId: string;
+}
+export interface MeasurementToolResult {
+    ok: boolean;
+    verification: 'unknown';
+    benchmarkEligibility: 'unknown';
+    compatibility: MeasurementCompatibility;
+    completion: MeasurementCompletion;
+    execution: 'completed' | 'running' | 'failed' | 'unknown';
+    reports: MeasurementReport[];
+    comparison: MeasurementComparison | null;
+    sources: MeasurementSourceLink[];
+    reasons: MeasurementReason[];
+}
+/** Read an original retained managed receipt before assessing producer measurement JSON. */
+export declare const measurementReportTool: Tool;

package/dist/agent/tools/measurement_report.js

@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto';
+import { assessMeasurements, compareMeasurements, parseMeasurementEnvelope, parseMeasurementRequirements } from '../runtime/measurements.js';
+import { ToolCapability } from '../runtime/capabilities.js';
+import { ToolResponseIntegrityError } from '../tool_response_store.js';
+const observationIdsSchema = { type: 'array', description: 'One retained observation, or baseline then candidate observations.',
+    items: { type: 'string' }, minItems: 1, maxItems: 2, uniqueItems: true };
+const measurementParameters = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        observation_ids: observationIdsSchema,
+        requirements: { type: 'object', description: 'Expected workload, instrumentation, selected metrics, units, timing domain, scope, ranks and smoke fields.' },
+    },
+    required: ['observation_ids', 'requirements'],
+};
+const SOURCE_BYTES = 32768;
+const REPORT_BYTES = 65536;
+const managedTools = new Set(['run_command', 'read_command']);
+const statuses = new Set(['running', 'completed', 'failed', 'cancelled', 'timed_out', 'interrupted']);
+const reason = (code, message) => ({ code, message });
+function unknown(reasons, sources = [], execution = 'unknown') {
+    return { ok: false, verification: 'unknown', benchmarkEligibility: 'unknown', compatibility: 'unknown',
+        completion: execution === 'running' ? 'incomplete' : 'unknown', execution, reports: [], comparison: null, sources, reasons };
+}
+function prefix(text, maxBytes) {
+    let kept = '';
+    let size = 0;
+    for (const character of text) {
+        const bytes = Buffer.byteLength(character);
+        if (size + bytes > maxBytes)
+            break;
+        kept += character;
+        size += bytes;
+    }
+    return kept;
+}
+function serialize(result) {
+    const bounded = (rows) => rows.slice(0, 32).map(row => ({ code: prefix(row.code, 128), message: prefix(row.message, 512) }));
+    result.reasons = bounded(result.reasons);
+    for (const report of result.reports)
+        report.reasons = bounded(report.reasons);
+    if (result.comparison) {
+        result.comparison.reasons = bounded(result.comparison.reasons);
+        result.comparison.baseline.reasons = bounded(result.comparison.baseline.reasons);
+        result.comparison.candidate.reasons = bounded(result.comparison.candidate.reasons);
+    }
+    const output = JSON.stringify(result);
+    return Buffer.byteLength(output) <= REPORT_BYTES ? output : JSON.stringify(unknown([
+        reason('report_too_large', 'The aggregate measurement report exceeds65536 UTF8 bytes; narrow the selected metrics.'),
+    ], result.sources));
+}
+function validReceipt(value, observation, context) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const row = value;
+    const job = observation.source.job;
+    if (!job || (context.sessionId !== undefined && job.sessionId !== context.sessionId)
+        || typeof row.job_id !== 'string' || row.job_id !== job.jobId || typeof row.status !== 'string' || !statuses.has(row.status) || row.status !== job.status
+        || typeof row.cwd !== 'string' || typeof row.command !== 'string' || typeof row.log_path !== 'string'
+        || (observation.source.cwd !== undefined && row.cwd !== observation.source.cwd)
+        || (observation.source.artifact !== undefined && row.log_path !== observation.source.artifact.path)
+        || typeof row.started_at !== 'string' || !Number.isFinite(Date.parse(row.started_at)) || row.started_at !== job.startedAt
+        || row.ended_at !== job.endedAt || (row.exit_code ?? null) !== job.exitCode
+        || (row.exit_code !== undefined && !Number.isSafeInteger(row.exit_code))
+        || typeof row.output !== 'string' || !Number.isSafeInteger(row.cursor) || row.cursor < Buffer.byteLength(row.output)
+        || row.cursor !== job.cursor || typeof row.has_more !== 'boolean' || row.has_more !== job.hasMore
+        || (row.output_truncated !== undefined && typeof row.output_truncated !== 'boolean')
+        || Boolean(row.output_truncated) !== job.outputTruncated)
+        return false;
+    if (row.status === 'running')
+        return row.ended_at === undefined && row.exit_code === undefined;
+    return typeof row.ended_at === 'string' && Number.isFinite(Date.parse(row.ended_at))
+        && Date.parse(row.ended_at) >= Date.parse(row.started_at) && Number.isSafeInteger(row.exit_code);
+}
+async function capture(id, context) {
+    const store = context.toolResponseStore;
+    const row = store.evidence.getSnapshot().records.find(record => record.id === id);
+    if (row?.kind !== 'observation')
+        return { error: reason('missing_observation', 'The requested retained observation is unavailable or is an interpretation.') };
+    if (row.source.origin !== 'host_receipt' || !managedTools.has(row.source.toolName ?? '') || !row.source.job
+        || !row.source.toolCallId || !/^[A-Za-z0-9_-]{1,256}$/.test(row.source.toolCallId)) {
+        return { error: reason('untrusted_source', 'Measurement assessment requires original host receipt provenance from a managed command.') };
+    }
+    if (row.partial || row.availability === 'unavailable')
+        return { error: reason('source_incomplete', 'The original source is partial or unavailable.') };
+    if (row.resultBytes > SOURCE_BYTES)
+        return { error: reason('source_too_large', 'The original receipt exceeds the32768 byte complete source retrieval limit.') };
+    let chunk;
+    try {
+        chunk = await store.getChunk(row.source.toolCallId, { cursor: 0, maxBytes: SOURCE_BYTES });
+    }
+    catch (error) {
+        if (!(error instanceof ToolResponseIntegrityError))
+            throw error;
+        return { error: reason('source_integrity', 'The original retained source failed its identity or SHA256 integrity check.') };
+    }
+    if (!chunk || !chunk.complete || chunk.availability === 'unavailable')
+        return { error: reason('source_incomplete', 'A complete original retained receipt is unavailable.') };
+    const meta = store.getMeta(row.source.toolCallId);
+    if (chunk.toolUseId !== row.source.toolCallId || chunk.observationId !== row.id || chunk.cursor !== 0
+        || chunk.totalBytes !== row.resultBytes || chunk.nextCursor !== chunk.totalBytes || chunk.sha256 !== row.resultSha256
+        || createHash('sha256').update(chunk.content).digest('hex') !== row.resultSha256
+        || meta?.observation_id !== row.id || meta.tool_name !== row.source.toolName) {
+        return { error: reason('source_integrity', 'The retrieved source identity, byte count or SHA256 digest disagrees with its retained observation.') };
+    }
+    let receipt;
+    try {
+        receipt = JSON.parse(chunk.content);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return { error: reason('invalid_receipt', 'The original managed receipt must be an entire JSON document.') };
+    }
+    if (!validReceipt(receipt, row, context))
+        return { error: reason('receipt_mismatch', 'The original receipt does not match its retained job identity or lifecycle fields.') };
+    const captured = { link: { observationId: row.id, toolCallId: row.source.toolCallId,
+            resultSha256: row.resultSha256, jobId: receipt.job_id }, sessionId: row.source.job.sessionId, receipt };
+    if (receipt.cursor !== Buffer.byteLength(receipt.output) || receipt.has_more || receipt.output_truncated) {
+        return { ...captured, error: reason('source_incomplete', 'The managed receipt does not contain complete command output from byte0, or its output is truncated.') };
+    }
+    if (receipt.status !== 'completed' || receipt.exit_code !== 0)
+        return captured;
+    if (row.isError)
+        return { ...captured, error: reason('source_error', 'The original captured source is marked as an execution error.') };
+    let output;
+    try {
+        output = JSON.parse(receipt.output);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return { ...captured, error: reason('invalid_output', 'Measurement output must be an entire JSON document; surrounding prose is not removed.') };
+    }
+    const envelope = parseMeasurementEnvelope(output);
+    return envelope ? { ...captured, envelope }
+        : { ...captured, error: reason('invalid_output', 'The original JSON document is not a supported bounded measurement envelope.') };
+}
+/** Read an original retained managed receipt before assessing producer measurement JSON. */
+export const measurementReportTool = {
+    capabilities: [ToolCapability.FILE_READ],
+    effect: 'read',
+    parallelSafe: true,
+    definition: {
+        name: 'measurement_report',
+        description: 'Assess or compare structured measurements from one or two retained managed-command observations. Supply observation IDs and measurement requirements, never copied values or receipts. Compatibility does not establish verification or benchmark eligibility.',
+        parameters: measurementParameters,
+    },
+    execute: async (args, context) => {
+        const unsupported = Object.keys(args).find(key => key !== 'observation_ids' && key !== 'requirements');
+        if (unsupported)
+            throw new TypeError(`measurement_report: unsupported argument ${unsupported}`);
+        const ids = args.observation_ids;
+        if (!Array.isArray(ids) || ids.length < 1 || ids.length > 2 || ids.some(id => typeof id !== 'string' || !id.trim()
+            || Buffer.byteLength(id) > 256 || /[\u0000-\u001f\u007f]/u.test(id)) || new Set(ids).size !== ids.length) {
+            throw new TypeError('measurement_report: observation_ids must contain one or two unique bounded nonempty observation IDs');
+        }
+        const required = parseMeasurementRequirements(args.requirements);
+        if (!required)
+            throw new TypeError('measurement_report: requirements must match the supported bounded measurement schema');
+        if (!context)
+            throw new Error('measurement_report: store unavailable');
+        const captures = [];
+        for (const id of ids)
+            captures.push(await capture(id, context));
+        const sources = captures.flatMap(item => item.link ? [item.link] : []);
+        const errors = captures.flatMap(item => item.error ? [item.error] : []);
+        if (errors.length)
+            return serialize(unknown(errors, sources));
+        if (captures.length === 2 && captures[0].sessionId === captures[1].sessionId
+            && captures[0].receipt.job_id === captures[1].receipt.job_id) {
+            return serialize(unknown([reason('alias_source', 'Two observations of the same canonical managed job are not independent comparison runs.')], sources));
+        }
+        if (captures.some(item => item.receipt.status !== 'completed' && item.receipt.status !== 'running'
+            || (item.receipt.exit_code !== undefined && item.receipt.exit_code !== 0))) {
+            return serialize(unknown([reason('execution_failed', 'The original managed process did not complete successfully; measurement admission is unavailable.')], sources, 'failed'));
+        }
+        if (captures.some(item => item.receipt.status === 'running')) {
+            return serialize(unknown([reason('execution_running', 'The original managed job is still running; a passed-false progress report is incomplete.')], sources, 'running'));
+        }
+        const comparison = captures.length === 2 ? compareMeasurements(captures[0].envelope, captures[1].envelope, required) : null;
+        const reports = comparison ? [comparison.baseline, comparison.candidate] : [assessMeasurements(captures[0].envelope, required)];
+        const completion = reports.some(report => report.completion === 'reported_fail') ? 'reported_fail'
+            : reports.some(report => report.completion === 'incomplete') ? 'incomplete'
+                : reports.every(report => report.completion === 'reported_pass') ? 'reported_pass' : 'unknown';
+        return serialize({ ok: true, verification: 'unknown', benchmarkEligibility: 'unknown', execution: 'completed', completion,
+            compatibility: comparison?.compatibility ?? reports[0].compatibility, reports, comparison, sources,
+            reasons: comparison?.reasons ?? reports[0].reasons });
+    },
+};