stitchkit 0.54.0 → 0.55.0

package/dist/testing.js

@@ -1,9 +1,362 @@
+import {
+  assertToolName,
+  assertUniqueToolName,
+  toToolName
+} from "./index-k4dftwf7.js";
+import {
+  toJsonSchema
+} from "./index-cby4ar3v.js";
 import {
   createClient,
   createClients
-} from "./index-e1es808r.js";
+} from "./index-qh4xevf5.js";
 import"./index-48ffdxgk.js";
-import"./index-bmnhqtya.js";
+import {
+  isRecord
+} from "./index-7eq9va6e.js";
+import"./index-1bx83sw4.js";
+
+// src/testing/surface-conformance.ts
+import { z as z2 } from "zod";
+
+// src/testing/surface-manifest.ts
+import { createHash } from "node:crypto";
+import { z } from "zod";
+var HttpMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+var ToolTransportSchema = z.enum(["MCP", "AGENT", "CLI"]);
+var SurfaceSchemaDigestsSchema = z.object({
+  params: z.string().nullable(),
+  input: z.string().nullable(),
+  output: z.string().nullable(),
+  multipart: z.string().nullable()
+});
+var SurfaceManifestOperationSchema = z.object({
+  kind: z.enum(["contract", "runtime"]),
+  service: z.string(),
+  action: z.string(),
+  method: HttpMethodSchema,
+  scope: z.string().nullable(),
+  description: z.string(),
+  schemas: SurfaceSchemaDigestsSchema,
+  http: z.array(z.object({ method: HttpMethodSchema, path: z.string() })),
+  tools: z.partialRecord(ToolTransportSchema, z.string())
+});
+var SurfaceManifestCliCommandSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  input: z.string(),
+  output: z.string().nullable()
+});
+var SurfaceManifestExtensionSchema = z.object({
+  name: z.string(),
+  transport: z.enum(["HTTP", "MCP", "AGENT", "CLI"])
+});
+var SurfaceManifestSchema = z.object({
+  manifestVersion: z.literal(1),
+  digestVersion: z.literal(1),
+  operations: z.array(SurfaceManifestOperationSchema),
+  cliOnly: z.array(SurfaceManifestCliCommandSchema),
+  extensions: z.array(SurfaceManifestExtensionSchema)
+});
+function compareCodepoints(left, right) {
+  if (left < right)
+    return -1;
+  if (left > right)
+    return 1;
+  return 0;
+}
+function canonicalValue(value) {
+  if (Array.isArray(value))
+    return value.map(canonicalValue);
+  if (!isRecord(value))
+    return value;
+  const result = {};
+  for (const key of Object.keys(value).sort(compareCodepoints)) {
+    result[key] = canonicalValue(value[key]);
+  }
+  return result;
+}
+function serializeSurfaceValue(value) {
+  return JSON.stringify(canonicalValue(value));
+}
+function digestValue(value) {
+  return createHash("sha256").update(serializeSurfaceValue(value)).digest("hex").slice(0, 16);
+}
+function canonicalSchemaValue(value, parentKey) {
+  if (Array.isArray(value)) {
+    const entries = value.map((entry) => canonicalSchemaValue(entry));
+    return parentKey === "required" && entries.every((entry) => typeof entry === "string") ? entries.sort((left, right) => compareCodepoints(String(left), String(right))) : entries;
+  }
+  if (!isRecord(value))
+    return value;
+  const result = {};
+  for (const key of Object.keys(value).sort(compareCodepoints)) {
+    result[key] = canonicalSchemaValue(value[key], key);
+  }
+  return result;
+}
+function schemaDigest(schema, io) {
+  if (!schema)
+    return null;
+  return digestValue(canonicalSchemaValue(toJsonSchema(schema, io, "any")));
+}
+function multipartDigest(value) {
+  return value === undefined ? null : digestValue(value);
+}
+function joinPath(...parts) {
+  const joined = parts.filter((part) => Boolean(part)).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+  return `/${joined}`;
+}
+function operationKey(kind, service, action) {
+  return `${kind}\x00${service}\x00${action}`;
+}
+function uniqueToolServices(config) {
+  const services = new Set;
+  for (const service of config.services ?? [])
+    services.add(service);
+  for (const group of config.groups ?? []) {
+    for (const service of group.services)
+      services.add(service);
+  }
+  return [...services];
+}
+function buildSurfaceManifest(config) {
+  const operations = new Map;
+  const addContract = (service, prefix) => {
+    for (const method of Object.values(service.methods)) {
+      const key = operationKey("contract", service.name, method.key);
+      const existing = operations.get(key);
+      const http = !method.expose || method.expose.includes("HTTP") ? [{ method: method.method, path: joinPath(prefix, service.prefix, method.path) }] : [];
+      if (existing) {
+        existing.http.push(...http);
+        continue;
+      }
+      operations.set(key, {
+        kind: "contract",
+        service: service.name,
+        action: method.key,
+        method: method.method,
+        scope: method.scope ?? service.scope ?? null,
+        description: method.desc,
+        schemas: {
+          params: schemaDigest(method.paramsSchema, "input"),
+          input: schemaDigest(method.inputSchema, "input"),
+          output: schemaDigest(method.outputSchema, "output"),
+          multipart: multipartDigest(method.multipart)
+        },
+        http,
+        tools: {}
+      });
+    }
+  };
+  for (const service of config.services ?? []) {
+    addContract(service, config.scopePrefixes?.[service.scope] ?? "");
+  }
+  for (const group of config.groups ?? []) {
+    for (const service of group.services)
+      addContract(service, group.pathPrefix ?? "");
+  }
+  for (const definition of config.runtimeTools ?? []) {
+    const identity = definition.identity;
+    const key = operationKey("runtime", identity.serviceName, identity.action);
+    if (operations.has(key)) {
+      throw new Error(`Duplicate runtime operation identity ${identity.serviceName}.${identity.action}`);
+    }
+    operations.set(key, {
+      kind: "runtime",
+      service: identity.serviceName,
+      action: identity.action,
+      method: identity.method,
+      scope: identity.scope ?? null,
+      description: definition.description,
+      schemas: {
+        params: null,
+        input: schemaDigest(definition.input, "input"),
+        output: schemaDigest(definition.output, "output"),
+        multipart: null
+      },
+      http: [],
+      tools: {}
+    });
+  }
+  const usedNames = {
+    MCP: new Set,
+    AGENT: new Set,
+    CLI: new Set
+  };
+  const addTool = (operation, name, transport) => {
+    if (transport !== "CLI")
+      assertToolName(name, operation.service, operation.action);
+    const surface = transport === "CLI" ? "CLI command" : transport === "MCP" ? "MCP tool name" : "agent tool name";
+    assertUniqueToolName(name, usedNames[transport].has(name), surface);
+    usedNames[transport].add(name);
+    operation.tools[transport] = name;
+  };
+  for (const service of uniqueToolServices(config)) {
+    for (const method of Object.values(service.methods)) {
+      if (method.multipart || method.rawBody || method.rawResponse || method.responseMeta)
+        continue;
+      const operation = operations.get(operationKey("contract", service.name, method.key));
+      if (!operation)
+        continue;
+      const name = method.toolName ?? toToolName(service.name, method.key);
+      if (!method.expose || method.expose.includes("MCP"))
+        addTool(operation, name, "MCP");
+      if (!method.expose || method.expose.includes("AGENT"))
+        addTool(operation, name, "AGENT");
+      if (method.expose?.includes("CLI"))
+        addTool(operation, name, "CLI");
+    }
+  }
+  for (const definition of config.runtimeTools ?? []) {
+    const operation = operations.get(operationKey("runtime", definition.identity.serviceName, definition.identity.action));
+    if (!operation)
+      continue;
+    const transports = definition.transports ?? [
+      "MCP",
+      "AGENT"
+    ];
+    for (const transport of transports)
+      addTool(operation, definition.name, transport);
+  }
+  const cliOnly = (config.cliCommands ?? []).map((command) => ({
+    name: command.name,
+    description: command.description,
+    input: schemaDigest(command.input, "input") ?? digestValue({}),
+    output: schemaDigest(command.output, "output")
+  })).sort((left, right) => compareCodepoints(left.name, right.name));
+  return SurfaceManifestSchema.parse({
+    manifestVersion: 1,
+    digestVersion: 1,
+    operations: [...operations.values()].sort((left, right) => compareCodepoints(left.service, right.service) || compareCodepoints(left.action, right.action) || compareCodepoints(left.kind, right.kind)),
+    cliOnly,
+    extensions: [...config.extensions ?? []].sort((left, right) => compareCodepoints(left.transport, right.transport) || compareCodepoints(left.name, right.name))
+  });
+}
+function assertSurfaceManifestSnapshot(manifest, snapshot) {
+  const actual = serializeSurfaceValue(SurfaceManifestSchema.parse(manifest));
+  const expected = serializeSurfaceValue(SurfaceManifestSchema.parse(snapshot));
+  if (actual !== expected) {
+    throw new Error(`Surface manifest diverged from its committed snapshot
+expected: ${expected}
+actual: ${actual}`);
+  }
+}
+
+// src/testing/surface-conformance.ts
+var ProbeOutcomeSchema = z2.enum(["success", "validation_error", "domain_error", "aborted"]);
+var TransportObservationSchema = z2.object({
+  outcome: ProbeOutcomeSchema,
+  code: z2.string().optional(),
+  data: z2.unknown().optional(),
+  diagnostic: z2.string().optional()
+});
+function sorted(values) {
+  return [...values].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+}
+function assertSameSet(label, expectedValues, actualValues) {
+  const expected = sorted(expectedValues);
+  const actual = sorted(actualValues);
+  if (serializeSurfaceValue(expected) === serializeSurfaceValue(actual))
+    return;
+  throw new Error(`${label} mismatch
+expected: ${expected.join(", ") || "(empty)"}
+actual: ${actual.join(", ") || "(empty)"}`);
+}
+function openApiOperations(document) {
+  return Object.entries(document.paths).flatMap(([path, item]) => Object.keys(item).filter((method) => ["get", "post", "put", "patch", "delete", "head"].includes(method)).map((method) => `${method.toUpperCase()}:${path}`));
+}
+function expectedToolNames(operations, transport) {
+  return operations.flatMap((operation) => {
+    const name = operation.tools[transport];
+    return name ? [name] : [];
+  });
+}
+function assertSurfaceDiscovery(manifest, observed) {
+  if (observed.openApi) {
+    assertSameSet("HTTP/OpenAPI", manifest.operations.flatMap((operation) => operation.http.map((entry) => `${entry.method}:${entry.path.replace(/:([^/]+)/g, "{$1}")}`)), openApiOperations(observed.openApi));
+  }
+  for (const transport of ["MCP", "AGENT", "CLI"]) {
+    const names = observed[transport];
+    if (names)
+      assertSameSet(`${transport} discovery`, expectedToolNames(manifest.operations, transport), names);
+  }
+  if (observed.cliOnly) {
+    assertSameSet("CLI-only discovery", manifest.cliOnly.map((command) => command.name), observed.cliOnly);
+  }
+  for (const transport of ["HTTP", "MCP", "AGENT", "CLI"]) {
+    const names = observed.extensions?.[transport];
+    if (!names)
+      continue;
+    assertSameSet(`${transport} extension discovery`, manifest.extensions.filter((extension) => extension.transport === transport).map((extension) => extension.name), names);
+  }
+}
+function boundedObservation(observation, maxDiagnosticBytes) {
+  const parsed = TransportObservationSchema.parse(observation);
+  if (!parsed.diagnostic)
+    return parsed;
+  const bytes = new TextEncoder().encode(parsed.diagnostic);
+  if (bytes.byteLength <= maxDiagnosticBytes)
+    return parsed;
+  return {
+    ...parsed,
+    diagnostic: new TextDecoder().decode(bytes.slice(0, maxDiagnosticBytes))
+  };
+}
+async function invokeBounded(driver, fixture, signal) {
+  signal.throwIfAborted();
+  let removeAbortListener = () => {
+    return;
+  };
+  const aborted = new Promise((_resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+  });
+  try {
+    return await Promise.race([driver.invoke(fixture, signal), aborted]);
+  } finally {
+    removeAbortListener();
+  }
+}
+async function runSurfaceProbes({
+  probes,
+  drivers,
+  signal,
+  timeoutMs = 1e4,
+  maxDiagnosticBytes = 4096
+}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError("Surface probe timeoutMs must be a finite positive number");
+  }
+  if (!Number.isInteger(maxDiagnosticBytes) || maxDiagnosticBytes <= 0) {
+    throw new TypeError("Surface probe maxDiagnosticBytes must be a positive integer");
+  }
+  for (const probe of probes) {
+    await probe.setup?.();
+    try {
+      for (const transport of probe.transports) {
+        const driver = drivers[transport];
+        if (!driver)
+          throw new Error(`Surface probe "${probe.name}" has no ${transport} driver`);
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        const invokeSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+        const actual = boundedObservation(await invokeBounded(driver, probe.fixture, invokeSignal), maxDiagnosticBytes);
+        const expected = probe.expected[transport];
+        if (!expected) {
+          throw new Error(`Surface probe "${probe.name}" has no ${transport} expectation`);
+        }
+        if (serializeSurfaceValue(actual) !== serializeSurfaceValue(expected)) {
+          throw new Error(`Surface probe "${probe.name}" ${transport} mismatch
+expected: ${serializeSurfaceValue(expected)}
+actual: ${serializeSurfaceValue(actual)}`);
+        }
+      }
+    } finally {
+      await probe.teardown?.();
+    }
+  }
+}
 
 // src/testing.ts
 function resolveTestBaseUrl(origin, pathPrefix) {
@@ -31,6 +384,16 @@ function createHandlerTestClients(config) {
   return createClients(config.contracts, createTestClientConfig(config), config.contractConfig);
 }
 export {
+  SurfaceManifestExtensionSchema,
+  SurfaceManifestOperationSchema,
+  SurfaceManifestSchema,
+  SurfaceSchemaDigestsSchema,
+  TransportObservationSchema,
+  assertSurfaceDiscovery,
+  assertSurfaceManifestSnapshot,
+  buildSurfaceManifest,
+  createHandlerTestClient,
   createHandlerTestClients,
-  createHandlerTestClient
+  runSurfaceProbes,
+  serializeSurfaceValue
 };

package/dist/tools/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAGlC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAwET"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAwET"}

