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

package/dist/emulation/tool_adapters.js

@@ -1,6 +1,7 @@
 import { ToolCapability } from '../agent/runtime/capabilities.js';
 import { applyExactReplace, resolvePath, updateFileAtomic } from '../agent/tools/file.js';
 import { buildSimpleDiffMeta } from '../utils/diff.js';
+import { runCommandTool } from '../agent/tools/shell.js';
 const CLAUDE_PROFILE_IDS = new Set(['claude-code']);
 const CODEX_PROFILE_IDS = new Set(['codex-cli', 'codex-cli-system']);
 export function buildEmulationCompatibilityTools(emulationId, tools) {
@@ -14,7 +15,10 @@ export function buildEmulationCompatibilityTools(emulationId, tools) {
             return;
         }
         existing.add(tool.definition.name);
-        adapters.push({ ...tool, parallelSafe: ['Read', 'Grep', 'LS'].includes(tool.definition.name) });
+        const commandAdapter = ['Bash', 'Glob', 'WebFetch', 'exec_command', 'shell_command'].includes(tool.definition.name)
+            && tools.find(candidate => candidate.definition.name === 'run_command') === runCommandTool;
+        adapters.push({ ...tool, parallelSafe: ['Read', 'Grep', 'LS'].includes(tool.definition.name),
+            ...(commandAdapter ? { outputSource: runCommandTool } : {}) });
     };
     const factories = [];
     if (CLAUDE_PROFILE_IDS.has(emulationId)) {
@@ -63,20 +67,23 @@ function makeClaudeAdapters(tools) {
     return [
         {
             capabilities: [ToolCapability.SHELL_EXEC, ToolCapability.FILE_WRITE],
+            resolveExecutionCwd: (args, context) => resolveClaudeBashCwd(tools, args, context),
             definition: {
                 name: 'Bash',
-                description: 'Run a shell command in the current working directory. Use for builds, tests, git, and other terminal operations; prefer Read, Edit, Write, Glob, and Grep for file operations when available. Quote paths containing spaces. Use cd with && when a command needs another directory; do not assume shell state persists between calls. timeout is optional, in milliseconds, up to 600000. Commands run synchronously; run_in_background is not supported by this adapter. Batch independent commands when useful, but sequence dependent commands so a failure stops later steps. Inspect exit errors and verify actual results before claiming success. Follow the user\'s authorization for commits, pushes, deletion, and other external or destructive actions.',
-                parameters: objectParams({
-                    command: 'Shell command to run',
-                    description: 'Short description of the command',
-                    timeout: 'Optional timeout in milliseconds (maximum 600000)',
-                }, ['command']),
+                description: 'Run a shell command in the host working directory or an optional cwd (workdir alias). A nonempty cwd takes precedence. Use for builds, tests, git, and other terminal operations; prefer Read, Edit, Write, Glob, and Grep for file operations when available. Quote paths containing spaces. Use cwd for a structured directory change; shell cd with && remains available. Do not assume shell state persists between calls. timeout is optional, in milliseconds, up to 600000. Commands run synchronously; run_in_background is not supported by this adapter. Batch independent commands when useful, but sequence dependent commands so a failure stops later steps. Inspect exit errors and verify actual results before claiming success. Follow the user\'s authorization for commits, pushes, deletion, and other external or destructive actions.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        command: { type: 'string', description: 'Shell command to run' },
+                        description: { type: 'string', description: 'Short description of the command' },
+                        timeout: { type: 'integer', minimum: 1, maximum: 600000, description: 'Optional timeout in milliseconds (maximum 600000)' },
+                        cwd: { type: 'string', description: 'Optional working directory, resolved relative to the host context. Takes precedence over workdir.' },
+                        workdir: { type: 'string', description: 'Optional working directory alias used when cwd is absent or empty.' },
+                    },
+                    required: ['command'],
+                },
             },
-            execute: (args, context) => callTool(tools, 'run_command', {
-                command: requiredString(args, ['command']),
-                cwd: optionalString(args, ['cwd', 'workdir']),
-                ...(args.timeout === undefined ? {} : { timeout: args.timeout }),
-            }, context),
+            execute: (args, context) => callTool(tools, 'run_command', claudeBashInvocation(args), context),
         },
         {
             capabilities: [ToolCapability.FILE_READ],
@@ -244,6 +251,7 @@ function makeCodexAdapters(tools) {
                     yield_time_ms: 'Ignored compatibility hint',
                 }, []),
             },
+            resolveExecutionCwd: (args, context) => resolveCodexShellCwd(tools, args, context),
             execute: (args, context) => executeCodexShell(tools, args, context),
         },
         {
@@ -256,6 +264,7 @@ function makeCodexAdapters(tools) {
                     cwd: 'Working directory',
                 }, ['command']),
             },
