dsh-session-messaging 0.0.0-stage → 0.1.2

package/lib/tools.js

@@ -0,0 +1,172 @@
+/**
+ * Model-facing tools for cross-session messaging. The tools are thin adapters
+ * over {@link SessionMessagingService}; the calling agent's own session is the
+ * only identity source, matching the subagent-control tools.
+ * @module dsh-session-messaging/tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+export const name = 'session-messaging-tools';
+export const inject = ['tools', 'sessionMessaging'];
+/**
+ * Reject calls without an owning agent session.
+ * @param agent - execution identity's agent, when present.
+ * @returns the owning agent.
+ */
+function requireAgent(agent) {
+    if (agent === undefined) {
+        throw new Error('session messaging tools require an owning agent session');
+    }
+    return agent;
+}
+/**
+ * Register the peer-list, relay, and opt-in tools.
+ * @param ctx - Cordis context with `tools` and `sessionMessaging` ready.
+ */
+export function apply(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'session_peers',
+        description: 'List other user-launched Harness sessions in the same working directory that this session can message. Use it before relaying coordination information. Only user-launched top-level sessions can use this tool; subagent sessions must use their parent/child channel. Sessions appear only while live in this Harness process.',
+        parameters: {},
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    peers: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                sessionId: { type: 'string', required: true, description: 'Stable target id for session_send.' },
+                                status: { type: 'string', required: true, enum: ['idle', 'running'] },
+                                canReceive: { type: 'boolean', required: true, description: 'Whether the session accepts peer messages.' },
+                                writeScopes: {
+                                    type: 'array',
+                                    required: true,
+                                    items: { type: 'string' },
+                                    description: 'Advisory paths that peer session declared it is changing.',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: value.peers.length === 0
+                        ? 'No other live user-launched sessions are available in this working directory.'
+                        : value.peers.map(peer => `${peer.sessionId} (${peer.status}, ${peer.canReceive ? 'accepting messages' : 'not opted in'})`).join('\n'),
+                }],
+            presentationMeta: (_args, value) => ({ peers: value.peers }),
+        },
+        execute(_args, exec) {
+            const peers = ctx.sessionMessaging.listPeers(requireAgent(exec.agent));
+            return Promise.resolve({ peers: peers.map(peer => ({ ...peer, writeScopes: [...peer.writeScopes] })) });
+        },
+        presentCall: () => ({ card: 'generic', title: 'List session peers', kind: 'search' }),
+    }));
+    ctx.tools.register(defineTool({
+        name: 'session_send',
+        description: 'Send a message to another user-launched Harness session in the same working directory. Use it to coordinate tasks and declared file-write scope with a peer session. The message is recorded as a user message in the target session, attributed to this session; it is peer input, not a user instruction. Both the caller and the target must be user-launched top-level sessions; subagent sessions use their parent/child channel. The target must be live and must not have paused reception. Success means the target accepted the message, not that it acted on it.',
+        parameters: {
+            targetSessionId: { type: 'string', required: true, description: 'Exact session id from session_peers.' },
+            message: { type: 'string', required: true, description: 'Coordination message. State what changed, what you need, and what you will not touch.' },
+            writeScopes: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Advisory workspace paths this session is changing, so the peer can avoid them.',
+            },
+            replyTo: { type: 'string', description: 'Optional message id this message answers.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    accepted: { type: 'boolean', required: true },
+                    messageId: { type: 'string', required: true },
+                    targetSessionId: { type: 'string', required: true },
+                    targetStatus: { type: 'string', required: true, enum: ['idle', 'running'] },
+                    conflicts: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                sessionId: { type: 'string', required: true },
+                                scopes: { type: 'array', required: true, items: { type: 'string' } },
+                            },
+                        },
+                        description: 'Peers whose declared write scopes overlap yours; coordinate before writing.',
+                    },
+                },
+            },
+            render: (_args, value) => {
+                const warning = value.conflicts.length === 0
+                    ? ''
+                    : ` Conflict warning: ${value.conflicts.map(conflict => `${conflict.sessionId} also declared ${conflict.scopes.join(', ')}`).join('; ')}. Coordinate before writing those paths.`;
+                return [{
+                        type: 'text',
+                        text: `Message ${value.messageId} accepted by session ${value.targetSessionId} (${value.targetStatus}). Acceptance means the message is in that session's inbox; it does not confirm the peer processed it.${warning}`,
+                    }];
+            },
+            presentationMeta: (_args, value) => ({ targetSessionId: value.targetSessionId, messageId: value.messageId }),
+        },
+        async execute(args, exec) {
+            const receipt = await ctx.sessionMessaging.send(requireAgent(exec.agent), {
+                targetSessionId: args.targetSessionId,
+                message: args.message,
+                ...(args.writeScopes === undefined ? {} : { writeScopes: args.writeScopes }),
+                ...(args.replyTo === undefined ? {} : { replyTo: args.replyTo }),
+            });
+            return {
+                ...receipt,
+                conflicts: receipt.conflicts.map(conflict => ({
+                    sessionId: conflict.sessionId,
+                    scopes: [...conflict.scopes],
+                })),
+            };
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `Message ${args.targetSessionId}`,
+            kind: 'other',
+            rawInput: { targetSessionId: args.targetSessionId, message: args.message },
+        }),
+    }));
+    ctx.tools.register(defineTool({
+        name: 'session_reception',
+        description: 'Set whether this session accepts peer messages. Reception is on by default; set enabled to false to pause it, or back to true to resume. Only user-launched top-level sessions can use this tool; subagent sessions use their parent/child channel. Optionally declare the workspace paths this session is changing so peers can avoid them.',
+        parameters: {
+            enabled: { type: 'boolean', required: true, description: 'Whether this session accepts peer messages.' },
+            writeScopes: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Advisory workspace paths this session is changing.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    enabled: { type: 'boolean', required: true },
+                    writeScopes: { type: 'array', required: true, items: { type: 'string' } },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: value.enabled
+                        ? `This session accepts peer messages${value.writeScopes.length > 0 ? ` and declares: ${value.writeScopes.join(', ')}` : ''}.`
+                        : 'This session has paused peer messages.',
+                }],
+        },
+        execute(args, exec) {
+            const entry = ctx.sessionMessaging.setConsent(requireAgent(exec.agent), args.enabled, args.writeScopes);
+            return Promise.resolve({ enabled: entry.enabled, writeScopes: [...entry.writeScopes] });
+        },
+    }));
+}

