super-dsh 0.1.0 → 0.1.2

package/agent-hub/dist/world-web-server.js

@@ -0,0 +1,248 @@
+/**
+ * Per-world virtual webServer (AW-B DL3).
+ *
+ * A world's plugins must be able to declare ANY path they like (`/api`,
+ * `/plugins`, `/whatever-name-i-like`). Enumerating those namespaces in the
+ * carrier is wrong by construction — a third-party plugin may declare a new
+ * one at any time. So this class translates at REGISTRATION time:
+ *
+ *   world registers  { kind, path }        →  real registers { kind, `${labelPath}${path}` }
+ *   real receives    /<label>/<path>/...   →  plugin handler sees /<path>/...
+ *
+ * Consequences:
+ *  - any declared prefix lands under the label automatically; no list;
+ *  - two worlds may both own `/api` (they become `/omp/api`, `/codex/api`);
+ *  - ctx0 only ever sees the label namespaces, so a world cannot collide with
+ *    ctx0's own routes.
+ *
+ * Index rows stay world-local: this instance owns its taps and emits nothing
+ * on the shared tree (worlds run as their own cordis ROOTS, whose event buses
+ * are isolated — probe 2026-09-16: emit on root B never reaches root A).
+ */
+import { renderIndexInjections } from '@deepseek-ai/dsh-host-webserver';
+import { rewriteIndexHtml } from './index-pass.js';
+import { renderClientShim } from './client-shim.js';
+import { agentRosterRow } from './agent-roster.js';
+function translatePath(labelPath, path) {
+    if (typeof path !== 'string' || !path.startsWith('/')) {
+        throw new Error(`world-web-server: route path must start with "/", got ${JSON.stringify(path)}`);
+    }
+    return path === '/' ? labelPath : `${labelPath}${path}`;
+}
+/** Remove the mount label from `req.url`, preserving the trailing query. */
+export function stripLabelFromUrl(url, labelPath) {
+    const raw = typeof url === 'string' && url !== '' ? url : '/';
+    const queryAt = raw.indexOf('?');
+    const path = queryAt === -1 ? raw : raw.slice(0, queryAt);
+    const rest = queryAt === -1 ? '' : raw.slice(queryAt);
+    if (path === labelPath)
+        return `/${rest}`;
+    if (path.startsWith(`${labelPath}/`))
+        return `${path.slice(labelPath.length)}${rest}`;
+    return raw;
+}
+/** One world's web surface, mounted under `<labelPath>`. */
+export class WorldWebServer {
+    labelPath;
+    real;
+    options;
+    disposers = [];
+    taps = [];
+    /**
+     * @param labelPath - mount root, e.g. `/omp` (no trailing slash).
+     * @param real - the ctx0 webServer this world's routes forward into.
+     * @param options - world-local index row source.
+     */
+    constructor(labelPath, real, options = {}) {
+        this.labelPath = labelPath;
+        this.real = real;
+        this.options = options;
+        if (typeof labelPath !== 'string' || !labelPath.startsWith('/') || labelPath === '/' || labelPath.endsWith('/')) {
+            throw new Error(`world-web-server: labelPath must start with "/" and carry no trailing slash, got ${JSON.stringify(labelPath)}`);
+        }
+    }
+    /** The ctx0 listener port (read-through; the world owns no socket). */
+    get port() {
+        return this.real.port ?? 0;
+    }
+    /** The ctx0 bind host (read-through). */
+    get host() {
+        return this.real.host ?? '127.0.0.1';
+    }
+    /**
+     * The RPC channel belongs to the HUB, not to the world: the hub's carrier
+     * answers `/<label>/api/*` and `/<label>/api/remote.mux` with ctx0's auth
+     * domain, so the world's own connection/gateway registrations are swallowed
+     * here (returning a no-op disposer) instead of colliding on the real table.
+     * Non-envelope GET/HEAD traffic on `/<label>/api` still reaches the world's
+     * exact Fetch routes: `world-entry` publishes the world connection's shared
+     * `/api` fetch handler through `world-host`, and the carrier forwards into
+     * it AFTER ctx0's fence — the world's own browser-auth gate is never in the
+     * path (a different tree, a different secret).
+     */
+    static hubOwned(path) {
+        return path === '/api' || path.startsWith('/api/');
+    }
+    /**
+     * Mount-side authentication for one forwarded world route.
+     *
+     * The world's own browser-auth gate never sees a browser: it is reached
+     * in-ctx through this mount, and its cookie secret belongs to a different
+     * tree (every runtime is nested with its own home). So the decision is made
+     * here, with ctx0's connection: the same cookie that authenticated `<label>`
+     * in ctx0 authorizes its pages and assets.
+     */
+    gate(handler) {
+        return (req, ...rest) => {
+            const res = rest[0];
+            // false => the authorizer already answered (401, or token→cookie 303).
+            if (res !== undefined && this.options.authorize !== undefined
+                && !this.options.authorize(req, res))
+                return;
+            return handler(req, ...rest);
+        };
+    }
+    /** Register a world route; the real table stores its translated path. */
+    register(route) {
+        if (WorldWebServer.hubOwned(route.path))
+            return () => { };
+        return this.track(this.real.register({
+            kind: route.kind,
+            path: translatePath(this.labelPath, route.path),
+            handler: this.strip(this.gate(route.handler)),
+        }));
+    }
+    /** Register a world upgrade route (verbatim exact path; hub-owned RPC paths are swallowed). */
+    registerUpgrade(route) {
+        if (WorldWebServer.hubOwned(route.path))
+            return () => { };
+        return this.track(this.real.registerUpgrade({
+            path: translatePath(this.labelPath, route.path),
+            handler: this.strip(route.handler),
+        }));
+    }
+    /**
+     * Claim the world's SPA fallback: the ctx0 fallback seat is already owned by
+     * native frontend-static, so the world's fallback lives as a PREFIX route on
+     * the mount path (`/<label>`), which also keeps it inside the label namespace.
+     */
+    registerFallback(handler) {
+        // The world's index arrives HERE (its own frontend-static claims the
+        // fallback seat), so this is the route the mount must authenticate.
+        const gated = this.gate((req, ...rest) => handler(req, rest[0]));
+        return this.track(this.real.register({
+            kind: 'prefix',
+            path: this.labelPath,
+            handler: this.htmlRewrite(this.strip(gated)),
+        }));
+    }
+    /**
+     * Fix up HTML on its way out. Two passes belong here, in this order:
+     *
+     *   1. the world's own frontend-static injects `<base href="/">` AFTER
+     *      `renderIndex`, and the FIRST `<base>` wins in a document, so the mount
+     *      base is re-pinned on the bytes actually sent;
+     *   2. the agent roster is injected LAST — its values are the mount paths of
+     *      OTHER worlds (`/`, `/omp/`, `/codex/`), which the mount pass above
+     *      would otherwise re-root under this world's label.
+     */
+    htmlRewrite(handler) {
+        const labelPath = this.labelPath;
+        return (req, ...rest) => {
+            const res = rest[0];
+            const originalEnd = res?.end?.bind(res);
+            if (res !== undefined && originalEnd !== undefined) {
+                res.end = ((chunk, ...tail) => {
+                    if (typeof chunk === 'string' || Buffer.isBuffer(chunk)) {
+                        const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+                        if (/<head[\s>]/i.test(text) && /<base\b/i.test(text)) {
+                            const mounted = rewriteIndexHtml(text, labelPath);
+                            // A world that composes the hub row emits its own roster row during
+                            // renderIndex — i.e. BEFORE this mount pass, so its paths were
+                            // already re-rooted. Drop every earlier copy and inject the one
+                            // this pass has just built from unrewritten values.
+                            const stale = /<script>globalThis\["__DSH_AGENT_ROSTER__"\][^<]*<\/script>/g;
+                            const cleaned = mounted.replace(stale, '');
+                            return originalEnd(renderIndexInjections(cleaned, [agentRosterRow()]), ...tail);
+                        }
+                    }
+                    return originalEnd(chunk, ...tail);
+                });
+            }
+            return handler(req, ...rest);
+        };
+    }
+    /** World-local raw index transform (never forwarded to ctx0's taps). */
+    tapIndex(transform) {
+        this.taps.push(transform);
+        return () => {
+            const at = this.taps.indexOf(transform);
+            if (at !== -1)
+                this.taps.splice(at, 1);
+        };
+    }
+    /** Apply this world's taps in registration order. */
+    applyIndexTaps(html) {
+        let out = html;
+        for (const transform of this.taps)
+            out = transform(out);
+        return out;
+    }
+    /** Collect this world's structured rows (supplied by the world root). */
+    collectIndexInjections() {
+        const table = [];
+        this.options.onIndexInject?.(table);
+        return table;
+    }
+    /**
+     * Render the world's index: the client mount shim first (it must run before
+     * the app entry module), then the world's rows, then its taps, then the mount
+     * pass (base pinned at `/<label>/`, root-absolute strings re-rooted).
+     *
+     * The agent roster is injected LAST, after the mount pass: its values are
+     * mount paths of OTHER worlds (`/`, `/omp/`, `/codex/`), and the pass would
+     * happily re-root them under this world's label.
+     */
+    renderIndex(html) {
+        const rows = [
+            { kind: 'script', placement: 'head', text: renderClientShim(this.labelPath) },
+            // No hub-invented widget here: the world composes the hub's own client
+            // plugin (see worldMountPatches), so its selector IS the native one.
+            ...this.collectIndexInjections(),
+        ];
+        const rendered = this.applyIndexTaps(renderIndexInjections(html, rows));
+        // The roster rides the outbound pass (htmlRewrite), not this one: the mount
+        // rewrite above would re-root other worlds' paths under this label.
+        return rewriteIndexHtml(rendered, this.labelPath);
+    }
+    /** Unregister every translated route (world unloaded). */
+    dispose() {
+        for (const dispose of this.disposers.splice(0).reverse()) {
+            try {
+                dispose();
+            }
+            catch {
+                // release must never throw during teardown
+            }
+        }
+        this.taps.length = 0;
+    }
+    /** Wrap a plugin handler so it sees the world-relative URL. */
+    strip(handler) {
+        const labelPath = this.labelPath;
+        return (req, ...rest) => {
+            req.url = stripLabelFromUrl(req.url, labelPath);
+            return handler(req, ...rest);
+        };
+    }
+    track(dispose) {
+        const wrapped = () => {
+            const at = this.disposers.indexOf(wrapped);
+            if (at !== -1)
+                this.disposers.splice(at, 1);
+            dispose();
+        };
+        this.disposers.push(wrapped);
+        return wrapped;
+    }
+}

