@wowyuarm/dsh-agent-team 0.1.8 → 0.1.9

package/packages/tool-agent-team/lib/context-tools.js

@@ -0,0 +1,179 @@
+/**
+ * Model-facing context-management tools for Team Members. Thin adapters
+ * only: validation runs in the Host adapter, the successful result is the
+ * durable intent, and every lifecycle side effect — generation swap, Session
+ * creation, inbox handling — happens in the Host coordinator after the
+ * result is durably appended. `concludeTurn()` rides the success result of
+ * `context_rollover` and `context_checkpoint`, so sibling calls settle in model
+ * order before the turn closes.
+ * @module @wowyuarm/dsh-agent-team/context-tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+function service(agent) {
+    const host = agent.ctx.get('agentTeam');
+    if (host === undefined)
+        throw new Error('Agent Team Host is unavailable');
+    return host;
+}
+function member(agent) {
+    const current = service(agent).memberForAgent(agent);
+    if (current === undefined)
+        throw new Error('team tool requires an active Team Member');
+    return current;
+}
+const MAX_HANDOFF_CHARS = 32 * 1024;
+const MAX_RELATED_FILES = 32;
+const contextRollover = defineTool({
+    name: 'context_rollover',
+    description: 'context_rollover: end this context generation and continue as the same Team Member in a new one. Without checkpointRef the context starts fresh and empty, seeded only by your handoff — this is the default, cheapest path at context pressure, and the right choice for ordinary generation changes and pressure-driven handoffs. Omit checkpointRef unless you are deliberately returning to a restorable anchor you just selected from a context_timeline result: supply a checkpointRef only when that timeline listed it as restorable and you are citing its exact ref — never synthesize, guess, or reconstruct one; a fabricated ref rejects as a model-visible error. Write the handoff as one prose string covering: current objective and every active Thread/Claim; verified facts and evidence; inferences and unresolved conflicts; current external side effects and their verification state (files, git, jobs, browser state, remote calls); one explicit next step. A context change never rolls back any external effect — describe current state so the next generation can re-verify. Record anything worth keeping in your private memory/notes first. Collect or stop your background jobs before calling: a rollover is refused while jobs this Member owns are still running.',
+    parameters: {
+        handoff: { type: 'string', required: true, description: 'Prose handoff for the next context generation: objective, active Threads/Claims, verified facts, inferences, external side effects and their verification state, next step.' },
+        checkpointRef: { type: 'string', description: 'Optional. Omit for the default fresh rollover — ordinary generation changes and pressure-driven handoffs must not supply this. Provide it only to resume from a restorable anchor you just selected in a context_timeline result, citing that exact ref; never synthesize or guess a ref.' },
+        relatedFiles: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', required: true }, reason: { type: 'string', required: true } } }, description: 'Workspace paths the next generation should look at first, each with one reason.' },
+    },
+    output: {
+        schema: { type: 'object', additionalProperties: false, properties: {
+                mode: { type: 'string', required: true }, status: { type: 'string', required: true },
+            } },
+        render: (_args, value) => [{ type: 'text', text: `Context rollover scheduled (${value.mode}). Finish this turn; the Host switches you to the next context generation afterward.` }],
+    },
+    async execute(args, exec) {
+        const agent = exec.agent;
+        if (agent === undefined)
+            throw new Error('context_rollover requires an Agent session');
+        const current = member(agent);
+        const host = service(agent);
+        const handoff = typeof args.handoff === 'string' ? args.handoff : '';
+        if (handoff.trim() === '')
+            throw new Error('context_rollover requires a non-empty handoff');
+        if (handoff.length > MAX_HANDOFF_CHARS)
+            throw new Error(`context_rollover handoff exceeds ${MAX_HANDOFF_CHARS} characters`);
+        const relatedFilesInput = Array.isArray(args.relatedFiles) ? args.relatedFiles : [];
+        if (relatedFilesInput.length > MAX_RELATED_FILES)
+            throw new Error(`context_rollover accepts at most ${MAX_RELATED_FILES} related files`);
+        // Tool argument validation is layered: the Harness schema (required and
+        // type checks) rejects at the execute boundary, and this body adds the
+        // checks the schema cannot express — each related file is validated
+        // here, so a blank path/reason rejects instead of seeding the handoff
+        // envelope with empty fields.
+        const relatedFiles = [];
+        for (const [index, entry] of relatedFilesInput.entries()) {
+            if (typeof entry !== 'object' || entry === null)
+                throw new Error(`context_rollover relatedFiles[${index}] must be an object with path and reason`);
+            const candidate = entry;
+            if (typeof candidate.path !== 'string' || candidate.path.trim() === '')
+                throw new Error(`context_rollover relatedFiles[${index}].path must be a non-empty string`);
+            if (typeof candidate.reason !== 'string' || candidate.reason.trim() === '')
+                throw new Error(`context_rollover relatedFiles[${index}].reason must be a non-empty string`);
+            relatedFiles.push({ path: candidate.path, reason: candidate.reason });
+        }
+        // Tool schemas are open at the root (Harness parameter specs set no
+        // `additionalProperties: false`), so an undeclared shape can still reach
+        // the body. Any supplied value that is not a non-empty string rejects
+        // here rather than being treated as absent — an absent ref means fresh,
+        // which is not what the model asked for.
+        const raw = args;
+        const suppliedRef = Object.hasOwn(raw, 'checkpointRef') ? raw.checkpointRef : undefined;
+        if (suppliedRef !== undefined && (typeof suppliedRef !== 'string' || suppliedRef.trim() === '')) {
+            throw new Error('context_rollover checkpointRef must be a non-empty string when supplied');
+        }
+        const checkpointRef = typeof suppliedRef === 'string' ? suppliedRef.trim() : undefined;
+        const outcome = await host.requestNewContext(agent, {
+            memberId: current.memberId,
+            ...(checkpointRef === undefined || checkpointRef === '' ? {} : { checkpointRef: checkpointRef }),
+            ...(relatedFiles.length === 0 ? {} : { relatedFiles }),
+        });
+        exec.concludeTurn();
+        return { mode: outcome.mode, status: 'scheduled' };
+    },
+});
+const contextCheckpoint = defineTool({
+    name: 'context_checkpoint',
+    description: 'Record a named checkpoint at the end of the current turn: an opaque, private, restorable anchor for this Member\'s context lineage. Use it before a noisy or risky phase — a broad refactor, an experiment whose value is unproven — when returning to the current completed state may later be useful. The checkpoint resolves only when this turn completes; the Host continues work in the next turn automatically. A checkpoint never snapshots files, git, jobs, or any external state: returning to one (via context_rollover with its checkpointRef) resumes the conversation prefix and nothing else. Checkpoints are private context structure, not Team facts, and are never visible to other Members.',
+    parameters: {
+        name: { type: 'string', required: true, description: 'Short semantic label for this checkpoint, shown in context_timeline.' },
+    },
+    output: {
+        schema: { type: 'object', additionalProperties: false, properties: {
+                checkpointRef: { type: 'string', required: true }, name: { type: 'string', required: true },
+            } },
+        // The ref is the selection surface for `context_rollover`: rendering only the
+        // name left the model with no legitimate way to cite the anchor it just
+        // recorded. Renders are the only channel results reach the model through.
+        render: (_args, value) => [{ type: 'text', text: `Checkpoint recorded: ${value.name} (ref: ${value.checkpointRef}). Work continues in the next turn; the Host will continue automatically.` }],
+    },
+    async execute(args, exec) {
+        const agent = exec.agent;
+        if (agent === undefined)
+            throw new Error('context_checkpoint requires an Agent session');
+        const current = member(agent);
+        const host = service(agent);
+        const name = typeof args.name === 'string' ? args.name : '';
+        // The Host validates binding, running-turn fencing, and the name budget;
+        // the durable checkpoint is the successful call/result pair the Session
+        // projection folds, and the ref derives from the tool call id.
+        const outcome = host.recordCheckpointForAgent(agent, { memberId: current.memberId, callId: exec.callId, name });
+        exec.concludeTurn();
+        return { checkpointRef: outcome.checkpointRef, name: outcome.name };
+    },
+});
+const contextTimeline = defineTool({
+    name: 'context_timeline',
+    description: 'Inspect the bounded structural timeline of this Member\'s context lineage: named checkpoints you recorded, Team boundaries (effect anchors: a committed team_message, a successful team_claim mutation, a follow/unfollow — rendered as `Team message`, `Team task claim change`, `Team attention change`; plus a Thread\'s first delivered notice, rendered as `First arrival: <refs>`), handoff and compaction boundaries, and the current head — across the current generation and its archived ancestors. Only the first delivery of a Thread\'s facts anchors; later re-deliveries and reminders produce no boundary. Returns approximate retained/discarded token estimates, current usage against the pressure budget, the Threads whose facts entered your context by each anchor, and which anchors are restorable. A Team boundary is a selectable default checkpoint exactly when it resolved at a completed turn and exactly one Thread is attributable to it; unattributable or multi-Thread boundaries state their reason. Structural only: no transcript content. A fresh context_rollover (no checkpointRef) never requires consulting this timeline first — call it directly. Use this tool only when you specifically intend a checkpointRef return: to pick the smallest sufficient ref, or to confirm that a fresh handoff is the better path when every anchor is marked non-restorable.',
+    parameters: {
+        limit: { type: 'number', description: 'Maximum number of items to return (default 12, at most 24).' },
+    },
+    output: {
+        schema: { type: 'object', additionalProperties: false, properties: {
+                usageTokens: { type: 'number', required: true },
+                hardLimit: { type: 'number', required: true },
+                handoffAt: { type: 'number', required: true },
+                items: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: {
+                            checkpointRef: { type: 'string', required: true },
+                            name: { type: 'string', required: true },
+                            source: { type: 'string', required: true },
+                            retainedTokens: { type: 'number', required: true },
+                            discardedTokens: { type: 'number', required: true },
+                            affectedThreads: { type: 'array', required: true, items: { type: 'string' } },
+                            restorable: { type: 'boolean', required: true },
+                            reason: { type: 'string' },
+                            sourceSessionId: { type: 'string' },
+                        } } },
+            } },
+        // The item list is the whole decision surface: without each anchor's
+        // ref, label, source, size estimates, affected Threads, and
+        // restorable/reason verdict, the model cannot pick a `checkpointRef` for
+        // `context_rollover` — the summary line alone left the tool unusable for
+        // seeded returns. The Host bounds items (default 12, at most 24), so this
+        // list cannot grow unbounded.
+        render: (_args, value) => {
+            const lines = [`Context timeline: ${value.usageTokens} tokens used (handoff at ${value.handoffAt}, hard limit ${value.hardLimit}). ${value.items.length} item(s):`];
+            for (const item of value.items) {
+                const threads = item.affectedThreads.length === 0 ? 'no Threads' : `Threads ${item.affectedThreads.join(', ')}`;
+                const size = `retained ~${item.retainedTokens}, discarded ~${item.discardedTokens}`;
+                const restorable = item.restorable
+                    ? `restorable — ref: ${item.checkpointRef}`
+                    : `not restorable — ${item.reason ?? 'no reason given'}`;
+                lines.push(`- ${item.name} [source: ${item.source}] (${size}; ${threads}) — ${restorable}`);
+            }
+            return [{ type: 'text', text: lines.join('\n') }];
+        },
+    },
+    async execute(args, exec) {
+        const agent = exec.agent;
+        if (agent === undefined)
+            throw new Error('context_timeline requires an Agent session');
+        const current = member(agent);
+        const host = service(agent);
+        const limit = typeof args.limit === 'number' ? args.limit : undefined;
+        const result = await host.contextTimelineForAgent(agent, { memberId: current.memberId, ...(limit === undefined ? {} : { limit }) });
+        // The Host result is deeply immutable; the tool output contract carries
+        // plain arrays, so re-shape without any semantic change.
+        return { usageTokens: result.usageTokens, hardLimit: result.hardLimit, handoffAt: result.handoffAt, items: result.items.map(item => ({ ...item, affectedThreads: [...item.affectedThreads] })) };
+    },
+});
+export function registerContextTools(ctx) {
+    ctx.tools.register(contextRollover);
+    ctx.tools.register(contextCheckpoint);
+    ctx.tools.register(contextTimeline);
+}

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

@@ -1,7 +1,44 @@
 import { AgentTeamDmDeliveryError, markAgentTeamPreset } from '@wowyuarm/dsh-agent-team/host';
+import { registerContextTools } from "./context-tools.js";
 import { defineTool } from '@deepseek-ai/dsh-tools';
 export const name = 'wowyuarm-agent-team-tools';
 export const inject = ['tools'];
+function activityFactView(sequence, activity, markers) {
+    return {
+        sequence, kind: 'activity', activity: activity.kind, actor: activity.actor, taskRef: activity.taskRef,
+        ...(activity.claimRef === undefined ? {} : { claimRef: activity.claimRef }),
+        ...(activity.claimRefs === undefined || activity.claimRefs.length === 0 ? {} : { claimRefs: [...activity.claimRefs] }),
+        ...(activity.completedClaimRefs === undefined || activity.completedClaimRefs.length === 0 ? {} : { completedClaimRefs: [...activity.completedClaimRefs] }),
+        ...(activity.acceptedClaimRefs === undefined || activity.acceptedClaimRefs.length === 0 ? {} : { acceptedClaimRefs: [...activity.acceptedClaimRefs] }),
+        ...(activity.releasedClaimRefs === undefined || activity.releasedClaimRefs.length === 0 ? {} : { releasedClaimRefs: [...activity.releasedClaimRefs] }),
+        ...(markers === undefined ? {} : { unread: markers.unread, direct: markers.direct }),
+    };
+}
+function adviceView(advice) {
+    return {
+        ...(advice.usageTokens === undefined ? {} : { usageTokens: advice.usageTokens }),
+        ...(advice.taskBoundaryThreshold === undefined ? {} : { taskBoundaryThreshold: advice.taskBoundaryThreshold }),
+        ...(advice.handoffAt === undefined ? {} : { handoffAt: advice.handoffAt }),
+        ...(advice.hardLimit === undefined ? {} : { hardLimit: advice.hardLimit }),
+        action: advice.action, guidance: advice.guidance,
+    };
+}
+/** Render one structured activity fact as a self-describing decision-surface line. */
+function activityLine(fact) {
+    const segments = [`${fact.sequence}`, fact.actor, fact.activity];
+    segments.push(`Task ${fact.taskRef}`);
+    if (fact.claimRef !== undefined)
+        segments.push(`Claim ${fact.claimRef}`);
+    if (fact.claimRefs !== undefined)
+        segments.push(`claims released ${fact.claimRefs.join(', ')}`);
+    if (fact.completedClaimRefs !== undefined)
+        segments.push(`completed claims ${fact.completedClaimRefs.join(', ')}`);
+    if (fact.acceptedClaimRefs !== undefined)
+        segments.push(`accepted claims ${fact.acceptedClaimRefs.join(', ')}`);
+    if (fact.releasedClaimRefs !== undefined)
+        segments.push(`released claims ${fact.releasedClaimRefs.join(', ')}`);
+    return segments.join(' ');
+}
 function service(agent) {
     const host = agent.ctx.get('agentTeam');
     if (host === undefined)
@@ -30,8 +67,9 @@ const teamInbox = defineTool({
                             taskNumber: { type: 'number' },
                         } } },
             } },
