@wowyuarm/dsh-agent-team 0.1.15 → 0.2.1

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

@@ -1,197 +1,181 @@
 /**
- * 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.
+ * Model-facing context-management tools for Team Members.
+ *
+ * All four are the published engine's tools, built by `createContinuityTools`:
+ * the engine owns their argument contract, the anti-forgery gate on a cited ref,
+ * the `concludeTurn()` timing, and the render shapes, while the Team supplies
+ * its own vocabulary (`TEAM_CONTINUITY_TEXT`) and the mechanism behind
+ * `ContinuityToolAdapter`. Hand-written copies of those descriptions used to
+ * live here and drifted from the engine's defaults, so the Team's guidance now
+ * travels only through the engine's text seams — including the Team glossary the
+ * engine splices into `context_status` as `timelineGuidance`.
+ *
+ * One Team rule survives only in the adapter: for a row the engine renders as
+ * not restorable it prints that row's `ref` verbatim (`brief` truncates at 120
+ * characters, and a Team ref is 83), and a printed ref is exactly what a model
+ * copies into `checkpointRef`. The adapter therefore answers such a row with a
+ * short digest instead of its ref — the same digest that keeps two rows sharing
+ * a label and a price apart — so no non-selectable row carries a citable string.
  * @module @wowyuarm/dsh-agent-team/context-tools
  */
 import { createHash } from 'node:crypto';
-import { defineTool } from '@deepseek-ai/dsh-tools';
+import { compactibleNow, createContinuityTools, } from '@wowyuarm/dsh-context-continuity';
+import { MAX_TIMELINE_LIMIT } from '@wowyuarm/dsh-agent-team/host';
 import { member, service } from "./host-access.js";
-const MAX_HANDOFF_CHARS = 32 * 1024;
-const MAX_RELATED_FILES = 32;
 /**
  * Short stable identifier for one timeline row: a digest of the anchor's own
  * ref. Rows routinely share a label (`Team message` is a constant) and a price
  * (the same completed turn prices both), so without it two distinct anchors
- * read as one duplicated row. Deliberately NOT the ref and deliberately not
- * actionable: a ref only means something on a restorable row, which prints it
- * in full for `context_rollover`.
+ * read as one duplicated row. It is also what a row that is NOT restorable
+ * answers as its `ref`, because the engine's render prints that field for every
+ * row: a ref only means something on a restorable row, which prints it in full
+ * for `context_rollover`.
  */
 function anchorId(checkpointRef) {
     return createHash('sha256').update(checkpointRef).digest('hex').slice(0, 6);
 }
