dsh-bridge 0.1.0-rc.10

package/README.md

@@ -0,0 +1,68 @@
+# dsh-bridge
+
+> Local, cross-session messaging for DeepSeek Harness.
+
+**DSH Bridge** is the local messaging foundation of the DSH family. It lets live
+sessions in one DSH host discover one another and exchange messages. It has no
+Web UI and no network transport.
+
+`dsh-weave` can extend Bridge across machines; `dsh-chat` can present its
+messages as a human-facing group chat. Neither is required for local use.
+
+The plugin exposes the `ctx.dshBridge` service and registers `session_list`,
+`session_send`, and `session_messages` for agents. The old `ctx.sessionMessaging`
+accessor remains as a temporary compatibility alias.
+
+`ctx.dshBridge.deliverExternal()` is the controlled inbound seam for a trusted
+transport such as Weave: it emits the same session follow-up and audit record
+as local delivery, rather than letting a transport manipulate agents directly.
+Delivery uses the public `ctx.agents` registry and `Agent.followup()`. An idle
+target is woken, a running target receives ordinary queued work, and a persisted
+offline target is resumed through DSH's configured Host agent resolver before
+delivery. Concurrent messages to the same cold session share one resume operation.
+The resolver reconstructs the recorded agent preset and model selection exactly
+as the Web host does. A bounded
+in-memory recent log (the latest 1,000 delivered messages) is kept only for
+`session_messages` replay and diagnostics; it is not a second delivery queue.
+Messages carry sender, target, UUID, and timestamp metadata.
+
+`ctx.dshBridge.status(sessionId)` reports a session's presentation state:
+`waking` while a cold resume is in flight, `archived` when the id is in the
+workspace registry's archive set, `idle`/`running` for live agents, `offline`
+for persisted sessions, and `missing` otherwise. Archive takes precedence over
+live presence: archiving a session hides it from live surfaces (such as
+dsh-chat room member indicators) without stopping its agent. Delivery to an
+archived session is rejected: `session_send` and `deliverExternal` refuse to
+wake or reach an archived target, so an archived agent stops receiving messages
+entirely rather than merely dropping off live surfaces.
+
+This package intentionally does not implement cross-host transport. `dsh-weave`
+will provide the authenticated network backend while preserving the local
+message semantics.
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-bridge@next
+```
+
+## Known Limitations and Deferred Work
+
+- **Process boundary** — sessions in another process or host are not visible;
+  add an authenticated relay/backend before advertising cross-host delivery.
+- **In-memory retention** — messages are lost when the plugin process exits and
+  older than the latest 1,000 are evicted; durable inbox/outbox persistence is
+  still deferred until a cross-process relay needs it.
+- **Delivery acknowledgement** — the current result means the target was live
+  (or successfully resumed) and accepted the follow-up call, not that the target
+  model processed it.
+
+## Model Experience
+
+None, as `session_list`, `session_send`, and `session_messages` expose their
+schemas directly through the tool registry.
+
+### KV Cache effect
+
+Independent tool schemas; sending a message changes only the target session's
+queued input and does not alter the sender's cached prompt prefix.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-bridge
+      name: dsh-bridge

package/lib/index.js

@@ -0,0 +1,240 @@
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+const name = "dsh-bridge";
+const inject = ["agents", "tools", "sessionPersistence", "workspaceRegistry", "typert"];
+const MAX_RECENT_MESSAGES = 1000;
+class LocalSessionMessagingImpl {
+	ctx;
+	messages = [];
+	listeners = /* @__PURE__ */ new Set();
+	resuming = /* @__PURE__ */ new Map();
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	list() {
+		return [...this.ctx.agents.list()].map((agent) => agent.session.id);
+	}
+	async status(sessionId) {
+		const id = String(sessionId);
+		if (this.resuming.has(id)) return { sessionId: id, state: "waking", live: false };
+		// Archive is a durable hide flag: it masks live presence so an archived
+		// session never advertises as running/idle, even while its agent keeps
+		// working in the background.
+		if (new Set(this.ctx.workspaceRegistry?.archivedSessionIds ?? []).has(id)) return { sessionId: id, state: "archived", live: false };
+		const live = this.ctx.agents.get(sessionId);
+		if (live) return { sessionId: id, state: live.status, live: true };
+		const headers = await this.ctx.sessionPersistence.list();
+		return { sessionId: id, state: headers.some((header) => String(header.id) === id) ? "offline" : "missing", live: false };
+	}
+	async target(to) {
+		const id = String(to);
+		// Archive is a durable hide flag: an archived session never receives
+		// delivery, whether its agent is still live or only persisted on disk.
+		if (new Set(this.ctx.workspaceRegistry?.archivedSessionIds ?? []).has(id)) {
+			throw new Error(`session "${id}" is archived and cannot receive messages`);
+		}
+		const live = this.ctx.agents.get(to);
+		if (live) return live;
+		let pending = this.resuming.get(id);
+		if (!pending) {
+			pending = (async () => {
+				const provider = this.ctx.typert.lookups.get("agent");
+				if (!provider) throw new Error("DSH host agent resolver is unavailable");
+				const resolved = await provider.resolve(to);
+				if (!resolved) throw new Error(`session "${id}" could not be resumed`);
+				return resolved;
+			})().then((agent) => {
+				return agent;
+			}).catch((error) => {
+				const raced = this.ctx.agents.get(to);
+				if (raced) return raced;
+				throw error;
+			}).finally(() => this.resuming.delete(id));
+			this.resuming.set(id, pending);
+		}
+		return pending;
+	}
+	async deliver({ id = crypto.randomUUID(), from, to, text, transport = "local" }) {
+		const target = await this.target(to);
+		const message = {
+			id,
+			from: String(from),
+			to,
+			text,
+			createdAt: Date.now(),
+			delivered: true,
+			transport
+		};
+		target.followup(createUserMessage({
+			content: [{
+				type: "text",
+				text: `[dsh-bridge ${transport} message ${id} from ${message.from}]\n${text}`
+			}],
+			source: {
+				kind: "plugin",
+				plugin: name,
+				form: transport
+			}
+		}));
+		this.messages.push(message);
+		if (this.messages.length > MAX_RECENT_MESSAGES) {
+			this.messages.splice(0, this.messages.length - MAX_RECENT_MESSAGES);
+		}
+		for (const listener of this.listeners) listener(message);
+		return {
+			messageId: id,
+			from: message.from,
+			to: String(to),
+			delivered: true
+		};
+	}
+	async send(from, to, text) {
+		return this.deliver({ from: from.session.id, to, text });
+	}
+	async deliverExternal(from, to, text, options = {}) {
+		return this.deliver({
+			id: options.id,
+			from,
+			to,
+			text,
+			transport: options.transport ?? "external"
+		});
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	receive(sessionId, limit) {
+		return this.messages.filter((message) => message.to === sessionId).slice(-limit);
+	}
+};
+function apply(ctx) {
+	const messaging = new LocalSessionMessagingImpl(ctx);
+	// `dshBridge` is the public service name. Keep the old accessor for one
+	// release so an early local installation does not break on upgrade.
+	ctx.accessor("dshBridge", { get: () => messaging });
+	ctx.accessor("sessionMessaging", { get: () => messaging });
+	ctx.tools.register(defineTool({
+		name: "session_list",
+		description: "List live DeepSeek Harness sessions in this process. Each returned session is idle or running and can be messaged immediately.",
+		parameters: {},
+		output: {
+			schema: {
+				type: "array",
+				items: { type: "string" }
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.join("\n") || "No live sessions."
+			}]
+		},
+		async execute() {
+			return messaging.list().map(String);
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "session_send",
+		description: "Send a message to another DeepSeek Harness session in this host. A persisted offline session is resumed before delivery.",
+		parameters: {
+			to: {
+				type: "string",
+				required: true,
+				description: "Target session id from session_list."
+			},
+			text: {
+				type: "string",
+				required: true,
+				description: "Message text."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					messageId: {
+						type: "string",
+						required: true
+					},
+					from: {
+						type: "string",
+						required: true
+					},
+					to: {
+						type: "string",
+						required: true
+					},
+					delivered: {
+						type: "boolean",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `Delivered ${value.messageId} to ${value.to}.`
+			}]
+		},
+		async execute(args, exec) {
+			if (!exec.agent) throw new Error("session_send requires an owning agent");
+			if (args.text.trim() === "") throw new Error("text must not be empty");
+			return await messaging.send(exec.agent, SessionId(args.to), args.text);
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "session_messages",
+		description: "Read messages delivered to the current session in this process.",
+		parameters: { limit: {
+			type: "number",
+			description: "Maximum number of messages, default 20."
+		} },
+		output: {
+			schema: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						id: {
+							type: "string",
+							required: true
+						},
+						from: {
+							type: "string",
+							required: true
+						},
+						to: {
+							type: "string",
+							required: true
+						},
+						text: {
+							type: "string",
+							required: true
+						},
+						createdAt: {
+							type: "number",
+							required: true
+						},
+						delivered: {
+							type: "boolean",
+							required: true
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.map((message) => `[${message.from}] ${message.text}`).join("\n") || "No messages."
+			}]
+		},
+		async execute(args, exec) {
+			if (!exec.agent) throw new Error("session_messages requires an owning agent");
+			const limit = args.limit === void 0 ? 20 : Math.max(1, Math.min(100, Math.floor(args.limit)));
+			return [...messaging.receive(exec.agent.session.id, limit)];
+		}
+	}));
+}
+//#endregion
+export { LocalSessionMessagingImpl, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Same-process session-to-session messaging.
+ *
+ * The transport is deliberately process-local. A future relay can implement
+ * the same interface without changing the model-facing tools.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type SessionId as SessionIdValue } from '@deepseek-ai/dsh-session';
+export declare const name = "dsh-bridge";
+export declare const inject: string[];
+export interface LocalMessage {
+    readonly id: string;
+    readonly from: string;
+    readonly to: SessionIdValue;
+    readonly text: string;
+    readonly createdAt: number;
+    readonly delivered: boolean;
+    readonly transport: string;
+}
+export interface SendMessageResult {
+    readonly messageId: string;
+    readonly from: string;
+    readonly to: string;
+    readonly delivered: boolean;
+}
+export type SessionRuntimeState = 'idle' | 'running' | 'waking' | 'offline' | 'archived' | 'missing';
+export interface SessionRuntimeStatus {
+    readonly sessionId: string;
+    readonly state: SessionRuntimeState;
+    readonly live: boolean;
+}
+export interface LocalSessionMessaging {
+    list(): readonly SessionIdValue[];
+    status(sessionId: SessionIdValue): Promise<SessionRuntimeStatus>;
+    send(from: Agent, to: SessionIdValue, text: string): Promise<SendMessageResult>;
+    deliverExternal(from: string, to: SessionIdValue, text: string, options?: {
+        id?: string;
+        transport?: string;
+    }): Promise<SendMessageResult>;
+    subscribe(listener: (message: LocalMessage) => void): () => void;
+    receive(sessionId: SessionIdValue, limit: number): readonly LocalMessage[];
+}
+export declare class LocalSessionMessagingImpl implements LocalSessionMessaging {
+    constructor(ctx: Context);
+    list(): readonly SessionIdValue[];
+    status(sessionId: SessionIdValue): Promise<SessionRuntimeStatus>;
+    send(from: Agent, to: SessionIdValue, text: string): Promise<SendMessageResult>;
+    deliverExternal(from: string, to: SessionIdValue, text: string, options?: { id?: string; transport?: string }): Promise<SendMessageResult>;
+    subscribe(listener: (message: LocalMessage) => void): () => void;
+    receive(sessionId: SessionIdValue, limit: number): readonly LocalMessage[];
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        dshBridge: LocalSessionMessaging;
+        sessionMessaging: LocalSessionMessaging;
+    }
+}
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,114 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+export const name = 'session-messaging';
+export const inject = ['agents', 'tools'];
+class LocalSessionMessagingImpl {
+    ctx;
+    messages = [];
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    list() {
+        return [...this.ctx.agents.list()].map(agent => agent.session.id);
+    }
+    send(from, to, text) {
+        const target = this.ctx.agents.get(to);
+        if (!target)
+            throw new Error(`session "${to}" is not live in this process`);
+        const id = crypto.randomUUID();
+        const message = {
+            id,
+            from: from.session.id,
+            to,
+            text,
+            createdAt: Date.now(),
+            delivered: true,
+        };
+        this.messages.push(message);
+        target.followup(createUserMessage({
+            content: [{ type: 'text', text: `[session-message ${id} from ${from.session.id}]\n${text}` }],
+            source: { kind: 'plugin', plugin: name, form: 'relay' },
+        }));
+        return { messageId: id, from: String(from.session.id), to: String(to), delivered: true };
+    }
+    receive(sessionId, limit) {
+        return this.messages.filter(message => message.to === sessionId).slice(-limit);
+    }
+}
+export function apply(ctx) {
+    const messaging = new LocalSessionMessagingImpl(ctx);
+    ctx.accessor('sessionMessaging', { get: () => messaging });
+    ctx.tools.register(defineTool({
+        name: 'session_list',
+        description: 'List live DeepSeek Harness sessions in this process.',
+        parameters: {},
+        output: {
+            schema: { type: 'array', items: { type: 'string' } },
+            render: (_args, value) => [{ type: 'text', text: value.join('\n') || 'No live sessions.' }],
+        },
+        async execute() {
+            return messaging.list().map(String);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'session_send',
+        description: 'Send a message to another live DeepSeek Harness session in this process.',
+        parameters: {
+            to: { type: 'string', required: true, description: 'Target session id from session_list.' },
+            text: { type: 'string', required: true, description: 'Message text.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    messageId: { type: 'string', required: true },
+                    from: { type: 'string', required: true },
+                    to: { type: 'string', required: true },
+                    delivered: { type: 'boolean', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `Delivered ${value.messageId} to ${value.to}.` }],
+        },
+        async execute(args, exec) {
+            if (!exec.agent)
+                throw new Error('session_send requires an owning agent');
+            if (args.text.trim() === '')
+                throw new Error('text must not be empty');
+            return messaging.send(exec.agent, SessionId(args.to), args.text);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'session_messages',
+        description: 'Read messages delivered to the current session in this process.',
+        parameters: {
+            limit: { type: 'number', description: 'Maximum number of messages, default 20.' },
+        },
+        output: {
+            schema: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        id: { type: 'string', required: true },
+                        from: { type: 'string', required: true },
+                        to: { type: 'string', required: true },
+                        text: { type: 'string', required: true },
+                        createdAt: { type: 'number', required: true },
+                        delivered: { type: 'boolean', required: true },
+                    },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.map(message => `[${message.from}] ${message.text}`).join('\n') || 'No messages.' }],
+        },
+        async execute(args, exec) {
+            if (!exec.agent)
+                throw new Error('session_messages requires an owning agent');
+            const limit = args.limit === undefined ? 20 : Math.max(1, Math.min(100, Math.floor(args.limit)));
+            return [...messaging.receive(exec.agent.session.id, limit)];
+        },
+    }));
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "dsh-bridge",
+  "description": "Local session messaging and event bridge for DeepSeek Harness",
+  "version": "0.1.0-rc.10",
+  "publishConfig": { "access": "public", "tag": "next" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baixianger/dsh-bridge.git"
+  },
+  "type": "module",
+  "scripts": {
+    "check": "node --check lib/index.js && npm pack --dry-run",
+    "test": "node --test test/**/*.test.mjs"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": ["lib/index.js", "lib/types/**/*.js", "lib/types/**/*.d.ts", "cordis.patch.yml", "README.md"],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-agent": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-session": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.5"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-agent": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-session": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.5"
+  }
+}