stitchkit 0.53.2 → 0.55.0

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":"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"}

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-command.d.ts

@@ -0,0 +1,29 @@
+import type { ZodObject, ZodType, z } from 'zod';
+import type { CliRunOptions } from './cli-args';
+import type { CliWriters } from './cli-format';
+import { type ToolResult } from './execute';
+export interface CliCommandContext<TInput extends ZodObject> extends CliWriters {
+    input: z.output<TInput>;
+    options: Readonly<CliRunOptions>;
+}
+export interface CliCommandDefinitionBase<TInput extends ZodObject> {
+    name: string;
+    description: string;
+    input: TInput;
+}
+export interface CliCommandDefinitionWithOutput<TInput extends ZodObject, TOutput extends ZodType> extends CliCommandDefinitionBase<TInput> {
+    output: TOutput;
+    handler: (context: CliCommandContext<TInput>) => z.output<TOutput> | Promise<z.output<TOutput>>;
+}
+export interface CliCommandDefinitionWithoutOutput<TInput extends ZodObject> extends CliCommandDefinitionBase<TInput> {
+    output?: never;
+    handler: (context: CliCommandContext<TInput>) => void | Promise<void>;
+}
+export type CliCommandDefinition = CliCommandDefinitionWithOutput<ZodObject, ZodType> | CliCommandDefinitionWithoutOutput<ZodObject>;
+/** Typed identity helper for one transport-local executable command. */
+export declare function defineCliCommand<TInput extends ZodObject, TOutput extends ZodType>(definition: CliCommandDefinitionWithOutput<TInput, TOutput>): CliCommandDefinitionWithOutput<TInput, TOutput>;
+export declare function defineCliCommand<TInput extends ZodObject>(definition: CliCommandDefinitionWithoutOutput<TInput>): CliCommandDefinitionWithoutOutput<TInput>;
+export declare function cliCommandPresentationSchema(definition: CliCommandDefinition): Record<string, unknown>;
+/** Execute a CLI-only definition without inventing a tool operation identity. */
+export declare function executeCliCommand(definition: CliCommandDefinition, rawArgs: Record<string, unknown>, options: CliRunOptions, writers: CliWriters, coerceJson: boolean): Promise<ToolResult>;
+//# sourceMappingURL=cli-command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command.d.ts","sourceRoot":"","sources":["../../src/tools/cli-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,WAAW,CAAC;AAGjE,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,SAAS,CAAE,SAAQ,UAAU;IAC7E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACxB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB,CAAC,MAAM,SAAS,SAAS;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,8BAA8B,CAC7C,MAAM,SAAS,SAAS,EACxB,OAAO,SAAS,OAAO,CACvB,SAAQ,wBAAwB,CAAC,MAAM,CAAC;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,CACP,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,KAC/B,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,iCAAiC,CAAC,MAAM,SAAS,SAAS,CACzE,SAAQ,wBAAwB,CAAC,MAAM,CAAC;IACxC,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED,MAAM,MAAM,oBAAoB,GAC5B,8BAA8B,CAAC,SAAS,EAAE,OAAO,CAAC,GAClD,iCAAiC,CAAC,SAAS,CAAC,CAAC;AAEjD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,SAAS,EAAE,OAAO,SAAS,OAAO,EAChF,UAAU,EAAE,8BAA8B,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1D,8BAA8B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,SAAS,EACvD,UAAU,EAAE,iCAAiC,CAAC,MAAM,CAAC,GACpD,iCAAiC,CAAC,MAAM,CAAC,CAAC;AAK7C,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,oBAAoB,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB;AAED,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,OAAO,GAClB,OAAO,CAAC,UAAU,CAAC,CAmCrB"}

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"}

package/dist/tools/cli.d.ts

@@ -1,25 +1,36 @@
 import type { ServiceDef, StitchLogger } from '../server/types';
+import { type CliCommandDefinition } from './cli-command';
 import { type ExitCodeMap } from './cli-format';
 import { type CliWaitConfig } from './cli-wait';
 import { type ErrorHintFn, type ToolCallHooks, type ToolLifecycle } from './execute';
