dsh-pi-bridge 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Twofruitsgrape
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# dsh-pi-bridge
 
-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.
+**One plugin, two hosts — and each host can install the other’s plugins.**
+
+Install it into [pi](https://pi.dev) (`pi install npm:dsh-pi-bridge`) or into
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh plugin add dsh-pi-bridge`),
+and you get the same behaviour either way, plus a bridge that loads packages from *the other
+ecosystem* as native tools, slash commands and skills.
+
+一份代码，两个宿主：装到 pi 或装到 DSH —— 装完之后，两边的插件可以互相安装。
+DSH 里用 `pi_install` 装 pi 的插件，pi 里用 `/dsh-install` 装 DSH 的插件，转成本地宿主的
+工具 / 斜杠命令 / 技能。
+
+## Install
+
+```bash
+# pi coding agent
+pi install npm:dsh-pi-bridge            # or: pi install git:github.com/Twofruitsgrape/dsh-pi-bridge
+
+# DeepSeek Harness
+dsh plugin add dsh-pi-bridge            # or install from the plugin panel: github:Twofruitsgrape/dsh-pi-bridge
+```
+
+Restart the host afterwards. Both keywords (`pi-package`, `dsh-plugin`) are declared, so the
+package is discoverable in each ecosystem’s own market.
+
+## What you get in each host
+
+| | pi | DSH |
+|---|---|---|
+| Install from the other side | `/dsh-install <source>`, tools `dsh_install` / `dsh_preview` | tools `pi_install` / `pi_preview` / `dsh_install` |
+| Manage bridges | `/bridge-list`, `/bridge-remove` | tools `bridge_list` / `bridge_remove` |
+| Skill | `skills/dsh-pi-bridge/SKILL.md` | same `SKILL.md`, mounted through the skill registry |
+
+Sources use one grammar on both sides: `npm:<pkg>[@ver]`, `git:github.com/<owner>/<repo>[@ref]`,
+`github:<owner>/<repo>`, a repository URL, or a local path — exactly what each host already accepts.
+
+```text
+dsh> pi_preview({ source: "npm:pi-subagents" })
+   package: pi-subagents@0.78.0
+   detected: {"pi":["keyword:pi-package","manifest:pi","layout:extensions|skills"]}
+     [tool] task     Run a supervised subagent task
+     [tool] taskstop Stop a running subagent
+     [command] /tasks Show running subagent tasks
+     [unsupported] TUI renderer (host-specific)
+
+dsh> pi_install({ source: "npm:pi-subagents" })
+   bridged npm:pi-subagents as pi-subagents@0.78.0
+     tools: pisubagents_task, pisubagents_taskstop
+     commands: /pisubagents_tasks
+     skipped: event has no DSH equivalent: cache_warming_decision
+```
+
+## How it works
+
+```text
+resolve      npm registry tarball / shallow git clone / local copy -> ~/.dsh-pi-bridge cache
+mirror       a private build tree, so a bridged package never imports a real host
+stub         every foreign host import becomes an inert stand-in, or a real bridge shim
+compile      TypeScript -> ESM with node:module stripTypeScriptTypes (no toolchain, no download)
+capture      load the package against a recording host API and collect what it registers
+replay       install those registrations onto the local host, converting schema both ways
+```
+
+A DSH tool declaration carries a property spec map (`{ text: { type: ‘string’, required: true } }`)
+that `@deepseek-ai/dsh-tools` compiles to JSON Schema; a pi tool carries the JSON Schema directly
+(TypeBox). `src/schema.js` converts both directions, so a bridged tool’s parameters validate in the
+host that receives it. Result shapes are projected the same way: pi’s
+`{ content: [{ type: ‘text’ }] }` to DSH’s `{ ok, result }` and back.
+
+Skills need no conversion at all — both hosts implement the
+[Agent Skills specification](https://agentskills.io/specification), so a `SKILL.md` directory simply
+travels. DSH providers are read asynchronously (`list()` is a promise), and the bridge awaits them
+before replay, which is how a bundle like `dsh-comsol` crosses into pi intact.
+
+## Verified against real published packages
+
+Measured with `npm run test:all` (offline suites plus the network cases), on the
+packages each ecosystem actually ships:
+
+| Bridged package | Direction | Arrived | Reported as not crossing |
+|---|---|---|---|
+| `pi-web-access@0.40.0` | pi → DSH | 4 tools, 4 commands, 6 event hooks | `registerShortcut`, 4 unmapped events |
+| `pi-subagents@0.78.0` | pi → DSH | 3 tools, 19 commands, 4 skill dirs | 33 items listed in the report |
+| `@plannotator/pi-extension@0.28.20` | pi → DSH | 216 TS files compiled, 1 skill dir | renderer registrations |
+| `dsh-comsol@1.1.1` (git) | DSH → pi / DSH | its `comsol-dsh` skill | — |
+| `dsh-cost-meter@1.8.26` | DSH → pi | nothing | correctly reports zero registrations |
+
+The last row is the honest case: a DSH plugin that is purely a UI/service
+overlay has nothing to bridge, and the preview says so instead of pretending.
+
+Bridged tools are executed in the tests, not just listed — `web_search` and
+`source_check` respond with their own argument-validation errors, which proves
+the real package logic runs under the receiving host's tool shape.
+
+## What does not cross
+
+The bridge reports these instead of failing quietly:
+
+- **Model providers and adapters** (`pi.registerProvider`, `ctx.llm.registerAdapter`): wired to host
+  internals, not portable.
+- **Host UI**: DSH browser pages / `ctx.slots` and pi’s TUI renderers, `ctx.ui`, shortcuts, CLI flags.
+- **Events without a counterpart**: a small name map covers the lifecycle overlap
+  (`session_start` ↔ `agent/created`, `tool_call` ↔ `tools/pre-execute`, …); anything else is listed.
+
+Registrations land in the current session immediately, and each host replays the recorded bridges when
+the plugin loads, so an install survives a restart. That replay is cache-only: host startup never waits
+on a network download, and a pruned cache simply reports the bridge as unavailable until it is installed
+again. `restoreOnLoad: false` in the bundle config turns replay off.
+
+The bridge keeps its own registry at `~/.dsh-pi-bridge/bridges.json` and writes nothing into either
+host’s settings. `bridge_remove` forgets a bridge and deletes its mirror; tools already registered in
+the running process stay until restart, because silently unregistering host state would be worse than
+leaving it visible.
+
+## Security
+
+A bridged package **executes code with your permissions**, on whichever side you install it — the
+same trust requirement every extension host has, doubled because the package came from the other
+ecosystem and was not vetted by its market. Read its source before you install it.
+
+The bridge limits the blast radius, it does not remove it: packages load from a private mirror whose
+`node_modules` contains only generated stubs, so a bridged extension cannot import the real host API
+or reach either host’s configuration through the import map. `preview` first — it resolves and
+captures but registers nothing.
+
+## Develop
+
+```bash
+npm test                # 34 offline checks: both directions, mock hosts, no network
+npm run test:entries    # loads both real entries and asserts the host-facing surface
+npm run test:all        # the above plus the real-package cases (needs network)
+npm run e2e             # just the published-package probes
+```
+
+The self-test builds fixtures by hand — a TypeScript pi extension using the TypeBox builder, and a
+DSH bundle using `defineTool` with an async skill provider — then runs the full pipeline against a
+recording mock host and executes the bridged tools. `scripts/selfhost-check.mjs` feeds this package's
+own DSH entry through the bridge, so the entry conventions are tested by the same machinery a foreign
+bundle meets.
+
+Nothing is written outside `~/.dsh-pi-bridge` (override with `DSH_PI_BRIDGE_HOME`). A bridged package
+sees only its mirrored build tree, so its relative imports work while its host imports resolve to the
+bridge's stubs.
+
+## Layout
+
+```text
+index.js              DSH entry: name / inject / apply(ctx), the pi_install tool family
+extensions/index.js   pi entry: default(pi) factory, /dsh-install and the dsh_install tools
+skills/dsh-pi-bridge/ SKILL.md, shared by both hosts
+cordis.patch.yml      DSH bundle mount (the plugin panel toggle target)
+src/manifest.js       host detection from keywords, manifests and directory layout
+src/resolve.js        npm / git / url / local sources into a cache
+src/tar.js            gzipped-tar reader (npm tarballs), no dependency
+src/transpile.js      TypeScript -> ESM via node:module, swc/typescript fallback
+src/stubs.js          import scanning + inert stub generation
+src/typebox-shim.js   TypeBox- and zod-shaped builders over plain JSON Schema
+src/capture.js        recording stand-in hosts for both entry conventions
+src/schema.js         parameter schema conversion, both directions
+src/replay-dsh.js     capabilities -> ctx.tools / ctx.commands / ctx.skills
+src/replay-pi.js      capabilities -> pi.registerTool / registerCommand / resources_discover
+src/capabilities.js   normalized capability model, event name map, result projection
+```
+
+`index.js` imports only `node:` builtins plus this package, and declares `inject: [‘tools’]` with
+everything else acquired through `ctx.inject`, so a profile that composes without the skill registry
+loses skill mounting rather than failing to load.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-pi-bridge bundle patch: mount the host half under its own name.
+- insert:
+    - id: pi-bridge
+      name: 'dsh-pi-bridge'
+      config: {}

package/extensions/index.js

@@ -0,0 +1,221 @@
+/**
+ * dsh-pi-bridge — pi entry: the extension half of the plugin.
+ *
+ * pi loads this file through the package's pi.extensions manifest and calls the
+ * default factory with an ExtensionAPI. The factory registers the cross-host
+ * installer as pi slash commands plus two model-callable tools, so a pi user or
+ * agent can install a DSH plugin bundle into the running pi session.
+ *
+ * A DSH bundle is loaded against a recording stand-in host (src/capture.js) and
+ * its registrations are replayed onto pi's real API (src/replay-pi.js).
+ * DSH-only capabilities are reported rather than dropped in silence.
+ *
+ * @module extensions/index.js
+ */
+import { loadForeign } from "../src/load.js";
+import { replayIntoPi } from "../src/replay-pi.js";
+import { CACHE_ROOT } from "../src/resolve.js";
+import { restoreIntoPi } from "../src/restore.js";
+
+const REGISTRY = CACHE_ROOT + "/bridges.json";
+
+/** Remember bridges in our own cache, never in pi's settings. */
+async function readState() {
+  try {
+    const { readFile } = await import("node:fs/promises");
+    return JSON.parse(await readFile(REGISTRY, "utf8"));
+  } catch {
+    return { bridges: {} };
+  }
+}
+
+async function writeState(state) {
+  const { mkdir, writeFile } = await import("node:fs/promises");
+  await mkdir(CACHE_ROOT, { recursive: true });
+  await writeFile(REGISTRY, JSON.stringify(state, null, 2), "utf8");
+}
+
+function shortPrefix(name) {
+  const s = String(name)
+    .replace(/^@[^/]+\//, "")
+    .replace(/^dsh-/, "")
+    .replace(/^pi-/, "")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .toLowerCase()
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 24);
+  return s || "bridged";
+}
+
+function formatReport(spec, captured, report) {
+  const lines = ["bridged " + spec + " as " + captured.info.name + "@" + captured.info.version];
+  lines.push("  tools: " + (report.tools.length ? report.tools.join(", ") : "none"));
+  lines.push("  commands: " + (report.commands.length ? report.commands.map((c) => "/" + c).join(", ") : "none"));
+  lines.push("  skills: " + (report.skills.length ? report.skills.join(", ") : "none"));
+  if (report.events.length) lines.push("  events: " + report.events.join(", "));
+  if (report.skipped.length) lines.push("  skipped: " + report.skipped.join("; "));
+  if (captured.errors && captured.errors.length) lines.push("  load errors: " + captured.errors.join("; "));
+  lines.push("  bridged tools are callable in this session immediately.");
+  return lines.join("\n");
+}
+
+async function previewText(captured) {
+  const lines = [
+    "package: " + captured.info.name + "@" + captured.info.version,
+    "detected hosts: " + JSON.stringify(captured.info.signals),
+  ];
+  for (const cap of captured.capabilities || []) {
+    lines.push("  [" + cap.kind + "] " + cap.name + " - " + String(cap.description || "").slice(0, 100));
+  }
+  for (const dir of captured.skillDirs || []) lines.push("  [skill-dir] " + dir);
+  for (const e of captured.events || []) lines.push("  [event] " + e.event);
+  for (const u of captured.unsupported || []) lines.push("  [unsupported] " + u);
+  for (const err of captured.errors || []) lines.push("  [error] " + err);
+  if (!(captured.capabilities || []).length && !(captured.skillDirs || []).length) {
+    lines.push("  (nothing registrable found - the bundle may need host services the bridge cannot stand in for)");
+  }
+  return lines.join("\n");
+}
+
+export default async function (pi) {
+  async function installDsh(spec, opts) {
+    const captured = await loadForeign(spec, { host: "dsh", refresh: !!(opts && opts.refresh) });
+    const prefix = (opts && opts.prefix) || shortPrefix(captured.info.name);
+    const report = replayIntoPi(pi, captured, { prefix });
+    const state = await readState();
+    state.bridges = state.bridges || {};
+    state.bridges[spec] = {
+      name: captured.info.name,
+      version: captured.info.version,
+      host: "dsh",
+      prefix,
+      mirror: captured.mirror,
+      report,
+      at: new Date().toISOString(),
+    };
+    await writeState(state);
+    return formatReport(spec, captured, report);
+  }
+
+  function firstArg(args) {
+    return String(args || "").trim().split(/\s+/)[0];
+  }
+
+  pi.registerCommand("dsh-install", {
+    description: "Install a DeepSeek Harness (DSH) plugin bundle into this pi session as tools, commands and skills",
+    handler: async (args, ctx) => {
+      const spec = firstArg(args);
+      if (!spec) return notify(ctx, "usage: /dsh-install <npm:pkg | github:owner/repo | url | local path>", "error");
+      notify(ctx, "bridging " + spec + " ...", "info");
+      try {
+        notify(ctx, await installDsh(spec), "info");
+      } catch (e) {
+        notify(ctx, "dsh-install failed: " + message(e), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("dsh-preview", {
+    description: "Inspect what a DSH plugin bundle would contribute before installing it",
+    handler: async (args, ctx) => {
+      const spec = firstArg(args);
+      if (!spec) return notify(ctx, "usage: /dsh-preview <source>", "error");
+      try {
+        notify(ctx, await previewText(await loadForeign(spec, { host: "dsh" })), "info");
+      } catch (e) {
+        notify(ctx, "dsh-preview failed: " + message(e), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("bridge-list", {
+    description: "List plugin bundles this bridge installed into pi",
+    handler: async (_args, ctx) => {
+      const state = await readState();
+      const keys = Object.keys(state.bridges || {});
+      if (!keys.length) return notify(ctx, "no bridged bundles yet", "info");
+      notify(ctx, keys.map((k) => {
+        const b = state.bridges[k];
+        return "- " + k + " (" + b.name + "@" + b.version + ") tools=" + (b.report.tools || []).join(",");
+      }).join("\n"), "info");
+    },
+  });
+
+  pi.registerCommand("bridge-remove", {
+    description: "Forget a bridged bundle and delete its mirror build",
+    handler: async (args, ctx) => {
+      const spec = firstArg(args);
+      const state = await readState();
+      if (!spec || !state.bridges || !state.bridges[spec]) {
+        return notify(ctx, "not bridged: " + (spec || "(no source given)"), "error");
+      }
+      const entry = state.bridges[spec];
+      delete state.bridges[spec];
+      await writeState(state);
+      const { rm } = await import("node:fs/promises");
+      if (entry.mirror) await rm(entry.mirror, { recursive: true, force: true });
+      notify(ctx, "removed " + spec + " (tools registered earlier stay until pi restarts)", "info");
+    },
+  });
+
+  // Model-callable mirrors, so an agent can install a DSH bundle unattended.
+  pi.registerTool({
+    name: "dsh_install",
+    label: "Install DSH plugin",
+    description: "Install a DeepSeek Harness plugin bundle into this pi session as native pi tools, slash commands and skills. Accepts the same source grammar pi uses: npm:<pkg>[@ver], git:github.com/<owner>/<repo>[@ref], github:<owner>/<repo>, a URL, or a local path.",
+    promptSnippet: "Install a DSH plugin bundle as pi tools and commands",
+    parameters: {
+      type: "object",
+      properties: {
+        source: { type: "string", description: "Bundle source string." },
+        prefix: { type: "string", description: "Optional lowercase prefix for bridged names." },
+        refresh: { type: "boolean", description: "Re-download even when already cached." },
+      },
+      required: ["source"],
+    },
+    async execute(_id, params) {
+      try {
+        return { content: [{ type: "text", text: await installDsh(params.source, params) }], details: { bridge: "dsh-install" } };
+      } catch (e) {
+        return { content: [{ type: "text", text: "dsh_install failed: " + message(e) }], details: { error: true } };
+      }
+    },
+  });
+
+  // Replay recorded DSH bundles so /dsh-install survives a pi restart.
+  const state = await readState();
+  const restore = await restoreIntoPi(pi, state, { log: (m) => console.log(m) });
+  if (restore.failed.length) console.log("dsh-pi-bridge restore skipped: " + restore.failed.join("; "));
+
+  pi.registerTool({
+    name: "dsh_preview",
+    label: "Preview DSH plugin",
+    description: "Inspect what a DeepSeek Harness plugin bundle would contribute to this pi session before installing it.",
+    promptSnippet: "Preview a DSH bundle's tools, commands and skills",
+    parameters: {
+      type: "object",
+      properties: { source: { type: "string", description: "Bundle source string." } },
+      required: ["source"],
+    },
+    async execute(_id, params) {
+      try {
+        return { content: [{ type: "text", text: await previewText(await loadForeign(params.source, { host: "dsh" })) }], details: { bridge: "dsh-preview" } };
+      } catch (e) {
+        return { content: [{ type: "text", text: "dsh_preview failed: " + message(e) }], details: { error: true } };
+      }
+    },
+  });
+}
+
+function notify(ctx, text, level) {
+  try {
+    if (ctx && ctx.ui && typeof ctx.ui.notify === "function") return ctx.ui.notify(text, level || "info");
+  } catch {
+    /* fall through to stdout */
+  }
+  console.log(text);
+}
+
+function message(e) {
+  return e && e.message ? String(e.message).slice(0, 400) : String(e);
+}

package/index.js

@@ -0,0 +1,230 @@
+/**
+ * dsh-pi-bridge — DSH (DeepSeek Harness) entry: the host half of the plugin.
+ *
+ * Cordis plugin contract: name, inject, apply(ctx, config). The plugin exposes
+ * the cross-host installer as DSH tools, so an agent — or the user through the
+ * tool — can install pi packages into the running DSH, preview what a package
+ * would provide before installing, and forget bridges again. Registry state
+ * lives under ~/.dsh-pi-bridge; nothing here writes into DSH's own profile, so
+ * uninstalling the bridge leaves the profile as it was.
+ *
+ * Services are acquired with ctx.inject rather than a static inject list for
+ * everything except tools: a profile that composes without the skills registry
+ * loses skill mounting, not the whole plugin.
+ *
+ * @module index.js
+ */
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises'
+import { loadForeign } from './src/load.js'
+import { replayIntoDsh, skillProviderFor } from './src/replay-dsh.js'
+import { CACHE_ROOT } from './src/resolve.js'
+import { restoreIntoDsh } from './src/restore.js'
+
+export const name = 'dsh-pi-bridge'
+/** tools is the only hard requirement; the rest degrades through ctx.inject. */
+export const inject = ['tools']
+
+const REGISTRY_FILE = path.join(CACHE_ROOT, 'bridges.json')
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+
+const OUT = () => ({
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      ok: { type: 'boolean', required: true },
+      result: { type: 'string', required: true },
+    },
+  },
+  render: (_args, value) => [{ type: 'text', text: (value && value.result) || '' }],
+})
+
+/** Every host tool answers through one guard: never throw into the agent loop. */
+function guarded (fn) {
+  return async (args) => {
+    try { return { ok: true, result: String(await fn(args || {})) } }
+    catch (e) { return { ok: false, result: 'dsh-pi-bridge: ' + message(e) } }
+  }
+}
+
+/** Host defineTool when the profile composes dsh-tools; a faithful fallback otherwise. */
+async function toolCompiler () {
+  try {
+    const mod = await import('@deepseek-ai/dsh-tools')
+    if (typeof mod.defineTool === 'function') return mod.defineTool
+  } catch { /* host without the tools package (self-test) */ }
+  const { specToJsonSchema } = await import('./src/schema.js')
+  return (options) => ({
+    ...options,
+    parameters: specToJsonSchema(options.parameters),
+    execute: async (args, exec) => options.execute(args, exec),
+  })
+}
+
+async function readRegistry () {
+  try { return JSON.parse(await readFile(REGISTRY_FILE, 'utf8')) } catch { return { bridges: {} } }
+}
+
+async function writeRegistry (state) {
+  await mkdir(CACHE_ROOT, { recursive: true })
+  await writeFile(REGISTRY_FILE, JSON.stringify(state, null, 2), 'utf8')
+}
+
+function defaultPrefix (name) {
+  const s = String(name)
+    .replace(/^@[^/]+\//, '')
+    .replace(/^dsh-/, '')
+    .replace(/^pi-/, '')
+    .replace(/[^A-Za-z0-9]+/g, '_')
+    .toLowerCase()
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 24)
+  return s || 'bridged'
+}
+
+function message (e) {
+  return e && e.message ? String(e.message).slice(0, 400) : String(e)
+}
+
+function formatReport (spec, captured, report) {
+  const lines = ['bridged ' + spec + ' as ' + captured.info.name + '@' + captured.info.version]
+  lines.push('  tools: ' + (report.tools.length ? report.tools.join(', ') : 'none'))
+  lines.push('  commands: ' + (report.commands.length ? report.commands.map(c => '/' + c).join(', ') : 'none'))
+  lines.push('  skills: ' + (report.skills.length ? report.skills.join(', ') : 'none'))
+  if (report.events.length) lines.push('  events: ' + report.events.join(', '))
+  if (report.skipped.length) lines.push('  skipped: ' + report.skipped.join('; '))
+  if (captured.errors && captured.errors.length) lines.push('  load errors: ' + captured.errors.join('; '))
+  lines.push('  Tools are callable now. On the next DSH start they are replayed from the bridge cache, so the install persists; other clients pick them up then.')
+  return lines.join('\n')
+}
+
+async function previewText (captured) {
+  const lines = ['package: ' + captured.info.name + '@' + captured.info.version, 'detected: ' + JSON.stringify(captured.info.signals)]
+  for (const cap of captured.capabilities || []) lines.push('  [' + cap.kind + '] ' + cap.name + ' - ' + String(cap.description || '').slice(0, 100))
+  for (const dir of captured.skillDirs || []) lines.push('  [skill-dir] ' + dir)
+  for (const e of captured.events || []) lines.push('  [event] ' + e.event)
+  for (const u of captured.unsupported || []) lines.push('  [unsupported] ' + u)
+  for (const err of captured.errors || []) lines.push('  [error] ' + err)
+  if (!(captured.capabilities || []).length && !(captured.skillDirs || []).length) lines.push('  (nothing registrable found - the bundle may need host services the bridge cannot stand in for)')
+  return lines.join('\n')
+}
+
+export async function apply (ctx, config) {
+  void config
+  const tool = await toolCompiler()
+  const state = await readRegistry()
+  state.bridges = state.bridges || {}
+  const log = (m) => { try { ctx.logger && ctx.logger.info && ctx.logger.info(m) } catch { /* ignore */ } }
+
+  /** Install one pi package as DSH capabilities and record it. */
+  async function installPi (spec, opts) {
+    const captured = await loadForeign(spec, { host: 'pi', refresh: !!(opts && opts.refresh), log })
+    const prefix = (opts && opts.prefix) || defaultPrefix(captured.info.name)
+    const report = await replayIntoDsh(ctx, captured, { prefix })
+    state.bridges[spec] = {
+      name: captured.info.name,
+      version: captured.info.version,
+      host: 'pi',
+      prefix,
+      mirror: captured.mirror,
+      report,
+      at: new Date().toISOString(),
+    }
+    await writeRegistry(state)
+    return formatReport(spec, captured, report)
+  }
+
+  const SOURCE = { type: 'string', required: true, description: 'Plugin source in pi grammar: npm:<pkg>[@ver], git:github.com/<owner>/<repo>[@ref], github:<owner>/<repo>, a URL, or a local path.' }
+  const PREFIX = { type: 'string', description: 'Optional lowercase prefix for bridged names; defaults to the package name.' }
+
+  ctx.tools.register(tool({
+    name: 'pi_install',
+    description: 'Install a pi coding agent package into this DSH session as native DSH tools, slash commands and skills. It resolves the source, compiles its TypeScript to ESM, loads it against a recording host, and replays what it registers onto DSH. Accepts the same source string pi would use. Re-running reloads the package.',
+    parameters: {
+      source: SOURCE,
+      prefix: PREFIX,
+      refresh: { type: 'boolean', description: 'Re-download the source even when it is already in the bridge cache.' },
+    },
+    output: OUT(),
+    execute: guarded(async (args) => installPi(args.source, args)),
+  }))
+
+  ctx.tools.register(tool({
+    name: 'pi_preview',
+    description: 'Inspect what a pi package would provide before installing it: the tools, commands, skills and events it registers, plus anything the bridge cannot carry over. Loads the package into the cache without touching the session.',
+    parameters: { source: SOURCE },
+    output: OUT(),
+    execute: guarded(async (args) => previewText(await loadForeign(args.source, { host: 'pi', log }))),
+  }))
+
+  ctx.tools.register(tool({
+    name: 'dsh_install',
+    description: 'Load another DSH plugin bundle into this session through the bridge, for a bundle the profile does not mount. Inspects the bundle manifest, records its registrations and replays them; it does not replace a bundle the profile already installed.',
+    parameters: { source: SOURCE, prefix: PREFIX },
+    output: OUT(),
+    execute: guarded(async (args) => {
+      const captured = await loadForeign(args.source, { host: 'dsh', log })
+      const prefix = (args.prefix) || defaultPrefix(captured.info.name)
+      const report = await replayIntoDsh(ctx, captured, { prefix })
+      state.bridges[args.source] = { name: captured.info.name, version: captured.info.version, host: 'dsh', prefix, mirror: captured.mirror, report, at: new Date().toISOString() }
+      await writeRegistry(state)
+      return formatReport(args.source, captured, report)
+    }),
+  }))
+
+  ctx.tools.register(tool({
+    name: 'bridge_list',
+    description: 'List plugin bundles this bridge installed into DSH, with the tools, commands and skills each contributed.',
+    parameters: {},
+    output: OUT(),
+    execute: guarded(async () => {
+      const keys = Object.keys(state.bridges)
+      if (!keys.length) return 'no bridged packages yet'
+      return keys.map(k => {
+        const b = state.bridges[k]
+        return '- ' + k + ' (' + b.name + '@' + b.version + ', host=' + b.host + ') tools=' + (b.report.tools || []).join(',') + ' commands=' + (b.report.commands || []).join(',') + ' skills=' + (b.report.skills || []).length
+      }).join('\n')
+    }),
+  }))
+
+  ctx.tools.register(tool({
+    name: 'bridge_remove',
+    description: 'Forget a bridged package and delete its mirror build from the bridge cache. Registrations already made in this process stay until DSH restarts.',
+    parameters: { source: { ...SOURCE, description: 'The exact source string previously installed.' } },
+    output: OUT(),
+    execute: guarded(async (args) => {
+      if (!state.bridges[args.source]) return 'not bridged: ' + args.source
+      const entry = state.bridges[args.source]
+      delete state.bridges[args.source]
+      await writeRegistry(state)
+      if (entry.mirror) await rm(entry.mirror, { recursive: true, force: true })
+      return 'removed ' + args.source + ' from the bridge registry (restart DSH to drop its registrations)'
+    }),
+  }))
+
+  // Skills from previously recorded bridges remount on every plugin load.
+  ctx.inject(['skills'], (scope) => {
+    if (!scope || !scope.skills || typeof scope.skills.registerProvider !== 'function') return
+    for (const entry of Object.values(state.bridges)) {
+      for (const dir of (entry.report && entry.report.skills) || []) {
+        if (existsSync(path.join(dir, 'SKILL.md'))) scope.skills.registerProvider(() => skillProviderFor(dir))
+      }
+    }
+    // The bridge's own skill, so users find the workflow from the skill list.
+    const selfSkill = path.join(HERE, 'skills', 'dsh-pi-bridge')
+    if (existsSync(path.join(selfSkill, 'SKILL.md'))) scope.skills.registerProvider(() => skillProviderFor(selfSkill))
+  })
+
+  // Replay recorded pi packages so an install survives a restart instead of
+  // living one session. Disabled with { restoreOnLoad: false } in bundle config.
+  const restore = (config && config.restoreOnLoad === false) ? { restored: [], failed: [] } : await restoreIntoDsh(ctx, state, { log })
+  if (restore.failed.length) { try { ctx.logger && ctx.logger.warn && ctx.logger.warn('dsh-pi-bridge restore: ' + restore.failed.join('; ')) } catch { /* ignore */ } }
+
+  const count = Object.keys(state.bridges).length
+  log('dsh-pi-bridge loaded: ' + count + ' bridged package(s) on record, ' + restore.restored.length + ' replayed')
+}
+
+export default { name, inject, apply }