-        render: (_args, value) => [{ type: 'text', text: value.items.length === 0 ? 'No unread Team work.'
-                    : value.items.map(item => `${item.threadRef}${item.taskRef === undefined ? '' : ` · ${item.taskRef}`}${item.taskNumber === undefined ? '' : ` (#${item.taskNumber})`} · ${item.directCount > 0 ? 'direct' : 'unread'}, ${item.unreadCount} update(s), revision ${item.revision}`).join('\n') }],
+        render: (_args, value) => [{ type: 'text', text: value.items.length === 0 ? `No unread Team work.${value.totalUnreadCount > 0 ? ` (${value.totalUnreadCount} unread on Threads beyond this bounded list — call again with a larger limit.)` : ''}`
+                    : [`${value.totalUnreadCount} unread update(s) total, ${value.totalDirectCount} direct, across ${value.items.length} Thread(s) shown${value.totalUnreadCount > value.items.reduce((sum, item) => sum + item.unreadCount, 0) ? ' — more exist beyond this bounded list' : ''}`,
+                        ...value.items.map(item => `${item.threadRef}${item.channelRef === undefined ? '' : ` · ${item.channelRef}`}${item.taskRef === undefined ? '' : ` · ${item.taskRef}`}${item.taskNumber === undefined ? '' : ` (#${item.taskNumber})`}${item.status === undefined ? '' : ` (${item.status})`} · ${item.unreadCount} unread, ${item.directCount} direct, revision ${item.revision}`)].join('\n') }],
     },
     async execute(args, exec) {
         const agent = exec.agent;
@@ -75,14 +113,56 @@ const teamThread = defineTool({
                             claimRef: { type: 'string', required: true }, direction: { type: 'string', required: true }, state: { type: 'string', required: true }, owner: { type: 'string', required: true },
                         } } },
                 facts: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: {
-                            sequence: { type: 'number', required: true }, kind: { type: 'string', required: true }, body: { type: 'string' }, sender: { type: 'string' }, mentions: { type: 'array', items: { type: 'string' } }, activity: { type: 'string' }, unread: { type: 'boolean' }, direct: { type: 'boolean' },
+                            sequence: { type: 'number', required: true }, kind: { type: 'string', required: true }, body: { type: 'string' }, sender: { type: 'string' }, mentions: { type: 'array', items: { type: 'string' } }, activity: { type: 'string' }, actor: { type: 'string' }, taskRef: { type: 'string' }, claimRef: { type: 'string' }, claimRefs: { type: 'array', items: { type: 'string' } }, completedClaimRefs: { type: 'array', items: { type: 'string' } }, acceptedClaimRefs: { type: 'array', items: { type: 'string' } }, releasedClaimRefs: { type: 'array', items: { type: 'string' } }, unread: { type: 'boolean' }, direct: { type: 'boolean' },
                         } } },
+                contextAdvice: { type: 'object', additionalProperties: false, properties: {
+                        usageTokens: { type: 'number' }, taskBoundaryThreshold: { type: 'number' }, handoffAt: { type: 'number' }, hardLimit: { type: 'number' },
+                        action: { type: 'string', required: true }, guidance: { type: 'string', required: true },
+                    } },
             } },
-        render: (_args, value) => [{ type: 'text', text: value.facts.length === 0
-                    ? `${value.threadRef} · revision ${value.revision}, following=${value.following}`
-                    : [`revision ${value.revision}`, ...value.facts.map(fact => fact.kind === 'message'
-                            ? `${fact.sequence} [${fact.sender ?? 'unknown sender'}] ${fact.body}`
-                            : `${fact.sequence} ${fact.activity}`)].join('\n') }],
+        // Renders are the only channel a tool result reaches the model through:
+        // the header states the Thread ref and the Task's standing, each activity
+        // line names the actor and every Claim the activity concluded, message
+        // facts carry their unread/direct markers so a bounded batch can be
+        // re-read discriminately, an acceptance the reader just acknowledged
+        // carries one context-guidance section, and read/history footers state
+        // what remains or whether older facts exist.
+        render: (_args, value) => {
+            // The header always identifies the Thread first — the ref the model
+            // must echo in its next team_message reply — then the Task's standing
+            // when the Thread is taskful. An empty-facts status/follow result
+            // still carries the same identifying surface.
+            const header = [
+                value.threadRef,
+                value.taskRef === undefined ? '' : `${value.taskRef} · ${value.status}${value.resolution === undefined ? '' : `/${value.resolution}`}`,
+                `revision ${value.revision}, following=${value.following}`,
+            ].filter(part => part !== '').join(' · ');
+            const lines = [header];
+            // The Claims snapshot is the collision surface: another Member's
+            // active Claim on this Task is invisible while facts alone render,
+            // yet exactly what the model must see before claiming its own angle.
+            for (const claim of value.claims)
+                lines.push(`Claim ${claim.claimRef} · ${claim.state} — ${claim.owner}: ${claim.direction}`);
+            // The anchor is the Thread's root task statement. Render it whenever
+            // it is not already among the facts, so a model reading a Thread for
+            // the first time never loses the original ask.
+            if (!value.facts.some(fact => fact.sequence === value.anchor.sequence))
+                lines.push(`Anchor ${value.anchor.sequence} [${value.anchor.sender}] ${value.anchor.body}`);
+            for (const fact of value.facts) {
+                lines.push(fact.kind === 'message'
+                    ? `${fact.sequence} [${fact.sender ?? 'unknown sender'}]${fact.unread === undefined ? '' : fact.direct === true ? ' [direct]' : fact.unread === true ? ' [unread]' : ''} ${fact.body}`
+                    : activityLine(fact));
+                if (fact.kind !== 'message' && fact.unread === true)
+                    lines.push(`${fact.sequence} … (unread activity)`);
+            }
+            if (value.kind === 'read')
+                lines.push(`Read through sequence ${value.readThroughSequence}; ${value.remainingUnreadCount ?? 0} unread update(s) remaining — call team_thread read again${(value.remainingUnreadCount ?? 0) > 0 ? '' : ' when new work arrives'}.`);
+            if (value.kind === 'history')
+                lines.push(`History cursor ${value.cursor}; hasMore=${value.hasMore ? 'true' : 'false'}${value.hasMore ? ' — older facts exist; page again with beforeSequence set to the cursor.' : ' — no older facts remain.'}`);
+            if (value.kind === 'read' && value.contextAdvice !== undefined)
+                lines.push(...adviceLines(value.contextAdvice));
+            return [{ type: 'text', text: lines.join('\n') }];
+        },
     },
     async execute(args, exec) {
         const agent = exec.agent;
@@ -112,14 +192,14 @@ const teamThread = defineTool({
             const status = host.attentionStatusForAgent(agent, base);
             return threadResult('history', 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] }
-                : { sequence: fact.sequence, kind: 'activity', activity: fact.activity.kind }), { cursor: history.cursor, hasMore: history.hasMore });
+                : activityFactView(fact.sequence, fact.activity)), { cursor: history.cursor, hasMore: history.hasMore });
         }
         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'
             ? { 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 }