+import type { RuntimeToolDefinition } from './runtime-tool';
+export type CliSurfaceSource<TAuth, TValue> = readonly TValue[] | ((auth: Awaited<TAuth> | undefined) => readonly TValue[]);
 export interface CliConfig<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>> {
     /** Program name — shown in help and unknown-command messages. */
     name: string;
     /** Program version — printed by `--version`. */
     version: string;
     /** Contract services exposed as commands — may depend on the resolved identity. */
-    services: ServiceDef[] | ((auth: Awaited<TAuth> | undefined) => ServiceDef[]);
+    services?: CliSurfaceSource<TAuth, ServiceDef>;
+    /** Pathless managed operations. CLI exposure always requires `transports: ['CLI']`. */
+    runtimeTools?: CliSurfaceSource<TAuth, RuntimeToolDefinition>;
+    /** CLI-only executable commands, dispatched before auth and managed surface factories. */
+    commands?: readonly CliCommandDefinition[];
     /**
      * Identity for the single CLI invocation — resolved ONCE at startup (from an
      * env var / token file), like a stdio MCP server, not per call. A value or a
      * promise of one.
      */
     auth?: TAuth | Promise<TAuth>;
+    /** Lazily resolve identity only when a managed command/surface actually needs it. */
+    resolveAuth?: () => TAuth | Promise<TAuth>;
     /**
      * Context merged into every handler. Typed against the app's context shape
      * when the CLI is built via `createToolkit<AppContext>()`.
      */
     context?: (auth: Awaited<TAuth> | undefined) => TContext;
+    /** Explicit cancellation for this invocation; applications may bind SIGINT to it. */
+    signal?: AbortSignal;
     /** Tool-call observability hooks — `afterToolCall` fires for every result,
      *  `onToolError` for the raw value behind a thrown one. */
     hooks?: ToolCallHooks;
@@ -74,10 +85,6 @@ export interface CliConfig<TAuth = unknown, TContext extends Record<string, unkn
     /** Read piped stdin — default reads when not a TTY; injectable for tests. */
     stdin?: () => Promise<string | null>;
 }
-/**
- * Build and run a CLI from contract services, then exit. Parses `process.argv`
- * (or `config.argv`), routes to a command, executes it through the shared tool
- * pipeline and writes the result. Resolves identity once up front.
- */
+/** Build and run one mixed contract/runtime/native CLI surface, then exit. */
 export declare function createCli<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>>(config: CliConfig<TAuth, TContext>): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/tools/cli.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,EAAsB,KAAK,WAAW,EAAc,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,YAAY,CAAC;AAC/D,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAGnB,MAAM,WAAW,CAAC;AAMnB,MAAM,WAAW,SAAS,CACxB,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElE,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,KAAK,UAAU,EAAE,CAAC,CAAC;IAC9E;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,KAAK,QAAQ,CAAC;IACzD;+DAC2D;IAC3D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,wEAAwE;IACxE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE;;;OAGG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtC;AAsLD;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkMnD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/tools/cli.ts"],"names":[],"mappings":"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"}

package/dist/tools/define-download-tool.d.ts

@@ -0,0 +1,18 @@
+import type { ZodObject, z } from 'zod';
+import { ManagedFileRefSchema } from '../contract';
+import type { ManagedFileBoundary } from '../files/boundary';
+import { type ManagedNativeToolConfig } from './native-definition';
+import { type RuntimeToolDefinitionWithOutput, type RuntimeToolHandlerContext, type RuntimeToolPresenters } from './runtime-tool';
+export interface DefineDownloadToolConfig<TInput extends ZodObject> extends ManagedNativeToolConfig {
+    input: TInput;
+    resolveUrl: (input: z.output<TInput>, context: RuntimeToolHandlerContext<TInput>) => string | null | Promise<string | null>;
+    files: ManagedFileBoundary;
+    pathFromInput?: (input: z.output<TInput>) => string | undefined;
+    allowPrivateHosts?: boolean;
+    maxBytes?: number;
+    timeoutMs?: number;
+    present?: RuntimeToolPresenters<z.output<typeof ManagedFileRefSchema>>;
+}
+/** Define one guarded managed download operation. */
+export declare function defineDownloadTool<TInput extends ZodObject>(config: DefineDownloadToolConfig<TInput>): RuntimeToolDefinitionWithOutput<TInput, typeof ManagedFileRefSchema>;
+//# sourceMappingURL=define-download-tool.d.ts.map

