@try-works/dsh-model-as-tool 0.1.2 → 0.3.6

package/node_modules/@try-works/tool-mode-contracts/lib/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@try-works/tool-mode-contracts` — model-free standard tool contracts.
+ *
+ * This package contains no model bindings, no weights and no host code. It is the
+ * shared vocabulary that the Tool Mode host registers, that MCP clients read, and
+ * that extension packages implement against (DECL-01).
+ *
+ * @module @try-works/tool-mode-contracts
+ */
+export { assertValidContract, assertValidInput, assertValidOutput, assertAgainstSchema, compileSchema, ContractError, ContractViolationError, TOOL_META_SCHEMA, type ToolContract, } from './registry.ts';
+export { withMeta, type ExecutionLocation, type ToolMeta } from './meta.ts';
+export { crossFieldRules, ProjectionError, projectSchemaToDsh, projectToDsh, toDshParameters, type CrossFieldRule, type DshParameters, type DshProjection, } from './dsh.ts';
+export { sttTranscribe, STT_ADMITTED_FORMATS } from './contracts/stt-transcribe.ts';
+export { langDetect } from './contracts/lang-detect.ts';
+export { textEmbed } from './contracts/text-embed.ts';
+export { textRerank } from './contracts/text-rerank.ts';
+export { textTitle, imageDescribe, multimodalEmbed, semanticSimilarity, semanticRank, semanticClassify, semanticDeduplicate, mediaFindMoments, decisionChoose, decisionTest, decisionScore, structuredExtract, toolsPlan, } from './contracts/standard.ts';
+import type { ToolContract } from './registry.ts';
+/**
+ * The standard contracts every Tool Mode host knows how to register.
+ *
+ * A host iterates this list; it does not switch on model names, which is what
+ * ARCH-02 and EXT-01 require of model-independent code.
+ */
+export declare const STANDARD_CONTRACTS: readonly ToolContract[];
+//# sourceMappingURL=index.d.ts.map

package/node_modules/@try-works/tool-mode-contracts/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,QAAQ,EAAE,KAAK,iBAAiB,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAA;AAE3E,OAAO,EACL,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,UAAU,CAAA;AAEjB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AACvD,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,SAAS,GACV,MAAM,yBAAyB,CAAA;AAqBhC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,YAAY,EAkBrD,CAAA"}

package/node_modules/@try-works/tool-mode-contracts/lib/index.js

@@ -0,0 +1,48 @@
+/**
+ * `@try-works/tool-mode-contracts` — model-free standard tool contracts.
+ *
+ * This package contains no model bindings, no weights and no host code. It is the
+ * shared vocabulary that the Tool Mode host registers, that MCP clients read, and
+ * that extension packages implement against (DECL-01).
+ *
+ * @module @try-works/tool-mode-contracts
+ */
+export { assertValidContract, assertValidInput, assertValidOutput, assertAgainstSchema, compileSchema, ContractError, ContractViolationError, TOOL_META_SCHEMA, } from "./registry.js";
+export { withMeta } from "./meta.js";
+export { crossFieldRules, ProjectionError, projectSchemaToDsh, projectToDsh, toDshParameters, } from "./dsh.js";
+export { sttTranscribe, STT_ADMITTED_FORMATS } from "./contracts/stt-transcribe.js";
+export { langDetect } from "./contracts/lang-detect.js";
+export { textEmbed } from "./contracts/text-embed.js";
+export { textRerank } from "./contracts/text-rerank.js";
+export { textTitle, imageDescribe, multimodalEmbed, semanticSimilarity, semanticRank, semanticClassify, semanticDeduplicate, mediaFindMoments, decisionChoose, decisionTest, decisionScore, structuredExtract, toolsPlan, } from "./contracts/standard.js";
+import { sttTranscribe } from "./contracts/stt-transcribe.js";
+import { langDetect } from "./contracts/lang-detect.js";
+import { textEmbed } from "./contracts/text-embed.js";
+import { textRerank } from "./contracts/text-rerank.js";
+import { textTitle, imageDescribe, multimodalEmbed, semanticSimilarity, semanticRank, semanticClassify, semanticDeduplicate, mediaFindMoments, decisionChoose, decisionTest, decisionScore, structuredExtract, toolsPlan, } from "./contracts/standard.js";
+/**
+ * The standard contracts every Tool Mode host knows how to register.
+ *
+ * A host iterates this list; it does not switch on model names, which is what
+ * ARCH-02 and EXT-01 require of model-independent code.
+ */
+export const STANDARD_CONTRACTS = [
+    sttTranscribe,
+    langDetect,
+    textEmbed,
+    textRerank,
+    textTitle,
+    imageDescribe,
+    multimodalEmbed,
+    semanticSimilarity,
+    semanticRank,
+    semanticClassify,
+    semanticDeduplicate,
+    mediaFindMoments,
+    decisionChoose,
+    decisionTest,
+    decisionScore,
+    structuredExtract,
+    toolsPlan,
+];
+//# sourceMappingURL=index.js.map

package/node_modules/@try-works/tool-mode-contracts/lib/meta.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The shared result envelope every Tool Mode tool returns (DECL-03).
+ *
+ * The envelope is what makes a result self-describing: a caller can tell which
+ * contract and version produced it, which implementation actually ran, where it
+ * ran, and whether the host attached any warnings. The host stamps the
+ * authoritative provenance fields; an implementation cannot forge another
+ * package's identity.
+ *
+ * DECL-04 is the reason `warnings` exists but a universal `confidence` does not:
+ * a successful call means a valid result was produced, not that it is correct,
+ * and a fabricated confidence number would claim more than the model supplied.
+ *
+ * @module @try-works/tool-mode-contracts/meta
+ */
+/** Where an implementation executed, relative to the caller (SPEC §6). */
+export type ExecutionLocation = 
+/** The harness host process itself. */
+'host'
+/** The user's own device. */
+ | 'device'
+/** A user-controlled server on the local network. */
+ | 'team-server'
+/** A remote service outside the user's control. */
+ | 'remote';
+/** Provenance and status metadata shared by every tool result. */
+export interface ToolMeta {
+    /** Contract identity, e.g. `stt.transcribe`. */
+    readonly contract: string;
+    /** Semantic version of the CONTRACT, independent of the host release. */
+    readonly contractVersion: string;
+    /** The implementation that actually executed, e.g. `voz-onnx`. */
+    readonly implementationId: string;
+    /** Owning extension package identity. */
+    readonly extension: string;
+    /** Extension version, stamped by the host. */
+    readonly extensionVersion: string;
+    /** Which activation generation produced this result (DECL-08). */
+    readonly activationGeneration: number;
+    /** Where the work happened. */
+    readonly executionLocation: ExecutionLocation;
+    /** Host-issued receipt identity, for correlation and audit. */
+    readonly receiptId: string;
+    /** Non-fatal conditions the caller should know about. */
+    readonly warnings: readonly string[];
+}
+/** The JSON Schema for {@link ToolMeta}, used to validate every result. */
+export declare const TOOL_META_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["contract", "contractVersion", "implementationId", "extension", "extensionVersion", "activationGeneration", "executionLocation", "receiptId", "warnings"];
+    readonly properties: {
+        readonly contract: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly contractVersion: {
+            readonly type: "string";
+            readonly pattern: "^\\d+\\.\\d+\\.\\d+$";
+        };
+        readonly implementationId: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly extension: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly extensionVersion: {
+            readonly type: "string";
+            readonly pattern: "^\\d+\\.\\d+\\.\\d+";
+        };
+        readonly activationGeneration: {
+            readonly type: "integer";
+            readonly minimum: 0;
+        };
+        readonly executionLocation: {
+            readonly type: "string";
+            readonly enum: readonly ["host", "device", "team-server", "remote"];
+        };
+        readonly receiptId: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly warnings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+    };
+};
+/**
+ * Attach a `meta` property to a result schema.
+ *
+ * Contracts declare their own payload; the envelope is identical everywhere, so
+ * it is composed here rather than retyped in each contract — retyping it is how
+ * the shapes drift apart.
+ * @param payload - the contract's payload schema properties.
+ * @param requiredPayload - payload property names that are required.
+ * @returns a closed object schema containing the payload plus `meta`.
+ */
+export declare function withMeta(payload: Record<string, unknown>, requiredPayload?: readonly string[]): Record<string, unknown>;
+//# sourceMappingURL=meta.d.ts.map

package/node_modules/@try-works/tool-mode-contracts/lib/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../src/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB;AAC3B,uCAAuC;AACrC,MAAM;AACR,6BAA6B;GAC3B,QAAQ;AACV,qDAAqD;GACnD,aAAa;AACf,mDAAmD;GACjD,QAAQ,CAAA;AAEZ,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,kEAAkE;IAClE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IACrC,+BAA+B;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAA;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBnB,CAAA;AAEV;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,eAAe,GAAE,SAAS,MAAM,EAAO,GACtC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}

package/node_modules/@try-works/tool-mode-contracts/lib/meta.js

@@ -0,0 +1,55 @@
+/**
+ * The shared result envelope every Tool Mode tool returns (DECL-03).
+ *
+ * The envelope is what makes a result self-describing: a caller can tell which
+ * contract and version produced it, which implementation actually ran, where it
+ * ran, and whether the host attached any warnings. The host stamps the
+ * authoritative provenance fields; an implementation cannot forge another
+ * package's identity.
+ *
+ * DECL-04 is the reason `warnings` exists but a universal `confidence` does not:
+ * a successful call means a valid result was produced, not that it is correct,
+ * and a fabricated confidence number would claim more than the model supplied.
+ *
+ * @module @try-works/tool-mode-contracts/meta
+ */
+/** The JSON Schema for {@link ToolMeta}, used to validate every result. */
+export const TOOL_META_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'contract', 'contractVersion', 'implementationId', 'extension',
+        'extensionVersion', 'activationGeneration', 'executionLocation',
+        'receiptId', 'warnings',
+    ],
+    properties: {
+        contract: { type: 'string', minLength: 1 },
+        contractVersion: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+        implementationId: { type: 'string', minLength: 1 },
+        extension: { type: 'string', minLength: 1 },
+        extensionVersion: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+' },
+        activationGeneration: { type: 'integer', minimum: 0 },
+        executionLocation: { type: 'string', enum: ['host', 'device', 'team-server', 'remote'] },
+        receiptId: { type: 'string', minLength: 1 },
+        warnings: { type: 'array', items: { type: 'string' } },
+    },
+};
+/**
+ * Attach a `meta` property to a result schema.
+ *
+ * Contracts declare their own payload; the envelope is identical everywhere, so
+ * it is composed here rather than retyped in each contract — retyping it is how
+ * the shapes drift apart.
+ * @param payload - the contract's payload schema properties.
+ * @param requiredPayload - payload property names that are required.
+ * @returns a closed object schema containing the payload plus `meta`.
+ */
+export function withMeta(payload, requiredPayload = []) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: [...requiredPayload, 'meta'],
+        properties: { ...payload, meta: TOOL_META_SCHEMA },
+    };
+}
+//# sourceMappingURL=meta.js.map

package/node_modules/@try-works/tool-mode-contracts/lib/registry.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Contract definitions and their runtime validation.
+ *
+ * A contract is the tool's public identity: stable name, version, input and
+ * output schema, semantics, limits and policy metadata (DECL-01). It is
+ * deliberately model-free — implementations bind to it, it does not know about
+ * them — which is what lets two models serve one `stt_transcribe` instead of
+ * producing a duplicate tool each (BASE-02).
+ *
+ * Milestone A is explicit that "a copied schema with no runtime validation is not
+ * completion", so this module validates both directions: the contract DEFINITION
+ * is checked when registered, and every RESULT is checked against the declared
+ * output schema before it reaches a caller.
+ *
+ * @module @try-works/tool-mode-contracts/registry
+ */
+import { TOOL_META_SCHEMA } from './meta.ts';
+/** One tool contract: the authored-once public identity (DECL-01). */
+export interface ToolContract {
+    /** Contract identity, e.g. `stt.transcribe`. Never a model name. */
+    readonly contract: string;
+    /** Semantic version, independent of any host release number. */
+    readonly version: string;
+    /** The tool name callers see, e.g. `stt_transcribe`. */
+    readonly toolName: string;
+    /** Concise description, used verbatim for DSH registration. */
+    readonly description: string;
+    /** Input schema as JSON Schema. The object root is closed. */
+    readonly inputSchema: Record<string, unknown>;
+    /** Output schema as JSON Schema, including the `meta` envelope. */
+    readonly outputSchema: Record<string, unknown>;
+    /** Declared semantics a caller must be able to rely on. */
+    readonly semantics: Readonly<Record<string, string | number | boolean>>;
+    /** Admitted resource limits, in the units the schema declares. */
+    readonly limits: Readonly<Record<string, number>>;
+    /** Unsupported cases the caller should be told about. */
+    readonly unsupported: readonly string[];
+}
+/** A contract that failed validation, with every reason. */
+export declare class ContractError extends Error {
+    readonly name = "ContractError";
+    /** The individual violations, in declaration order. */
+    readonly violations: readonly string[];
+    constructor(subject: string, violations: readonly string[]);
+}
+/** A value that did not satisfy a declared schema. */
+export declare class ContractViolationError extends Error {
+    readonly name = "ContractViolationError";
+    readonly violations: readonly string[];
+    constructor(subject: string, violations: readonly string[]);
+}
+/**
+ * Validate a contract definition.
+ *
+ * This is deliberately strict about the identity fields: a contract whose
+ * `toolName` is not a legal tool name, or whose version is not semver, would
+ * register a tool that callers cannot address consistently.
+ * @param contract - the definition to check.
+ * @throws ContractError listing every violation.
+ */
+export declare function assertValidContract(contract: ToolContract): void;
+/**
+ * Validate caller arguments against the contract's input schema.
+ * @param contract - the contract to check against.
+ * @param args - the candidate arguments.
+ * @throws ContractViolationError listing every violation.
+ */
+export declare function assertValidInput(contract: ToolContract, args: unknown): void;
+/**
+ * Validate a result against the contract's output schema.
+ *
+ * This runs before the value reaches a caller, so a violation surfaces as a
+ * tool failure rather than as malformed data downstream (AT-11).
+ * @param contract - the contract to check against.
+ * @param value - the candidate result.
+ * @throws ContractViolationError listing every violation.
+ */
+export declare function assertValidOutput(contract: ToolContract, value: unknown): void;
+/** The meta envelope's own schema, exported for contract authors. */
+export { TOOL_META_SCHEMA };
+/**
+ * Compile an arbitrary JSON Schema once, for a host that serves manifest-declared
+ * tool schemas rather than registered contracts.
+ *
+ * Compiling at REGISTRATION (in the host's try/catch) means a malformed schema
+ * fails when the tool is registered, not on the first caller's event-loop tick —
+ * and it is never re-compiled per call, which a per-call text-keyed cache could
+ * not guarantee.
+ * @param schema - the JSON Schema to compile.
+ * @throws ContractError when the schema does not compile.
+ * @returns a validator whose violations are rendered by {@link assertAgainstSchema}.
+ */
+export declare function compileSchema(schema: Readonly<Record<string, unknown>>): (value: unknown) => readonly string[];
+/**
+ * Validate an arbitrary value against a compiled declared schema.
+ *
+ * The full-schema counterpart of {@link assertValidInput}/{@link assertValidOutput}:
+ * the projected advertisement the DSH registry validates is deliberately LOOSER
+ * (union members become `json`, unsupported keywords are dropped), so without this
+ * the dropped keywords are enforced nowhere for manifest-declared tools.
+ * @param subject - the tool or schema name used in the violation message.
+ * @param validate - the compiled validator, from {@link compileSchema}.
+ * @param value - the candidate value.
+ * @throws ContractViolationError listing every violation.
+ */
+export declare function assertAgainstSchema(subject: string, validate: (value: unknown) => readonly string[], value: unknown): void;
+//# sourceMappingURL=registry.d.ts.map

package/node_modules/@try-works/tool-mode-contracts/lib/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAE5C,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7C,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9C,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAA;IACvE,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC;AAED,4DAA4D;AAC5D,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAkB,IAAI,mBAAkB;IACxC,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;gBAC1B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE;CAI3D;AAED,sDAAsD;AACtD,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAkB,IAAI,4BAA2B;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;gBAC1B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE;CAI3D;AA0ED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAmDhE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAM5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAM9E;AAED,qEAAqE;AACrE,OAAO,EAAE,gBAAgB,EAAE,CAAA;AAE3B;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,MAAM,EAAE,CAQ9G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,MAAM,EAAE,EAC/C,KAAK,EAAE,OAAO,GACb,IAAI,CAGN"}

package/node_modules/@try-works/tool-mode-contracts/lib/registry.js

@@ -0,0 +1,246 @@
+/**
+ * Contract definitions and their runtime validation.
+ *
+ * A contract is the tool's public identity: stable name, version, input and
+ * output schema, semantics, limits and policy metadata (DECL-01). It is
+ * deliberately model-free — implementations bind to it, it does not know about
+ * them — which is what lets two models serve one `stt_transcribe` instead of
+ * producing a duplicate tool each (BASE-02).
+ *
+ * Milestone A is explicit that "a copied schema with no runtime validation is not
+ * completion", so this module validates both directions: the contract DEFINITION
+ * is checked when registered, and every RESULT is checked against the declared
+ * output schema before it reaches a caller.
+ *
+ * @module @try-works/tool-mode-contracts/registry
+ */
+// The explicit `.js` suffix is REQUIRED for packed installs: plain Node ESM does
+// not apply extension resolution to package subpaths, and the workspace's tsx
+// loader masks that (the round-67 packed-orchestration run caught exactly this
+// failure). extension-needle's validation.ts uses the same spelling.
+import Ajv2020 from 'ajv/dist/2020.js';
+import { TOOL_META_SCHEMA } from "./meta.js";
+/** A contract that failed validation, with every reason. */
+export class ContractError extends Error {
+    name = 'ContractError';
+    /** The individual violations, in declaration order. */
+    violations;
+    constructor(subject, violations) {
+        super(`${subject} is not a valid contract: ${violations.join('; ')}`);
+        this.violations = violations;
+    }
+}
+/** A value that did not satisfy a declared schema. */
+export class ContractViolationError extends Error {
+    name = 'ContractViolationError';
+    violations;
+    constructor(subject, violations) {
+        super(`value violates the ${subject} schema: ${violations.join('; ')}`);
+        this.violations = violations;
+    }
+}
+/**
+ * The validator, on the 2020-12 dialect.
+ *
+ * 2020-12 rather than draft-07 because extension-declared schemas ship as
+ * 2020-12 documents (`$schema`, `$id`, `$defs` — the extension-needle package's
+ * tools-plan/structured-extract schemas are the concrete case): a draft-07
+ * compiler cannot resolve `#/$defs/...` references, so those real packages
+ * could not be activated in the host. `strict: false` for the same reason as
+ * before — contract schemas annotate keywords Ajv's strict mode rejects when
+ * they are merely descriptive, and a strict-mode THROW on an annotation would
+ * refuse a schema that validates fine. A schema that does not COMPILE (an
+ * unresolvable `$ref`, a structurally broken keyword) still throws at
+ * registration, so a bad schema refuses loudly rather than being accepted.
+ * `allowUnionTypes` admits `type: ["number", "null"]`-style unions, which the
+ * shipped needle schemas use for nullable fields. `allErrors` keeps the
+ * violation report listing every problem rather than the first.
+ */
+function createAjv() {
+    return new Ajv2020({ allErrors: true, strict: false, allowUnionTypes: true });
+}
+const ajv = createAjv();
+const outputValidators = new Map();
+const inputValidators = new Map();
+/**
+ * Validators for $id-bearing schemas, keyed by the id itself.
+ *
+ * Ajv registers a compiled schema under its `$id`, and compiling the same id a
+ * second time THROWS "already exists" — which would make re-activating an
+ * extension (or two tools sharing one declared schema file) fail on the second
+ * compile. Identical content re-compiles to the same validator; DIFFERENT
+ * content under one id is a refusal, because two schemas sharing an id is
+ * exactly the drift a caller must never silently inherit.
+ */
+const compiledById = new Map();
+/** Compile a schema, tolerating a repeat compile of identical $id content. */
+function compileTracked(schema) {
+    const id = typeof schema.$id === 'string' ? schema.$id : undefined;
+    if (id === undefined)
+        return ajv.compile(schema);
+    const serialized = JSON.stringify(schema);
+    const cached = compiledById.get(id);
+    if (cached !== undefined) {
+        if (cached.serialized !== serialized) {
+            throw new ContractError('declared-schema', [`a schema with $id ${JSON.stringify(id)} was already compiled from different content; two different schemas must not share an id`]);
+        }
+        return cached.validate;
+    }
+    const validate = ajv.compile(schema);
+    compiledById.set(id, { serialized, validate });
+    return validate;
+}
+/** Render Ajv errors as stable, deduplicated strings. */
+function renderErrors(errors) {
+    const seen = new Set();
+    const out = [];
+    for (const error of errors ?? []) {
+        const path = error.instancePath === '' ? '(root)' : error.instancePath;
+        const line = `${path} ${error.message ?? 'is invalid'}`;
+        if (!seen.has(line)) {
+            seen.add(line);
+            out.push(line);
+        }
+    }
+    return out;
+}
+/**
+ * Validate a contract definition.
+ *
+ * This is deliberately strict about the identity fields: a contract whose
+ * `toolName` is not a legal tool name, or whose version is not semver, would
+ * register a tool that callers cannot address consistently.
+ * @param contract - the definition to check.
+ * @throws ContractError listing every violation.
+ */
+export function assertValidContract(contract) {
+    const violations = [];
+    if (!/^[a-z][a-z0-9_]*$/.test(contract.toolName)) {
+        violations.push(`toolName ${JSON.stringify(contract.toolName)} must be lower snake_case`);
+    }
+    if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(contract.contract)) {
+        violations.push(`contract ${JSON.stringify(contract.contract)} must be a dotted lower-case identity `
+            + '(for example "stt.transcribe" or "text.language_detect")');
+    }
+    if (!/^\d+\.\d+\.\d+$/.test(contract.version)) {
+        violations.push(`version ${JSON.stringify(contract.version)} must be semantic (x.y.z)`);
+    }
+    if (contract.description.trim().length < 10) {
+        violations.push('description must be a real sentence, not a placeholder');
+    }
+    const input = contract.inputSchema;
+    if (input.type !== 'object') {
+        violations.push('inputSchema root must be an object (clients require an object argument)');
+    }
+    const output = contract.outputSchema;
+    if (output.type !== 'object') {
+        violations.push('outputSchema root must be an object for broad client compatibility (DECL-02)');
+    }
+    else if (output.properties?.meta === undefined) {
+        violations.push('outputSchema must include the shared `meta` envelope (DECL-03)');
+    }
+    // DECL-02: an unconstrained open object is not an adequate leaf-tool contract.
+    if (output.additionalProperties !== false) {
+        violations.push('outputSchema must be closed (additionalProperties: false), not a generic open object (DECL-02)');
+    }
+    if (contract.unsupported.length === 0) {
+        violations.push('unsupported must name at least one case; an empty list claims universal support');
+    }
+    if (violations.length > 0)
+        throw new ContractError(contract.contract, violations);
+    // Schemas must be compilable, or the contract is unenforceable.
+    try {
+        inputValidators.set(contract.contract, compileTracked(contract.inputSchema));
+    }
+    catch (error) {
+        throw new ContractError(contract.contract, [`inputSchema does not compile: ${message(error)}`]);
+    }
+    try {
+        outputValidators.set(contract.contract, compileTracked(contract.outputSchema));
+    }
+    catch (error) {
+        throw new ContractError(contract.contract, [`outputSchema does not compile: ${message(error)}`]);
+    }
+}
+/**
+ * Validate caller arguments against the contract's input schema.
+ * @param contract - the contract to check against.
+ * @param args - the candidate arguments.
+ * @throws ContractViolationError listing every violation.
+ */
+export function assertValidInput(contract, args) {
+    const validate = inputValidators.get(contract.contract);
+    if (validate === undefined) {
+        throw new ContractError(contract.contract, ['input was validated before the contract was registered']);
+    }
+    if (!validate(args))
+        throw new ContractViolationError(contract.contract, renderErrors(validate.errors));
+}
+/**
+ * Validate a result against the contract's output schema.
+ *
+ * This runs before the value reaches a caller, so a violation surfaces as a
+ * tool failure rather than as malformed data downstream (AT-11).
+ * @param contract - the contract to check against.
+ * @param value - the candidate result.
+ * @throws ContractViolationError listing every violation.
+ */
+export function assertValidOutput(contract, value) {
+    const validate = outputValidators.get(contract.contract);
+    if (validate === undefined) {
+        throw new ContractError(contract.contract, ['result was validated before the contract was registered']);
+    }
+    if (!validate(value))
+        throw new ContractViolationError(contract.contract, renderErrors(validate.errors));
+}
+/** The meta envelope's own schema, exported for contract authors. */
+export { TOOL_META_SCHEMA };
+/**
+ * Compile an arbitrary JSON Schema once, for a host that serves manifest-declared
+ * tool schemas rather than registered contracts.
+ *
+ * Compiling at REGISTRATION (in the host's try/catch) means a malformed schema
+ * fails when the tool is registered, not on the first caller's event-loop tick —
+ * and it is never re-compiled per call, which a per-call text-keyed cache could
+ * not guarantee.
+ * @param schema - the JSON Schema to compile.
+ * @throws ContractError when the schema does not compile.
+ * @returns a validator whose violations are rendered by {@link assertAgainstSchema}.
+ */
+export function compileSchema(schema) {
+    let validate;
+    try {
+        validate = compileTracked(schema);
+    }
+    catch (error) {
+        throw new ContractError('declared-schema', [`schema does not compile: ${message(error)}`]);
+    }
+    return value => (validate(value) ? [] : renderErrors(validate.errors));
+}
+/**
+ * Validate an arbitrary value against a compiled declared schema.
+ *
+ * The full-schema counterpart of {@link assertValidInput}/{@link assertValidOutput}:
+ * the projected advertisement the DSH registry validates is deliberately LOOSER
+ * (union members become `json`, unsupported keywords are dropped), so without this
+ * the dropped keywords are enforced nowhere for manifest-declared tools.
+ * @param subject - the tool or schema name used in the violation message.
+ * @param validate - the compiled validator, from {@link compileSchema}.
+ * @param value - the candidate value.
+ * @throws ContractViolationError listing every violation.
+ */
+export function assertAgainstSchema(subject, validate, value) {
+    const violations = validate(value);
+    if (violations.length > 0)
+        throw new ContractViolationError(subject, violations);
+}
+/** Best-effort message from an arbitrary thrown value. */
+function message(error) {
+    try {
+        return error instanceof Error ? error.message : String(error);
+    }
+    catch {
+        return '<unrenderable>';
+    }
+}
+//# sourceMappingURL=registry.js.map

