super-dsh 0.1.0 → 0.1.2

package/agent-omp/sidecar/main.ts

@@ -0,0 +1,481 @@
+/**
+ * omp-web sidecar entry — run under bun.
+ *
+ *   OMP_HOME=~/.omp bun run sidecar/main.ts
+ *
+ * Wraps @oh-my-pi/pi-coding-agent and speaks the v0 JSON-lines protocol
+ * defined in ../src/protocol.ts. One sidecar = one OMP "app instance":
+ * shared authStorage / modelRegistry across all sessions it hosts.
+ *
+ * Sessions are addressed by a sidecar-minted `handle` (h1, h2, ...) rather
+ * than the OMP session id, because AgentSession-level operations
+ * (newSession / switchSession / fork) mint a NEW OMP session id while the
+ * bridge-side handle must stay stable for the lifetime of the client.
+ */
+import { createAgentSession, SessionManager, discoverAuthStorage, ModelRegistry, Settings, loadSessionMessagesReadOnly, parseSessionEntries, discoverSkills, discoverSlashCommands, AgentRegistry, getThemeByName, setThemeInstance } from "@oh-my-pi/pi-coding-agent";
+import { PROTOCOL_VERSION, type EventFrame, type RequestFrame, type ResponseFrame } from "../dist/protocol.js";
+// The SDK's lsp tool formats results through the module-level `theme`
+// instance, which only TUI mode initializes. In this headless sidecar any
+// `theme.status` access crashes ("undefined is not an object") — the lsp
+// device was unusable in the bridge line. Initialize the configured theme
+// (config.yml `theme.dark`) at startup; fall back to a minimal identity stub
+// so startup can never fail over cosmetics.
+try {
+  // The lsp formatter only touches `theme.status` icons, so the identity stub
+  // is the guaranteed floor; the configured theme (config.yml theme.dark,
+  // "titanium" in this deployment) is preferred when loadable.
+  const stub = {
+    status: { success: "✓", warning: "⚠", error: "✗" },
+    fg: (_role: unknown, text?: string) => (typeof text === "string" ? text : ""),
+  } as unknown as Parameters<typeof setThemeInstance>[0];
+  setThemeInstance((await getThemeByName("titanium")) ?? stub);
+  console.error("[sidecar] theme initialized");
+}
+catch (error) {
+  console.error(`[sidecar] theme init failed (lsp device may crash): ${error}`);
+  if (error instanceof Error) console.error(error.stack?.split("\n").slice(0, 8).join("\n") ?? "(no stack)");
+}
+
+// ---------- outbound ----------
+
+function send(frame: ResponseFrame | EventFrame): void {
+  process.stdout.write(JSON.stringify(frame) + "\n");
+}
+
+// ---------- shared app-level state (A-lane) ----------
+
+const piPkg = (await import("@oh-my-pi/pi-coding-agent/package.json")) as any;
+const PKG_VERSION: string = piPkg?.default?.version ?? piPkg?.version ?? "unknown";
+
+const authStorage = await discoverAuthStorage();
+const modelRegistry = new ModelRegistry(authStorage);
+void (modelRegistry as any).refreshInBackground?.()?.catch?.(() => {});
+
+// Lazily-cached PERSISTENT Settings instance for modelRoles writes. Cached so
+// repeated writes reuse one instance (and one agent.db handle); the SDK's
+// whole-object `set` captures the on-disk generation at write time, so a cached
+// instance does NOT serve stale data to the generation check. (readOnly
+// instances never persist, so a fresh instance is not an option here.)
+let writableSettingsPromise: Promise<Settings> | null = null;
+function getWritableSettings(): Promise<Settings> {
+  if (writableSettingsPromise === null) {
+    writableSettingsPromise = Settings.loadIsolated();
+  }
+  return writableSettingsPromise;
+}
+
+interface HeldSession {
+  session: Awaited<ReturnType<typeof createAgentSession>>["session"];
+  unsubscribe: () => void;
+}
+const sessions = new Map<string, HeldSession>();
+let nextHandle = 0;
+/**
+ * Per-session agent identity for `createAgentSession`. The SDK's session init
+ * registers the top-level agent in the PROCESS-GLOBAL roster keyed by agent id
+ * — the default id ("Main") collides whenever a second session initializes
+ * while a first is still registered, failing with `Agent "Main" was replaced
+ * during session initialization` (upstream changelog: embedders pass a unique
+ * id / private registry for exactly this). Unique ids keep concurrent live
+ * sessions out of each other's way; `AgentRegistry.global().list()`
+ * consumers here filter `kind === "sub"`, so these roster entries never leak
+ * into the subagents surface.
+ */
+let nextAgentSeq = 0;
+function nextAgentId(): string {
+  return `omp-web-${process.pid}-${++nextAgentSeq}`;
+}
+
+function hold(session: HeldSession["session"]): string {
+  const handle = `h${++nextHandle}`;
+  const unsubscribe = session.subscribe((event: any) => {
+    send({ event: "session:event", sessionId: handle, payload: event });
+  });
+  sessions.set(handle, { session, unsubscribe });
+  return handle;
+}
+
+async function get(handle: string) {
+  const held = sessions.get(handle);
+  if (!held) throw new Error(`unknown session handle: ${handle}`);
+  return held.session;
+}
+
+function drop(handle: string): HeldSession | undefined {
+  const held = sessions.get(handle);
+  if (held) sessions.delete(handle);
+  return held;
+}
+
+async function createSession(params: any): Promise<string> {
+  const opts: Record<string, unknown> = {};
+  if (params?.cwd) opts.cwd = params.cwd;
+  if (params?.model) {
+    const found = modelRegistry.find?.(params.model);
+    if (found) opts.model = found;
+  }
+  if (params?.systemPrompt !== undefined) opts.systemPrompt = params.systemPrompt;
+  if (params?.appendSystemPrompt !== undefined) opts.appendSystemPrompt = params.appendSystemPrompt;
+  // approval parity with `omp --approval-mode`: yolo = fully auto-approved.
+  if (params?.approvalMode === "yolo") opts.autoApprove = true;
+  // omp SDK >= 18.1 made the SessionManager constructors async (they return
+  // promises); await keeps compatibility with the older sync surface too.
+  if (params?.resumeFile) opts.sessionManager = await SessionManager.open(params.resumeFile);
+  else if (params?.persistence === "file") opts.sessionManager = await SessionManager.create(params.cwd ?? process.cwd());
+  else opts.sessionManager = await SessionManager.inMemory();
+  opts.agentId = nextAgentId();
+
+  const { session } = await createAgentSession(opts as any);
+  return hold(session);
+}
+
+function describe(session: HeldSession["session"]) {
+  const model: any = session.model;
+  return {
+    sessionId: session.sessionId,
+    sessionFile: session.sessionFile ?? undefined,
+    model: model ? { id: model.id, provider: model.provider, name: model.name } : undefined,
+    thinkingLevel: String(session.thinkingLevel),
+    isStreaming: session.isStreaming,
+    messageCount: session.messages.length,
+  };
+}
+
+/** Normalize a SDK timestamp (Date | number | ISO string) to epoch ms. */
+function toEpochMs(value: unknown): number | undefined {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (typeof value === "string") {
+    const t = Date.parse(value);
+    return Number.isFinite(t) ? t : undefined;
+  }
+  return undefined;
+}
+
+// ---------- method implementations ----------
+
+type Handler = (params: any) => Promise<unknown>;
+
+const table: Record<string, Handler> = {
+  "sys.ping": async () => ({ pong: true, sdk: PKG_VERSION, bun: Bun.version }),
+
+  "models.list": async ({ refresh }: { refresh?: boolean }) => {
+    if (refresh) await modelRegistry.refresh();
+    const all = modelRegistry.getAvailable();
+    return {
+      models: all.map((m: any) => ({
+        provider: m.provider,
+        id: m.id,
+        name: m.name,
+        ...(m.api !== undefined ? { api: m.api } : {}),
+        ...(m.baseUrl !== undefined ? { baseUrl: m.baseUrl } : {}),
+        ...(typeof m.reasoning === "boolean" ? { reasoning: m.reasoning } : {}),
+        ...(Array.isArray(m.input) ? { input: m.input } : {}),
+        ...(typeof m.contextWindow === "number"
+          ? { contextWindow: m.contextWindow }
+          : typeof m.context_length === "number"
+            ? { contextWindow: m.context_length }
+            : {}),
+        ...(typeof m.maxTokens === "number" ? { maxTokens: m.maxTokens } : {}),
+        ...(m.thinking !== null && typeof m.thinking === "object"
+          ? {
+              thinking: {
+                ...(typeof m.thinking.mode === "string" ? { mode: m.thinking.mode } : {}),
+                ...(Array.isArray(m.thinking.efforts) ? { efforts: m.thinking.efforts } : {}),
+                ...(typeof m.thinking.defaultLevel === "string" ? { defaultLevel: m.thinking.defaultLevel } : {}),
+              },
+            }
+          : {}),
+      })),
+      providers: [...new Set(all.map((m: any) => m.provider))],
+    };
+  },
+
+  // ---- settings: modelRoles (A1) ----
+  //
+  // Read path reads FRESH on every call (Settings.loadReadOnly) rather than a
+  // sidecar-cached Settings instance: the OMP TUI is a separate process that
+  // rewrites config.yml when the operator changes the default model, and a
+  // long-lived sidecar's cached Settings instance would keep serving the stale
+  // in-memory value (the SDK does not watch config for a running session).
+  // modelRoles reads happen at the bridge's reconcile-tick cadence (~30s), so a
+  // fresh disk read per get is cheap and is the faithful equivalent of
+  // `omp config get modelRoles --json`.
+  "settings.modelRoles.get": async () => {
+    const s = await Settings.loadReadOnly();
+    return { modelRoles: s.getModelRoles() };
+  },
+
+  // Whole-object write, matching `omp config set modelRoles` (dotted keys are
+  // rejected; the entire modelRoles object is the unit). `set()` + `flush()`
+  // makes the write durable before we answer; the SDK re-reads config.yml under
+  // a file lock and writes atomically, preserving a concurrent edit to a sibling
+  // top-level key while modelRoles is replaced as a unit. A read-back confirms
+  // the write actually landed (the SDK silently skips a stale generation), so
+  // the bridge's shadow-key sync only advances on a real write.
+  "settings.modelRoles.set": async ({ modelRoles }: any) => {
+    if (modelRoles === null || typeof modelRoles !== "object" || Array.isArray(modelRoles)) {
+      throw new Error("settings.modelRoles.set: modelRoles must be a record");
+    }
+    const s = await getWritableSettings();
+    s.set("modelRoles", modelRoles as Record<string, string>);
+    await s.flush();
+    const fresh = await Settings.loadReadOnly();
+    const onDisk = fresh.getModelRoles();
+    return { ok: Bun.deepEquals(onDisk, modelRoles as Record<string, string>) };
+  },
+
+  "session.create": async (params) => {
+    const handle = await createSession(params);
+    return { handle, ...describe(await get(handle)) };
+  },
+
+  "session.dispose": async ({ handle }: any) => {
+    const held = drop(handle);
+    if (!held) return { disposed: true };
+    held.unsubscribe();
+    await held.session.dispose();
+    return { disposed: true };
+  },
+
+  // get_state parity
+  "session.state": async ({ handle }: any) => describe(await get(handle)),
+
+  // get_messages parity
+  "session.messages": async ({ handle }: any) => {
+    const session = await get(handle);
+    return { messages: session.messages };
+  },
+
+  // Render the held session's full base system prompt (live path). The prompt
+  // is lazy (a short placeholder until the first refresh), so force a rebuild
+  // and return the rendered blocks joined into one text.
+  "session.systemPrompt": async ({ handle }: any) => {
+    const session: any = await get(handle);
+    await session.refreshBaseSystemPrompt?.();
+    const blocks = session.systemPrompt ?? session.state?.systemPrompt ?? [];
+    const text = Array.isArray(blocks) ? blocks.join("\n\n") : String(blocks ?? "");
+    return { systemPrompt: text };
+  },
+
+  // get_session_stats parity (live sessions)
+  "session.stats": async ({ handle }: any) => {
+    const session: any = await get(handle);
+    try {
+      return (await session.getSessionStats?.()) ?? {};
+    } catch {
+      return {};
+    }
+  },
+
+  // /compact parity: run the SDK's own context compaction on the held
+  // session. The TUI's /compact awaits compact() then prints the
+  // context-usage delta, so this resolves only when it settles.
+  "session.compact": async ({ handle, instructions }: any) => {
+    const session: any = await get(handle);
+    const text = typeof instructions === "string" && instructions.trim() !== "" ? instructions.trim() : undefined;
+    await session.compact(text);
+    return { compacted: true };
+  },
+
+  // Context-usage snapshot (sync SDK getter) — pre/post compact metering.
+  "session.contextUsage": async ({ handle }: any) => {
+    const session: any = await get(handle);
+    const usage = session.getContextUsage?.();
+    return { usage: usage ?? undefined };
+  },
+
+  // get_subagents parity — SDK subagent registry exposure TBD; fail-soft.
+  // Subagent registry: enumerate the session's own subagents (kind === "sub"
+  // with parentId === this session's registry id). The sidecar's per-session
+  // registry would give a faithful tree; the global registry is the fallback.
+  "session.subagents": async ({ handle }: any) => {
+    const session: any = await get(handle);
+    const myId = session.getAgentId?.();
+    const subagents = AgentRegistry.global().list()
+      .filter((r: any) => r.kind === "sub" && (myId === undefined || r.parentId === myId))
+      .map((r: any) => ({
+        id: r.id, displayName: r.displayName, parentId: r.parentId, kind: r.kind,
+        status: r.status, sessionFile: r.sessionFile, cwd: r.session?.cwd,
+        createdAt: r.createdAt, lastActivity: r.lastActivity, activity: r.activity,
+      }));
+    return { subagents };
+  },
+
+  // Skills + slash commands from OMP's extensibility store (fail-soft).
+  "skills.list": async ({ cwd }: any) => {
+    try {
+      const { skills } = await discoverSkills(cwd);
+      return { skills: skills.map((s: any) => ({ name: s.name, description: s.description, filePath: s.filePath, baseDir: s.baseDir, source: s.source })) };
+    } catch {
+      return { skills: [] };
+    }
+  },
+
+  "slashCommands.list": async ({ cwd }: any) => {
+    try {
+      const commands = await discoverSlashCommands(cwd);
+      return { commands: commands.map((c: any) => ({ name: c.name, description: c.description, content: c.content, source: c.source })) };
+    } catch {
+      return { commands: [] };
+    }
+  },
+
+  "session.prompt": async ({ handle, text, streamingBehavior }: any) => {
+    const session = await get(handle);
+    // Fire-and-forget, mirroring RPC's prompt semantics: the response reports
+    // acceptance only; the turn itself streams through session:event frames.
+    // Turn-level failures arrive as events (`message_update` error / notice).
+    void Promise.resolve(
+      session.prompt(text, streamingBehavior ? { streamingBehavior } : undefined),
+    ).catch(() => {});
+    return { accepted: true };
+  },
+
+  "session.steer": async ({ handle, text }: any) => {
+    const session = await get(handle);
+    await session.steer(text);
+    return { accepted: true };
+  },
+
+  "session.followUp": async ({ handle, text }: any) => {
+    const session = await get(handle);
+    await session.followUp(text);
+    return { accepted: true };
+  },
+
+  "session.abort": async ({ handle }: any) => {
+    const session = await get(handle);
+    await session.abort();
+    return { accepted: true };
+  },
+
+  "session.setModel": async ({ handle, provider, modelId }: any) => {
+    const session = await get(handle);
+    const all = modelRegistry.getAvailable();
+    const target = all.find((m: any) => m.provider === provider && m.id === modelId);
+    if (!target) throw new Error(`model not available: ${provider}/${modelId}`);
+    await session.setModel(target as any);
+    return { accepted: true };
+  },
+
+  // new_session parity: replace the held AgentSession with a fresh one under
+  // the same handle. The old session is disposed after the swap.
+  "session.new": async ({ handle, cwd }: any) => {
+    const held = sessions.get(handle);
+    if (!held) throw new Error(`unknown session handle: ${handle}`);
+    const fresh = await createSession({ cwd: cwd ?? (held.session as any).cwd ?? process.cwd(), persistence: "file" });
+    // hold() minted a new handle for the fresh session; steal its entry.
+    const freshHeld = drop(fresh)!;
+    held.unsubscribe();
+    sessions.set(handle, freshHeld);
+    try { await held.session.dispose(); } catch {}
+    return describe(freshHeld.session);
+  },
+
+  "sessions.list": async ({ cwd, all }: any) => {
+    // `SessionManager.listAll` takes no cwd — it walks the whole sessions root,
+    // so the `all` branch must NOT pass the cwd through (the pre-P4 code did,
+    // which fed the string into the `storage` slot and returned an empty list).
+    const entries = all
+      ? await SessionManager.listAll()
+      : await SessionManager.list(cwd ?? process.cwd());
+    const arr = (entries as any[]) ?? [];
+    return {
+      sessions: arr.map((e: any) => ({
+        id: e.id ?? e.sessionId,
+        file: e.file ?? e.path,
+        title: e.title,
+        timestamp: e.timestamp,
+      })),
+    };
+  },
+
+  // A6 — full-library native session index: one listAll across every cwd group.
+  // Serialized as epoch ms so the Node side needs no Date/ISO ambiguity.
+  "sessions.listAll": async () => {
+    const arr = ((await SessionManager.listAll()) as any[]) ?? [];
+    return {
+      sessions: arr.map((e: any) => ({
+        id: e.id,
+        file: e.path ?? e.file,
+        ...(typeof e.cwd === "string" ? { cwd: e.cwd } : {}),
+        ...(typeof e.title === "string" && e.title !== "" ? { title: e.title } : {}),
+        ...(typeof e.firstMessage === "string" && e.firstMessage !== "" ? { firstMessage: e.firstMessage } : {}),
+        ...(e.created !== undefined ? { createdAt: toEpochMs(e.created) } : {}),
+        ...(e.modified !== undefined ? { mtimeMs: toEpochMs(e.modified) } : {}),
+        ...(typeof e.size === "number" ? { size: e.size } : {}),
+      })),
+    };
+  },
+
+  // A6 — read-only transcript extraction (resume/replay). Messages come from the
+  // SDK's canonical reader (migration + blob refs + compaction aware); model
+  // changes have no dedicated reader, so they are recovered from a lenient parse.
+  "sessions.messagesReadOnly": async ({ file }: any) => {
+    const messages = await loadSessionMessagesReadOnly(file);
+    let modelChanges: Array<{ model: string; role?: string }> = [];
+    try {
+      const content = await Bun.file(file).text();
+      const entries = parseSessionEntries(content);
+      modelChanges = entries
+        .filter((e: any) => e.type === "model_change" && typeof e.model === "string" && e.model !== "")
+        .map((e: any) => ({ model: e.model, ...(typeof e.role === "string" ? { role: e.role } : {}) }));
+    } catch {
+      // model changes are optional — messages alone still serve replay.
+    }
+    return { messages, modelChanges };
+  },
+};
+
+// ---------- inbound loop ----------
+
+const decoder = new TextDecoder();
+let buffer = "";
+process.stdin.on("data", (chunk: Uint8Array) => {
+  buffer += decoder.decode(chunk, { stream: true });
+  let nl: number;
+  while ((nl = buffer.indexOf("\n")) >= 0) {
+    const raw = buffer.slice(0, nl).trim();
+    buffer = buffer.slice(nl + 1);
+    if (!raw) continue;
+    void handleRaw(raw);
+  }
+});
+
+async function handleRaw(raw: string): Promise<void> {
+  let frame: any;
+  try {
+    frame = JSON.parse(raw);
+  } catch {
+    send({ id: -1, ok: false, error: `malformed frame: ${raw.slice(0, 120)}` });
+    return;
+  }
+  if (frame?.method && typeof frame.id === "number") {
+    const handler = table[frame.method];
+    if (!handler) {
+      send({ id: frame.id, ok: false, error: `unknown method: ${frame.method}` });
+      return;
+    }
+    try {
+      const result = await handler(frame.params ?? {});
+      send({ id: frame.id, ok: true, result });
+    } catch (err: any) {
+      send({ id: frame.id, ok: false, error: String(err?.message ?? err) });
+    }
+  }
+}
+
+process.stdin.on("end", () => {
+  void (async () => {
+    for (const [, held] of sessions) {
+      try {
+        held.unsubscribe();
+        await held.session.dispose();
+      } catch {}
+    }
+    process.exit(0);
+  })();
+});
+
+send({ event: "ready", payload: { protocol: PROTOCOL_VERSION, sdk: PKG_VERSION, sessions: 0 } });

