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

package/dist/agent/backends/types.d.ts

@@ -1,4 +1,8 @@
 import type { ToolDefinition, Message } from '../../types.js';
+/** A request ZTC refuses before sending it. Nothing reached a provider, so its message is shown as written. */
+export declare class RequestRefusedError extends Error {
+    readonly name = "RequestRefusedError";
+}
 export interface RequestTextBlock {
     type: 'text';
     text: string;
@@ -35,6 +39,13 @@ export interface ToolUseRequestBlock {
     id: string;
     name: string;
     input: Record<string, unknown>;
+    /** Exact native Responses function item; call_id remains the execution identity. */
+    responsesItem?: Record<string, unknown>;
+}
+export interface ResponsesReasoningBlock {
+    type: 'responses_reasoning';
+    /** Opaque encrypted provider context. Never render it or replay across models/prefixes. */
+    item: Record<string, unknown>;
 }
 export interface ThinkingBlock {
     type: 'thinking';
@@ -46,8 +57,9 @@ export interface RedactedThinkingBlock {
     type: 'redacted_thinking';
     data: string;
 }
-export type RequestContentBlock = RequestTextBlock | RequestImageBlock | RequestVideoBlock | ToolResultBlock | ToolUseRequestBlock | ThinkingBlock | RedactedThinkingBlock;
+export type RequestContentBlock = RequestTextBlock | RequestImageBlock | RequestVideoBlock | ToolResultBlock | ToolUseRequestBlock | ThinkingBlock | RedactedThinkingBlock | ResponsesReasoningBlock;
 export interface LlmMessage {
+    responseItems?: Array<Record<string, unknown>>;
     role: 'user' | 'assistant';
     content: string | RequestContentBlock[];
     /** Provider-specific opaque reasoning trace (e.g. Kimi/Moonshot
@@ -64,8 +76,9 @@ export interface ToolUseBlock {
     id: string;
     name: string;
     input: Record<string, unknown>;
+    responsesItem?: Record<string, unknown>;
 }
-export type ContentBlock = TextBlock | ToolUseBlock | ThinkingBlock | RedactedThinkingBlock;
+export type ContentBlock = TextBlock | ToolUseBlock | ThinkingBlock | RedactedThinkingBlock | ResponsesReasoningBlock;
 /**
  * An action surfaced by a provider that runs its OWN tool/command loop (e.g. the
  * official Codex App Server). Unlike ZTC-owned tool calls — where the model
@@ -278,6 +291,7 @@ export interface ClientToolCallResult {
     }>;
 }
 export interface BackendResponse {
+    responseItems?: Array<Record<string, unknown>>;
     content: ContentBlock[];
     stopReason: string;
     stopDetails?: Record<string, unknown>;
@@ -314,6 +328,9 @@ export interface TokenUsage {
     contextWindow?: number;
 }
 export type StreamEvent = {
+    type: 'response_items';
+    items: Array<Record<string, unknown>>;
+} | {
     type: 'heartbeat';
 } | {
     type: 'reasoning_delta';
@@ -382,6 +399,12 @@ export interface AgentBackend {
     allowsBufferedFallbackAfterStreamFailure?(request: BackendRequest): boolean;
     /** Native harnesses return false once dispatch may have produced external effects. */
     allowsRequestRetryAfterFailure?(request: BackendRequest): boolean;
+    /**
+     * Ask the provider to stop generating a request the agent abandoned. Router
+     * keeps producing a turn after the client stops reading so it can resume, so
+     * a response dropped as runaway output would otherwise run to its limit.
+     */
+    cancelTurn?(request: BackendRequest): Promise<void>;
     /**
      * True when the backend correlates a logical turn across transport reconnects
      * (it stamps a `transportTurnId` so the Router can resume the same buffered

package/dist/agent/backends/types.js

@@ -1,3 +1,7 @@
+/** A request ZTC refuses before sending it. Nothing reached a provider, so its message is shown as written. */
+export class RequestRefusedError extends Error {
+    name = 'RequestRefusedError';
+}
 /** Convert a non-streaming BackendResponse into synthetic StreamEvents. */
 export function* syntheticStreamEvents(response) {
     if (response.reasoning) {

package/dist/agent/backends/zrouter_stream.d.ts

@@ -1,6 +1,8 @@
 import type { RouterCatalog, RouterModelCapabilities } from '../../utils/router_catalog.js';
+import type { OpenRouterPreferences } from '../../config/types.js';
 import { AgentBackend, BackendRequest, BackendResponse, StreamEvent } from './types.js';
 export interface ZRouterStreamConfig {
+    model?: string;
     catalog?: RouterCatalog;
     apiKey: string;
     proxyUrl: string;
@@ -19,6 +21,8 @@ export interface ZRouterStreamConfig {
     conversationId?: string;
     /** Product identity for attribution. Defaults to the regular ZTC client. */
     clientName?: string;
+    /** Read on every request, so a changed preference applies to the next one. */
+    openRouterPreferences?: () => OpenRouterPreferences | undefined;
 }
 /**
  * Backend that streams LLM responses through ZRouter proxy.
@@ -28,6 +32,7 @@ export interface ZRouterStreamConfig {
  * uses the unified chat endpoint so routing can fall back across providers.
  */
 export declare class ZRouterStreamBackend implements AgentBackend {
+    readonly preservesNativeHistory: boolean;
     private readonly initialCatalog?;
     private get catalog();
     private apiKey;
@@ -37,11 +42,22 @@ export declare class ZRouterStreamBackend implements AgentBackend {
     private workspaceId?;
     private conversationId?;
     private clientName;
+    private openRouterPreferences?;
     constructor(config: ZRouterStreamConfig);
     private endpointFor;
     isAuthenticationConfigured(): boolean;
     allowsBufferedFallbackAfterStreamFailure(): boolean;
     handlesTransportRetries(): boolean;
+    allowsRequestRetryAfterFailure(request: BackendRequest): boolean;
+    private usesNativeResponses;
+    private nativeResponses;
+    /**
+     * Stop the provider stream of an abandoned turn. Without it Router keeps
+     * producing until the response ends. Router then has no provider usage
+     * report, so the request settles as incomplete: use it only for responses
+     * that would otherwise run to their output limit.
+     */
+    cancelTurn(request: BackendRequest): Promise<void>;
     getModelCapabilities(model: string): RouterModelCapabilities | undefined;
     private buildOpenAIBody;
     private serializeBody;

package/dist/agent/backends/zrouter_stream.js

@@ -3,15 +3,17 @@ import { readRouterCatalog, resolveRouterModel } from '../../utils/router_catalo
 import { randomUUID } from 'node:crypto';
 import { measureResponse, measureStream } from './request_metrics.js';
 import { BackendHttpError, readHttpErrorBody, retryAfterDelayMs } from './http_error.js';
+import { RequestRefusedError } from './types.js';
 import { parseSSEEvents } from './sse.js';
 import { buildOpenAIMessages, buildOpenAIToolDefs } from './openai_format.js';
 import { isKimiModel } from './kimi_params.js';
 import { runtimeDiag } from '../../utils/debug_log.js';
 import { createZrouterEventMapper } from './zrouter_events.js';
 import { parseTokenUsage } from './token_usage.js';
-import { DEEPSEEK_FLASH_MAX_OUTPUT, isModalDeepSeekFlashModel, MODAL_DEEPSEEK_FLASH_MAX_OUTPUT, isDeepSeekFlashModel } from '../../utils/deepseek.js';
+import { clampCompletionTokens } from '../../utils/deepseek.js';
 import { getVersion } from '../../utils/version.js';
-import { isTransportError } from './transport_errors.js';
+import { IncompleteStreamError, isTransportError } from './transport_errors.js';
+import { OpenAIResponsesBackend } from './openai_responses.js';
 const ZROUTER_HEADERS_TIMEOUT_MS = 90_000;
 // A process session is descriptive telemetry, never a registered machine identity.
 const routerClientSession = randomUUID();
@@ -48,6 +50,26 @@ function resolveReconnectPolicy() {
         capMs: envBoundedInt('ZTC_ROUTER_RECONNECT_CAP_MS', DEFAULT_RECONNECT_CAP_MS, 0, MAX_RECONNECT_MS),
     };
 }
+/**
+ * The limits as Router's fields: the model's price caps (OpenRouter applies
+ * them) and fixed speed, and the profile's shares of providers to beat, which
+ * Router turns into speed figures, its uptime and whether speed is required.
+ */
+function routerLimits(profile, model) {
+    const { maxInputPrice: prompt, maxOutputPrice: completion, minThroughput, maxLatency } = model ?? {};
+    const { fasterThan, quickerThan, minUptime, requireSpeed } = profile ?? {};
+    return {
+        ...(prompt === undefined && completion === undefined ? {} : { max_price: {
+                ...(prompt === undefined ? {} : { prompt }), ...(completion === undefined ? {} : { completion })
+            } }),
+        ...(minThroughput === undefined ? {} : { min_throughput: minThroughput }),
+        ...(maxLatency === undefined ? {} : { max_latency: maxLatency }),
+        ...(fasterThan === undefined ? {} : { faster_than: fasterThan }),
+        ...(quickerThan === undefined ? {} : { quicker_than: quickerThan }),
+        ...(minUptime === undefined ? {} : { min_uptime: minUptime }),
+        ...(requireSpeed ? { require_speed: true } : {}),
+    };
+}
 /**
  * Backend that streams LLM responses through ZRouter proxy.
  *
@@ -56,6 +78,7 @@ function resolveReconnectPolicy() {
  * uses the unified chat endpoint so routing can fall back across providers.
  */
 export class ZRouterStreamBackend {
+    preservesNativeHistory;
     initialCatalog;
     get catalog() {
         return readRouterCatalog({ origin: this.proxyUrl, token: this.apiKey, workspaceId: this.workspaceId }) ?? this.initialCatalog;
@@ -67,7 +90,9 @@ export class ZRouterStreamBackend {
     workspaceId;
     conversationId;
     clientName;
+    openRouterPreferences;
     constructor(config) {
+        this.preservesNativeHistory = config.provider === 'openai' && (config.model === 'gpt-6.1-sol' || process.env.ZTC_ROUTER_REQUIRED === '1');
         this.initialCatalog = config.catalog ? structuredClone(config.catalog) : undefined;
         this.apiKey = config.apiKey;
         this.proxyUrl = config.proxyUrl.replace(/\/+$/, '');
@@ -76,6 +101,7 @@ export class ZRouterStreamBackend {
         this.workspaceId = normalizeHeaderValue(config.workspaceId, 'workspace id', 128);
         this.conversationId = normalizeHeaderValue(config.conversationId, 'conversation id', 128);
         this.clientName = normalizeHeaderValue(config.clientName ?? 'ztc', 'client name', 64);
+        this.openRouterPreferences = config.openRouterPreferences;
     }
     endpointFor() {
         return `${this.proxyUrl}/v1/chat/completions`;
@@ -89,6 +115,62 @@ export class ZRouterStreamBackend {
     handlesTransportRetries() {
         return true;
     }
+    allowsRequestRetryAfterFailure(request) {
+        return !this.usesNativeResponses(request);
+    }
+    usesNativeResponses(request) {
+        if (process.env.ZTC_ROUTER_REQUIRED === '1' && (this.provider !== 'openai' || request.model !== 'gpt-6.1-sol'
+            || request.routePlan?.allow_fallbacks || request.routePlan?.fallbacks.length)) {
+            throw new Error('Required Router profile permits only openai/gpt-6.1-sol without fallbacks');
+        }
+        return this.provider === 'openai' && request.model === 'gpt-6.1-sol';
+    }
+    async nativeResponses(request, fetcher) {
+        const contract = modelContract('openai', request.model);
+        const effort = request.codexEffort ?? 'low';
+        if (process.env.ZTC_ROUTER_REQUIRED === '1' && (effort !== 'low' || request.codexFastMode)) {
+            throw new Error('Required Router profile permits only low reasoning and standard processing');
+        }
+        if (!contract?.reasoningEfforts.includes(effort))
+            throw new Error('Unsupported reasoning effort for Router Sol Responses');
+        if (request.maxTokens !== undefined && (!Number.isSafeInteger(request.maxTokens) || request.maxTokens < 1
+            || request.maxTokens > (contract.maxOutputTokens?.max ?? 0)))
+            throw new Error('Invalid Router Sol output token limit');
+        if (request.routePlan?.allow_fallbacks || request.routePlan?.fallbacks.length)
+            throw new Error('Router Sol Responses does not allow fallback routing');
+        const timeoutMs = Math.min(300_000, Math.max(1, request.timeoutMs ?? 180_000));
+        const controller = new AbortController();
+        const signal = request.signal ? AbortSignal.any([request.signal, controller.signal]) : controller.signal;
+        const timer = setTimeout(() => controller.abort(new Error('Router Responses request deadline exceeded')), timeoutMs);
+        timer.unref();
+        try {
+            const headers = await this.buildHeaders(request);
+            headers['X-Zerg-Request-Timeout-Ms'] = String(timeoutMs);
+            return { request: { ...request, signal, codexEffort: effort }, dispose: () => clearTimeout(timer),
+                backend: new OpenAIResponsesBackend({ apiKey: '', baseUrl: `${this.proxyUrl}/v1`, extraHeaders: headers, fetcher,
+                    preserveNativeHistory: true, reasoningFromRequestOnly: true, extraBody: { provider: 'openai', store: false, include: ['reasoning.encrypted_content'] } }) };
+        }
+        catch (error) {
+            clearTimeout(timer);
+            throw error;
+        }
+    }
+    /**
+     * Stop the provider stream of an abandoned turn. Without it Router keeps
+     * producing until the response ends. Router then has no provider usage
+     * report, so the request settles as incomplete: use it only for responses
+     * that would otherwise run to their output limit.
+     */
+    async cancelTurn(request) {
+        if (!request.transportTurnId)
+            return;
+        const headers = await this.buildHeaders(request);
+        const response = await fetch(`${this.proxyUrl}/v1/chat/turns/cancel`, {
+            method: 'POST', headers: { ...headers, 'X-Zerg-Turn-ID': request.transportTurnId },
+            signal: AbortSignal.timeout(10_000),
+        });
+        await response.body?.cancel();
+    }
     getModelCapabilities(model) {
         return this.catalog?.version === 1
             ? resolveRouterModel(this.catalog, this.provider, model)?.capabilities : undefined;
@@ -97,21 +179,39 @@ export class ZRouterStreamBackend {
         if (this.catalog?.version === 1) {
             const descriptor = resolveRouterModel(this.catalog, this.provider, request.model);
             if (!descriptor?.capabilities?.chat)
-                throw new Error('This model is no longer in the Router chat catalog. Refresh /model.');
+                throw new RequestRefusedError('This model is no longer in the Router chat catalog. Refresh /model.');
             const caps = descriptor.capabilities;
             if (request.codexEffort && caps.reasoning && !caps.reasoning.choices.includes(request.codexEffort)) {
-                throw new Error(`Unsupported reasoning effort: ${request.codexEffort}`);
+                throw new RequestRefusedError(`Unsupported reasoning effort: ${request.codexEffort}`);
             }
             if (request.maxTokens !== undefined && caps.max_output_tokens !== undefined && request.maxTokens > caps.max_output_tokens) {
-                throw new Error(`Max output tokens exceeds the advertised limit (${caps.max_output_tokens}).`);
+                throw new RequestRefusedError(`Max output tokens exceeds the advertised limit (${caps.max_output_tokens}).`);
+            }
+            const media = caps.images === false ? request.messages.flatMap(message => Array.isArray(message.content)
+                ? message.content.filter(block => block.type === 'image' || block.type === 'video') : [])[0] : undefined;
+            if (media) {
+                const [kind, item] = media.type === 'image' ? ['images', 'image'] : ['video', 'video'];
+                throw new RequestRefusedError(`${descriptor.display_name ?? request.model} does not take ${kind}. `
+                    + `Choose a model that does with /model, or send the message without the ${item}.`);
             }
-            if (caps.images === false && request.messages.some(message => Array.isArray(message.content)
-                && message.content.some(block => block.type === 'image' || block.type === 'video')))
-                throw new Error('This model does not support images.');
             const prepared = caps.tools === false ? chatOnlyRequest(request) : request;
-            return { provider: descriptor.owned_by, model: descriptor.id,
+            const outputLimit = clampCompletionTokens(request.model, request.maxTokens)
+                ?? clampCompletionTokens(request.model, caps.max_output_tokens);
+            const openRouter = descriptor.owned_by === 'openrouter' ? this.openRouterPreferences?.() : undefined;
+            const pinned = openRouter?.providers?.[descriptor.id];
+            // OpenRouter's routing variants; free models have none, and a provider pinned for the model replaces them.
+            const variant = openRouter?.variant && !pinned && !descriptor.id.endsWith(':free') ? `:${openRouter.variant}` : '';
+            const routing = openRouter && { ...(openRouter.zdr ? { zdr: true } : {}),
+                ...(openRouter.quantizations?.length ? { quantizations: openRouter.quantizations } : {}),
+                // A variant is its own sort.
+                ...(openRouter.sort && !variant ? { sort: openRouter.sort } : {}),
+                ...(openRouter.dataCollection ? { data_collection: openRouter.dataCollection } : {}),
+                ...(pinned ? { provider: pinned.tag, fallbacks: pinned.fallbacks } : {}),
+                ...routerLimits(openRouter.limits, openRouter.modelLimits?.[descriptor.id]) };
+            return { provider: descriptor.owned_by, model: `${descriptor.id}${variant}`,
+                ...(routing && Object.keys(routing).length ? { openrouter: routing } : {}),
                 ...(request.routePlan ? { route: request.routePlan } : {}),
-                ...(request.maxTokens === undefined ? {} : { max_output_tokens: request.maxTokens }),
+                ...(outputLimit === undefined ? {} : { max_output_tokens: outputLimit }),
                 ...(caps.reasoning && request.codexEffort ? { reasoning_effort: request.codexEffort } : {}),
                 messages: buildOpenAIMessages(prepared),
                 ...(prepared.tools.length ? { tools: buildOpenAIToolDefs(prepared.tools) } : {}),
@@ -135,10 +235,9 @@ export class ZRouterStreamBackend {
             || /^gpt-5/.test(request.model)
             || isKimiModel(request.model);
         const isGpt4o = request.model.startsWith('gpt-4o');
-        const limit = isGpt4o ? 16384
-            : isModalDeepSeekFlashModel(request.model) ? MODAL_DEEPSEEK_FLASH_MAX_OUTPUT
-                : isDeepSeekFlashModel(request.model) ? DEEPSEEK_FLASH_MAX_OUTPUT : Infinity;
-        const effectiveMaxTokens = request.maxTokens === undefined ? undefined : Math.min(request.maxTokens, limit);
+        const reviewedLimit = modelContract(this.provider, request.model)?.maxOutputTokens?.max;
+        const limit = reviewedLimit ?? (isGpt4o ? 16384 : Infinity);
+        const effectiveMaxTokens = clampCompletionTokens(request.model, request.maxTokens === undefined ? undefined : Math.min(request.maxTokens, limit));
         const tokenParam = effectiveMaxTokens === undefined ? {} : useCompletionTokens
             ? { max_completion_tokens: effectiveMaxTokens }
             : { max_tokens: effectiveMaxTokens };
@@ -241,6 +340,15 @@ export class ZRouterStreamBackend {
         return measureResponse(routedRequest, fetcher => this.generateResponse(routedRequest, fetcher));
     }
     async generateResponse(request, fetcher) {
+        if (this.usesNativeResponses(request)) {
+            const native = await this.nativeResponses(request, fetcher);
+            try {
+                return await native.backend.generate(native.request);
+            }
+            finally {
+                native.dispose();
+            }
+        }
         const body = this.serializeBody(request);
         const headers = await this.buildHeaders(request);
         // Proof-chain log: the exact router endpoint + model this turn dispatches to.
@@ -314,11 +422,25 @@ export class ZRouterStreamBackend {
         return measureStream(routedRequest, fetcher => this.streamResponse(routedRequest, fetcher));
     }
     async *streamResponse(request, fetcher) {
+        if (this.usesNativeResponses(request)) {
+            const native = await this.nativeResponses(request, fetcher);
+            try {
+                yield* native.backend.generateStream(native.request);
+            }
+            finally {
+                native.dispose();
+            }
+            return;
+        }
         const body = this.serializeBody(request, true);
         const mapEvent = createZrouterEventMapper();
         let resumeAfter;
         let emittedMappedEvent = false;
+        let sawTerminalEvent = false;
         let resumeSupported = false;
+        // Router appends a router_error as the turn's last event and ends the turn,
+        // so a resume past it replays nothing: report the error instead.
+        let routerTurnEnded = false;
         const policy = resolveReconnectPolicy();
         let reconnectStarted;
         const budget = () => resumeAfter ? 300_000 : 30_000;
@@ -336,7 +458,7 @@ export class ZRouterStreamBackend {
                 }, Math.min(ZROUTER_HEADERS_TIMEOUT_MS, Math.max(1, remaining())));
                 if (!response.ok) {
                     const failure = await readHttpErrorBody(response, request.signal);
-                    const error = new BackendHttpError(response.status, failure.body, { prefix: 'ZRouter API', headers,
+                    const error = new BackendHttpError(response.status, routerErrorFrameBody(failure.body), { prefix: 'ZRouter API', headers,
                         bodyReadState: failure.bodyReadState, retryAfter: response.headers.get('retry-after'),
                         rateLimitReset: response.headers.get('x-ratelimit-reset') });
                     error.message += failureHeaderSuffix(response);
@@ -368,6 +490,7 @@ export class ZRouterStreamBackend {
                         const status = Number.isInteger(suppliedStatus) && suppliedStatus >= 400 && suppliedStatus <= 599
                             ? suppliedStatus
                             : 502;
+                        routerTurnEnded = true;
                         throw new BackendHttpError(status, JSON.stringify(ev.body ?? {}), { prefix: 'ZRouter API', headers });
                     }
                     const mapped = mapEvent(ev);
@@ -380,11 +503,16 @@ export class ZRouterStreamBackend {
                         // stays eligible for the reconnect below without Router resume.
                         if (mapped.some(event => event.type !== 'heartbeat'))
                             emittedMappedEvent = true;
+                        if (mapped.some(event => event.type === 'done'))
+                            sawTerminalEvent = true;
                         if (!validEventId)
                             resumeSupported = false;
                     }
                     yield* mapped;
                 }
+                if (!sawTerminalEvent) {
+                    throw new IncompleteStreamError();
+                }
                 return;
             }
             catch (error) {
@@ -393,9 +521,9 @@ export class ZRouterStreamBackend {
                 // emitted output. So a transient HTTP failure on a resume (the Router's
                 // coordination 503 while its shared store blips, a gateway 502/504) is
                 // retryable here, not just a raw socket error.
-                const retryable = error instanceof BackendHttpError
+                const retryable = !routerTurnEnded && (error instanceof BackendHttpError
                     ? resumeAfter !== undefined && isRetryableResumeStatus(error)
-                    : isTransportError(error);
+                    : isTransportError(error));
                 if (request.signal?.aborted
                     || !retryable
                     || (emittedMappedEvent && (!resumeSupported || !resumeAfter))) {
@@ -493,6 +621,23 @@ function failureHeaderSuffix(response) {
     }
     return parts.length > 0 ? ` [${parts.join(' ')}]` : '';
 }
+/**
+ * A failed streamed turn can answer with an SSE router_error frame instead of a JSON body. Its body is the same error
+ * the stream path reports, so callers read Router's code and message either way: the frame alone left only "Rate
+ * limit exceeded" on screen (2026-10-27). Any other body passes through unchanged.
+ */
+function routerErrorFrameBody(body) {
+    const frame = /^(?:id: [^\n]*\n)?data: (\{.*\})\s*$/s.exec(body);
+    if (!frame)
+        return body;
+    try {
+        const event = JSON.parse(frame[1]);
+        return event.type === 'router_error' && event.body !== undefined ? JSON.stringify(event.body) : body;
+    }
+    catch {
+        return body;
+    }
+}
 /**
  * True for a `ZRouter API error (NNN)` a resume is worth retrying: a gateway or
  * rate-limit failure that is expected to clear. Kept separate from

package/dist/agent/background_workers.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Workers a lead started in the background (delegate_task `background: true`)
+ * and supervises. Each worker's report waits here until the lead's next
+ * request, where it joins the conversation once, or until the lead collects it.
+ * While workers run the lead gets a progress check every check interval: their
+ * steps, recent actions and milestone notes, so it can steer a worker that is
+ * off track or stop one it no longer needs. Workers still running when the
+ * lead's run ends are stopped.
+ */
+export interface WorkerReport {
+    id: string;
+    task: string;
+    report: string;
+}
+/** What a running worker's job sees of its supervision. */
+export interface WorkerControl {
+    signal: AbortSignal;
+    /** A milestone note for the lead's next progress check. */
+    note(text: string): void;
+    /** One worker step. */
+    step(): void;
+    /** A tool the worker called. */
+    tool(name: string): void;
+    /** Messages from the lead not yet delivered to the worker. */
+    takeMessages(): string[];
+}
+/** Background workers that may run at once; each can run shell commands for up to an hour. */
+export declare const MAX_RUNNING_WORKERS = 4;
+export declare class BackgroundWorkers {
+    private readonly checkIntervalMs;
+    private readonly now;
+    private readonly running;
+    private ready;
+    private nextId;
+    private lastCheckAt;
+    /** A worker started, posted a milestone note or finished since the last check the lead saw. */
+    private news;
+    constructor(checkIntervalMs?: number, now?: () => number);
+    /** Workers that can start before the cap is reached. */
+    room(): number;
+    /** Starts `run` and returns the worker's id; its report (or failure) becomes ready when it settles. */
+    start(task: string, run: (control: WorkerControl) => Promise<string>): string;
+    /** Reports that arrived since the last call, in arrival order. */
+    takeReady(): WorkerReport[];
+    /**
+     * The running workers' progress, for the lead to supervise. A check the lead
+     * asks for with nothing new since the last one answers in one line.
+     */
+    progress(asked?: boolean): string;
+    /** The progress check, when workers are running and a check interval has passed since the last one. */
+    takeDueCheck(): string | null;
+    /**
+     * Waits for every running worker, or for the next progress check if that
+     * comes first, and returns the reports not yet handed over and the check.
+     */
+    collect(): Promise<{
+        reports: WorkerReport[];
+        check: string | null;
+    }>;
+    /** Delivers `message` to a running worker before its next step; false when it is not running. */
+    steer(id: string, message: string): boolean;
+    /** Stops one running worker; false when it is not running. */
+    stop(id: string): boolean;
+    /** Stops every running worker; their results are dropped. */
+    stopAll(): void;
+}
+/** Reports as the lead reads them. */
+export declare function formatWorkerReports(reports: readonly WorkerReport[]): string;

package/dist/agent/background_workers.js

@@ -0,0 +1,139 @@
+/**
+ * Workers a lead started in the background (delegate_task `background: true`)
+ * and supervises. Each worker's report waits here until the lead's next
+ * request, where it joins the conversation once, or until the lead collects it.
+ * While workers run the lead gets a progress check every check interval: their
+ * steps, recent actions and milestone notes, so it can steer a worker that is
+ * off track or stop one it no longer needs. Workers still running when the
+ * lead's run ends are stopped.
+ */
+const RECENT_TOOLS = 6;
+/** Background workers that may run at once; each can run shell commands for up to an hour. */
+export const MAX_RUNNING_WORKERS = 4;
+export class BackgroundWorkers {
+    checkIntervalMs;
+    now;
+    running = new Map();
+    ready = [];
+    nextId = 1;
+    lastCheckAt = 0;
+    /** A worker started, posted a milestone note or finished since the last check the lead saw. */
+    news = false;
+    constructor(checkIntervalMs = 600_000, now = Date.now) {
+        this.checkIntervalMs = checkIntervalMs;
+        this.now = now;
+    }
+    /** Workers that can start before the cap is reached. */
+    room() {
+        return MAX_RUNNING_WORKERS - this.running.size;
+    }
+    /** Starts `run` and returns the worker's id; its report (or failure) becomes ready when it settles. */
+    start(task, run) {
+        if (this.room() <= 0)
+            throw new Error(`at most ${MAX_RUNNING_WORKERS} background workers run at once`);
+        const id = `w${this.nextId++}`;
+        const controller = new AbortController();
+        if (this.running.size === 0)
+            this.lastCheckAt = this.now();
+        this.news = true;
+        const worker = { task, controller, done: Promise.resolve(), startedAt: this.now(), steps: 0,
+            recentTools: [], notes: [], inbox: [] };
+        const settle = (report) => {
+            // A stopped worker's late result is dropped.
+            if (this.running.delete(id)) {
+                this.ready.push({ id, task, report });
+                this.news = true;
+            }
+        };
+        worker.done = run({
+            signal: controller.signal,
+            note: text => { worker.notes.push(text); this.news = true; },
+            step: () => { worker.steps++; },
+            tool: name => { worker.recentTools = [...worker.recentTools, name].slice(-RECENT_TOOLS); },
+            takeMessages: () => worker.inbox.splice(0),
+        }).then(settle, (error) => settle(`Worker failed: ${error instanceof Error ? error.message : String(error)}`));
+        this.running.set(id, worker);
+        return id;
+    }
+    /** Reports that arrived since the last call, in arrival order. */
+    takeReady() {
+        const reports = this.ready;
+        this.ready = [];
+        return reports;
+    }
+    /**
+     * The running workers' progress, for the lead to supervise. A check the lead
+     * asks for with nothing new since the last one answers in one line.
+     */
+    progress(asked = false) {
+        if (this.running.size === 0)
+            return '[Progress check] No workers are running.';
+        const next = `The next check arrives on its own in ${Math.round(this.checkIntervalMs / 60_000)} min.`;
+        if (asked && !this.news) {
+            const steps = [...this.running].map(([id, worker]) => `${id}: ${worker.steps} step${worker.steps === 1 ? '' : 's'}`);
+            return `[Progress check] No new milestone notes since the last check. ${steps.join(', ')}. ${next} `
+                + 'Keep working on your own part, or collect to wait for reports.';
+        }
+        const lines = [`[Progress check] ${this.running.size} worker${this.running.size === 1 ? '' : 's'} running`];
+        for (const [id, worker] of this.running) {
+            const minutes = Math.round((this.now() - worker.startedAt) / 60_000);
+            lines.push(`- ${id} (${minutes} min, ${worker.steps} step${worker.steps === 1 ? '' : 's'}): ${worker.task.split('\n')[0].slice(0, 160)}`);
+            if (worker.notes.length > 0)
+                lines.push(`  latest note: ${worker.notes.at(-1)}`);
+            if (worker.recentTools.length > 0)
+                lines.push(`  recent tools: ${worker.recentTools.join(', ')}`);
+        }
+        lines.push('Steer a worker that is off track, inefficient or repeating failures (delegate_task steer), stop one you no '
+            + `longer need (stop), and keep working. ${next}`);
+        this.lastCheckAt = this.now();
+        this.news = false;
+        return lines.join('\n');
+    }
+    /** The progress check, when workers are running and a check interval has passed since the last one. */
+    takeDueCheck() {
+        if (this.running.size === 0 || this.now() - this.lastCheckAt < this.checkIntervalMs)
+            return null;
+        return this.progress();
+    }
+    /**
+     * Waits for every running worker, or for the next progress check if that
+     * comes first, and returns the reports not yet handed over and the check.
+     */
+    async collect() {
+        const all = Promise.all([...this.running.values()].map(worker => worker.done));
+        if (this.running.size > 0) {
+            const wait = Math.max(0, this.lastCheckAt + this.checkIntervalMs - this.now());
+            let timer;
+            await Promise.race([all, new Promise(resolve => { timer = setTimeout(resolve, wait); })]);
+            clearTimeout(timer);
+        }
+        return { reports: this.takeReady(), check: this.takeDueCheck() };
+    }
+    /** Delivers `message` to a running worker before its next step; false when it is not running. */
+    steer(id, message) {
+        const worker = this.running.get(id);
+        if (!worker)
+            return false;
+        worker.inbox.push(message);
+        return true;
+    }
+    /** Stops one running worker; false when it is not running. */
+    stop(id) {
+        const worker = this.running.get(id);
+        if (!worker)
+            return false;
+        worker.controller.abort();
+        this.running.delete(id);
+        return true;
+    }
+    /** Stops every running worker; their results are dropped. */
+    stopAll() {
+        for (const worker of this.running.values())
+            worker.controller.abort();
+        this.running.clear();
+    }
+}
+/** Reports as the lead reads them. */
+export function formatWorkerReports(reports) {
+    return ['[Worker reports]', ...reports.map(({ id, task, report }) => `### ${id}: ${task.split('\n')[0]}\n\n${report}`)].join('\n\n');
+}

package/dist/agent/commands/accounts.d.ts

@@ -9,11 +9,19 @@
  *   /accounts login <id>      run the official CLI login at the account's dir
  *   /accounts remove <id>     drop an account from the pool
  */
-import { Command } from './types.js';
+import { Command, CommandContext } from './types.js';
 /**
  * The account list is written into the transcript, which is saved and mirrored
  * to every viewer, so the ChatGPT email appears masked: enough to tell two
  * logins apart, not enough to publish the address.
  */
 export declare function maskAccountEmail(email: string | undefined): string | undefined;
+/**
+ * The account manager opened from the settings panel: Escape hands the user
+ * back to `onBack` (the panel) instead of the transcript.
+ */
+export declare function openAccountsManager(ctx: CommandContext, options?: {
+    focus?: string;
+    onBack?: () => void;
+}): Promise<void>;
 export declare const accountsCommand: Command;