package/dist/tools/define-download-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-download-tool.d.ts","sourceRoot":"","sources":["../../src/tools/define-download-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,EAAY,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,EAAE,KAAK,uBAAuB,EAAyB,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EAEL,KAAK,+BAA+B,EACpC,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,wBAAwB,CAAC,MAAM,SAAS,SAAS,CAChE,SAAQ,uBAAuB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,CACV,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EACvB,OAAO,EAAE,yBAAyB,CAAC,MAAM,CAAC,KACvC,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,KAAK,EAAE,mBAAmB,CAAC;IAC3B,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IAChE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC;CACxE;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,CAAC,MAAM,SAAS,SAAS,EACzD,MAAM,EAAE,wBAAwB,CAAC,MAAM,CAAC,GACvC,+BAA+B,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAC,CAiCtE"}

package/dist/tools/define-upload-tool.d.ts

@@ -0,0 +1,16 @@
+import { type ZodType, z } from 'zod';
+import type { ManagedFileBoundary, ManagedFileSource } from '../files/boundary';
+import { type ManagedNativeToolConfig } from './native-definition';
+import { type RuntimeToolDefinitionWithOutput, type RuntimeToolHandlerContext, type RuntimeToolPresenters } from './runtime-tool';
+export declare const UploadToolInputSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+export interface DefineUploadToolConfig<TOutput extends ZodType> extends ManagedNativeToolConfig {
+    output: TOutput;
+    files: ManagedFileBoundary;
+    upload: (source: ManagedFileSource, context: RuntimeToolHandlerContext<typeof UploadToolInputSchema>) => z.output<TOutput> | Promise<z.output<TOutput>>;
+    present?: RuntimeToolPresenters<z.output<TOutput>>;
+}
+/** Define one managed local-file upload operation. */
+export declare function defineUploadTool<TOutput extends ZodType>(config: DefineUploadToolConfig<TOutput>): RuntimeToolDefinitionWithOutput<typeof UploadToolInputSchema, TOutput>;
+//# sourceMappingURL=define-upload-tool.d.ts.map

package/dist/tools/define-upload-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-upload-tool.d.ts","sourceRoot":"","sources":["../../src/tools/define-upload-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,KAAK,uBAAuB,EAAyB,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EAEL,KAAK,+BAA+B,EACpC,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AAGxB,eAAO,MAAM,qBAAqB;;iBAEhC,CAAC;AAEH,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,OAAO,CAC7D,SAAQ,uBAAuB;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,CACN,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,yBAAyB,CAAC,OAAO,qBAAqB,CAAC,KAC7D,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;CACpD;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,OAAO,EACtD,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACtC,+BAA+B,CAAC,OAAO,qBAAqB,EAAE,OAAO,CAAC,CAkBxE"}

package/dist/tools/define-view-file-tool.d.ts

@@ -0,0 +1,10 @@
+import type { z } from 'zod';
+import { type ManagedNativeToolConfig } from './native-definition';
+import { type RuntimeToolDefinitionWithOutput, type RuntimeToolPresenters } from './runtime-tool';
+import { ViewFileInputSchema, type ViewFileOptions, ViewFileOutputSchema } from './view-file';
+export interface DefineViewFileToolConfig extends ManagedNativeToolConfig, ViewFileOptions {
+    present?: RuntimeToolPresenters<z.output<typeof ViewFileOutputSchema>>;
+}
+/** Define one protected managed multimodal media-inspection operation. */
+export declare function defineViewFileTool(config: DefineViewFileToolConfig): RuntimeToolDefinitionWithOutput<typeof ViewFileInputSchema, typeof ViewFileOutputSchema>;
+//# sourceMappingURL=define-view-file-tool.d.ts.map

package/dist/tools/define-view-file-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-view-file-tool.d.ts","sourceRoot":"","sources":["../../src/tools/define-view-file-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAE,KAAK,uBAAuB,EAAyB,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EAIL,KAAK,+BAA+B,EACpC,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,mBAAmB,EACnB,KAAK,eAAe,EACpB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB,EAAE,eAAe;IACxF,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC;CACxE;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,wBAAwB,GAC/B,+BAA+B,CAAC,OAAO,mBAAmB,EAAE,OAAO,oBAAoB,CAAC,CAwC1F"}

package/dist/tools/define-wait-tool.d.ts

