@codespar/types 0.10.5 → 0.10.9

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./types.js";
 export * from "./guards.js";
+export * from "./meta-tool-contract.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from "./types.js";
 export * from "./guards.js";
+export * from "./meta-tool-contract.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC"}

package/dist/meta-tool-contract.d.ts

@@ -0,0 +1,162 @@
+/**
+ * A field's required wire shape, expressed as a JSON-value kind. The kit
+ * uses these to assert wire-shape validity without importing a schema
+ * library: each kind maps to a `typeof`/`Array.isArray` check.
+ *
+ * `string-enum` additionally constrains the value to a closed set (see
+ * {@link FieldRule.values}).
+ */
+export type FieldKind = "string" | "string-enum" | "number" | "boolean" | "object" | "array";
+/** One field's contract within a wire shape. */
+export interface FieldRule {
+    /** The field name on the wire object. */
+    name: string;
+    /** The required JSON-value kind. */
+    kind: FieldKind;
+    /** Whether the field must be present (and non-null). Defaults to true. */
+    required?: boolean;
+    /** Closed value set — required when `kind` is "string-enum". */
+    values?: readonly string[];
+}
+/**
+ * A named wire shape: the set of field rules an instance of the shape must
+ * satisfy. A conforming implementation MAY carry optional fields beyond
+ * these (subset-shape), but MUST carry every `required` field with the
+ * stated kind.
+ */
+export interface WireShape {
+    /** The interface name in `types.ts`, e.g. "ShopSearchResult". */
+    name: string;
+    /** Field-level rules the result object must satisfy. */
+    fields: readonly FieldRule[];
+}
+/**
+ * One action a meta-tool exposes, with the input it is driven by and the
+ * result wire shape it returns. `terminal` marks an action whose result
+ * carries a terminal status (the state machine cannot advance past it).
+ */
+export interface ActionRule {
+    /** The `action` discriminator value, e.g. "search". */
+    action: string;
+    /** A minimal valid input the kit can post to drive this action. The
+     *  `action` field is added by the kit, so omit it here. */
+    sampleInput: Record<string, unknown>;
+    /** The result wire shape this action returns. */
+    result: WireShape;
+    /** The `status` field on the result that the state machine reads, when
+     *  this action's result participates in the state machine. */
+    statusField?: string;
+}
+/**
+ * The action state machine for a meta-tool. `actions` is keyed by the
+ * `action` discriminator; `terminalStatuses` is the closed set of status
+ * values that end a flow (no further action advances past them); `start`
+ * names the action a flow begins at.
+ *
+ * Example (shop): start `search`, advance through `checkout` to
+ * `checkout_status`, whose `ready_for_payment` / `canceled` are terminal.
+ */
+export interface ActionStateMachine {
+    /** The action a flow begins at. */
+    start: string;
+    /** Every action the tool exposes, keyed by the discriminator value. */
+    actions: readonly ActionRule[];
+    /** Status values that terminate a flow. */
+    terminalStatuses: readonly string[];
+}
+/**
+ * The error rules a meta-tool must honor. These are the two
+ * implementation-agnostic guarantees every contract'd meta-tool makes,
+ * regardless of which runtime serves it.
+ */
+export interface ErrorRules {
+    /**
+     * The error a runtime returns when the tool has no registered
+     * implementation. The runtime returns a `ToolResult` with
+     * `success: false` and an `error` that starts with this string —
+     * never an HTTP error. The literal is "Tool not registered".
+     */
+    unregisteredErrorPrefix: string;
+    /**
+     * A malformed input the kit posts to assert the runtime returns a typed
+     * error envelope (`success: false`, non-empty `error`) rather than
+     * throwing across the wire or returning a success result. The `action`
+     * field is added by the kit when `malformedAction` is set.
+     */
+    malformedInput: Record<string, unknown>;
+    /** The action to drive the malformed input against, when the tool is
+     *  action-based. Omit for tools with no action discriminator. */
+    malformedAction?: string;
+}
+/**
+ * The happy-path contract for a single-shot tool — one with no action
+ * discriminator (e.g. `codespar_discover`). Names a minimal valid input to
+ * drive the tool with and the result wire shape the response must satisfy,
+ * so the kit asserts the result shape rather than only that it succeeded.
+ */
+export interface SingleShotRule {
+    /** A minimal valid input the kit posts to drive the happy path. */
+    sampleInput: Record<string, unknown>;
+    /** The result wire shape the successful response must satisfy. */
+    result: WireShape;
+}
+/**
+ * The full contract descriptor for one meta-tool — the machine-readable
+ * contract the conformance kit consumes. Names the tool, its wire types,
+ * its action state machine (or single-shot rule), and its error rules.
+ *
+ * Exactly one of `stateMachine` (action-discriminated tools) or
+ * `singleShot` (tools with no action) describes the happy path.
+ */
+export interface MetaToolContractDescriptor {
+    /** The wire tool name, e.g. "codespar_shop". */
+    toolName: string;
+    /** The Args interface name in `types.ts`, e.g. "ShopArgs". */
+    argsType: string;
+    /** The Result interface (or union) name in `types.ts`, e.g.
+     *  "ShopResult". */
+    resultType: string;
+    /** The action state machine. Present for action-discriminated tools. */
+    stateMachine?: ActionStateMachine;
+    /** The single-shot happy-path rule. Present for tools with no action
+     *  discriminator (mutually exclusive with `stateMachine`). */
+    singleShot?: SingleShotRule;
+    /** The error rules every runtime serving this tool must honor. */
+    errors: ErrorRules;
+}
+/** The literal a runtime returns for a tool with no registered impl. */
+export declare const TOOL_NOT_REGISTERED_PREFIX: "Tool not registered";
+/**
+ * `codespar_discover` is a single-shot search (no action discriminator):
+ * it takes a `use_case` and returns a `DiscoverResult`. The contract is the
+ * result wire shape (DiscoverResult's real fields) plus the two error
+ * rules. `recommended` is intentionally not required: it is nullable by
+ * contract (`DiscoverToolMatch | null`), so a conforming result MAY return
+ * `recommended: null` — when present it must be an object.
+ */
+export declare const DISCOVER_CONTRACT: MetaToolContractDescriptor;
+/**
+ * `codespar_manage_connections` is action-discriminated over
+ * `list | status | initiate`, but the actions do not form a sequential
+ * flow — each is an independent read/initiate against a server's
+ * connection state, so there is no terminal-status state machine. The
+ * contract names the per-action result shape and the error rules.
+ */
+export declare const MANAGE_CONNECTIONS_CONTRACT: MetaToolContractDescriptor;
+/**
+ * `codespar_shop` is the canonical action state machine: `search` finds
+ * offers, `checkout` starts an async session, and `checkout_status` polls
+ * to a terminal `ready_for_payment` (carries a payable Pix) or `canceled`
+ * (carries an error). The `in_progress` status is non-terminal — the flow
+ * advances by re-polling `checkout_status`.
+ */
+export declare const SHOP_CONTRACT: MetaToolContractDescriptor;
+/** Every in-scope contract descriptor, keyed by wire tool name. */
+export declare const META_TOOL_CONTRACTS: {
+    readonly codespar_discover: MetaToolContractDescriptor;
+    readonly codespar_manage_connections: MetaToolContractDescriptor;
+    readonly codespar_shop: MetaToolContractDescriptor;
+};
+/** The wire tool names that have a published contract descriptor. */
+export type ContractedToolName = keyof typeof META_TOOL_CONTRACTS;
+//# sourceMappingURL=meta-tool-contract.d.ts.map

