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

package/dist/headless_cli.js

@@ -64,6 +64,14 @@ async function main() {
         configStore.setCliOverride('model', options.model);
     if (options.effort)
         configStore.setCliOverride('codexEffort', options.effort);
+    // The headless package is a standalone entry, so it must discover configured
+    // MCP tools before the synchronous agent factory builds the allowed surface.
+    // Required servers fail startup; optional failures retain the client policy.
+    const servers = configStore.get().mcpServers;
+    if (servers && Object.keys(servers).length > 0) {
+        const { initMcpServers } = await import('./mcp/client.js');
+        await initMcpServers(servers);
+    }
     try {
         const { preloadSkillsManifest } = await import('./skills/registry.js');
         await preloadSkillsManifest();

package/dist/headless_cli_args.d.ts

@@ -6,6 +6,7 @@ export interface HeadlessCliOptions {
     timestamps?: boolean;
     verbose?: boolean;
     sessionFile?: string;
+    detachEnvironment?: boolean;
     provider?: string;
     model?: string;
     effort?: CodexReasoningEffort;

package/dist/headless_cli_args.js

@@ -9,6 +9,7 @@ export function parseHeadlessCliArgs(args) {
         jsonStream: false,
     };
     const booleanFlags = new Map([
+        ['--detach-environment', () => { options.detachEnvironment = true; }],
         ['--json', () => { options.json = true; }],
         ['--json-stream', () => { options.jsonStream = true; }],
         ['--quiet', () => { options.quiet = true; }],

package/dist/intake/cli.d.ts

@@ -0,0 +1 @@
+export declare function runInboxCli(args: string[]): Promise<void>;

package/dist/intake/cli.js

@@ -0,0 +1,33 @@
+import { readFile, stat } from 'node:fs/promises';
+import { receiveIntakeRequest, listIntakeReceipts, getIntakeReceipt } from './store.js';
+import { formatIntakeReceipt } from './format.js';
+export async function runInboxCli(args) {
+    const json = args.includes('--json');
+    const tokens = args.filter(arg => arg !== '--json');
+    let result;
+    if (tokens[0] === 'receive' && tokens[1] === '--file' && tokens.length === 3) {
+        if ((await stat(tokens[2])).size > 64 * 1024)
+            throw new Error('Intake envelope exceeds 64 KiB.');
+        result = await receiveIntakeRequest(JSON.parse(await readFile(tokens[2], 'utf8')));
+    }
+    else if ((tokens[0] === 'list' && tokens.length === 1) || tokens.length === 0) {
+        result = await listIntakeReceipts();
+    }
+    else if (tokens[0] === 'show' && tokens.length === 2) {
+        result = await getIntakeReceipt(tokens[1]);
+    }
+    else
+        throw new Error('Usage: ztc inbox list|show <req-ID>|receive --file <request.json> [--json]');
+    if (json)
+        process.stdout.write(JSON.stringify(result) + '\n');
+    else if ('receipts' in result) {
+        const list = result;
+        console.log(list.receipts.length ? list.receipts.map(formatIntakeReceipt).join('\n\n') : 'Inbox is empty. Receive a request with ztc inbox receive --file request.json.');
+    }
+    else if ('receipt' in result) {
+        const received = result;
+        console.log(`${received.duplicate ? 'Existing' : 'New'} receipt\n${formatIntakeReceipt(received.receipt)}`);
+    }
+    else
+        console.log(formatIntakeReceipt(result));
+}

package/dist/intake/format.d.ts

@@ -0,0 +1,2 @@
+import type { IntakeReceipt } from './store.js';
+export declare function formatIntakeReceipt(receipt: IntakeReceipt): string;

package/dist/intake/format.js

@@ -0,0 +1,14 @@
+export function formatIntakeReceipt(receipt) {
+    return [receipt.intakeId, `Task: ${receipt.taskId}`,
+        `Source: ${receipt.source.channel} · ${receipt.source.account} · ${receipt.source.eventId}`,
+        `Received: ${receipt.receivedAt}${receipt.sentAt ? ` · sent ${receipt.sentAt}` : ''}`,
+        `State: ${receipt.state}${receipt.state === 'accepted' ? ' (submitted, outcome not yet recorded)' : ''}`,
+        `Acknowledgment: ${receipt.acknowledgedAt ?? 'pending'}`,
+        `Owner: ${receipt.owner ? `${receipt.owner.sessionId} · ${receipt.owner.cwd}` : 'unassigned, awaiting your review'}`,
+        `Request: ${receipt.action}`, receipt.outcome ? `Outcome: ${receipt.outcome}` : '',
+        receipt.owner ? `Session: /inbox open ${receipt.intakeId} session` : '',
+        ...Object.entries(receipt.links ?? {}).map(([kind, target]) => `${kind}: ${target}\nOpen: /inbox open ${receipt.intakeId} ${kind}`),
+        `Acknowledge: /inbox ack ${receipt.intakeId}`,
+        receipt.state === 'received' ? `Run only after review: /inbox run ${receipt.intakeId}` : '',
+    ].filter(Boolean).join('\n');
+}

package/dist/intake/notifications.d.ts

@@ -0,0 +1,16 @@
+import { type IntakeOwner } from './store.js';
+/** Read-only receipt notifications. This surface never acknowledges or runs work. */
+export declare class IntakeNotifications {
+    private seen;
+    private polling;
+    private profileDirectory;
+    private watcher?;
+    private watchedDirectory?;
+    private initialRead;
+    private changed;
+    private receipts;
+    private overflow;
+    dispose(): void;
+    private watchProfile;
+    poll(owner: IntakeOwner): Promise<string | null>;
+}

package/dist/intake/notifications.js

@@ -0,0 +1,132 @@
+import { getIntakeReceipt, listIntakeReceipts } from './store.js';
+import { watch } from 'node:fs';
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { profileConfigDir } from '../config/profiles.js';
+/** Read-only receipt notifications. This surface never acknowledges or runs work. */
+export class IntakeNotifications {
+    seen = new Set();
+    polling = false;
+    profileDirectory = '';
+    watcher;
+    watchedDirectory;
+    initialRead = true;
+    changed = new Set();
+    receipts = new Map();
+    overflow = false;
+    dispose() { this.watcher?.close(); this.watcher = undefined; this.watchedDirectory = undefined; }
+    async watchProfile(directory) {
+        try {
+            const info = await lstat(join(directory, 'inbox'));
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error('Inbox notifications require an owned directory.');
+            if (this.watcher && this.watchedDirectory?.dev === info.dev && this.watchedDirectory.ino === info.ino)
+                return;
+            this.dispose();
+            this.initialRead = true;
+            // Watch new receipt directories only, avoiding one native watch per revision/history directory.
+            const watcher = watch(join(directory, 'inbox'), { recursive: false }, (_event, filename) => {
+                if (this.watcher !== watcher || this.profileDirectory !== directory)
+                    return;
+                const match = filename?.toString().replace(/\\/g, '/').match(/^(req-[a-f0-9]{64})(?:\/\d{6}\.json)?$/);
+                if (!match)
+                    return;
+                if (this.changed.size >= 512 && !this.changed.has(match[1])) {
+                    this.overflow = true;
+                    return;
+                }
+                this.changed.add(match[1]);
+            });
+            this.watcher = watcher;
+            this.watchedDirectory = { dev: info.dev, ino: info.ino };
+            watcher.on('error', () => { if (this.watcher === watcher) {
+                this.dispose();
+                this.initialRead = true;
+            } });
+            watcher.unref();
+        }
+        catch {
+            this.dispose();
+            this.initialRead = true;
+        } // An inbox created later is picked up on the next poll.
+    }
+    async poll(owner) {
+        if (this.polling)
+            return null;
+        this.polling = true;
+        try {
+            const profileDirectory = profileConfigDir();
+            if (profileDirectory !== this.profileDirectory) {
+                this.dispose();
+                this.receipts.clear();
+                this.changed.clear();
+                this.initialRead = true;
+                this.overflow = false;
+                this.seen.clear();
+                this.profileDirectory = profileDirectory;
+            }
+            await this.watchProfile(profileDirectory);
+            if (this.initialRead) {
+                const result = await listIntakeReceipts();
+                if (profileConfigDir() !== profileDirectory)
+                    return null;
+                this.receipts = new Map(result.receipts.map(receipt => [receipt.intakeId, receipt]));
+                this.initialRead = !this.watcher;
+            }
+            else {
+                // One tick reads at most 64 changed receipts, never all retained history.
+                for (const id of [...this.changed].slice(0, 64)) {
+                    if (profileConfigDir() !== profileDirectory)
+                        return null;
+                    this.changed.delete(id);
+                    try {
+                        this.receipts.set(id, await getIntakeReceipt(id));
+                    }
+                    catch (error) {
+                        if (error instanceof Error && error.message === 'Receipt is still being published; retry.')
+                            this.changed.add(id);
+                        else if (error.code === 'ENOENT')
+                            this.receipts.delete(id);
+                        else
+                            throw error;
+                    }
+                }
+            }
+            if (profileConfigDir() !== profileDirectory)
+                return null;
+            const receipts = [...this.receipts.values()].sort((a, b) => b.receivedAt.localeCompare(a.receivedAt) || a.intakeId.localeCompare(b.intakeId)).slice(0, 100);
+            this.receipts = new Map(receipts.map(receipt => [receipt.intakeId, receipt]));
+            if (this.overflow) {
+                this.overflow = false;
+                return 'Inbox activity exceeded the 512-receipt notification queue. Use /inbox to review the retained requests. Nothing has been started.';
+            }
+            const visible = new Set(receipts.map(receipt => receipt.intakeId));
+            this.seen = new Set([...this.seen].filter(id => visible.has(id)));
+            const candidates = receipts.filter(receipt => receipt.state === 'received' && !receipt.acknowledgedAt && !this.seen.has(receipt.intakeId)
+                && (!receipt.owner || (receipt.owner.sessionId === owner.sessionId && receipt.owner.cwd === owner.cwd)));
+            const pending = [];
+            // A receipt may be acknowledged after discovery. Verify only unseen,
+            // eligible candidates instead of recursively watching all past revisions.
+            for (const candidate of candidates) {
+                if (profileConfigDir() !== profileDirectory)
+                    return null;
+                const receipt = await getIntakeReceipt(candidate.intakeId);
+                if (profileConfigDir() !== profileDirectory)
+                    return null;
+                this.receipts.set(receipt.intakeId, receipt);
+                if (receipt.state === 'received' && !receipt.acknowledgedAt && (!receipt.owner || (receipt.owner.sessionId === owner.sessionId && receipt.owner.cwd === owner.cwd)))
+                    pending.push(receipt);
+            }
+            if (!pending.length)
+                return null;
+            for (const receipt of pending)
+                this.seen.add(receipt.intakeId);
+            return [`Inbox: ${pending.length} new request${pending.length === 1 ? '' : 's'} awaiting your review.`,
+                ...pending.slice(0, 3).map(receipt => `${receipt.source.channel} · ${receipt.action.replace(/\s+/g, ' ').slice(0, 80)}\n/inbox show ${receipt.intakeId}`),
+                'Receipt only. Use /inbox to review; nothing has been started.'].join('\n');
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+}

package/dist/intake/store.d.ts

@@ -0,0 +1,56 @@
+export interface IntakeOwner {
+    sessionId: string;
+    cwd: string;
+}
+export interface IntakeLinks {
+    source?: string;
+    card?: string;
+    artifact?: string;
+}
+export interface IntakeRequest {
+    source: {
+        channel: string;
+        account: string;
+        eventId: string;
+    };
+    action: string;
+    sentAt?: string;
+    owner?: IntakeOwner;
+    links?: IntakeLinks;
+}
+export type IntakeState = 'received' | 'accepted' | 'completed' | 'failed' | 'dismissed';
+export interface IntakeReceipt extends IntakeRequest {
+    schemaVersion: 1;
+    intakeId: string;
+    taskId: string;
+    receivedAt: string;
+    revision: number;
+    state: IntakeState;
+    acknowledgedAt?: string;
+    acceptedAt?: string;
+    outcome?: string;
+}
+export type IntakeChange = {
+    type: 'acknowledge';
+} | {
+    type: 'accept';
+    owner: IntakeOwner;
+} | {
+    type: 'complete' | 'fail' | 'dismiss';
+    note: string;
+} | {
+    type: 'link';
+    links: IntakeLinks;
+};
+export declare function validateIntakeRequest(value: unknown): IntakeRequest;
+export declare function getIntakeReceipt(id: string): Promise<IntakeReceipt>;
+export declare function receiveIntakeRequest(value: unknown): Promise<{
+    receipt: IntakeReceipt;
+    duplicate: boolean;
+}>;
+export declare function listIntakeReceipts(limit?: number): Promise<{
+    receipts: IntakeReceipt[];
+    total: number;
+    unavailable?: number;
+}>;
+export declare function changeIntakeReceipt(id: string, change: IntakeChange): Promise<IntakeReceipt>;

package/dist/intake/store.js

@@ -0,0 +1,238 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, writeFile, link, unlink, stat } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { profileConfigDir } from '../config/profiles.js';
+const MAX_BYTES = 64 * 1024;
+class IntakeRecordError extends Error {
+}
+const ID = /^req-[a-f0-9]{64}$/;
+const root = () => join(profileConfigDir(), 'inbox');
+const directory = (id) => {
+    if (!ID.test(id))
+        throw new Error('Use the full req- ID from /inbox.');
+    return join(root(), id);
+};
+function text(value, name, max) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max || /[\x00-\x08\x0b-\x1f\x7f]/.test(value)) {
+        throw new Error(`${name} must contain 1–${max} characters without terminal control characters.`);
+    }
+    return value;
+}
+function owner(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid owner object.');
+    const sessionId = text(value.sessionId, 'Session ID', 128);
+    if (!/^[a-zA-Z0-9_-]+$/.test(sessionId))
+        throw new Error('Invalid session ID.');
+    const cwd = text(value.cwd, 'Working directory', 4096);
+    if (!isAbsolute(cwd))
+        throw new Error('Owner working directory must be absolute.');
+    return { sessionId, cwd };
+}
+function links(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid links object.');
+    const result = {};
+    for (const key of ['source', 'card']) {
+        if (value[key] === undefined)
+            continue;
+        const url = new URL(text(value[key], `${key} URL`, 4096));
+        if (url.protocol !== 'https:' || url.username || url.password)
+            throw new Error('Receipt links must use HTTPS without credentials.');
+        if (key === 'card' && (url.hostname !== 'zergboard.com' || !/^\/app\/cards\/[a-f0-9-]{36}$/.test(url.pathname))) {
+            throw new Error('Card links must point to a ZergBoard card.');
+        }
+        result[key] = text(url.href, `${key} URL`, 4096);
+    }
+    if (value.artifact !== undefined) {
+        result.artifact = text(value.artifact, 'Artifact path', 4096);
+        if (!isAbsolute(result.artifact))
+            throw new Error('Artifact path must be absolute.');
+    }
+    return result;
+}
+export function validateIntakeRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Expected an intake request object.');
+    const input = value;
+    if (!input.source || typeof input.source !== 'object')
+        throw new Error('Request source is required.');
+    const channel = text(input.source.channel, 'Source channel', 64);
+    const account = text(input.source.account, 'Source account', 256);
+    const eventId = text(input.source.eventId, 'Source event ID', 1024);
+    if ([channel, account, eventId].some(value => /[\n\t]/.test(value)))
+        throw new Error('Source provenance must use a single line.');
+    const action = text(input.action, 'Requested action', 16_384);
+    let sentAt;
+    if (input.sentAt !== undefined) {
+        if (typeof input.sentAt !== 'string' || !Number.isFinite(Date.parse(input.sentAt)))
+            throw new Error('Invalid source timestamp.');
+        sentAt = new Date(input.sentAt).toISOString();
+    }
+    return { source: { channel, account, eventId }, action, ...(sentAt ? { sentAt } : {}),
+        ...(input.owner !== undefined ? { owner: owner(input.owner) } : {}), ...(input.links !== undefined ? { links: links(input.links) } : {}) };
+}
+// Publish immutable files with an exclusive hard link. Competing processes can
+// neither overwrite a receipt nor publish two revisions at the same position.
+// A crash leaves, at worst, an ignored temporary file; it never leaves a lock.
+async function publish(path, value) {
+    const content = JSON.stringify(value);
+    if (Buffer.byteLength(content) > MAX_BYTES)
+        throw new Error('Inbox record exceeds 64 KiB.');
+    const temporary = `${path}.tmp-${randomUUID()}`;
+    await writeFile(temporary, content, { flag: 'wx', mode: 0o600 });
+    try {
+        await link(temporary, path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        await unlink(temporary);
+    }
+}
+async function read(path) {
+    if ((await stat(path)).size > MAX_BYTES)
+        throw new IntakeRecordError('Inbox record exceeds 64 KiB.');
+    const bytes = await readFile(path, 'utf8');
+    let receipt;
+    try {
+        receipt = JSON.parse(bytes);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new IntakeRecordError('Inbox record is not valid JSON.');
+        throw error;
+    }
+    if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)
+        || receipt.schemaVersion !== 1 || !ID.test(receipt.intakeId))
+        throw new IntakeRecordError('Unsupported inbox record.');
+    if (typeof receipt.receivedAt !== 'string' || !Number.isFinite(Date.parse(receipt.receivedAt))
+        || !Number.isSafeInteger(receipt.revision) || receipt.revision < 0 || receipt.revision > 999999
+        || !['received', 'accepted', 'completed', 'failed', 'dismissed'].includes(receipt.state)) {
+        throw new IntakeRecordError('Invalid inbox receipt metadata.');
+    }
+    try {
+        validateIntakeRequest(receipt);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw new IntakeRecordError(error.message);
+        throw error;
+    }
+    return receipt;
+}
+export async function getIntakeReceipt(id) {
+    return readReceiptDirectory(directory(id));
+}
+async function readReceiptDirectory(dir) {
+    const files = await readdir(dir);
+    const revisions = files.filter(file => /^\d{6}\.json$/.test(file)).sort();
+    if (!revisions.length)
+        throw new Error('Receipt is still being published; retry.');
+    return read(join(dir, revisions.at(-1)));
+}
+export async function receiveIntakeRequest(value) {
+    const input = validateIntakeRequest(value);
+    const hash = createHash('sha256').update(JSON.stringify(input.source)).digest('hex');
+    const intakeId = `req-${hash}`;
+    const dir = directory(intakeId);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const receipt = { ...input, schemaVersion: 1, intakeId, taskId: `task-${hash}`,
+        receivedAt: new Date().toISOString(), revision: 0, state: 'received' };
+    if (await publish(join(dir, '000000.json'), receipt))
+        return { receipt, duplicate: false };
+    const original = await read(join(dir, '000000.json'));
+    if (JSON.stringify(validateIntakeRequest(original)) !== JSON.stringify(input)) {
+        throw new Error('Source event ID was reused with different request content. The original receipt was preserved.');
+    }
+    return { receipt: await getIntakeReceipt(intakeId), duplicate: true };
+}
+export async function listIntakeReceipts(limit = 100) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+        throw new Error('Inbox limit must be 1–1000.');
+    const profileRoot = root();
+    let files;
+    try {
+        files = await readdir(profileRoot);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { receipts: [], total: 0 };
+        throw error;
+    }
+    const ids = files.filter(file => ID.test(file));
+    const receipts = [];
+    let total = 0;
+    let unavailable = 0;
+    // Keep filesystem reads sequential and the preview bounded. Durable records
+    // remain addressable by their immutable ID after they leave the preview.
+    for (const id of ids) {
+        try {
+            receipts.push(await readReceiptDirectory(join(profileRoot, id)));
+            total++;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'Receipt is still being published; retry.')
+                continue;
+            if (error instanceof IntakeRecordError) {
+                unavailable++;
+                continue;
+            }
+            throw error;
+        }
+        receipts.sort((a, b) => b.receivedAt.localeCompare(a.receivedAt) || a.intakeId.localeCompare(b.intakeId));
+        if (receipts.length > limit)
+            receipts.pop();
+    }
+    return { receipts, total, ...(unavailable > 0 ? { unavailable } : {}) };
+}
+export async function changeIntakeReceipt(id, change) {
+    for (let attempt = 0; attempt < 32; attempt++) {
+        const before = await getIntakeReceipt(id);
+        const next = { ...before, revision: before.revision + 1 };
+        if (next.revision > 999999)
+            throw new Error('Receipt revision limit reached.');
+        const now = new Date().toISOString();
+        switch (change.type) {
+            case 'acknowledge':
+                if (before.acknowledgedAt)
+                    return before;
+                next.acknowledgedAt = now;
+                break;
+            case 'accept': {
+                if (before.state !== 'received')
+                    throw new Error(`Request is ${before.state}; it cannot be submitted again.`);
+                const target = owner(change.owner);
+                if (before.owner && (before.owner.sessionId !== target.sessionId || before.owner.cwd !== target.cwd)) {
+                    throw new Error('Request belongs to another session. Open its receipt to resume that owner.');
+                }
+                next.owner = target;
+                next.state = 'accepted';
+                next.acceptedAt = now;
+                next.acknowledgedAt ??= now;
+                break;
+            }
+            case 'complete':
+            case 'fail':
+            case 'dismiss':
+                if (change.type === 'dismiss' ? before.state !== 'received' : before.state !== 'accepted') {
+                    throw new Error(`Cannot ${change.type} a ${before.state} request.`);
+                }
+                next.state = change.type === 'complete' ? 'completed' : change.type === 'fail' ? 'failed' : 'dismissed';
+                next.outcome = text(change.note, 'Outcome note', 4096);
+                next.acknowledgedAt ??= now;
+                break;
+            case 'link':
+                next.links = { ...before.links, ...links(change.links) };
+                break;
+        }
+        const path = join(directory(id), `${String(next.revision).padStart(6, '0')}.json`);
+        if (await publish(path, next))
+            return next;
+    }
+    throw new Error('Receipt changed too often; retry.');
+}

