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

package/dist/app/workspace_presets.js

@@ -0,0 +1,192 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+import { buildZtcPaneLaunchCommand, createZtcLaunchSpec } from '../panes/ztc_launch.js';
+const defaults = { main: 'Main', decisions: 'Decisions', status: 'Status', worker: 'Worker' };
+const isRecord = (value) => value !== null
+    && typeof value === 'object' && !Array.isArray(value);
+function integer(value, max, field) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > max) {
+        throw new Error(`${field} must be an integer from 1 to ${max}`);
+    }
+    return value;
+}
+export function loadWorkspacePreset(cwd, name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name)) {
+        throw new Error('Layout name must contain 1–64 letters, digits, underscores or hyphens.');
+    }
+    let data;
+    let filename;
+    if (['orchestrator', 'pair', 'grid'].includes(name))
+        data = { schema_version: 1, template: name };
+    else {
+        filename = join(cwd, '.ztc', 'layouts', `${name}.yaml`);
+        try {
+            const bytes = readFileSync(filename);
+            if (bytes.length > 65536)
+                throw new Error('Layout YAML exceeds 64 KiB');
+            const document = parseDocument(bytes.toString('utf8'), { uniqueKeys: true });
+            if (document.errors.length)
+                throw new Error(document.errors[0].message);
+            const parsed = document.toJS({ maxAliasCount: 20 });
+            if (!isRecord(parsed))
+                throw new Error('Layout must be a YAML object');
+            data = parsed;
+        }
+        catch (error) {
+            throw new Error(`${filename}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    try {
+        for (const key of Object.keys(data)) {
+            if (!['schema_version', 'template', 'workers', 'refresh_ms', 'titles'].includes(key))
+                throw new Error(`Unknown layout field: ${key}`);
+        }
+        if (data.schema_version !== 1)
+            throw new Error('schema_version must be 1');
+        if (typeof data.template !== 'string' || !['orchestrator', 'pair', 'grid'].includes(data.template))
+            throw new Error('template must be orchestrator, pair, or grid');
+        const template = data.template;
+        const workers = integer(data.workers === undefined ? (template === 'grid' ? 4 : 1) : data.workers, 32, 'workers');
+        if (template !== 'grid' && data.workers !== undefined)
+            throw new Error('workers is only configurable for grid');
+        const refresh_ms = integer(data.refresh_ms === undefined ? 600000 : data.refresh_ms, 86400000, 'refresh_ms');
+        const titles = { ...defaults };
+        if (data.titles !== undefined) {
+            if (!isRecord(data.titles))
+                throw new Error('titles must be an object');
+            for (const [key, value] of Object.entries(data.titles)) {
+                if (!Object.hasOwn(defaults, key))
+                    throw new Error(`Unknown title field: ${key}`);
+                if (typeof value !== 'string' || !value.trim() || value.length > 80 || /[\x00-\x1f\x7f]/.test(value))
+                    throw new Error(`titles.${key} must be 1–80 printable characters`);
+                titles[key] = value;
+            }
+        }
+        return { template, workers, refresh_ms, titles };
+    }
+    catch (error) {
+        throw new Error(`${filename ? `${filename}: ` : ''}${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function buildWorkspaceMonitorLaunch(mode, host, preset) {
+    const entry = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './workspace_monitor.ts' : './workspace_monitor.js', import.meta.url));
+    const loader = import.meta.url.endsWith('.ts') ? ['--import', import.meta.resolve('tsx')] : [];
+    return { kind: 'process', command: process.execPath,
+        args: [...loader, entry, mode, String(host.mirrorPort), host.workspaceOwnerId, String(preset.refresh_ms)],
+        cwd: host.cwd, title: preset.titles[mode], paneType: 'process' };
+}
+const leaves = (node) => node.type === 'leaf' ? [node.pane_id]
+    : [...leaves(node.first), ...leaves(node.second)];
+/** Creates only new panes; authored processes in an earlier window remain running. */
+export async function openWorkspacePreset(transport, host, args) {
+    const name = args[0];
+    const preset = loadWorkspacePreset(host.cwd, name);
+    for (let index = 1; index < args.length; index += 2) {
+        const flag = args[index];
+        const raw = args[index + 1];
+        if (!raw || !/^\d+$/.test(raw))
+            throw new Error(`${flag} requires a positive integer`);
+        if (flag === '--workers' && preset.template === 'grid')
+            preset.workers = integer(Number(raw), 32, 'workers');
+        else if (flag === '--refresh-ms' && preset.template === 'orchestrator')
+            preset.refresh_ms = integer(Number(raw), 86400000, 'refresh_ms');
+        else
+            throw new Error(`Unsupported layout option: ${flag}`);
+    }
+    // Build every command before altering native state, including loader/runtime checks.
+    const specs = preset.template === 'orchestrator'
+        ? [buildWorkspaceMonitorLaunch('decisions', host, preset), buildWorkspaceMonitorLaunch('status', host, preset)]
+        : Array.from({ length: preset.template === 'pair' ? 1 : preset.workers }, (_, index) => createZtcLaunchSpec({
+            cwd: host.cwd, title: `${preset.titles.worker} ${index + 1}`,
+            providerOverride: host.providerOverride, modelOverride: host.modelOverride,
+        }));
+    const commands = specs.map(spec => {
+        if (spec.kind === 'ztc') {
+            const built = buildZtcPaneLaunchCommand(spec, host.argv);
+            if (built instanceof Error)
+                throw built;
+            return built;
+        }
+        if (spec.kind !== 'process')
+            throw new Error('Invalid preset process');
+        return spec;
+    });
+    const send = (command) => {
+        if (host.isActive && !host.isActive())
+            throw new Error('Workspace is closing; layout creation cancelled.');
+        if (!transport.send(command))
+            throw new Error(`Workspace renderer rejected ${command.type}`);
+    };
+    const request = (command, match) => new Promise((resolve, reject) => {
+        let unsubscribe = () => { };
+        const timeout = setTimeout(() => { unsubscribe(); reject(new Error(`Workspace renderer did not acknowledge ${command.type}`)); }, 8000);
+        unsubscribe = transport.on(event => {
+            if (event.type !== 'error' && !match(event))
+                return;
+            clearTimeout(timeout);
+            unsubscribe();
+            if (event.type === 'error')
+                reject(new Error(event.message));
+            else
+                resolve(event);
+        });
+        try {
+            send(command);
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            unsubscribe();
+            reject(error);
+        }
+    });
+    const snapshot = async () => {
+        const event = await request({ type: 'get_session_state' }, event => event.type === 'session_state');
+        if (event.type !== 'session_state')
+            throw new Error('Unexpected workspace snapshot');
+        return event.state;
+    };
+    const initial = await snapshot();
+    const rootWindow = initial.windows?.find(window => leaves(window.layout).includes(0));
+    const rootWindowId = rootWindow?.id ?? initial.active_window_id ?? 0;
+    const rootLeaves = leaves(rootWindow?.layout ?? initial.layout);
+    if (!rootLeaves.includes(0))
+        throw new Error('Main is unavailable in this workspace');
+    send({ type: 'switch_window', window_id: rootWindowId });
+    let windowId = rootWindowId;
+    const created = [];
+    for (let index = 0; index < specs.length; index++) {
+        const spec = specs[index];
+        const command = commands[index];
+        const requestId = randomUUID();
+        host.trackLaunch(requestId, spec);
+        const event = await request({ type: 'create_pane', request_id: requestId, command: command.command,
+            args: command.args, cwd: command.cwd, title: spec.title, pane_type: spec.kind === 'ztc' ? 'ztc' : 'process',
+            env: host.env, target: index === 0 ? 0 : created.at(-1),
+            new_window: index === 0 && rootLeaves.length > 1 }, event => event.type === 'pane_created' && event.request_id === requestId);
+        if (event.type !== 'pane_created')
+            throw new Error('Unexpected pane creation response');
+        // A preset name is authored workspace state, independent of child inference.
+        send({ type: 'set_pane_title', pane_id: event.pane_id, title: spec.title, source: 'manual' });
+        created.push(event.pane_id);
+        if (index === 0 && rootLeaves.length > 1) {
+            windowId = (await snapshot()).active_window_id ?? rootWindowId;
+            send({ type: 'set_pane_window', pane_id: 0, window_id: windowId });
+        }
+        else {
+            send({ type: 'set_pane_window', pane_id: event.pane_id, window_id: windowId });
+        }
+        send({ type: 'focus_pane', pane_id: event.pane_id });
+    }
+    send({ type: 'set_pane_title', pane_id: 0, title: preset.titles.main });
+    send({ type: 'focus_pane', pane_id: 0 });
+    send({ type: 'set_layout', layout: preset.template === 'orchestrator' ? 'main_and_stack' : preset.template === 'pair' ? 'columns' : 'grid' });
+    const final = await snapshot();
+    const actual = leaves(final.layout);
+    if (actual.length !== created.length + 1 || ![0, ...created].every(id => actual.includes(id))) {
+        throw new Error(`Renderer layout contains panes ${actual.join(', ')}; expected ${[0, ...created].join(', ')} in window ${windowId}. Created panes are retained for inspection.`);
+    }
+    return `Opened layout ${JSON.stringify(name)}. ${preset.template === 'orchestrator' ? `Status uses runtime observations; refresh every ${preset.refresh_ms} ms or press r.` : `${created.length} new worker${created.length === 1 ? '' : 's'}.`}`;
+}

package/dist/attention/queue.d.ts

@@ -0,0 +1,37 @@
+import type { MirrorEvent, MirrorPaneRecord } from '../web/mirror_stream.js';
+export type AttentionKind = 'question' | 'approval' | 'prompt' | 'blocked' | 'failed' | 'review' | 'stale';
+export interface AttentionItem {
+    id: string;
+    requestId: string;
+    kind: AttentionKind;
+    paneId: number;
+    sessionId: string;
+    agent: string;
+    task: string;
+    blocker: string;
+    createdAt: string;
+    primaryAction: 'answer' | 'approve' | 'inspect';
+    /** Live request facts let a reconnecting view restore the actual prompt. */
+    request?: MirrorEvent;
+    requestPreviewUnavailable?: boolean;
+}
+export interface AttentionSnapshot {
+    items: AttentionItem[];
+    total: number;
+}
+/** Canonical pending-request and attention state, shared by terminal and views. */
+export declare class AttentionQueue {
+    private items;
+    private settings;
+    private tasks;
+    observe(event: MirrorEvent, pane?: MirrorPaneRecord): void;
+    snapshot(limit?: number, offset?: number): AttentionSnapshot;
+    find(id: string): AttentionItem | undefined;
+    findRequest(kind: AttentionKind, requestId: string, paneId: number): AttentionItem | undefined;
+    hasSettings(requestId: string, paneId: number): boolean;
+    closeSettings(requestId: string, paneId: number): void;
+    markStale(paneId: number): void;
+    resolve(id: string): AttentionItem | undefined;
+    private clearSignals;
+    private clearPane;
+}

package/dist/attention/queue.js

@@ -0,0 +1,183 @@
+const bounded = (value, fallback = '') => typeof value === 'string'
+    ? value.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '').slice(0, 500) : fallback;
+const identity = (value) => {
+    if (typeof value !== 'string' || value.length > 4096 || /[\x00-\x1f\x7f]/.test(value))
+        return '';
+    return value;
+};
+const rank = { approval: 0, question: 1, prompt: 2, failed: 3, blocked: 4, review: 5, stale: 6 };
+const requestKinds = new Set(['question', 'approval', 'prompt']);
+const maxPreviewBytes = 64 * 1024;
+/** Canonical pending-request and attention state, shared by terminal and views. */
+export class AttentionQueue {
+    items = new Map();
+    settings = new Set();
+    tasks = new Map();
+    observe(event, pane) {
+        const data = event.data;
+        const paneId = typeof data.pane_id === 'number' ? data.pane_id : 0;
+        const sessionId = bounded(data.origin_session_id);
+        if (event.type === 'message' && data.role === 'user') {
+            const metadata = data.metadata;
+            if (!metadata?.isAskUserAnswer)
+                this.tasks.set(paneId, bounded(data.content));
+            return;
+        }
+        if (event.type === 'pane_info' && Array.isArray(data.panes)) {
+            for (const entry of data.panes) {
+                if (typeof entry.pane_id === 'number' && entry.is_alive === false)
+                    this.markStale(entry.pane_id);
+            }
+            return;
+        }
+        if (event.type === 'widget_settings') {
+            const widgetId = identity(data.widget_id);
+            if (widgetId)
+                this.settings.add(`${paneId}:${widgetId}`);
+            return;
+        }
+        if (event.type === 'attention_resolved') {
+            if (typeof data.id === 'string')
+                this.items.delete(data.id);
+            return;
+        }
+        if (event.type === 'widget_dismiss') {
+            if (typeof data.widget_id === 'string')
+                this.settings.delete(`${paneId}:${data.widget_id}`);
+            for (const item of this.items.values()) {
+                if (item.paneId === paneId && item.kind === 'prompt' && (!data.widget_id || item.requestId === data.widget_id))
+                    this.items.delete(item.id);
+            }
+            return;
+        }
+        if (event.type === 'question_dismiss' || event.type === 'hook_approval_resolved') {
+            for (const item of this.items.values()) {
+                const kind = event.type === 'question_dismiss' ? 'question' : 'approval';
+                const requestId = kind === 'question' ? data.question_id : data.id;
+                if (item.paneId === paneId && item.kind === kind && item.requestId === requestId)
+                    this.items.delete(item.id);
+            }
+            return;
+        }
+        if (event.type === 'cancel' || event.type === 'clear') {
+            this.clearPane(paneId);
+            return;
+        }
+        if (event.type === 'session_end') {
+            this.markStale(paneId);
+            return;
+        }
+        let kind;
+        let requestId = '';
+        let blocker = '';
+        if (event.type === 'ask_user') {
+            kind = 'question';
+            requestId = identity(data.question_id);
+            blocker = bounded(data.question, Array.isArray(data.questions) ? data.questions.flatMap(question => question !== null && typeof question === 'object' && !Array.isArray(question) ? [bounded(question.question)].filter(Boolean) : []).join(' · ') : 'Answer the pending question');
+        }
+        else if (event.type === 'hook_approval_request') {
+            kind = 'approval';
+            requestId = identity(data.id);
+            blocker = bounded(data.reason, bounded(data.tool_name, 'Approve or deny the requested action'));
+        }
+        else if (['widget_prompt', 'widget_select', 'widget_questionnaire'].includes(event.type)) {
+            kind = 'prompt';
+            requestId = identity(data.widget_id);
+            blocker = bounded(data.question, bounded(data.title, 'Complete the pending prompt'));
+        }
+        else if (event.type === 'error') {
+            kind = 'failed';
+            blocker = bounded(data.message, 'Run failed');
+        }
+        else if (event.type === 'status') {
+            const status = bounded(data.status);
+            kind = status === 'error' || status === 'failed' ? 'failed' : status === 'blocked' ? 'blocked'
+                : ['review', 'ready_for_review'].includes(status) ? 'review' : status === 'stale' ? 'stale' : undefined;
+            if (!kind) {
+                // Idle follows both success and failure; it does not acknowledge an
+                // operator alert. Actual new work supersedes the previous signal.
+                if (['thinking', 'running', 'working', 'executing', 'tool_use'].includes(status))
+                    this.clearSignals(paneId);
+                return;
+            }
+            blocker = bounded(data.verb, status);
+            // A pending prompt already explains this pane's block. Avoid a second row.
+            if (kind === 'blocked' && [...this.items.values()].some(item => item.paneId === paneId && requestKinds.has(item.kind)))
+                return;
+            const previous = [...this.items.values()].find(item => item.paneId === paneId && item.kind === kind && !item.request);
+            if (previous)
+                return;
+        }
+        if (!kind)
+            return;
+        if (requestKinds.has(kind) && !requestId)
+            return;
+        if (kind === 'question') {
+            for (const item of this.items.values())
+                if (item.kind === 'question' && item.paneId === paneId && item.requestId !== requestId)
+                    this.items.delete(item.id);
+        }
+        if (requestKinds.has(kind))
+            this.clearSignals(paneId);
+        else {
+            this.clearSignals(paneId);
+            requestId = `${sessionId}:${event.seq ?? event.timestamp}`;
+        }
+        const id = `${kind}:${paneId}:${requestId}`;
+        if (this.items.has(id))
+            return;
+        const preview = requestKinds.has(kind) ? JSON.stringify(event) : undefined;
+        const previewFits = preview !== undefined && Buffer.byteLength(preview, 'utf8') <= maxPreviewBytes;
+        this.items.set(id, { id, requestId, kind, paneId, sessionId,
+            agent: bounded(pane?.title, `Pane ${paneId}`), task: bounded(data.task, bounded(pane?.labels?.task, this.tasks.get(paneId) ?? bounded(data.title, blocker))),
+            blocker: blocker.slice(0, 500), createdAt: event.timestamp,
+            primaryAction: kind === 'approval' ? 'approve' : kind === 'question' || kind === 'prompt' ? 'answer' : 'inspect',
+            ...(previewFits ? { request: JSON.parse(preview) } : preview !== undefined ? { requestPreviewUnavailable: true } : {}),
+        });
+    }
+    snapshot(limit = 100, offset = 0) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(offset) || offset < 0)
+            throw new Error('Invalid attention page.');
+        const items = [...this.items.values()].sort((a, b) => rank[a.kind] - rank[b.kind] || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        return { items: structuredClone(items.slice(offset, offset + limit)), total: items.length };
+    }
+    find(id) { const item = this.items.get(id); return item ? structuredClone(item) : undefined; }
+    findRequest(kind, requestId, paneId) {
+        const item = [...this.items.values()].find(item => item.kind === kind && item.requestId === requestId && item.paneId === paneId);
+        return item ? structuredClone(item) : undefined;
+    }
+    hasSettings(requestId, paneId) { return this.settings.has(`${paneId}:${requestId}`); }
+    closeSettings(requestId, paneId) { this.settings.delete(`${paneId}:${requestId}`); }
+    markStale(paneId) {
+        for (const item of this.items.values()) {
+            if (item.paneId === paneId) {
+                item.kind = 'stale';
+                item.primaryAction = 'inspect';
+                delete item.request;
+            }
+        }
+        this.tasks.delete(paneId);
+        for (const id of this.settings)
+            if (id.startsWith(`${paneId}:`))
+                this.settings.delete(id);
+    }
+    resolve(id) {
+        const item = this.find(id);
+        if (item)
+            this.items.delete(id);
+        return item;
+    }
+    clearSignals(paneId) {
+        for (const item of this.items.values())
+            if (item.paneId === paneId && !requestKinds.has(item.kind))
+                this.items.delete(item.id);
+    }
+    clearPane(paneId) {
+        for (const item of this.items.values())
+            if (item.paneId === paneId)
+                this.items.delete(item.id);
+        for (const id of this.settings)
+            if (id.startsWith(`${paneId}:`))
+                this.settings.delete(id);
+    }
+}