package/dist/meta-tool-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-tool-contract.d.ts","sourceRoot":"","sources":["../src/meta-tool-contract.ts"],"names":[],"mappings":"AAeA;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,aAAa,GACb,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,CAAC;AAEZ,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE,SAAS,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;+DAC2D;IAC3D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,iDAAiD;IACjD,MAAM,EAAE,SAAS,CAAC;IAClB;kEAC8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,2CAA2C;IAC3C,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,uBAAuB,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;qEACiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,kEAAkE;IAClE,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;wBACoB;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;kEAC8D;IAC9D,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,kEAAkE;IAClE,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,EAAG,qBAA8B,CAAC;AAIzE;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,0BA2B/B,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,0BA2DzC,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,0BA2D3B,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC;AAEX,qEAAqE;AACrE,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,mBAAmB,CAAC"}

package/dist/meta-tool-contract.js

@@ -0,0 +1,196 @@
+/* ── Meta-tool contract descriptor ───────────────────────────────
+ *
+ * A machine-readable description of a single meta-tool's contract: the
+ * names of its wire types, its action state machine, and its error rules.
+ * The conformance kit (`@codespar/types/testing`) consumes a descriptor and
+ * asserts that whatever implementation is registered at a live backend
+ * honors it — so the descriptor is the single source of truth for "what it
+ * means to conform", and both the OSS runtime and a managed backend prove
+ * parity by passing the same descriptor-driven suite.
+ *
+ * Descriptors are data, not code paths: they reference wire shapes by name
+ * (the interfaces authored in `types.ts`) rather than carrying validators,
+ * so they stay portable across language ports and serialize cleanly.
+ * ─────────────────────────────────────────────────────────────── */
+/** The literal a runtime returns for a tool with no registered impl. */
+export const TOOL_NOT_REGISTERED_PREFIX = "Tool not registered";
+/* ── codespar_discover ───────────────────────────────────────── */
+/**
+ * `codespar_discover` is a single-shot search (no action discriminator):
+ * it takes a `use_case` and returns a `DiscoverResult`. The contract is the
+ * result wire shape (DiscoverResult's real fields) plus the two error
+ * rules. `recommended` is intentionally not required: it is nullable by
+ * contract (`DiscoverToolMatch | null`), so a conforming result MAY return
+ * `recommended: null` — when present it must be an object.
+ */
+export const DISCOVER_CONTRACT = {
+    toolName: "codespar_discover",
+    argsType: "DiscoverOptions",
+    resultType: "DiscoverResult",
+    singleShot: {
+        sampleInput: { use_case: "test conformance probe" },
+        result: {
+            name: "DiscoverResult",
+            fields: [
+                { name: "use_case", kind: "string" },
+                {
+                    name: "search_strategy",
+                    kind: "string-enum",
+                    values: ["embedding", "trigram", "empty"],
+                },
+                { name: "recommended", kind: "object", required: false },
+                { name: "related", kind: "array" },
+                { name: "next_steps", kind: "array" },
+            ],
+        },
+    },
+    errors: {
+        unregisteredErrorPrefix: TOOL_NOT_REGISTERED_PREFIX,
+        // A discover call with no use_case is malformed — the tool cannot
+        // search for nothing.
+        malformedInput: {},
+    },
+};
+/* ── codespar_manage_connections ─────────────────────────────── */
+/**
+ * `codespar_manage_connections` is action-discriminated over
+ * `list | status | initiate`, but the actions do not form a sequential
+ * flow — each is an independent read/initiate against a server's
+ * connection state, so there is no terminal-status state machine. The
+ * contract names the per-action result shape and the error rules.
+ */
+export const MANAGE_CONNECTIONS_CONTRACT = {
+    toolName: "codespar_manage_connections",
+    argsType: "ConnectionWizardOptions",
+    resultType: "ConnectionWizardResult",
+    stateMachine: {
+        start: "list",
+        actions: [
+            {
+                action: "list",
+                sampleInput: {},
+                result: {
+                    name: "ConnectionWizardResult",
+                    fields: [
+                        { name: "action", kind: "string-enum", values: ["list"] },
+                        { name: "connections", kind: "array" },
+                    ],
+                },
+            },
+            {
+                action: "status",
+                sampleInput: { server_id: "asaas" },
+                result: {
+                    name: "ConnectionWizardResult",
+                    fields: [
+                        { name: "action", kind: "string-enum", values: ["status"] },
+                        { name: "connections", kind: "array" },
+                        // `status` is `ConnectionStatusRow | null` — an object when a
+                        // row is found, null when the server is unknown. Validated
+                        // only when present.
+                        { name: "status", kind: "object", required: false },
+                    ],
+                },
+            },
+            {
+                action: "initiate",
+                sampleInput: { server_id: "asaas" },
+                result: {
+                    name: "ConnectionWizardResult",
+                    fields: [
+                        { name: "action", kind: "string-enum", values: ["initiate"] },
+                        { name: "connections", kind: "array" },
+                        // `initiate` is `ConnectionWizardInstructions | null` — an
+                        // object when the wizard is issued, null otherwise. Validated
+                        // only when present.
+                        { name: "initiate", kind: "object", required: false },
+                    ],
+                },
+            },
+        ],
+        // No flow terminus — each action is independent.
+        terminalStatuses: [],
+    },
+    errors: {
+        unregisteredErrorPrefix: TOOL_NOT_REGISTERED_PREFIX,
+        // An unknown action is malformed — the closed set is
+        // list | status | initiate.
+        malformedInput: { action: "not_a_real_action" },
+        malformedAction: "not_a_real_action",
+    },
+};
+/* ── codespar_shop ───────────────────────────────────────────── */
+/**
+ * `codespar_shop` is the canonical action state machine: `search` finds
+ * offers, `checkout` starts an async session, and `checkout_status` polls
+ * to a terminal `ready_for_payment` (carries a payable Pix) or `canceled`
+ * (carries an error). The `in_progress` status is non-terminal — the flow
+ * advances by re-polling `checkout_status`.
+ */
+export const SHOP_CONTRACT = {
+    toolName: "codespar_shop",
+    argsType: "ShopArgs",
+    resultType: "ShopResult",
+    stateMachine: {
+        start: "search",
+        actions: [
+            {
+                action: "search",
+                sampleInput: { query: "cat food" },
+                result: {
+                    name: "ShopSearchResult",
+                    fields: [
+                        { name: "rail", kind: "string" },
+                        { name: "products", kind: "array" },
+                    ],
+                },
+            },
+            {
+                action: "checkout",
+                sampleInput: { url: "https://example.test/p/sku_1" },
+                result: {
+                    name: "ShopCheckoutResult",
+                    fields: [
+                        { name: "checkout_session_id", kind: "string" },
+                        {
+                            name: "status",
+                            kind: "string-enum",
+                            values: ["in_progress"],
+                        },
+                    ],
+                },
+                statusField: "status",
+            },
+            {
+                action: "checkout_status",
+                sampleInput: { checkout_session_id: "cks_sample" },
+                result: {
+                    name: "ShopStatusResult",
+                    fields: [
+                        { name: "checkout_session_id", kind: "string" },
+                        {
+                            name: "status",
+                            kind: "string-enum",
+                            values: ["in_progress", "ready_for_payment", "canceled"],
+                        },
+                    ],
+                },
+                statusField: "status",
+            },
+        ],
+        terminalStatuses: ["ready_for_payment", "canceled"],
+    },
+    errors: {
+        unregisteredErrorPrefix: TOOL_NOT_REGISTERED_PREFIX,
+        // A search with no query is malformed — there is nothing to search for.
+        malformedInput: {},
+        malformedAction: "search",
+    },
+};
+/** Every in-scope contract descriptor, keyed by wire tool name. */
+export const META_TOOL_CONTRACTS = {
+    codespar_discover: DISCOVER_CONTRACT,
+    codespar_manage_connections: MANAGE_CONNECTIONS_CONTRACT,
+    codespar_shop: SHOP_CONTRACT,
+};
+//# sourceMappingURL=meta-tool-contract.js.map

