@wowyuarm/dsh-agent-team 0.1.0 → 0.1.1

package/README.md

@@ -2,9 +2,13 @@
 
 [English](README.md) | [简体中文](README.zh.md)
 
-An Agent Team plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): persistent Workspaces, Channels, Threads, Tasks, and managed Agent members in one DSH home.
+[![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)
 
-Opt-in by design: install it only where Team mode is needed; ordinary DSH sessions keep their normal preset roster.
+**dsh-agent-team** helps a human manage tasks in an orderly way and use agents as true collaborators: agents are persistent identities for their sessions; Workspaces organize agents and sessions per project; Channels carry responsibilities; Task Threads chain session agents into one line of progress.
+
+An opt-in plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): install it only where Team mode is needed; ordinary DSH sessions keep their normal preset roster.
 
 ## Preview
 
@@ -53,6 +57,14 @@ Team mode
 
 Create an Agent only in a trusted Workspace. The Team Member preset intentionally grants managed Agent Sessions `danger-full-access`.
 
+## Uninstall
+
+Remove the bundle from the profile; this also removes its composed layers:
+
+```sh
+dsh plugin --profile web remove @wowyuarm/dsh-agent-team
+```
+
 ## What it adds
 
 - A durable single-host Team with Channels, Messages, Tasks, Threads, Claims, and Agent membership.

package/README.zh.md

@@ -2,9 +2,9 @@
 
 [English](README.md) | 简体中文
 
-这是一个为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供的 Agent Team 插件：在一个 DSH home 中组织持久化的 Workspace、Channel、Thread、Task 和由 Team 管理的 Agent 成员。
+**dsh-agent-team** 帮助 human 有序管理任务、把 agents 用成真正的协作者：Agent 是 session 的持久身份；Workspace 按项目组织 agents 与 sessions；Channel 承载职责分派；Task Thread 把多个 session agent 串成一条推进线。
 
-按需启用：只在需要 Team mode 的 profile 中安装；普通 DSH Session 保持原有 preset roster。
+一个为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供的按需启用插件：只在需要 Team mode 的 profile 安装，普通 DSH Session 保持原有 preset roster。
 
 ## 预览
 
@@ -53,6 +53,14 @@ Team mode
 
 只在可信 Workspace 中创建 Agent。Team Member preset 会给被管理的 Agent Session 授予 `danger-full-access`。
 
+## 卸载
+
+从 profile 移除 bundle，同时会移除它组合进来的层：
+
+```sh
+dsh plugin --profile web remove @wowyuarm/dsh-agent-team
+```
+
 ## 提供的能力
 
 - 持久化的单 Host Team，包含 Channel、Message、Task、Thread、Claim 和 Agent membership。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wowyuarm/dsh-agent-team",