@@ -0,0 +1,22 @@
+import type { ZodObject, ZodType, z } from 'zod';
+import { type ManagedNativeToolConfig } from './native-definition';
+import { type RuntimeToolDefinitionWithOutput, type RuntimeToolHandlerContext, type RuntimeToolPresenters } from './runtime-tool';
+export interface ManagedWaitRender {
+    text: string;
+    isError: boolean;
+}
+export interface DefineWaitToolConfig<TInput extends ZodObject, TState extends ZodType> extends ManagedNativeToolConfig {
+    input: TInput;
+    state: TState;
+    poll: (input: z.output<TInput>, context: RuntimeToolHandlerContext<TInput>) => unknown | Promise<unknown>;
+    done: (state: z.output<TState>) => boolean;
+    timeoutFromInput?: (input: z.output<TInput>) => number | undefined;
+    backoff?: number[];
+    defaultTimeout?: number;
+    /** Optional pure MCP renderer; `isError` also classifies terminal domain failure. */
+    render?: (state: z.output<TState>, timedOut: boolean) => ManagedWaitRender;
+    present?: RuntimeToolPresenters<z.output<TState>>;
+}
+/** Define one managed wait operation for `runtimeTools` and/or Agent tools. */
+export declare function defineWaitTool<TInput extends ZodObject, TState extends ZodType>(config: DefineWaitToolConfig<TInput, TState>): RuntimeToolDefinitionWithOutput<TInput, TState>;
+//# sourceMappingURL=define-wait-tool.d.ts.map

package/dist/tools/define-wait-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-wait-tool.d.ts","sourceRoot":"","sources":["../../src/tools/define-wait-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEjD,OAAO,EAAE,KAAK,uBAAuB,EAAyB,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EAGL,KAAK,+BAA+B,EACpC,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AAGxB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,SAAS,SAAS,EAAE,MAAM,SAAS,OAAO,CACpF,SAAQ,uBAAuB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CACJ,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EACvB,OAAO,EAAE,yBAAyB,CAAC,MAAM,CAAC,KACvC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC;IAC3C,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,OAAO,KAAK,iBAAiB,CAAC;IAC3E,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;CACnD;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,MAAM,SAAS,SAAS,EAAE,MAAM,SAAS,OAAO,EAC7E,MAAM,EAAE,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,+BAA+B,CAAC,MAAM,EAAE,MAAM,CAAC,CA4DjD"}

package/dist/tools/download-core.d.ts

