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

package/dist/web/event_history_store.d.ts

@@ -71,6 +71,8 @@ export declare class MemoryHistoryStore implements EventHistoryStore {
     oldestSeq(): number;
     canResume(cursor: number): boolean;
     append(event: MirrorEvent): void;
+    /** Drops the earlier copy of a snapshot this event replaces; true when one was dropped. */
+    protected dropSuperseded(event: MirrorEvent): boolean;
     snapshot(): MirrorEvent[];
     since(cursor: number): MirrorEvent[];
     purgePane(paneId: number): void;

package/dist/web/event_history_store.js

@@ -16,11 +16,18 @@
  */
 import { existsSync, appendFileSync, readFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
-import { createHash } from 'crypto';
-import { homedir } from 'os';
 import { writeFileAtomicSync } from '../utils/atomic_write.js';
+import { getGlobalSessionsRoot, getProjectHash } from '../session.js';
 const DEFAULT_MAX_EVENTS = 500;
 const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * State snapshots a client applies latest-wins. They are re-sent on every checkpoint and every 30 s while idle, and
+ * once filled half of a session's 500-event window, pushing out its conversation (2026-10-27). A pane keeps only
+ * its latest of each.
+ */
+const SNAPSHOT_EVENT_TYPES = new Set(['goal', 'task_handoff', 'evidence']);
+const snapshotKey = (event) => SNAPSHOT_EVENT_TYPES.has(event.type)
+    ? `${event.type}:${typeof event.data?.pane_id === 'number' ? event.data.pane_id : 0}` : null;
 /**
  * In-memory adapter: the bounded ring + seq + resume logic, no disk.
  * Base for JsonlHistoryStore, which adds persistence via the protected hooks.
@@ -51,10 +58,25 @@ export class MemoryHistoryStore {
     }
     append(event) {
         const serialized = JSON.stringify(event);
+        const superseded = this.dropSuperseded(event);
         this.events.push(event);
         this.bytes += Buffer.byteLength(serialized, 'utf8');
         const trimmed = this.trim();
-        this.onAppended(event, serialized, trimmed);
+        this.onAppended(event, serialized, trimmed || superseded);
+    }
+    /** Drops the earlier copy of a snapshot this event replaces; true when one was dropped. */
+    dropSuperseded(event) {
+        const key = snapshotKey(event);
+        if (key === null)
+            return false;
+        let index = this.events.length - 1;
+        while (index >= 0 && snapshotKey(this.events[index]) !== key)
+            index -= 1;
+        if (index < 0)
+            return false;
+        this.bytes -= this.measure(this.events[index]);
+        this.events.splice(index, 1);
+        return true;
     }
     snapshot() {
         return [...this.events];
@@ -163,8 +185,8 @@ export class JsonlHistoryStore extends MemoryHistoryStore {
      * the legacy MirrorStreamServer.initSessionPersistence path derivation.
      */
     static sessionFilePath(persistenceKey) {
-        const cwdHash = createHash('sha256').update(process.cwd()).digest('hex').slice(0, 12);
-        const sessionDir = join(homedir(), '.ztc', 'sessions', cwdHash);
+        // Beside the session's own files, so ZTC_SESSIONS_DIR moves both.
+        const sessionDir = join(getGlobalSessionsRoot(), getProjectHash(process.cwd()));
         if (!existsSync(sessionDir)) {
             mkdirSync(sessionDir, { recursive: true });
         }
@@ -189,6 +211,7 @@ export class JsonlHistoryStore extends MemoryHistoryStore {
                 const content = readFileSync(this.file, 'utf-8');
                 const lines = content.trimEnd().split('\n');
                 let maxSeq = 0;
+                let superseded = false;
                 for (const line of lines) {
                     if (!line)
                         continue;
@@ -200,6 +223,8 @@ export class JsonlHistoryStore extends MemoryHistoryStore {
                         // Ephemeral modals from an older log would replay as dead zombies.
                         if (this.ephemeral(evt))
                             continue;
+                        if (this.dropSuperseded(evt))
+                            superseded = true;
                         this.events.push(evt);
                         this.bytes += this.measure(evt);
                         if (evt.seq && evt.seq > maxSeq)
@@ -209,7 +234,7 @@ export class JsonlHistoryStore extends MemoryHistoryStore {
                         // Skip malformed lines.
                     }
                 }
-                if (this.trim()) {
+                if (this.trim() || superseded) {
                     this.rewrite();
                 }
                 // Resume sequence numbering from where we left off.

package/dist/web/mirror_client.d.ts

@@ -110,7 +110,10 @@ export declare class MirrorClient implements MirrorPublisher {
             value: string;
             label: string;
             description?: string;
+            details?: string[];
         }>;
+        defaultValue?: string | string[];
+        required?: boolean;
     }): void;
     publishWidgetQuestionnaire(widgetId: string, options: {
         title?: string;

package/dist/web/mirror_stream.d.ts

@@ -443,6 +443,8 @@ export declare class MirrorStreamServer implements MirrorPublisher {
     private operatorIsSuperuser;
     private readonly browserBasePath;
     private sfxConfig;
+    /** The settings page's Connection section state; see publishConnectionState. */
+    private connectionState;
     private setSfxCallback;
     private savedLayout;
     private layoutFilePath;
@@ -568,7 +570,10 @@ export declare class MirrorStreamServer implements MirrorPublisher {
             value: string;
             label: string;
             description?: string;
+            details?: string[];
         }>;
+        defaultValue?: string | string[];
+        required?: boolean;
     }): void;
     /**
      * Publish a questionnaire widget to the browser (multi-field form).
@@ -765,6 +770,12 @@ export declare class MirrorStreamServer implements MirrorPublisher {
      * (auto/direct/zrouter) after a change. Retained so a reload sees the
      * current mode; the connected payload carries it as initial state.
      */
+    /**
+     * Broadcast the connection snapshot (the ZergAI login and where each
+     * provider key comes from, masked) after a change. Live-only: the connected
+     * payload and /debug/config give new clients the current one.
+     */
+    publishConnectionState(state: Record<string, unknown>): void;
     publishAuthMode(mode: string, envOverride?: string): void;
     private pendingReasoning;
     /** Events that close an open thought: anything that continues the turn. */

package/dist/web/mirror_stream.js

@@ -194,6 +194,8 @@ export class MirrorStreamServer {
     operatorIsSuperuser = false;
     browserBasePath;
     sfxConfig = null;
+    /** The settings page's Connection section state; see publishConnectionState. */
+    connectionState = null;
     setSfxCallback = null;
     // DockView layout persistence
     savedLayout = null;
@@ -941,8 +943,10 @@ export class MirrorStreamServer {
         this.accountsUnsub?.();
         this.accountsUnsub = null;
         await new Promise((resolve) => {
-            this.server.close(() => resolve());
-            setTimeout(resolve, 2000);
+            // Open SSE clients can hold close() open; give up after two seconds, and clear the timer
+            // when close() finishes first so it cannot hold the process open.
+            const giveUp = setTimeout(resolve, 2000);
+            this.server.close(() => { clearTimeout(giveUp); resolve(); });
         });
         await Promise.allSettled([...this.toolImageJobs]);
         await this.cleanupMediaDir();
@@ -1024,7 +1028,10 @@ export class MirrorStreamServer {
             && event.type !== 'settings_page'
             // Legacy open_accounts is also live-only: replay would navigate a fresh
             // browser tab to Accounts without a new user command.
-            && event.type !== 'open_accounts') {
+            && event.type !== 'open_accounts'
+            // connection_state is current state, not conversation: new clients read
+            // it from the connected payload, so history never holds stale copies.
+            && event.type !== 'connection_state') {
             this.history.append(fullEvent);
         }
         // Notify plugins (e.g. for event persistence)
@@ -1117,6 +1124,7 @@ export class MirrorStreamServer {
             colony_enabled: this.hasViewPlugin('colony'),
             colony_config: configStore.get().workflows ?? {},
             repo_config: { cwd: process.cwd(), config: readRepoConfig(process.cwd()) ?? {} },
+            ...(this.connectionState ? { connection_state: this.connectionState } : {}),
         };
     }
     /**
@@ -1151,6 +1159,9 @@ export class MirrorStreamServer {
             // server's cwd is the repo being worked on); live changes arrive as
             // repo_config events.
             repo_config: { cwd: process.cwd(), config: readRepoConfig(process.cwd()) ?? {} },
+            // Initial Connection section state; live changes arrive as
+            // connection_state events (see publishConnectionState).
+            ...(this.connectionState ? { connection_state: this.connectionState } : {}),
         };
     }
     /**
@@ -1181,6 +1192,15 @@ export class MirrorStreamServer {
      * (auto/direct/zrouter) after a change. Retained so a reload sees the
      * current mode; the connected payload carries it as initial state.
      */
+    /**
+     * Broadcast the connection snapshot (the ZergAI login and where each
+     * provider key comes from, masked) after a change. Live-only: the connected
+     * payload and /debug/config give new clients the current one.
+     */
+    publishConnectionState(state) {
+        this.connectionState = state;
+        this.publish({ type: 'connection_state', data: state });
+    }
     publishAuthMode(mode, envOverride) {
         this.publish({ type: 'auth_mode', data: { mode, ...(envOverride ? { env_override: envOverride } : {}) } });
     }

package/dist/worker/executor.js

@@ -75,7 +75,8 @@ export class InProcessWorkerExecutor {
                 } : undefined,
                 signal: task.signal,
                 systemPrompt: task.systemPrompt,
-                tools: resolveWorkerToolset(task.toolset),
+                tools: [...resolveWorkerToolset(task.toolset), ...(task.extraTools ?? [])],
+                takeMessages: options?.takeMessages,
                 onIteration: onEvent
                     ? (info) => {
                         onEvent({ type: 'iteration', current: info.iteration, max: info.max });
@@ -114,6 +115,7 @@ function mapResult(sub) {
         commandsRun: sub.commandsRun,
         iterations: sub.iterations,
         error: sub.error,
+        ...(sub.stoppedAtStepLimit ? { stoppedAtStepLimit: true } : {}),
         tokensUsed: sub.tokensUsed,
         durationMs: sub.durationMs,
     };

package/dist/worker/toolsets.d.ts

@@ -9,6 +9,6 @@ import type { WorkerToolset } from './types.js';
 export declare const PLANNING_TOOLS: Tool[];
 /** Read-only-ish research tools for delegate tasks that may need diagnostics. */
 export declare const RESEARCH_TOOLS: Tool[];
-/** Research tools + write access for background / batch worker tasks. */
+/** Research tools + write and edit access for background / batch / editing worker tasks. */
 export declare const WRITE_TOOLS: Tool[];
 export declare function resolveWorkerToolset(toolset?: WorkerToolset): Tool[];

package/dist/worker/toolsets.js

@@ -3,7 +3,8 @@
  *
  * Moved from subagent.ts. Workers are the consumers of these sets, not SubAgent.
  */
-import { readFileTool, writeFileTool, listDirectoryTool } from '../agent/tools/file.js';
+import { readFileTool, writeFileTool, editFileTool, listDirectoryTool } from '../agent/tools/file.js';
+import { applyPatchTool } from '../agent/tools/apply_patch.js';
 import { searchTool } from '../agent/tools/search.js';
 import { runCommandTool, readCommandTool, stopCommandTool } from '../agent/tools/shell.js';
 /** Strict read-only tools for planning phases. No shell: shell can mutate workspaces. */
@@ -19,8 +20,8 @@ export const RESEARCH_TOOLS = [
     readCommandTool,
     stopCommandTool,
 ];
-/** Research tools + write access for background / batch worker tasks. */
-export const WRITE_TOOLS = [...RESEARCH_TOOLS, writeFileTool];
+/** Research tools + write and edit access for background / batch / editing worker tasks. */
+export const WRITE_TOOLS = [...RESEARCH_TOOLS, writeFileTool, editFileTool, applyPatchTool];
 export function resolveWorkerToolset(toolset = 'research') {
     switch (toolset) {
         case 'planning':

package/dist/worker/types.d.ts

@@ -32,6 +32,8 @@ export type WorkerEvent = Extract<AgentEvent, {
 export interface WorkerExecutionOptions {
     onEvent?: (event: WorkerEvent) => void;
     onUsage?: ModelUsageObserver;
+    /** Messages from a supervising lead, delivered before the worker's next step. */
+    takeMessages?: () => string[];
 }
 export type WorkerFailureClass = 'timeout' | 'abort' | 'trust_gate' | 'prompt_delivery' | 'protocol' | 'tool_error' | 'llm_error' | 'workspace_mismatch' | 'infra';
 export type WorkerToolset = 'planning' | 'research' | 'write';
@@ -47,6 +49,8 @@ export interface WorkerTask {
     maxIterations?: number;
     timeoutMs?: number;
     temporaryWriteRoot?: string;
+    /** Tools added to the toolset for this task, such as a supervised worker's report_progress. */
+    extraTools?: import('../agent/tools/types.js').Tool[];
 }
 export interface WorkerResult {
     evidence?: DelegatedEvidenceHandoff;
@@ -57,6 +61,8 @@ export interface WorkerResult {
     commandsRun: string[];
     iterations: number;
     error?: string;
+    /** Ran out of steps; `summary` is the report it wrote when asked to stop. */
+    stoppedAtStepLimit?: boolean;
     tokensUsed: {
         input: number;
         output: number;

package/dist/worker/worker_models.d.ts

@@ -0,0 +1,17 @@
+import { ModelPoolBackend } from '../agent/backends/model_pool.js';
+import type { OpenRouterPreferences, WorkerSettings } from '../config/types.js';
+import type { RouterCatalogConnection } from '../utils/router_catalog.js';
+export interface WorkerModels {
+    backend: ModelPoolBackend;
+    /** The first model, reported as the workers' model. */
+    model: string;
+}
+/** The user's Router login, for Router-served worker models. */
+export interface WorkerRouter {
+    connection?: RouterCatalogConnection;
+    /** The lead's session, pinned on Router turns like the lead's own. */
+    conversationId?: string;
+    /** The user's OpenRouter preferences, read on every request. */
+    openRouterPreferences?: () => OpenRouterPreferences | undefined;
+}
+export declare function createWorkerModels(settings: WorkerSettings, router?: WorkerRouter): WorkerModels;

package/dist/worker/worker_models.js

@@ -0,0 +1,79 @@
+/**
+ * Builds the model pool delegated workers run on from the `workers` setting.
+ * A Router model runs on the user's ZergRouter login. Any other entry inherits
+ * the shared endpoint and may override any part of it.
+ */
+import { BackendHttpError } from '../agent/backends/http_error.js';
+import { OpenAICompatibleBackend } from '../agent/backends/openai_compatible.js';
+import { ModelPoolBackend } from '../agent/backends/model_pool.js';
+import { ZRouterStreamBackend } from '../agent/backends/zrouter_stream.js';
+import { discoverRouterCatalog, readRouterCatalog } from '../utils/router_catalog.js';
+/** The catalog row a worker names by its exact id, or else by a unique alias. */
+function catalogRow(catalog, model) {
+    const rows = catalog?.models ?? [];
+    const exact = rows.filter(row => row.id === model);
+    const matches = exact.length > 0 ? exact : rows.filter(row => row.aliases?.includes(model));
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/**
+ * Worker models served by ZergRouter. Each request's model is a Router catalog
+ * id, resolved to its provider through the catalog like the lead's model. A
+ * model the catalog does not list is gone (404), so a pool moves past it.
+ */
+class RouterWorkerBackend {
+    connection;
+    conversationId;
+    openRouterPreferences;
+    providers = new Map();
+    constructor(connection, conversationId, openRouterPreferences) {
+        this.connection = connection;
+        this.conversationId = conversationId;
+        this.openRouterPreferences = openRouterPreferences;
+    }
+    async route(request) {
+        let catalog = readRouterCatalog(this.connection);
+        let row = catalogRow(catalog, request.model);
+        if (!row) {
+            catalog = await discoverRouterCatalog(this.connection, request.signal);
+            row = catalogRow(catalog, request.model);
+        }
+        if (!row)
+            throw new BackendHttpError(404, `Model ${request.model} is not in the Router catalog.`, { prefix: 'ZRouter' });
+        let backend = this.providers.get(row.owned_by);
+        if (!backend) {
+            backend = new ZRouterStreamBackend({ apiKey: this.connection.token, proxyUrl: this.connection.origin,
+                provider: row.owned_by, workspaceId: this.connection.workspaceId, conversationId: this.conversationId, catalog,
+                openRouterPreferences: this.openRouterPreferences });
+            this.providers.set(row.owned_by, backend);
+        }
+        return { backend, request: { ...request, model: row.id } };
+    }
+    async generate(request) {
+        const routed = await this.route(request);
+        return routed.backend.generate(routed.request);
+    }
+    async *generateStream(request) {
+        const routed = await this.route(request);
+        yield* routed.backend.generateStream(routed.request);
+    }
+}
+export function createWorkerModels(settings, router = {}) {
+    let routerBackend;
+    const members = settings.models.map(entry => {
+        const { model, router: ownRouter, ...own } = typeof entry === 'string' ? { model: entry } : entry;
+        if (ownRouter ?? settings.router) {
+            if (Object.keys(own).length > 0)
+                throw new Error(`Worker model ${model} runs on ZergRouter and cannot set an endpoint.`);
+            if (!router.connection)
+                throw new Error(`Worker model ${model} runs on ZergRouter, which needs a Router login: run ztc auth login.`);
+            routerBackend ??= new RouterWorkerBackend(router.connection, router.conversationId, router.openRouterPreferences);
+            return { model, backend: routerBackend };
+        }
+        const endpoint = { ...settings.endpoint, ...own };
+        if (!endpoint.baseUrl)
+            throw new Error(`Worker model ${model} has no endpoint baseUrl.`);
+        return { model, backend: new OpenAICompatibleBackend({ apiKey: endpoint.apiKey ?? '', baseUrl: endpoint.baseUrl,
+                apiPath: endpoint.apiPath, headers: endpoint.headers }) };
+    });
+    return { backend: new ModelPoolBackend(members), model: members[0].model };
+}