+            resolveExecutionCwd: (args, context) => resolveCodexShellCwd(tools, args, context),
             execute: (args, context) => executeCodexShell(tools, args, context),
         },
         {
@@ -291,18 +300,39 @@ async function callTool(tools, name, args, context) {
         throw new Error(output);
     return output;
 }
+function claudeBashInvocation(args) {
+    return {
+        command: requiredString(args, ['command']),
+        cwd: optionalString(args, ['cwd', 'workdir']),
+        ...(args.timeout === undefined ? {} : { timeout: args.timeout }),
+    };
+}
+function resolveClaudeBashCwd(tools, args, context) {
+    const call = claudeBashInvocation(args);
+    const target = tools.find(tool => tool.definition.name === 'run_command');
+    return target?.resolveExecutionCwd?.(call, context) ?? (context?.cwd || process.cwd());
+}
 async function executeCodexShell(tools, args, context) {
+    const call = codexShellInvocation(args);
+    return callTool(tools, call.name, call.args, context);
+}
+function resolveCodexShellCwd(tools, args, context) {
+    const call = codexShellInvocation(args);
+    const target = tools.find(tool => tool.definition.name === call.name);
+    return target?.resolveExecutionCwd?.(call.args, context) ?? (context?.cwd || process.cwd());
+}
+function codexShellInvocation(args) {
     const command = requiredString(args, ['cmd', 'command']);
     const patch = extractApplyPatchPayload(command);
     if (patch) {
-        return callTool(tools, 'apply_patch', { patch }, context);
+        return { name: 'apply_patch', args: { patch } };
     }
     const timeout = args.timeout_ms === undefined ? args.timeout : args.timeout_ms;
-    return callTool(tools, 'run_command', {
-        command,
-        cwd: optionalString(args, ['workdir', 'cwd']),
-        ...(timeout === undefined ? {} : { timeout }),
-    }, context);
+    return { name: 'run_command', args: {
+            command,
+            cwd: optionalString(args, ['workdir', 'cwd']),
+            ...(timeout === undefined ? {} : { timeout }),
+        } };
 }
 function extractApplyPatchPayload(command) {
     const start = command.indexOf('*** Begin Patch');

package/dist/emulation/ztc_addendum.d.ts

@@ -6,6 +6,7 @@
  */
 export interface ZtcAddendumOptions {
     askUserAvailable?: boolean;
+    /** @deprecated The checklist is retired; retained for caller compatibility. */
     todoWriteAvailable?: boolean;
     ztcCommandAvailable?: boolean;
     workflowAvailable?: boolean;

package/dist/emulation/ztc_addendum.js

@@ -45,6 +45,12 @@ const LANGUAGE_SECTION = `
 
 Write every user-visible response in the same language as the user's latest prompt, unless the user explicitly asks for a different language. An English prompt gets an English answer; a Spanish prompt gets Spanish. Do not switch languages on your own, even when code, tool output, or earlier context is written in another language.
 `.trim();
+const FORMAT_SECTION = `
+## Response Formatting
+
+Explicit user formats take precedence over these defaults, including JSON-only output and an exact answer.
+For comparisons of three or more items, use a Markdown table. Use bullets for steps or findings, and bold the key decision or recommendation.
+`.trim();
 const WORKFLOW_SECTION = `
 ## Workflow Orchestration
 
@@ -59,38 +65,34 @@ function buildToolEfficiencySection(options) {
     if (options.askUserAvailable) {
         lines.push('If you need to ask the user something, call `ask_user` directly.');
     }
-    if (options.todoWriteAvailable) {
-        lines.push('Use `todo_write` only for multi-step tasks, and pair it with real action tools in the same turn when work can proceed.', 'Do not use `todo_write` for single-step tasks, greetings, or clarification-only turns.');
-    }
     return lines.join('\n');
 }
-const TODO_COMPLETION_SECTION = `
-## Todo Completion Rule
-
-If you create a todo list with \`todo_write\`, keep it current and mark every task completed before saying the work is done.
-`.trim();
 // R3/F6: "done" was asserted, never demonstrated. State, before the model claims
 // completion, what counts as evidence per task class — inline, not a vague nudge.
 const VERIFICATION_SECTION = `
 ## Verify Before Done
 
 Before reporting work complete, produce verification evidence — a prose claim that it works is not enough:
-- code change: run the narrowest test or build that exercises it, or show a diff of the edited region (e.g. \`git diff <files>\`)
+- code change: a diff demonstrates an edit only; report diff-only work as edited and unverified. Run the narrowest relevant test or build and identify what it actually covers.
 - web feature: a browser action or a screenshot of the working result
 - orchestration: the structured verdict returned by \`ask_ztc_pane\` (never a hand-authored "passed")
 - shell task: the command output proving the requested state
 
-If no test or build harness exists, fall back to a diff plus a targeted re-read of the changed code, and say no test harness was available.
+Keep edited, compiled, tested, benchmarked and qualified outcomes separate. Identify the source snapshot, command, environment/build identity, stated scope and actual process outcome for each result. A build result does not establish behavioral correctness, and an earlier result cannot qualify later edits. Retain stale results as historical evidence for their original source.
+
+Diagnostic timing is diagnostic evidence, not a clean benchmark. A component check cannot establish full-model qualification. A declared purpose or successful shell exit alone does not admit source or semantic verification; report unknown or unverified where a trusted verifier has not supplied it.
+
+If no test or build harness exists, show a diff plus a targeted re-read, and explicitly report the work as edited/unverified with no behavioral verification available.
 `.trim();
 export function buildZtcAddendum(options = {}) {
     return [
         LANGUAGE_SECTION,
+        FORMAT_SECTION,
         options.ztcCommandAvailable === false ? undefined : ZTC_COMMAND_SECTION,
         options.askUserAvailable ? ASK_USER_SECTION : undefined,
         ACTION_SECTION,
         options.workflowAvailable && options.workflowGuidanceAvailable !== false ? WORKFLOW_SECTION : undefined,
         buildToolEfficiencySection(options),
-        options.todoWriteAvailable ? TODO_COMPLETION_SECTION : undefined,
         options.verificationAvailable === false ? undefined : VERIFICATION_SECTION,
     ]
         .filter(Boolean)
@@ -98,6 +100,5 @@ export function buildZtcAddendum(options = {}) {
 }
 export const ZTC_ADDENDUM = buildZtcAddendum({
     askUserAvailable: true,
-    todoWriteAvailable: true,
     ztcCommandAvailable: true,
 });

package/dist/environment/service_runner.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/environment/service_runner.js

@@ -0,0 +1,68 @@
+import { readFile, appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeFileAtomic } from '../utils/atomic_write.js';
+import { runShellCommand } from '../utils/shell.js';
+import { ToolCapability } from '../agent/runtime/capabilities.js';
+// Detached supervisor; only this launch's UUID stop file controls its shell.
+const directory = process.argv[2];
+const launch = JSON.parse(await readFile(join(directory, 'launch.json'), 'utf8'));
+const receipt = launch.service;
+const controller = new AbortController();
+let finished = false;
+let written = 0;
+let outputWrites = Promise.resolve();
+const save = async () => {
+    receipt.heartbeat = new Date().toISOString();
+    await writeFileAtomic(join(directory, 'receipt.json'), JSON.stringify(receipt));
+};
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
+    process.on(signal, () => controller.abort());
+}
+receipt.status = 'running';
+await save();
+const running = runShellCommand(receipt.command, launch.cwd, controller.signal, undefined, {
+    ...launch.shell, capabilities: [ToolCapability.SHELL_EXEC], noTimeout: true,
+    onOutput: (_stream, text) => {
+        const bytes = Buffer.from(text);
+        const count = Math.min(bytes.length, Math.max(0, 16 * 1024 * 1024 - written));
+        written += count;
+        if (count < bytes.length)
+            receipt.outputTruncated = true;
+        if (count)
+            outputWrites = outputWrites.then(() => appendFile(join(directory, 'output.log'), bytes.subarray(0, count), { mode: 0o600 })).catch(error => {
+                receipt.failure = `Service output could not be saved: ${String(error)}`;
+                controller.abort();
+            });
+    },
+}).then(result => {
+    receipt.exitCode = result.exitCode;
+    receipt.status = controller.signal.aborted ? 'stopped' : result.exitCode === 0 ? 'stopped' : 'failed';
+}, error => {
+    receipt.status = controller.signal.aborted ? 'stopped' : 'failed';
+    receipt.exitCode = 1;
+    if (!controller.signal.aborted)
+        receipt.failure = String(error);
+}).finally(() => { finished = true; receipt.endedAt = new Date().toISOString(); });
+try {
+    while (!finished) {
+        try {
+            if (await readFile(join(directory, 'stop'), 'utf8') === receipt.id)
+                controller.abort();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await save();
+        await new Promise(resolve => setTimeout(resolve, 250));
+    }
+}
+catch (error) {
+    receipt.failure = `Service supervision failed: ${String(error)}`;
+    controller.abort();
+}
+await running;
+await outputWrites;
+if (receipt.failure)
+    receipt.status = 'failed';
+await save();

package/dist/environment/store.d.ts

@@ -0,0 +1,120 @@
+import type { RunShellCommandOptions } from '../utils/shell.js';
+export interface EnvironmentFile {
+    path: string;
+    kind: 'file' | 'symlink' | 'directory';
+    sha256: string;
+    bytes: number;
+    mode: number;
+    target?: string;
+}
+export interface EnvironmentCheckpoint {
+    id: string;
+    label: string;
+    createdAt: string;
+    files: EnvironmentFile[];
+    services: Array<{
+        name: string;
+        command: string;
+        cwd?: string;
+    }>;
+}
+export interface EnvironmentService {
+    id: string;
+    name: string;
+    command: string;
+    cwd?: string;
+    status: 'starting' | 'running' | 'stopped' | 'failed' | 'recovery_required';
+    startedAt: string;
+    endedAt?: string;
+    exitCode?: number;
+    heartbeat?: string;
+    failure?: string;
+    outputTruncated?: boolean;
+    logPath: string;
+}
+export interface EnvironmentRecord {
+    schemaVersion: 1;
+    id: string;
+    name: string;
+    backend: 'local';
+    workspacePath: string;
+    credentialProfile: string;
+    status: 'active' | 'paused';
+    createdAt: string;
+    updatedAt: string;
+    owner?: {
+        sessionId: string;
+        pid: number;
+        token: string;
+    };
+    checkpoints: EnvironmentCheckpoint[];
+    services: EnvironmentService[];
+    setupNotes: Array<{
+        text: string;
+        createdAt: string;
+    }>;
+    recovery?: {
+        checkpointId: string;
+        restoredAt: string;
+        retainedFiles: number;
+        servicesNeedingRestart: string[];
+        externalLinks: string[];
+    };
+}
+export declare function getEnvironment(name: string): Promise<EnvironmentRecord>;
+export declare function listEnvironments(): Promise<EnvironmentRecord[]>;
+export declare function createEnvironment(name: string, sessionId: string): Promise<EnvironmentRecord>;
+export declare function openEnvironment(name: string, sessionId: string): Promise<EnvironmentRecord>;
+export declare function releaseEnvironment(name: string, sessionId: string): Promise<void>;
+export declare function checkpointEnvironment(name: string, sessionId: string, label: string): Promise<EnvironmentCheckpoint>;
+export declare function restoreEnvironment(name: string, sessionId: string, checkpointId: string): Promise<EnvironmentRecord>;
+export declare function addEnvironmentNote(name: string, sessionId: string, text: string): Promise<void>;
+export declare function startEnvironmentService(name: string, sessionId: string, serviceName: string, command: string, shell: RunShellCommandOptions, workingDirectory?: string): Promise<EnvironmentService>;
+export declare function pauseEnvironment(name: string, sessionId: string): Promise<EnvironmentRecord>;
+export declare function resumeEnvironment(name: string, sessionId: string): Promise<EnvironmentRecord>;
+export declare function discardEnvironment(name: string, sessionId: string): Promise<string>;
+export declare function environmentForWorkspace(cwd: string): Promise<EnvironmentRecord | undefined>;
+/** Bounded setup context, without keys, owner tokens or service launch commands. */
+export declare function describeEnvironmentForAgent(record: EnvironmentRecord): string;
+/** Observable status excludes potentially huge per-file inventories and owner tokens. */
+export declare function environmentSummary(record: EnvironmentRecord): {
+    owner: {
+        sessionId: string;
+        pid: number;
+    } | undefined;
+    checkpointCount: number;
+    checkpoints: {
+        id: string;
+        label: string;
+        createdAt: string;
+        retainedFiles: number;
+        services: string[];
+    }[];
+    serviceCount: number;
+    services: EnvironmentService[];
+    setupNoteCount: number;
+    setupNotes: {
+        text: string;
+        createdAt: string;
+    }[];
+    schemaVersion: 1;
+    id: string;
+    name: string;
+    backend: "local";
+    workspacePath: string;
+    credentialProfile: string;
+    status: "active" | "paused";
+    createdAt: string;
+    updatedAt: string;
+    recovery?: {
+        checkpointId: string;
+        restoredAt: string;
+        retainedFiles: number;
+        servicesNeedingRestart: string[];
+        externalLinks: string[];
+    };
+};
+export declare function isEnvironmentWorkspacePath(workspace: string, path: string): boolean;
+/** A saved environment could not be attached without violating recovery guards. */
+export declare class EnvironmentRecoveryError extends Error {
+}