package/agent-pi/README.md

@@ -0,0 +1,67 @@
+# @pgmi-builds/agent-adapter-pi (Agent Worlds AW-F)
+
+pi coding agent provider for DeepSeek Harness — an `AgentFactory` dsh plugin that embeds the
+**pi coding agent** (`@earendil-works/pi-coding-agent@0.84.2`) **in-process via its SDK**
+(`createAgentSession` / `AgentSession` / `ModelRuntime`) and bridges pi's session surface into
+the Dash Agent/Session contracts. Structure follows `agent-omp` (same pi-agent-core lineage);
+lifecycle follows `agent-codex` (AW-E SDK line, DSH-native session persistence).
+
+## Per-adapter rulings (2026-09-17 user; decisions recorded per dev-rules §4/§12)
+
+1. **Native data home `~/.pi`.** Unlike every prior adapter (codex `<dshHome>/agents/codex`,
+   omp `<dshHome>/agents/omp/.omp`), pi keeps its **native home**: the adapter passes no
+   `agentDir` override, so the SDK's `getAgentDir()` default applies — auth, models, settings,
+   skills, extensions and project trust are exactly what the user's pi CLI sees. No app-home
+   seeding, no config one-way-valve. Dev-rules §5/§13's app-home ruling is superseded for pi's
+   runtime data by this directive. Tests redirect via `PI_CODING_AGENT_DIR` /
+   `PI_CODING_AGENT_SESSION_DIR` env only.
+2. **`<dshHome>/agents/pi/` = adapter-owned DSH state only** — currently the mapping file
+   `dsh-sessions.json`. pi never reads it; it is DSH-side bookkeeping in the same class as the
+   DSH session log itself.
+3. **Session storage duplication accepted**: pi writes its native session JSONL under
+   `~/.pi/agent/sessions/<encoded-cwd>/`; the adapter writes the DSH log through upstream
+   `session-persistence-jsonl` (factory holds the write channel). The WebUI reads the DSH copy;
+   the native copy stays pi's authority; no back-read of pi transcripts for list/replay.
+4. **Session identity = "mapping only"** (codex model): the DSH session id is the authority;
+   the pi session file path is `null` in the map until the first prompt materializes it; resume
+   resolves through the map and **fails closed** when unknown. Lazy iron law: zero pi objects
+   before the first real prompt.
+5. **In-process SDK** (user choice "sdk, refer to omp agent adapter"): no sidecar, no
+   `--mode rpc` subprocess. Shared module-level `ModelRuntime`; one `AgentSession` per session.
+6. **Model route**: single provider id `pi` on `ctx.llm`; model ids are composite
+   `<provider>/<modelId>` (pi is multi-provider). Selection is live (`session.setModel`) — an
+   upgrade over the codex SDK line's next-turn-only switch. `steer` is also real (pi supports it).
+7. **Permission presets → launch-only toolsets** (pi has no per-action approval):
+   `danger-full-access` / `workspace-write` → pi default tools (`read,bash,edit,write`);
+   `read-only` → `read,grep,find,ls`. `/permission` is shadowed per-session with a clean
+   refusal; `PI_APPROVAL_MODE=<preset-name>` overrides for headless runs.
+8. **Compaction is wired** (unlike codex): `/compact` works via `session.compact()`;
+   pi `compaction_start|end` → DSH `compaction/start|end` with a generated `compactionId`.
+9. **Titles**: pi owns them — `session_info_changed` → DSH `session/title`
+   (`source: {kind:"provider", provider:"pi"}`); the dsh `session-title-llm` row stays disabled.
+
+## Layout
+
+`src/`: `index.ts` (PiProvider + `setupAndPublish` transaction), `agent.ts` (PiAgent shim),
+`pi-client.ts` (SDK client seam + lazy start), `pi-events.ts` (pi → wire vocabulary projection),
+`session-map.ts`, `models.ts` (ModelRuntime singleton + catalog memo), `adapter.ts` (LlmAdapter),
+`permission.ts`, `agent-preset-pi.ts` + `agent-preset-projection.ts` (roster/chip), `pi-home.ts`
+(state dir), `knobs.ts`, `inbox.ts`, `world-plugin.ts` (hub bridge).
+
+## Testing
+
+`npm run build` then `node --test test/*.test.mjs` — tests import `dist/`, use temp homes, and
+inject fake pi sessions via `setPiSessionFactory`; the SDK seam is never hit by unit tests.
+Acceptance = standalone `dsh + adapter` real instance (form A) with a real pi turn, then the
+world form (form B) via the hub.
+
+## Trap: `npm install` materializes the hub link
+
+`dependencies["file:../agent-hub"]` gets materialized by `npm install` as a
+**physical copy** under `node_modules/@pgmi-builds/agent-hub` — a second hub
+module instance whose rosters/mount-registry are dead. Symptom in world form:
+the world's virtual webServer never appears (`9 entries did not activate`,
+everything pending on webServer). After ANY `npm install` in this package,
+re-link: `rm -rf node_modules/@pgmi-builds/agent-hub && ln -sfn ../../../agent-hub
+node_modules/@pgmi-builds/agent-hub` (codex symlink discipline; same class as
+the `@deepseek-ai/*` heal).

