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

package/dist/headless_output_schema.js

@@ -0,0 +1,386 @@
+/**
+ * `--output-schema` contract for headless runs: the final assistant message
+ * of a prompt must be exactly one JSON document that validates against a
+ * JSON Schema. Supports a closed, fail-safe subset of draft 2020-12; any
+ * assertion keyword outside it is rejected when the schema loads, so a
+ * constraint is never silently ignored. Pattern exemplar: the autodev
+ * runner's strict final-JSON parser (zapps/zergboard/runner/autodev/src/
+ * structured-cli-agent.ts) and Codex's `--output-schema`.
+ */
+import { readFileSync, statSync } from 'node:fs';
+export const OUTPUT_SCHEMA_LIMITS = Object.freeze({
+    schemaBytes: 64 * 1024,
+    depth: 64,
+    reportedErrors: 20,
+    /** Schema-node visits per validation; bounds anyOf/oneOf/$ref fan-out. */
+    validationSteps: 200_000,
+});
+export class OutputSchemaError extends Error {
+    code;
+    errors;
+    constructor(code, message, errors = []) {
+        super(message);
+        this.code = code;
+        this.errors = errors;
+        this.name = 'OutputSchemaError';
+    }
+}
+const JSON_TYPES = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
+const ANNOTATIONS = new Set(['$schema', '$id', '$comment', 'title', 'description', 'default', 'examples', 'format',
+    'deprecated', 'readOnly', 'writeOnly', 'contentMediaType', 'contentEncoding']);
+const SCHEMA_MAP_KEYWORDS = new Set(['properties', '$defs', 'definitions']);
+const SCHEMA_LIST_KEYWORDS = new Set(['anyOf', 'oneOf', 'allOf']);
+const SCHEMA_KEYWORDS = new Set(['items', 'not', 'additionalProperties']);
+const COUNT_KEYWORDS = new Set(['minLength', 'maxLength', 'minItems', 'maxItems', 'minProperties', 'maxProperties']);
+const NUMBER_KEYWORDS = new Set(['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum']);
+const OTHER_KEYWORDS = new Set(['type', 'enum', 'const', 'required', 'uniqueItems', 'pattern', '$ref']);
+function isSchemaObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function childPath(path, key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+}
+function invalid(message) {
+    return new OutputSchemaError('output_schema_invalid', `Invalid --output-schema: ${message}`);
+}
+/** Key-order-insensitive JSON equality, as `enum`, `const` and `uniqueItems` require. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (isSchemaObject(value)) {
+        return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function codePoints(text) {
+    let count = 0;
+    for (const _ of text)
+        count += 1;
+    return count;
+}
+/** RFC 6901 tokens of a local `#/...` reference (percent-decoded, then ~1, ~0). */
+function refTokens(ref, path) {
+    return ref.slice(1).split('/').slice(1).map(raw => {
+        let token;
+        try {
+            token = decodeURIComponent(raw);
+        }
+        catch {
+            throw invalid(`malformed $ref pointer ${JSON.stringify(ref)} at ${path}`);
+        }
+        return token.replaceAll('~1', '/').replaceAll('~0', '~');
+    });
+}
+function encodePointer(tokens) {
+    return tokens.map(token => `/${token.replaceAll('~', '~0').replaceAll('/', '~1')}`).join('');
+}
+/**
+ * A resource limit was hit. It aborts the whole validation so that `not`,
+ * `anyOf` and `oneOf` can never read it as "this subschema did not match".
+ */
+class ValidationLimitExceeded extends Error {
+}
+function typeMatches(value, type) {
+    switch (type) {
+        case 'object': return isSchemaObject(value);
+        case 'array': return Array.isArray(value);
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number' && Number.isFinite(value);
+        case 'integer': return Number.isInteger(value);
+        case 'boolean': return typeof value === 'boolean';
+        default: return value === null;
+    }
+}
+export class OutputSchemaContract {
+    root;
+    patterns = new Map();
+    /** JSON pointers of every position compile() checked as a schema. */
+    schemaPointers = new Set();
+    refSites = [];
+    refTargets = new Map();
+    steps = 0;
+    constructor(root) {
+        this.root = root;
+        this.compile(root, '$', 0, []);
+        // A $ref may only name a position that was compiled as a schema, never an
+        // annotation, `const`/`enum` value or keyword map whose keywords were
+        // never checked (and so would be silently ignored or crash validation).
+        for (const { ref, path } of this.refSites) {
+            const tokens = refTokens(ref, path);
+            if (!this.schemaPointers.has(encodePointer(tokens))) {
+                throw invalid(`$ref ${JSON.stringify(ref)} does not resolve to a schema at ${path}`);
+            }
+            let target = root;
+            for (const token of tokens)
+                target = target[token];
+            this.refTargets.set(ref, target);
+        }
+    }
+    /** Read, bound and compile a schema file; every failure is `output_schema_invalid`. */
+    static fromFile(path) {
+        let text;
+        try {
+            if (statSync(path).size > OUTPUT_SCHEMA_LIMITS.schemaBytes) {
+                throw invalid(`${path} exceeds ${OUTPUT_SCHEMA_LIMITS.schemaBytes} bytes`);
+            }
+            text = readFileSync(path, 'utf8');
+        }
+        catch (error) {
+            if (error instanceof OutputSchemaError)
+                throw error;
+            throw invalid(`${path} cannot be read (${error.code ?? 'error'})`);
+        }
+        let schema;
+        try {
+            schema = JSON.parse(text);
+        }
+        catch {
+            throw invalid(`${path} is not valid JSON`);
+        }
+        return OutputSchemaContract.fromSchema(schema);
+    }
+    static fromSchema(schema) {
+        if (typeof schema !== 'boolean' && !isSchemaObject(schema))
+            throw invalid('schema must be an object or boolean');
+        return new OutputSchemaContract(schema);
+    }
+    /** Text appended to each schema-bound prompt so the model knows the contract up front. */
+    promptContract() {
+        return 'Output contract: end this task with a final message that is exactly one JSON document '
+            + '(no prose, no Markdown code fences) that validates against this JSON Schema:\n'
+            + JSON.stringify(this.root);
+    }
+    repairPrompt(errors) {
+        return 'Your final message did not satisfy the required JSON Schema:\n'
+            + errors.slice(0, OUTPUT_SCHEMA_LIMITS.reportedErrors).map(error => `- ${error}`).join('\n')
+            + '\nReply now with only the corrected JSON document (no prose, no Markdown code fences). '
+            + 'This is the only repair attempt.';
+    }
+    validateMessage(text) {
+        const trimmed = text?.trim() ?? '';
+        if (!trimmed)
+            return { ok: false, errors: ['$: no final assistant message was produced'] };
+        const fenced = /^```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n```$/.exec(trimmed);
+        let value;
+        try {
+            value = JSON.parse(fenced ? fenced[1] : trimmed);
+        }
+        catch {
+            return { ok: false, errors: ['$: final message is not a single JSON document'] };
+        }
+        const errors = [];
+        this.steps = 0;
+        try {
+            this.check(value, this.root, '$', 0, errors);
+        }
+        catch (error) {
+            if (!(error instanceof ValidationLimitExceeded))
+                throw error;
+            return { ok: false, errors: [...errors.slice(0, OUTPUT_SCHEMA_LIMITS.reportedErrors - 1), error.message] };
+        }
+        return errors.length === 0 ? { ok: true, value, json: JSON.stringify(value) } : { ok: false, errors };
+    }
+    compile(schema, path, depth, pointer) {
+        if (depth > OUTPUT_SCHEMA_LIMITS.depth)
+            throw invalid(`schema nesting exceeds ${OUTPUT_SCHEMA_LIMITS.depth} at ${path}`);
+        this.schemaPointers.add(encodePointer(pointer));
+        if (typeof schema === 'boolean')
+            return;
+        if (!isSchemaObject(schema))
+            throw invalid(`schema must be an object or boolean at ${path}`);
+        for (const [keyword, value] of Object.entries(schema)) {
+            const at = `${path}.${keyword}`;
+            if (ANNOTATIONS.has(keyword))
+                continue;
+            if (SCHEMA_MAP_KEYWORDS.has(keyword)) {
+                if (!isSchemaObject(value))
+                    throw invalid(`"${keyword}" must be an object at ${path}`);
+                for (const [key, child] of Object.entries(value))
+                    this.compile(child, childPath(at, key), depth + 1, [...pointer, keyword, key]);
+            }
+            else if (SCHEMA_LIST_KEYWORDS.has(keyword)) {
+                if (!Array.isArray(value) || value.length === 0)
+                    throw invalid(`"${keyword}" must be a non-empty array at ${path}`);
+                value.forEach((child, index) => this.compile(child, `${at}[${index}]`, depth + 1, [...pointer, keyword, String(index)]));
+            }
+            else if (SCHEMA_KEYWORDS.has(keyword)) {
+                this.compile(value, at, depth + 1, [...pointer, keyword]);
+            }
+            else if (COUNT_KEYWORDS.has(keyword)) {
+                if (!Number.isSafeInteger(value) || value < 0)
+                    throw invalid(`"${keyword}" must be a non-negative integer at ${path}`);
+            }
+            else if (NUMBER_KEYWORDS.has(keyword)) {
+                if (typeof value !== 'number' || !Number.isFinite(value))
+                    throw invalid(`"${keyword}" must be a number at ${path}`);
+            }
+            else if (OTHER_KEYWORDS.has(keyword)) {
+                this.compileOther(keyword, value, path);
+            }
+            else {
+                throw invalid(`unsupported keyword "${keyword}" at ${path}`);
+            }
+        }
+    }
+    compileOther(keyword, value, path) {
+        switch (keyword) {
+            case 'type': {
+                const types = Array.isArray(value) ? value : [value];
+                for (const type of types) {
+                    if (typeof type !== 'string' || !JSON_TYPES.has(type))
+                        throw invalid(`invalid type ${JSON.stringify(type)} at ${path}`);
+                }
+                return;
+            }
+            case 'enum':
+                if (!Array.isArray(value) || value.length === 0)
+                    throw invalid(`"enum" must be a non-empty array at ${path}`);
+                return;
+            case 'required':
+                if (!Array.isArray(value) || !value.every(item => typeof item === 'string')) {
+                    throw invalid(`"required" must be an array of strings at ${path}`);
+                }
+                return;
+            case 'uniqueItems':
+                if (typeof value !== 'boolean')
+                    throw invalid(`"uniqueItems" must be a boolean at ${path}`);
+                return;
+            case 'pattern':
+                if (typeof value !== 'string')
+                    throw invalid(`invalid pattern at ${path}`);
+                try {
+                    this.patterns.set(value, new RegExp(value, 'u'));
+                }
+                catch {
+                    throw invalid(`invalid pattern at ${path}`);
+                }
+                return;
+            case '$ref':
+                if (typeof value !== 'string' || (value !== '#' && !value.startsWith('#/'))) {
+                    throw invalid(`only local "#/..." $ref targets are supported at ${path}`);
+                }
+                // Resolved once the whole schema is compiled (see the constructor).
+                this.refSites.push({ ref: value, path });
+                return;
+            default:
+                return; // const: any JSON value
+        }
+    }
+    matches(value, schema, depth) {
+        const errors = [];
+        this.check(value, schema, '$', depth, errors);
+        return errors.length === 0;
+    }
+    check(value, schema, path, depth, errors) {
+        const report = (message) => {
+            if (errors.length < OUTPUT_SCHEMA_LIMITS.reportedErrors)
+                errors.push(`${path}: ${message}`);
+        };
+        if (depth > OUTPUT_SCHEMA_LIMITS.depth)
+            throw new ValidationLimitExceeded(`${path}: nesting exceeds ${OUTPUT_SCHEMA_LIMITS.depth}`);
+        this.steps += 1;
+        if (this.steps > OUTPUT_SCHEMA_LIMITS.validationSteps)
+            throw new ValidationLimitExceeded('$: validation budget exceeded');
+        if (schema === true)
+            return;
+        if (schema === false)
+            return report('schema false rejects every value');
+        if (typeof schema.$ref === 'string') {
+            this.check(value, this.refTargets.get(schema.$ref), path, depth + 1, errors);
+        }
+        if (schema.type !== undefined) {
+            const types = (Array.isArray(schema.type) ? schema.type : [schema.type]);
+            if (!types.some(type => typeMatches(value, type)))
+                return report(`expected ${types.join(' or ')}`);
+        }
+        if (Array.isArray(schema.enum) && !schema.enum.some(option => canonical(option) === canonical(value))) {
+            report(`must be one of ${JSON.stringify(schema.enum)}`);
+        }
+        if (Object.hasOwn(schema, 'const') && canonical(schema.const) !== canonical(value)) {
+            report(`must equal ${JSON.stringify(schema.const)}`);
+        }
+        if (typeof value === 'string')
+            this.checkString(value, schema, report);
+        if (typeof value === 'number')
+            this.checkNumber(value, schema, report);
+        if (Array.isArray(value))
+            this.checkArray(value, schema, path, depth, errors, report);
+        if (isSchemaObject(value))
+            this.checkObject(value, schema, path, depth, errors, report);
+        if (Array.isArray(schema.allOf)) {
+            for (const child of schema.allOf)
+                this.check(value, child, path, depth + 1, errors);
+        }
+        if (Array.isArray(schema.anyOf) && !schema.anyOf.some(child => this.matches(value, child, depth + 1))) {
+            report('must match at least one schema in anyOf');
+        }
+        if (Array.isArray(schema.oneOf)) {
+            const matched = schema.oneOf.filter(child => this.matches(value, child, depth + 1)).length;
+            if (matched !== 1)
+                report(`must match exactly one schema in oneOf (matched ${matched})`);
+        }
+        if (schema.not !== undefined && this.matches(value, schema.not, depth + 1)) {
+            report('must not match the schema in not');
+        }
+    }
+    checkString(value, schema, report) {
+        const length = codePoints(value);
+        if (typeof schema.minLength === 'number' && length < schema.minLength)
+            report(`length ${length} is below minLength ${schema.minLength}`);
+        if (typeof schema.maxLength === 'number' && length > schema.maxLength)
+            report(`length ${length} exceeds maxLength ${schema.maxLength}`);
+        if (typeof schema.pattern === 'string' && !this.patterns.get(schema.pattern).test(value)) {
+            report(`does not match pattern ${JSON.stringify(schema.pattern)}`);
+        }
+    }
+    checkNumber(value, schema, report) {
+        if (typeof schema.minimum === 'number' && value < schema.minimum)
+            report(`${value} is below minimum ${schema.minimum}`);
+        if (typeof schema.maximum === 'number' && value > schema.maximum)
+            report(`${value} exceeds maximum ${schema.maximum}`);
+        if (typeof schema.exclusiveMinimum === 'number' && value <= schema.exclusiveMinimum) {
+            report(`${value} is not above exclusiveMinimum ${schema.exclusiveMinimum}`);
+        }
+        if (typeof schema.exclusiveMaximum === 'number' && value >= schema.exclusiveMaximum) {
+            report(`${value} is not below exclusiveMaximum ${schema.exclusiveMaximum}`);
+        }
+    }
+    checkArray(value, schema, path, depth, errors, report) {
+        if (typeof schema.minItems === 'number' && value.length < schema.minItems)
+            report(`${value.length} items is below minItems ${schema.minItems}`);
+        if (typeof schema.maxItems === 'number' && value.length > schema.maxItems)
+            report(`${value.length} items exceeds maxItems ${schema.maxItems}`);
+        if (schema.uniqueItems === true && new Set(value.map(canonical)).size !== value.length)
+            report('items must be unique');
+        if (schema.items !== undefined) {
+            value.forEach((item, index) => this.check(item, schema.items, `${path}[${index}]`, depth + 1, errors));
+        }
+    }
+    checkObject(value, schema, path, depth, errors, report) {
+        const keys = Object.keys(value);
+        if (typeof schema.minProperties === 'number' && keys.length < schema.minProperties) {
+            report(`${keys.length} properties is below minProperties ${schema.minProperties}`);
+        }
+        if (typeof schema.maxProperties === 'number' && keys.length > schema.maxProperties) {
+            report(`${keys.length} properties exceeds maxProperties ${schema.maxProperties}`);
+        }
+        for (const name of (schema.required ?? [])) {
+            if (!Object.hasOwn(value, name))
+                report(`missing required property ${JSON.stringify(name)}`);
+        }
+        const properties = isSchemaObject(schema.properties) ? schema.properties : {};
+        for (const key of keys) {
+            const at = childPath(path, key);
+            if (Object.hasOwn(properties, key)) {
+                this.check(value[key], properties[key], at, depth + 1, errors);
+            }
+            else if (schema.additionalProperties === false) {
+                if (errors.length < OUTPUT_SCHEMA_LIMITS.reportedErrors)
+                    errors.push(`${at}: additional property is not allowed`);
+            }
+            else if (schema.additionalProperties !== undefined) {
+                this.check(value[key], schema.additionalProperties, at, depth + 1, errors);
+            }
+        }
+    }
+}

