@atelierai/uco 1.0.0

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

@@ -0,0 +1,255 @@
+/**
+ * Transport-neutral tool-call control metadata.
+ *
+ * This module is deliberately independent from the HTTP and WebSocket
+ * adapters. Adapters can normalize a call once, carry the returned request
+ * across a hop, and use the runtime context without ever serializing its
+ * AbortSignal.
+ */
+export declare const TOOL_CALL_CONTROL_VERSION: 1;
+/** Alias retained for callers that prefer an explicit supported-version name. */
+export declare const SUPPORTED_TOOL_CALL_CONTROL_VERSION: 1;
+/** A linked runtime signal and the cleanup hook for its listeners. */
+export interface LinkedAbortSignals {
+    signal?: AbortSignal;
+    dispose: () => void;
+}
+/**
+ * Link all supplied caller/runtime signals without ever putting the derived
+ * signal on the wire.  A single signal is returned as-is; multiple signals
+ * share one controller and are detached by `dispose()` when the operation
+ * settles.
+ */
+export declare function linkAbortSignals(...signals: Array<AbortSignal | undefined>): LinkedAbortSignals;
+export type ToolCallErrorCode = 'invalid_control' | 'unsupported_control_version' | 'deadline_exceeded' | 'cancelled' | 'middleware_rejected' | 'tool_execution_failed' | 'validation_failed' | 'confirmation_required' | 'confirmation_invalid' | 'confirmation_expired' | 'confirmation_stale' | 'dry_run_unsupported' | 'path_policy_violation' | 'safety_unsupported' | 'undo_unavailable' | 'authoring_transaction_failed' | 'editor_not_ready' | 'editor_settling' | 'operation_capacity_exceeded' | 'operation_not_found' | 'operation_owner_missing' | 'operation_interrupted' | 'cancellation_unavailable' | 'scheduling_metadata_invalid' | 'identity_mismatch' | 'identity_unavailable';
+/** The only dry-run directives accepted by the g-005 authoring seam. */
+export type ToolCallDryRun = 'none' | 'validate' | 'plan';
+/**
+ * Caller-asserted Editor identity constraints (COCli-01). Evaluated by the Node
+ * server against the routed connection's handshake identity after connection
+ * resolution and before forwarding; any mismatch or unavailable member rejects
+ * the call fail-closed. Paths compare case-insensitively on Windows; instance
+ * ids and PIDs compare exactly.
+ */
+export interface ToolCallIdentityConstraints {
+    projectPath?: string;
+    instanceId?: string;
+    pid?: number;
+}
+/** Opaque confirmation material returned by a Unity plan. */
+export interface ToolCallConfirmation {
+    planId: string;
+    planHash: string;
+    expiresAtUnixMs: number;
+    /** Forward-compatible token members are retained but never interpreted by Node. */
+    [member: string]: unknown;
+}
+/** The serializable, version-one control envelope. */
+export interface ToolCallControl {
+    version?: number | null;
+    callId?: string | null;
+    correlationId?: string | null;
+    parentCallId?: string | null;
+    deadlineUnixMs?: number | null;
+    cancellationId?: string | null;
+    idempotencyKey?: string | null;
+    /** Explicit approval directive; it is not sufficient without a confirmation token. */
+    confirm?: boolean | null;
+    /** Omitted means `none`; any supplied value must be one of the three literals. */
+    dryRun?: ToolCallDryRun | null;
+    /** Opaque confirmation token produced by Unity's policy. */
+    confirmation?: ToolCallConfirmation | null;
+    /** Optional Editor identity constraints (fail-closed at Node routing time). */
+    expectedProjectPath?: string | null;
+    expectedInstanceId?: string | null;
+    expectedPid?: number | null;
+    /** Forward-compatible fields unknown to this version. */
+    [member: string]: unknown;
+}
+/** A normalized request accepted by the Node adapters. */
+export interface ToolCallRequest {
+    name: string;
+    arguments: Record<string, unknown>;
+    requestID?: string | null;
+    control?: ToolCallControl | null;
+    [member: string]: unknown;
+}
+/** Runtime-only context. `signal` is intentionally not serializable. */
+export interface ToolCallContext {
+    version: typeof TOOL_CALL_CONTROL_VERSION;
+    requestID: string;
+    /** Readable alias for integrations that use lower-camel request naming. */
+    readonly requestId?: string;
+    callId: string;
+    correlationId: string;
+    parentCallId?: string;
+    deadlineUnixMs?: number;
+    cancellationId?: string;
+    idempotencyKey?: string;
+    confirm?: boolean;
+    dryRun: ToolCallDryRun;
+    confirmation?: ToolCallConfirmation;
+    /** Caller-asserted identity constraints present on a controlled call. */
+    identity?: ToolCallIdentityConstraints;
+    signal: AbortSignal;
+    /** Readable alias; both names refer to the same runtime signal. */
+    readonly abortSignal?: AbortSignal;
+    legacy: boolean;
+    unknownMembers: Record<string, unknown>;
+}
+export interface NormalizedToolCall {
+    request: ToolCallRequest & {
+        requestID: string;
+    };
+    context: ToolCallContext;
+}
+/** The controlled body shape sent to a REST endpoint. */
+export interface SerializedToolCallBody {
+    arguments: Record<string, unknown>;
+    control: ToolCallControl;
+    requestID?: string;
+    [member: string]: unknown;
+}
+/** A normalized call together with its controlled REST representation. */
+export interface SerializedToolCall {
+    body: Record<string, unknown> | SerializedToolCallBody;
+    request: ToolCallRequest & {
+        requestID: string;
+    };
+    context: ToolCallContext;
+}
+export interface NormalizeToolCallOptions {
+    /** Test and adapter hook for deterministic ids. */
+    generateId?: () => string;
+    /** Runtime cancellation signal; it never enters the wire request. */
+    signal?: AbortSignal;
+    /** Per-hop WebSocket correlation; deliberately not copied into context ids. */
+    envelopeId?: string;
+}
+/** Values accepted by transport/library adapters when selecting a context. */
+export interface ToolCallOptionValues {
+    /** Serializable control metadata or a runtime context to serialize. */
+    control?: ToolCallControl | ToolCallContext | null;
+    /** Alias for callers that already hold a runtime context. */
+    context?: ToolCallContext | null;
+    /** Compatibility/deferred-completion id when it differs from callId. */
+    requestID?: string | null;
+    callId?: string | null;
+    correlationId?: string | null;
+    parentCallId?: string | null;
+    deadlineUnixMs?: number | null;
+    cancellationId?: string | null;
+    idempotencyKey?: string | null;
+    /** Optional explicit control version (normally supplied through `control`). */
+    controlVersion?: number | null;
+    confirm?: boolean | null;
+    dryRun?: ToolCallDryRun | null;
+    confirmation?: ToolCallConfirmation | null;
+    expectedProjectPath?: string | null;
+    expectedInstanceId?: string | null;
+    expectedPid?: number | null;
+}
+/** Options used when converting a normalized call to a REST body. */
+export interface ToolCallSerializationOptions extends NormalizeToolCallOptions {
+    requestID?: string | null;
+}
+export interface DeriveChildToolCallOptions extends NormalizeToolCallOptions {
+    /** Optional compatibility/deferred-completion id for the child. */
+    requestID?: string;
+}
+export interface ToolCallStructuredError {
+    code: ToolCallErrorCode;
+    message: string;
+    retryable: boolean;
+    callId?: string;
+    correlationId?: string;
+    details?: Record<string, unknown>;
+}
+/** Alias matching the terminology used by the wire contract. */
+export type StructuredToolCallError = ToolCallStructuredError;
+export interface ToolCallErrorOptions {
+    callId?: string;
+    correlationId?: string;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/**
+ * A safe, structured validation/control error. The error itself is useful to
+ * local callers while `toStructuredError()` is the machine contract for
+ * HTTP/WebSocket adapters.
+ */
+export declare class ToolCallControlError extends Error {
+    readonly code: ToolCallErrorCode;
+    readonly retryable: boolean;
+    readonly callId?: string;
+    readonly correlationId?: string;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: unknown;
+    constructor(code: ToolCallErrorCode, message?: string, options?: ToolCallErrorOptions);
+    toStructuredError(): ToolCallStructuredError;
+    toJSON(): ToolCallStructuredError;
+}
+/** Build a structured error without exposing an underlying exception message. */
+export declare function createToolCallError(code: ToolCallErrorCode, options?: ToolCallErrorOptions): ToolCallStructuredError;
+/** Convert a local control error to its stable wire value. */
+export declare function toStructuredToolCallError(error: unknown): ToolCallStructuredError;
+/** Return true for errors created by this module, including cross-realm-like values. */
+export declare function isToolCallControlError(error: unknown): error is ToolCallControlError;
+/**
+ * Normalize a regular or system request. This function does not mutate the
+ * input and does not serialize the runtime signal.
+ */
+export declare function normalizeToolCall(request: ToolCallRequest, options?: NormalizeToolCallOptions): NormalizedToolCall;
+/**
+ * Normalize either REST body form:
+ *
+ *   legacy:     { ...tool arguments }
+ *   controlled: { arguments: { ... }, control: { ... } }
+ *
+ * The wrapper is recognized only when both members are own object members.
+ * This keeps a legitimate legacy argument named `control` intact.
+ */
+export declare function normalizeRestToolCall(name: string, body: unknown, options?: NormalizeToolCallOptions): NormalizedToolCall;
+/**
+ * Serialize a controlled REST body using the same canonical member ordering
+ * as the forwarding adapters. Unknown members are sorted after known ones.
+ */
+export declare function serializeControlledToolBody(arguments_: Record<string, unknown>, control: ToolCallControl | ToolCallContext, options?: NormalizeToolCallOptions): {
+    arguments: Record<string, unknown>;
+    control: ToolCallControl;
+    requestID?: string;
+};
+/**
+ * Normalize and serialize a named controlled call. This is the adapter seam
+ * shared by REST transports, library helpers, and command-facing adapters.
+ * Runtime signals are used for local cancellation only and never enter the
+ * returned body.
+ */
+export declare function serializeToolCallBody(name: string, arguments_: Record<string, unknown>, control: ToolCallControl | ToolCallContext, options?: ToolCallSerializationOptions): SerializedToolCall;
+/** Serialize a previously normalized call without normalizing it again. */
+export declare function serializeNormalizedToolCall(normalized: NormalizedToolCall): Record<string, unknown>;
+/**
+ * Resolve an adapter's optional control/context fields into one value. Direct
+ * fields are useful to CLI adapters; an explicit `control` object remains the
+ * source of truth when it already contains the corresponding member.
+ */
+export declare function resolveToolCallControl(options: ToolCallOptionValues): ToolCallControl | ToolCallContext | undefined;
+/** Serialize just the control envelope, omitting runtime-only members. */
+export declare function serializeToolCallControl(control: ToolCallControl | ToolCallContext, options?: NormalizeToolCallOptions): ToolCallControl;
+/**
+ * Derive a child context for an internal/batch invocation. A child always
+ * receives a new logical id, inherits the top-level correlation id, and never
+ * inherits its parent's idempotency key.
+ */
+export declare function deriveChildToolCallContext(parent: ToolCallContext, childControl?: ToolCallControl, options?: DeriveChildToolCallOptions): ToolCallContext;
+/** Alias for callers that use the shorter context terminology. */
+export declare const deriveChildContext: typeof deriveChildToolCallContext;
+/** Normalize a standalone control object into a runtime context. */
+export declare function normalizeToolCallContext(control: ToolCallControl, options?: NormalizeToolCallOptions & {
+    requestID?: string;
+}): ToolCallContext;
+/** Explicit aliases for adapters that name the operation after its input. */
+export declare const normalizeToolCallControl: typeof normalizeToolCallContext;
+export declare const createToolCallContext: typeof normalizeToolCallContext;
+export declare function isToolCallContext(value: unknown): value is ToolCallContext;