package/agent-pi/cordis.patch.yml

@@ -0,0 +1,80 @@
+# @pgmi-builds/agent-adapter-pi bundle patch (AW-F SDK line, codex form).
+# This file is the `dsh.bundle.patch` layer of the adapter package: when the pi
+# world profile mounts the bundle, the boot merges THIS patch — mount the pi
+# provider plus disable the native components it replaces.
+#
+# Profile-specific values are deliberately NOT here: `webserver.port` (port
+# choice) belongs to the world/profile patch layer.
+#
+# Home ruling (2026-09-17 user): the pi runtime keeps its NATIVE data home
+# `~/.pi` (via the SDK's getAgentDir() default); this adapter seeds no app home
+# and never redirects PI_CODING_AGENT_DIR. `<DSH_HOME>/agents/pi/` holds only
+# adapter-owned DSH state (the dsh↔pi session mapping).
+
+# Mount the pi provider: a Cordis Service that registers an AgentFactory on
+# ctx.agents. The provider drives @earendil-works/pi-coding-agent AgentSessions
+# in-process (one PiSessionClient per session) plus resume via the recorded
+# native session file; the model selector is served by a Pi LlmAdapter reading
+# the shared ModelRuntime catalog (auth/models-store from ~/.pi).
+- insert:
+    - id: pi-provider
+      name: '@pgmi-builds/agent-adapter-pi'
+
+# pi owns the live agent transcript (its native session JSONL under
+# ~/.pi/agent/sessions); disable the built-in loop so it does not double-run
+# alongside the SDK session.
+- id: agent-loop
+  disabled: true
+
+# The native routes register deepseek-official / pi-ai providers; the pi
+# provider registers its own adapter (the single `pi` route) on ctx.llm.
+# Leaving them mounted would advertise native models alongside pi's.
+- id: llm-deepseek
+  disabled: true
+- id: llm-pi-ai
+  disabled: true
+
+# pi is single-mode: the SDK session drives tools itself, so no Dash preset
+# composition is needed (the provider ships the fixed single-preset roster).
+- id: agent-presets
+  disabled: true
+
+# The upstream jsonl persistence row STAYS MOUNTED: the provider writes the
+# DSH session log through it (create/open/append/close), so list/read/replay/
+# workspace grouping are ordinary DSH services over that log. Session storage
+# is duplicated by design (DSH copy for the WebUI, pi's native copy as the
+# runtime authority) — accepted 2026-09-17.
+
+# pi has no per-action approval channel — the adapter maps the Dash preset
+# onto a launch-only toolset (src/permission.ts). Default to
+# danger-full-access. Restate the full 3-preset table: a patch with only
+# defaultPreset silently drops the bundle's 3-preset table to the plugin's
+# built-in 2, breaking the 3:3 Dash<->pi pairing.
+- id: permission
+  config:
+    presets:
+      read-only:
+        sandbox: read-only
+        approval: ask
+      workspace-write:
+        sandbox: workspace-write
+        approval: ask
+      danger-full-access:
+        sandbox: danger-full-access
+        approval: never
+    defaultPreset: danger-full-access
+
+# Directory picker: the stock `directory-picker-auto` RESOLVES the interaction
+# once per boot and mounts BOTH faces through the loader: the host backend
+# package AND the matching CLIENT SURFACE package. The client surface occupies
+# the workspace picker's directory-flow hole; NEVER just `disabled: true` this
+# row — that removed the "add workspace" button (dev-rules §4.1). Pin the
+# in-app browser by mounting both faces of `browse` ourselves and unmounting
+# the auto row.
+- insert:
+    - id: directory-picker-browse
+      name: '@deepseek-ai/dsh-host-directory-picker-browse'
+    - id: directory-picker-browse-surface
+      name: '@deepseek-ai/dsh-client-ui-directory-picker-browse'
+- id: directory-picker
+  disabled: true