package/dist/tools/async-operation.d.ts

@@ -0,0 +1,168 @@
+import { type ZodObject, type ZodType, z } from 'zod';
+import type { ContractDef, EndpointDef, EndpointToolAnnotations } from '../contract';
+import type { Handlers } from '../server/types';
+import { type RuntimeToolDefinition, type RuntimeToolDefinitionWithOutput, type RuntimeToolHandlerContext, type RuntimeToolTransport } from './runtime-tool';
+export declare const AsyncOperationCancelResultSchema: z.ZodDiscriminatedUnion<[ZodObject<{
+    outcome: z.ZodLiteral<"accepted">;
+}, z.core.$strip>, ZodObject<{
+    outcome: z.ZodLiteral<"already_terminal">;
+}, z.core.$strip>, ZodObject<{
+    outcome: z.ZodLiteral<"rejected">;
+    reason: z.ZodString;
+}, z.core.$strip>], "outcome">;
+export type AsyncOperationCancelResult = z.infer<typeof AsyncOperationCancelResultSchema>;
+export type AsyncOperationCapability = 'start' | 'status' | 'wait' | 'cancel' | 'result' | 'artifacts';
+export declare function createAsyncOperationSnapshotSchema<TProgress extends ZodType | undefined = undefined, TFailure extends ZodType = ZodType>(config: {
+    progress?: TProgress;
+    failure: TFailure;
+}): z.ZodDiscriminatedUnion<[ZodObject<{
+    progress: z.ZodOptional<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    phase: z.ZodLiteral<"pending">;
+} | {
+    progress?: undefined;
+    phase: z.ZodLiteral<"pending">;
+}, z.core.$strip>, ZodObject<{
+    progress: z.ZodOptional<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    phase: z.ZodLiteral<"running">;
+} | {
+    progress?: undefined;
+    phase: z.ZodLiteral<"running">;
+}, z.core.$strip>, ZodObject<{
+    progress: z.ZodOptional<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    phase: z.ZodLiteral<"succeeded">;
+} | {
+    progress?: undefined;
+    phase: z.ZodLiteral<"succeeded">;
+}, z.core.$strip>, ZodObject<{
+    progress: z.ZodOptional<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    phase: z.ZodLiteral<"failed">;
+    failure: TFailure;
+} | {
+    progress?: undefined;
+    phase: z.ZodLiteral<"failed">;
+    failure: TFailure;
+}, z.core.$strip>, ZodObject<{
+    progress: z.ZodOptional<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    phase: z.ZodLiteral<"cancelled">;
+} | {
+    progress?: undefined;
+    phase: z.ZodLiteral<"cancelled">;
+}, z.core.$strip>], "phase">;
+export interface AsyncOperationIdentity {
+    serviceName: string;
+    action: string;
+    scope?: string;
+    meta?: Record<string, unknown>;
+}
+export interface AsyncOperationCancelCapability<TId extends ZodObject, TState extends ZodType> {
+    handler: (state: z.output<TState>, context: RuntimeToolHandlerContext<TId>) => z.output<typeof AsyncOperationCancelResultSchema> | Promise<z.output<typeof AsyncOperationCancelResultSchema>>;
+}
+export interface AsyncOperationOutputCapability<TId extends ZodObject, TState extends ZodType, TOutput extends ZodType> {
+    output: TOutput;
+    handler: (state: z.output<TState>, context: RuntimeToolHandlerContext<TId>) => z.output<TOutput> | Promise<z.output<TOutput>>;
+}
+export interface RuntimeAsyncOperationConfig<TStartInput extends ZodObject, TId extends ZodObject, TState extends ZodType, TSnapshot extends ZodType, TCancel extends AsyncOperationCancelCapability<TId, TState> = never, TResult extends AsyncOperationOutputCapability<TId, TState, ZodType> = never, TArtifacts extends AsyncOperationOutputCapability<TId, TState, ZodType> = never> {
+    mode: 'runtime-only';
+    /** Provider-safe prefix used for the generated capability names. */
+    name: string;
+    description: string;
+    identity: AsyncOperationIdentity;
+    startInput: TStartInput;
+    id: TId;
+    state: TState;
+    snapshot: TSnapshot;
+    start: (input: z.output<TStartInput>, context: RuntimeToolHandlerContext<TStartInput>) => z.output<TId> | Promise<z.output<TId>>;
+    /** Mandatory resource authorization, repeated before every follow-up callback. */
+    authorize: (id: z.output<TId>, capability: Exclude<AsyncOperationCapability, 'start'>, context: RuntimeToolHandlerContext<TId>) => void | Promise<void>;
+    inspect: (id: z.output<TId>, context: RuntimeToolHandlerContext<TId>) => z.output<TState> | Promise<z.output<TState>>;
+    classify: (state: z.output<TState>, context: RuntimeToolHandlerContext<TId>) => z.output<TSnapshot> | Promise<z.output<TSnapshot>>;
+    cancel?: TCancel;
+    result?: TResult;
+    artifacts?: TArtifacts;
+    names?: Partial<Record<AsyncOperationCapability, string>>;
+    descriptions?: Partial<Record<AsyncOperationCapability, string>>;
+    scopes?: Partial<Record<AsyncOperationCapability, string>>;
+    annotations?: Partial<Record<AsyncOperationCapability, EndpointToolAnnotations>>;
+    transports?: Partial<Record<AsyncOperationCapability, readonly RuntimeToolTransport[]>>;
+    backoff?: number[];
+    defaultTimeout?: number;
+    timeoutFromId?: (id: z.output<TId>) => number | undefined;
+}
+export type AsyncOperationStartDefinition<TInput extends ZodObject, TId extends ZodObject> = RuntimeToolDefinitionWithOutput<TInput, TId>;
+export type AsyncOperationFollowDefinition<TId extends ZodObject, TOutput extends ZodType> = RuntimeToolDefinitionWithOutput<TId, TOutput>;
+export type RuntimeAsyncOperation<TStartInput extends ZodObject, TId extends ZodObject, TSnapshot extends ZodType, TCancel, TResult, TArtifacts> = {
+    start: AsyncOperationStartDefinition<TStartInput, TId>;
+    status: AsyncOperationFollowDefinition<TId, TSnapshot>;
+    wait: AsyncOperationFollowDefinition<TId, TSnapshot>;
+    runtimeTools: readonly RuntimeToolDefinition[];
+    schemas: {
+        id: TId;
+        snapshot: TSnapshot;
+        cancelResult: typeof AsyncOperationCancelResultSchema;
+    };
+} & ([TCancel] extends [never] ? object : {
+    cancel: AsyncOperationFollowDefinition<TId, typeof AsyncOperationCancelResultSchema>;
+}) & ([TResult] extends [never] ? object : TResult extends {
+    output: infer TOutput extends ZodType;
+} ? {
+    result: AsyncOperationFollowDefinition<TId, TOutput>;
+} : object) & ([TArtifacts] extends [never] ? object : TArtifacts extends {
+    output: infer TOutput extends ZodType;
+} ? {
+    artifacts: AsyncOperationFollowDefinition<TId, TOutput>;
+} : object);
+/** Define a pathless async-operation surface. It never creates an HTTP route. */
+export declare function defineAsyncOperation<TStartInput extends ZodObject, TId extends ZodObject, TState extends ZodType, TSnapshot extends ZodType, TCancel extends AsyncOperationCancelCapability<TId, TState> = never, TResult extends AsyncOperationOutputCapability<TId, TState, ZodType> = never, TArtifacts extends AsyncOperationOutputCapability<TId, TState, ZodType> = never>(config: RuntimeAsyncOperationConfig<TStartInput, TId, TState, TSnapshot, TCancel, TResult, TArtifacts>): RuntimeAsyncOperation<TStartInput, TId, TSnapshot, TCancel, TResult, TArtifacts>;
+export type ContractAsyncOperationKeys<TEndpoints extends Record<string, EndpointDef>> = keyof TEndpoints & string;
+type EndpointInputSchema<TEndpoint> = TEndpoint extends {
+    input: infer TSchema extends ZodType;
+} ? TSchema : never;
+type EndpointOutputSchema<TEndpoint> = TEndpoint extends {
+    output: infer TSchema extends ZodType;
+} ? TSchema : never;
+type TypesEqual<TLeft, TRight> = [TLeft] extends [TRight] ? [TRight] extends [TLeft] ? true : false : false;
+type SchemasEquivalent<TLeft extends ZodType, TRight extends ZodType> = TypesEqual<z.input<TLeft>, z.input<TRight>> extends true ? TypesEqual<z.output<TLeft>, z.output<TRight>> : false;
+export type ContractAsyncOperationStartKey<TEndpoints extends Record<string, EndpointDef>> = {
+    [TKey in keyof TEndpoints]: EndpointOutputSchema<TEndpoints[TKey]> extends never ? never : TKey;
+}[keyof TEndpoints] & string;
+export type ContractAsyncOperationFollowKey<TEndpoints extends Record<string, EndpointDef>, TStart extends ContractAsyncOperationStartKey<TEndpoints>> = {
+    [TKey in keyof TEndpoints]: EndpointInputSchema<TEndpoints[TKey]> extends infer TInput extends ZodType ? EndpointOutputSchema<TEndpoints[TStart]> extends infer TId extends ZodType ? SchemasEquivalent<TInput, TId> extends true ? TKey : never : never : never;
+}[keyof TEndpoints] & string;
+export type ContractAsyncOperationWaitKey<TEndpoints extends Record<string, EndpointDef>, TStart extends ContractAsyncOperationStartKey<TEndpoints>, TStatus extends ContractAsyncOperationFollowKey<TEndpoints, TStart>> = {
+    [TKey in keyof TEndpoints]: TKey extends ContractAsyncOperationFollowKey<TEndpoints, TStart> ? EndpointOutputSchema<TEndpoints[TKey]> extends infer TOutput extends ZodType ? EndpointOutputSchema<TEndpoints[TStatus]> extends infer TSnapshot extends ZodType ? SchemasEquivalent<TOutput, TSnapshot> extends true ? TKey : never : never : never : never;
+}[keyof TEndpoints] & string;
+export interface ContractAsyncOperationConfig<TEndpoints extends Record<string, EndpointDef>, TScope extends string, TStart extends ContractAsyncOperationStartKey<TEndpoints> = ContractAsyncOperationStartKey<TEndpoints>, TStatus extends ContractAsyncOperationFollowKey<TEndpoints, TStart> = ContractAsyncOperationFollowKey<TEndpoints, TStart>> {
+    mode: 'contract-backed';
+    contract: ContractDef<TEndpoints, TScope>;
+    capabilities: {
+        start: TStart;
+        status: TStatus;
+        wait: ContractAsyncOperationWaitKey<TEndpoints, TStart, TStatus>;
+        cancel?: ContractAsyncOperationFollowKey<TEndpoints, TStart>;
+        result?: ContractAsyncOperationFollowKey<TEndpoints, TStart>;
+        artifacts?: ContractAsyncOperationFollowKey<TEndpoints, TStart>;
+    };
+    handlers: Handlers<TEndpoints>;
+}
+/**
+ * Bind a dedicated contract's already-declared methods as one async operation.
+ * The returned handlers go straight to `implement`; no schema or HTTP route is copied.
+ */
+export declare function bindContractAsyncOperation<TEndpoints extends Record<string, EndpointDef>, TScope extends string, const TStart extends ContractAsyncOperationStartKey<TEndpoints>, const TStatus extends ContractAsyncOperationFollowKey<TEndpoints, TStart>>(config: ContractAsyncOperationConfig<TEndpoints, TScope, TStart, TStatus>): {
+    contract: ContractDef<TEndpoints, TScope>;
+    handlers: Handlers<TEndpoints, import("..").HandlerContext<undefined, undefined>>;
+    capabilities: {
+        start: TStart;
+        status: TStatus;
+        wait: { [TKey in keyof TEndpoints]: TKey extends ContractAsyncOperationFollowKey<TEndpoints, TStart> ? EndpointOutputSchema<TEndpoints[TKey]> extends infer TOutput extends ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? EndpointOutputSchema<TEndpoints[TStatus]> extends infer TSnapshot extends ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? SchemasEquivalent<TOutput, TSnapshot> extends true ? TKey : never : never : never : never; }[keyof TEndpoints];
+        cancel?: ContractAsyncOperationFollowKey<TEndpoints, TStart> | undefined;
+        result?: ContractAsyncOperationFollowKey<TEndpoints, TStart> | undefined;
+        artifacts?: ContractAsyncOperationFollowKey<TEndpoints, TStart> | undefined;
+    };
+    schemas: {
+        id: ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        snapshot: ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    };
+};
+export {};
+//# sourceMappingURL=async-operation.d.ts.map