-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.` }],
+/** The calling Agent, or a model-visible rejection — these tools only exist in a Member Session. */
+function agentOf(exec) {
+    const agent = exec.agent;
+    if (agent === undefined)
+        throw new Error('context tool requires an Agent session');
+    return agent;
+}
+/**
+ * The compaction capability in one calling Agent's preset scope, priced by the
+ * same meter the pressure policy reads. The Host owns the address: a preset
+ * revision publishes its services behind its own isolate, so the engine is asked
+ * for through the one method that knows which realm holds it. A Member whose
+ * composition mounts none reports "not available in this scope" — never a
+ * failure, never a silent no-op.
+ *
+ * The meter travels with the scope because two engine decisions read it: how
+ * much of the newest surface a compaction keeps verbatim, and the price a status
+ * reports for a compaction started now. A scope without one still compacts —
+ * keeping the newest instruction and everything after it — and prices nothing.
+ */
+function compactionScopeFor(agent) {
+    const engine = service(agent).compactionForAgent(agent);
+    if (engine === undefined)
+        return undefined;
+    const meter = agent.ctx.get('tokenMeter');
+    return { engine, ...(meter === undefined ? {} : { meter }) };
+}
+/**
+ * One Host timeline item in the engine's own vocabulary. Team's four sources
+ * collapse onto the engine's three kinds, and the two that say something a
+ * reader needs (`handoff`, `compaction`) ride its opaque `kind` field rather
+ * than being flattened silently.
+ *
+ * The `ref` of a row that is not restorable is a short digest rather than the
+ * ref itself: the engine's render prints this field on every row, and a printed
+ * ref is what a model copies into `checkpointRef`. Only a restorable row — the
+ * one kind of row whose ref `context_rollover` accepts — carries a citable
+ * string.
+ */
+export function engineTimelineItems(items) {
+    return items.map(item => ({
+        ref: item.restorable ? item.checkpointRef : anchorId(item.checkpointRef),
+        label: item.name,
+        source: item.source === 'agent' ? 'checkpoint' : item.source === 'head' ? 'head' : 'boundary',
+        ...(item.source === 'handoff' || item.source === 'compaction' ? { kind: item.source } : {}),
+        retainedTokens: item.retainedTokens,
+        discardedTokens: item.discardedTokens,
+        affectedTopics: [...item.affectedThreads],
+        restorable: item.restorable,
+        ...(item.reason === undefined ? {} : { reason: item.reason }),
+    }));
+}
+/**
+ * Team's half of the engine's contract: resolve the calling execution to its
+ * Member and Host, answer the ref gate from the one policy that owns it, and run
+ * the effects. Every method resolves its own caller, because one adapter serves
+ * all four tools.
+ */
+const adapter = {
+    /**
+     * One policy, two readers: a ref is restorable exactly when the Team timeline
+     * — the same list the model picked from — offers it as such. The walk is asked
+     * for the widest window `context_status` can show, so any ref a status read
+     * could have printed is answered here.
+     */
+    async isRestorableRef(checkpointRef, exec) {
+        const agent = agentOf(exec);
+        const current = member(agent);
+        const timeline = await service(agent).contextTimelineForAgent(agent, { memberId: current.memberId, limit: MAX_TIMELINE_LIMIT });
+        return timeline.items.some(item => item.checkpointRef === checkpointRef && item.restorable);
     },
-    async execute(args, exec) {
-        const agent = exec.agent;
-        if (agent === undefined)
-            throw new Error('context_rollover requires an Agent session');
+    async requestRollover(request, exec) {
+        const agent = agentOf(exec);
         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, {
+        // The engine already validated the argument shape and the cited ref; the
+        // Host owns the durable intent and the generation swap that follows it at
+        // the idle boundary.
+        const outcome = await service(agent).requestNewContext(agent, {
             memberId: current.memberId,
-            ...(checkpointRef === undefined || checkpointRef === '' ? {} : { checkpointRef: checkpointRef }),
-            ...(relatedFiles.length === 0 ? {} : { relatedFiles }),
+            ...(request.checkpointRef === undefined ? {} : { checkpointRef: request.checkpointRef }),
+            ...(request.relatedFiles.length === 0 ? {} : { relatedFiles: [...request.relatedFiles] }),
         });
-        exec.concludeTurn();
-        return { mode: outcome.mode, status: 'scheduled' };
+        return { mode: outcome.mode };
     },
-});
-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');
+    async recordCheckpoint(request, exec) {
+        const agent = agentOf(exec);
         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();
+        const outcome = service(agent).recordCheckpointForAgent(agent, { memberId: current.memberId, callId: request.callId, name: request.name });
         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 the retained prefix through it stays inside one Thread and the return would shrink the working set below the handoff budget; a boundary spanning several Threads, or attributable to none, states its reason instead. Every row carries a short `anchor` id: it distinguishes rows that share a label and a price, and it is NOT a ref — only the `checkpointRef` printed on a restorable row may be cited to context_rollover. 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' },
-                        } } },
-                incompleteFrom: { type: 'object', additionalProperties: false, properties: {
-                        sessionId: { type: 'string', required: true },
-                        reason: { type: 'string', required: true },
-                    } },
-            } },
-        // 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 short anchor id distinguishes rows that share a
-        // label and a price without ever printing a ref that is not usable. The
-        // Host bounds items (default 12, at most 24), so the list cannot grow
-        // unbounded. `incompleteFrom` states where and why the lineage walk
-        // stopped early, so history read up to that ancestor is known to be a
-        // truncation, not everything that exists.
-        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}; anchor ${anchorId(item.checkpointRef)}] (${size}; ${threads}) — ${restorable}`);
-            }
-            if (value.incompleteFrom !== undefined) {
-                lines.push(`History incomplete: the lineage walk stopped at Session ${value.incompleteFrom.sessionId} (${value.incompleteFrom.reason}); ancestors before it could not be read and are not reflected above.`);
-            }
-            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');
+    async timeline(request, exec) {
+        const agent = agentOf(exec);
         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.
+        const result = await service(agent).contextTimelineForAgent(agent, {
+            memberId: current.memberId,
+            ...(request.limit === undefined ? {} : { limit: request.limit }),
+        });
+        // "This scope cannot price a compaction" and "a compaction would replace
+        // nothing" are different facts, and only the second is worth showing, so an
+        // unpriced scope omits the field and the status omits its line.
+        const scope = compactionScopeFor(agent);
+        const compactible = scope === undefined ? undefined : compactibleNow(agent.session, scope);
         return {
             usageTokens: result.usageTokens,
-            hardLimit: result.hardLimit,
             handoffAt: result.handoffAt,
-            items: result.items.map(item => ({ ...item, affectedThreads: [...item.affectedThreads] })),
+            hardLimit: result.hardLimit,
+            ...(compactible === undefined ? {} : { compactible }),
+            items: engineTimelineItems(result.items),
             ...(result.incompleteFrom === undefined ? {} : { incompleteFrom: result.incompleteFrom }),
         };
     },
