@wowyuarm/dsh-agent-team 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowyuarm/dsh-agent-team",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "A persistent agent team for long-running collaboration in DeepSeek Harness",
   "repository": {
     "type": "git",

package/packages/agent-team/core-skills/member-skill-manager/SKILL.md

@@ -7,6 +7,8 @@ description: Create, install, revise, or retire this Member's private skills, in
 
 A skill preserves a reusable way of working. It is not a memory, a personal preference, or a record of one event.
 
+Skills are private to this Member — no other human or agent can read this directory. When a Team message or your session output needs the method, restate the relevant content there; citing a skill by name does not transfer it to anyone.
+
 ## Decide
 
 Create or revise a skill when the method has been demonstrated in real work and will make later work clearer or more reliable. Keep one-off work, changing facts, and personal continuity in this Member's notes and memory index instead.

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

@@ -53,6 +53,7 @@ import { ATTACHMENT_MAX_BYTES, attachmentPayloadPath, attachmentsRoot, copyPathA
 import { acceptedTaskCompactionMembers, AutoCompactionCoordinator, PRE_COMPACTION_NOTICE_SUMMARY, preCompactionNoticeText } from "./auto-compaction.js";
 import { AGENT_TEAM_HUMAN_MEMBER_ID, AgentTeamLedger, agentTeamHumanActor } from "./ledger.js";
 import { AGENT_TEAM_TOOL_NAMES, deepCopyCapabilities, MemberRuntime } from "./member-runtime.js";
+import { ProgressNudgeCoordinator } from "./progress-nudge.js";
 import { classifyRecoverableError, RecoveryCoordinator, RECOVERY_MAX_CONSECUTIVE_ERRORS } from "./recovery.js";
 import { agentTeamDomainSpec } from "./spec.js";
 export { agentTeamDomainSpec, agentTeamOperationSchema } from "./spec.js";
@@ -189,6 +190,8 @@ let AgentTeam = (() => {
         domain = __runInitializers(this, _instanceExtraInitializers);
         ledger;
         handles = new Map();
+        /** Live Member per session id; drives the root session/event listener. */
+        memberBySessionId = new Map();
         /** Live selection refs let model edits take effect without disposing the Session. */
         modelSelections = new Map();
         /** Agent ids with a turn in flight; restarts must wait for the boundary. */
@@ -226,6 +229,22 @@ let AgentTeam = (() => {
                 this.ctx.logger.warn(`agent-team: member '${this.memberLabel(memberId)}' reached ${consecutiveFailures}/${RECOVERY_MAX_CONSECUTIVE_ERRORS} consecutive recoverable failures; leaving it in error for the operator`);
             },
         });
+        /**
+         * Advisory progress-visibility nudges. Purely in-process: the ledger owns
+         * eligibility, this coordinator owns counting and notices, and neither ever
+         * writes Team facts. See docs/team-collaboration.md for the regimes.
+         */
+        progressNudge = new ProgressNudgeCoordinator({
+            agentForMember: memberId => this.handles.get(memberId)?.agent,
+            targetsForMember: memberId => this.requireLedger().progressNudgeTargets(memberId),
+            sessionLogForMember: (memberId, sessionId) => {
+                const handle = this.handles.get(memberId);
+                if (handle === undefined || handle.agent.session.id !== sessionId)
+                    return undefined;
+                return { events: handle.agent.session.ownEvents() };
+            },
+            log: message => { this.ctx.logger.warn(message); },
+        });
         lifecycleTail = Promise.resolve();
         accepting = true;
         changeVersion = 0;
@@ -252,6 +271,10 @@ let AgentTeam = (() => {
                         content: [{ type: 'text', text: preCompactionNoticeText() }],
                         source: { kind: 'plugin', plugin: AGENT_TEAM_PLUGIN_ID, form: 'notice', summary: PRE_COMPACTION_NOTICE_SUMMARY },
                     });
+                    // Persist-your-conclusions outranks a queued progress nudge.
+                    const member = this.memberForAgent(agent);
+                    if (member !== undefined)
+                        this.progressNudge.revokePendingNotice(member.memberId);
                     agent.steer(hint);
                 },
             });