package/agent-hub/lib/client/index.js

@@ -0,0 +1,242 @@
+window.__ModuleLoader__.load({ id: "@pgmi-builds/agent-hub", factory: (require) => {
+var module = { exports: {} }; var exports = module.exports;
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let react = require("react");
+react = __toESM(react);
+let react_jsx_runtime = require("react/jsx-runtime");
+react_jsx_runtime = __toESM(react_jsx_runtime);
+
+//#region src/client/RuntimeSeat.tsx
+const NATIVE = {
+	key: "native",
+	label: "DSH",
+	path: "/"
+};
+/** Fallback labels for the read-only face (which only reports keys). */
+const RUNTIME_LABELS = {
+	native: "DSH",
+	omp: "OMP",
+	codex: "Codex"
+};
+function fromGlobal() {
+	const agents = globalThis.__DSH_AGENT_ROSTER__?.agents;
+	if (!Array.isArray(agents)) return void 0;
+	const links = [];
+	for (const entry of agents) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const { key, label, path } = entry;
+		if (typeof key !== "string" || typeof path !== "string") continue;
+		links.push({
+			key,
+			label: typeof label === "string" ? label : RUNTIME_LABELS[key] ?? key,
+			path
+		});
+	}
+	return links.length > 0 ? links : void 0;
+}
+/** Normalize the current mount root: `/omp` and `/omp/` are the same page. */
+function currentPath() {
+	const pathname = typeof location === "undefined" ? "/" : location.pathname;
+	if (pathname === "" || pathname === "/") return "/";
+	return pathname.endsWith("/") ? pathname : `${pathname}/`;
+}
+function RuntimeSeat({ wide }) {
+	const [agents, setAgents] = react.useState(() => fromGlobal() ?? [NATIVE]);
+	const [open, setOpen] = react.useState(false);
+	const rootRef = react.useRef(null);
+	react.useEffect(() => {
+		let cancelled = false;
+		fetch("/api/agent-runtime", { credentials: "same-origin" }).then((r) => r.ok ? r.json() : Promise.reject(/* @__PURE__ */ new Error(`HTTP ${r.status}`))).then((j) => {
+			if (cancelled) return;
+			if (Array.isArray(j?.agents)) {
+				const listed = [];
+				for (const entry of j.agents) {
+					if (typeof entry !== "object" || entry === null) continue;
+					const { key, label, path } = entry;
+					if (typeof key !== "string" || typeof path !== "string") continue;
+					listed.push({
+						key,
+						label: typeof label === "string" ? label : RUNTIME_LABELS[key] ?? key,
+						path
+					});
+				}
+				if (listed.length > 0) {
+					setAgents(listed);
+					return;
+				}
+			}
+			if (!Array.isArray(j?.available)) return;
+			const links = [];
+			for (const key of j.available) {
+				if (typeof key !== "string") continue;
+				links.push(key === "native" ? NATIVE : {
+					key,
+					label: RUNTIME_LABELS[key] ?? key,
+					path: `/${key}/`
+				});
+			}
+			if (links.length > 0) setAgents(links);
+		}).catch(() => {});
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+	react.useEffect(() => {
+		if (!open) return;
+		const onDown = (event) => {
+			if (rootRef.current !== null && !rootRef.current.contains(event.target)) setOpen(false);
+		};
+		document.addEventListener("mousedown", onDown);
+		return () => document.removeEventListener("mousedown", onDown);
+	}, [open]);
+	const here = currentPath();
+	const active = agents.find((agent) => agent.path === here) ?? NATIVE;
+	const styleBase = {
+		display: "flex",
+		alignItems: "center",
+		gap: 8,
+		width: "100%",
+		padding: wide ? "7px 10px" : "7px 0",
+		justifyContent: wide ? "flex-start" : "center",
+		border: "none",
+		borderRadius: 8,
+		background: "transparent",
+		color: "inherit",
+		font: "inherit",
+		fontSize: 13,
+		cursor: "pointer",
+		position: "relative"
+	};
+	const styleBadge = {
+		fontSize: 10,
+		lineHeight: 1.4,
+		padding: "1px 6px",
+		borderRadius: 999,
+		background: "color-mix(in srgb, currentColor 12%, transparent)",
+		whiteSpace: "nowrap"
+	};
+	const styleMenu = {
+		position: "absolute",
+		bottom: "calc(100% + 6px)",
+		left: 6,
+		right: 6,
+		zIndex: 40,
+		background: "var(--dsh-surface, #26262b)",
+		border: "1px solid color-mix(in srgb, currentColor 18%, transparent)",
+		borderRadius: 10,
+		boxShadow: "0 8px 24px rgba(0,0,0,.35)",
+		overflow: "hidden"
+	};
+	const styleItem = (isActive) => ({
+		display: "block",
+		width: "100%",
+		padding: "8px 12px",
+		border: "none",
+		background: isActive ? "color-mix(in srgb, currentColor 10%, transparent)" : "transparent",
+		color: "inherit",
+		font: "inherit",
+		fontSize: 13,
+		textAlign: "left",
+		cursor: "pointer"
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		ref: rootRef,
+		style: {
+			position: "relative",
+			width: "100%"
+		},
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+			type: "button",
+			style: styleBase,
+			title: "Agent runtime — picking one opens that runtime's mount (/omp/, /codex/, …)",
+			onClick: () => {
+				setOpen((v) => !v);
+			},
+			children: wide ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					"aria-hidden": true,
+					children: "⌘"
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+					style: {
+						flex: 1,
+						textAlign: "left",
+						whiteSpace: "nowrap",
+						overflow: "hidden",
+						textOverflow: "ellipsis"
+					},
+					children: ["Agent · ", active.label]
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					style: styleBadge,
+					children: "open"
+				})
+			] }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				"aria-hidden": true,
+				children: "⌘"
+			})
+		}), open && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			style: styleMenu,
+			children: agents.map((agent) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+				href: agent.path,
+				style: {
+					...styleItem(agent.path === here),
+					textDecoration: "none"
+				},
+				"aria-current": agent.path === here ? "page" : void 0,
+				onClick: () => {
+					setOpen(false);
+				},
+				children: agent.path === here ? `${agent.label} ✓` : agent.label
+			}, agent.key))
+		})]
+	});
+}
+
+//#endregion
+//#region src/client/index.ts
+/** Required services (cordis fiber inject): the slot registry. */
+const inject = ["slots"];
+/**
+* Mount the selector. Degrades silently when the slot service is absent (a
+* composition without the sidebar renders nothing — a footer action is an
+* optional occupant by contract).
+*
+* @param ctx - client root context.
+*/
+function apply(ctx) {
+	ctx.inject(["slots"], (raw) => {
+		const scope = raw;
+		scope.effect(() => scope.slots.inject("sidebar.footer.action", () => scope.slots.register({
+			name: "sidebar.footer.action",
+			id: "agent-runtime"
+		}, RuntimeSeat)), "agent-hub: runtime footer action");
+	});
+}
+
+//#endregion
+exports.apply = apply;
+exports.inject = inject;
+return module.exports; } });