-            : { sequence: entry.fact.sequence, kind: 'activity', activity: entry.fact.activity.kind, unread: entry.unread, direct: entry.direct }), { readThroughSequence: read.readThroughSequence, remainingUnreadCount: read.remainingUnreadCount });
+            : activityFactView(entry.fact.sequence, entry.fact.activity, { unread: entry.unread, direct: entry.direct })), { readThroughSequence: read.readThroughSequence, remainingUnreadCount: read.remainingUnreadCount, ...(read.contextAdvice === undefined ? {} : { contextAdvice: adviceView(read.contextAdvice) }) });
     },
 });
 function threadResult(kind, snapshot, attention, facts, extra = {}) {
@@ -134,6 +214,14 @@ function threadResult(kind, snapshot, attention, facts, extra = {}) {
         facts,
     };
 }
+/** Render one read-time acceptance advice; unavailable never prints a fabricated number. */
+function adviceLines(advice) {
+    const measured = advice.usageTokens !== undefined && advice.taskBoundaryThreshold !== undefined && advice.handoffAt !== undefined && advice.hardLimit !== undefined;
+    const summary = measured
+        ? `${advice.usageTokens.toLocaleString('en-US')} tokens used; Task-boundary threshold ${advice.taskBoundaryThreshold.toLocaleString('en-US')}; normal handoff at ${advice.handoffAt.toLocaleString('en-US')}; hard limit ${advice.hardLimit.toLocaleString('en-US')}.`
+        : 'Context usage could not be measured for this acceptance.';
+    return [`Context guidance — ${summary}`, `Action: ${advice.action}. ${advice.guidance}`];
+}
 const teamMessage = markAgentTeamPreset(defineTool({
     name: 'team_message',
     description: 'Start a top-level Thread, reply to an existing Thread, or send a direct message (DM). start defaults to a taskless Thread; pass asTask true to create a Task in the same send. Read the Thread first; replies require its current revision (an internal concurrency token carried by baseRevision, never quoted in bodies). 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.',
@@ -155,8 +243,18 @@ const teamMessage = markAgentTeamPreset(defineTool({
                 recipientMemberId: { type: 'string' }, recipientHandle: { type: 'string' }, delivered: { type: 'boolean' }, deliveryNote: { type: 'string' },
             } },
         render: (_args, value) => [{ type: 'text', text: value.kind === 'dm-sent' ? `DM ${value.delivered === false ? 'recorded but not delivered' : 'delivered'} to @${value.recipientHandle} (${value.recipientMemberId})${value.deliveryNote === undefined ? '' : `: ${value.deliveryNote}`}`
-                    : value.kind === 'committed' ? `Message ${value.messageRef} committed at revision ${value.revision}.`
-                        : `${value.kind}: ${value.memberIds?.join(', ') ?? `${value.threadRef ?? ''}${value.taskRef === undefined ? '' : ` · Task ${value.taskRef}`} revision ${value.revision ?? ''}`}` }],
+                    : value.kind === 'committed' ? `Message ${value.messageRef} committed at revision ${value.revision} on ${value.threadRef}${value.taskRef === undefined ? '' : ` (${value.taskRef})`}.`
+                        : value.kind === 'unread_required' ? `unread_required: ${value.threadRef}${value.taskRef === undefined ? '' : ` (${value.taskRef})`} has ${value.unreadCount} unread update(s), ${value.directCount} direct at revision ${value.revision}. Read the pending updates (team_thread read) before retrying this send.`
+                            : value.kind === 'stale_revision' ? `stale_revision: your baseRevision ${value.expectedRevision} is obsolete; ${value.threadRef}${value.taskRef === undefined ? '' : ` (${value.taskRef})`} is now at revision ${value.revision}. Read the Thread, then retry with baseRevision ${value.revision}.`
+                                : value.kind === 'member_not_following' ? `member_not_following: ${(value.memberIds ?? []).join(', ')} not following; the message was not committed. Only a Human can invite an unfollowed Agent — retry without mentioning them, or ask the Human.`
+                                    : `${value.kind}: ${value.memberIds?.join(', ') ?? `${value.threadRef ?? ''}${value.taskRef === undefined ? '' : ` · Task ${value.taskRef}`} revision ${value.revision ?? ''}`}` }],
+        // Minimal durable projection for the Host's context timeline: the
+        // structured outcome identity (never the render text). The effect-anchor
+        // fold reads `kind === 'committed'` + threadRef from the persisted
+        // tool/result meta — a start's Thread is born here, in the result.
+        presentationMeta: (_args, value) => value.kind === 'committed' && value.threadRef !== undefined
+            ? { kind: value.kind, threadRef: value.threadRef, ...(value.taskRef === undefined ? {} : { taskRef: value.taskRef }) }
+            : { kind: value.kind },
     },
     async execute(args, exec) {
         const agent = exec.agent;
@@ -236,8 +334,14 @@ const teamClaim = defineTool({
                 unreadCount: { type: 'number' }, directCount: { type: 'number' },
                 claims: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: { claimRef: { type: 'string', required: true }, direction: { type: 'string', required: true }, state: { type: 'string', required: true }, owner: { type: 'string', required: true } } } },
             } },