package/dist/tools/async-operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-operation.d.ts","sourceRoot":"","sources":["../../src/tools/async-operation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,uBAAuB,EAExB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,+BAA+B,EACpC,KAAK,yBAAyB,EAE9B,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AAExB,eAAO,MAAM,gCAAgC;;;;;;;8BAI3C,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAC1F,MAAM,MAAM,wBAAwB,GAChC,OAAO,GACP,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,WAAW,CAAC;AAEhB,wBAAgB,kCAAkC,CAChD,SAAS,SAAS,OAAO,GAAG,SAAS,GAAG,SAAS,EACjD,QAAQ,SAAS,OAAO,GAAG,OAAO,EAClC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BASpD;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,8BAA8B,CAC7C,GAAG,SAAS,SAAS,EACrB,MAAM,SAAS,OAAO;IAEtB,OAAO,EAAE,CACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EACvB,OAAO,EAAE,yBAAyB,CAAC,GAAG,CAAC,KAErC,CAAC,CAAC,MAAM,CAAC,OAAO,gCAAgC,CAAC,GACjD,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,gCAAgC,CAAC,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,8BAA8B,CAC7C,GAAG,SAAS,SAAS,EACrB,MAAM,SAAS,OAAO,EACtB,OAAO,SAAS,OAAO;IAEvB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,CACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EACvB,OAAO,EAAE,yBAAyB,CAAC,GAAG,CAAC,KACpC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,2BAA2B,CAC1C,WAAW,SAAS,SAAS,EAC7B,GAAG,SAAS,SAAS,EACrB,MAAM,SAAS,OAAO,EACtB,SAAS,SAAS,OAAO,EACzB,OAAO,SAAS,8BAA8B,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,KAAK,EACnE,OAAO,SAAS,8BAA8B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,EAC5E,UAAU,SAAS,8BAA8B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK;IAE/E,IAAI,EAAE,cAAc,CAAC;IACrB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,sBAAsB,CAAC;IACjC,UAAU,EAAE,WAAW,CAAC;IACxB,EAAE,EAAE,GAAG,CAAC;IACR,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,CACL,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,EAC5B,OAAO,EAAE,yBAAyB,CAAC,WAAW,CAAC,KAC5C,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5C,kFAAkF;IAClF,SAAS,EAAE,CACT,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EACjB,UAAU,EAAE,OAAO,CAAC,wBAAwB,EAAE,OAAO,CAAC,EACtD,OAAO,EAAE,yBAAyB,CAAC,GAAG,CAAC,KACpC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,EAAE,CACP,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EACjB,OAAO,EAAE,yBAAyB,CAAC,GAAG,CAAC,KACpC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,EAAE,CACR,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EACvB,OAAO,EAAE,yBAAyB,CAAC,GAAG,CAAC,KACpC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,wBAAwB,EAAE,uBAAuB,CAAC,CAAC,CAAC;IACjF,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,wBAAwB,EAAE,SAAS,oBAAoB,EAAE,CAAC,CAAC,CAAC;IACxF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;CAC3D;AAED,MAAM,MAAM,6BAA6B,CACvC,MAAM,SAAS,SAAS,EACxB,GAAG,SAAS,SAAS,IACnB,+BAA+B,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACjD,MAAM,MAAM,8BAA8B,CACxC,GAAG,SAAS,SAAS,EACrB,OAAO,SAAS,OAAO,IACrB,+BAA+B,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,MAAM,qBAAqB,CAC/B,WAAW,SAAS,SAAS,EAC7B,GAAG,SAAS,SAAS,EACrB,SAAS,SAAS,OAAO,EACzB,OAAO,EACP,OAAO,EACP,UAAU,IACR;IACF,KAAK,EAAE,6BAA6B,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,EAAE,8BAA8B,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACvD,IAAI,EAAE,8BAA8B,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACrD,YAAY,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC/C,OAAO,EAAE;QACP,EAAE,EAAE,GAAG,CAAC;QACR,QAAQ,EAAE,SAAS,CAAC;QACpB,YAAY,EAAE,OAAO,gCAAgC,CAAC;KACvD,CAAC;CACH,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,GAC1B,MAAM,GACN;IAAE,MAAM,EAAE,8BAA8B,CAAC,GAAG,EAAE,OAAO,gCAAgC,CAAC,CAAA;CAAE,CAAC,GAC3F,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,GACtB,MAAM,GACN,OAAO,SAAS;IAAE,MAAM,EAAE,MAAM,OAAO,SAAS,OAAO,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,8BAA8B,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;CAAE,GACxD,MAAM,CAAC,GACb,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,GACzB,MAAM,GACN,UAAU,SAAS;IAAE,MAAM,EAAE,MAAM,OAAO,SAAS,OAAO,CAAA;CAAE,GAC1D;IAAE,SAAS,EAAE,8BAA8B,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;CAAE,GAC3D,MAAM,CAAC,CAAC;AAsBhB,iFAAiF;AACjF,wBAAgB,oBAAoB,CAClC,WAAW,SAAS,SAAS,EAC7B,GAAG,SAAS,SAAS,EACrB,MAAM,SAAS,OAAO,EACtB,SAAS,SAAS,OAAO,EACzB,OAAO,SAAS,8BAA8B,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,KAAK,EACnE,OAAO,SAAS,8BAA8B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,EAC5E,UAAU,SAAS,8BAA8B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,EAE/E,MAAM,EAAE,2BAA2B,CACjC,WAAW,EACX,GAAG,EACH,MAAM,EACN,SAAS,EACT,OAAO,EACP,OAAO,EACP,UAAU,CACX,GACA,qBAAqB,CAAC,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAyJpF,MAAM,MAAM,0BAA0B,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IACnF,MAAM,UAAU,GAAG,MAAM,CAAC;AAE5B,KAAK,mBAAmB,CAAC,SAAS,IAAI,SAAS,SAAS;IACtD,KAAK,EAAE,MAAM,OAAO,SAAS,OAAO,CAAC;CACtC,GACG,OAAO,GACP,KAAK,CAAC;AAEV,KAAK,oBAAoB,CAAC,SAAS,IAAI,SAAS,SAAS;IACvD,MAAM,EAAE,MAAM,OAAO,SAAS,OAAO,CAAC;CACvC,GACG,OAAO,GACP,KAAK,CAAC;AAEV,KAAK,UAAU,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,GACrD,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GACtB,IAAI,GACJ,KAAK,GACP,KAAK,CAAC;AAEV,KAAK,iBAAiB,CAAC,KAAK,SAAS,OAAO,EAAE,MAAM,SAAS,OAAO,IAClE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,IAAI,GACpD,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAC7C,KAAK,CAAC;AAEZ,MAAM,MAAM,8BAA8B,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI;KAC1F,IAAI,IAAI,MAAM,UAAU,GAAG,oBAAoB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,KAAK,GAC5E,KAAK,GACL,IAAI;CACT,CAAC,MAAM,UAAU,CAAC,GACjB,MAAM,CAAC;AAET,MAAM,MAAM,+BAA+B,CACzC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC9C,MAAM,SAAS,8BAA8B,CAAC,UAAU,CAAC,IACvD;KACD,IAAI,IAAI,MAAM,UAAU,GAAG,mBAAmB,CAC7C,UAAU,CAAC,IAAI,CAAC,CACjB,SAAS,MAAM,MAAM,SAAS,OAAO,GAClC,oBAAoB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,OAAO,GACxE,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,IAAI,GACzC,IAAI,GACJ,KAAK,GACP,KAAK,GACP,KAAK;CACV,CAAC,MAAM,UAAU,CAAC,GACjB,MAAM,CAAC;AAET,MAAM,MAAM,6BAA6B,CACvC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC9C,MAAM,SAAS,8BAA8B,CAAC,UAAU,CAAC,EACzD,OAAO,SAAS,+BAA+B,CAAC,UAAU,EAAE,MAAM,CAAC,IACjE;KACD,IAAI,IAAI,MAAM,UAAU,GAAG,IAAI,SAAS,+BAA+B,CAAC,UAAU,EAAE,MAAM,CAAC,GACxF,oBAAoB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,SAAS,OAAO,GAC1E,oBAAoB,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,SAAS,SAAS,OAAO,GAC/E,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,IAAI,GAChD,IAAI,GACJ,KAAK,GACP,KAAK,GACP,KAAK,GACP,KAAK;CACV,CAAC,MAAM,UAAU,CAAC,GACjB,MAAM,CAAC;AAET,MAAM,WAAW,4BAA4B,CAC3C,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC9C,MAAM,SAAS,MAAM,EACrB,MAAM,SACJ,8BAA8B,CAAC,UAAU,CAAC,GAAG,8BAA8B,CAAC,UAAU,CAAC,EACzF,OAAO,SAAS,+BAA+B,CAC7C,UAAU,EACV,MAAM,CACP,GAAG,+BAA+B,CAAC,UAAU,EAAE,MAAM,CAAC;IAEvD,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,WAAW,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1C,YAAY,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,EAAE,6BAA6B,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACjE,MAAM,CAAC,EAAE,+BAA+B,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC7D,MAAM,CAAC,EAAE,+BAA+B,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC7D,SAAS,CAAC,EAAE,+BAA+B,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;KACjE,CAAC;IACF,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC9C,MAAM,SAAS,MAAM,EACrB,KAAK,CAAC,MAAM,SAAS,8BAA8B,CAAC,UAAU,CAAC,EAC/D,KAAK,CAAC,OAAO,SAAS,+BAA+B,CAAC,UAAU,EAAE,MAAM,CAAC,EACzE,MAAM,EAAE,4BAA4B,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC;IAmCvE,QAAQ;IACR,QAAQ;IACR,YAAY;;;iBAjFb,IAAI,+IACoD,OAAO,yIACF,SAAS;;;;;IAgFrE,OAAO;QAAI,EAAE;QAAgB,QAAQ;;EAExC"}

