@atelierai/uco 1.0.0

package/dist/util/call-control.d.ts

@@ -0,0 +1,30 @@
+import { Command } from 'commander';
+import { type ToolCallConfirmation, type ToolCallDryRun } from '../tool-call-control.js';
+import type { CallOptions } from '../transport/index.js';
+/** Commander-facing names for the shared tool-call control fields. */
+export interface ToolCallCliOptions {
+    control?: string;
+    /** Commander derives this spelling from `--request-id`. */
+    requestId?: string;
+    /** Backwards-compatible programmatic spelling used by library callers. */
+    requestID?: string;
+    callId?: string;
+    correlationId?: string;
+    parentCallId?: string;
+    deadlineUnixMs?: string;
+    /** Shorter compatibility alias for --deadline-unix-ms. */
+    deadline?: string;
+    cancellationId?: string;
+    idempotencyKey?: string;
+    confirm?: boolean;
+    dryRun?: ToolCallDryRun;
+    /** JSON token supplied by a prior confirmation response. */
+    confirmation?: string | ToolCallConfirmation;
+    expectedProjectPath?: string;
+    expectedInstanceId?: string;
+    expectedPid?: string;
+}
+/** Add control metadata options to a tool command without changing its schema. */
+export declare function addToolCallControlOptions(command: Command): Command;
+/** Convert Commander values to the transport's shared CallOptions shape. */
+export declare function toolCallOptionsFromCli(options: ToolCallCliOptions): CallOptions;

package/dist/util/call-control.js