-  "version": "0.1.0",
-  "description": "Agent Team plugin for DeepSeek Harness",
+  "version": "0.1.1",
+  "description": "Help humans organize tasks and let agents collaborate - a Team plugin for DeepSeek Harness",
   "repository": {
     "type": "git",
     "url": "https://github.com/wowyuarm/dsh-agent-team.git"

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

@@ -0,0 +1,157 @@
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, extname, isAbsolute, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+/**
+ * Composer attachments are a cache, not an archive: bytes live only so Member
+ * agents can read them within the consumption window, while the ledger keeps
+ * the metadata forever. Everything here derives from the on-disk layout
+ * `$DSH_HOME/agent-team/attachments/v1/<attachmentId>/` holding the payload
+ * file (original sanitized name) plus a `meta.json` sidecar.
+ */
+export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+/** Referenced uploads survive this long after upload for member consumption. */
+export const ATTACHMENT_REFERENCED_TTL_MS = 72 * 60 * 60 * 1000;
+/** Unreferenced uploads (uploaded but never sent) are cleaned much sooner. */
+export const ATTACHMENT_ORPHAN_TTL_MS = 24 * 60 * 60 * 1000;
+export function attachmentsRoot() {
+    return dshHomePath('agent-team', 'attachments', 'v1');
+}
+export function newAttachmentId() {
+    return randomUUID();
+}
+/** Strip path separators, control characters, and leading dots from one client-supplied name. */
+export function sanitizeFileName(raw) {
+    const cleaned = raw.replaceAll(/[\\/\u0000-\u001f\u007f]/g, '').replaceAll(/^\.+/g, '').trim();
+    return cleaned === '' ? 'attachment' : cleaned.slice(0, 180);
+}
+/** Extension-derived media types for agent-supplied files; unknown types stay generic. */
+const PATH_MEDIA_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+    '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf',
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.json': 'application/json',
+};
+/** Best-effort media type from one path's extension, so images render as thumbnails. */
+export function mediaTypeForPath(raw) {
+    return PATH_MEDIA_TYPES[extname(raw).toLowerCase()] ?? 'application/octet-stream';
+}
+/**
+ * Validate one agent-supplied attachment path before any cache write happens,
+ * so a rejection anywhere leaves the upload cache untouched.
+ */
+export async function validatePathAttachment(raw) {
+    if (!isAbsolute(raw))
+        throw new Error(`attachment path '${raw}' must be absolute`);
+    const info = await stat(raw).catch(() => undefined);
+    if (info === undefined)
+        throw new Error(`attachment path '${raw}' does not exist`);
+    if (!info.isFile())
+        throw new Error(`attachment path '${raw}' is not a regular file`);
+    if (info.size === 0)
+        throw new Error(`attachment '${basename(raw)}' must not be empty`);
+    if (info.size > ATTACHMENT_MAX_BYTES)
+        throw new Error(`attachment '${basename(raw)}' exceeds the ${ATTACHMENT_MAX_BYTES} byte limit`);
+}
+/** Copy one validated file into the cache as a fresh immutable entry. */
+export async function copyPathAttachment(root, raw) {
+    const bytes = await readFile(raw);
+    const stored = await writeAttachment(root, newAttachmentId(), basename(raw), mediaTypeForPath(raw), bytes);
+    return { attachmentId: stored.attachmentId, name: stored.name, byteSize: stored.byteSize, mediaType: stored.mediaType };
+}
+function attachmentDir(root, attachmentId) {
+    return join(root, attachmentId);
+}
+/** Write one upload as an immutable payload plus its metadata sidecar. */
+export async function writeAttachment(root, attachmentId, rawName, mediaType, bytes) {
+    const name = sanitizeFileName(rawName);
+    const dir = attachmentDir(root, attachmentId);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, name), bytes);
+    const meta = { name, mediaType, uploadedAt: new Date().toISOString() };
+    await writeFile(join(dir, 'meta.json'), JSON.stringify(meta), 'utf8');
+    return { attachmentId, path: join(dir, name), name, byteSize: bytes.byteLength, mediaType };
+}
+/** Read one attachment back; `undefined` when the cache entry is gone (GC'd). */
+export async function readAttachment(root, attachmentId) {
+    const dir = attachmentDir(root, attachmentId);
+    let metaRaw;
+    try {
+        metaRaw = await readFile(join(dir, 'meta.json'));
+    }
+    catch {
+        return undefined;
+    }
+    const meta = JSON.parse(metaRaw.toString('utf8'));
+    const entries = await readdir(dir);
+    const payload = entries.filter(entry => entry !== 'meta.json')[0];
+    if (payload === undefined)
+        return undefined;
+    const bytes = await readFile(join(dir, payload));
+    return { name: meta.name, mediaType: meta.mediaType, byteSize: bytes.byteLength, uploadedAt: meta.uploadedAt, bytes };
+}
+/** Whether an upload with this id still has bytes on disk. */
+export async function attachmentExists(root, attachmentId) {
+    try {
+        await stat(attachmentDir(root, attachmentId));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** List every cache entry with its upload instant for the GC sweep. */
+export async function scanAttachmentCache(root) {
+    let ids;
+    try {
+        ids = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const id of ids) {
+        try {
+            const metaRaw = await readFile(join(root, id, 'meta.json'));
+            const meta = JSON.parse(metaRaw.toString('utf8'));
+            entries.push({ attachmentId: id, uploadedAt: Date.parse(meta.uploadedAt) });
+        }
+        catch {
+            // A half-written or foreign directory is not ours to judge; skip it.
+        }
+    }
+    return entries;
+}
+/** Remove one cache entry's bytes; missing entries already satisfy the sweep. */
+export async function removeAttachment(root, attachmentId) {
+    await rm(attachmentDir(root, attachmentId), { recursive: true, force: true });
+}
+/**
+ * One GC pass: drop uploads older than the orphan TTL, and referenced ones
+ * older than the consumption-window TTL. Returns the ids removed so the
+ * service can log them.
+ */
+export async function sweepAttachmentCache(root, referenced, now) {
+    const removed = [];
+    for (const entry of await scanAttachmentCache(root)) {
+        const age = now - entry.uploadedAt;
+        const ttl = referenced.has(entry.attachmentId) ? ATTACHMENT_REFERENCED_TTL_MS : ATTACHMENT_ORPHAN_TTL_MS;
+        if (age > ttl) {
+            await removeAttachment(root, entry.attachmentId);
+            removed.push(entry.attachmentId);
+        }
+    }
+    return removed;
+}
+/** Accept only well-formed `type/subtype` media types; anything else falls back to the generic binary type. */
+export function sanitizeMediaType(raw) {
+    const candidate = (raw ?? '').trim().toLowerCase();
+    return /^[a-z0-9][-.\w]*\/[-.\w]+$/.test(candidate) ? candidate : 'application/octet-stream';
+}

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

@@ -50,7 +50,9 @@ import { scopeOf } from '@deepseek-ai/dsh-scope';
 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, attachmentsRoot, copyPathAttachment, newAttachmentId, readAttachment, sanitizeMediaType, sweepAttachmentCache, validatePathAttachment, writeAttachment } from "./attachments.js";
 import { AGENT_TEAM_HUMAN_MEMBER_ID, AgentTeamLedger, agentTeamHumanActor } from "./ledger.js";
+import { classifyRecoverableError, RecoveryCoordinator, RECOVERY_MAX_ATTEMPTS } from "./recovery.js";
 import { agentTeamDomainSpec } from "./spec.js";
 export { agentTeamDomainSpec, agentTeamOperationSchema } from "./spec.js";
 export { AGENT_TEAM_HUMAN_MEMBER_ID, AGENT_TEAM_INITIALIZE_REQUEST_ID } from "./ledger.js";
@@ -86,11 +88,15 @@ let AgentTeam = (() => {
     let _createChannel_decorators;
     let _updateChannel_decorators;
     let _addMember_decorators;
+    let _recoverMember_decorators;
+    let _restartMember_decorators;
     let _updateMember_decorators;
     let _changeTask_decorators;
     let _joinChannel_decorators;
     let _removeChannelMember_decorators;
     let _sendMessage_decorators;
+    let _putAttachment_decorators;
+    let _getAttachment_decorators;
     let _reply_decorators;
     let _changeAttention_decorators;
     let _inbox_decorators;
@@ -106,11 +112,15 @@ let AgentTeam = (() => {
             _createChannel_decorators = [Remote('createChannel')];
             _updateChannel_decorators = [Remote('updateChannel')];
             _addMember_decorators = [Remote('addMember')];
+            _recoverMember_decorators = [Remote('recoverMember')];
+            _restartMember_decorators = [Remote('restartMember')];
             _updateMember_decorators = [Remote('updateMember')];
             _changeTask_decorators = [Remote('changeTask')];
             _joinChannel_decorators = [Remote('joinChannel')];
             _removeChannelMember_decorators = [Remote('removeChannelMember')];
             _sendMessage_decorators = [Remote('sendMessage')];
+            _putAttachment_decorators = [Remote('putAttachment')];
+            _getAttachment_decorators = [Remote('getAttachment')];
             _reply_decorators = [Remote('reply')];
             _changeAttention_decorators = [Remote('changeAttention')];
             _inbox_decorators = [Remote('inbox')];
@@ -123,11 +133,15 @@ let AgentTeam = (() => {
             __esDecorate(this, null, _createChannel_decorators, { kind: "method", name: "createChannel", static: false, private: false, access: { has: obj => "createChannel" in obj, get: obj => obj.createChannel }, metadata: _metadata }, null, _instanceExtraInitializers);
             __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, _restartMember_decorators, { kind: "method", name: "restartMember", static: false, private: false, access: { has: obj => "restartMember" in obj, get: obj => obj.restartMember }, 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, _joinChannel_decorators, { kind: "method", name: "joinChannel", static: false, private: false, access: { has: obj => "joinChannel" in obj, get: obj => obj.joinChannel }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _removeChannelMember_decorators, { kind: "method", name: "removeChannelMember", static: false, private: false, access: { has: obj => "removeChannelMember" in obj, get: obj => obj.removeChannelMember }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sendMessage_decorators, { kind: "method", name: "sendMessage", static: false, private: false, access: { has: obj => "sendMessage" in obj, get: obj => obj.sendMessage }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _putAttachment_decorators, { kind: "method", name: "putAttachment", static: false, private: false, access: { has: obj => "putAttachment" in obj, get: obj => obj.putAttachment }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getAttachment_decorators, { kind: "method", name: "getAttachment", static: false, private: false, access: { has: obj => "getAttachment" in obj, get: obj => obj.getAttachment }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _reply_decorators, { kind: "method", name: "reply", static: false, private: false, access: { has: obj => "reply" in obj, get: obj => obj.reply }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _changeAttention_decorators, { kind: "method", name: "changeAttention", static: false, private: false, access: { has: obj => "changeAttention" in obj, get: obj => obj.changeAttention }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _inbox_decorators, { kind: "method", name: "inbox", static: false, private: false, access: { has: obj => "inbox" in obj, get: obj => obj.inbox }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -151,7 +165,19 @@ let AgentTeam = (() => {
         handles = new Map();
         diagnostics = new Map();
         runtimeErrors = new Map();
+        /** Agent ids with a turn in flight; restarts must wait for the boundary. */
+        runningAgents = new Set();
         notifiedInbox = new Map();
+        attachmentGcTimer;
+        recovery = new RecoveryCoordinator({
+            inject: (memberId, attempt, kind) => {
+                this.ctx.logger.info(`agent-team: automatic recovery steering member '${this.memberLabel(memberId)}' (attempt ${attempt}/${RECOVERY_MAX_ATTEMPTS}, ${kind})`);
+                this.injectRecovery(memberId, attempt, kind);
+            },
+            onStandDown: (memberId, attempts) => {
+                this.ctx.logger.warn(`agent-team: member '${this.memberLabel(memberId)}' still failing after ${attempts} automatic recovery attempts; leaving it in error for the operator`);
+            },
+        });
         lifecycleTail = Promise.resolve();
         accepting = true;
         changeVersion = 0;
@@ -165,11 +191,20 @@ let AgentTeam = (() => {
                 const member = this.memberForAgent(agent);
                 if (member === undefined)
                     return;
-                this.runtimeErrors.set(agent.id, error instanceof Error ? error.message : String(error));
+                const message = error instanceof Error ? error.message : String(error);
+                this.runtimeErrors.set(agent.id, message);
+                const kind = classifyRecoverableError(message);
+                if (kind !== undefined)
+                    this.ctx.logger.warn(`agent-team: member '${member.handle}' hit a recoverable error (${kind}); automatic recovery scheduled`);
+                this.recovery.onError(member.memberId, message);
                 this.emitChanged([{ kind: 'workspace', workspaceId: member.workspaceId }]);
             });
             this.ctx.on('agent/status', ({ agent, status }) => {
                 const member = this.memberForAgent(agent);
+                if (status === 'running')
+                    this.runningAgents.add(agent.id);
+                else
+                    this.runningAgents.delete(agent.id);
                 if (status === 'running' && member !== undefined) {
                     const recovered = this.runtimeErrors.delete(agent.id);
                     if (recovered)
@@ -177,14 +212,23 @@ let AgentTeam = (() => {
                     this.emitChanged([{ kind: 'workspace', workspaceId: member.workspaceId }]);
                     this.notifyMember(agent);
                 }
+                // A turn that ends without an error closes any automatic recovery episode.
+                if (status === 'idle' && member !== undefined && !this.runtimeErrors.has(agent.id)) {
+                    this.recovery.onCleanTurnEnd(member.memberId);
+                }
             });
             const domain = await this.ctx.storageDomain.open(agentTeamDomainSpec);
             this.ctx.effect(() => async () => {
                 this.accepting = false;
+                this.recovery.dispose();
+                if (this.attachmentGcTimer !== undefined)
+                    clearInterval(this.attachmentGcTimer);
+                this.attachmentGcTimer = undefined;
                 this.emitChanged();
                 await this.lifecycleTail;
                 await Promise.all([...this.handles.values()].map(handle => handle.dispose()));
                 this.handles.clear();
+                this.runningAgents.clear();
                 await domain.close();
             }, 'agentTeam.dispose');
             this.domain = domain;
@@ -193,6 +237,7 @@ let AgentTeam = (() => {
             const initialization = await ledger.initialize();
             if (initialization.committed)
                 this.emitCommitted(initialization.value);
+            this.startAttachmentGc(ledger);
             // One metadata listing serves every Member restore; per-member list calls
             // would repeat the same I/O linearly during startup.
             const persistedSessions = new Set((await this.ctx.sessionPersistence.list()).map(header => header.id));
@@ -293,6 +338,7 @@ let AgentTeam = (() => {
         async addMember(request) {
             return this.enqueueLifecycle(async () => {
                 const workspace = this.requireWorkspace(request.workspaceId);
+                await this.assertModelRoute(request.model);
                 const memberId = `member:${randomUUID()}`;
                 const member = Object.freeze({
                     memberId,
@@ -341,6 +387,129 @@ let AgentTeam = (() => {
                 return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(result.value.member) });
             });
         }
+        /**
+         * Operator nudge for an error-stopped Member: steer a continuation prompt
+         * into its live session. Runtime-only — no ledger operation, no suspend.
+         * Taking over manually also cancels any pending automatic recovery episode.
+         */
+        async recoverMember(request) {
+            this.requireAccepting();
+            const member = this.requireLedger().getMember(request.memberId);
+            if (member === undefined || member.workspaceId !== request.workspaceId)
+                throw new Error(`unknown Member '${request.memberId}' in workspace '${request.workspaceId}'`);
+            const storedError = this.storedErrorFor(member.memberId);
+            this.recovery.stopTracking(request.memberId);
+            const kind = classifyRecoverableError(storedError ?? '');
+            this.ctx.logger.info(`agent-team: operator asked member '${member.handle}' to resume`);
+            this.steerResume(member, this.resumeText(kind ?? 'unspecified failure', { operatorRequested: true }));
+            return Object.freeze({ status: this.memberStatus(member) });
+        }
+        /**
+         * Restart one enabled Member's live session in place: dispose the handle and
+         * reactivate on the same session id, so the transcript, private memory, and
+         * every ledger fact survive while tools and prompt templates are re-minted
+         * from the running plugin. The audit operation changes no projection state.
+         */
+        async restartMember(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 be restarted`);
+                const active = this.handles.get(request.memberId);
+                if (active === undefined)
+                    throw new Error(`Agent Member '${stored.handle}' has no active session to restart`);
+                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 restarting`);
+                const result = await this.requireLedger().restartMember({ ...request, actor: agentTeamHumanActor() });
+                if (result.committed)
+                    this.emitCommitted(result.value.receipt);
+                // 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);
+                this.runtimeErrors.delete(active.agent.id);
+                this.notifiedInbox.delete(request.memberId);
+                await active.dispose();
+                this.handles.delete(request.memberId);
+                this.diagnostics.delete(request.memberId);
+                await this.activateMember(stored);
+                const reactivated = this.handles.get(request.memberId);
+                if (reactivated === undefined) {
+                    // Reactivation failed; the activation diagnostic carries the reason and
+                    // the audit record stays honest about the attempt.
+                    throw new Error(`Agent Member '${stored.handle}' failed to reactivate: ${this.diagnostics.get(request.memberId) ?? 'unknown error'}`);
+                }
+                return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(stored) });
+            });
+        }
+        /** Ledger handle for log lines; falls back to the raw id when unknown. */
+        memberLabel(memberId) {
+            return this.ledger?.getMember(memberId)?.handle ?? memberId;
+        }
+        /**
+         * Cache GC: uploads referenced by a Message survive 72h from upload so
+         * Member agents keep a consumption window; orphans (never sent) go after
+         * 24h. Runs once at startup and then daily — in-process only, because the
+         * cache is transient by design and rebuilds nothing across restarts.
+         */
+        startAttachmentGc(ledger) {
+            const sweep = async () => {
+                await sweepAttachmentCache(attachmentsRoot(), ledger.referencedAttachmentIds(), Date.now());
+            };
+            void sweep();
+            this.attachmentGcTimer = setInterval(() => { void sweep(); }, 24 * 60 * 60 * 1000);
+            this.attachmentGcTimer.unref?.();
+        }
+        /** Latest runtime error summary for a Member's live session, if any. */
+        storedErrorFor(memberId) {
+            const handle = this.handles.get(memberId);
+            if (handle === undefined)
+                return undefined;
+            return this.runtimeErrors.get(handle.agent.id);
+        }
+        /**
+         * Continuation prompt per the recovery design: name the error family,
+         * annotate automatic attempts, and on the final attempt ask for a graceful
+         * handoff instead of another crash.
+         */
+        resumeText(kindLabel, options) {
+            const opening = options?.operatorRequested === true ? 'The operator asked you to resume. ' : '';
+            const attemptNote = options?.attempt === undefined ? '' : ` (automatic recovery, attempt ${options.attempt}/${RECOVERY_MAX_ATTEMPTS})`;
+            let text = `${opening}Your previous turn ended early due to an error (${kindLabel})${attemptNote}. Please continue your work from where it stopped.`;
+            if (options?.attempt === RECOVERY_MAX_ATTEMPTS) {
+                text += ' If the same error recurs, stop and leave a short handoff note for the operator.';
+            }
+            return text;
+        }
+        /**
+         * Steer one continuation message into a Member's live session. Throws when
+         * no handle exists so the coordinator stops tracking; appends the inbox
+         * snapshot whenever there is anything new to read.
+         */
+        steerResume(member, text) {
+            const handle = this.handles.get(member.memberId);
+            if (handle === undefined)
+                throw new Error(`member '${member.handle}' has no active session`);
+            const notifications = this.requireLedger().notificationFacts(member.memberId, { workspaceId: member.workspaceId });
+            const body = notifications.length === 0 ? text : `${text}\n\n${this.notificationText(notifications)}`;
+            const hint = createUserMessage({
+                content: [{ type: 'text', text: body }],
+                source: { kind: 'plugin', plugin: '@wowyuarm/dsh-agent-team', form: 'notice', summary: 'Recovery: continue your interrupted work.' },
+            });
+            handle.agent.steer(hint);
+        }
+        /** Automatic-recovery injection; throwing tells the coordinator the target is gone. */
+        injectRecovery(memberId, attempt, kind) {
+            const handle = this.handles.get(memberId);
+            const agent = handle?.agent;
+            const member = agent !== undefined ? this.memberForAgent(agent) : undefined;
+            if (agent === undefined || member === undefined || member.state !== 'enabled')
+                throw new Error(`member '${memberId}' cannot be recovered automatically`);
+            this.steerResume(member, this.resumeText(kind, { attempt }));
+        }
         /**
          * Human edit of one Member's mutable facts. A model change restarts an
          * active Member: single-Session Members read their selection only at
@@ -349,6 +518,7 @@ let AgentTeam = (() => {
          */
         async updateMember(request) {
             return this.enqueueLifecycle(async () => {
+                await this.assertModelRoute(request.model);
                 const previous = this.requireLedger().getMember(request.memberId);
                 const result = await this.requireLedger().updateMember({ ...request, actor: agentTeamHumanActor() });
                 if (result.committed)
@@ -413,15 +583,84 @@ let AgentTeam = (() => {
         async sendMessage(request) {
             this.requireAccepting();
             this.requireWorkspace(request.workspaceId);
-            const result = await this.requireLedger().sendMessage({ ...request, actor: agentTeamHumanActor() });
+            const metadata = await this.resolveMessageAttachments(request);
+            const result = await this.requireLedger().sendMessage({
+                ...request, body: this.appendAttachmentLines(request.body, metadata),
+                ...(metadata.length === 0 ? {} : { resolvedAttachments: metadata }),
+                actor: agentTeamHumanActor(),
+            });
             this.emitCommittedOutcome(result);
             return result.value;
         }
+        /**
+         * Resolve uploaded ids and agent-supplied absolute paths into one attachment
+         * metadata list. Paths are all validated before anything is copied, so one
+         * rejection leaves the cache untouched and the message uncommitted.
+         */
+        async resolveMessageAttachments(request) {
+            const fromPaths = [];
+            if (request.attachmentPaths !== undefined && request.attachmentPaths.length > 0) {
+                for (const absolutePath of request.attachmentPaths)
+                    await validatePathAttachment(absolutePath);
+                for (const absolutePath of request.attachmentPaths)
+                    fromPaths.push(Object.freeze(await copyPathAttachment(attachmentsRoot(), absolutePath)));
+            }
+            return [...fromPaths, ...await this.prepareAttachments(request.attachments)];
+        }
+        /** Verify requested attachment ids against the cache. */
+        async prepareAttachments(requested) {
+            if (requested === undefined || requested.length === 0)
+                return [];
+            const metadata = [];
+            for (const attachmentId of requested) {
+                const stored = await readAttachment(attachmentsRoot(), attachmentId);
+                if (stored === undefined)
+                    throw new Error(`attachment '${attachmentId}' is not in the upload cache`);
+                metadata.push(Object.freeze({ attachmentId, name: stored.name, byteSize: stored.byteSize, mediaType: stored.mediaType }));
+            }
+            return metadata;
+        }
+        /**
+         * Derive the stored body: one machine-facing `[attachment] <absolute path>`
+         * line per attachment appended to the member-facing text.
+         */
+        appendAttachmentLines(body, metadata) {
+            const trimmed = body.trim();
+            if (metadata.length === 0)
+                return trimmed;
+            const lines = metadata.map(attachment => `[attachment] ${dshHomePath('agent-team', 'attachments', 'v1', attachment.attachmentId, attachment.name)}`);
+            return `${trimmed}\n${lines.join('\n')}`;
+        }
+        /** Upload one composer attachment into the cache; bytes are immutable once written. */
+        async putAttachment(request) {
+            this.requireAccepting();
+            this.requireWorkspace(request.workspaceId);
+            const bytes = Buffer.from(request.bytesBase64, 'base64');
+            if (bytes.byteLength === 0)
+                throw new Error('attachment must not be empty');
+            if (bytes.byteLength > ATTACHMENT_MAX_BYTES)
+                throw new Error(`attachment exceeds the ${ATTACHMENT_MAX_BYTES} byte limit`);
+            const mediaType = sanitizeMediaType(request.mediaType);
+            const attachmentId = newAttachmentId();
+            return Object.freeze(await writeAttachment(attachmentsRoot(), attachmentId, request.name, mediaType, bytes));
+        }
+        /** Read one cached attachment back for client display; gone entries throw and the UI degrades to a chip. */
+        async getAttachment(request) {
+            const stored = await readAttachment(attachmentsRoot(), request.attachmentId);
+            if (stored === undefined)
+                throw new Error(`attachment '${request.attachmentId}' is no longer cached`);
+            return Object.freeze({ name: stored.name, mediaType: stored.mediaType, byteSize: stored.byteSize, bytesBase64: stored.bytes.toString('base64') });
+        }
         /** Human existing-Thread reply; unread and revision conflicts are business outcomes. */
         async reply(request) {
             this.requireAccepting();
             this.requireWorkspace(request.workspaceId);
-            const result = await this.requireLedger().reply({ ...request, actor: agentTeamHumanActor() });
+            const metadata = await this.resolveMessageAttachments(request);
+            const result = await this.requireLedger().reply({
+                ...request, body: this.appendAttachmentLines(request.body, metadata),
+                ...(metadata.length === 0 ? {} : { resolvedAttachments: metadata }),
+                actor: agentTeamHumanActor(),
+            });
             this.emitCommittedOutcome(result);
             return result.value;
         }
@@ -468,7 +707,12 @@ let AgentTeam = (() => {
             this.requireAccepting();
             const actor = this.memberActor(agent);
             this.requireAgentWorkspace(actor, request.workspaceId);
-            const result = await this.requireLedger().sendMessage({ ...request, actor });
+            const metadata = await this.resolveMessageAttachments(request);
+            const result = await this.requireLedger().sendMessage({
+                ...request, body: this.appendAttachmentLines(request.body, metadata),
+                ...(metadata.length === 0 ? {} : { resolvedAttachments: metadata }),
+                actor,
+            });
             this.emitCommittedOutcome(result);
             return result.value;
         }
@@ -477,7 +721,12 @@ let AgentTeam = (() => {
             this.requireAccepting();
             const actor = this.memberActor(agent);
             this.requireAgentWorkspace(actor, request.workspaceId);
-            const result = await this.requireLedger().reply({ ...request, actor });
+            const metadata = await this.resolveMessageAttachments(request);
+            const result = await this.requireLedger().reply({
+                ...request, body: this.appendAttachmentLines(request.body, metadata),
+                ...(metadata.length === 0 ? {} : { resolvedAttachments: metadata }),
+                actor,
+            });
             this.emitCommittedOutcome(result);
             return result.value;
         }
@@ -565,6 +814,26 @@ let AgentTeam = (() => {
             if (this.requireLedger().getMember(actor.memberId)?.workspaceId !== workspaceId)
                 throw new Error('Member cannot mutate another Workspace');
         }
+        /**
+         * Validate a pinned model route's reasoning effort against the adapter's own
+         * metadata when the LLM service is reachable; unknown routes defer to the
+         * LLM layer's runtime check at call time.
+         */
+        async assertModelRoute(model) {
+            if (model === undefined || model.reasoningEffort === undefined)
+                return;
+            try {
+                const resolved = await this.ctx.llm.resolveModelInfo(model.provider, model.model);
+                const efforts = resolved.reasoning?.efforts ?? [];
+                if (efforts.length > 0 && !efforts.some(effort => effort.id === model.reasoningEffort)) {
+                    throw new Error(`reasoning effort '${model.reasoningEffort}' is not supported by ${model.provider}/${model.model}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.includes('is not supported by'))
+                    throw error;
+            }
+        }
         async activateMember(member, knownWorkspacePath, knownSessions) {
             if (this.handles.has(member.memberId))
                 return;