@wowyuarm/dsh-agent-team 0.1.11 → 0.1.13

package/packages/tool-agent-team/lib/index.js

@@ -1,7 +1,7 @@
-import { AgentTeamDmDeliveryError, markAgentTeamPreset } from '@wowyuarm/dsh-agent-team/host';
+import { AGENT_TEAM_HUMAN_HANDLE, AgentTeamDmDeliveryError, markAgentTeamPreset } from '@wowyuarm/dsh-agent-team/host';
 import { formatTeamTimestamp } from '@wowyuarm/dsh-agent-team/time-format';
 import { registerContextTools } from "./context-tools.js";
-import { member, service } from "./host-access.js";
+import { service, workspaceOf, workspaceParam } from "./host-access.js";
 import { defineTool } from '@deepseek-ai/dsh-tools';
 export const name = 'wowyuarm-agent-team-tools';
 export const inject = ['tools'];
@@ -114,13 +114,13 @@ function rejectionLines(noun, value) {
 }
 const teamInbox = defineTool({
     name: 'team_inbox',
-    description: 'List your bounded Team Inbox for triage: unread Thread summaries with counts, without message bodies and without marking anything read. Read a selected Thread with team_thread read; the inbox itself authorizes no mutation.',
-    parameters: { limit: { type: 'number' } },
+    description: 'List your bounded Team Inbox across all joined Workspaces for triage: unread Thread summaries with counts, without message bodies and without marking anything read. Read a selected Thread with team_thread read; the inbox itself authorizes no mutation.',
+    parameters: { limit: { type: 'number' }, workspace: { type: 'string', description: 'Optional Workspace id filter. Omit to triage all your participations together.' } },
     output: {
         schema: { type: 'object', additionalProperties: false, properties: {
                 totalUnreadCount: { type: 'number', required: true }, totalDirectCount: { type: 'number', required: true },
                 items: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: {
-                            threadRef: { type: 'string', required: true }, channelRef: { type: 'string', required: true },
+                            workspaceId: { type: 'string', required: true }, threadRef: { type: 'string', required: true }, channelRef: { type: 'string', required: true },
                             taskRef: { type: 'string' }, status: { type: 'string' }, revision: { type: 'number', required: true }, unreadCount: { type: 'number', required: true }, directCount: { type: 'number', required: true },
                             taskNumber: { type: 'number' }, newestOccurredAt: { type: 'string' },
                         } } },
@@ -139,7 +139,7 @@ const teamInbox = defineTool({
             const shown = value.items.reduce((sum, item) => sum + item.unreadCount, 0);
             return [{ type: 'text', text: [
                         `Inbox — ${value.totalUnreadCount} unread update(s) total, ${value.totalDirectCount} direct, across ${value.items.length} Thread(s) shown${value.totalUnreadCount > shown ? `; ${value.totalUnreadCount - shown} more on Threads beyond this bounded list — call again with a larger limit.` : '.'}`,
-                        ...value.items.map(item => `${item.threadRef}${item.channelRef === undefined ? '' : ` · ${item.channelRef}`}${item.taskRef === undefined ? '' : ` · ${taskStanding(item)}`} · ${item.unreadCount} unread, ${item.directCount} direct${item.newestOccurredAt === undefined ? '' : ` · newest ${formatTeamTimestamp(item.newestOccurredAt)}`}`),
+                        ...value.items.map(item => `${item.workspaceId} · ${item.threadRef}${item.channelRef === undefined ? '' : ` · ${item.channelRef}`}${item.taskRef === undefined ? '' : ` · ${taskStanding(item)}`} · ${item.unreadCount} unread, ${item.directCount} direct${item.newestOccurredAt === undefined ? '' : ` · newest ${formatTeamTimestamp(item.newestOccurredAt)}`}`),
                         'Read a selected Thread with team_thread read. Listing changes no read state and supplies no write token.',
                     ].join('\n') }];
         },
@@ -148,16 +148,13 @@ const teamInbox = defineTool({
         const agent = exec.agent;
         if (agent === undefined)
             throw new Error('team_inbox requires an Agent session');
-        const current = member(agent);
         const host = service(agent);
-        const inbox = host.inboxForAgent(agent, { workspaceId: current.workspaceId, ...(args.limit === undefined ? {} : { limit: args.limit }) });
-        const taskNumbers = new Map(host.viewForAgent(agent, { workspaceId: current.workspaceId, topLevelOnly: true, includeActivities: false, direction: 'before' })
-            .taskNumbers.map(entry => [entry.taskRef, entry.taskNumber]));
+        const inbox = host.inboxForAgent(agent, { ...(args.workspace === undefined ? {} : { workspaceId: workspaceOf(args, agent) }), ...(args.limit === undefined ? {} : { limit: args.limit }) });
         return {
             totalUnreadCount: inbox.totalUnreadCount, totalDirectCount: inbox.totalDirectCount,
             items: inbox.items.map(item => {
-                const taskNumber = item.task === undefined ? undefined : taskNumbers.get(item.task.taskRef);
-                return { threadRef: item.thread.threadRef, channelRef: item.channelRef,
+                const taskNumber = item.taskNumber;
+                return { workspaceId: item.workspaceId, threadRef: item.thread.threadRef, channelRef: item.channelRef,
                     ...(item.task === undefined ? {} : { taskRef: item.task.taskRef, status: item.task.status }),
                     revision: item.thread.revision, unreadCount: item.unreadCount, directCount: item.directCount, newestOccurredAt: item.newestOccurredAt,
                     ...(taskNumber === undefined ? {} : { taskNumber }) };
@@ -167,18 +164,19 @@ const teamInbox = defineTool({
 });
 const teamThread = defineTool({
     name: 'team_thread',
-    description: 'Read or manage your Attention on one Thread. read acknowledges one chronological batch of unread facts and is the only read-side source of a next-write token — and only once no unread remains; your own committed public mutations hand off the token as well. history pages older facts without changing read state; status, follow, and unfollow change or report Attention only and render no Thread timeline. Prefer threadRef; taskRef is a compatibility alias when the Thread has a Task.',
+    description: 'Read or manage your Attention on one Thread. read acknowledges one chronological batch of unread facts and is the only read-side source of a next-write token — and only once no unread remains; your own committed public mutations hand off the token as well. A read orients on the Thread anchor and that batch, never the whole Thread: a Member re-entering one it has read before gets no background at all, so the facts between are its own to page back to. history pages older facts without changing read state; status, follow, and unfollow change or report Attention only and render no Thread timeline. Prefer threadRef; taskRef is a compatibility alias when the Thread has a Task.',
     parameters: {
         action: { type: 'string', required: true, enum: ['status', 'follow', 'unfollow', 'read', 'history'] },
         threadRef: { type: 'string', description: "Full branded Thread ref exactly as returned by Team tools, including the 'thread:' prefix. An unambiguous abbreviation of the first 6+ UUID hex characters also resolves." },
         taskRef: { type: 'string', description: "Optional Task ref alias for released clients. Prefer threadRef; if both are given they must identify the same Thread." },
-        beforeSequence: { type: 'number' }, limit: { type: 'number' },
+        beforeSequence: { type: 'number' }, limit: { type: 'number' }, workspace: workspaceParam,
     },
     output: {
         schema: { type: 'object', additionalProperties: false, properties: {
+                workspaceId: { type: 'string', required: true }, channelRef: { type: 'string', required: true },
                 kind: { type: 'string', required: true }, threadRef: { type: 'string', required: true }, taskRef: { type: 'string' },
                 revision: { type: 'number', required: true }, status: { type: 'string' }, resolution: { type: 'string' }, taskNumber: { type: 'number' },
-                following: { type: 'boolean', required: true }, readThroughSequence: { type: 'number' }, remainingUnreadCount: { type: 'number' }, cursor: { type: 'number' }, hasMore: { type: 'boolean' },
+                following: { type: 'boolean', required: true }, readThroughSequence: { type: 'number' }, remainingUnreadCount: { type: 'number' }, earlierFactCount: { type: 'number' }, cursor: { type: 'number' }, hasMore: { type: 'boolean' },
                 anchor: { type: 'object', required: true, additionalProperties: false, properties: {
                         messageRef: { type: 'string', required: true }, sender: { type: 'string', required: true }, body: { type: 'string', required: true }, sequence: { type: 'number', required: true }, occurredAt: { type: 'string' },
                     } },
@@ -201,15 +199,16 @@ const teamThread = defineTool({
         // current collision surface or any write token.
         render: (args, value) => {
             const standing = taskStanding(value);
+            const source = `Workspace: ${value.workspaceId} · Channel: ${value.channelRef}`;
             if (value.kind === 'status') {
-                return [{ type: 'text', text: `Attention status — ${value.following ? 'following' : 'not following'} ${value.threadRef}${standing === '' ? '' : ` · ${standing}`}.` }];
+                return [{ type: 'text', text: `${source}\nAttention status — ${value.following ? 'following' : 'not following'} ${value.threadRef}${standing === '' ? '' : ` · ${standing}`}.` }];
             }
             if (value.kind === 'follow' || value.kind === 'unfollow') {
-                return [{ type: 'text', text: `Attention changed — ${value.following ? 'now following' : 'no longer following'} ${value.threadRef}${standing === '' ? '' : ` · ${standing}`}.` }];
+                return [{ type: 'text', text: `${source}\nAttention changed — ${value.following ? 'now following' : 'no longer following'} ${value.threadRef}${standing === '' ? '' : ` · ${standing}`}.` }];
             }
             if (value.kind === 'history') {
                 const facts = value.facts;
-                const lines = [`History for ${value.threadRef}${standing === '' ? '' : ` · ${standing}`}`];
+                const lines = [source, `History for ${value.threadRef}${standing === '' ? '' : ` · ${standing}`}`];
                 // First page (no beforeSequence supplied) orients on the full
                 // anchor; a continuation orients on the shared bounded subject. An
                 // anchor already selected as a fact never repeats.
@@ -235,6 +234,7 @@ const teamThread = defineTool({
             // A read with nothing unread writes no durable operation, so the opening
             // line claims a commit only when unread facts were actually acknowledged.
             const lines = [
+                source,
                 acknowledged === 0
                     ? `Read — no unread updates on ${value.threadRef}; nothing remains.`
                     : `Read committed — acknowledged ${acknowledged} unread update(s) on ${value.threadRef}; ${remaining} remain.`,
@@ -263,6 +263,13 @@ const teamThread = defineTool({
             else
                 lines.push(...facts.map(fact => factLine(fact)));
             lines.push('', `Read through sequence ${value.readThroughSequence}; ${remaining} unread update(s) remaining${remaining > 0 ? ' — call team_thread read again.' : '.'}`);
+            // What this bounded read answered with is the newest batch; the span
+            // before the watermark is the orientation it did not supply. Rendering
+            // the count is what lets a returning reader see the size of that span
+            // instead of assuming the batch is the Thread.
+            const earlier = value.earlierFactCount ?? 0;
+            if (earlier > 0)
+                lines.push(`Earlier facts: ${earlier} — read older ones with team_thread.history.`);
             if (value.contextAdvice !== undefined)
                 lines.push('', ...adviceLines(value.contextAdvice));
             if (remaining === 0)
@@ -274,15 +281,14 @@ const teamThread = defineTool({
         const agent = exec.agent;
         if (agent === undefined)
             throw new Error('team_thread requires an Agent session');
-        const current = member(agent);
         const host = service(agent);
         if (args.threadRef === undefined && args.taskRef === undefined)
             throw new Error('team_thread requires threadRef');
-        const base = { workspaceId: current.workspaceId, ...(args.threadRef === undefined ? {} : { threadRef: args.threadRef }), ...(args.taskRef === undefined ? {} : { taskRef: args.taskRef }) };
+        const base = { workspaceId: workspaceOf(args, agent), ...(args.threadRef === undefined ? {} : { threadRef: args.threadRef }), ...(args.taskRef === undefined ? {} : { taskRef: args.taskRef }) };
         const taskNumberOf = (task) => {
             if (task === undefined)
                 return {};
-            const resolved = host.resolveTaskRefs({ workspaceId: current.workspaceId, taskRefs: [task.taskRef] }).resolved[0];
+            const resolved = host.resolveTaskRefs({ workspaceId: base.workspaceId, taskRefs: [task.taskRef] }).resolved[0];
             return resolved === undefined ? {} : { taskNumber: resolved.taskNumber };
         };
         if (args.action === 'status') {
@@ -290,28 +296,28 @@ const teamThread = defineTool({
                 throw new Error('status does not accept history arguments');
             const status = host.attentionStatusForAgent(agent, base);
             const snapshot = host.threadHistoryForAgent(agent, { ...base, beforeSequence: 1, limit: 1 });
-            return threadResult('status', snapshot, status.attention, [], taskNumberOf(snapshot.task));
+            return threadResult('status', base.workspaceId, snapshot, status.attention, [], taskNumberOf(snapshot.task));
         }
         if (args.action === 'follow' || args.action === 'unfollow') {
             if (args.beforeSequence !== undefined || args.limit !== undefined)
                 throw new Error(`${args.action} does not accept history arguments`);
             const result = await host.changeAttentionForAgent(agent, { requestId: requestId(agent.id, exec.callId), ...base, action: args.action });
             const snapshot = host.threadHistoryForAgent(agent, { ...base, beforeSequence: 1, limit: 1 });
-            return threadResult(args.action, snapshot, result.attention, [], taskNumberOf(snapshot.task));
+            return threadResult(args.action, base.workspaceId, snapshot, result.attention, [], taskNumberOf(snapshot.task));
         }
         if (args.action === 'history') {
             const history = host.threadHistoryForAgent(agent, { ...base, ...(args.beforeSequence === undefined ? {} : { beforeSequence: args.beforeSequence }), ...(args.limit === undefined ? {} : { limit: args.limit }) });
             const status = host.attentionStatusForAgent(agent, base);
-            return threadResult('history', history, status.attention, history.facts.map(fact => fact.kind === 'message'
+            return threadResult('history', base.workspaceId, history, status.attention, history.facts.map(fact => fact.kind === 'message'
                 ? { sequence: fact.sequence, kind: 'message', body: fact.message.body, sender: fact.message.sender, mentions: [...fact.mentions], occurredAt: fact.occurredAt }
                 : activityFactView(fact.sequence, fact.activity, undefined, fact.occurredAt)), { cursor: history.cursor, hasMore: history.hasMore, ...taskNumberOf(history.task) });
         }
         if (args.beforeSequence !== undefined || args.limit !== undefined)
             throw new Error('read does not accept history arguments');
         const read = await host.readThreadForAgent(agent, { requestId: requestId(agent.id, exec.callId), ...base });
-        return threadResult('read', read, read.attention, read.facts.map(entry => entry.fact.kind === 'message'
+        return threadResult('read', base.workspaceId, read, read.attention, read.facts.map(entry => entry.fact.kind === 'message'
             ? { sequence: entry.fact.sequence, kind: 'message', body: entry.fact.message.body, sender: entry.fact.message.sender, mentions: [...entry.fact.mentions], unread: entry.unread, direct: entry.direct, occurredAt: entry.fact.occurredAt }
-            : activityFactView(entry.fact.sequence, entry.fact.activity, { unread: entry.unread, direct: entry.direct }, entry.fact.occurredAt)), { readThroughSequence: read.readThroughSequence, remainingUnreadCount: read.remainingUnreadCount, ...(read.contextAdvice === undefined ? {} : { contextAdvice: adviceView(read.contextAdvice) }), ...taskNumberOf(read.task) });
+            : activityFactView(entry.fact.sequence, entry.fact.activity, { unread: entry.unread, direct: entry.direct }, entry.fact.occurredAt)), { readThroughSequence: read.readThroughSequence, remainingUnreadCount: read.remainingUnreadCount, ...(read.earlierFactCount === undefined ? {} : { earlierFactCount: read.earlierFactCount }), ...(read.contextAdvice === undefined ? {} : { contextAdvice: adviceView(read.contextAdvice) }), ...taskNumberOf(read.task) });
     },
 });
 /** One rendered fact line; markers are inline, never a separate ellipsis line. */
@@ -325,8 +331,9 @@ function factLine(fact) {
 function claimLine(claim) {
     return `${claim.claimRef} — ${claim.owner}: ${claim.direction}`;
 }
-function threadResult(kind, snapshot, attention, facts, extra = {}) {
+function threadResult(kind, workspaceId, snapshot, attention, facts, extra = {}) {
     return {
+        workspaceId, channelRef: snapshot.anchor.channelRef,
         kind, threadRef: snapshot.thread.threadRef, revision: snapshot.thread.revision,
         ...(snapshot.task === undefined ? {} : { taskRef: snapshot.task.taskRef, status: snapshot.task.status, resolution: snapshot.task.resolution }),
         ...(extra.taskNumber === undefined ? {} : { taskNumber: extra.taskNumber }),
@@ -348,7 +355,7 @@ function adviceLines(advice) {
 }
 const teamMessage = markAgentTeamPreset(defineTool({
     name: 'team_message',
-    description: 'Start a top-level Thread, reply to an existing Thread, or send a direct message (DM). Read the Thread first: a reply needs the current next-write token from a fully drained team_thread read (or your own last committed mutation), and unread work rejects before staleness is even checked. start defaults to a taskless Thread; pass asTask true to create a Task in the same send. A top-level start may mention related Agents directly; in replies, only a Human can invite an unfollowed Agent. Pass Member refs in mentions and spell their handles inside the body; only mentioned Members render as mention chips. dm sends a private direct message to one enabled Agent Member in your Workspace: use it for quick clarifications and status syncs — never for task work, decisions, or anything that needs team visibility or traceability (use a Thread); if a DM exchange with the same Member exceeds about 3 exchanges, move it to a Thread, because every DM costs the recipient a full agent turn.',
+    description: 'Start a top-level Thread, reply to an existing Thread, or send a direct message (DM). Read the Thread first: a reply needs the current next-write token from a fully drained team_thread read (or your own last committed mutation), and unread work rejects before staleness is even checked — and a mention only delivers its Message and restores Attention, never the Thread\'s earlier facts, so entering a Thread whose facts have left your context means reading back through it first. start defaults to a taskless Thread; pass asTask true to create a Task in the same send. A top-level start may mention related Agents directly; in replies, only a Human can invite a Member the Thread has never carried. Mention by writing `@Handle` in body — the `@` is required, matching ignores case, and each named Member is delivered to and renders as a mention chip; `@all` reaches every Member of the Channel. Naming a Member this Thread has never carried still commits, delivers nothing to that Member, and reports them under undeliveredMentions: ask the Human to invite them, or reach them with a dm. dm sends a private direct message to one enabled Agent Member in your Workspace: use it for quick clarifications and status syncs — never for task work, decisions, or anything that needs team visibility or traceability (use a Thread); if a DM exchange with the same Member exceeds about 3 exchanges, move it to a Thread, because every DM costs the recipient a full agent turn.',
     parameters: {
         action: { type: 'string', required: true, enum: ['start', 'reply', 'dm'] },
         channelRef: { type: 'string', description: "Full branded Channel ref exactly as returned by Team tools, including the 'channel:' prefix. An unambiguous abbreviation of the first 6+ UUID hex characters also resolves." },
@@ -356,15 +363,16 @@ const teamMessage = markAgentTeamPreset(defineTool({
         taskRef: { type: 'string', description: "Optional Task ref alias for reply on a Taskful Thread. Prefer threadRef; an unambiguous abbreviation of the first 6+ UUID hex characters also resolves." },
         memberRef: { type: 'string', description: "Full branded Member ref exactly as returned by Team tools, including the 'member:' prefix. An unambiguous abbreviation of the first 6+ UUID hex characters also resolves. Required for dm; the Member must be an enabled Agent in your Workspace (the Human cannot be DMed)." },
         asTask: { type: 'boolean', description: 'When true, start creates a Task with the Thread. Default false creates a taskless Thread.' },
-        body: { type: 'string', required: true, description: "Markdown body. Lead with the conclusion or state. Mention the Human only when they must know or decide, with a one-to-three-sentence opening and a `Decision needed: X (default: Y)` line when a decision is owed; mechanical detail follows below. Cite Team refs exactly as returned, as bare text with one colon (e.g. task:0f0a…) — never a double colon, never inside backticks or quotes. Unambiguous UUID abbreviations (first 6+ hex chars) also resolve. Spell each mentioned Member's handle in the prose so the mention renders inline." }, baseRevision: { type: 'number', description: "The next-write token from your latest fully drained team_thread read (or your own last committed mutation) on this Thread. Copy the explicitly rendered value verbatim; never increment, derive, compare, or cite it — it is an opaque concurrency token, not a fact about the Thread." },
-        mentions: { type: 'array', items: { type: 'string' }, description: 'Member refs to mention. Mentioned Agents receive the Message directly; write their handles in the body (any casing, optional @) so the mention renders inline.' },
+        body: { type: 'string', required: true, description: "Markdown body. Lead with the conclusion or state. Mention the Human only when they must know or decide; when a decision is owed, say plainly what needs deciding and what happens by default if nobody answers — no fixed template. Keep it the shortest useful message for the recipients; mechanical detail follows below. Cite Team refs exactly as returned, as bare text with one colon (e.g. task:0f0a…) — never a double colon, never inside backticks or quotes. Unambiguous UUID abbreviations (first 6+ hex chars) also resolve. Mention a Member by writing `@Handle` (`@` required, case-insensitive) in the prose: that is what delivers the Message to them and renders the mention chip, and `@all` reaches the whole Channel." }, baseRevision: { type: 'number', description: "The next-write token from your latest fully drained team_thread read (or your own last committed mutation) on this Thread. Copy the explicitly rendered value verbatim; never increment, derive, compare, or cite it — it is an opaque concurrency token, not a fact about the Thread." },
         attachments: { type: 'array', items: { type: 'string' }, description: 'Absolute file paths to share, e.g. screenshots or generated artifacts; images render as thumbnails for recipients. The Host validates each path and copies the file into the attachment cache, and members also receive one cached path per attachment; if any path fails validation the whole send is rejected.' },
+        workspace: workspaceParam,
     },
     output: {
         schema: { type: 'object', additionalProperties: false, properties: {
                 kind: { type: 'string', required: true }, action: { type: 'string' }, taskRef: { type: 'string' }, threadRef: { type: 'string' }, revision: { type: 'number' },
                 expectedRevision: { type: 'number' }, messageRef: { type: 'string' }, memberIds: { type: 'array', items: { type: 'string' } }, unreadCount: { type: 'number' }, directCount: { type: 'number' },
                 recipientMemberId: { type: 'string' }, recipientHandle: { type: 'string' }, delivered: { type: 'boolean' }, deliveryNote: { type: 'string' }, occurredAt: { type: 'string' },
+                undeliveredMentions: { type: 'array', items: { type: 'string' } },
             } },
         render: (_args, value) => {
             if (value.kind === 'dm-sent') {
@@ -381,6 +389,9 @@ const teamMessage = markAgentTeamPreset(defineTool({
                             value.action === 'start' ? 'Committed — Thread created.' : 'Committed — reply added.',
                             [value.messageRef, value.threadRef, ...(value.taskRef === undefined ? [] : [value.taskRef])].join(' · '),
                             ...(value.occurredAt === undefined ? [] : [`Committed at ${formatTeamTimestamp(value.occurredAt)}`]),
+                            ...(value.undeliveredMentions === undefined || value.undeliveredMentions.length === 0 ? [] : [
+                                `Mention not delivered — ${value.undeliveredMentions.join(', ')} never took part in this Thread, so nothing reached them. Only a Human can invite a Member: reach them with a dm, or ask the Human.`,
+                            ]),
                             nextWriteLine(value.revision),
                         ].join('\n') }];
             }
@@ -398,26 +409,24 @@ const teamMessage = markAgentTeamPreset(defineTool({
         const agent = exec.agent;
         if (agent === undefined)
             throw new Error('team_message requires an Agent session');
-        const current = member(agent);
         const host = service(agent);
-        const mentions = args.mentions;
         const rawPaths = args.attachments;
         const attachmentPaths = Array.isArray(rawPaths) ? rawPaths.filter((entry) => typeof entry === 'string' && entry.trim() !== '') : undefined;
         const paths = attachmentPaths !== undefined && attachmentPaths.length > 0 ? { attachmentPaths } : {};
         if (args.action === 'start') {
             if (args.channelRef === undefined || args.taskRef !== undefined || args.threadRef !== undefined || args.baseRevision !== undefined)
                 throw new Error('start requires channelRef and does not accept threadRef, taskRef, or baseRevision');
-            const result = await host.sendMessageForAgent(agent, { requestId: requestId(agent.id, exec.callId), workspaceId: current.workspaceId,
-                channelRef: args.channelRef, body: args.body, asTask: args.asTask === true, ...(mentions === undefined ? {} : { recipients: mentions }), ...paths });
+            const result = await host.sendMessageForAgent(agent, { requestId: requestId(agent.id, exec.callId), workspaceId: workspaceOf(args, agent),
+                channelRef: args.channelRef, body: args.body, asTask: args.asTask === true, ...paths });
             return messageOutcome(result, 'start');
         }
         if (args.action === 'dm') {
             if (args.memberRef === undefined || args.channelRef !== undefined || args.threadRef !== undefined || args.taskRef !== undefined
-                || args.baseRevision !== undefined || args.asTask !== undefined || mentions !== undefined || attachmentPaths !== undefined) {
-                throw new Error('dm requires memberRef and body only; it does not accept channelRef, threadRef, taskRef, baseRevision, asTask, mentions, or attachments');
+                || args.baseRevision !== undefined || args.asTask !== undefined || attachmentPaths !== undefined) {
+                throw new Error('dm requires memberRef and body only; it does not accept channelRef, threadRef, taskRef, baseRevision, asTask, or attachments');
             }
             try {
-                const result = await host.dmForAgent(agent, { requestId: requestId(agent.id, exec.callId), workspaceId: current.workspaceId,
+                const result = await host.dmForAgent(agent, { requestId: requestId(agent.id, exec.callId), workspaceId: workspaceOf(args, agent),
                     recipientMemberId: args.memberRef, body: args.body });
                 return { kind: 'dm-sent', recipientMemberId: result.recipient.memberId, recipientHandle: result.recipient.handle, delivered: true, occurredAt: result.receipt.occurredAt };
             }
@@ -432,19 +441,23 @@ const teamMessage = markAgentTeamPreset(defineTool({
         if ((args.threadRef === undefined && args.taskRef === undefined) || args.channelRef !== undefined || args.asTask !== undefined || typeof baseRevision !== 'number' || !Number.isSafeInteger(baseRevision) || baseRevision < 1) {
             throw new Error('reply requires threadRef and a positive baseRevision; drain the Thread with team_thread read and copy the token it renders, or reuse the one your own last committed mutation rendered');
         }
-        const result = await host.replyForAgent(agent, { requestId: requestId(agent.id, exec.callId), workspaceId: current.workspaceId,
+        const result = await host.replyForAgent(agent, { requestId: requestId(agent.id, exec.callId), workspaceId: workspaceOf(args, agent),
             ...(args.threadRef === undefined ? {} : { threadRef: args.threadRef }),
             ...(args.taskRef === undefined ? {} : { taskRef: args.taskRef }),
-            body: args.body, baseRevision,
-            ...(mentions === undefined ? {} : { recipients: mentions }), ...paths });
+            body: args.body, baseRevision, ...paths });
         return messageOutcome(result, 'reply');
     },
 }));
 function messageOutcome(result, action) {
-    if (result.kind === 'committed')
+    if (result.kind === 'committed') {
+        // A start always delivers to the Members it names — they begin following the
+        // new Thread — so only a reply can report names the Thread has never carried.
+        const undelivered = 'undeliveredMentions' in result ? result.undeliveredMentions : undefined;
         return { kind: result.kind, action, threadRef: result.thread.threadRef,
             ...(result.task === undefined ? {} : { taskRef: result.task.taskRef }),
-            revision: result.thread.revision, messageRef: result.message.messageRef, occurredAt: result.receipt.occurredAt };
+            revision: result.thread.revision, messageRef: result.message.messageRef, occurredAt: result.receipt.occurredAt,
+            ...(undelivered === undefined || undelivered.length === 0 ? {} : { undeliveredMentions: [...undelivered] }) };
+    }
     if (result.kind === 'member_not_following')
         return { kind: result.kind, memberIds: [...result.memberIds],
             ...(result.taskRef === undefined ? {} : { taskRef: result.taskRef }), ...(result.threadRef === undefined ? {} : { threadRef: result.threadRef, revision: result.revision }) };
@@ -464,6 +477,7 @@ const teamClaim = defineTool({
         taskRef: { type: 'string', required: true, description: "Full branded Task ref exactly as returned by Team tools, including the 'task:' prefix. An unambiguous abbreviation of the first 6+ UUID hex characters also resolves." },
         baseRevision: { type: 'number', description: "The next-write token from your latest fully drained team_thread read (or your own last committed mutation) on this Task's Thread. Copy the explicitly rendered value verbatim; never increment, derive, compare, or cite it — it is an opaque concurrency token, not a fact about the Task." }, direction: { type: 'string' },
         claimRef: { type: 'string', description: "Full branded Claim ref exactly as returned by team_claim, including the 'claim:' prefix. An unambiguous abbreviation of the first 6+ UUID hex characters also resolves." },
+        workspace: workspaceParam,
     },
     output: {
         schema: { type: 'object', additionalProperties: false, properties: {
@@ -505,9 +519,8 @@ const teamClaim = defineTool({
         const agent = exec.agent;
         if (agent === undefined)
             throw new Error('team_claim requires an Agent session');
-        const current = member(agent);
         const host = service(agent);
-        const base = { workspaceId: current.workspaceId, taskRef: args.taskRef };
+        const base = { workspaceId: workspaceOf(args, agent), taskRef: args.taskRef };
         if (args.action === 'list') {
             if (args.baseRevision !== undefined || args.direction !== undefined || args.claimRef !== undefined)
                 throw new Error('list accepts only taskRef');
@@ -544,11 +557,13 @@ const teamView = defineTool({
     description: 'Discover your authorized Team addresses: current Channels, a newest-first page of top-level Threads (each with its bounded anchor subject; Task standing inline on taskful rows), and current Members. This is an address book, not a work queue — unread work lives in team_inbox, and a Thread is read with team_thread read. The cursor pages Thread rows only.',
     parameters: {
         channelRef: { type: 'string', description: "Full branded Channel ref exactly as returned by Team tools, including the 'channel:' prefix. An unambiguous abbreviation of the first 6+ UUID hex characters also resolves." },
-        limit: { type: 'number' }, cursor: { type: 'number' },
+        limit: { type: 'number' }, cursor: { type: 'number' }, workspace: workspaceParam,
     },
     output: {
         schema: { type: 'object', additionalProperties: false, properties: {
                 channels: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: { channelRef: { type: 'string', required: true }, name: { type: 'string', required: true } } } },
+                workspaceId: { type: 'string', required: true },
+                workspaces: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: { workspaceId: { type: 'string', required: true }, title: { type: 'string' }, default: { type: 'boolean', required: true } } } },
                 members: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: {
                             memberId: { type: 'string', required: true }, kind: { type: 'string', required: true }, handle: { type: 'string', required: true }, description: { type: 'string', required: true }, presence: { type: 'string', required: true },
                         } } },
@@ -568,7 +583,7 @@ const teamView = defineTool({
         // which is reading, never writing from a directory snapshot.
         render: (_args, value) => {
             const continuation = value.page === 'threads';
-            const lines = [];
+            const lines = [`Workspace: ${value.workspaceId}`];
             if (!continuation) {
                 lines.push('Team directory', '', 'Channels — current');
                 if (value.channels.length === 0)
@@ -583,6 +598,10 @@ const teamView = defineTool({
             else
                 lines.push(...value.threads.map(thread => `${thread.threadRef} · ${thread.channelRef}${thread.taskRef === undefined ? ' · taskless' : ` · ${taskStanding(thread)}`} — ${thread.subject}${thread.lastActivityAt === undefined ? '' : ` · last activity ${formatTeamTimestamp(thread.lastActivityAt)}`}`));
             lines.push(`Thread cursor ${value.cursor}; hasMore=${value.hasMore ? 'true' : 'false'}${value.hasMore ? ' — older Thread anchors exist; page again with this cursor.' : ' — no older Threads remain.'}`);
+            if (!continuation && value.workspaces.length > 1) {
+                lines.push('', 'Workspaces — you participate in');
+                lines.push(...value.workspaces.map(workspace => `${workspace.workspaceId}${workspace.title === undefined ? '' : ` · ${workspace.title}`}${workspace.default ? ' · default — your Session and cwd live here' : ' — address it with the workspace argument; file work needs absolute paths'}`));
+            }
             if (!continuation) {
                 lines.push('', 'Members — current');
                 if (value.members.length === 0)
@@ -597,14 +616,17 @@ const teamView = defineTool({
         const agent = exec.agent;
         if (agent === undefined)
             throw new Error('team_view requires an Agent session');
-        const current = member(agent);
         const host = service(agent);
-        const view = host.viewForAgent(agent, { workspaceId: current.workspaceId, ...(args.channelRef === undefined ? {} : { channelRef: args.channelRef }), ...(args.limit === undefined ? {} : { limit: args.limit }), ...(args.cursor === undefined ? {} : { cursor: args.cursor }), topLevelOnly: true, includeActivities: false, direction: 'before' });
+        const workspaceId = workspaceOf(args, agent);
+        const view = host.viewForAgent(agent, { workspaceId, ...(args.channelRef === undefined ? {} : { channelRef: args.channelRef }), ...(args.limit === undefined ? {} : { limit: args.limit }), ...(args.cursor === undefined ? {} : { cursor: args.cursor }), topLevelOnly: true, includeActivities: false, direction: 'before' });
         const visibleMemberIds = new Set(view.members.map(membership => membership.memberId));
         return {
+            workspaceId,
+            workspaces: view.workspaces.map(participation => ({ workspaceId: participation.workspaceId,
+                ...(participation.title === undefined ? {} : { title: participation.title }), default: participation.default })),
             channels: view.channels.map(channel => ({ channelRef: channel.channelRef, name: channel.name })),
             members: [
-                { memberId: view.humanMemberId, kind: 'human', handle: 'human', description: 'Human Team Member', presence: 'available' },
+                { memberId: view.humanMemberId, kind: 'human', handle: AGENT_TEAM_HUMAN_HANDLE, description: 'Human Team Member', presence: 'available' },
                 ...host.members().filter(status => visibleMemberIds.has(status.member.memberId)).map(status => ({ memberId: status.member.memberId,
                     kind: 'agent', handle: status.member.handle, description: status.member.description, presence: status.presence })),
             ],

package/packages/tool-agent-team/lib/types/host-access.d.ts

@@ -5,10 +5,20 @@
  * rejection rather than a silent no-op. Both messages are user-facing text.
  */
 import AgentTeam from '@wowyuarm/dsh-agent-team/host';
+import type { WorkspaceId } from '@deepseek-ai/dsh-api-workspace-controller/client';
 /** The Agent shape every Team tool receives. */
 export type TeamToolAgent = NonNullable<Parameters<AgentTeam['memberForAgent']>[0]>;
 /** Resolve the Team Host service, or reject the tool call. */
 export declare function service(agent: TeamToolAgent): AgentTeam;
 /** Resolve the calling Team Member, or reject the tool call. */
 export declare function member(agent: TeamToolAgent): import("@wowyuarm/dsh-agent-team/types").AgentTeamAgentMember;
+/** A collaboration address, never a cwd or Session switch. */
+export declare const workspaceParam: {
+    type: "string";
+    description: string;
+};
+/** Reject ambiguous routing before a tool reads facts or attempts a mutation. */
+export declare function workspaceOf(args: {
+    workspace?: string | undefined;
+}, agent: TeamToolAgent): WorkspaceId;
 //# sourceMappingURL=host-access.d.ts.map

package/packages/tool-agent-team/lib/types/host-access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-access.d.ts","sourceRoot":"","sources":["../../src/host-access.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,SAAS,MAAM,+BAA+B,CAAA;AAErD,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAEnF,8DAA8D;AAC9D,wBAAgB,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAIvD;AAED,gEAAgE;AAChE,wBAAgB,MAAM,CAAC,KAAK,EAAE,aAAa,iEAI1C"}
+{"version":3,"file":"host-access.d.ts","sourceRoot":"","sources":["../../src/host-access.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,SAAS,MAAM,+BAA+B,CAAA;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAA;AAEnF,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAEnF,8DAA8D;AAC9D,wBAAgB,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAIvD;AAED,gEAAgE;AAChE,wBAAgB,MAAM,CAAC,KAAK,EAAE,aAAa,iEAI1C;AAED,8DAA8D;AAC9D,eAAO,MAAM,cAAc;;;CAG1B,CAAA;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAAE,KAAK,EAAE,aAAa,GAAG,WAAW,CAUvG"}

package/packages/tool-agent-team/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAelD,eAAO,MAAM,IAAI,8BAA8B,CAAA;AAC/C,eAAO,MAAM,MAAM,UAAY,CAAA;AAupB/B,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAOxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAelD,eAAO,MAAM,IAAI,8BAA8B,CAAA;AAC/C,eAAO,MAAM,MAAM,UAAY,CAAA;AA8qB/B,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAOxC"}