-        render: (_args, value) => [{ type: 'text', text: [`${value.kind}: ${value.taskRef} · ${value.status}, revision ${value.revision}`,
-                    ...value.claims.map(claim => `${claim.claimRef} · ${claim.state} — ${claim.owner}: ${claim.direction}`)].join('\n') }],
+        render: (_args, value) => [{ type: 'text', text: [
+                    value.kind === 'unread_required'
+                        ? `unread_required: ${value.taskRef} (${value.threadRef}) has ${value.unreadCount} unread update(s), ${value.directCount} direct at revision ${value.revision}. Read the pending updates (team_thread read) before retrying this Claim mutation.`
+                        : value.kind === 'stale_revision'
+                            ? `stale_revision: your baseRevision ${value.expectedRevision} is obsolete; ${value.taskRef} (${value.threadRef}) is now at revision ${value.revision}. Read the Thread, then retry with baseRevision ${value.revision}.`
+                            : `${value.kind}: ${value.taskRef} (${value.threadRef}) · ${value.status}, revision ${value.revision}`,
+                    ...value.claims.map(claim => `${claim.claimRef} · ${claim.state} — ${claim.owner}: ${claim.direction}`)
+                ].join('\n') }],
     },
     async execute(args, exec) {
         const agent = exec.agent;
@@ -276,7 +380,7 @@ const teamClaim = defineTool({
 });
 const teamView = defineTool({
     name: 'team_view',
-    description: 'Discover authorized Team Channels, Tasks, and Members. It is not a substitute for team_thread reading.',
+    description: 'Discover authorized Team Channels, top-level Threads, Tasks, and Members. It is not a substitute for team_thread reading.',
     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' },
@@ -287,15 +391,23 @@ const teamView = defineTool({
                 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 },
                         } } },
+                threads: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: {
+                            threadRef: { type: 'string', required: true }, channelRef: { type: 'string', required: true }, revision: { type: 'number', required: true }, messageCount: { type: 'number', required: true },
+                            taskRef: { type: 'string' }, status: { type: 'string' }, taskNumber: { type: 'number' },
+                        } } },
                 tasks: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: { taskRef: { type: 'string', required: true }, threadRef: { type: 'string', required: true }, channelRef: { type: 'string', required: true }, status: { type: 'string', required: true }, revision: { type: 'number', required: true } } } },
                 cursor: { type: 'number', required: true }, hasMore: { type: 'boolean', required: true },
             } },
         render: (_args, value) => [{ type: 'text', text: [
                     ...value.channels.map(channel => `${channel.channelRef} · ${channel.name}`),
                     ...value.members.map(m => `${m.memberId} · ${m.handle} (${m.kind}, ${m.presence})${m.description === '' ? '' : ` — ${m.description}`}`),
+                    ...(value.threads.length > 0
+                        ? value.threads.map(thread => `${thread.threadRef} · ${thread.channelRef}${thread.taskRef === undefined ? '' : ` · ${thread.taskRef}${thread.taskNumber === undefined ? '' : ` (#${thread.taskNumber})`} (${thread.status})`} · ${thread.messageCount} message(s), revision ${thread.revision}`)
+                        : ['No Team Threads.']),
                     ...(value.tasks.length > 0
-                        ? value.tasks.map(task => `${task.taskRef} · ${task.status}`)
+                        ? value.tasks.map(task => `${task.taskRef} · ${task.threadRef} · ${task.channelRef} · ${task.status}, revision ${task.revision}`)
                         : ['No Team Tasks.']),
+                    `cursor ${value.cursor}, hasMore=${value.hasMore ? 'true' : 'false'}${value.hasMore ? ' — more items exist; call team_view again with cursor set to this value.' : ' — no further pages.'}`,
                 ].join('\n') }],
     },
     async execute(args, exec) {
@@ -313,6 +425,12 @@ const teamView = defineTool({
                 ...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 })),
             ],
