@wowyuarm/dsh-agent-team 0.1.4 → 0.1.5

package/README.zh.md

@@ -2,6 +2,9 @@
 
 [English](README.md) | 简体中文
 
+[![npm](https://img.shields.io/npm/v/@wowyuarm/dsh-agent-team?style=flat-square)](https://www.npmjs.com/package/@wowyuarm/dsh-agent-team)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/wowyuarm/dsh-agent-team?include_prereleases&style=flat-square)](https://github.com/wowyuarm/dsh-agent-team/releases)
 [![Listed on Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com/p/wowyuarm/dsh-agent-team/)
 
 **dsh-agent-team** 帮助 human 有序管理任务、把 agents 用成真正的协作者：Agent 是 session 的持久身份；Workspace 按项目组织 agents 与 sessions；Channel 承载职责分派；Task Thread 把多个 session agent 串成一条推进线。
@@ -98,7 +101,7 @@ dsh web
 
 ## 开发
 
-维护中的文档入口是 [`docs/README.md`](docs/README.md)。常用检查命令：
+维护中的文档入口是 [`docs/README.zh.md`](docs/README.zh.md)。常用检查命令：
 
 ```sh
 corepack pnpm install
@@ -112,7 +115,7 @@ npm pack --dry-run
 
 `npm run test:browser` 使用相邻的 `../deepseek-harness` checkout、隔离临时 profile 和 `/usr/bin/google-chrome`（可用 `CHROME_PATH` 覆盖），不需要 provider credentials。手动检查时，`npm run preview:ui` 会加载不调用模型的 Team fixture；`DEEPSEEK_API_KEY=... npm run preview` 会启动真实 provider preview。两个 preview 命令都会在 `Ctrl+C` 后清理临时状态。
 
-架构和协作协议见 [`docs/architecture.md`](docs/architecture.md) 与 [`docs/team-collaboration.md`](docs/team-collaboration.md)。
+架构和协作协议见 [`docs/architecture.zh.md`](docs/architecture.zh.md) 与 [`docs/team-collaboration.zh.md`](docs/team-collaboration.zh.md)。
 
 ## 许可证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowyuarm/dsh-agent-team",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Help humans organize tasks and let agents collaborate - a Team plugin for DeepSeek Harness",
   "repository": {
     "type": "git",

package/packages/agent-team/lib/auto-compaction.js

@@ -1,6 +1,15 @@
 import { ManualCompactionError } from '@deepseek-ai/dsh-compaction';
 /** Strict threshold: 200K exactly does not compact. */
 export const AUTO_COMPACTION_TOKEN_LIMIT = 200_000;
+/**
+ * Suggested summary marker of the pre-compaction memory hint. Same shape as
+ * the inbox and recovery notices so future turns can recognize it.
+ */
+export const PRE_COMPACTION_NOTICE_SUMMARY = 'Compaction is imminent; consider persisting key conclusions.';
+/** Suggested pre-compaction hint body; writing is the Agent's own call. */
+export function preCompactionNoticeText() {
+    return 'This session is about to be compacted, which will summarize away the current conversation detail. If there are durable conclusions worth keeping — validated facts, decisions, or reusable details — consider writing them to your memory or notes now. This is only a reminder: decide yourself whether anything is worth persisting, and do nothing if not. Do not start new work because of this message.';
+}
 /** Claim owners of a durable Human acceptance, including early-completed ones. */
 export function acceptedTaskCompactionMembers(operation) {
     if (operation.kind !== 'team/task-changed' || operation.actor.kind !== 'human' || operation.data.activity.kind !== 'accept')
@@ -69,11 +78,40 @@ export class AutoCompactionCoordinator {
                 this.fail(memberId, agent, 'automatic compaction failed: tokenMeter is unavailable in the Member scope');
                 return;
             }
-            const before = meter.measure(agent.session).totalTokens;
+            let before = meter.measure(agent.session).totalTokens;
             if (before <= AUTO_COMPACTION_TOKEN_LIMIT) {
                 this.complete(memberId, agent);
                 return;
             }
+            // The session is over the threshold and about to be compacted: steer one
+            // advisory hint so the Agent can persist its own key conclusions first.
+            // The hint turn itself is ordinary agent work — its failure is contained
+            // by the agent loop and never blocks compaction; only the fresh idle
+            // boundary is awaited before the final measurement and compactNow.
+            if (this.options.steerPreCompaction !== undefined) {
+                try {
+                    this.options.steerPreCompaction(agent);
+                }
+                catch (error) {
+                    this.options.log(`pre-compaction memory hint failed: ${describe(error)} (member ${memberId}, session ${agent.id})`);
+                }
+                try {
+                    if (!(await waitForIdleOrAbort(agent, this.controller.signal)))
+                        return;
+                }
+                catch (error) {
+                    this.options.log(`pre-compaction hint idle wait failed: ${describe(error)} (member ${memberId}, session ${agent.id})`);
+                }
+                if (this.controller.signal.aborted)
+                    return;
+                if (this.options.agentForMember(memberId) !== agent)
+                    continue;
+                before = meter.measure(agent.session).totalTokens;
+                if (before <= AUTO_COMPACTION_TOKEN_LIMIT) {
+                    this.complete(memberId, agent);
+                    return;
+                }
+            }
             const engine = this.options.compactionForAgent(agent);
             if (engine === undefined) {
                 // A roster-subtree teardown (bundle-row reload, config hot-apply)

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

@@ -52,7 +52,7 @@ import { SessionId } from '@deepseek-ai/dsh-session';
 import { effectiveSandboxMode, setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { ATTACHMENT_MAX_BYTES, attachmentPayloadPath, attachmentsRoot, copyPathAttachment, newAttachmentId, readAttachment, sanitizeMediaType, sweepAttachmentCache, validatePathAttachment, writeAttachment } from "./attachments.js";
-import { acceptedTaskCompactionMembers, AutoCompactionCoordinator } from "./auto-compaction.js";
+import { acceptedTaskCompactionMembers, AutoCompactionCoordinator, PRE_COMPACTION_NOTICE_SUMMARY, preCompactionNoticeText } from "./auto-compaction.js";
 import { AGENT_TEAM_HUMAN_MEMBER_ID, AgentTeamLedger, agentTeamHumanActor } from "./ledger.js";
 import { classifyRecoverableError, RecoveryCoordinator, RECOVERY_MAX_CONSECUTIVE_ERRORS } from "./recovery.js";
 import { agentTeamDomainSpec } from "./spec.js";
@@ -96,6 +96,7 @@ let AgentTeam = (() => {
     let _updateChannel_decorators;
     let _addMember_decorators;
     let _recoverMember_decorators;
+    let _clearMemberContext_decorators;
     let _updateMember_decorators;
     let _changeTask_decorators;
     let _promoteThread_decorators;
@@ -121,6 +122,7 @@ let AgentTeam = (() => {
             _updateChannel_decorators = [Remote('updateChannel')];
             _addMember_decorators = [Remote('addMember')];
             _recoverMember_decorators = [Remote('recoverMember')];
+            _clearMemberContext_decorators = [Remote('clearMemberContext')];
             _updateMember_decorators = [Remote('updateMember')];
             _changeTask_decorators = [Remote('changeTask')];
             _promoteThread_decorators = [Remote('promoteThread')];
@@ -143,6 +145,7 @@ let AgentTeam = (() => {
             __esDecorate(this, null, _updateChannel_decorators, { kind: "method", name: "updateChannel", static: false, private: false, access: { has: obj => "updateChannel" in obj, get: obj => obj.updateChannel }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _addMember_decorators, { kind: "method", name: "addMember", static: false, private: false, access: { has: obj => "addMember" in obj, get: obj => obj.addMember }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _recoverMember_decorators, { kind: "method", name: "recoverMember", static: false, private: false, access: { has: obj => "recoverMember" in obj, get: obj => obj.recoverMember }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _clearMemberContext_decorators, { kind: "method", name: "clearMemberContext", static: false, private: false, access: { has: obj => "clearMemberContext" in obj, get: obj => obj.clearMemberContext }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _updateMember_decorators, { kind: "method", name: "updateMember", static: false, private: false, access: { has: obj => "updateMember" in obj, get: obj => obj.updateMember }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _changeTask_decorators, { kind: "method", name: "changeTask", static: false, private: false, access: { has: obj => "changeTask" in obj, get: obj => obj.changeTask }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _promoteThread_decorators, { kind: "method", name: "promoteThread", static: false, private: false, access: { has: obj => "promoteThread" in obj, get: obj => obj.promoteThread }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -216,6 +219,14 @@ let AgentTeam = (() => {
                     this.emitAutoCompactionChanged(memberId);
                 },
                 log: message => { this.ctx.logger.warn(`agent-team: ${message}`); },
+                // Advisory only: the Agent decides whether anything is worth persisting.
+                steerPreCompaction: agent => {
+                    const hint = createUserMessage({
+                        content: [{ type: 'text', text: preCompactionNoticeText() }],
+                        source: { kind: 'plugin', plugin: AGENT_TEAM_PLUGIN_ID, form: 'notice', summary: PRE_COMPACTION_NOTICE_SUMMARY },
+                    });
+                    agent.steer(hint);
+                },
             });
         }
         /** Open the durable ledger and restore every enabled Member independently. */
@@ -246,8 +257,15 @@ let AgentTeam = (() => {
                     this.notifyMember(agent);
                 }
                 // A turn that ends without an error closes any automatic recovery episode.
-                if (status === 'idle' && member !== undefined && this.memberFailures.get(member.memberId)?.runtime === undefined) {
-                    this.recovery.onCleanTurnEnd(member.memberId);
+                // The idle transition is itself presence-affecting (working → available),
+                // so it must wake workspace watchers exactly like the running transition
+                // above; without this wake, cached Client member rows keep showing the
+                // Member as working after every turn until an unrelated change arrives.
+                if (status === 'idle' && member !== undefined) {
+                    if (this.memberFailures.get(member.memberId)?.runtime === undefined) {
+                        this.recovery.onCleanTurnEnd(member.memberId);
+                    }
+                    this.emitChanged([{ kind: 'workspace', workspaceId: member.workspaceId }]);
                 }
             });
             const domain = await this.ctx.storageDomain.open(agentTeamDomainSpec);
@@ -463,6 +481,66 @@ let AgentTeam = (() => {
             this.steerResume(member, this.manualResumeText());
             return Object.freeze({ status: this.memberStatus(member) });
         }
+        /**
+         * Start one enabled Member from a new context: dispose the live handle,
+         * archive the previous Session (its log stays on disk for history), and
+         * activate a fresh Session under a new sessionId, so preset, tools, private
+         * memory, and model selection all reload while the next turn carries no
+         * history. The durable operation moves the Member's sessionId; identity,
+         * memory path, and binding survive. A new id is what keeps the Web Client
+         * seat live: a disposed generation's resident instance keeps its `removed`
+         * bit forever, so renewing under the same id would leave a permanently
+         * grayed session view.
+         */
+        async clearMemberContext(request) {
+            return this.enqueueLifecycle(async () => {
+                this.requireAccepting();
+                this.requireWorkspace(request.workspaceId);
+                const stored = this.requireLedger().getMember(request.memberId);
+                if (stored === undefined || stored.workspaceId !== request.workspaceId)
+                    throw new Error(`unknown Member '${request.memberId}' in workspace '${request.workspaceId}'`);
+                if (stored.state !== 'enabled')
+                    throw new Error(`Agent Member '${stored.handle}' is ${stored.state}; only enabled Members can start from a new context`);
+                const active = this.handles.get(request.memberId);
+                if (active === undefined)
+                    throw new Error(`Agent Member '${stored.handle}' has no active session to clear`);
+                if (this.runningAgents.has(active.agent.id))
+                    throw new Error(`Agent Member '${stored.handle}' is still running; wait for the current turn to end before starting from a new context`);
+                const previousSessionId = stored.sessionId;
+                // The fresh id derives from the requestId, so a retried identical
+                // request mints the same id and the ledger dedupes it instead of
+                // colliding; the format matches addMember's `agent-team-<uuid>`.
+                const sessionId = SessionId(`agent-team-${request.requestId}`);
+                const result = await this.requireLedger().renewMemberSession({ ...request, sessionId, actor: agentTeamHumanActor() });
+                if (result.committed)
+                    this.emitCommitted(result.value.receipt);
+                else {
+                    // A retried identical request already renewed this Member; report the
+                    // recorded outcome without another dispose/reactivate cycle.
+                    return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(result.value.member) });
+                }
+                const renewed = result.value.member;
+                // 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);
+                await active.dispose();
+                this.handles.delete(request.memberId);
+                this.modelSelections.delete(request.memberId);
+                this.clearMemberFailure(request.memberId, 'activation');
+                this.clearMemberNotificationState(request.memberId);
+                // The previous log survives on disk; archiving hides it from every
+                // grouping surface so one Member keeps exactly one visible Session.
+                await this.ctx.workspaceRegistry.archiveSession(previousSessionId);
+                await this.activateMember(renewed, undefined, undefined, previousSessionId);
+                const reactivated = this.handles.get(request.memberId);
+                if (reactivated === undefined) {
+                    // Reactivation failed; the activation diagnostic carries the reason and
+                    // the durable renewal stays honest about the attempt.
+                    throw new Error(`Agent Member '${stored.handle}' failed to start a new context: ${this.memberFailures.get(request.memberId)?.activation ?? 'unknown error'}`);
+                }
+                return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(renewed) });
+            });
+        }
         /** Ledger handle for log lines; falls back to the raw id when unknown. */
         memberLabel(memberId) {
             return this.ledger?.getMember(memberId)?.handle ?? memberId;
@@ -831,7 +909,7 @@ let AgentTeam = (() => {
                     throw error;
             }
         }
-        async activateMember(member, knownWorkspacePath, knownSessions) {
+        async activateMember(member, knownWorkspacePath, knownSessions, forkedFrom) {
             if (this.handles.has(member.memberId))
                 return;
             let created;
@@ -865,7 +943,9 @@ let AgentTeam = (() => {
                     ? await this.ctx.agents.resume({ resumeSessionId: member.sessionId, agentOptions, setup })
                     : await this.ctx.agents.create({
                         sessionId: member.sessionId,
-                        meta: { cwd: workspacePath, agentPreset: member.presetId },
+                        // A context renewal records its fork lineage so the archived
+                        // previous Session stays discoverable from the durable header.
+                        meta: { cwd: workspacePath, agentPreset: member.presetId, ...(forkedFrom === undefined ? {} : { parentSession: forkedFrom }) },
                         agentOptions,
                         setup,
                     });

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

@@ -195,6 +195,35 @@ export class AgentTeamLedger {
     resumeMember(request) {
         return this.setMemberState(request, 'enabled');
     }
+    /**
+     * Move one enabled Member onto a fresh Session: the durable operation
+     * records the sessionId transition while identity, memory, and binding
+     * survive. The Host disposes the old handle and archives the previous
+     * Session log around this write, so the next turn starts empty.
+     */
+    renewMemberSession(request) {
+        return this.enqueue(async () => {
+            const existing = this.state.byRequest.get(request.requestId);
+            if (existing !== undefined) {
+                this.assertSameMemberSessionRenewed(existing, request);
+                return this.resolved(this.memberResult(existing));
+            }
+            this.assertHumanActor(request.actor);
+            const prior = this.requireMember(request.memberId);
+            if (prior.state !== 'enabled')
+                throw new Error(`Agent Member '${prior.handle}' is ${prior.state}; only enabled Members can start from a new context`);
+            if (prior.sessionId === request.sessionId)
+                throw new Error(`Agent Member '${prior.handle}' already runs Session '${request.sessionId}'`);
+            const member = Object.freeze({ ...prior, sessionId: request.sessionId });
+            const operation = Object.freeze({
+                ...this.operationBase(request, this.nextSequence()), kind: 'team/member-session-renewed',
+                data: Object.freeze({ member, previousSessionId: prior.sessionId }),
+            });
+            await this.table.put(operation.operationId, operation);
+            this.apply(operation);
+            return this.committed(this.memberResult(operation));
+        });
+    }
     getMember(memberId) {
         return this.state.members.get(memberId);
     }
@@ -481,8 +510,10 @@ export class AgentTeamLedger {
             // Acceptance normally waits for every Claim to finish (in_review);
             // a Human may also accept early while work is in progress, which then
             // completes the still-active Claims inside the same atomic operation.
-            if (request.action === 'accept' && task.status !== 'in_review' && task.status !== 'in_progress') {
-                throw new Error(`Task '${task.taskRef}' must be in_review or in_progress before acceptance`);
+            // A never-claimed todo Task may be accepted directly as well: work
+            // finished outside the ledger is declared complete by the Human.
+            if (request.action === 'accept' && task.status !== 'in_review' && task.status !== 'in_progress' && task.status !== 'todo') {
+                throw new Error(`Task '${task.taskRef}' must be in_review, in_progress, or todo before acceptance`);
             }
             const priorActiveClaims = [...this.state.claims.values()].filter(claim => claim.taskRef === task.taskRef && claim.state === 'active');
             if (request.action === 'accept' && task.status === 'in_progress' && priorActiveClaims.length === 0) {
@@ -860,6 +891,8 @@ export class AgentTeamLedger {
             case 'team/member-suspended':
             case 'team/member-resumed':
             case 'team/member-session-restarted':
+            case 'team/member-context-cleared':
+            case 'team/member-session-renewed':
             case 'team/member-updated':
             case 'team/member-removed':
                 return [{ kind: 'workspace', workspaceId: operation.data.member.workspaceId }];
@@ -949,6 +982,8 @@ export class AgentTeamLedger {
             case 'team/member-suspended':
             case 'team/member-resumed':
             case 'team/member-session-restarted':
+            case 'team/member-context-cleared':
+            case 'team/member-session-renewed':
             case 'team/member-updated':
             case 'team/channel-member-added':
             case 'team/thread-read':
@@ -1058,6 +1093,28 @@ export class AgentTeamLedger {
                 throw new Error('invalid Member restart');
             return;
         }
+        if (operation.kind === 'team/member-context-cleared') {
+            assertHuman();
+            const prior = projection.members.get(operation.data.member.memberId);
+            // Legacy in-place clear: the recorded Member is unchanged, and the
+            // projection deliberately does not change either.
+            if (prior === undefined || prior.state !== 'enabled' || !this.sameMemberIdentity(prior, operation.data.member))
+                throw new Error('invalid Member context clear');
+            return;
+        }
+        if (operation.kind === 'team/member-session-renewed') {
+            assertHuman();
+            const prior = projection.members.get(operation.data.member.memberId);
+            // The renewal moves exactly the sessionId: the prior Member must be
+            // enabled on the recorded previous Session, and every other fact must
+            // carry over unchanged.
+            if (prior === undefined || prior.state !== 'enabled'
+                || prior.sessionId !== operation.data.previousSessionId
+                || operation.data.member.sessionId === operation.data.previousSessionId
+                || !this.sameMemberFacts(prior, operation.data.member))
+                throw new Error('invalid Member session renewal');
+            return;
+        }
         if (operation.kind === 'team/channel-updated') {
             assertHuman();
             const prior = projection.channels.get(operation.data.channel.channelRef);
@@ -1486,6 +1543,15 @@ export class AgentTeamLedger {
             // projection deliberately does not change.
             return;
         }
+        if (operation.kind === 'team/member-context-cleared') {
+            // Legacy audit-only marker: identity, memory path, and binding were
+            // untouched; the Host recreated the live Session empty under the same id.
+            return;
+        }
+        if (operation.kind === 'team/member-session-renewed') {
+            target.members.set(operation.data.member.memberId, operation.data.member);
+            return;
+        }
         if (operation.kind === 'team/channel-updated') {
             target.channels.set(operation.data.channel.channelRef, operation.data.channel);
             return;
@@ -2176,6 +2242,11 @@ export class AgentTeamLedger {
         if (operation.kind !== kind || !this.sameActor(operation.actor, request.actor) || operation.data.member.memberId !== request.memberId)
             this.throwRequestCollision(request.requestId);
     }
+    assertSameMemberSessionRenewed(operation, request) {
+        if (operation.kind !== 'team/member-session-renewed' || !this.sameActor(operation.actor, request.actor)
+            || operation.data.member.memberId !== request.memberId || operation.data.member.sessionId !== request.sessionId)
+            this.throwRequestCollision(request.requestId);
+    }
     assertSameChannelUpdate(operation, request) {
         if (operation.kind !== 'team/channel-updated' || !this.sameActor(operation.actor, request.actor)
             || operation.data.workspaceId !== request.workspaceId || operation.data.channel.channelRef !== request.channelRef
@@ -2282,6 +2353,13 @@ export class AgentTeamLedger {
             && isDeepStrictEqual(left.model ?? undefined, right.model ?? undefined)
             && left.privateMemoryPath === right.privateMemoryPath;
     }
+    /** sameMemberIdentity minus the sessionId: every durable Member fact a session renewal must carry over unchanged. */
+    sameMemberFacts(left, right) {
+        return left.memberId === right.memberId && left.workspaceId === right.workspaceId
+            && left.handle === right.handle && left.description === right.description && left.presetId === right.presetId
+            && isDeepStrictEqual(left.model ?? undefined, right.model ?? undefined)
+            && left.privateMemoryPath === right.privateMemoryPath;
+    }
     sameActor(left, right) {
         return left.kind === right.kind && left.memberId === right.memberId && left.handle === right.handle;
     }

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

@@ -237,6 +237,18 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         kind: z.literal('team/member-session-restarted'),
         data: z.object({ member: memberSchema }).strict(),
     }).strict(),
+    z.object({
+        ...operationBase,
+        previousOperationId: operationIdSchema.nullable(),
+        kind: z.literal('team/member-context-cleared'),
+        data: z.object({ member: memberSchema }).strict(),
+    }).strict(),
+    z.object({
+        ...operationBase,
+        previousOperationId: operationIdSchema.nullable(),
+        kind: z.literal('team/member-session-renewed'),
+        data: z.object({ member: memberSchema, previousSessionId: sessionIdSchema }).strict(),
+    }).strict(),
     z.object({
         ...operationBase,
         previousOperationId: operationIdSchema.nullable(),