@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/README.md

@@ -1,3 +1,300 @@
-# Temporary Holding Version
+# dsh-tool-mode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install on-device models as DSH tools and skills, with per-platform capability
+gating. Ships with the [Desert Ant Labs](https://desertant.com/models/) catalog.
+
+A DSH agent gets a real tool for every model that can run in its process, a
+skill that teaches it *when* to reach for that tool, and an honest explanation
+for every model that cannot run — instead of a tool that fails at call time.
+
+## What it does
+
+The plugin composes six layers:
+
+1. **Catalog** (`catalog/desert-ant-models.json`) — all 18 Desert Ant models,
+   their inputs, outputs, language counts and the npm package that runs them.
+2. **Capability resolver** (`src/capability.ts`) — decides, per model, whether it
+   can actually run *in this process*, and why not when it cannot.
+3. **Adapters** (`src/adapters/`) — lazily import a model package and invoke it.
+4. **Transports** (`src/transport.ts`) — reach a model this machine cannot run:
+   through the Desert Ant CLI, or through a bridge on a machine that can.
+5. **Registrar** (`src/registrar.ts`) — turns each reachable model into a
+   `defineTool` definition registered on `ctx.tools`.
+6. **Skills** (`src/skills.ts` + `catalog/playbooks.json`) — publishes one skill
+   per registered tool describing when to use it, when not to, and how.
+
+Nothing is imported from a model package at plugin load, so a deployment that
+installs none of them still starts cleanly and reports exactly what is missing.
+
+## Tools it registers
+
+| Tool | Model | Runs on Windows x64 | Notes |
+| --- | --- | --- | --- |
+| `lang_detect` | Tongue | **yes** | Pure JavaScript, 2 MB model inside the package, no network |
+| `transcribe_audio` | Voz | **yes** | Needs `onnxruntime-node`; ~349 MB weights download on first use |
+| `model_tools` | — | yes | Lists every catalogued model, and installs/removes tools |
+
+The other 16 catalog models are reported by `model_tools` with the exact reason
+they cannot run, for example:
+
+```
+- [unavailable] redact (`redact_pii`): On-device redaction that strips personal
+  data as you type, in 27 languages, with restore support.
+  why not: Redact has no prebuilt native build for win32-x64; @desert-ant-labs/redact/native
+  ships one for linux-x64, linux-arm64 and darwin-arm64 only.
+```
+
+## Reaching the other 16 models
+
+A model only needs a route, not a rewrite. Two routes cover the rest.
+
+### The CLI (macOS and Linux)
+
+Every shipping model is `desertant <verb> … --json`, so wherever the CLI is
+installed the plugin will drive it. Nothing to configure — it is detected on
+PATH:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Desert-Ant-Labs/desert-ant-cli/main/install.sh | sh
+```
+
+That immediately makes Redact, Emo, Gist, Clear, Ear, Moderator, Shapes, Align,
+Tongue and Voz callable on that machine.
+
+### The bridge (an Apple machine, for Apple-only models)
+
+Title and Uhm run only on Apple silicon. Run the reference bridge there and point
+the plugin at it:
+
+```sh
+# on the Mac
+node scripts/desert-ant-bridge.mjs --token "$(openssl rand -hex 16)"
+```
+
+```yaml
+- id: model-tools
+  config:
+    remote:
+      endpoint: http://mac-studio.local:8787
+      token: <the token>
+```
+
+`suggest_title` then registers here with `route: remote`, and the existing
+catalog entry, parameter schema and skill apply unchanged. The bridge is a thin
+wrapper over the CLI; it binds to loopback and requires a token. **The plugin
+does not host anything** — the licence forbids re-hosting the models as a
+service, so the bridge must be your own machine.
+
+## Installing tools at run time
+
+`model_tools` actions: `list`, `installed`, `describe <id>`, `enable <id>`,
+`disable <id>`, `reset [<id>]`.
+
+**Enable and disable are remembered across restarts.** A plugin `config` states
+the *deployment* default; `enable`/`disable` record the *user's* choice on top of
+it:
+
+- `disable` always wins, so a user can turn off something the config ships.
+- `enable` adds to the config selection, so a user can turn something on without
+  editing YAML.
+- `reset` forgets the choice and makes the configuration authoritative again.
+
+Choices are stored as JSON at `<DSH_HOME>/model-as-tool/state.json`, written
+through a temporary file and a rename so a crash cannot leave a truncated
+document that reads as "everything is gone".
+
+```json
+{ "enabled": ["voz"], "disabled": ["tongue"] }
+```
+
+The plugin writes its own state file rather than rewriting your
+`cordis.patch.yml`: a rewrite there would fight the profile's reload and could
+clobber comments you wrote. Point it elsewhere with `stateFile`, or set
+`persist: false` for the earlier session-scoped behaviour.
+
+Enabling a model that cannot run here fails with the resolver's reason and
+nothing is written — persisting a failed enable would install it silently on the
+next start.
+
+## Install
+
+The package is a DSH bundle: `package.json` declares
+`dsh.bundle.patch: ./cordis.patch.yml`, and that patch is the single `insert`
+row a profile mounts. Install it with `plugin_manager`'s `install_bundle`
+action, or copy the row from [`cordis.patch.yml`](cordis.patch.yml) into the
+profile's own patch file.
+
+The package builds itself on install: `prepare` runs `tsc` from `src/` into
+`lib/`, which is the entry point `main` and `exports` advertise. A registry
+tarball ships `lib/` prebuilt by `prepack`, so a consumer needs no toolchain.
+
+Model packages are **optional dependencies**: install only the ones you want.
+
+```sh
+npm i @desert-ant-labs/tongue                 # language detection, works everywhere
+npm i @desert-ant-labs/voz onnxruntime-node   # transcription on Windows/Linux/macOS
+```
+
+The plugin never bundles or re-hosts model weights.
+
+## What gets downloaded, and when
+
+Three separate things arrive at three separate times. Measured sizes are from a
+Windows x64 install of this package.
+
+**1. The plugin itself — ~58 kB, from npm, at install.** `lib/`, the two catalog
+JSON files, `cordis.patch.yml` and this README. It contains **no model weights
+and no inference runtime**.
+
+**2. The model SDK packages — from npm, at install, only if you asked for them.**
+They are `optionalDependencies`, so a failed or skipped download does not fail the
+install; the capability resolver simply reports the model as unavailable.
+
+| Package | Size on disk | Contains |
+| --- | --- | --- |
+| `@desert-ant-labs/tongue` | 2.1 MB | **The model itself** — `tongue_int8.bin` (2.0 MB) ships inside the tarball |
+| `@desert-ant-labs/voz` | 44.2 MB | The WebAssembly runtime (`VozWeb.wasm`), not the weights |
+| `onnxruntime-node` | 287.1 MB | The prebuilt inference engine for this platform |
+
+**3. The weights — from Hugging Face, on first call, not at install.** Each SDK
+pins one revision and verifies the download, then caches it. Voz fetches about
+**367 MB** on its first transcription:
+
+```
+~/.cache/desert-ant-models/desert-ant-labs/voz      367 MB   (first call)
+```
+
+Tongue never downloads anything: its model is inside the npm package.
+
+Point an SDK at a pre-populated folder to run offline (each adapter accepts a
+`directory`), and set `HF_TOKEN` for a gated repo. Because the licence forbids
+redistribution, the plugin never bundles or mirrors weights — it downloads them
+the way the vendor intends, once, into the vendor's own cache.
+
+### Install cost is real, so it is opt-out
+
+Installing with the optional dependencies present pulls roughly **333 MB** before
+any model runs, and a first Voz call adds **367 MB** more. If that is unwanted,
+install the plugin with them skipped and add only what you use:
+
+```sh
+npm i @try-works/dsh-tool-mode --omit=optional
+npm i @desert-ant-labs/tongue        # 2 MB, and its model is included
+```
+
+**Watch out for the other model packages.** They ship prebuilt native cores for
+`linux-x64`, `linux-arm64` and `darwin-arm64` inside one tarball — roughly 50 MB
+each — so `@desert-ant-labs/redact` is ~166 MB of which the great majority is
+Linux and macOS binaries that can never load on Windows. Installing one on
+Windows buys ~130 MB that cannot run.
+
+## Development
+
+```sh
+npm install          # devDependencies: tsc, tsx, and the two model packages
+npm run link:dsh     # point @deepseek-ai/* peers at a DSH checkout
+npm run verify       # typecheck -> build -> 35 tests -> built-artifact check
+```
+
+`link:dsh` exists because `@deepseek-ai/*` are **peer** dependencies — DSH
+supplies them at runtime, so locally they must be pointed at a checkout:
+
+```sh
+node scripts/link-dsh.mjs --checkout /path/to/deepseek-harness
+```
+
+Run it again after any `npm install`: npm prunes anything in `node_modules` it
+does not own, which includes those links.
+
+`npm run verify` ends with `verify:built`, which loads `lib/index.js` — resolved
+through the package's own `main`, under plain Node with no TypeScript loader —
+and runs a real inference. That is the artifact DSH loads, so it is the only
+build whose behaviour proves the plugin is installable; passing tests against
+`src/` under `tsx` does not.
+
+| Command | Purpose |
+| --- | --- |
+| `npm run demo` | Mount the plugin on a real context and print what it registered |
+| `npm run gating` | Print the resolved route for every catalogued model |
+| `npm run gen-docs` | Regenerate the data-derived docs from the catalog |
+| `npm run bridge` | Run the reference bridge for an Apple/Linux machine |
+
+Tests always mount through `tests/helpers.ts`, which points the durable state at
+a throwaway directory. That is not cosmetic: the plugin writes user choices into
+`DSH_HOME` by default, so an unisolated test would edit the developer's real
+configuration and a later test would read those edits as a user decision.
+
+## Configuration
+
+```yaml
+- id: model-tools
+  name: '@try-works/dsh-tool-mode'
+  config:
+    models: []              # empty = every runnable model; or list ids, e.g. [tongue]
+    exclude: []             # ids to drop after `models`
+    exposeUnavailable: false # true registers tools that will fail at call time
+    registerSkills: true
+    registerControlTool: true
+    persist: true           # remember enable/disable across restarts
+    # stateFile: /path/to/state.json   # default <DSH_HOME>/model-as-tool/state.json
+    allowNpm: true          # false forces the CLI/bridge routes
+    cli:
+      enabled: true         # use the Desert Ant CLI when it is on PATH
+      command: desertant
+    remote:
+      endpoint: ''          # a bridge on a machine that can run what this one cannot
+      token: ''
+    # catalogFile: /path/to/other-catalog.json
+    # playbookFile: /path/to/other-playbooks.json
+```
+
+## Platform support
+
+This is the part that matters most, because Desert Ant's Node prebuilds cover
+`linux-x64`, `linux-arm64` and `darwin-arm64` — **not `win32-x64`**.
+
+| Tier | Models | How |
+| --- | --- | --- |
+| Runs in plain Node everywhere | Tongue | Pure JS, no WASM, no inference runtime |
+| Runs where ONNX Runtime runs | Voz | `onnxruntime-node` ships win32-x64 binaries |
+| Prebuilt for linux/darwin only | Redact, Emo, Gist, Clear, Ear, Moderator, Shapes, Align | `/native` subpath |
+| Apple only (Core ML / MLX) | Title, Uhm | Swift SDK; no JS or Kotlin SDK |
+| Closed beta, no SDK | Schemer, Toxic, Who, Eye, Face | Weights on Hugging Face, nothing ships them |
+
+The browser/WASM entry of the LiteRT models explicitly refuses to run in plain
+Node ("needs a browser/Worker environment"), so it is not a fallback.
+
+## Licensing
+
+The Desert Ant Labs models are under the
+[Source-Available License 1.0](https://license.desertant.com/1.0) — not an
+open-source license. Inference is unlimited and free below 100,000 monthly active
+devices **per platform, per model**; above that a commercial license is required.
+Attribution ("Powered by Desert Ant Labs", linked) is required, and the models
+may not be redistributed or re-hosted as a standalone product or service.
+
+That is exactly why this plugin is an installer/wrapper: it loads the official
+npm packages locally and never ships, mirrors or proxies the weights.
+
+## Tests
+
+```sh
+npm run verify        # from the repository root
+```
+
+The suite boots the plugin on a real Cordis context with the shipping
+`ToolRuntime`, `SystemPrompt` and `SkillRegistry`, then drives the registered
+tools through `ctx.tools.execute` — including a real Tongue inference. The
+transport suite injects its command runner and HTTP poster, so the CLI and bridge
+failure paths are covered without a process or a socket.
+
+The tracked requirements and acceptance evidence are summarized in
+[verification/FINAL-REPORT.md](../../verification/FINAL-REPORT.md).
+
+## Design notes
+
+- See [docs/model-as-tool-architecture.md](../../docs/model-as-tool-architecture.md)
+  for the full design.
+- See [docs/adding-a-model.md](../../docs/adding-a-model.md) to add a model.
+- See [docs/model-tool-playbook.md](../../docs/model-tool-playbook.md) for the
+  per-model use cases, tool shapes and skill content.

package/bin/dsh-tool-mode-credentials.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * The `dsh-tool-mode-credentials` executable (SEC-01).
+ *
+ * The HUMAN-ONLY credential surface: the model-visible `model_tools`
+ * management action refuses generation (a generated secret must never enter a
+ * model transcript), and this CLI is the operator's terminal instead. The
+ * stream discipline is the stdio bridge's own: STDOUT carries the credential
+ * (the secret exactly once) and nothing else; diagnostics and usage go to
+ * stderr. The secret is never logged and never recoverable.
+ */
+
+import { runCredentialsCli } from '../lib/mcp/credential-cli.js'
+
+const exit = runCredentialsCli(process.argv.slice(2), {
+  out: line => process.stdout.write(`${line}\n`),
+  err: line => process.stderr.write(`${line}\n`),
+})
+
+process.exit(exit)

package/bin/dsh-tool-mode-mcp-stdio.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * The `dsh-tool-mode-mcp-stdio` executable (MCP-03, P26-08).
+ *
+ * This file owns the one property that cannot be tested from the library: that
+ * STDOUT CARRIES PROTOCOL TRAFFIC AND NOTHING ELSE. Everything written here goes
+ * through two explicitly separate streams, and nothing in this process writes to
+ * stdout except a protocol frame — not a banner, not a version, not a warning.
+ *
+ * The endpoint and token come from the environment, which is how an MCP client
+ * launches a stdio server. A missing token is reported on STDERR and the process
+ * exits non-zero: an unattended launch must fail with guidance rather than hang
+ * waiting for a credential nobody will supply (P26-16).
+ */
+
+import { createStdioBridge } from '../lib/mcp/stdio.js'
+
+const url = process.env.DSH_TOOL_MODE_MCP_URL ?? 'http://127.0.0.1:3765/mcp'
+const token = process.env.DSH_TOOL_MODE_MCP_TOKEN
+
+/** Diagnostics. NEVER stdout. */
+const diagnostic = line => process.stderr.write(`${line}\n`)
+
+if (token === undefined || token.length === 0) {
+  // P26-16: unattended operation must fail with setup guidance, never hang.
+  diagnostic('dsh-tool-mode-mcp-stdio: no credential configured.')
+  diagnostic('  Set DSH_TOOL_MODE_MCP_TOKEN to the token the operator configured for this client,')
+  diagnostic('  and DSH_TOOL_MODE_MCP_URL if the endpoint is not http://127.0.0.1:3765/mcp.')
+  process.exit(2)
+}
+
+const bridge = createStdioBridge(
+  {
+    url,
+    token,
+    fetch: async (target, init) => {
+      const response = await fetch(target, {
+        method: init.method,
+        headers: init.headers,
+        body: init.body,
+        signal: init.signal,
+      })
+      const headers = {}
+      response.headers.forEach((value, key) => { headers[key] = value })
+      return { status: response.status, headers, body: await response.text() }
+    },
+  },
+  {
+    // The ONLY writer to stdout in this process.
+    protocol: line => process.stdout.write(`${line}\n`),
+    diagnostic,
+  },
+)
+
+// Newline-delimited input. Chunk boundaries are not frame boundaries, so a partial
+// line is buffered until its newline arrives.
+let buffer = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', chunk => {
+  buffer += chunk
+  let index = buffer.indexOf('\n')
+  while (index !== -1) {
+    const line = buffer.slice(0, index)
+    buffer = buffer.slice(index + 1)
+    void bridge.handleLine(line).then(output => {
+      if (output !== undefined) process.stdout.write(`${output}\n`)
+    }).catch(error => {
+      // A bridge fault is a diagnostic; the protocol channel stays clean.
+      diagnostic(`bridge error: ${error instanceof Error ? error.message : String(error)}`)
+    })
+    index = buffer.indexOf('\n')
+  }
+})
+
+process.stdin.on('end', () => {
+  // P26-08: EOF shuts down BRIDGE-OWNED requests without killing the shared host.
+  bridge.close()
+  diagnostic('stdin closed; bridge-owned requests aborted')
+  process.exit(0)
+})