package/dist/headless_trajectory.d.ts

@@ -0,0 +1,44 @@
+export declare const TRAJECTORY_SCHEMA_VERSION = 1;
+export declare const TRAJECTORY_LIMITS: Readonly<{
+    /** Larger serialized tool arguments are replaced by their size. */
+    argsBytes: number;
+    /** Tool results are previewed, never copied whole. */
+    resultPreviewChars: 4096;
+    /** File-change records list at most this many paths. */
+    paths: 64;
+}>;
+export declare class TrajectoryUnavailableError extends Error {
+    readonly code = "trajectory_unavailable";
+    constructor(message: string);
+}
+export type TrajectoryEvent = {
+    type: 'tool_call';
+    tool: string;
+    toolCallId?: string;
+    args: unknown;
+} | {
+    type: 'tool_result';
+    tool: string;
+    toolCallId?: string;
+    success: boolean;
+    result: string;
+} | {
+    type: 'file_change';
+    paths: readonly string[];
+    cwd: string;
+};
+export declare class TrajectoryJsonlWriter {
+    private fd;
+    private readonly path;
+    private seq;
+    private constructor();
+    /** Open (append or create, owner-only) the sink; failure is `trajectory_unavailable`. */
+    static open(path: string): TrajectoryJsonlWriter;
+    isOpen(): boolean;
+    /**
+     * Append one record. A write failure closes the sink and throws once; later
+     * records are dropped, because a broken sink cannot be trusted for order.
+     */
+    record(sessionId: string, turn: number, event: TrajectoryEvent): void;
+    close(): void;
+}