@@ -0,0 +1,123 @@
+import { Option } from 'commander';
+import { ToolCallControlError, resolveToolCallControl, } from '../tool-call-control.js';
+import { CliError } from './errors.js';
+/** Add control metadata options to a tool command without changing its schema. */
+export function addToolCallControlOptions(command) {
+    return command
+        .addOption(new Option('--control <json>', 'JSON control metadata (version-one fields and unknown members).'))
+        .addOption(new Option('--request-id <id>', 'Compatibility/deferred-completion request id.'))
+        .addOption(new Option('--call-id <id>', 'Logical tool-call id (stable across retries).'))
+        .addOption(new Option('--correlation-id <id>', 'Top-level trace correlation id.'))
+        .addOption(new Option('--parent-call-id <id>', 'Immediate parent logical call id.'))
+        .addOption(new Option('--deadline-unix-ms <ms>', 'Absolute Unix timestamp deadline in milliseconds.').conflicts('deadline'))
+        .addOption(new Option('--deadline <ms>', 'Alias for --deadline-unix-ms.').conflicts('deadlineUnixMs'))
+        .addOption(new Option('--cancellation-id <id>', 'Opaque cancellation metadata.'))
+        .addOption(new Option('--idempotency-key <key>', 'Opaque idempotency metadata.'))
+        .addOption(new Option('--confirm', 'Approve a previously returned authoring confirmation record.'))
+        .addOption(new Option('--dry-run <mode>', 'Authoring dry-run mode.').choices(['none', 'validate', 'plan']))
+        .addOption(new Option('--confirmation <json>', 'JSON token returned by confirmation_required or dry-run plan.'))
+        .addOption(new Option('--expected-project-path <path>', 'Fail closed unless the routed Editor reports this project path (identity constraint).'))
+        .addOption(new Option('--expected-instance-id <id>', 'Fail closed unless the routed Editor reports this stable instance id (identity constraint).'))
+        .addOption(new Option('--expected-pid <pid>', 'Fail closed unless the routed Editor runs under this process id (identity constraint).'))
+        .addOption(new Option('--wait-until-idle', 'After the call returns, wait until the Editor stops compiling/importing/reloading (bounded by --idle-timeout-ms).'))
+        .addOption(new Option('--idle-timeout-ms <ms>', 'Bound for --wait-until-idle in milliseconds (default: 120000).'))
+        .addOption(new Option('--wait', 'When the call returns a durable operation handle, poll it to a terminal state and print the terminal envelope.'))
+        .addOption(new Option('--wait-timeout-ms <ms>', 'Bound for --wait in milliseconds (default: 600000).'));
+}
+/** Convert Commander values to the transport's shared CallOptions shape. */
+export function toolCallOptionsFromCli(options) {
+    const control = parseControl(options.control);
+    const deadlineRaw = options.deadlineUnixMs ?? options.deadline;
+    const requestID = options.requestId ?? options.requestID;
+    const confirmation = parseConfirmation(options.confirmation);
+    const expectedPid = parseExpectedPid(options.expectedPid);
+    const values = {
+        ...(control === undefined ? {} : { control }),
+        ...(requestID === undefined ? {} : { requestID }),
+        ...(options.callId === undefined ? {} : { callId: options.callId }),
+        ...(options.correlationId === undefined ? {} : { correlationId: options.correlationId }),
+        ...(options.parentCallId === undefined ? {} : { parentCallId: options.parentCallId }),
+        ...(deadlineRaw === undefined ? {} : { deadlineUnixMs: parseDeadline(deadlineRaw) }),
+        ...(options.cancellationId === undefined ? {} : { cancellationId: options.cancellationId }),
+        ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
+        ...(options.confirm === undefined ? {} : { confirm: options.confirm }),
+        ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+        ...(confirmation === undefined ? {} : { confirmation }),
+        ...(options.expectedProjectPath === undefined ? {} : { expectedProjectPath: options.expectedProjectPath }),
+        ...(options.expectedInstanceId === undefined ? {} : { expectedInstanceId: options.expectedInstanceId }),
+        ...(expectedPid === undefined ? {} : { expectedPid }),
+    };
+    try {
+        const resolved = resolveToolCallControl(values);
+        if (resolved === undefined)
+            return {};
+        return {
+            control: resolved,
+            ...(requestID === undefined ? {} : { requestID }),
+        };
+    }
+    catch (error) {
+        if (error instanceof ToolCallControlError) {
+            throw new CliError(error.message, error.code, 1, false, error.toStructuredError());
+        }
+        throw error;
+    }
+}
+function parseConfirmation(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw))
+        return raw;
+    if (typeof raw !== 'string') {
+        throw new CliError('--confirmation must contain a JSON object', 'invalid_control');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new CliError(`Invalid JSON in --confirmation: ${error instanceof Error ? error.message : String(error)}`, 'invalid_control');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new CliError('--confirmation must contain a JSON object', 'invalid_control');
+    }
+    return parsed;
+}
+function parseControl(raw) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new CliError(`Invalid JSON in --control: ${error instanceof Error ? error.message : String(error)}`, 'invalid_control');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new CliError('--control must contain a JSON object', 'invalid_control');
+    }
+    return parsed;
+}
+function parseDeadline(raw) {
+    if (!/^[0-9]+$/.test(raw)) {
+        throw new CliError('--deadline-unix-ms must be a non-negative integer', 'invalid_control');
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new CliError('--deadline-unix-ms must be a safe non-negative integer', 'invalid_control');
+    }
+    return value;
+}
+function parseExpectedPid(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^[0-9]+$/.test(raw)) {
+        throw new CliError('--expected-pid must be a positive integer', 'invalid_control');
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new CliError('--expected-pid must be a safe positive integer', 'invalid_control');
+    }
+    return value;
+}
+//# sourceMappingURL=call-control.js.map

