@try-works/dsh-model-as-tool 0.1.1 → 0.1.3

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

@@ -0,0 +1,163 @@
+/**
+ * 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 { Ajv } from 'ajv';
+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 result that did not satisfy its contract's output schema. */
+export class ContractViolationError extends Error {
+    name = 'ContractViolationError';
+    violations;
+    constructor(contract, violations) {
+        super(`result violates the ${contract} contract: ${violations.join('; ')}`);
+        this.violations = violations;
+    }
+}
+/**
+ * The validator. `strict: false` because contract schemas use JSON Schema
+ * keywords that Ajv's strict mode rejects when they are merely annotated, and
+ * `allErrors` so a violation report lists every problem rather than the first.
+ */
+function createAjv() {
+    return new Ajv({ allErrors: true, strict: false, allowUnionTypes: true });
+}
+const ajv = createAjv();
+const outputValidators = new Map();
+const inputValidators = new Map();
+/** 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, ajv.compile(contract.inputSchema));
+    }
+    catch (error) {
+        throw new ContractError(contract.contract, [`inputSchema does not compile: ${message(error)}`]);
+    }
+    try {
+        outputValidators.set(contract.contract, ajv.compile(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 };
+/** 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,35 @@
+{
+  "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" },
+    "./src/*": "./src/*",
+    "./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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@try-works/dsh-model-as-tool",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Install Desert Ant Labs on-device models as DSH tools and skills, with per-platform capability gating",
   "keywords": [
     "dsh",
@@ -48,7 +48,8 @@
     "catalog/desert-ant-models.json",
     "catalog/playbooks.json",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "bin"
   ],
   "dsh": {
     "bundle": {
@@ -75,11 +76,22 @@
     "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"
+    "prepack": "node scripts/stage-bundle.mjs && npm run build",
+    "prepare": "tsc -p tsconfig.build.json",
+    "postpack": "node scripts/stage-bundle.mjs --clean"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0"
-  }
+  },
+  "dependencies": {
+    "@try-works/tool-mode-contracts": "^0.1.0",
+    "ajv": "^8.20.0"
+  },
+  "bin": {
+    "dsh-tool-mode-mcp-stdio": "./bin/dsh-tool-mode-mcp-stdio.mjs"
+  },
+  "bundledDependencies": [
+    "@try-works/tool-mode-contracts"
+  ]
 }