package/bin/dsh-tool-mode.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * The `dsh-tool-mode` launcher (RUN-03/RUN-04): serve / doctor / prepare /
+ * mcp-stdio.
+ *
+ * - `serve` boots the headless host composition. The host package ships no
+ *   composition entry of its own (no src/host.ts — the recorded seam): serve
+ *   attempts to resolve the DSH composition runtime and, when it is not
+ *   resolvable from this artifact, exits non-zero with the exact missing seam
+ *   rather than inventing service constructors.
+ * - `doctor` reports configuration, package/runtime compatibility, platform
+ *   readiness and the launcher seam WITHOUT secrets.
+ * - `prepare --tool <name>` resolves the installed extension that serves the
+ *   tool and runs the digest-verified prepared-assets acquisition (a REAL
+ *   download is opt-in: the operator runs this command deliberately).
+ * - `mcp-stdio` reuses the existing stdio relay (same env contract as the
+ *   standalone binary).
+ *
+ * Every subcommand: `--json` emits structured JSON on stdout; failures exit
+ * non-zero; an unattended launch never hangs (P26-16).
+ */
+
+import { readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
+import { createInterface } from 'node:readline'
+import { dirname, join, resolve } from 'node:path'
+import { createPreparedAssetRegistry, parseAssetLock, plannedAssets, lockGroups, identityFor } from '../lib/prepared-assets.js'
+import { planPreparation } from '../lib/deployment-coordinator.js'
+import { createHttpSource } from '../lib/http-acquisition.js'
+import { createStdioBridge } from '../lib/mcp/stdio.js'
+import { discoverExtension } from '@try-works/tool-mode-extension-sdk'
+
+const args = process.argv.slice(2)
+const command = args[0] ?? '--help'
+const flag = name => {
+  const index = args.indexOf(name)
+  return index === -1 || index + 1 >= args.length ? undefined : args[index + 1]
+}
+const jsonOut = args.includes('--json')
+const report = (value) => {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+  process.exit(0)
+}
+const fail = (message, code = 2) => {
+  if (jsonOut) process.stdout.write(`${JSON.stringify({ ok: false, error: message })}\n`)
+  else process.stderr.write(`dsh-tool-mode: ${message}\n`)
+  process.exit(code)
+}
+
+/** Read the config document, tolerating its absence for the read-only commands. */
+function readConfig(path) {
+  const target = path ?? process.env.DSH_TOOL_MODE_CONFIG ?? './tool-mode.json'
+  try {
+    return JSON.parse(readFileSync(target, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+if (command === 'mcp-stdio') {
+  const url = process.env.DSH_TOOL_MODE_MCP_URL ?? 'http://127.0.0.1:3765/mcp'
+  const token = process.env.DSH_TOOL_MODE_MCP_TOKEN
+  if (token === undefined || token.length === 0) {
+    process.stderr.write('dsh-tool-mode mcp-stdio: no credential configured (DSH_TOOL_MODE_MCP_TOKEN).\n')
+    process.exit(2)
+  }
+  const bridge = createStdioBridge(
+    {
+      url,
+      token,
+      fetch: async (target, init) => {
+        const response = await fetch(target, {
+          method: init.method,
+          headers: init.headers,
+          body: init.body,
+          signal: init.signal,
+        })
+        const headers = {}
+        response.headers.forEach((value, key) => { headers[key] = value })
+        return { status: response.status, headers, body: await response.text() }
+      },
+    },
+    {
+      protocol: line => process.stdout.write(`${line}\n`),
+      diagnostic: line => process.stderr.write(`${line}\n`),
+    },
+  )
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  lines.on('line', line => {
+    void bridge.handleLine(line).then(
+      reply => { if (reply !== undefined) process.stdout.write(`${reply}\n`) },
+      error => process.stderr.write(`dsh-tool-mode mcp-stdio: ${error instanceof Error ? error.message : String(error)}\n`),
+    )
+  })
+  lines.on('close', () => bridge.close())
+  process.on('SIGINT', () => { bridge.close(); process.exit(0) })
+  process.on('SIGTERM', () => { bridge.close(); process.exit(0) })
+} else if (command === 'doctor') {
+  const config = readConfig(flag('--config'))
+  const platform = `${process.platform} ${process.arch}`
+  const nodeVersion = process.version
+  const mcpPort = config.mcpV3?.port ?? config.mcp?.port ?? 3765
+  const extensionStore = config.extensionStore ?? config.extensions?.registry ?? 'unset'
+  const result = {
+    ok: true,
+    command: 'doctor',
+    platform: { os: process.platform, arch: process.arch, node: nodeVersion, accelerator: 'cpu' },
+    configuration: {
+      schemaVersion: config.schemaVersion ?? 'legacy (v1/v2 flat shape)',
+      mcp: { host: '127.0.0.1', port: mcpPort, path: config.mcpV3?.path ?? '/mcp' },
+      extensionStore,
+      fixedFalseFlags: {
+        automaticUpdates: false,
+        runInstallScripts: false,
+        automaticActivation: false,
+        allowExecutableTemplates: false,
+        inheritConversation: false,
+        allowModelToolCalls: false,
+      },
+    },
+    launcherSeam:
+      '`serve` boots the headless composition in lib/headless.js: config -> catalog -> contract bindings -> MCP host -> '
+      + 'HTTP with credential authentication, without the DSH CLI or a browser (RUN-03). Harness-backed program '
+      + 'execution (tool_mode_run) stays refused headless: it needs the DSH PtcHostContext (CODE-10).',
+    serverStatus: 'not running (doctor does not start the listener)',
+  }
+  report(result)
+} else if (command === 'prepare') {
+  const tool = flag('--tool')
+  if (tool === undefined) fail('prepare requires --tool <toolName> (RUN-04)')
+  const config = readConfig(flag('--config'))
+  const storeDir = config.extensionStore
+  if (typeof storeDir !== 'string' || storeDir.length === 0) {
+    fail('prepare requires the extension store (config.extensionStore); the store is not configured')
+  }
+  // Resolve the installed extension whose manifest serves the requested tool.
+  const found = []
+  if (existsSync(storeDir)) {
+    for (const entry of readdirSync(storeDir)) {
+      const root = join(storeDir, entry)
+      if (!statSync(root).isDirectory()) continue
+      for (const id of readdirSync(root)) {
+        const scope = join(root, id)
+        if (!statSync(scope).isDirectory()) continue
+        for (const version of readdirSync(scope)) {
+          const installPath = join(scope, version)
+          if (!existsSync(join(installPath, 'tool-mode.extension.json'))) continue
+          try {
+            const discovery = discoverExtension(installPath)
+            const serves = discovery.manifest.tools.some(t => t.name === tool)
+              || discovery.manifest.implementations.some(impl => {
+                const owner = discovery.manifest.tools.find(t => t.contractId === impl.contractId)
+                return owner?.name === tool
+              })
+            if (serves) found.push({ discovery, installPath })
+          } catch {
+            // A broken package is skipped: prepare never guesses.
+          }
+        }
+      }
+    }
+  }
+  if (found.length === 0) fail(`no installed extension serves the tool ${JSON.stringify(tool)} (prepare never guesses)`)
+  const { discovery, installPath } = found[0]
+  const model = discovery.manifest.models[0]
+  if (model === undefined) fail(`the extension serving ${tool} declares no model deployment`)
+  const lockPath = join(dirname(discovery.manifestPath), model.assetLock)
+  const lock = parseAssetLock(readFileSync(lockPath, 'utf8'))
+  const groups = lockGroups(lock, model.assetSet)
+  const plan = planPreparation(identityFor(discovery.manifest.id, model.id, lock), plannedAssets(lock, model.assetSet), lock.license)
+  const statePath = config.stateFile ?? join(process.env.LOCALAPPDATA ?? process.env.TEMP ?? '.', 'dsh-tool-mode', 'state.json')
+  const registry = createPreparedAssetRegistry({ cacheRoot: join(dirname(resolve(statePath)), 'asset-cache') })
+  const outcome = await registry.prepare(discovery.manifest.id, plan, groups, {
+    source: createHttpSource(),
+    allowExecutable: false,
+    signal: new AbortController().signal,
+  })
+  if (!outcome.ok) fail(`the preparation failed: ${outcome.reason}`, 1)
+  const transferred = outcome.groups.map(group => group.digests.map(digest => createHash('sha256').update(digest).digest('hex')))
+  report({
+    ok: true,
+    command: 'prepare',
+    tool,
+    extension: discovery.manifest.id,
+    model: model.id,
+    revision: lock.revision,
+    groups: outcome.groups.map(group => ({ groupId: group.groupId, path: group.path, digests: group.digests })),
+    note: `transferred digests (${transferred.length} groups) are the content hashes; sizes are per-asset in the lock`,
+  })
+} else if (command === 'serve') {
+  // The REAL headless composition (RUN-03, task-74): config load, catalog
+  // resolution, contract bindings, the MCP HTTP listener, and a bounded
+  // SIGINT/SIGTERM shutdown — composed from the host's own services, no DSH
+  // CLI required.
+  const { runHeadlessServe } = await import('../lib/headless.js')
+  const exit = await runHeadlessServe(
+    { configPath: flag('--config'), json: jsonOut },
+    { out: line => process.stdout.write(`${line}\n`), err: line => process.stderr.write(`${line}\n`) },
+  )
+  process.exit(exit)
+} else {
+  process.stderr.write(
+    'dsh-tool-mode: usage\n'
+    + '  dsh-tool-mode serve [--config tool-mode.json] [--json]\n'
+    + '  dsh-tool-mode doctor [--config tool-mode.json] [--json]\n'
+    + '  dsh-tool-mode prepare --tool <toolName> [--config tool-mode.json] [--json]\n'
+    + '  dsh-tool-mode mcp-stdio\n',
+  )
+  process.exit(command === '--help' || command === '-h' ? 0 : 2)
+}

package/builtins.lock.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "description": "Host-release trusted built-ins. This file is authoritative; a package manifest cannot grant itself built-in status or extra trust.",
+  "builtins": [
+    {
+      "extensionId": "@try-works/extension-embeddinggemma",
+      "package": "@try-works/extension-embeddinggemma",
+      "protected": true
+    },
+    {
+      "extensionId": "@try-works/extension-laya",
+      "package": "@try-works/extension-laya",
+      "protected": true
+    },
+    {
+      "extensionId": "@try-works/extension-needle",
+      "package": "@try-works/extension-needle",
+      "protected": true
+    },
+    {
+      "extensionId": "@try-works/extension-declarative-recipes",
+      "package": "@try-works/extension-declarative-recipes",
+      "protected": true
+    }
+  ]
+}