package/dist/util/call-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-control.js","sourceRoot":"","sources":["../../src/util/call-control.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,MAAM,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GAKvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA0BvC,kFAAkF;AAClF,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,OAAO,OAAO;SACX,SAAS,CAAC,IAAI,MAAM,CAAC,kBAAkB,EAAE,iEAAiE,CAAC,CAAC;SAC5G,SAAS,CAAC,IAAI,MAAM,CAAC,mBAAmB,EAAE,+CAA+C,CAAC,CAAC;SAC3F,SAAS,CAAC,IAAI,MAAM,CAAC,gBAAgB,EAAE,+CAA+C,CAAC,CAAC;SACxF,SAAS,CAAC,IAAI,MAAM,CAAC,uBAAuB,EAAE,iCAAiC,CAAC,CAAC;SACjF,SAAS,CAAC,IAAI,MAAM,CAAC,uBAAuB,EAAE,mCAAmC,CAAC,CAAC;SACnF,SAAS,CAAC,IAAI,MAAM,CAAC,yBAAyB,EAAE,mDAAmD,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;SAC3H,SAAS,CAAC,IAAI,MAAM,CAAC,iBAAiB,EAAE,+BAA+B,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;SACrG,SAAS,CAAC,IAAI,MAAM,CAAC,wBAAwB,EAAE,+BAA+B,CAAC,CAAC;SAChF,SAAS,CAAC,IAAI,MAAM,CAAC,yBAAyB,EAAE,8BAA8B,CAAC,CAAC;SAChF,SAAS,CAAC,IAAI,MAAM,CAAC,WAAW,EAAE,8DAA8D,CAAC,CAAC;SAClG,SAAS,CAAC,IAAI,MAAM,CAAC,kBAAkB,EAAE,yBAAyB,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;SAC1G,SAAS,CAAC,IAAI,MAAM,CAAC,uBAAuB,EAAE,+DAA+D,CAAC,CAAC;SAC/G,SAAS,CAAC,IAAI,MAAM,CAAC,gCAAgC,EAAE,uFAAuF,CAAC,CAAC;SAChJ,SAAS,CAAC,IAAI,MAAM,CAAC,6BAA6B,EAAE,6FAA6F,CAAC,CAAC;SACnJ,SAAS,CAAC,IAAI,MAAM,CAAC,sBAAsB,EAAE,wFAAwF,CAAC,CAAC;SACvI,SAAS,CAAC,IAAI,MAAM,CAAC,mBAAmB,EAAE,mHAAmH,CAAC,CAAC;SAC/J,SAAS,CAAC,IAAI,MAAM,CAAC,wBAAwB,EAAE,gEAAgE,CAAC,CAAC;SACjH,SAAS,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,gHAAgH,CAAC,CAAC;SACjJ,SAAS,CAAC,IAAI,MAAM,CAAC,wBAAwB,EAAE,qDAAqD,CAAC,CAAC,CAAC;AAC5G,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,sBAAsB,CAAC,OAA2B;IAChE,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC;IAC/D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;IACzD,MAAM,YAAY,GAAG,iBAAiB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAG,gBAAgB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAyB;QACnC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;QAC7C,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;QACjD,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACnE,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;QACxF,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;QACrF,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;QACpF,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;QAC3F,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;QAC3F,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QACtE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACnE,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC;QACvD,GAAG,CAAC,OAAO,CAAC,mBAAmB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,EAAE,CAAC;QAC1G,GAAG,CAAC,OAAO,CAAC,kBAAkB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,EAAE,CAAC;QACvG,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;KACtD,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACtC,OAAO;YACL,OAAO,EAAE,QAAQ;YACjB,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;SAClD,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,oBAAoB,EAAE,CAAC;YAC1C,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,iBAAiB,EAAE,CAAC,CAAC;QACrF,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,GAA8C;IACvE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAC/E,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,QAAQ,CAAC,2CAA2C,EAAE,iBAAiB,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAChB,mCAAmC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAC3F,iBAAiB,CAClB,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,QAAQ,CAAC,2CAA2C,EAAE,iBAAiB,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,MAA8B,CAAC;AACxC,CAAC;AAED,SAAS,YAAY,CAAC,GAAuB;IAC3C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAChB,8BAA8B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACtF,iBAAiB,CAClB,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,QAAQ,CAAC,sCAAsC,EAAE,iBAAiB,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,MAAyB,CAAC;AACnC,CAAC;AAED,SAAS,aAAa,CAAC,GAAW;IAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,QAAQ,CAAC,mDAAmD,EAAE,iBAAiB,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,QAAQ,CAAC,wDAAwD,EAAE,iBAAiB,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAuB;IAC/C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,QAAQ,CAAC,2CAA2C,EAAE,iBAAiB,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,QAAQ,CAAC,gDAAgD,EAAE,iBAAiB,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/util/cli-context.d.ts

