@zergai/ztc 0.5.0-beta.1 → 0.5.1-dev.202611021234

package/README.md

@@ -35,9 +35,9 @@ See the [public Quickstart](https://zergai.com/docs/ztc) for install,
 authentication, your first plan, named sessions, platform support, and licensing.
 
 ```bash
-# Check the published version and install the public CLI
-npm view @zergai/ztc version
-npm install -g @zergai/ztc
+# Check the published beta and install the public CLI
+npm view @zergai/ztc@next version
+npm install -g @zergai/ztc@next
 ztc --version
 
 # Start with a read-only inspection of a real project
@@ -50,16 +50,24 @@ the source version used during development. Use `ztc --version` to identify your
 installed release. For reproducible installs, use `@zergai/ztc@<version>` with the
 version you selected.
 
-On first launch, choose one authentication route in the welcome message. Then
-describe the project outcome you want. Review the plan and run `/execute` when
-you are ready for ZTC to make the proposed changes.
+At launch, until you log in with ZergAI or choose local API keys that reach a
+model, ZTC asks how to reach a model: **Log in with ZergAI (recommended)** or
+**Use your local API keys**. The question needs an answer: typing or Esc only
+reminds you to choose one, and Ctrl+C quits. Choosing ZergAI opens your browser
+to log in. A first login starts on DeepSeek V4.1 Flash on Fireworks; pick any
+other Zerg Router model with `/model zergrouter <provider> <model>`. `/connect`
+asks again any time. Then describe the project outcome you want. Review the
+plan and run `/execute` when you are ready for ZTC to make the proposed changes.
 
 Authentication options are Zerg Router browser login (`/auth login`), a provider API key
-(`/config key <provider> <api-key>`), or Claude Code OAuth (`claude setup-token`, then
-`/model claude_code`).
+(`/config key <provider>`, which takes the key in a hidden prompt or the name of the
+environment variable that holds it), or Claude Code OAuth (`claude setup-token`, then
+`/model claude_code`). A variable you name is used once it is set; until then ZTC keeps
+using the saved key or the provider's standard variable.
 
 For browser login at **zergrouter.com**, run `ztc auth login` in your shell or
-`/auth login` inside ZTC. Both use the same flow and credentials. See
+`/auth login` inside ZTC. Both use the same flow and credentials. `/auth cancel`
+(or Esc) stops a login still waiting for approval; in the shell, Ctrl+C does. See
 [Zerg Router and DeepSeek setup](docs/zerg-router.md) for model selection,
 Claude Code/Codex emulation, and `ztc "prompt"` or `ztc -p "prompt"` usage.
 
@@ -151,57 +159,65 @@ beta does not claim an interactive native payload for them.
 
 ### ZTC Desktop
 
-On Apple Silicon macOS, launch the native desktop surface explicitly:
+On Apple Silicon macOS, ZTC also ships as a native desktop app, `ztc.app`,
+from [zergai.com/ztc](https://zergai.com/ztc) or the installer:
+
+```bash
+curl -fsSL https://zergai.com/install/ztc.sh | sh -s -- --preview
+```
+
+The app carries its own Node and matching ZTC agent, so it starts from the
+icon without a global Node or ZTC install, and it uses the same accounts,
+configuration and saved sessions as the CLI. Its title bar names the project
+and branch, and holds the model (click it to choose another), the queue, Stop
+and Updates. Releases are signed, notarized and published in
+[`Epoch-ML/ztc-releases`](https://github.com/Epoch-ML/ztc-releases).
+
+From a terminal you can also open the desktop surface explicitly:
 
 ```bash
 ztc --desktop --cwd /path/to/project
 ```
 
-`npm install` installs the CLI; it does not automatically create an application
-bundle. The package includes an optional launcher installer. To create
-`ZTC Desktop.app`, run it explicitly after installing the scoped package:
+An npm-installed `ztc --desktop` uses a legacy `/Applications/ZTerm.app` (or
+`~/Applications/ZTerm.app`) when one is installed, and otherwise the renderer
+packaged with the CLI. `npm install` does not create an application bundle;
+the package includes an optional launcher installer:
 
 ```bash
 node "$(npm root -g)/@zergai/ztc/scripts/install-macos-app.mjs"
 ```
 
-The installer uses `/Applications` when writable, otherwise `~/Applications`.
-`ZTC_DESKTOP_APP_DIR=/path` selects another directory and `ZTC_SKIP_DESKTOP_APP=1`
-skips this optional installer. These variables do not change the npm CLI install.
-Opening the launcher starts `ztc --desktop --cwd "$HOME"`.
-
-The native desktop distribution currently uses `ZTerm.app` and its existing
-signed preview/stable channels. An unbundled `ztc --desktop` launch prefers a
-compatible installed renderer in `/Applications` or `~/Applications` over the
-packaged development binary.
-
-The bundled ZTC app implementation includes its own Node and matching agent.
-It starts from the app icon without a global Node or ZTC installation and uses
-the CLI's existing accounts, configuration and session stores. Its visible name
-and Finder icon are ZTC; `ZTerm.app`, the bundle identifier and channel trust
-remain compatible with the existing distribution. Signed bundled publication
-and the installed-user upgrade matrix remain pending; older published apps
-retain their renderer-only behavior.
-
-From a bundled app session, type `/desktop install-cli` to install an optional
-`ztc` command in `~/.local/bin`, or `/desktop install-cli /path/to/bin` to choose
-another directory. Installation preserves foreign commands and does not edit
-PATH or shell configuration. The command runs that app's agent with the same
-arguments, working directory and profile/config/session selection as the CLI.
-If the app moves, the command reports how to reinstall it. An agent cannot
-request installation on the user's behalf.
-
-The native Updates window saves **Check for updates on startup**, enabled by
-default. Downloads and installation require explicit actions. Bundled sessions
-use this app update path instead of npm updates. A successful update starts its
-helper only after a forced session save, then resumes the owning ZTC session
-with a fresh renderer socket. See [desktop release details](packages/zterm/RELEASES.md)
-for the current source implementation and publication gates.
+It creates `ZTC Desktop.app` in `/Applications` when writable, otherwise
+`~/Applications`; `ZTC_DESKTOP_APP_DIR=/path` selects another directory and
+`ZTC_SKIP_DESKTOP_APP=1` skips it. Opening the launcher runs
+`ztc --desktop --cwd "$HOME"` through the package's own launcher.
+
+From a desktop session, type `/desktop install-cli` to install an optional
+`ztc` command in `~/.local/bin` (or `/desktop install-cli /path/to/bin`). It
+preserves foreign commands, does not edit PATH or shell configuration, and runs
+that app's agent with the same arguments, directory and profile/config/session
+selection as the CLI. If the app moves, the command says how to reinstall it.
+
+**Updates are automatic.** The app checks its signed release feed at startup
+and every 6 hours, downloads and verifies a newer release in the background,
+and installs it when you quit ZTC; it never restarts while you work. Turning
+off **Update ZTC automatically** in the Updates window restores manual
+download and installation. Inside the app, `/update` explains this instead of
+running npm. See [desktop release details](packages/zterm/RELEASES.md) for the
+trust, packaging and publication contract.
 
 ### Voice & Media
 - **Voice dictation** — native Whisper transcription (Ctrl+R)
 - **TTS synthesis** — multiple backends (macOS say, Parler, OpenAI, ElevenLabs)
 - **Image support** — paste from clipboard (Ctrl+I), screenshot compression
+- **Images in the transcript** — pasted images, image files the agent reads and
+  tool screenshots appear under their message. Ghostty and Kitty show the image
+  itself, sent once with the Kitty graphics protocol and placed with its Unicode
+  placeholders, so it scrolls into history like text, in zmux or without it.
+  Other terminals, tmux, ZTC child panes and ZTC Desktop show a 24-bit
+  half-block preview.
+  `ZTC_IMAGE_PROTOCOL=kitty` or `=blocks` overrides the detection.
 
 ---
 
@@ -805,7 +821,8 @@ preserve operation tombstones and call linkage before archiving evidence.
 | Command | Description |
 |---------|-------------|
 | `/config show` | View configuration |
-| `/config key <key>` | Set API key |
+| `/config key [provider]` | Add a provider API key in a hidden prompt, or name the variable that holds it; without a provider, pick one first |
+| `/config key <provider> --remove` | Forget the saved key, or stop reading the variable named for it; for `openai_compatible`, both, keeping the endpoint's URL and model |
 | `/config model <name>` | Set model |
 | `/config statusline [show|on|off|reset]` | Inspect or toggle the bottom status line |
 | `/config statusline <left|right> <field,...>` | Set status line fields without opening the editor |
@@ -940,6 +957,7 @@ Optional App Server config:
 |---------|-------------|
 | `/clear` | Clear message history |
 | `/sessions` | List/manage saved sessions |
+| `/handoff` | Show the saved task checkpoint a resumed session started from |
 | `/rename <name>` | Set a stable session name; `--clear` returns to automatic labels |
 | `/label [pane <id>] ...` | Show, name, pin, group, or tag a session or pane |
 | `/status` | Show current status |
@@ -1345,6 +1363,7 @@ unset preserves normal interactive discovery.
 |----------|-------------|
 | `ANTHROPIC_API_KEY` | Anthropic API key for direct API billing |
 | `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code OAuth token from `claude setup-token`; used by `/config provider claude_code` |
+| `ZTC_NO_BROWSER` | Set to `1` so ZTC never opens a browser (logins, `/mirror`, billing); it prints the URL instead. CI and test runs behave this way already |
 | `ZTC_DEBUG` | Enable debug logging |
 | `ZTC_SUBAGENT_DEBUG` | Log sub-agent execution |
 | `ZTC_DISABLE_AUTO_COMPACT` | Disable automatic compaction |

package/THIRD_PARTY_NOTICES.md

@@ -26,7 +26,8 @@ retain their own license and notice files; this table does not replace them.
 
 | Package | Locked version | License | Upstream |
 | --- | ---: | --- | --- |
-| `@modelcontextprotocol/sdk` | 1.30.0 | MIT | https://www.npmjs.com/package/@modelcontextprotocol/sdk |
+| `@aws-sdk/client-bedrock-runtime` | 3.1160.0 | Apache-2.0 | https://www.npmjs.com/package/@aws-sdk/client-bedrock-runtime |
+| `@modelcontextprotocol/sdk` | 1.32.2 | MIT | https://www.npmjs.com/package/@modelcontextprotocol/sdk |
 | `acorn` | 8.18.0 | MIT | https://www.npmjs.com/package/acorn |
 | `chalk` | 5.6.2 | MIT | https://www.npmjs.com/package/chalk |
 | `docx` | 9.7.1 | MIT | https://www.npmjs.com/package/docx |
@@ -34,16 +35,20 @@ retain their own license and notice files; this table does not replace them.
 | `fastify` | 5.12.5 | MIT | https://www.npmjs.com/package/fastify |
 | `immer` | 10.1.1 | MIT | https://github.com/immerjs/immer |
 | `ink` | 5.2.1 | MIT | https://www.npmjs.com/package/ink |
+| `jpeg-js` | 0.4.4 | BSD-3-Clause | https://www.npmjs.com/package/jpeg-js |
 | `jsonrepair` | 3.15.0 | ISC | https://www.npmjs.com/package/jsonrepair |
 | `node-pty` | 1.1.0 | MIT | https://www.npmjs.com/package/node-pty |
 | `nunjucks` | 3.2.4 | BSD-2-Clause | https://www.npmjs.com/package/nunjucks |
+| `omggif` | 1.0.10 | MIT | https://www.npmjs.com/package/omggif |
 | `pdfkit` | 0.18.0 | MIT | https://www.npmjs.com/package/pdfkit |
+| `pngjs` | 7.0.0 | MIT | https://www.npmjs.com/package/pngjs |
 | `pptxgenjs` | 4.0.1 | MIT | https://github.com/gitbrent/PptxGenJS/tree/v4.0.1 |
+| `proper-lockfile` | 4.1.2 | MIT | https://www.npmjs.com/package/proper-lockfile |
 | `react` | 18.3.1 | MIT | https://www.npmjs.com/package/react |
 | `semver` | 7.8.5 | ISC | https://www.npmjs.com/package/semver |
 | `socket.io-client` | 4.8.3 | MIT | https://www.npmjs.com/package/socket.io-client |
 | `yaml` | 2.9.0 | ISC | https://www.npmjs.com/package/yaml |
-| `zod` | 4.4.3 | MIT | https://www.npmjs.com/package/zod |
+| `zod` | 4.6.7 | MIT | https://www.npmjs.com/package/zod |
 
 ### Separate view clients and retained historical references
 

package/dist/App.js

@@ -207,6 +207,7 @@ export const App = () => {
     const [agentMode, setAgentMode] = useState('normal');
     const [agent, setAgent] = useState(null);
     const diagnosticAgentRef = useRef(null);
+    const agentStartFailedRef = useRef(false); // the last createBoundAgent threw, and said why
     diagnosticAgentRef.current = agent;
     const retainedUsageRef = useRef({ sessionId, snapshot: createUsageSnapshot() });
     const [routingUsageRevision, setRoutingUsageRevision] = useState(0);
@@ -883,7 +884,17 @@ export const App = () => {
         onLocalFileChange: async (paths, cwd) => { await workspaceCoordinator.recordObservedPaths(paths, cwd); },
     }), [admitWorkspace, addMessage, sessionId, workspaceCoordinator]);
     const createBoundAgent = useCallback((mode, skillPrompt) => {
-        const next = createAgent(mode, skillPrompt, workspaceFactoryOptions());
+        agentStartFailedRef.current = false;
+        let next;
+        try {
+            next = createAgent(mode, skillPrompt, workspaceFactoryOptions());
+        }
+        catch (error) {
+            // A configuration no agent can be built from is said in the transcript, not thrown into the renderer.
+            agentStartFailedRef.current = true;
+            addMessage({ role: 'system', content: `Unable to start the agent: ${error instanceof Error ? error.message : String(error)}` });
+            return null;
+        }
         const previous = diagnosticAgentRef.current;
         if (next) {
             next.restoreUsageSnapshot(getUsageSnapshot());
@@ -897,7 +908,7 @@ export const App = () => {
             diagnosticAgentRef.current = next;
         }
         return next;
-    }, [workspaceFactoryOptions, getUsageSnapshot]);
+    }, [workspaceFactoryOptions, getUsageSnapshot, addMessage]);
     // Every reconstruction retains workspace admission and successful-file observation.
     const reloadAgent = useCallback(() => {
         retireAgentQuestion();
@@ -1795,10 +1806,12 @@ export const App = () => {
             setAgent(currentAgent);
         }
         if (!currentAgent) {
-            addMessage({
-                role: 'system',
-                content: 'Failed to initialize agent. Please check your configuration.'
-            });
+            if (!agentStartFailedRef.current) { // otherwise createBoundAgent just said why
+                addMessage({
+                    role: 'system',
+                    content: 'Failed to initialize agent. Please check your configuration.'
+                });
+            }
             return;
         }
         const userMsg = {
@@ -1960,9 +1973,13 @@ export const App = () => {
                     break;
                 case 'api_retry':
                     setAgentState(s => applyAgentEventToState(s, event));
-                    addMessage({
-                        role: 'system',
-                        content: formatApiRetryNotice(event)
+                    // Retries of one request update one notice instead of adding a line per attempt.
+                    setMessages(prev => {
+                        const last = prev[prev.length - 1];
+                        const content = formatApiRetryNotice(event);
+                        return last?.role === 'system' && last.metadata?.apiRetry === true
+                            ? [...prev.slice(0, -1), { ...last, content }]
+                            : [...prev, { role: 'system', content, metadata: { apiRetry: true }, id: generateId(), timestamp: new Date() }];
                     });
                     break;
                 case 'error':

package/dist/agent/agent.d.ts

@@ -10,9 +10,12 @@ import { type ExecutionContext } from './runtime/execution_context.js';
 import { Policy } from './runtime/policy.js';
 import { Tracer } from './runtime/tracing.js';
 import { type DiagnosticEventKind, type DiagnosticJsonObject, type DiagnosticSnapshot } from '../diagnostics/session_export.js';
+import { type ToolGroupsConfig } from './tools/tool_groups.js';
+import type { ToolDefinition } from '../types.js';
 import type { Tool } from './tools/types.js';
 import { ToolResponseStore } from './tool_response_store.js';
 import { type EvidenceSnapshot } from './runtime/evidence.js';
+import { BackgroundWorkers } from './background_workers.js';
 import type { HostApprovalContext } from './runtime/tool_runtime.js';
 import { ToolCapability } from './runtime/capabilities.js';
 import { HookDispatcher } from '../hooks/dispatcher.js';
@@ -30,6 +33,7 @@ export interface SteeringAdmissionCheckpoint {
 }
 export type SteeringAdmissionCheckpointHandler = (checkpoint: SteeringAdmissionCheckpoint) => Promise<void>;
 export interface AgentConfig {
+    provider?: string;
     remoteResourceSession?: import('./runtime/remote_resources.js').RemoteResourceSession;
     model?: string;
     apiKey?: string;
@@ -73,6 +77,7 @@ export interface AgentConfig {
     tracer?: Tracer;
     cwd?: string;
     autoContinue?: boolean;
+    completionCheck?: boolean;
     /**
      * Cap on consecutive auto-continues before a turn is allowed to end. Each
      * auto-continue is a full-context API request, and a model that narrates an
@@ -88,6 +93,15 @@ export interface AgentConfig {
      * request.system exactly as configured.
      */
     pinTaskHeader?: boolean;
+    /**
+     * Session environment composed at startup (working directory, date, git
+     * status). It changes between sessions of one project, so local task
+     * sessions send it as the first conversation row, after the system prompt
+     * and the tool definitions that chat templates render after it, leaving
+     * that whole prefix shared across sessions in provider caches. Otherwise it
+     * ends request.system.
+     */
+    runtimeContext?: string;
     /**
      * Exact environment exposed to ZTC shell-tool subprocesses. When present it
      * replaces ambient process.env; reserved ZTC coordination variables are
@@ -121,6 +135,15 @@ export interface AgentConfig {
      * via tool_search (which a restrictive mode allowlist can even hide).
      */
     alwaysLoadedToolNames?: Iterable<string>;
+    /** Host note placed after each authored prompt, such as a lead's reminder to delegate. */
+    leadTurnNote?: string;
+    /** Host note for a lead that has worked alone for `afterSteps` requests in a turn, sent once. */
+    leadStaffingNote?: {
+        afterSteps: number;
+        content: string;
+    };
+    /** How often a lead gets a progress check on its background workers. */
+    workerCheckIntervalMs?: number;
     /**
      * When false, every registered tool schema ships with each request instead
      * of hiding non-core tools behind tool_search. Set by factory for modes
@@ -128,6 +151,18 @@ export interface AgentConfig {
      * the agent's whole vocabulary. Default: true (defer).
      */
     deferToolSchemas?: boolean;
+    /** Host-declared tool groups; visibility lasts for this Agent instance. */
+    toolGroups?: ToolGroupsConfig;
+    onMidTurnCompact?: (context: MidTurnCompactContext) => Promise<Message[] | null>;
+    midTurnCompactThresholdPercent?: number;
+    midTurnCompactWindow?: number | null;
+    midTurnCompactTokenBudget?: number;
+}
+export interface MidTurnCompactContext {
+    messages: Message[];
+    usedTokens: number;
+    windowTokens?: number;
+    signal?: AbortSignal;
 }
 export interface AgentConversationBinding {
     driver: ConversationDriver;
@@ -141,6 +176,7 @@ export interface AgentRunResult {
     usage?: TokenUsage;
     stopReason: 'complete' | 'interactive' | 'max_iterations';
     reasoning?: string;
+    responseItems?: Array<Record<string, unknown>>;
     nativeContent?: ContentBlock[];
     nativeModel?: string;
     nativeContextId?: string;
@@ -171,8 +207,15 @@ export type EventHandler = (event: AgentEvent) => void;
 export declare class Agent {
     #private;
     private config;
+    private onMidTurnCompact?;
+    private midTurnCompactThresholdPercent?;
+    private midTurnCompactWindow?;
+    private midTurnCompactTokenBudget?;
     /** Codex/GPT reasoning effort override; undefined = provider default. */
     private _codexEffort?;
+    /** One-shot: the next request carries the output-limit note at this effort. */
+    /** The next request retries a discarded response: a note for the model, and lower effort when offered. */
+    private responseRetry;
     /** Fast mode — request the priority service tier from the Codex/GPT backend. */
     private _codexFastMode;
     private eventHandlers;
@@ -194,6 +237,11 @@ export declare class Agent {
     private _autoContinue;
     /** Auto-continues spent since the last tool run; reset per turn and per tool. */
     private _consecutiveAutoContinues;
+    private _turnAutoContinues;
+    private _turnToolBatches;
+    private _turnToolChangedState;
+    private _turnCommandsRun;
+    private _turnCheckAsked;
     private readonly _subprocessEnv?;
     private readonly commandPolicy?;
     private readonly toolEffectObserver?;
@@ -223,8 +271,13 @@ export declare class Agent {
     private toolTraceData;
     /** Fresh applicability is a projection; original process/source observations remain immutable. */
     refreshVerificationCoverage(): Promise<void>;
+    private readonly toolGroups;
     readonly discoveredTools: Set<string>;
     readonly alwaysLoadedToolNames: Set<string>;
+    /** Workers started with delegate_task `background: true`; stopped when a run ends. */
+    readonly backgroundWorkers: BackgroundWorkers;
+    /** The latest authored prompt, for a worker's brief. */
+    private turnInstruction;
     private hooks?;
     private approvalRequester?;
     private readonly approvalRequiredCapabilities;
@@ -251,8 +304,16 @@ export declare class Agent {
     hasApiKey(): boolean;
     setCwd(cwd: string): void;
     getCwd(): string;
+    /** Load a declared group after a host page change; Codex requires a new session. */
+    loadToolGroup(group: string): {
+        group: string;
+        tools: ToolDefinition[];
+    };
     /** Snapshot the effective tool surface after mode/provider filtering. */
     getConfiguredToolNames(): string[];
+    getHandoffContext(messages?: Message[]): BackendRequest & {
+        backend: AgentBackend;
+    };
     private getDefaultSystemPrompt;
     on(handler: EventHandler): () => void;
     private emit;
@@ -264,6 +325,8 @@ export declare class Agent {
     private _nativeContextId?;
     private formatMessages;
     private _encodeDeps;
+    /** A whole result kept on disk before it is sent shortened; an ephemeral tool's stays in memory. */
+    private saveFullResult;
     private contentLength;
     private buildContentBlocks;
     private loadImageBlock;
@@ -300,6 +363,7 @@ export declare class Agent {
     steerUserMessage(message: Message): Promise<boolean>;
     /** Tools that end the agent turn when called (require user interaction before continuing). */
     private static readonly TURN_ENDING_TOOLS;
+    private static readonly SELF_RESOLVING_TOOLS;
     /**
      * R7: the original task, pinned into request.system so it survives compaction
      * (which only rewrites the message array, never request.system) and the rolling
@@ -309,9 +373,22 @@ export declare class Agent {
      * genuinely multi-task long-lived agents is deferred (plan A10).
      */
     private _taskHeader;
+    private runtimeContext;
     private taskHandoff;
+    private taskHandoffTurn;
+    private runtimeEnvironmentTurn;
     /** Only a host-selected checkpoint may supply historical task context. */
     setTaskHandoff(projection: TaskHandoffProjection | null): void;
+    hostScaffoldMessages(): Array<{
+        id: string;
+        content: string;
+        capturedAt: string;
+    }>;
+    setHostScaffoldMessages(rows: readonly {
+        id: string;
+        content: string;
+        capturedAt: string;
+    }[] | undefined): void;
     /**
      * Drop the explicitly pinned task for the next conversation. Wired into the /clear-only path (clearTransientState), never into
      * /compact — the pin must survive compaction (that is the whole point of R7).