package/dist/library.d.ts

@@ -25,6 +25,7 @@
  */
 import { Agent } from './agent/agent.js';
 import type { AgentBackend } from './agent/backends/types.js';
+import type { NativeAnthropicMessagesRouterConfig } from './agent/backends/index.js';
 import type { Tool } from './agent/tools/types.js';
 import type { Policy } from './agent/runtime/policy.js';
 import type { HostApprovalContext } from './agent/runtime/tool_runtime.js';
@@ -33,13 +34,18 @@ import type { ToolCapability } from './agent/runtime/capabilities.js';
 import type { AgentHandlerFn } from './agent/tools/sim_domain_tools.js';
 import type { AgentEvent, Message } from './types.js';
 import type { HostMetadata, InferenceCredentialProvider, ToolEffectObserver } from './host/index.js';
+import type { CodexReasoningEffort } from './config/types.js';
 export type { AgentEvent, Message, MessageRole, ToolCall } from './types.js';
 export type { AgentConfig } from './agent/agent.js';
 export type { AgentBackend } from './agent/backends/types.js';
+export type { NativeAnthropicMessagesRouterConfig } from './agent/backends/anthropic.js';
+export type { ContentBlock, RequestContentBlock, ThinkingBlock, RedactedThinkingBlock } from './agent/backends/types.js';
 export type { Tool } from './agent/tools/types.js';
 export type { AgentHandlerFn } from './agent/tools/sim_domain_tools.js';
 /** Options for `createAgent`. All fields are optional; sensible defaults come from env. */
 export interface CreateAgentOptions {
+    /** Explicit hosted native Messages transport; ambient provider keys are ignored. */
+    nativeAnthropicMessagesRouter?: NativeAnthropicMessagesRouterConfig;
     /** Provider name: 'anthropic' | 'openai' | 'gemini' | 'kimi' | 'deepseek' | ... */
     provider?: string;
     /** Model id. Defaults to the provider's canonical model. */
@@ -128,6 +134,8 @@ export interface CreateAgentOptions {
      * explicitly here if you need to pin the value across ZTC upgrades.
      */
     maxTokens?: number;
+    /** Provider reasoning effort for every request. Opus 5.5 defaults to high. */
+    codexEffort?: CodexReasoningEffort;
     /** Auto-continue on incomplete responses (default true). */
     autoContinue?: boolean;
     /**

package/dist/library.js

@@ -24,7 +24,7 @@
  *   }
  */
 import { Agent } from './agent/agent.js';
-import { createBackendForProvider } from './agent/backends/index.js';
+import { createBackendForProvider, createNativeAnthropicMessagesRouterBackend } from './agent/backends/index.js';
 import { defaultTools as baseDefaultTools } from './agent/tools/registry.js';
 import { toolSearchTool } from './agent/tools/tool_search.js';
 import { recallToolResponseTool } from './agent/tools/recall_tool_response.js';
@@ -44,10 +44,16 @@ export async function createAgent(opts = {}) {
     if (opts.backend && opts.inferenceCredentialProvider) {
         throw new Error('backend and inferenceCredentialProvider are mutually exclusive');
     }
+    if (opts.nativeAnthropicMessagesRouter && (opts.backend || opts.inferenceCredentialProvider)) {
+        throw new Error('nativeAnthropicMessagesRouter supplies its own backend and credential authority');
+    }
     const ambientDiscovery = opts.ambientDiscovery ?? true;
-    const provider = opts.provider ?? (ambientDiscovery ? inferDefaultProvider() : 'anthropic');
+    const provider = opts.provider ?? (opts.nativeAnthropicMessagesRouter ? 'anthropic' : ambientDiscovery ? inferDefaultProvider() : 'anthropic');
+    if (opts.nativeAnthropicMessagesRouter && provider !== 'anthropic' && provider !== 'claude') {
+        throw new Error('Native Anthropic Router requires the anthropic provider');
+    }
     const model = opts.model ?? getDefaultModelForProvider(provider);
-    const apiKey = opts.inferenceCredentialProvider
+    const apiKey = opts.inferenceCredentialProvider || opts.nativeAnthropicMessagesRouter
         ? ''
         : (opts.apiKey ?? (ambientDiscovery ? getDefaultApiKeyForProvider(provider) : undefined) ?? '');
     const makeBackend = (bearer) => createBackendForProvider(provider, {
@@ -55,7 +61,8 @@ export async function createAgent(opts = {}) {
         apiEndpoint: opts.apiEndpoint,
         baseUrl: opts.openaiCompatibleBaseUrl,
     });
-    const backend = opts.backend ?? (opts.inferenceCredentialProvider
+    const backend = opts.backend ?? (opts.nativeAnthropicMessagesRouter
+        ? createNativeAnthropicMessagesRouterBackend(opts.nativeAnthropicMessagesRouter) : (opts.inferenceCredentialProvider
         ? createCredentialedBackend({
             provider: opts.inferenceCredentialProvider,
             providerId: provider,
@@ -63,7 +70,7 @@ export async function createAgent(opts = {}) {
             context: opts.inferenceCredentialContext,
             requestId: opts.inferenceRequestId,
         })
-        : makeBackend(apiKey));
+        : makeBackend(apiKey)));
     let tools = opts.tools
         ? [...opts.tools]
         : (ambientDiscovery ? [...defaultTools] : []);
@@ -108,8 +115,8 @@ export async function createAgent(opts = {}) {
     }
     const config = {
         apiKey,
-        disableApiKeyFallback: opts.inferenceCredentialProvider !== undefined,
-        runtimeCredentialsAvailable: opts.inferenceCredentialProvider !== undefined,
+        disableApiKeyFallback: Boolean(opts.inferenceCredentialProvider || opts.nativeAnthropicMessagesRouter),
+        runtimeCredentialsAvailable: Boolean(opts.inferenceCredentialProvider || opts.nativeAnthropicMessagesRouter),
         ambientDiscovery,
         model,
         apiEndpoint: opts.apiEndpoint,
@@ -117,15 +124,16 @@ export async function createAgent(opts = {}) {
         backend,
         tools,
         alwaysLoadedToolNames: opts.alwaysLoadedToolNames,
-        deferToolSchemas: opts.deferToolSchemas,
+        deferToolSchemas: opts.deferToolSchemas ?? (opts.nativeAnthropicMessagesRouter ? false : undefined),
         cwd: opts.cwd,
-        pinTaskHeader: opts.pinTaskHeader,
-        subprocessEnv: opts.inferenceCredentialProvider
+        pinTaskHeader: opts.nativeAnthropicMessagesRouter ? false : opts.pinTaskHeader,
+        subprocessEnv: opts.inferenceCredentialProvider || opts.nativeAnthropicMessagesRouter
             ? buildCredentialSafeSubprocessEnv(opts.subprocessEnv ?? process.env)
             : opts.subprocessEnv,
         toolEffectObserver: opts.toolEffectObserver,
         maxIterations: opts.maxIterations,
         maxTokens: opts.maxTokens,
+        codexEffort: opts.codexEffort,
         autoContinue: opts.autoContinue,
         llmRequestTimeoutMs: opts.llmRequestTimeoutMs,
         policy: opts.policy,
@@ -198,6 +206,7 @@ async function* runAndAppend(agent, messages, userMsg) {
             id: `assistant_${Date.now()}`,
             role: 'assistant',
             content: result.content,
+            ...(result.nativeContent ? { nativeContent: result.nativeContent, nativeModel: result.nativeModel, nativeContextId: result.nativeContextId } : {}),
             timestamp: new Date(),
             toolCalls: result.toolCalls?.length ? result.toolCalls : undefined,
             // Reasoning models expect their trace replayed with the assistant

package/dist/mcp/client.d.ts

@@ -1,4 +1,5 @@
 import type { MCPServerConfig } from '../config/types.js';
+export declare const MAX_MCP_IMAGE_BYTES: number;
 export { ZTC_MCP_TOOL_CALL_ID_META_KEY, RequiredMcpServerError, getMcpTools, getMcpServerStatuses, noteShadowedMcpTool, getColonyAttachInfo, closeMcpServers, type McpServerStatus, } from './registry.js';
 /**
  * Connect every configured (and the default colony) MCP server and collect their