-});
+    compactionFor(agent) {
+        return compactionScopeFor(agent);
+    },
+};
+/**
+ * Team vocabulary for the engine's tools. `carriedContext` names the channels a
+ * fresh generation already receives — without it the engine's "seeded only by
+ * your handoff" sentence reads as "everything must be restated", which is what
+ * our own corpus showed members doing. The checklist carries the one item the
+ * engine's default does not ask for and the corpus showed missing: which facts
+ * were verified and which were only trusted. `timelineGuidance` is the glossary
+ * the engine splices into `context_status`: the engine names the structure, and
+ * only the Team can say what its own rows mean.
+ */
+const TEAM_CONTINUITY_TEXT = {
+    subjectNoun: 'Team Member',
+    carriedContext: 'You stay the same Team Member: your @handle and role, your private memory index, your skills catalog, and the Team and Workspace instructions carry across a rollover — they are re-injected at birth — and the Team ledger (Threads, Tasks, Claims, your inbox, your owner jobs) is one query away (team_view, team_inbox). Do not restate any of it.',
+    rolloverChecklist: 'the objective and the atomic action in flight; facts and evidence not already recorded elsewhere; which items you verified and which you only trusted; inferences and unresolved conflicts; current external side effects and their verification state (files, git, jobs, browser state, remote calls); one explicit next step',
+    timelineGuidance: ' Team rows carry Team sources: `checkpoint` is one you recorded, `boundary` is a Team boundary this Host contributed — a committed team_message, a successful team_claim mutation, or a follow/unfollow, rendered as `Team message`, `Team task claim change`, `Team attention change` — and `head` is the current generation. A Thread\'s first delivered notice is a boundary too, rendered `First arrival: <refs>`; later re-deliveries and reminders produce none. A Team boundary is a selectable default exactly when the retained prefix through it stays inside one Thread and the return would shrink the working set below the handoff budget; a boundary spanning several Threads, or attributable to none, states its reason instead. The `anchor` shown on a row that is not restorable is a short digest, never a ref: cite only a ref printed on a restorable row.',
+    topicNoun: 'Thread',
+    topicNounPlural: 'Threads',
+};
+const engineTools = createContinuityTools(adapter, TEAM_CONTINUITY_TEXT);
 export function registerContextTools(ctx) {
-    ctx.tools.register(contextRollover);
-    ctx.tools.register(contextCheckpoint);
-    ctx.tools.register(contextTimeline);
+    // The engine's four, and nothing else: the roster the Host validates against
+    // carries the same names, so no description names a tool this surface lacks.
+    ctx.tools.register(engineTools.rollover);
+    ctx.tools.register(engineTools.checkpoint);
+    ctx.tools.register(engineTools.status);
+    ctx.tools.register(engineTools.compact);
 }

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

@@ -114,7 +114,7 @@ function rejectionLines(noun, value) {
 }
 const teamInbox = defineTool({
     name: 'team_inbox',
-    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.',
+    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. This is your own unread queue; to see work others have in flight (whether or not you have unread on it), use the active-task-threads section of team_view.',
     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: {
@@ -554,7 +554,7 @@ const teamClaim = defineTool({
 });
 const teamView = defineTool({
     name: 'team_view',
-    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.',
+    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), current Members, and an「active task threads」section listing the work in flight right now — every in_progress / in_review Task Thread in your Channels, with its subject and the Members already on it. This is an address book, not a work queue: unread work lives in team_inbox, and a Thread is read with team_thread read. Consult the active-task-threads section when a Workspace change surprises you, or before you claim or commit, to tell in-flight work from a real conflict and avoid riding onto someone else\'s unpushed work — it is independent of your own unread. 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' }, workspace: workspaceParam,
@@ -571,6 +571,11 @@ const teamView = defineTool({
                             threadRef: { type: 'string', required: true }, channelRef: { type: 'string', required: true }, revision: { type: 'number', required: true }, messageCount: { type: 'number', required: true }, subject: { type: 'string', required: true },
                             taskRef: { type: 'string' }, status: { type: 'string' }, taskNumber: { type: 'number' }, lastActivityAt: { type: 'string' },
                         } } },
+                activeTaskThreads: { 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 }, subject: { type: 'string', required: true },
+                            taskNumber: { type: 'number' }, lastActivityAt: { type: 'string', required: true },
+                            members: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: { memberId: { type: 'string', required: true }, name: { type: 'string', required: true } } } },
+                        } } },
                 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' } } } },
                 cursor: { type: 'number', required: true }, hasMore: { type: 'boolean', required: true }, page: { type: 'string' },
             } },