package/lib/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Durable message-source declaration for relayed session messages. Importing
+ * this module for its types adds the `session-message` kind to
+ * `MessageSourceMap`, which is what makes the receiving `user/message`
+ * reconstructable from the session log.
+ * @module dsh-session-messaging/types
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** A message another user-launched session relayed to this one. */
+        'session-message': {
+            readonly kind: 'session-message';
+            /** Shared relay form used by existing agent-to-agent messages. */
+            readonly form: 'relay';
+            /** Session id of the sending session. */
+            readonly senderSessionId: SessionId;
+            /** Sender-minted correlation id for receipts and replies. */
+            readonly messageId: string;
+        };
+    }
+}
+export {};

package/lib/types.js

@@ -0,0 +1,8 @@
+/**
+ * Durable message-source declaration for relayed session messages. Importing
+ * this module for its types adds the `session-message` kind to
+ * `MessageSourceMap`, which is what makes the receiving `user/message`
+ * reconstructable from the session log.
+ * @module dsh-session-messaging/types
+ */
+export {};

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Session Messaging",
+    "description": "Peer messaging between user-launched sessions in one workspace: discover peers, relay coordination messages, pause reception, and receive advisory write-scope conflict warnings."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "跨会话消息",
+    "description": "让同一工作区里用户自行启动的多个会话互相发消息：发现对等会话、转发协调消息、暂停接收，并获得建议性的文件写入范围冲突提示。"
+  }
+}

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "dsh-session-messaging",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Peer messaging between user-launched sessions in one workspace: discover peers, relay coordination messages, pause reception, and get advisory write-scope conflict warnings.",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./tools": {
+      "types": "./lib/tools.d.ts",
+      "default": "./lib/tools.js"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./tools/locale/*.json": "./tools/locale/*.json",
+    "./tools/icon": "./assets/tools-icon.svg",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "locale",
+    "tools/locale",
+    "assets",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "session",
+    "messaging",
+    "multi-agent",
+    "agent-collaboration"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XBXyftx/dsh-session-messaging.git"
+  },
+  "homepage": "https://github.com/XBXyftx/dsh-session-messaging#readme",
+  "bugs": {
+    "url": "https://github.com/XBXyftx/dsh-session-messaging/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0",
+    "dsh": ">=0.2.1-rc.2 <0.3.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.5"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --experimental-strip-types --test tests/protocol.test.ts",
+    "test:integration": "node --experimental-strip-types tests/integration-smoke.ts",
+    "test:model-e2e": "node --experimental-strip-types tests/model-e2e-smoke.ts"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "icon": "./assets/icon.svg",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tools/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Session Messaging Tools",
+    "description": "Model-facing tools: session_peers (discover peers), session_send (relay a message with optional write scopes), session_reception (pause or resume reception)."
+  }
+}

package/tools/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "跨会话消息工具",
+    "description": "模型工具：session_peers（发现对等会话）、session_send（发送消息并可声明写范围）、session_reception（暂停或恢复接收）。"
+  }
+}