package/dist/headless_trajectory.js

@@ -0,0 +1,113 @@
+/**
+ * `--trajectory-jsonl <path>` sink: one JSON record per tool call, tool
+ * result and tool-reported file change, so a supervisor can render a live
+ * "agent is working" view without parsing the --json event protocol.
+ * (`--json-stream` is unrelated: it means streaming JSONL *input*.)
+ *
+ * Writes are synchronous so record order matches event order and nothing is
+ * lost when headless calls process.exit(). The sink is opened for append, so a
+ * path reused across resumed runs keeps earlier records (`seq` counts within
+ * one process); a regular file is made owner-only because records carry tool
+ * arguments and result previews. A `/dev/fd/N` path writes to an inherited
+ * descriptor and keeps that descriptor's own mode. Pattern exemplar: the autodev runner's
+ * StructuredCliTrajectoryObserver (zapps/zergboard/runner/autodev/src/
+ * structured-cli-agent.ts), which consumes the same tool/file events.
+ */
+import { closeSync, fchmodSync, fstatSync, openSync, writeSync } from 'node:fs';
+import { resolve } from 'node:path';
+export const TRAJECTORY_SCHEMA_VERSION = 1;
+export const TRAJECTORY_LIMITS = Object.freeze({
+    /** Larger serialized tool arguments are replaced by their size. */
+    argsBytes: 8 * 1024,
+    /** Tool results are previewed, never copied whole. */
+    resultPreviewChars: 4096,
+    /** File-change records list at most this many paths. */
+    paths: 64,
+});
+export class TrajectoryUnavailableError extends Error {
+    code = 'trajectory_unavailable';
+    constructor(message) {
+        super(message);
+        this.name = 'TrajectoryUnavailableError';
+    }
+}
+function boundedArgs(args) {
+    const serialized = JSON.stringify(args ?? null);
+    const bytes = Buffer.byteLength(serialized);
+    return bytes > TRAJECTORY_LIMITS.argsBytes ? { truncated: true, bytes } : args ?? null;
+}
+export class TrajectoryJsonlWriter {
+    fd;
+    path;
+    seq = 0;
+    constructor(fd, path) {
+        this.fd = fd;
+        this.path = path;
+    }
+    /** Open (append or create, owner-only) the sink; failure is `trajectory_unavailable`. */
+    static open(path) {
+        let fd = null;
+        try {
+            fd = openSync(path, 'a', 0o600);
+            // The creation mode does not apply to a file that already exists.
+            if (fstatSync(fd).isFile())
+                fchmodSync(fd, 0o600);
+            return new TrajectoryJsonlWriter(fd, path);
+        }
+        catch (error) {
+            if (fd !== null)
+                closeSync(fd);
+            const code = error.code ?? 'error';
+            throw new TrajectoryUnavailableError(`--trajectory-jsonl ${path} cannot be opened (${code})`);
+        }
+    }
+    isOpen() {
+        return this.fd !== null;
+    }
+    /**
+     * Append one record. A write failure closes the sink and throws once; later
+     * records are dropped, because a broken sink cannot be trusted for order.
+     */
+    record(sessionId, turn, event) {
+        if (this.fd === null)
+            return;
+        const base = { v: TRAJECTORY_SCHEMA_VERSION, seq: this.seq + 1, ts: new Date().toISOString(), session_id: sessionId, turn };
+        let record;
+        switch (event.type) {
+            case 'tool_call':
+                record = { ...base, type: event.type, tool: event.tool, tool_call_id: event.toolCallId ?? null, args: boundedArgs(event.args) };
+                break;
+            case 'tool_result':
+                record = { ...base, type: event.type, tool: event.tool, tool_call_id: event.toolCallId ?? null, success: event.success,
+                    result_preview: event.result.slice(0, TRAJECTORY_LIMITS.resultPreviewChars),
+                    result_chars: event.result.length };
+                break;
+            default:
+                // Tools report paths relative to their cwd; records carry absolute paths.
+                record = { ...base, type: event.type, cwd: event.cwd,
+                    paths: event.paths.slice(0, TRAJECTORY_LIMITS.paths).map(path => resolve(event.cwd, path)),
+                    ...(event.paths.length > TRAJECTORY_LIMITS.paths ? { paths_omitted: event.paths.length - TRAJECTORY_LIMITS.paths } : {}) };
+        }
+        try {
+            writeSync(this.fd, `${JSON.stringify(record)}\n`);
+            this.seq += 1;
+        }
+        catch (error) {
+            this.close();
+            const code = error.code ?? 'error';
+            throw new TrajectoryUnavailableError(`--trajectory-jsonl ${this.path} write failed (${code})`);
+        }
+    }
+    close() {
+        if (this.fd === null)
+            return;
+        const fd = this.fd;
+        this.fd = null;
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // The descriptor is already unusable; nothing further can be recorded.
+        }
+    }
+}