package/dist/bench/rf_shared.d.ts

@@ -109,6 +109,8 @@ export interface RfSessionState {
     last_update: string;
     active_backend?: string;
     backend_note?: string;
+    /** Reported optimization comparability; source verification and admission remain independent. */
+    measurementReport?: import('../optimize/measurements.js').OptimizationMeasurementReport;
 }
 export interface RfTargetSpec {
     name: string;

package/dist/board/binding.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare const BOARD_PENDING_MAX_BYTES: number;
+/** Credentials never belong to a canonical/shareable session checkpoint. */
+export declare function admitBoardOrigin(value: string): string;
+declare const binding: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    taskUuid: z.ZodString;
+    taskId: z.ZodString;
+    origin: z.ZodString;
+    boardId: z.ZodString;
+    cardId: z.ZodOptional<z.ZodString>;
+    revision: z.ZodOptional<z.ZodNumber>;
+    pending: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"create">;
+        key: z.ZodString;
+        body: z.ZodObject<{
+            boardId: z.ZodString;
+            columnId: z.ZodString;
+            title: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"evidence">;
+        key: z.ZodString;
+        expectedRevision: z.ZodNumber;
+        packageId: z.ZodString;
+        body: z.ZodObject<{
+            filename: z.ZodString;
+            mime_type: z.ZodLiteral<"application/json">;
+            data: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>], "kind">>;
+    lastEvidence: z.ZodOptional<z.ZodObject<{
+        packageId: z.ZodString;
+        attachmentId: z.ZodString;
+        revision: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type BoardSessionBinding = z.infer<typeof binding>;
+export declare function admitBoardSessionBinding(value: unknown, sessionId: string): BoardSessionBinding;
+export {};

package/dist/board/binding.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export const BOARD_PENDING_MAX_BYTES = 512 * 1024;
+const uuid = z.string().uuid();
+const revision = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+/** Credentials never belong to a canonical/shareable session checkpoint. */
+export function admitBoardOrigin(value) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/')
+        throw new Error('Zergboard origin must be a credential-free origin without a path');
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname))) {
+        throw new Error('Zergboard origin requires HTTPS (HTTP is allowed only for local development)');
+    }
+    return url.origin;
+}
+const pending = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('create'), key: uuid, body: z.object({ boardId: uuid, columnId: uuid,
+            title: z.string().min(1).max(255), description: z.string().max(2000) }).strict() }).strict(),
+    z.object({ kind: z.literal('evidence'), key: uuid, expectedRevision: revision, packageId: z.string().regex(/^[a-f0-9]{64}$/),
+        body: z.object({ filename: z.string().min(1).max(255), mime_type: z.literal('application/json'),
+            data: z.string().min(1).max(Math.ceil(BOARD_PENDING_MAX_BYTES / 3) * 4).regex(/^[A-Za-z0-9+/]+={0,2}$/) }).strict() }).strict(),
+]);
+const binding = z.object({ version: z.literal(1), sessionId: z.string().min(1).max(256),
+    taskUuid: uuid, taskId: z.string().min(1).max(512), origin: z.string().max(2048), boardId: uuid,
+    cardId: uuid.optional(), revision: revision.optional(), pending: pending.optional(),
+    lastEvidence: z.object({ packageId: z.string().regex(/^[a-f0-9]{64}$/), attachmentId: uuid, revision }).strict().optional(),
+}).strict();
+export function admitBoardSessionBinding(value, sessionId) {
+    const result = binding.parse(value);
+    if (result.sessionId !== sessionId || admitBoardOrigin(result.origin) !== result.origin)
+        throw new Error('Zergboard binding belongs to a different session or invalid origin');
+    if (result.pending?.kind === 'create' && (result.cardId || result.pending.body.boardId !== result.boardId))
+        throw new Error('Invalid Zergboard pending creation identity');
+    if (result.pending?.kind === 'evidence' && !result.cardId)
+        throw new Error('Zergboard pending evidence has no attached card');
+    if ((result.cardId === undefined) !== (result.revision === undefined))
+        throw new Error('Zergboard card and revision must be paired');
+    return result;
+}