@@ -0,0 +1,35 @@
+import { Command } from 'commander';
+import { type UnityCoTransport } from '../transport/index.js';
+import { type Resolved } from '../config/resolve.js';
+import { type OutputContext } from './output.js';
+import { CliError, TransportError } from './errors.js';
+export interface GlobalOptions {
+    project?: string;
+    url?: string;
+    token?: string;
+    json?: boolean;
+    verbose?: boolean;
+    timeout?: string;
+    timeoutMs?: string;
+    waitUntilIdle?: boolean;
+    idleTimeoutMs?: string;
+    wait?: boolean;
+    waitTimeoutMs?: string;
+}
+export interface CommandContext {
+    transport: UnityCoTransport;
+    resolved: Resolved;
+    output: OutputContext;
+    timeoutMs: number;
+}
+export interface CommandContextOverrides {
+    /** Command-local positional project. When defined, it wins over root --project. */
+    project?: string;
+}
+export declare function buildContext(opts: GlobalOptions): CommandContext;
+/**
+ * Wrap a command handler so all commands share the same output /
+ * error / exit-code contract.
+ */
+export declare function runCommand<TArgs extends unknown[]>(cmd: Command, handler: (ctx: CommandContext, ...args: TArgs) => Promise<unknown> | unknown, contextOverrides?: CommandContextOverrides): (...args: TArgs) => Promise<void>;
+export { CliError, TransportError };

package/dist/util/cli-context.js