package/dist/library.d.ts

@@ -108,6 +108,7 @@ export interface CreateAgentOptions {
      * only when `tools` is already an explicit, bounded vocabulary.
      */
     deferToolSchemas?: boolean;
+    toolGroups?: import('./agent/tools/tool_groups.js').ToolGroupsConfig;
     /**
      * Domain name under `.ztc/domains/<name>/`. Loads its YAML tool definitions
      * and auto-imports the sibling `handlers.{mjs,js,cjs}` bundle.
@@ -129,9 +130,10 @@ export interface CreateAgentOptions {
      */
     maxIterations?: number;
     /**
-     * Max output tokens per API call. When omitted, defers to the
-     * underlying `Agent`'s default (currently 32000; see `agent.ts`). Set
-     * explicitly here if you need to pin the value across ZTC upgrades.
+     * Max output tokens per API call. When omitted, the backend chooses:
+     * Router requests send the model's advertised maximum, the direct
+     * Anthropic backend 32000. Set 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. */
@@ -198,3 +200,4 @@ export interface LibraryAgent {
     runOnCurrentMessages(): AsyncGenerator<AgentEvent, void, void>;
 }
 export declare function createAgent(opts?: CreateAgentOptions): Promise<LibraryAgent>;
+export type { ToolGroupsConfig } from './agent/tools/tool_groups.js';

package/dist/library.js

@@ -124,6 +124,9 @@ export async function createAgent(opts = {}) {
         backend,
         tools,
         alwaysLoadedToolNames: opts.alwaysLoadedToolNames,
+        toolGroups: opts.toolGroups,
+        runtimeFacts: { provider },
+        provider,
         deferToolSchemas: opts.deferToolSchemas ?? (opts.nativeAnthropicMessagesRouter ? false : undefined),
         cwd: opts.cwd,
         pinTaskHeader: opts.nativeAnthropicMessagesRouter ? false : opts.pinTaskHeader,
@@ -158,8 +161,8 @@ export async function createAgent(opts = {}) {
             role: 'user',
             content: userMessage,
             timestamp: new Date(),
-        }),
-        runOnCurrentMessages: () => runAndAppend(agent, libAgent.messages, null),
+        }, model),
+        runOnCurrentMessages: () => runAndAppend(agent, libAgent.messages, null, model),
     };
     return libAgent;
 }