+            threads: view.items.map(item => {
+                const thread = item.thread;
+                const task = item.task;
+                return { threadRef: thread.threadRef, channelRef: item.message.channelRef, revision: thread.revision, messageCount: item.messageCount,
+                    ...(task === undefined ? {} : { taskRef: task.taskRef, status: task.status, ...(item.taskNumber === undefined ? {} : { taskNumber: item.taskNumber }) }) };
+            }),
             tasks: view.tasks.map(task => ({ taskRef: task.taskRef, threadRef: task.threadRef, channelRef: task.channelRef,
                 status: task.status, revision: view.threads.find(thread => thread.threadRef === task.threadRef)?.revision ?? 0 })),
             cursor: view.cursor, hasMore: view.hasMore,
@@ -325,4 +443,5 @@ export function apply(ctx) {
     ctx.tools.register(teamMessage);
     ctx.tools.register(teamClaim);
     ctx.tools.register(teamView);
+    registerContextTools(ctx);
 }

package/packages/tool-agent-team/lib/types/context-tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Model-facing context-management tools for Team Members. Thin adapters
+ * only: validation runs in the Host adapter, the successful result is the
+ * durable intent, and every lifecycle side effect — generation swap, Session
+ * creation, inbox handling — happens in the Host coordinator after the
+ * result is durably appended. `concludeTurn()` rides the success result of
+ * `context_rollover` and `context_checkpoint`, so sibling calls settle in model
+ * order before the turn closes.
+ * @module @wowyuarm/dsh-agent-team/context-tools
+ */
+export declare function registerContextTools(ctx: {
+    readonly tools: {
+        register(tool: unknown): void;
+    };
+}): void;
+//# sourceMappingURL=context-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-tools.d.ts","sourceRoot":"","sources":["../../src/context-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoKH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,CAIrG"}

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;AAWlD,eAAO,MAAM,IAAI,8BAA8B,CAAA;AAC/C,eAAO,MAAM,MAAM,UAAY,CAAA;AAwT/B,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAMxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAalD,eAAO,MAAM,IAAI,8BAA8B,CAAA;AAC/C,eAAO,MAAM,MAAM,UAAY,CAAA;AAmd/B,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAOxC"}