package/node_modules/@try-works/tool-mode-contracts/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@try-works/tool-mode-contracts",
+  "version": "0.1.0",
+  "description": "Model-free standard tool contracts for Tool Mode: identities, schemas, semantics and runtime validation",
+  "license": "MIT",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/try-works/dsh-model-as-tool.git",
+    "directory": "packages/tool-mode-contracts"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": { "types": "./lib/index.d.ts", "default": "./lib/index.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["lib/**/*.js", "lib/**/*.d.ts", "lib/**/*.d.ts.map", "README.md"],
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx --test tests/*.test.ts",
+    "prepack": "tsc -p tsconfig.build.json",
+    "prepare": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/node_modules/@try-works/tool-mode-extension-sdk/bin/dsh-tool-mode.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * The `dsh-tool-mode` executable (EXT-31).
+ *
+ * A thin shim: it wires real process streams into the tested CLI and translates
+ * the returned code into an exit status. All the logic lives in the library, so
+ * every path — including the refusals — is exercised by tests rather than only by
+ * running the binary by hand.
+ */
+
+import { runToolModeCli } from '../lib/cli.js'
+
+const code = await runToolModeCli(
+  process.argv.slice(2),
+  {
+    out: line => process.stdout.write(`${line}\n`),
+    err: line => process.stderr.write(`${line}\n`),
+  },
+)
+process.exitCode = code