@@ -0,0 +1,20 @@
+import type { ManagedFileRef } from '../contract/file-ref';
+import type { ManagedFileBoundary } from '../files/boundary';
+/** Expected, caller-safe download failure; unexpected runtime errors still throw raw. */
+export declare class DownloadOperationError extends Error {
+    readonly code: 'DOWNLOAD_HTTP_ERROR' | 'DOWNLOAD_TOO_LARGE';
+    readonly status: number;
+    constructor(code: 'DOWNLOAD_HTTP_ERROR' | 'DOWNLOAD_TOO_LARGE', message: string, status: number);
+}
+export interface DownloadOperationConfig {
+    url: string;
+    files: ManagedFileBoundary;
+    path?: string;
+    allowPrivateHosts?: boolean;
+    maxBytes?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** Fetch and persist one URL without owning tool registration or presentation. */
+export declare function runDownloadOperation(config: DownloadOperationConfig): Promise<ManagedFileRef>;
+//# sourceMappingURL=download-core.d.ts.map

package/dist/tools/download-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-core.d.ts","sourceRoot":"","sources":["../../src/tools/download-core.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAkB7D,yFAAyF;AACzF,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,IAAI,EAAE,qBAAqB,GAAG,oBAAoB;aAElD,MAAM,EAAE,MAAM;IAHhC,YACkB,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,EAClE,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EAI/B;CACF;AAwBD,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,mBAAmB,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,kFAAkF;AAClF,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,cAAc,CAAC,CA6BzB"}

package/dist/tools/execute.d.ts

@@ -1,5 +1,5 @@
 import type { ZodType, z } from 'zod';
-import { AppError, type RuntimeContext, type TransportSource } from '../contract';
+import { AppError, type McpCallContext, type RuntimeContext, type TransportSource } from '../contract';
 import type { OperationIdentity } from '../server/types';
 export type ToolResult = {
     ok: true;
@@ -15,6 +15,8 @@ type ToolFailure = Extract<ToolResult, {
 }>;
 export interface ToolCallContext {
     source: TransportSource;
+    /** Validated metadata for an MCP call; absent on every other transport. */
+    mcp?: McpCallContext;
     [key: string]: unknown;
 }
 export interface BeforeToolCallOptions {

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

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"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"}

package/dist/tools/lifecycle.d.ts

@@ -0,0 +1,4 @@
+import type { ToolLifecycle } from './execute';
+/** Compose tool lifecycle hooks without inventing HTTP-only phases. */
+export declare function composeToolLifecycle(...hooks: readonly (ToolLifecycle | undefined)[]): ToolLifecycle;
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/tools/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,uEAAuE;AACvE,wBAAgB,oBAAoB,CAClC,GAAG,KAAK,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,EAAE,GAC/C,aAAa,CAcf"}

package/dist/tools/mcp-round.d.ts

@@ -16,7 +16,6 @@ export interface McpRoundState {
     round: number;
     accepted: Record<string, unknown>;
 }
-export type McpRoundOutcome = 'input_required' | 'declined' | 'cancelled' | 'invalid' | 'complete';
 export interface McpRoundRuntime {
     codec: RequestStateCodec<McpRoundState>;
     maxRounds: number;

package/dist/tools/mcp-round.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-round.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-round.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,mBAAmB,EAIxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAY,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,sBAAsB,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,UAAU,GAAG,CAChB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,cAAc,GAAG,mBAAmB,CAAA;CAAE,CAAC;AAsHzE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE;IAAE,eAAe,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxD,IAAI,CA6BN;AAsBD,qFAAqF;AACrF,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAC7C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,cAAc,CAAC;CACvD,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmK9B"}
+{"version":3,"file":"mcp-round.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-round.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,mBAAmB,EAIxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAEL,KAAK,iBAAiB,EAGvB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,sBAAsB,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,UAAU,GAAG,CAChB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,cAAc,GAAG,mBAAmB,CAAA;CAAE,CAAC;AAsHzE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE;IAAE,eAAe,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxD,IAAI,CA6BN;AAsBD,qFAAqF;AACrF,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAC7C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,cAAc,CAAC;CACvD,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmK9B"}

package/dist/tools/mcp-stdio-signals.d.ts

@@ -0,0 +1,33 @@
+import type { ProcessSignalName, SignalSource } from '../server/process-signals';
+import type { McpStdioHandle } from './mcp-stdio';
+export type StdioProcessSignalsErrorPhase = 'prepare' | 'close' | 'complete';
+export interface StdioProcessSignalsOptions {
+    /** Defaults to `['SIGINT', 'SIGTERM']`; duplicates are ignored. */
+    signals?: readonly ProcessSignalName[];
+    signalSource?: SignalSource;
+    /** Runs before the transport closes. Failure is reported and close still runs. */
+    onClose?: (signal: ProcessSignalName) => void | Promise<void>;
+    /** Runs after the official stdio handle has closed. */
+    onComplete?: () => void | Promise<void>;
+    onError?: (phase: StdioProcessSignalsErrorPhase, error: unknown) => void;
+    /** A later signal cannot force stdio close, so it always means escalation. */
+    onRepeatedSignal?: (signal: ProcessSignalName) => void;
+    /** Called when another listener prevents restoration of the default disposition. */
+    onEscalationBlocked?: (signal: ProcessSignalName) => void;
+}
+export interface StdioProcessSignalsBinding {
+    /** Resolves after close, or `undefined` when an idle binding is removed. */
+    readonly promise: Promise<void>;
+    /** Remove listeners. Idempotent; does not cancel an already-running close. */
+    close(): void;
+}
+export type StdioCloseTarget = Pick<McpStdioHandle, 'close'>;
+/**
+ * Bind process signals to one close-only stdio MCP handle.
+ *
+ * Unlike managed HTTP shutdown, stdio exposes no deadline or force method. A
+ * later signal therefore removes this binding and restores the signal's default
+ * disposition instead of pretending an AbortSignal can affect `close()`.
+ */
+export declare function bindStdioProcessSignals(handle: StdioCloseTarget, options?: StdioProcessSignalsOptions): StdioProcessSignalsBinding;
+//# sourceMappingURL=mcp-stdio-signals.d.ts.map

package/dist/tools/mcp-stdio-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-stdio-signals.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-stdio-signals.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,MAAM,6BAA6B,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7E,MAAM,WAAW,0BAA0B;IACzC,mEAAmE;IACnE,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,kFAAkF;IAClF,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,6BAA6B,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACzE,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACvD,oFAAoF;IACpF,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,0BAA0B;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,8EAA8E;IAC9E,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAI7D;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,0BAA+B,GACvC,0BAA0B,CAkG5B"}