package/dist/tools/cli-args.d.ts

@@ -20,7 +20,7 @@
 import { z } from 'zod';
 /** CLI-behaviour flags, parsed out of argv before the tool arguments. */
 export interface CliRunOptions {
-    /** `--json` — emit raw JSON on stdout for piping. */
+    /** `--json` — emit compact success/error JSON records for scripts. */
     json: boolean;
     /** `--wait` — block-poll an async result to a terminal state. */
     wait: boolean;

package/dist/tools/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../../src/tools/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,KAAK,SAAS,GACV,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,UAAU,SAAS;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAOD,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AAEjF,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,SAAsB;CACpC;AAuED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AA8FD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACvE,aAAa,CA+Kf"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../../src/tools/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,KAAK,SAAS,GACV,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,UAAU,SAAS;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAOD,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AAEjF,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,SAAsB;CACpC;AAuED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AA8FD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACvE,aAAa,CA+Kf"}

package/dist/tools/cli-format.d.ts

@@ -4,7 +4,7 @@
  * Output is JSON — the CLI's audience is agents (Skills via Bash), scripts and
  * `| jq`, for which structured JSON is the right shape, not a hand-formatted
  * table. The default is pretty-printed (indented, the same shape an MCP tool
- * returns); `--json` switches to a compact single line for piping.
+ * returns); `--json` switches success and error records to one compact line.
  *
  * stdout is reserved for that result; an error goes to stderr as the same
  * model-facing `{ error, details, _hint }` object the MCP / agent transports