package/dist/board/client.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare class BoardApiError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+export declare function configuredBoardOrigin(): string;
+export declare function boardRequest<T>(origin: string, sessionId: string, path: string, schema: z.ZodType<T>, options?: {
+    method?: 'POST' | 'PATCH';
+    body?: object;
+    key?: string;
+    revision?: number;
+}): Promise<T>;
+export declare const boardCardResponse: z.ZodObject<{
+    card: z.ZodObject<{
+        id: z.ZodString;
+        board_id: z.ZodString;
+        column_id: z.ZodString;
+        title: z.ZodString;
+        revision: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+        state_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        status: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const boardDetailsResponse: z.ZodObject<{
+    board: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    columns: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    states: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const boardAttachmentResponse: z.ZodObject<{
+    attachment: z.ZodObject<{
+        id: z.ZodString;
+        card_id: z.ZodString;
+    }, z.core.$strip>;
+    revision: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+}, z.core.$strip>;

package/dist/board/client.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { admitBoardOrigin } from './binding.js';
+export class BoardApiError extends Error {
+    status;
+    constructor(status) {
+        super(status === 409 ? 'Zergboard conflict (409); use /board refresh, review the card and decide again.'
+            : `Zergboard request failed (${status}); pending intent is retained.`);
+        this.status = status;
+    }
+}
+export function configuredBoardOrigin() {
+    const configured = process.env.ZTC_ZERGBOARD_ORIGIN;
+    if (!configured)
+        throw new Error('Set ZTC_ZERGBOARD_ORIGIN to your Zergboard origin');
+    return admitBoardOrigin(configured);
+}
+export async function boardRequest(origin, sessionId, path, schema, options = {}) {
+    if (admitBoardOrigin(origin) !== configuredBoardOrigin())
+        throw new Error('Configured Zergboard origin changed; restore the attached destination before syncing');
+    const token = process.env.ZTC_ZERGBOARD_TOKEN;
+    if (!token)
+        throw new Error('Set ZTC_ZERGBOARD_TOKEN to a token with access to this board');
+    const response = await fetch(new URL(path, origin), { method: options.method ?? 'GET', redirect: 'manual',
+        signal: AbortSignal.timeout(15_000), headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json',
+            'x-zergboard-agent-session-id': sessionId, ...(options.key ? { 'idempotency-key': options.key } : {}),
+            ...(options.revision === undefined ? {} : { 'if-match': String(options.revision) }) },
+        ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }) });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new BoardApiError(response.status);
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Zergboard response has no body; operation outcome is unknown');
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            length += value.length;
+            if (length > 8 * 1024 * 1024)
+                throw new Error('Zergboard response exceeds the read limit');
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    return schema.parse(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+}
+const uuid = z.string().uuid();
+const apiRevision = z.union([z.number(), z.string().regex(/^\d+$/)]).transform(Number)
+    .refine(value => Number.isSafeInteger(value) && value >= 0, 'Invalid card revision');
+export const boardCardResponse = z.object({ card: z.object({ id: uuid, board_id: uuid, column_id: uuid,
+        title: z.string(), revision: apiRevision, state_id: uuid.nullable().optional(), status: z.string() }) });
+export const boardDetailsResponse = z.object({ board: z.object({ id: uuid }), columns: z.array(z.object({ id: uuid })),
+    states: z.array(z.object({ id: uuid, kind: z.string() })) });
+export const boardAttachmentResponse = z.object({ attachment: z.object({ id: uuid, card_id: uuid }), revision: apiRevision });

package/dist/cli.js

@@ -131,7 +131,7 @@ async function main() {
         };
     }
     // Render the app
-    const { waitUntilExit } = render(_jsx(App, {}));
+    const { waitUntilExit } = render(_jsx(App, {}), { exitOnCtrlC: false });
     // Handle clean exit
     waitUntilExit().then(() => {
         // Disable Kitty keyboard protocol