stitchkit 0.54.0 → 0.55.0

package/README.md

@@ -85,9 +85,12 @@ Server code imports server entrypoints:
 import { createServer, createHandler, implement } from 'stitchkit/server'
 import { createSocketIOServer, createAuthHook } from 'stitchkit/server'
 import { createMcpHandler, mountAgent } from 'stitchkit/tools'
+import { implementRemote } from 'stitchkit/remote'
 ```
 
-The root `stitchkit` entrypoint is browser-safe. Server and tool code live behind `stitchkit/server` and `stitchkit/tools`.
+The root `stitchkit` entrypoint is browser-safe. Server, tool and peer-free
+remote-proxy code live behind `stitchkit/server`, `stitchkit/tools` and
+`stitchkit/remote` respectively.
 
 ## Quick Start
 

package/dist/browser/socket-io.d.ts

@@ -22,7 +22,8 @@
  */
 import type { EventsMap } from '@socket.io/component-emitter';
 import type { StitchLogger } from '../logger';
-import type { RealtimeContract, RealtimeEventRegistry, RealtimeRejectedEventHook } from '../realtime/contract';
+import type { RealtimeAcknowledgedEvent, RealtimeAcknowledgement, RealtimeContract, RealtimeEventRegistry, RealtimeRejectedEventHook, RealtimeRequestArguments } from '../realtime/contract';
+import { type RealtimeRequestOptions } from '../realtime/request';
 import { type ValidatedRealtimeSocket } from '../realtime/socket';
 /**
  * Socket.IO event map — `{ event: (...args) => void }`. Aliases Socket.IO's
@@ -143,6 +144,11 @@ export interface SocketIOClient<TServerEvents extends SocketEventMap, TClientEve
      * of an unordered backlog of stale emits.
      */
     emit<E extends keyof TClientEvents & string>(event: E, ...args: Parameters<TClientEvents[E]>): boolean;
+    /**
+     * Low-level native Socket.IO acknowledgement request. Contract-aware callers
+     * should use `createRealtimeClient().request()`, which validates both sides.
+     */
+    emitWithAck(event: string, args: unknown[], options: RealtimeRequestOptions): Promise<unknown>;
     /**
      * Subscribe to connection up/down changes. Returns an unsubscribe. On a
      * disconnect the listener also receives the Socket.IO **reason** (e.g.
@@ -156,6 +162,10 @@ export interface RealtimeClient<TServerToClient extends RealtimeEventRegistry, T
     connect(): void;
     disconnect(): void;
     readonly connected: boolean;
+    request<TEvent extends RealtimeAcknowledgedEvent<TClientToServer>>(event: TEvent, ...args: [
+        ...RealtimeRequestArguments<TClientToServer[TEvent]>,
+        options: RealtimeRequestOptions
+    ]): Promise<RealtimeAcknowledgement<TClientToServer[TEvent]>>;
     onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void;
 }
 export interface RealtimeClientOptions<TServerToClient extends RealtimeEventRegistry> extends SocketIOClientConfig<{

package/dist/browser/socket-io.d.ts.map

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

package/dist/cli.js

@@ -5,15 +5,20 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-7vb44hy8.js";
-import"./index-yxpe3phd.js";
-import"./index-173tvqcp.js";
-import"./index-bmnhqtya.js";
+} from "./index-0gv7k0ra.js";
+import"./index-sbdmyz75.js";
+import"./index-k4dftwf7.js";
+import"./index-cby4ar3v.js";
+import"./index-v4bbq3p4.js";
+import"./index-h60df7rj.js";
+import"./index-6k1937bx.js";
+import"./index-7eq9va6e.js";
+import"./index-1bx83sw4.js";
 export {
-  pollUntilDone,
-  parseCliArgs,
-  emitResult,
-  defineCliCommand,
+  DEFAULT_EXIT_CODES,
   createCli,
-  DEFAULT_EXIT_CODES
+  defineCliCommand,
+  emitResult,
+  parseCliArgs,
+  pollUntilDone
 };

package/dist/contract/file-ref.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+/** Canonical POSIX-style path relative to a managed file boundary. */
+export declare const ManagedFilePathSchema: z.ZodString;
+/** Transport-safe identity and metadata for a file owned by a managed boundary. */
+export declare const ManagedFileRefSchema: z.ZodObject<{
+    path: z.ZodString;
+    size: z.ZodNumber;
+    mediaType: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ManagedFilePath = z.infer<typeof ManagedFilePathSchema>;
+export type ManagedFileRef = z.infer<typeof ManagedFileRefSchema>;
+//# sourceMappingURL=file-ref.d.ts.map

package/dist/contract/file-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-ref.d.ts","sourceRoot":"","sources":["../../src/contract/file-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,aAE6C,CAAC;AAEhF,mFAAmF;AACnF,eAAO,MAAM,oBAAoB;;;;;iBAK/B,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/contract/index.d.ts

@@ -2,5 +2,6 @@ export { ALL_TRANSPORTS, type BodyHttpSuccessStatus, type ClientRequestOptions,
 export { AppError, appError, badRequest, conflict, type ErrorEnvelope, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from './errors';
 export { type DefinedAppError, type DefinedErrors, defineErrors, type ErrorDefinition, type ErrorDefinitions, type ErrorDetailsOutput, type ErrorDetailsSchema, type ErrorFactories, type ErrorFactory, type ErrorFactoryArguments, type FrozenErrorDefinitions, } from './errors-factory';
 export { type ContractFactoryConfig, type ContractFactoryToolExposure, createContractFactory, type ExplicitScopedDefineContract, type ExplicitToolExposureEndpoints, type FactoryScopedEndpoint, type ScopedContractDef, type ScopedDefineContract, } from './factory';
+export { type ManagedFilePath, ManagedFilePathSchema, type ManagedFileRef, ManagedFileRefSchema, } from './file-ref';
 export { decodeCursor, encodeCursor, type Paginated, paginatedSchema, } from './pagination';
 //# sourceMappingURL=index.d.ts.map

package/dist/contract/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,aAAa,EAClB,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EACd,eAAe,GAChB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,aAAa,EAClB,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,cAAc,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EACd,eAAe,GAChB,MAAM,cAAc,CAAC"}

package/dist/contract/index.js

@@ -1,6 +1,8 @@
 import {
   ALL_TRANSPORTS,
   AppError,
+  ManagedFilePathSchema,
+  ManagedFileRefSchema,
   STITCH_ERROR_STATUS,
   appError,
   badRequest,
@@ -16,24 +18,26 @@ import {
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "../index-pfqjb5xy.js";
+} from "../index-rgd18hx3.js";
 import"../index-tss6bk5c.js";
 export {
-  unauthorized,
-  rateLimited,
-  paginatedSchema,
-  notFound,
-  isStitchErrorCode,
-  forbidden,
-  encodeCursor,
-  defineErrors,
-  defineContract,
-  decodeCursor,
-  createContractFactory,
-  conflict,
-  badRequest,
-  appError,
-  STITCH_ERROR_STATUS,
+  ALL_TRANSPORTS,
   AppError,
-  ALL_TRANSPORTS
+  ManagedFilePathSchema,
+  ManagedFileRefSchema,
+  STITCH_ERROR_STATUS,
+  appError,
+  badRequest,
+  conflict,
+  createContractFactory,
+  decodeCursor,
+  defineContract,
+  defineErrors,
+  encodeCursor,
+  forbidden,
+  isStitchErrorCode,
+  notFound,
+  paginatedSchema,
+  rateLimited,
+  unauthorized
 };

package/dist/files/boundary.d.ts

@@ -0,0 +1,52 @@
+import { type ManagedFileRef } from '../contract/file-ref';
+export type ManagedFileErrorCode = 'FILE_INVALID_PATH' | 'FILE_NOT_FOUND' | 'FILE_NOT_REGULAR' | 'FILE_OUTSIDE_ROOT' | 'FILE_TOO_LARGE' | 'FILE_EXISTS' | 'FILE_INSPECTION_REJECTED' | 'FILE_IO_ERROR';
+export declare class ManagedFileError extends Error {
+    readonly code: ManagedFileErrorCode;
+    constructor(code: ManagedFileErrorCode, message: string, options?: ErrorOptions);
+}
+export interface ManagedFileInspectionInput {
+    prefix: Uint8Array;
+    declaredMediaType?: string;
+    name: string;
+}
+export interface ManagedFileInspection {
+    mediaType?: string;
+    name?: string;
+}
+export type ManagedFileInspector = (input: ManagedFileInspectionInput) => ManagedFileInspection | Promise<ManagedFileInspection>;
+export interface ManagedFileBoundaryConfig {
+    /** Existing directory owned exclusively by the application or trusted OS actor. */
+    root: string;
+    maxReadBytes?: number;
+    maxWriteBytes?: number;
+    inspectionBytes?: number;
+    inspect?: ManagedFileInspector;
+    onCleanupError?: (error: unknown) => void;
+}
+export interface ManagedFileReadOptions {
+    maxBytes?: number;
+    signal?: AbortSignal;
+}
+export interface ManagedFileWriteOptions {
+    replace?: boolean;
+    durable?: boolean;
+    maxBytes?: number;
+    mediaType?: string;
+    name?: string;
+    signal?: AbortSignal;
+}
+export interface ManagedFileSource {
+    ref: ManagedFileRef;
+    bytes: Uint8Array;
+}
+export interface ManagedFileBoundary {
+    read(path: string, options?: ManagedFileReadOptions): Promise<ManagedFileSource>;
+    write(path: string, source: Uint8Array | ReadableStream<Uint8Array>, options?: ManagedFileWriteOptions): Promise<ManagedFileRef>;
+}
+/**
+ * Bind one existing application-owned directory as a portable Node/Bun file boundary.
+ * Concurrent replacement by another filesystem actor is intentionally outside this
+ * portable threat model; use OS-specific descriptor-relative isolation for that case.
+ */
+export declare function createManagedFileBoundary(config: ManagedFileBoundaryConfig): Promise<ManagedFileBoundary>;
+//# sourceMappingURL=boundary.d.ts.map

package/dist/files/boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.d.ts","sourceRoot":"","sources":["../../src/files/boundary.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAO9B,MAAM,MAAM,oBAAoB,GAC5B,mBAAmB,GACnB,gBAAgB,GAChB,kBAAkB,GAClB,mBAAmB,GACnB,gBAAgB,GAChB,aAAa,GACb,0BAA0B,GAC1B,eAAe,CAAC;AAEpB,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,IAAI,EAAE,oBAAoB;IAD5C,YACkB,IAAI,EAAE,oBAAoB,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,EAIvB;CACF;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,KAAK,EAAE,0BAA0B,KAC9B,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAE5D,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACjF,KAAK,CACH,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,EAC/C,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAyID;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAqJ9B"}

package/dist/files.d.ts

@@ -0,0 +1,3 @@
+export { type ManagedFilePath, ManagedFilePathSchema, type ManagedFileRef, ManagedFileRefSchema, } from './contract/file-ref';
+export { createManagedFileBoundary, type ManagedFileBoundary, type ManagedFileBoundaryConfig, ManagedFileError, type ManagedFileErrorCode, type ManagedFileInspection, type ManagedFileInspectionInput, type ManagedFileInspector, type ManagedFileReadOptions, type ManagedFileSource, type ManagedFileWriteOptions, } from './files/boundary';
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,cAAc,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAC"}

package/dist/files.js

@@ -0,0 +1,16 @@
+import {
+  ManagedFileError,
+  createManagedFileBoundary
+} from "./index-1k16zv57.js";
+import"./index-sbdmyz75.js";
+import {
+  ManagedFilePathSchema,
+  ManagedFileRefSchema
+} from "./index-6k1937bx.js";
+import"./index-1bx83sw4.js";
+export {
+  ManagedFileError,
+  ManagedFilePathSchema,
+  ManagedFileRefSchema,
+  createManagedFileBoundary
+};

package/dist/{index-7vb44hy8.js → index-0gv7k0ra.js}

@@ -1,23 +1,33 @@
 import {
-  isWithinDir,
+  isWithinDir
+} from "./index-sbdmyz75.js";
+import {
+  assertToolName,
+  assertUniqueToolName,
+  hasUsableChars,
+  toToolName
+} from "./index-k4dftwf7.js";
+import {
   jsonSchemaFields,
   toJsonSchema
-} from "./index-yxpe3phd.js";
+} from "./index-cby4ar3v.js";
 import {
-  AppError,
-  STITCH_ERROR_STATUS,
   formatZodError,
   getRequestContext,
-  isStitchErrorCode,
-  isUnsafeKey,
   normalizeError,
   runWithRequestContext,
-  safeJsonParse,
   validateDeclaredOutput
-} from "./index-173tvqcp.js";
+} from "./index-v4bbq3p4.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS,
+  isStitchErrorCode,
+  isUnsafeKey,
+  safeJsonParse
+} from "./index-h60df7rj.js";
 import {
   isRecord
-} from "./index-bmnhqtya.js";
+} from "./index-7eq9va6e.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";
@@ -769,71 +779,6 @@ async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycl
   }
 }
 
-// src/tools/names.ts
-var SINGULAR_EXCEPTIONS = new Set([
-  "analytics",
-  "status",
-  "stats",
-  "settings",
-  "media",
-  "progress",
-  "news"
-]);
-var TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
-function normalizeService(value) {
-  return value.replace(/[^a-zA-Z0-9_]/g, "_");
-}
-function normalizeMethod(value) {
-  return value.replace(/[^a-zA-Z0-9_-]/g, "_");
-}
-function singularize(name) {
-  if (SINGULAR_EXCEPTIONS.has(name))
-    return name;
-  if (name.endsWith("ies"))
-    return `${name.slice(0, -3)}y`;
-  if (name.endsWith("s") && !name.endsWith("ss"))
-    return name.slice(0, -1);
-  return name;
-}
-function singularizeTail(name) {
-  const cut = name.lastIndexOf("_");
-  if (cut === -1)
-    return singularize(name);
-  return `${name.slice(0, cut + 1)}${singularize(name.slice(cut + 1))}`;
-}
-function hasUsableChars(value) {
-  return /[a-zA-Z0-9]/.test(value);
-}
-function assertToolName(name, serviceName, key) {
-  const where = `service "${serviceName}", method "${key}"`;
-  if (!TOOL_NAME_RE.test(name)) {
-    const why = name.length > 64 ? `is ${name.length} characters (max 64) — set an explicit \`toolName\`` : "must match [a-zA-Z0-9_-]";
-    throw new Error(`Tool name "${name}" (${where}) ${why}`);
-  }
-}
-function toToolName(serviceName, methodName) {
-  const normalized = normalizeService(serviceName);
-  const singular = singularizeTail(normalized);
-  const method = normalizeMethod(methodName);
-  if (method === "list")
-    return `list_${normalized}`;
-  if (method === "get")
-    return `get_${singular}`;
-  if (method === "create")
-    return `create_${singular}`;
-  if (method === "update")
-    return `update_${singular}`;
-  if (method === "delete")
-    return `delete_${singular}`;
-  const snake = method.replace(/([A-Z])/g, "_$1").toLowerCase();
-  return `${snake}_${singular}`.replace(/^_/, "");
-}
-function assertUniqueToolName(name, taken, surface) {
-  if (taken) {
-    throw new Error(`Duplicate ${surface} "${name}" across mounted operations`);
-  }
-}
-
 // src/tools/presentation.ts
 import { z as z3 } from "zod";
 function withoutDialect(schema) {
@@ -1494,19 +1439,21 @@ var DEFAULT_EXIT_CODES = {
   CONFLICT: 5,
   RATE_LIMITED: 6,
   TIMEOUT: 7,
+  WAIT_FAILED: 1,
   INTERNAL_SERVER_ERROR: 1
 };
 function emitResult(result, writers, opts) {
   if (result.ok) {
     if (result.data === undefined)
       return 0;
-    const text = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
-    writers.stdout(`${text}
+    const text2 = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
+    writers.stdout(`${text2}
 `);
     return 0;
   }
   const error = formatToolError(result, opts.toolName, opts.errorHint);
-  writers.stderr(`${JSON.stringify(error, null, 2)}
+  const text = opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2);
+  writers.stderr(`${text}
 `);
   const codes = opts.exitCodes ?? DEFAULT_EXIT_CODES;
   return codes[result.code] ?? 1;
@@ -1515,6 +1462,13 @@ function emitResult(result, writers, opts) {
 // src/tools/wait-core.ts
 var DEFAULT_BACKOFF = [2, 3, 5, 5, 8, 10];
 var DEFAULT_TIMEOUT = 600;
+
+class WaitTimeoutError extends Error {
+  constructor() {
+    super("wait deadline elapsed before the first snapshot");
+    this.name = "WaitTimeoutError";
+  }
+}
 var defaultSleep = (ms, signal) => {
   signal?.throwIfAborted();
   return new Promise((resolve, reject) => {
@@ -1544,52 +1498,104 @@ async function pollUntil(params) {
   const lastBackoff = backoff[backoff.length - 1] ?? 5;
   const timeoutSec = params.timeoutSec ?? DEFAULT_TIMEOUT;
   const sleep = params.sleepFn ?? defaultSleep;
-  const startedAt = Date.now();
+  const now = params.nowFn ?? (() => performance.now());
+  const startedAt = now();
+  const deadline = startedAt + timeoutSec * 1000;
+  let last;
   for (let attempt = 0;; attempt++) {
     params.signal?.throwIfAborted();
-    const state = await params.poll();
+    const remainingBeforePoll = Math.max(0, deadline - now());
+    if (remainingBeforePoll === 0 && last) {
+      return { state: last.state, timedOut: true };
+    }
+    const deadlineController = new AbortController;
+    const onCallerAbort = () => deadlineController.abort(params.signal?.reason);
+    params.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    const deadlineTimer = setTimeout(() => deadlineController.abort(new WaitTimeoutError), remainingBeforePoll);
+    deadlineTimer.unref?.();
+    let state;
+    try {
+      state = await params.poll(deadlineController.signal);
+    } catch (error) {
+      if (params.signal?.aborted)
+        throw params.signal.reason ?? error;
+      if (deadlineController.signal.aborted && now() >= deadline) {
+        if (last)
+          return { state: last.state, timedOut: true };
+        throw new WaitTimeoutError;
+      }
+      throw error;
+    } finally {
+      clearTimeout(deadlineTimer);
+      params.signal?.removeEventListener("abort", onCallerAbort);
+    }
     params.signal?.throwIfAborted();
+    last = { state };
     if (params.done(state))
       return { state, timedOut: false };
-    const elapsedSec = (Date.now() - startedAt) / 1000;
+    const elapsedMs = now() - startedAt;
+    const elapsedSec = elapsedMs / 1000;
     params.onTick?.(attempt + 1, elapsedSec);
     if (elapsedSec >= timeoutSec)
       return { state, timedOut: true };
     const waitSec = backoff[Math.min(attempt, backoff.length - 1)] ?? lastBackoff;
-    await sleep(waitSec * 1000, params.signal);
+    await sleep(Math.min(waitSec * 1000, Math.max(0, deadline - now())), params.signal);
   }
 }
 function runWaitOperation(params) {
   return pollUntil({
-    poll: () => params.poll(params.input, params.signal),
+    poll: (signal) => params.poll(params.input, signal),
     done: params.done,
     backoff: params.backoff,
     timeoutSec: params.timeoutSec,
     sleepFn: params.sleepFn,
     onTick: params.onTick,
-    signal: params.signal
+    signal: params.signal,
+    nowFn: params.nowFn
   });
 }
 
 // src/tools/cli-wait.ts
 var DEFAULT_TIMEOUT2 = 600;
+function waitFailure(tool, result) {
+  return {
+    ok: false,
+    code: "WAIT_FAILED",
+    details: {
+      message: `"${tool}" reached a terminal failed state`,
+      result
+    }
+  };
+}
 async function pollUntilDone(params) {
   const { initial, wait, call } = params;
   if (!initial.ok)
     return initial;
+  if (wait.failed?.(initial.data))
+    return waitFailure(wait.tool, initial.data);
   if (wait.done(initial.data))
     return initial;
   const pollArgs = wait.poll(initial.data);
   if (!pollArgs)
     return initial;
   const timeoutSec = params.timeoutSec ?? wait.timeout ?? DEFAULT_TIMEOUT2;
+  let failedState;
   const { state, timedOut } = await pollUntil({
     poll: () => call(wait.tool, pollArgs),
-    done: (result) => !result.ok || wait.done(result.data),
+    done: (result) => {
+      if (!result.ok)
+        return true;
+      if (wait.failed?.(result.data)) {
+        failedState = result;
+        return true;
+      }
+      return wait.done(result.data);
+    },
     backoff: wait.backoff,
     timeoutSec,
     sleepFn: params.sleepFn,
-    onTick: params.onTick
+    onTick: params.onTick,
+    signal: params.signal
   });
   if (timedOut) {
     return {
@@ -1598,6 +1604,8 @@ async function pollUntilDone(params) {
       details: { message: `Timed out after ${timeoutSec}s waiting for "${wait.tool}"` }
     };
   }
+  if (state === failedState && state.ok)
+    return waitFailure(wait.tool, state.data);
   return state;
 }
 
@@ -1961,7 +1969,7 @@ function collectToolSurface({
 
 // src/tools/cli.ts
 var GLOBAL_OPTIONS = [
-  ["--json", "Emit raw JSON on stdout (for piping / scripts)"],
+  ["--json", "Emit compact success/error JSON records (for scripts)"],
   ["--wait", "Block-poll an async result to a terminal state"],
   ["--wait-timeout <s>", "Override the --wait timeout in seconds"],
   ["--output-dir <dir>", "Download result media into a directory"],
@@ -2058,15 +2066,41 @@ function renderTopHelp(name, version, commands) {
 `;
 }
 function renderCommandHelp(name, command, descriptor) {
-  const lines = [descriptor.description, "", `Usage: ${name} ${command} [args] [--flags]`, ""];
   const fields = jsonSchemaFields(descriptor.presentationSchema);
+  const fieldsByName = new Map(fields.map((field) => [field.name, field]));
+  const positionals = [];
+  for (const [fieldName, info] of describeSchemaFields(descriptor.argumentSchema)) {
+    if (info.kind === "boolean")
+      continue;
+    const field = fieldsByName.get(fieldName);
+    if (field)
+      positionals.push(field);
+  }
+  const positionalSyntax = new Map(positionals.map((field) => [
+    field.name,
+    field.required ? `<${field.name}>` : `[${field.name}]`
+  ]));
+  const usage = [
+    `Usage: ${name} ${command}`,
+    ...positionals.map((field) => positionalSyntax.get(field.name) ?? field.name),
+    "[--flags]"
+  ].join(" ");
+  const lines = [descriptor.description, "", usage, ""];
   if (fields.length > 0) {
     lines.push("Arguments:");
-    const width = Math.max(...fields.map((f) => f.name.length));
+    const labels = new Map(fields.map((field) => {
+      const positional = positionalSyntax.get(field.name);
+      return [
+        field.name,
+        positional ? `${positional} | --${field.name}` : `--${field.name}`
+      ];
+    }));
+    const width = Math.max(...fields.map((field) => labels.get(field.name)?.length ?? 0));
     for (const f of fields) {
       const req = f.required ? " (required)" : "";
       const desc = f.description ? ` — ${f.description}` : "";
-      lines.push(`  --${padRight(f.name, width)}  <${typeLabel(f.schema)}>${req}${desc}`);
+      const label = labels.get(f.name) ?? `--${f.name}`;
+      lines.push(`  ${padRight(label, width)}  <${typeLabel(f.schema)}>${req}${desc}`);
     }
     lines.push("");
   }
@@ -2302,7 +2336,7 @@ async function createCli(config) {
   }
   const runTool = createToolRunner({
     source: "cli",
-    context: config.context?.(managed.auth),
+    context: { ...config.context?.(managed.auth), signal: config.signal },
     hooks: config.hooks,
     lifecycle: config.lifecycle,
     errorHint: config.errorHint,
@@ -2332,7 +2366,8 @@ async function createCli(config) {
       },
       timeoutSec: options.waitTimeout,
       onTick: options.quiet ? undefined : (attempt) => stderr(`waiting… (poll ${attempt})
-`)
+`),
+      signal: config.signal
     });
   }
   let downloadsOk = true;
@@ -2348,4 +2383,4 @@ async function createCli(config) {
   return exit(downloadsOk ? exitCode : 1);
 }
 
-export { coerceJsonArgs, toolResultFromError, toolErrorFromResult, executeToolMethod, assertToolName, assertUniqueToolName, flattenToolJsonSchema, buildToolPresentationSchema, isObjectPresentationSchema, presentationMetadata, collectTools, createToolRunner, formatToolError, defineRuntimeTool, createRuntimeToolFactory, collectToolSurface, fetchGuarded, fetchPinnedDocument, readCapped, writeDownload, parseCliArgs, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, runWaitOperation, pollUntilDone, createCli };
+export { coerceJsonArgs, toolResultFromError, toolErrorFromResult, executeToolMethod, flattenToolJsonSchema, buildToolPresentationSchema, isObjectPresentationSchema, presentationMetadata, collectTools, createToolRunner, formatToolError, defineRuntimeTool, createRuntimeToolFactory, collectToolSurface, WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, parseCliArgs, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, pollUntilDone, createCli };

package/dist/index-1bx83sw4.js

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+export { __require };