@@ -171,7 +174,7 @@ export async function createAgent(opts = {}) {
  * awaited in the `finally` block so the unsubscribe and any run-side errors
  * flow back to the caller.
  */
-async function* runAndAppend(agent, messages, userMsg) {
+async function* runAndAppend(agent, messages, userMsg, model) {
     if (userMsg)
         messages.push(userMsg);
     const DONE = Symbol('ztc:turn-done');
@@ -211,7 +214,8 @@ async function* runAndAppend(agent, messages, userMsg) {
             toolCalls: result.toolCalls?.length ? result.toolCalls : undefined,
             // Reasoning models expect their trace replayed with the assistant
             // message on later turns; dropping it strips the history.
-            ...(result.reasoning ? { metadata: { reasoningContent: result.reasoning } } : {}),
+            metadata: { ...(result.reasoning ? { reasoningContent: result.reasoning } : {}),
+                ...(result.responseItems ? { openaiResponseItems: result.responseItems, openaiResponseModel: model } : {}) },
         });
     })
         .catch((err) => {

package/dist/lsp/client.js

@@ -6,6 +6,7 @@
  */
 import { spawn } from 'child_process';
 import { EventEmitter } from 'events';
+import { buildUserSubprocessEnv } from '../utils/subprocess_env.js';
 export class LSPClient extends EventEmitter {
     options;
     process = null;
@@ -28,9 +29,11 @@ export class LSPClient extends EventEmitter {
             throw new Error('LSP client already started');
         }
         const { command, args = [], cwd, env } = this.options;
+        // Language servers run workspace code (build scripts, proc macros, local
+        // plugins), so they get the tool-child env plus their configured env.
         this.process = spawn(command, args, {
             cwd,
-            env: { ...process.env, ...env },
+            env: { ...buildUserSubprocessEnv(), ...env },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         this.process.stdout?.on('data', (data) => {

package/dist/lsp/servers.js

@@ -123,10 +123,12 @@ export function getLanguageId(ext) {
  */
 export async function isServerAvailable(config) {
     const { spawn } = await import('child_process');
+    const { buildUserSubprocessEnv } = await import('../utils/subprocess_env.js');
     return new Promise((resolve) => {
         const proc = spawn(config.command, ['--version'], {
             stdio: 'ignore',
             timeout: 5000,
+            env: buildUserSubprocessEnv(),
         });
         proc.on('error', () => resolve(false));
         proc.on('exit', (code) => resolve(code === 0));