@@ -24,7 +24,7 @@ export interface CliWriters {
     stderr: (text: string) => void;
 }
 export interface EmitOptions {
-    /** Compact single-line JSON (for `| jq` / scripts); otherwise pretty-printed. */
+    /** Compact single-line success/error JSON; otherwise pretty-printed. */
     json: boolean;
     toolName: string;
     errorHint?: ErrorHintFn;

package/dist/tools/cli-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-format.d.ts","sourceRoot":"","sources":["../../src/tools/cli-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGzD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAUhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR"}
+{"version":3,"file":"cli-format.d.ts","sourceRoot":"","sources":["../../src/tools/cli-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGzD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAWhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAgBR"}

package/dist/tools/cli-wait.d.ts

@@ -17,6 +17,13 @@ export interface CliWaitConfig {
     tool: string;
     /** Done when this returns `true` for a poll result. */
     done: (result: unknown) => boolean;
+    /**
+     * Terminal domain failure. A `true` result stops polling and turns the
+     * otherwise-successful tool payload into a `WAIT_FAILED` CLI failure. Checked
+     * before `done`, including for the initial result, so contradictory
+     * predicates fail closed.
+     */
+    failed?: (result: unknown) => boolean;
     /** Backoff schedule in seconds; the last entry repeats. Default `[2,3,5,5,8,10]`. */
     backoff?: number[];
     /** Max seconds before giving up. Default `600`. */
@@ -34,12 +41,14 @@ export interface PollParams {
     onTick?: (attempt: number, elapsedSec: number) => void;
     /** Injectable sleep for tests. */
     sleepFn?: (ms: number) => Promise<void>;
+    /** Explicit caller cancellation. Process SIGINT wiring remains application-owned. */
+    signal?: AbortSignal;
 }
 /**
  * Poll `wait.tool` until `wait.done` or the timeout. Returns the last poll
  * result; returns the initial result untouched when the initial call failed,
- * already satisfies `done`, or yields no poll target. A timeout produces a
- * `TIMEOUT` failed `ToolResult`.
+ * already satisfies `done`, or yields no poll target. A terminal result matched
+ * by `failed` produces `WAIT_FAILED`; a timeout produces `TIMEOUT`.
  */
 export declare function pollUntilDone(params: PollParams): Promise<ToolResult>;
 //# sourceMappingURL=cli-wait.d.ts.map

package/dist/tools/cli-wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-wait.d.ts","sourceRoot":"","sources":["../../src/tools/cli-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACnC,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,wEAAwE;IACxE,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/E,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,kCAAkC;IAClC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CA0B3E"}
+{"version":3,"file":"cli-wait.d.ts","sourceRoot":"","sources":["../../src/tools/cli-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAeD,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,wEAAwE;IACxE,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/E,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,kCAAkC;IAClC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAuC3E"}