@@ -0,0 +1,316 @@
+// Shared CLI plumbing — resolves a transport from global options,
+// runs a command body, and handles output / exit code uniformly.
+import process from 'node:process';
+import { RestTransport } from '../transport/index.js';
+import { resolveConnection } from '../config/resolve.js';
+import { printError, printInfo, printResult } from './output.js';
+import { CliError, TransportError } from './errors.js';
+import { toolPayloadRecords } from './tool-payload.js';
+import { MAX_TIMER_MILLISECONDS, parseBoundedInteger } from './timeout.js';
+import { ToolCallControlError } from '../tool-call-control.js';
+import { waitForEditorIdle } from './idle-wait.js';
+import { inspectInitialOperationState, waitForDurableOperation } from './operation-wait.js';
+export function buildContext(opts) {
+    const projectPath = opts.project ?? defaultProjectPathFromCwd();
+    const resolved = resolveConnection({
+        projectPath,
+        url: opts.url,
+        token: opts.token,
+    });
+    const timeoutMs = parseTimeout(opts.timeoutMs ?? opts.timeout, opts.timeoutMs !== undefined ? '--timeout-ms' : '--timeout');
+    const transport = new RestTransport({
+        baseUrl: resolved.baseUrl,
+        token: resolved.token,
+        defaultTimeoutMs: timeoutMs,
+    });
+    return {
+        transport,
+        resolved,
+        output: { json: Boolean(opts.json), verbose: Boolean(opts.verbose) },
+        timeoutMs,
+    };
+}
+/**
+ * Wrap a command handler so all commands share the same output /
+ * error / exit-code contract.
+ */
+export function runCommand(cmd, handler, contextOverrides) {
+    return async (...args) => {
+        const opts = mergeGlobalOptions(cmd);
+        if (contextOverrides?.project !== undefined) {
+            opts.project = contextOverrides.project;
+        }
+        let ctx;
+        try {
+            ctx = buildContext(opts);
+        }
+        catch (err) {
+            printError({ json: Boolean(opts.json), verbose: Boolean(opts.verbose) }, err);
+            await exitAfterFlush(1);
+            return;
+        }
+        try {
+            let result = await handler(ctx, ...args);
+            const reportedFailure = toolReportedFailure(result);
+            if (reportedFailure !== null)
+                throw reportedFailure;
+            if (opts.wait === true) {
+                // Terminal-state wait for durable operations (COCli-03), with
+                // graceful degradation (COCli-11): a durable handle is polled to its
+                // terminal record; a response that already carries a terminal status
+                // is mapped directly onto the exit map; a response with neither is
+                // printed as-is with a hint instead of failing the whole invocation —
+                // the tool call itself succeeded, only the wait protocol does not
+                // apply (non-durable tool or an older plugin).
+                const initial = inspectInitialOperationState(result);
+                if (initial.operationId !== undefined) {
+                    const terminal = await waitForDurableOperation(ctx.transport, result, {
+                        timeoutMs: parseWaitTimeout(opts.waitTimeoutMs),
+                    });
+                    if (terminal.status === 'failed') {
+                        throw new CliError(`Editor operation '${terminal.operationId}' failed.`, 'operation-failed', 5, false, terminal.record);
+                    }
+                    if (terminal.status === 'cancelled') {
+                        throw new CliError(`Editor operation '${terminal.operationId}' was cancelled.`, 'operation-cancelled', 6, false, terminal.record);
+                    }
+                    if (terminal.status === 'interrupted') {
+                        throw new CliError(`Editor operation '${terminal.operationId}' was interrupted.`, 'operation-interrupted', 7, false, terminal.record);
+                    }
+                    result = terminal.record;
+                }
+                else if (initial.terminalStatus === 'failed') {
+                    throw new CliError('The tool reported a terminal failure in its response.', 'operation-failed', 5, false, result);
+                }
+                else if (initial.terminalStatus === 'cancelled') {
+                    throw new CliError('The tool reported a cancelled operation in its response.', 'operation-cancelled', 6, false, result);
+                }
+                else if (initial.terminalStatus === 'interrupted') {
+                    throw new CliError('The tool reported an interrupted operation in its response.', 'operation-interrupted', 7, false, result);
+                }
+                else if (initial.terminalStatus === undefined) {
+                    printInfo(ctx.output, 'Response carried no durable operation handle; --wait polls only durable operations. ' +
+                        'For non-durable tools poll the relevant surface instead (e.g. build-job-get, tests-job-list, editor-operation-get).');
+                }
+            }
+            if (opts.waitUntilIdle === true) {
+                // Opt-in post-call idle gate (COCli-05): hold the result until the
+                // Editor stops compiling/importing/reloading, bounded by the caller's
+                // timeout. A timeout fails the invocation naming the last blocker.
+                await waitForEditorIdle(ctx.transport, {
+                    timeoutMs: parseIdleTimeout(opts.idleTimeoutMs),
+                    requestTimeoutMs: ctx.timeoutMs,
+                });
+            }
+            if (result !== undefined) {
+                printResult(ctx.output, result);
+            }
+        }
+        catch (err) {
+            printError(ctx.output, err);
+            await exitAfterFlush(transportExitCode(err));
+        }
+    };
+}
+/**
+ * Documented failure vocabulary for wrapper-position `status` members
+ * (COCli-04). Values outside this vocabulary (success, queued, running,
+ * pending, …) never flag a failure.
+ */
+const TOOL_FAILURE_STATUS_VOCABULARY = new Set(['error', 'failed']);
+function toolReportedFailure(result) {
+    for (const payload of toolPayloadRecords(result)) {
+        const failure = wrapperFailureDetail(payload);
+        if (failure === null)
+            continue;
+        return new CliError(failure, 'tool-reported-failure', 5, false, payload);
+    }
+    return null;
+}
+/**
+ * Detect an inner failure indicator at the bridge's known wrapper positions:
+ * `ok`/`Ok` false, `isError`/`IsError` true, a `status`/`Status` in the
+ * documented failure vocabulary, or an `error`/`Error` member carrying a
+ * message or code. The scan stays bounded to wrapper records and never
+ * recurses into arbitrary application data.
+ */
+function wrapperFailureDetail(payload) {
+    if (payload['Ok'] === false || payload['ok'] === false) {
+        return detailMessage(payload) ?? 'Unity tool reported failure.';
+    }
+    if (payload['IsError'] === true || payload['isError'] === true) {
+        return detailMessage(payload) ?? 'Unity tool reported an inner error (isError=true).';
+    }
+    for (const key of ['status', 'Status']) {
+        const value = payload[key];
+        if (typeof value === 'string' && TOOL_FAILURE_STATUS_VOCABULARY.has(value.toLowerCase())) {
+            return detailMessage(payload) ?? `Unity tool reported failure status '${value}'.`;
+        }
+    }
+    const errorMember = payload['Error'] ?? payload['error'];
+    if (errorMember !== undefined && errorMember !== null) {
+        if (typeof errorMember === 'string' && errorMember.trim().length > 0) {
+            return errorMember;
+        }
+        if (typeof errorMember === 'object' && !Array.isArray(errorMember)) {
+            const errorRecord = errorMember;
+            const message = [errorRecord['message'], errorRecord['Message']]
+                .find((value) => typeof value === 'string' && value.trim().length > 0);
+            const code = [errorRecord['code'], errorRecord['Code']]
+                .find((value) => typeof value === 'string' && value.trim().length > 0);
+            if (message !== undefined || code !== undefined) {
+                return message !== undefined && code !== undefined
+                    ? `${message} (${code})`
+                    : (message ?? `Unity tool reported error code '${code}'.`);
+            }
+        }
+    }
+    return null;
+}
+function detailMessage(payload) {
+    for (const key of ['Message', 'message']) {
+        const value = payload[key];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value;
+    }
+    for (const key of ['Error', 'error']) {
+        const value = payload[key];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value;
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            const nested = value;
+            const nestedMessage = [nested['message'], nested['Message']]
+                .find((entry) => typeof entry === 'string' && entry.trim().length > 0);
+            if (nestedMessage !== undefined)
+                return nestedMessage;
+        }
+    }
+    return undefined;
+}
+function mergeGlobalOptions(cmd) {
+    // Collect opts along the chain root → … → cmd so that a value parsed at a
+    // deeper level (an option placed after the subcommand name, enabled by
+    // enablePositionalOptions + the passthrough registrations) overrides the
+    // root's value for the same key. The previous child → root walk let the
+    // root's defaults clobber explicitly-passed subcommand values.
+    const chain = [];
+    let current = cmd;
+    while (current) {
+        chain.unshift(current);
+        current = current.parent ?? null;
+    }
+    const collected = {};
+    for (const node of chain) {
+        Object.assign(collected, node.opts());
+    }
+    return collected;
+}
+function defaultProjectPathFromCwd() {
+    // If the CWD looks like a Unity project, use it; otherwise let
+    // resolveConnection() complain.
+    const cwd = process.cwd();
+    return cwd;
+}
+function parseTimeout(raw, option) {
+    if (!raw)
+        return 60_000;
+    return parseBoundedInteger(raw, {
+        option,
+        unit: 'milliseconds',
+        maximum: MAX_TIMER_MILLISECONDS,
+    });
+}
+const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
+const DEFAULT_OPERATION_WAIT_TIMEOUT_MS = 600_000;
+function parseIdleTimeout(raw) {
+    if (!raw)
+        return DEFAULT_IDLE_TIMEOUT_MS;
+    return parseBoundedInteger(raw, {
+        option: '--idle-timeout-ms',
+        unit: 'milliseconds',
+        maximum: MAX_TIMER_MILLISECONDS,
+    });
+}
+function parseWaitTimeout(raw) {
+    if (!raw)
+        return DEFAULT_OPERATION_WAIT_TIMEOUT_MS;
+    return parseBoundedInteger(raw, {
+        option: '--wait-timeout-ms',
+        unit: 'milliseconds',
+        maximum: MAX_TIMER_MILLISECONDS,
+    });
+}
+/**
+ * Documented exit-code map (docs/cli.md):
+ *   0 success · 1 unexpected · 2 connection-refused · 3 timeout/wait-timeout/
+ *   deadline-exceeded · 4 HTTP-level server rejection · 5 tool-reported
+ *   failure (incl. detected inner failures) · 6 cancelled · 7 interrupted.
+ */
+function transportExitCode(err) {
+    if (err instanceof TransportError) {
+        switch (err.kind) {
+            case 'connection-refused':
+                return 2;
+            case 'timeout':
+                return 3;
+            case 'http':
+                return 4;
+            default:
+                return 1;
+        }
+    }
+    if (err instanceof ToolCallControlError) {
+        switch (err.code) {
+            case 'cancelled':
+                return 6;
+            case 'deadline_exceeded':
+                return 3;
+            case 'tool_execution_failed':
+                return 5;
+            default:
+                // Any other structured server rejection (confirmation_required,
+                // invalid_control, identity_mismatch, editor_not_ready, …) is an
+                // HTTP-level rejection of the call.
+                return 4;
+        }
+    }
+    if (err instanceof CliError)
+        return err.exitCode;
+    return 1;
+}
+// Re-export so command files can use a single import.
+export { CliError, TransportError };
+/**
+ * Exit after pending stdout/stderr writes flush. Calling process.exit() with a
+ * pipe write still in flight aborts the process on Windows (libuv asserts on
+ * the closing handle), which surfaces as exit code 0xC0000409 instead of the
+ * documented code.
+ */
+function exitAfterFlush(code) {
+    process.exitCode = code;
+    const flush = (stream) => new Promise((resolve) => {
+        if (stream.writableLength === 0)
+            resolve();
+        else
+            stream.once('drain', () => resolve());
+    });
+    // Exiting exactly as a socket closes aborts the process on Windows
+    // (0xC0000409) instead of reporting the documented code, so a process that
+    // holds network handles gets one bounded settle window before the hard
+    // exit. When no network handles are active (unit tests, pure-local
+    // failures) the exit is immediate — mocked-timer environments never
+    // observe a forced wait. The global fetch dispatcher is deliberately NOT
+    // closed: it is process-global, and closing it would poison every later
+    // fetch in host processes (test workers) that reuse this module.
+    const active = typeof process.getActiveResourcesInfo === 'function'
+        ? process.getActiveResourcesInfo()
+        : [];
+    const hasNetwork = active.some((resource) => resource === 'TCPSocketWrap' || resource === 'TCPWrap' || resource === 'Socket');
+    const drained = Promise.all([flush(process.stdout), flush(process.stderr)]);
+    const settle = hasNetwork
+        ? new Promise((resolve) => setTimeout(resolve, 25).unref())
+        : Promise.resolve();
+    return Promise.race([drained.then(() => settle), new Promise((resolve) => setTimeout(resolve, 1_000).unref())])
+        .catch(() => undefined)
+        .then(() => process.exit(code));
+}
+//# sourceMappingURL=cli-context.js.map