package/dist/meta-tool-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-tool-contract.js","sourceRoot":"","sources":["../src/meta-tool-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;qEAaqE;AA8IrE,wEAAwE;AACxE,MAAM,CAAC,MAAM,0BAA0B,GAAG,qBAA8B,CAAC;AAEzE,oEAAoE;AAEpE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA+B;IAC3D,QAAQ,EAAE,mBAAmB;IAC7B,QAAQ,EAAE,iBAAiB;IAC3B,UAAU,EAAE,gBAAgB;IAC5B,UAAU,EAAE;QACV,WAAW,EAAE,EAAE,QAAQ,EAAE,wBAAwB,EAAE;QACnD,MAAM,EAAE;YACN,IAAI,EAAE,gBAAgB;YACtB,MAAM,EAAE;gBACN,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACpC;oBACE,IAAI,EAAE,iBAAiB;oBACvB,IAAI,EAAE,aAAa;oBACnB,MAAM,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC;iBAC1C;gBACD,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE;gBACxD,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE;gBAClC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE;aACtC;SACF;KACF;IACD,MAAM,EAAE;QACN,uBAAuB,EAAE,0BAA0B;QACnD,kEAAkE;QAClE,sBAAsB;QACtB,cAAc,EAAE,EAAE;KACnB;CACF,CAAC;AAEF,oEAAoE;AAEpE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA+B;IACrE,QAAQ,EAAE,6BAA6B;IACvC,QAAQ,EAAE,yBAAyB;IACnC,UAAU,EAAE,wBAAwB;IACpC,YAAY,EAAE;QACZ,KAAK,EAAE,MAAM;QACb,OAAO,EAAE;YACP;gBACE,MAAM,EAAE,MAAM;gBACd,WAAW,EAAE,EAAE;gBACf,MAAM,EAAE;oBACN,IAAI,EAAE,wBAAwB;oBAC9B,MAAM,EAAE;wBACN,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE;wBACzD,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE;qBACvC;iBACF;aACF;YACD;gBACE,MAAM,EAAE,QAAQ;gBAChB,WAAW,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;gBACnC,MAAM,EAAE;oBACN,IAAI,EAAE,wBAAwB;oBAC9B,MAAM,EAAE;wBACN,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE;wBAC3D,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE;wBACtC,8DAA8D;wBAC9D,2DAA2D;wBAC3D,qBAAqB;wBACrB,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE;qBACpD;iBACF;aACF;YACD;gBACE,MAAM,EAAE,UAAU;gBAClB,WAAW,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;gBACnC,MAAM,EAAE;oBACN,IAAI,EAAE,wBAAwB;oBAC9B,MAAM,EAAE;wBACN,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,UAAU,CAAC,EAAE;wBAC7D,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE;wBACtC,2DAA2D;wBAC3D,8DAA8D;wBAC9D,qBAAqB;wBACrB,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE;qBACtD;iBACF;aACF;SACF;QACD,iDAAiD;QACjD,gBAAgB,EAAE,EAAE;KACrB;IACD,MAAM,EAAE;QACN,uBAAuB,EAAE,0BAA0B;QACnD,qDAAqD;QACrD,4BAA4B;QAC5B,cAAc,EAAE,EAAE,MAAM,EAAE,mBAAmB,EAAE;QAC/C,eAAe,EAAE,mBAAmB;KACrC;CACF,CAAC;AAEF,oEAAoE;AAEpE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAA+B;IACvD,QAAQ,EAAE,eAAe;IACzB,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;IACxB,YAAY,EAAE;QACZ,KAAK,EAAE,QAAQ;QACf,OAAO,EAAE;YACP;gBACE,MAAM,EAAE,QAAQ;gBAChB,WAAW,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE;gBAClC,MAAM,EAAE;oBACN,IAAI,EAAE,kBAAkB;oBACxB,MAAM,EAAE;wBACN,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAChC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE;qBACpC;iBACF;aACF;YACD;gBACE,MAAM,EAAE,UAAU;gBAClB,WAAW,EAAE,EAAE,GAAG,EAAE,8BAA8B,EAAE;gBACpD,MAAM,EAAE;oBACN,IAAI,EAAE,oBAAoB;oBAC1B,MAAM,EAAE;wBACN,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC/C;4BACE,IAAI,EAAE,QAAQ;4BACd,IAAI,EAAE,aAAa;4BACnB,MAAM,EAAE,CAAC,aAAa,CAAC;yBACxB;qBACF;iBACF;gBACD,WAAW,EAAE,QAAQ;aACtB;YACD;gBACE,MAAM,EAAE,iBAAiB;gBACzB,WAAW,EAAE,EAAE,mBAAmB,EAAE,YAAY,EAAE;gBAClD,MAAM,EAAE;oBACN,IAAI,EAAE,kBAAkB;oBACxB,MAAM,EAAE;wBACN,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC/C;4BACE,IAAI,EAAE,QAAQ;4BACd,IAAI,EAAE,aAAa;4BACnB,MAAM,EAAE,CAAC,aAAa,EAAE,mBAAmB,EAAE,UAAU,CAAC;yBACzD;qBACF;iBACF;gBACD,WAAW,EAAE,QAAQ;aACtB;SACF;QACD,gBAAgB,EAAE,CAAC,mBAAmB,EAAE,UAAU,CAAC;KACpD;IACD,MAAM,EAAE;QACN,uBAAuB,EAAE,0BAA0B;QACnD,wEAAwE;QACxE,cAAc,EAAE,EAAE;QAClB,eAAe,EAAE,QAAQ;KAC1B;CACF,CAAC;AAEF,mEAAmE;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,iBAAiB,EAAE,iBAAiB;IACpC,2BAA2B,EAAE,2BAA2B;IACxD,aAAa,EAAE,aAAa;CACpB,CAAC"}