package/agent-hub/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@pgmi-builds/agent-hub",
+  "version": "0.1.0",
+  "description": "Agent Worlds hub host half: world inventory control plane, roster, world spawner and the single-origin per-world mount carrier (no server-side selection; the addressed world is the request's mount path)",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./lib/client/index.js",
+    "./world": "./dist/world-entry.js",
+    "./join": "./dist/world-join.js"
+  },
+  "files": [
+    "dist",
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "build-client": "node scripts/build-client.mjs",
+    "test": "node --test --test-force-exit test/*.test.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.21.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-api-gateway": "*",
+    "@deepseek-ai/dsh-host-webserver": "*",
+    "@deepseek-ai/dsh-typert-protocol": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-api-gateway": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-typert-protocol": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "tsdown": "^0.15.12",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/agent-omp/README.md

@@ -0,0 +1,77 @@
+# omp-web（新线，0.0.1-alpha.0）
+
+OMP Web 的 SDK 线：**衔接层（DSH 契约/术语/类形状）沿用 `apps/omp-web` 现行源码，内核从 `omp --mode rpc` 子进程换成 `@oh-my-pi/pi-coding-agent` SDK**。数据面目标 = `docs/plans/sdk-data-surface-assessment.md` 的 A1–A8 / S1–S10。
+
+## 集成形态（承 sdk-direction §3 裁决 (a)）
+
+```
+dsh 宿主 (Node 22, 本包 dist/)            Bun sidecar (本包 sidecar/)
+  omp-web 衔接层（agent/adapter/      ←→     createAgentSession / ModelRegistry /
+  replay/store/supervisor 移植）            Settings / SessionManager / discover*
+```
+
+- dsh 进程树保持纯 Node；SDK 只活在 sidecar 进程（bun run）。
+- 协议不再是 omp 的 rpc 面，而是**自有 sidecar 协议**：在数据流等价（prompt/steer/followUp/abort/事件流）之上，新增 app 层命令（settings 读写、auth/provider 状态、模型注册表、session list/open/fork、system prompt、custom message / messages 手术、compact）——即把 A/S 清单映射成方法表。
+
+## Spike 实测记录（2026-09-09，SDK 18.1.14 + bun 1.4.2）
+
+- 安装：`npm i @oh-my-pi/pi-coding-agent`（main 直指 `./src/index.ts`，无需构建步骤）+ devDep `bun`（node_modules 内二进制，不装全局）。
+- 根 exports 619 个。桥关心的全部在位：`createAgentSession` `AgentSession` `SessionManager(.create/.open/.continueRecent/.inMemory/.list/.listAll/.forkFrom)` `Settings(.init/.isolated/.loadReadOnly)` `ModelRegistry` `AuthStorage` `discoverAuthStorage` `AgentRegistry` `createSessionManager` `listSessions` `listAllSessions` `loadSessionMessagesReadOnly` `discoverSkills/SlashCommands/Extensions/ContextFiles/PromptTemplates` `buildSystemPrompt` `createCustomMessage` `wrapSteeringForModel` `expandPromptTemplate`。
+- **pi 文档 vs omp 实现**：`createAgentSessionRuntime`/`ModelRuntime`/`DefaultResourceLoader`/`SettingsManager`/`defineTool`/`createEventBus` 不在 omp 根 exports——对应能力由 `AgentSession` 实例面与 `Settings`/`discover*` 家族承担。评估文档中标 [pi] 的条目按此折算。
+- **`AgentSession` 实例面远超 pi 文档**：`state{systemPrompt,model,thinkingLevel,tools,messages,isStreaming,streamMessage,pendingToolCalls,error}`、`messages`、`systemPrompt`、`prompt`/`promptCustomMessage`/`sendCustomMessage`/`sendUserMessage`、`steer`/`followUp`、`setModel`/`cycleModel`/`applyRoleModel`、`compact`/`abortCompaction`、`switchSession`/`branch`/`navigateTree`/`fork`/`handoff`、`newSession`/`moveSession`、`abort`、`beginDispose`/`dispose`。S1/S2/S3/S6/S7/S8/S10 均有一等 API；S5（messages 手术）通道结构性在位（`state` 暴露 messages/tools 键），赋值语义待 TS 类型面确认。
+- **真机冒烟**：`OMP_HOME=~/.omp` 下 `discoverAuthStorage`+`ModelRegistry.refresh()` 得 50 模型 / 5 provider（deepseek,xai,bailian,kimi-plan,zai-plan）——与 `omp models --json` 完全一致；`SessionManager.inMemory()` 建会话成功、dispose 干净、零 LLM 调用。
+- **沙箱注意**：SDK 以读写模式打开 `~/.omp/agent/agent.db`；agent 沙箱内跑 sidecar/spike 需要对该库的写权限（本轮以 danger-full-access 实测通过）。
+
+## 下一步（M2 → M3 收敛）
+
+1. sidecar 骨架：bun 入口 + 方法表协议（JSON lines over stdio）+ 生命周期（spawn/健康检查/退出）。
+2. 移植衔接层：从 `apps/omp-web/src` 拷 `agent.ts`/`adapter.ts`/`replay.ts`/`session-persistence-omp.ts`/`store/`，把 `rpc.ts` 调用点逐个改打 sidecar 协议；`omp-cli.ts` 的 models/config 面改走 SDK（A1/A3）。
+3. S5 spike：`state.messages` 注入 toolResult + 真 turn 验证 journal 落盘。
+4. 会话所有权对齐：SDK 写 OMP session store 后与 bridge-store/supervisor/TUI 的三方避让（dev_0.0.3 §9 过一遍）。
+
+## As-built：sidecar 骨架（2026-09-09，已完成 ✅）
+
+- `sidecar/main.ts`（bun 入口）：ready 握手 + JSON-lines 请求/响应/事件三帧协议；app 级共享单例 `authStorage`/`modelRegistry`；session 池（create/dispose/事件转发）。
+- `src/protocol.ts`：协议与方法表类型（sys.ping / models.list / settings.get / session.create|info|prompt|steer|followUp|abort|dispose / sessions.list）。
+- `src/sidecar-client.ts`：Node 侧 spawn/关联/事件分发/优雅关停；`src/index.ts` 暂导出 client。
+- 冒烟 `test/sidecar-smoke.test.mjs`：ready 0.9s，全链路（ping→50 模型→session create/info/dispose→sessions.list）2.4s，`npm test` 1.8s 绿。
+- 坑已修：`ModelRegistry.refreshInBackground()` 此版本返回 void（非 Promise），可选链后接 `.catch` 会炸；ready-timeout 定时器必须 clear 否则 Node 进程挂 60s。
+
+## As-built：衔接层移植（2026-09-09，已完成 ✅）
+
+- `src/rpc-types.ts`：从 omp-web `rpc.ts` 提取的 OMP wire 类型（verbatim），两条线共用同一载荷形状。
+- `src/sdk-client.ts`：**`OmpSdkClient`——与 `OmpRpcClient` 同公共面**（on/onFailure/sendRaw/send/getState/getMessages/getSessionStats/getSubagents/prompt/followUp/steer/setModel/abort/newSession/close），底层复用单个共享 sidecar（模块级单例 + 引用计数，refcount 归零自动关停）。spawn args 解析 `--approval-mode`（yolo→autoApprove）与 `--resume`；未知 flag fail-loud。
+- 衔接层整体移植（与 omp-web 逐字节同源，仅换接缝）：`agent.ts` `adapter.ts` `index.ts` `models.ts` `knobs.ts` `pairing.ts` `permission.ts` `replay.ts` `session-persistence-omp.ts` `supervisor.ts` `omp-store.ts` `agent-preset-omp.ts` `omp-cli.ts` `store/`。
+- sidecar 升级：session handle 化（`newSession` 换 OMP session id 但 handle 稳定）；补齐 `session.state/messages/stats/subagents/setModel/new`；`getSessionStats` 实测返回 contextUsage（contextWindow 1000000）。
+- 测试：omp-web 单测四件（content-detection/omp-store/replay/store）+ sidecar 冒烟 + sdk-client 集成 = **20/20 绿，3.6s**；tsc 0 错。
+- 本地 dev fixture：`node_modules/@deepseek-ai/*` symlink 至真实 dsh 安装（照 omp-web 惯例，node_modules 不入库）。
+
+### 已知差异（SDK 线 vs RPC 线，待办）
+
+- `extension_ui_response`（审批卡应答）在 SDK 线暂为 no-op：SDK 侧审批走 `autoApprove`/approval 事件，卡片化审批的等价通道待接。
+- `getSubagents` 暂返回 `[]`（SDK 的 subagent registry 暴露面待查）。
+- 未跑 4999 全链路（dsh 宿主内 provider 挂载）——下一步。
+
+## As-built：4999 全链路冒烟（2026-09-09，PASS ✅）
+
+- test profile `omp-web-test` 切换 dep 至 `link:…/apps/omp-web`（bundle 位同步换 `@pgmi-builds/omp-web`，patch 语义同 omp-web：mount omp-provider + 禁 agent-loop/llm 路由/agent-presets）。
+- systemd-run `omp-web-4999-test`（DSH_HOME=~/.omp/omp-web、OMP_HOME=~/.omp、port 4999）拉起全局 dsh 0.1.3-alpha.2，unit active。
+- 验证链：auth 200 → `session/create` ok → **dsh 进程树内 1 个共享 bun sidecar** → `session/prompt`（mode:queue + requestId，typert request 形状）accepted → `session/page`（`records[].event`，`throughSeq ≤ cursor`）回读：turn/start、user/message、2×step（reasoning + `think` 工具调用 + tool/result）、assistant/message（text "sdk-line-alive"，xai/grok-4.6，含 stream chunks）、turn/end。
+- wire 备忘：`session/prompt` 必填 `requestId`/`mode`/`content`；`session/page` 用 `args.request`（非 `_request`），`address:{kind:"session",sessionId}` + `throughSeq` 超 cursor 直接报错并回吐当前 cursor。
+
+## As-built：四阶段增强（2026-09-09，全部 doer(v4-pro)+verify 双签 PASS ✅）
+
+- **P1 `7e44412`** preset 槽位：桥自供 `agentPresets` typert remote（服务 key==wire namespace==ctx.remote.agentPresets），roster 恰一条 `omp`/`OMP`/isDefault；copy/delete 报 `agent-preset/read-only`，未知 id 报 `not-found`。关键：注册必须挂顶层 fiber（嵌套 ctx.plugin 会 404）。4999 wire 实测单条 OMP 行。
+- **P2 `fee6406`** system prompt → UI：`request/header.data.header.system`（EpochHeader.system）即 UI System-prompt 行的数据源。sidecar 加 `session.systemPrompt`（live，refreshBaseSystemPrompt 后 38807 字符）与 `session.systemPrompt.forFile`（冷会话 throwaway 渲染，dispose 前 releaseRetainedEntries 抑制 session_exit 落盘，实测只读）。replay/cold-shadow/open 注入；live turn 不合成 header（无 per-turn 成本）。已知 gap：live 会话要到 replay 路径才显示 System prompt 行。
+- **P3 `8e9f21d`** settings/models 切 sidecar：`settings.modelRoles.get/set`（set 带 flush→loadReadOnly→deepEquals 读回校验，shadow-key 只在真实落盘后推进；echo roundtrip 实测 config.yml SHA 不变）+ 富化 `models.list`（12 键与 normalizeModel 逐一对照）。omp-cli 四导出改缓存+异步暖缓存语义，Sync 变体冷启动 undefined→on-disk 回退。4999 实测 modelCatalog 5 provider 全量。
+- **P3.1 `e4db900`** EPIPE 加固（verify 发现的历史崩溃）：child stdin 永久 no-op error sink + `#writeSafe` per-write 降级——sidecar 死亡从崩宿主变为拒绝当次调用。
+- **P4 `97cbc7b`** JSONL 解析切 SDK：`sessions.listAll` 一次全库索引（147 会话 26ms；id/cwd/size 0 diff，20 处 title 差异经实证为 SDK 当前 title slot 更正确）+ `sessions.messagesReadOnly` 按需 transcript（compaction 折叠语义）；自研解析保留为 fail-soft fallback；顺带修了 `sessions.list {all:true}` 恒 0 的旧 bug。supervisor 热路径保留 naive 防游标错位。
+- 总验收：29/29 测试、4999 wire 三连（roster 单条 OMP / session list 147 / modelCatalog）、实例留 4999 供手动验收。
+- 遗留（低）：forFile 对个别大文件 "Agent Main was replaced"（~1/tick，fail-soft）；SDK 元数据快照滞后一个 tick；`sessions.messagesReadOnly` 大文件双读。
+
+## As-built：P1.1 修复 + P5 mobile 包（2026-09-09）
+
+- **P1.1 `434f046`**（"no omp mode" 根因修复）：P1 的 roster 服务 200 但 chip 仍不显示——UI 的 preset chip 门控在 `session.projectionValues.agentPreset` 上，该投影原本由（被我们禁用的）dsh-agent-presets 宿主半驱动。桥现在自己注册同一 fold（`ctx.inject(['sessionProjections'])` + `agent-preset/selected` 事件推进），headless 截图确认 hero 行渲染 `OMP ˅` chip。配套 vendored `dsh-session-projection` 类型（父 repo）。
+- **P5 `29b043b`**（dashr mobile 包移植，本插件首个 client 半）：`src/mobile/`（gesture/zoom-guard/client）+ `src/client/index.ts` 入口 + `scripts/build-client.ts`（tsdown 闭包工厂 → `lib/client/index.js`，id=包名）+ host 半 `src/mobile-boot.ts`（`window.__OMP_WEB_MOBILE__` + iOS zoom-guard 经 webserver/index-inject）。`dsh.client` manifest inject 只挂 ui-layout。测试 41/41。
+- **P5 视觉验证**（5199 实测，4999 当时被 superd 的 ui-preact 实例占用）：桌面回归 OK（OMP chip 在）；390x844 断点折叠（rail→0px、无横向滚动）；全局注入 OK；边缘滑动手势开关侧栏实测通过；截图证据 `.scratch/p5-verify/`。
+- 遗留：移动端侧栏为 push-drawer 语义（打开时内容窗格被压窄，与 dashr 原行为一致）；`npm install` 会剪掉 `node_modules/@deepseek-ai` symlink（需重挂）；4999 端口与 superd 测试线冲突时用 `--patch` overlay 换端口。