package/agent-pi/dist/adapter.js

@@ -0,0 +1,53 @@
+/**
+ * Pi-backed `LlmAdapter` registered on `ctx.llm` by the pi provider.
+ *
+ * The browser model selector never touches the pi agent directly: it is an
+ * RPC round-trip through the apiproxy, which reads `ctx.llm.listProviders /
+ * listModels / resolveModel` to build the catalog. This adapter answers those
+ * queries from the warmed catalog memo (`models.ts`: the shared ModelRuntime's
+ * available models). Like omp, it serves REAL per-provider routes: boot
+ * registers the single placeholder route `pi` and the provider swaps in the
+ * distinct catalog slugs (`piProviderIds` → `handle.replace`) once warm, so
+ * the picker groups models under DeepSeek/ZAI/… instead of one flat "Pi"
+ * group — never the native deepseek-official / pi-ai routes, which the
+ * profile disables.
+ *
+ * Model ids are the BARE provider-scoped id per route (omp parity: the
+ * composite `<provider>/<modelId>` prefix is dropped at the picker boundary;
+ * legacy composite selections are split upstream before they reach the
+ * runtime). `stream` is never dispatched: pi owns generation through its SDK
+ * session (`PiAgent`), so the adapter only serves catalog/metadata queries.
+ * It throws rather than fabricating a wire route the harness would misuse.
+ */
+import { LlmAdapter, LlmError, } from "@deepseek-ai/dsh-llm";
+import { PI_PROVIDER_ID, providerDisplayName, readPiModelCatalog } from "./models.js";
+export { PI_PROVIDER_ID };
+export class PiLlmAdapter extends LlmAdapter {
+    providerInfo(provider) {
+        return { id: provider, name: providerDisplayName(provider) };
+    }
+    async listModels(provider) {
+        return readPiModelCatalog()
+            .models.filter((model) => model.provider === provider)
+            .map((model) => ({
+            provider,
+            id: model.id,
+            name: model.label,
+        }));
+    }
+    stream(_options) {
+        throw new LlmError("the Pi adapter does not stream: pi owns generation through its SDK agent", "UNSUPPORTED_STREAM");
+    }
+    async resolveModel(provider, model) {
+        const found = readPiModelCatalog().models.find((candidate) => candidate.provider === provider && candidate.id === model);
+        if (found === undefined) {
+            throw new LlmError(`Pi provider "${provider}" does not serve model "${model}"`, "MODEL_NOT_FOUND");
+        }
+        return {
+            provider,
+            id: found.id,
+            name: found.label,
+            ...(found.contextWindow !== undefined && found.contextWindow > 0 ? { context: { contextWindow: found.contextWindow } } : {}),
+        };
+    }
+}