package/dist/testing/conformance-kit.d.ts

@@ -0,0 +1,101 @@
+import type { ToolResult } from "../index.js";
+import { type ContractedToolName, type FieldRule, type MetaToolContractDescriptor, type WireShape } from "../meta-tool-contract.js";
+/** Options for {@link runMetaToolConformanceSuite}. */
+export interface ConformanceSuiteOptions {
+    /** Which contract'd meta-tool to assert conformance for. */
+    tool: ContractedToolName;
+    /**
+     * Server ids to post when opening the session. Defaults to `[]`, matching
+     * a self-hosted OSS runtime that accepts an empty server list. A managed
+     * backend requires at least one server, so a managed-side consumer MUST
+     * pass `[<seeded-server-id>]` here — see {@link runMetaToolConformanceSuite}.
+     */
+    servers?: string[];
+}
+/** A single conformance violation: which check failed and why. */
+export interface Violation {
+    /** A stable code for the kind of violation. */
+    code: "wire-shape" | "action-state" | "error-unregistered" | "error-malformed";
+    /** Human-readable detail naming the specific field/rule that failed. */
+    detail: string;
+}
+/** True when `value` matches the JSON-value kind `rule.kind` demands. */
+export declare function fieldMatches(rule: FieldRule, value: unknown): boolean;
+/**
+ * Check a wire object against a {@link WireShape}. Returns the violations
+ * found (empty array = conforms). A field is checked when it is `required`
+ * (the default) or present; absent optional fields are skipped.
+ */
+export declare function checkWireShape(shape: WireShape, obj: unknown): Violation[];
+/**
+ * Verify a successful action result: the `ToolResult` reports success and
+ * its `data` conforms to the action's result wire shape. Also enforces that
+ * a `statusField`, when declared, holds a value the state machine knows —
+ * a terminal status or `in_progress`/non-terminal status drawn from the
+ * declared enum (the enum check is part of the wire shape).
+ */
+export declare function checkActionResult(descriptor: MetaToolContractDescriptor, action: string, result: ToolResult): Violation[];
+/**
+ * Verify a single-shot tool's happy-path result: the `ToolResult` reports
+ * success and its `data` conforms to the descriptor's `singleShot` result
+ * wire shape. This gives a no-state-machine tool (e.g. `codespar_discover`)
+ * the same wire-shape teeth the action path has — a wrong-shaped result
+ * fails with a precise `[wire-shape]` violation rather than passing on
+ * `success: true` alone.
+ */
+export declare function checkSingleShotResult(descriptor: MetaToolContractDescriptor, result: ToolResult): Violation[];
+/**
+ * Verify the unregistered-tool error rule: a runtime with no registered
+ * implementation returns `success: false` with an `error` that starts with
+ * the descriptor's `unregisteredErrorPrefix` (never an HTTP-level error and
+ * never a success result).
+ */
+export declare function checkUnregisteredError(descriptor: MetaToolContractDescriptor, result: ToolResult): Violation[];
+/**
+ * Verify the malformed-input error rule: a malformed input yields a typed
+ * error envelope (`success: false` with a non-empty `error`) rather than a
+ * success result. The error message itself is implementation-defined; only
+ * the shape of the failure is contracted.
+ */
+export declare function checkMalformedError(descriptor: MetaToolContractDescriptor, result: ToolResult): Violation[];
+/**
+ * Register the meta-tool conformance test suite against a live backend.
+ *
+ * Given a base URL and an `apiKey` for a backend that has an implementation
+ * of `opts.tool` registered, drives `execute(toolName, ...)` and asserts the
+ * tool's contract descriptor: every action's result wire shape, the action
+ * state machine (the declared status enum, terminal vs non-terminal), and
+ * the two error rules (unregistered → "Tool not registered"; malformed
+ * input → typed error envelope).
+ *
+ * The suite is implementation-agnostic — it tests whatever is registered at
+ * `baseUrl`. It validates the baseUrl before issuing any request: only
+ * https:// URLs and localhost are accepted, so a misconfigured CI
+ * environment fails early rather than leaking the apiKey to an arbitrary
+ * host.
+ *
+ * The unregistered-error leg uses a deliberately unregistered tool name
+ * (the contract'd tool name with a `__unregistered_probe` suffix) so it
+ * asserts the runtime's fall-through behavior without depending on any
+ * tool being absent.
+ *
+ * Backend prerequisites:
+ * - **Route prefix.** The kit drives `POST /v1/sessions`,
+ *   `POST /v1/sessions/:id/execute`, and `DELETE /v1/sessions/:id` — the
+ *   backend (or test harness) must mount the session routes under the `/v1`
+ *   prefix.
+ * - **`servers` option.** `opts.servers` defaults to `[]`. A self-hosted
+ *   OSS runtime accepts an empty server list on session create, but a
+ *   managed backend requires at least one server — so a managed-side
+ *   consumer MUST pass `opts.servers: [<seeded-server-id>]` (a server whose
+ *   meta-tool implementation is registered), or session create will be
+ *   rejected before any conformance case runs.
+ *
+ * @param baseUrl - API base URL (e.g. "https://your-runtime.example" or "http://localhost:3000")
+ * @param apiKey  - Bearer token for session creation
+ * @param opts    - The tool to assert and optional servers list (see {@link ConformanceSuiteOptions})
+ */
+export declare function runMetaToolConformanceSuite(baseUrl: string, apiKey: string, opts: ConformanceSuiteOptions): void;
+/** Join violations into a single message for an assertion failure. */
+export declare function formatViolations(violations: Violation[]): string;
+//# sourceMappingURL=conformance-kit.d.ts.map

package/dist/testing/conformance-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance-kit.d.ts","sourceRoot":"","sources":["../../src/testing/conformance-kit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,0BAA0B,EAC/B,KAAK,SAAS,EACf,MAAM,0BAA0B,CAAC;AAElC,uDAAuD;AACvD,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,IAAI,EAAE,kBAAkB,CAAC;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAUD,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,IAAI,EACA,YAAY,GACZ,cAAc,GACd,oBAAoB,GACpB,iBAAiB,CAAC;IACtB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAoBrE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,OAAO,GACX,SAAS,EAAE,CA+Bb;AAeD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,0BAA0B,EACtC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,GACjB,SAAS,EAAE,CAqBb;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,0BAA0B,EACtC,MAAM,EAAE,UAAU,GACjB,SAAS,EAAE,CAmBb;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,0BAA0B,EACtC,MAAM,EAAE,UAAU,GACjB,SAAS,EAAE,CAmBb;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,0BAA0B,EACtC,MAAM,EAAE,UAAU,GACjB,SAAS,EAAE,CAkBb;AA+ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CAqEN;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAGhE"}