package/dist/util/cli-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-context.js","sourceRoot":"","sources":["../../src/util/cli-context.ts"],"names":[],"mappings":"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"}

package/dist/util/errors.d.ts

@@ -0,0 +1,31 @@
+export type TransportErrorKind = 'http' | 'timeout' | 'connection-refused' | 'connection-reset' | 'dns' | 'unknown';
+export interface TransportErrorFields {
+    kind: TransportErrorKind;
+    url: string;
+    method: string;
+    message: string;
+    status?: number;
+    statusText?: string;
+    body?: unknown;
+    /** Logical call id for tool-call requests (present when the caller sent one). */
+    callId?: string;
+    cause?: Error;
+}
+export declare class TransportError extends Error {
+    readonly kind: TransportErrorKind;
+    readonly url: string;
+    readonly method: string;
+    readonly status: number | undefined;
+    readonly statusText: string | undefined;
+    readonly body: unknown;
+    readonly callId: string | undefined;
+    constructor(fields: TransportErrorFields);
+    toJSON(): Record<string, unknown>;
+}
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly retryable: boolean;
+    readonly details: unknown;
+    constructor(message: string, code?: string, exitCode?: number, retryable?: boolean, details?: unknown);
+}

package/dist/util/errors.js

@@ -0,0 +1,52 @@
+// Typed errors — let the CLI surface format them with a stable shape.
+//
+// Every command path should funnel non-fatal failures through
+// formatAndExit() in cli-context.ts so JSON / pretty modes both produce
+// machine-parseable output.
+export class TransportError extends Error {
+    kind;
+    url;
+    method;
+    status;
+    statusText;
+    body;
+    callId;
+    constructor(fields) {
+        super(fields.message, { cause: fields.cause });
+        this.name = 'TransportError';
+        this.kind = fields.kind;
+        this.url = fields.url;
+        this.method = fields.method;
+        this.status = fields.status;
+        this.statusText = fields.statusText;
+        this.body = fields.body;
+        this.callId = fields.callId;
+    }
+    toJSON() {
+        return {
+            error: true,
+            kind: this.kind,
+            url: this.url,
+            method: this.method,
+            message: this.message,
+            ...(this.status !== undefined ? { status: this.status, statusText: this.statusText } : {}),
+            ...(this.body !== undefined ? { body: this.body } : {}),
+            ...(this.callId !== undefined ? { callId: this.callId } : {}),
+        };
+    }
+}
+export class CliError extends Error {
+    code;
+    exitCode;
+    retryable;
+    details;
+    constructor(message, code = 'cli-error', exitCode = 1, retryable = false, details) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.exitCode = exitCode;
+        this.retryable = retryable;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/util/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,8DAA8D;AAC9D,wEAAwE;AACxE,4BAA4B;AAuB5B,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAqB;IACzB,GAAG,CAAS;IACZ,MAAM,CAAS;IACf,MAAM,CAAqB;IAC3B,UAAU,CAAqB;IAC/B,IAAI,CAAU;IACd,MAAM,CAAqB;IAEpC,YAAY,MAA4B;QACtC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,MAAM;QACJ,OAAO;YACL,KAAK,EAAE,IAAI;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1F,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,QAAQ,CAAS;IACjB,SAAS,CAAU;IACnB,OAAO,CAAU;IAE1B,YAAY,OAAe,EAAE,IAAI,GAAG,WAAW,EAAE,QAAQ,GAAG,CAAC,EAAE,SAAS,GAAG,KAAK,EAAE,OAAiB;QACjG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/util/idle-wait.d.ts

@@ -0,0 +1,17 @@
+import type { UnityCoTransport } from '../transport/index.js';
+export interface IdleWaitOptions {
+    /** Absolute bound for the whole wait. */
+    timeoutMs: number;
+    /** Poll interval (default 1s; readiness settles in frames, not minutes). */
+    intervalMs?: number;
+    /** Per-request timeout for health/probe calls (defaults to the CLI request timeout). */
+    requestTimeoutMs?: number;
+}
+/**
+ * Poll the readiness health stages and the editor state probe until the Editor
+ * reports not compiling, not updating, not importing, not domain-reloading,
+ * and no play-mode transition. Resolves when idle; throws the documented
+ * wait-timeout failure (exit 3) naming the last blocking stage and cause when
+ * the bound expires.
+ */
+export declare function waitForEditorIdle(transport: UnityCoTransport, options: IdleWaitOptions): Promise<void>;