@@ -608,6 +613,12 @@ const teamView = defineTool({
                     lines.push('No visible Members.');
                 else
                     lines.push(...value.members.map(m => `${m.memberId} · @${m.handle} (${m.kind}, ${m.presence})${m.description === '' ? '' : ` — ${m.description}`}`));
+                lines.push('', 'Active task threads — work in flight right now');
+                if (value.activeTaskThreads.length === 0)
+                    lines.push('No task thread is in flight in this Workspace.');
+                else
+                    lines.push(...value.activeTaskThreads.map(t => `${t.threadRef} · ${t.channelRef} · ${t.status}${t.taskNumber === undefined ? '' : ` · #${t.taskNumber}`}${t.members.length === 0 ? '' : ` · ${t.members.map(m => `@${m.name}`).join(', ')}`} — ${t.subject} · last activity ${formatTeamTimestamp(t.lastActivityAt)}`));
+                lines.push('Use this when a Workspace change surprises you, or before you claim or commit — to see who is already on a Task rather than riding onto their in-flight work. It is not the unread queue; unread work still lives in team_inbox.');
             }
             return [{ type: 'text', text: lines.join('\n') }];
         },
@@ -645,6 +656,10 @@ const teamView = defineTool({
                 return { taskRef: task.taskRef, threadRef: task.threadRef, channelRef: task.channelRef, status: task.status,
                     ...(revision === undefined ? {} : { revision }) };
             }),
+            activeTaskThreads: view.activeTaskThreads.map(t => ({ taskRef: t.taskRef, threadRef: t.threadRef, channelRef: t.channelRef,
+                status: t.status, subject: t.subject, lastActivityAt: t.lastActivityAt,
+                ...(t.taskNumber === undefined ? {} : { taskNumber: t.taskNumber }),
+                members: t.members.map(m => ({ memberId: m.memberId, name: m.name })) })),
             cursor: view.cursor, hasMore: view.hasMore,
             ...(args.cursor === undefined ? {} : { page: 'threads' }),
         };

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

@@ -1,13 +1,38 @@
 /**
- * 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.
+ * Model-facing context-management tools for Team Members.
+ *
+ * All four are the published engine's tools, built by `createContinuityTools`:
+ * the engine owns their argument contract, the anti-forgery gate on a cited ref,
+ * the `concludeTurn()` timing, and the render shapes, while the Team supplies
+ * its own vocabulary (`TEAM_CONTINUITY_TEXT`) and the mechanism behind
+ * `ContinuityToolAdapter`. Hand-written copies of those descriptions used to
+ * live here and drifted from the engine's defaults, so the Team's guidance now
+ * travels only through the engine's text seams — including the Team glossary the
+ * engine splices into `context_status` as `timelineGuidance`.
+ *
+ * One Team rule survives only in the adapter: for a row the engine renders as
+ * not restorable it prints that row's `ref` verbatim (`brief` truncates at 120
+ * characters, and a Team ref is 83), and a printed ref is exactly what a model
+ * copies into `checkpointRef`. The adapter therefore answers such a row with a
+ * short digest instead of its ref — the same digest that keeps two rows sharing
+ * a label and a price apart — so no non-selectable row carries a citable string.
  * @module @wowyuarm/dsh-agent-team/context-tools
  */
+import { type ContextTimelineItem } from '@wowyuarm/dsh-context-continuity';
+import { type AgentTeamTimelineItem } from '@wowyuarm/dsh-agent-team/host';
+/**
+ * One Host timeline item in the engine's own vocabulary. Team's four sources
+ * collapse onto the engine's three kinds, and the two that say something a
+ * reader needs (`handoff`, `compaction`) ride its opaque `kind` field rather
+ * than being flattened silently.
+ *
+ * The `ref` of a row that is not restorable is a short digest rather than the
+ * ref itself: the engine's render prints this field on every row, and a printed
+ * ref is what a model copies into `checkpointRef`. Only a restorable row — the
+ * one kind of row whose ref `context_rollover` accepts — carries a citable
+ * string.
+ */
+export declare function engineTimelineItems(items: readonly AgentTeamTimelineItem[]): ContextTimelineItem[];
 export declare function registerContextTools(ctx: {
     readonly tools: {
         register(tool: unknown): void;

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

@@ -1 +1 @@
-{"version":3,"file":"context-tools.d.ts","sourceRoot":"","sources":["../../src/context-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsLH,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"}
+{"version":3,"file":"context-tools.d.ts","sourceRoot":"","sources":["../../src/context-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAKL,KAAK,mBAAmB,EAIzB,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AA6C9F;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,GAAG,mBAAmB,EAAE,CAYlG;AA0FD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,CAOrG"}

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;AA8qB/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;AA2rB/B,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAOxC"}