@@ -295,10 +318,28 @@ let AgentTeam = (() => {
                     this.emitChanged([{ kind: 'workspace', workspaceId: member.workspaceId }]);
                 }
             });
+            // Progress nudges count every `tool/call` of each Member Session. The
+            // store's dispatch carrier is untagged, so a scope-tagged listener inside
+            // the Agent setup would receive nothing; one root listener that maps the
+            // session id back to its Member is the seam that works (same shape as the
+            // `agent/status` listener above). The first turn of a freshly published
+            // Member cannot race this: `handles.set()` precedes the same activation
+            // continuation that publishes the Agent, so by the time any tool call
+            // streams, the map lookup succeeds.
+            this.ctx.on('session/event', (session, event) => {
+                const memberId = this.memberBySessionId.get(session.id);
+                if (memberId === undefined)
+                    return;
+                const handle = this.handles.get(memberId);
+                if (handle === undefined || handle.agent.session.id !== session.id)
+                    return;
+                this.progressNudge.onSessionEvent(memberId, session.id, handle.agent, event);
+            });
             const domain = await this.ctx.storageDomain.open(agentTeamDomainSpec);
             this.ctx.effect(() => async () => {
                 this.accepting = false;
                 this.recovery.dispose();
+                this.progressNudge.dispose();
                 await this.autoCompaction.dispose();
                 if (this.attachmentGcTimer !== undefined)
                     clearInterval(this.attachmentGcTimer);
@@ -566,6 +607,10 @@ let AgentTeam = (() => {
                 // Drop the old handle's transient state: pending recovery episodes and
                 // error markers belong to the disposed agent, not to the Member.
                 this.recovery.stopTracking(request.memberId);
+                // The fresh Session may re-earn one Claim suggestion per Thread; the
+                // old Session's one-shot records must not leak into it.
+                this.progressNudge.stopTracking(request.memberId);
+                this.memberBySessionId.delete(previousSessionId);
                 await active.dispose();
                 this.handles.delete(request.memberId);
                 this.modelSelections.delete(request.memberId);
@@ -628,6 +673,9 @@ let AgentTeam = (() => {
                 if (this.isInboxNotice(pending))
                     handle.agent.inbox.remove(pending.id);
             }
+            // Recovery carries the concrete interrupted work; a queued progress nudge
+            // is stale next to it and must not survive as a second reminder.
+            this.progressNudge.revokePendingNotice(member.memberId);
             handle.agent.steer(hint);
         }
         /** Automatic-recovery wakeup; throwing tells the coordinator the target is gone. */
@@ -1090,6 +1138,7 @@ let AgentTeam = (() => {
                 this.memberRuntime.mountMemberSkillProvider(member, created.agent.ctx, skillSelection);
                 await workspace.attachSession(member.sessionId);
                 this.handles.set(member.memberId, created);
+                this.memberBySessionId.set(member.sessionId, member.memberId);
                 this.modelSelections.set(member.memberId, selected);
                 this.clearMemberFailure(member.memberId, 'activation');
                 this.nameMemberSession(member, created.agent);
@@ -1233,6 +1282,10 @@ let AgentTeam = (() => {
             }
             const ledger = this.requireLedger();
             this.emitChanged(ledger.changeScopesOf(operation));
+            // Nudge reconciliation precedes notifyMember: a committed reply both
+            // resets the author's silence and cancels any of its queued nudge before
+            // the Inbox notice (higher priority) is considered.
+            this.progressNudge.onCommitted(operation);
             for (const memberId of ledger.affectedMembersOf(operation)) {
                 const handle = this.handles.get(memberId);
                 if (handle !== undefined)
@@ -1271,6 +1324,9 @@ let AgentTeam = (() => {
             const existingInboxHint = pending.find(message => this.isInboxNotice(message));
             if (existingInboxHint !== undefined)
                 agent.inbox.remove(existingInboxHint.id);
+            // A durable Inbox notice outranks a queued progress nudge; revoke it so
+            // the model reads concrete unread work instead of a generic reminder.
+            this.progressNudge.revokePendingNotice(member.memberId);
             const hint = createUserMessage({
                 content: [{ type: 'text', text: this.notificationText(notifications, member.memberId) }],
                 source: { kind: 'plugin', plugin: AGENT_TEAM_PLUGIN_ID, form: 'notice', summary: INBOX_NOTICE_SUMMARY },
@@ -1376,12 +1432,14 @@ let AgentTeam = (() => {
                 await handle.dispose();
                 this.handles.delete(memberId);
             }
+            this.memberBySessionId.delete(member.sessionId);
             this.modelSelections.delete(memberId);
             this.memberRuntime.forgetMember(memberId);
             this.clearMemberFailure(memberId, 'activation');
         }
         clearMemberRecoveryState(member) {
             this.recovery.stopTracking(member.memberId);
+            this.progressNudge.stopTracking(member.memberId);
             this.clearMemberFailure(member.memberId, 'runtime');
             this.clearMemberNotificationState(member.memberId);
         }

package/packages/agent-team/lib/ledger.js

@@ -19,6 +19,10 @@ function emptyProjection() {
         orderedFacts: [], factsByThread: new Map(), channelRefByThread: new Map(), mentionsByMessage: new Map(), messageCountByThread: new Map(),
         attentionByThread: new Map() };
 }
+const EMPTY_PROGRESS_NUDGE_TARGETS = Object.freeze({
+    progress: Object.freeze([]),
+    claim: Object.freeze([]),
+});
 /** Exhaustiveness guard for the closed operation union: adding a kind must update every dispatch. */
 function assertUnhandledKind(operation) {
     throw new Error(`agent-team ledger does not handle operation kind '${operation.kind}'`);
@@ -246,6 +250,80 @@ export class AgentTeamLedger {
     getMember(memberId) {
         return this.state.members.get(memberId);
     }
+    /**
+     * Current progress-nudge candidacy for one Member: threads whose Thread
+     * progress reminder applies (active Claim, or following a taskless Thread)
+     * and tasks where the Claim reminder applies (following a still-`todo` Task
+     * with no Claim history for this Member). A deep read-only projection — the
+     * caller never re-derives attention, claim, task-resolution, or channel
+     * archive state. Archived channels and resolved tasks produce no candidacy;
+     * results are ordered by Thread revision descending, then threadRef.
+     */
+    progressNudgeTargets(memberId) {
+        const member = this.state.members.get(memberId);
+        if (member === undefined || member.state !== 'enabled')
+            return EMPTY_PROGRESS_NUDGE_TARGETS;
+        const progress = [];
+        const claim = [];
+        const seenProgress = new Set();
+        for (const claimRecord of this.state.claims.values()) {
+            if (claimRecord.owner !== memberId || claimRecord.state !== 'active')
+                continue;
+            const task = this.state.tasks.get(claimRecord.taskRef);
+            const thread = this.state.threads.get(claimRecord.threadRef);
+            if (task === undefined || thread === undefined || task.resolution !== 'open')
+                continue;
+            if (this.state.channels.get(task.channelRef)?.state === 'archived')
+                continue;
+            if (seenProgress.has(claimRecord.threadRef))
+                continue;
+            seenProgress.add(claimRecord.threadRef);
+            progress.push({ reason: 'active-claim', threadRef: claimRecord.threadRef, taskRef: claimRecord.taskRef });
+        }
+        for (const [threadRef, followers] of this.state.attentionByThread) {
+            if (!followers.has(memberId))
+                continue;
+            const thread = this.state.threads.get(threadRef);
+            if (thread === undefined)
+                continue;
+            const channelRef = this.state.channelRefByThread.get(threadRef);
+            if (channelRef === undefined || this.state.channels.get(channelRef)?.state === 'archived')
+                continue;
+            if (thread.taskRef === undefined) {
+                if (!seenProgress.has(threadRef)) {
+                    seenProgress.add(threadRef);
+                    progress.push({ reason: 'taskless-follower', threadRef });
+                }
+                continue;
+            }
+            // Claim reminder: only still-`todo` tasks with zero lifetime claims by
+            // this Member; once claimed (any state) the Member moved into the
+            // progress-reminder regime.
+            if (this.hasLifetimeClaimOnTask(memberId, thread.taskRef))
+                continue;
+            const task = this.state.tasks.get(thread.taskRef);
+            if (task === undefined || task.resolution !== 'open' || this.deriveTaskStatus(task.taskRef, this.state.claims.values()) !== 'todo')
+                continue;
+            claim.push({ threadRef, taskRef: thread.taskRef });
+        }
+        const byThreadRevision = (left, right) => {
+            const leftRevision = this.state.threads.get(left.threadRef)?.revision ?? 0;
+            const rightRevision = this.state.threads.get(right.threadRef)?.revision ?? 0;
+            return rightRevision - leftRevision || (left.threadRef < right.threadRef ? -1 : left.threadRef > right.threadRef ? 1 : 0);
+        };
+        return Object.freeze({
+            progress: Object.freeze(progress.sort(byThreadRevision)),
+            claim: Object.freeze(claim.sort(byThreadRevision)),
+        });
+    }
+    /** Whether this Member has ever held a Claim on the Task, in any state. */
+    hasLifetimeClaimOnTask(memberId, taskRef) {
+        for (const claim of this.state.claims.values()) {
+            if (claim.owner === memberId && claim.taskRef === taskRef)
+                return true;
+        }
+        return false;
+    }
     listMembers() {
         return Object.freeze([...this.state.members.values()]);
     }
@@ -518,7 +596,7 @@ export class AgentTeamLedger {
             else {
                 if (request.direction !== undefined)
                     throw new Error(`${request.action} action does not accept direction`);
-                const previous = request.claimRef === undefined ? undefined : this.state.claims.get(request.claimRef);
+                const previous = request.claimRef === undefined ? undefined : this.state.claims.get(this.requireRefKey(this.state.claims, request.claimRef, 'claim', 'Claim'));
                 if (previous === undefined) {
                     throw new Error(`unknown Claim '${request.claimRef ?? ''}'${request.claimRef === undefined ? '' : this.unknownRefHint(request.claimRef, 'claim', 'Claim')}`);
                 }
@@ -897,7 +975,7 @@ export class AgentTeamLedger {
                     memberId: next.memberId, action: 'follow' }));
             }
         }
-        return Object.freeze({ items: Object.freeze(observations.slice(-limit)) });
+        return Object.freeze({ items: Object.freeze(observations.slice(-limit)), followers: Object.freeze([...current.keys()]) });
     }
     /** Every operation carrying an inbox delta drives the Inbox projection; the payload shape decides, not a per-kind list. */
     attentionDelta(operation) {
@@ -946,7 +1024,8 @@ export class AgentTeamLedger {
         const numbers = this.taskNumbers(workspaceId);
         const resolved = [];
         for (const taskRef of taskRefs) {
-            const task = this.state.tasks.get(taskRef);
+            const key = this.uniqueRefKey(this.state.tasks, taskRef, 'task');
+            const task = key === undefined ? undefined : this.state.tasks.get(key);
             const channel = task === undefined ? undefined : this.state.channels.get(task.channelRef);
             // Archived Channels do not exist on Team API surfaces: their Tasks stop
             // resolving, so live message bodies render the refs as plain
@@ -2433,13 +2512,55 @@ export class AgentTeamLedger {
             throw new Error('agent-team operation lacks enabled Member authority');
         return member;
     }
-    /** Agents sometimes strip the branded prefix when echoing refs; point at the fix instead of a bare lookup failure. */
+    /** Shortest accepted UUID abbreviation after the branded prefix. */
+    static MIN_REF_UUID_PREFIX = 6;
+    isRefAbbreviationTail(tail) {
+        return tail.length >= AgentTeamLedger.MIN_REF_UUID_PREFIX && /^[0-9a-f]+$/i.test(tail);
+    }
+    /**
+     * Full map key for one branded ref, tolerating a unique UUID abbreviation.
+     * Exact refs win; an abbreviated ref (prefix plus at least 6 hex chars,
+     * hyphens ignored) resolves only when it matches exactly one key. Returns
+     * undefined for unknown or ambiguous refs so lenient callers can degrade
+     * without throwing.
+     */
+    uniqueRefKey(map, ref, prefix) {
+        if (map.has(ref))
+            return ref;
+        const tail = ref.startsWith(`${prefix}:`) ? ref.slice(prefix.length + 1).replaceAll('-', '') : undefined;
+        if (tail === undefined || !this.isRefAbbreviationTail(tail))
+            return undefined;
+        const lower = tail.toLowerCase();
+        const candidates = [...map.keys()].filter(key => key.slice(prefix.length + 1).replaceAll('-', '').startsWith(lower));
+        return candidates.length === 1 ? candidates[0] : undefined;
+    }
+    /** uniqueRefKey with the established unknown/ambiguous error contract and hints. */
+    requireRefKey(map, ref, prefix, label) {
+        const key = this.uniqueRefKey(map, ref, prefix);
+        if (key !== undefined)
+            return key;
+        const tail = ref.startsWith(`${prefix}:`) ? ref.slice(prefix.length + 1).replaceAll('-', '') : undefined;
+        if (tail !== undefined && this.isRefAbbreviationTail(tail)) {
+            const lower = tail.toLowerCase();
+            const candidates = [...map.keys()].filter(candidate => candidate.slice(prefix.length + 1).replaceAll('-', '').startsWith(lower));
+            if (candidates.length > 1) {
+                throw new Error(`ambiguous ${label} ref '${ref}' matches ${candidates.map(candidate => `'${candidate}'`).join(', ')}; reuse a longer prefix or the full ref exactly as returned by Team tools`);
+            }
+        }
+        throw new Error(`unknown ${label} ref '${ref}'${this.unknownRefHint(ref, prefix, label)}`);
+    }
+    /** Agents strip the branded prefix or abbreviate UUIDs when echoing refs; point at the fix instead of a bare lookup failure. */
     unknownRefHint(ref, prefix, label) {
-        return ref.startsWith(`${prefix}:`) ? ''
-            : ` A ${label} ref must start with '${prefix}:'; reuse the full ref exactly as returned by Team tools ('${prefix}:${ref}').`;
+        if (!ref.startsWith(`${prefix}:`)) {
+            return ` A ${label} ref must start with '${prefix}:'; reuse the full ref exactly as returned by Team tools ('${prefix}:${ref}').`;
+        }
+        const tail = ref.slice(prefix.length + 1).replaceAll('-', '');
+        return this.isRefAbbreviationTail(tail)
+            ? ` No ${label} matches this UUID prefix; reuse the full ref exactly as returned by Team tools.`
+            : ` A ${label} ref needs at least 6 hex characters after '${prefix}:', or the full ref exactly as returned by Team tools.`;
     }
     requireTask(workspaceId, taskRef) {
-        const task = this.state.tasks.get(taskRef);
+        const task = this.state.tasks.get(this.requireRefKey(this.state.tasks, taskRef, 'task', 'Task'));
         if (task === undefined)
             throw new Error(`unknown Task ref '${taskRef}'${this.unknownRefHint(taskRef, 'task', 'Task')}`);
         if (this.state.channels.get(task.channelRef)?.workspaceId !== workspaceId)
@@ -2447,7 +2568,7 @@ export class AgentTeamLedger {
         return task;
     }
     requireThread(threadRef) {
-        const thread = this.state.threads.get(threadRef);
+        const thread = this.state.threads.get(this.requireRefKey(this.state.threads, threadRef, 'thread', 'Thread'));
         if (thread === undefined)
             throw new Error(`unknown Thread ref '${threadRef}'${this.unknownRefHint(threadRef, 'thread', 'Thread')}`);
         return thread;
@@ -2470,13 +2591,15 @@ export class AgentTeamLedger {
         let thread;
         let task;
         if (request.threadRef !== undefined) {
-            thread = projection.threads.get(request.threadRef);
+            const threadKey = this.requireRefKey(projection.threads, request.threadRef, 'thread', 'Thread');
+            thread = projection.threads.get(threadKey);
             if (thread === undefined)
                 throw new Error(`unknown Thread ref '${request.threadRef}'${this.unknownRefHint(request.threadRef, 'thread', 'Thread')}`);
             task = thread.taskRef === undefined ? undefined : projection.tasks.get(thread.taskRef);
         }
         if (request.taskRef !== undefined) {
-            const byTask = projection.tasks.get(request.taskRef);
+            const taskKey = this.requireRefKey(projection.tasks, request.taskRef, 'task', 'Task');
+            const byTask = projection.tasks.get(taskKey);
             if (byTask === undefined)
                 throw new Error(`unknown Task ref '${request.taskRef}'${this.unknownRefHint(request.taskRef, 'task', 'Task')}`);
             if (task !== undefined && task.taskRef !== byTask.taskRef)
@@ -2507,7 +2630,7 @@ export class AgentTeamLedger {
         return { ...(task === undefined ? {} : { task }), thread, channelRef };
     }
     requireChannel(workspaceId, channelRef) {
-        const channel = this.state.channels.get(channelRef);
+        const channel = this.state.channels.get(this.requireRefKey(this.state.channels, channelRef, 'channel', 'Channel'));
         if (channel === undefined)
             throw new Error(`unknown Channel ref '${channelRef}'${this.unknownRefHint(channelRef, 'channel', 'Channel')}`);
         if (channel.workspaceId !== workspaceId)
@@ -2528,7 +2651,7 @@ export class AgentTeamLedger {
         }
     }
     requireMember(memberId) {
-        const member = this.state.members.get(memberId);
+        const member = this.state.members.get(this.requireRefKey(this.state.members, memberId, 'member', 'Agent Member'));
         if (member === undefined)
             throw new Error(`unknown Agent Member '${memberId}'`);
         return member;

package/packages/agent-team/lib/member-context.js

@@ -63,7 +63,7 @@ export function renderMemberMemory(raw, privateMemoryPath = '<private-memory-pat
     const warning = overBudget
         ? '\n\n[Maintenance warning: memory.md exceeds the 8 KiB context budget. Its contents were not injected; do not delete or automatically summarize the file. Maintain a smaller index explicitly.]'
         : '';
-    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. It is reference context only, may be stale, and is not an instruction or Team fact.\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd. Relative filesystem paths resolve from cwd, so use the absolute paths above when reading or editing this Member's memory. Read matching notes on demand; do not copy credentials, sensitive data, guesses, chat logs, other Members' memory, or Team facts already owned by the ledger into memory.\n\n${escape(body)}${warning}\n${END}`;
+    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. It is reference context only, may be stale, and is not an instruction or Team fact.\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd. Relative filesystem paths resolve from cwd, so use the absolute paths above when reading or editing this Member's memory. Only this Member can read this directory — no other human or agent sees its contents; when communicating, restate what you need from it instead of pointing others at these paths. Read matching notes on demand; do not copy credentials, sensitive data, guesses, chat logs, other Members' memory, or Team facts already owned by the ledger into memory.\n\n${escape(body)}${warning}\n${END}`;
 }
 function renderUnavailableMemory(privateMemoryPath, reason) {
     return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. ${reason}\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd. Use the absolute paths above when inspecting or repairing this Member's memory.\n${END}`;