@wowyuarm/dsh-agent-team 0.1.0 → 0.1.2

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

@@ -76,8 +76,6 @@ export class AgentTeamLedger {
             const description = request.description.trim();
             if (name === '')
                 throw new Error('channel name must not be empty');
-            if (description === '')
-                throw new Error('channel description must not be empty');
             const memberIds = this.normalizeUnique(request.memberIds, 'initial Channel members');
             for (const memberId of memberIds)
                 this.assertJoinableMember(request.workspaceId, memberId);
@@ -107,8 +105,6 @@ export class AgentTeamLedger {
             const description = request.description.trim();
             if (name === '')
                 throw new Error('channel name must not be empty');
-            if (description === '')
-                throw new Error('channel description must not be empty');
             const channel = Object.freeze({ ...this.requireChannel(request.workspaceId, request.channelRef), name, description });
             const operation = Object.freeze({
                 ...this.operationBase(request, this.nextSequence()), kind: 'team/channel-updated',
@@ -132,13 +128,11 @@ export class AgentTeamLedger {
             const presetId = request.presetId.trim();
             if (handle === '')
                 throw new Error('member handle must not be empty');
-            if (description === '')
-                throw new Error('member description must not be empty');
             if (presetId === '')
                 throw new Error('member preset must not be empty');
+            // Description and initial Channels are optional: a Member with neither is
+            // still drivable through its DM view, and joins Channels later.
             const channelRefs = this.normalizeUnique(request.channelRefs, 'initial Member Channels');
-            if (channelRefs.length === 0)
-                throw new Error('Agent Member requires at least one initial Channel');
             for (const channelRef of channelRefs)
                 this.requireChannel(request.workspaceId, channelRef);
             this.assertHandleAvailable(request.workspaceId, handle);
@@ -172,8 +166,6 @@ export class AgentTeamLedger {
             const description = request.description.trim();
             if (handle === '')
                 throw new Error('member handle must not be empty');
-            if (description === '')
-                throw new Error('member description must not be empty');
             if (handle !== prior.handle)
                 this.assertHandleAvailable(prior.workspaceId, handle, prior.memberId);
             this.assertModelSelection(request.model);
@@ -292,7 +284,9 @@ export class AgentTeamLedger {
             const thread = Object.freeze({ threadRef, taskRef, revision: sequence });
             const message = Object.freeze({
                 messageRef: this.ref('message'), channelRef: channel.channelRef, threadRef, taskRef,
-                sender: request.actor.memberId, body, topLevel: true, sequence, occurredAt: base.occurredAt,
+                sender: request.actor.memberId, body,
+                ...(request.resolvedAttachments === undefined ? {} : { attachments: request.resolvedAttachments }),
+                topLevel: true, sequence, occurredAt: base.occurredAt,
             });
             const started = [this.startAttention(request.actor.memberId, threadRef, sequence),
                 ...recipients.filter(memberId => this.state.members.has(memberId))
@@ -345,7 +339,9 @@ export class AgentTeamLedger {
             const base = this.operationBase(request, sequence);
             const message = Object.freeze({
                 messageRef: this.ref('message'), channelRef: task.channelRef, threadRef: task.threadRef,
-                taskRef: task.taskRef, sender: request.actor.memberId, body, topLevel: false, sequence, occurredAt: base.occurredAt,
+                taskRef: task.taskRef, sender: request.actor.memberId, body,
+                ...(request.resolvedAttachments === undefined ? {} : { attachments: request.resolvedAttachments }),
+                topLevel: false, sequence, occurredAt: base.occurredAt,
             });
             const nextThread = Object.freeze({ ...thread, revision: sequence });
             const started = unfollowedAgents.map(memberId => this.startAttention(memberId, thread.threadRef, sequence));
@@ -456,13 +452,24 @@ export class AgentTeamLedger {
                 throw new Error(`Task '${task.taskRef}' is already ${task.resolution}`);
             if (request.action === 'close' && task.resolution === 'closed')
                 throw new Error(`Task '${task.taskRef}' is already closed`);
-            if (request.action === 'accept' && task.status !== 'in_review')
-                throw new Error(`Task '${task.taskRef}' must be in_review before acceptance`);
+            // 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`);
+            }
+            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) {
+                throw new Error(`Task '${task.taskRef}' has no active Claims to complete for early acceptance`);
+            }
             if (request.action === 'reopen' && task.resolution === 'open')
                 throw new Error(`Task '${task.taskRef}' is already open`);
             const sequence = this.nextSequence();
-            const claims = [...this.state.claims.values()].filter(claim => claim.taskRef === task.taskRef).map(claim => request.action === 'close' && claim.state === 'active' ? Object.freeze({ ...claim, state: 'released' }) : claim);
+            const claims = [...this.state.claims.values()].filter(claim => claim.taskRef === task.taskRef).map(claim => request.action === 'close' && claim.state === 'active' ? Object.freeze({ ...claim, state: 'released' })
+                : request.action === 'accept' && claim.state === 'active' ? Object.freeze({ ...claim, state: 'done' })
+                    : claim);
             const releasedClaims = claims.filter(claim => claim.state === 'released' && this.state.claims.get(claim.claimRef)?.state === 'active');
+            const completedClaims = claims.filter(claim => claim.state === 'done' && this.state.claims.get(claim.claimRef)?.state === 'active');
             const resolution = request.action === 'reopen' ? 'open' : request.action === 'accept' ? 'accepted' : 'closed';
             const status = resolution === 'accepted' ? 'done' : resolution === 'closed' ? 'closed'
                 : this.deriveTaskStatus(task.taskRef, claims);
@@ -470,12 +477,13 @@ export class AgentTeamLedger {
             const nextThread = Object.freeze({ ...thread, revision: sequence });
             const activity = Object.freeze({ activityRef: this.ref('activity'), kind: request.action,
                 taskRef: task.taskRef, threadRef: task.threadRef, actor: request.actor.memberId, sequence,
-                ...(releasedClaims.length === 0 ? {} : { releasedClaimRefs: Object.freeze(releasedClaims.map(claim => claim.claimRef)) }) });
+                ...(releasedClaims.length === 0 ? {} : { releasedClaimRefs: Object.freeze(releasedClaims.map(claim => claim.claimRef)) }),
+                ...(completedClaims.length === 0 ? {} : { completedClaimRefs: Object.freeze(completedClaims.map(claim => claim.claimRef)) }) });
             const inbox = request.action === 'close'
                 ? this.closeThreadInbox(activity, thread.threadRef)
                 : request.action === 'reopen'
                     ? this.reopenThreadInbox(activity, thread.threadRef)
-                    : this.inboxDelta();
+                    : this.acceptThreadInbox(activity, thread.threadRef, completedClaims.map(claim => claim.owner));
             const operation = Object.freeze({
                 ...this.operationBase(request, sequence), kind: 'team/task-changed',
                 data: Object.freeze({ workspaceId: request.workspaceId, baseRevision: request.baseRevision,
@@ -684,6 +692,17 @@ export class AgentTeamLedger {
                 return undefined;
         }
     }
+    /** Attachment ids referenced by any stored Message — the GC's keep-set oracle. */
+    referencedAttachmentIds() {
+        const referenced = new Set();
+        for (const fact of this.state.orderedFacts) {
+            if (fact.kind !== 'message')
+                continue;
+            for (const attachment of fact.message.attachments ?? [])
+                referenced.add(attachment.attachmentId);
+        }
+        return referenced;
+    }
     threadHistory(actor, request) {
         const authorized = this.assertActorForWorkspace(actor, request.workspaceId);
         const task = this.requireTask(request.workspaceId, request.taskRef);
@@ -713,6 +732,21 @@ export class AgentTeamLedger {
     getTask(taskRef) {
         return this.state.tasks.get(taskRef);
     }
+    getClaim(claimRef) {
+        return this.state.claims.get(claimRef);
+    }
+    /** Navigation facts for message-body Task refs; unknown refs are omitted. */
+    resolveTaskRefs(workspaceId, taskRefs) {
+        const numbers = this.taskNumbers(workspaceId);
+        const resolved = [];
+        for (const taskRef of taskRefs) {
+            const task = this.state.tasks.get(taskRef);
+            if (task === undefined || this.state.channels.get(task.channelRef)?.workspaceId !== workspaceId)
+                continue;
+            resolved.push(Object.freeze({ taskRef: task.taskRef, channelRef: task.channelRef, threadRef: task.threadRef, taskNumber: numbers.get(task.taskRef) ?? 0 }));
+        }
+        return resolved;
+    }
     view(request, memberId) {
         const limit = request.limit ?? 20;
         const direction = request.direction ?? 'after';
@@ -814,6 +848,7 @@ export class AgentTeamLedger {
             case 'team/member-added':
             case 'team/member-suspended':
             case 'team/member-resumed':
+            case 'team/member-session-restarted':
             case 'team/member-updated':
             case 'team/member-removed':
                 return [{ kind: 'workspace', workspaceId: operation.data.member.workspaceId }];
@@ -968,7 +1003,7 @@ export class AgentTeamLedger {
         if (operation.kind === 'team/member-added') {
             assertHuman();
             const { member, channelRefs } = operation.data;
-            if (projection.members.has(member.memberId) || channelRefs.length === 0 || new Set(channelRefs).size !== channelRefs.length)
+            if (projection.members.has(member.memberId) || new Set(channelRefs).size !== channelRefs.length)
                 throw new Error('invalid Member creation');
             this.addRef(refs, member.memberId);
             for (const channelRef of channelRefs) {
@@ -987,6 +1022,14 @@ export class AgentTeamLedger {
                 throw new Error('invalid Member lifecycle transition');
             return;
         }
+        if (operation.kind === 'team/member-session-restarted') {
+            assertHuman();
+            const prior = projection.members.get(operation.data.member.memberId);
+            // The restart records the unchanged Member: same identity, still enabled.
+            if (prior === undefined || prior.state !== 'enabled' || !this.sameMemberIdentity(prior, operation.data.member))
+                throw new Error('invalid Member restart');
+            return;
+        }
         if (operation.kind === 'team/channel-updated') {
             assertHuman();
             const prior = projection.channels.get(operation.data.channel.channelRef);
@@ -1161,12 +1204,18 @@ export class AgentTeamLedger {
             const expectedResolution = activity.kind === 'accept' ? 'accepted' : activity.kind === 'close' ? 'closed' : 'open';
             const expectedStatus = expectedResolution === 'accepted' ? 'done' : expectedResolution === 'closed' ? 'closed'
                 : this.deriveTaskStatus(task.taskRef, operation.data.claims);
+            const expectedCompletedClaimRefs = operation.data.claims
+                .filter(claim => projection.claims.get(claim.claimRef)?.state === 'active' && claim.state === 'done')
+                .map(claim => claim.claimRef);
             if (task.resolution !== expectedResolution || task.status !== expectedStatus
                 || (activity.kind !== 'close' && activity.releasedClaimRefs !== undefined)
+                || (activity.kind !== 'accept' && activity.completedClaimRefs !== undefined)
                 || (activity.kind === 'close' && !this.sameList(activity.releasedClaimRefs ?? [], operation.data.claims
                     .filter(claim => projection.claims.get(claim.claimRef)?.state === 'active' && claim.state === 'released')
-                    .map(claim => claim.claimRef))))
+                    .map(claim => claim.claimRef)))
+                || !this.sameList(activity.completedClaimRefs ?? [], expectedCompletedClaimRefs)) {
                 throw new Error('invalid Task state transition');
+            }
             const priorClaims = [...projection.claims.values()].filter(claim => claim.taskRef === task.taskRef).sort((left, right) => left.claimRef.localeCompare(right.claimRef));
             const operationClaims = [...operation.data.claims].sort((left, right) => left.claimRef.localeCompare(right.claimRef));
             if (priorClaims.length !== operationClaims.length || priorClaims.some((claim, index) => claim.claimRef !== operationClaims[index]?.claimRef))
@@ -1177,7 +1226,9 @@ export class AgentTeamLedger {
                     throw new Error('invalid Task Claim identity');
                 const legal = activity.kind === 'close'
                     ? (previousClaim.state === 'active' ? claim.state === 'released' : claim.state === previousClaim.state)
-                    : claim.state === previousClaim.state;
+                    : activity.kind === 'accept'
+                        ? (previousClaim.state === 'active' ? claim.state === 'done' : claim.state === previousClaim.state)
+                        : claim.state === previousClaim.state;
                 if (!legal)
                     throw new Error('invalid Task Claim transition');
             }
@@ -1186,7 +1237,7 @@ export class AgentTeamLedger {
                 ? this.closeThreadInboxFrom(projection, activity, thread.threadRef)
                 : activity.kind === 'reopen'
                     ? this.reopenThreadInboxFrom(projection, activity, thread.threadRef)
-                    : this.inboxDelta();
+                    : this.acceptThreadInboxFrom(projection, activity, thread.threadRef, expectedCompletedClaimRefs);
             if (!isDeepStrictEqual(operation.data.inbox, expectedInbox))
                 throw new Error('invalid Task inbox projection');
             this.validateInboxDelta(operation.data.inbox, projection, refs, [], [], [activity]);
@@ -1367,6 +1418,11 @@ export class AgentTeamLedger {
             target.members.set(operation.data.member.memberId, operation.data.member);
             return;
         }
+        if (operation.kind === 'team/member-session-restarted') {
+            // Audit-only: identity, transcript, and memory are untouched, so the
+            // projection deliberately does not change.
+            return;
+        }
         if (operation.kind === 'team/channel-updated') {
             target.channels.set(operation.data.channel.channelRef, operation.data.channel);
             return;
@@ -1602,6 +1658,25 @@ export class AgentTeamLedger {
             activityRef: activity.activityRef, sequence: activity.sequence }));
         return this.inboxDelta([], removed, [], [...projection.directMarkers.values()].filter(marker => marker.threadRef === threadRef), activityMarkers, [...projection.activityMarkers.values()].filter(marker => marker.threadRef === threadRef));
     }
+    /**
+     * Early acceptance completes open Claims inside the accept operation; their
+     * owners learn about it through activity markers regardless of whether they
+     * still follow the Thread. Plain accepts (no completed Claims) stay silent.
+     */
+    acceptThreadInbox(activity, threadRef, completedOwners) {
+        if (completedOwners.length === 0)
+            return this.inboxDelta();
+        const recipients = [...new Set(completedOwners)].filter(memberId => memberId !== activity.actor);
+        const markers = recipients.map(memberId => Object.freeze({ memberId, threadRef,
+            activityRef: activity.activityRef, sequence: activity.sequence }));
+        return this.inboxDelta([], [], [], [], markers);
+    }
+    acceptThreadInboxFrom(projection, activity, threadRef, completedClaimRefs) {
+        if (completedClaimRefs.length === 0)
+            return this.inboxDelta();
+        const owners = completedClaimRefs.map(claimRef => projection.claims.get(claimRef)?.owner).filter(owner => owner !== undefined);
+        return this.acceptThreadInbox(activity, threadRef, owners);
+    }
     reopenThreadInbox(activity, threadRef) {
         return this.reopenThreadInboxFrom(this.state, activity, threadRef);
     }
@@ -1972,7 +2047,8 @@ export class AgentTeamLedger {
     assertSameMessage(operation, request, recipients) {
         if (operation.kind !== 'team/message-sent' || !this.sameActor(operation.actor, request.actor)
             || operation.data.workspaceId !== request.workspaceId || operation.data.message.channelRef !== request.channelRef
-            || operation.data.message.body !== request.body.trim() || !this.sameList(operation.data.mentions, recipients))
+            || operation.data.message.body !== request.body.trim() || !this.sameList(operation.data.mentions, recipients)
+            || !this.sameList(operation.data.message.attachments?.map(attachment => attachment.attachmentId) ?? [], request.attachments ?? []))
             this.throwRequestCollision(request.requestId);
     }
     assertSameReply(operation, request, recipients) {

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

@@ -0,0 +1,87 @@
+const TRANSIENT_NETWORK_PATTERNS = [/fetch failed/i, /econnreset/i, /etimedout/i, /socket hang up/i];
+const RATE_LIMIT_PATTERNS = [/\b429\b/, /rate limit/i, /\b503\b/, /overloaded/i];
+export function classifyRecoverableError(message) {
+    if (RATE_LIMIT_PATTERNS.some(pattern => pattern.test(message)))
+        return 'rate limiting';
+    if (TRANSIENT_NETWORK_PATTERNS.some(pattern => pattern.test(message)))
+        return 'transient network';
+    return undefined;
+}
+export const RECOVERY_DELAY_MS = 120_000;
+export const RECOVERY_MAX_ATTEMPTS = 3;
+/**
+ * Per-member automatic recovery episodes. One episode covers a run of
+ * identical errors; a changed error string starts a fresh one, and any clean
+ * turn end clears the slate. After `maxAttempts` injections of the same error
+ * the coordinator stands down and leaves the Member in error for the operator.
+ */
+export class RecoveryCoordinator {
+    episodes = new Map();
+    inject;
+    onStandDown;
+    delayMs;
+    maxAttempts;
+    constructor(options) {
+        this.inject = options.inject;
+        this.onStandDown = options.onStandDown;
+        this.delayMs = options.delayMs ?? RECOVERY_DELAY_MS;
+        this.maxAttempts = options.maxAttempts ?? RECOVERY_MAX_ATTEMPTS;
+    }
+    /** Observe one error occurrence for a Member. */
+    onError(memberId, errorMessage) {
+        const kind = classifyRecoverableError(errorMessage);
+        if (kind === undefined) {
+            // A non-retryable failure cancels anything pending: retrying cannot help.
+            this.stopTracking(memberId);
+            return;
+        }
+        let episode = this.episodes.get(memberId);
+        if (episode === undefined || episode.lastError !== errorMessage) {
+            this.cancelTimer(episode);
+            episode = { kind, lastError: errorMessage, attempts: 0 };
+            this.episodes.set(memberId, episode);
+        }
+        else if (episode.attempts >= this.maxAttempts) {
+            // The same error survived every allowed injection — stand down once.
+            if (episode.stoodDown !== true) {
+                episode.stoodDown = true;
+                this.onStandDown?.(memberId, episode.attempts);
+            }
+            return;
+        }
+        if (episode.timer !== undefined)
+            return;
+        episode.timer = setTimeout(() => {
+            episode.timer = undefined;
+            episode.attempts += 1;
+            try {
+                this.inject(memberId, episode.attempts, kind);
+            }
+            catch {
+                this.stopTracking(memberId);
+            }
+        }, this.delayMs);
+    }
+    /** A turn ended cleanly (running→idle without an error): the episode is over. */
+    onCleanTurnEnd(memberId) {
+        this.stopTracking(memberId);
+    }
+    stopTracking(memberId) {
+        const episode = this.episodes.get(memberId);
+        if (episode === undefined)
+            return;
+        this.cancelTimer(episode);
+        this.episodes.delete(memberId);
+    }
+    dispose() {
+        for (const episode of this.episodes.values())
+            this.cancelTimer(episode);
+        this.episodes.clear();
+    }
+    cancelTimer(episode) {
+        if (episode?.timer === undefined)
+            return;
+        clearTimeout(episode.timer);
+        episode.timer = undefined;
+    }
+}

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

@@ -11,6 +11,7 @@ const taskRefSchema = z.string().regex(/^task:[^:]+$/).transform(value => value)
 const threadRefSchema = z.string().regex(/^thread:[^:]+$/).transform(value => value);
 const claimRefSchema = z.string().regex(/^claim:[^:]+$/).transform(value => value);
 const activityRefSchema = z.string().regex(/^activity:[^:]+$/).transform(value => value);
+const attachmentIdSchema = z.string().min(1).transform(value => value);
 const actorSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('human'), memberId: memberIdSchema, handle: z.string().min(1) }).strict(),
     z.object({ kind: z.literal('member'), memberId: memberIdSchema, handle: z.string().min(1) }).strict(),
@@ -25,13 +26,18 @@ const operationBase = {
 const modelSelectionSchema = z.object({
     provider: z.string().min(1),
     model: z.string().min(1),
-}).strict();
+    reasoningEffort: z.string().min(1).transform(value => value).optional(),
+}).strict().transform(({ provider, model, reasoningEffort }) => ({
+    provider,
+    model,
+    ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+}));
 const memberSchema = z.object({
     memberId: memberIdSchema,
     sessionId: sessionIdSchema,
     workspaceId: workspaceIdSchema,
     handle: z.string().min(1),
-    description: z.string().min(1),
+    description: z.string(),
     presetId: z.string().min(1),
     // Ledgers written before per-Member model selection existed omit the field.
     model: modelSelectionSchema.optional(),
@@ -42,10 +48,18 @@ const channelSchema = z.object({
     channelRef: channelRefSchema,
     workspaceId: workspaceIdSchema,
     name: z.string().min(1),
-    description: z.string().min(1),
+    description: z.string(),
     createdAtSequence: z.number().int().positive(),
 }).strict();
-// Ledgers written before message occurredAt existed store bare messages; the union schema below stamps them on load.
+// Ledgers written before message occurredAt or attachments existed store bare
+// messages; the union schema below stamps occurredAt on load and leaves absent
+// attachment metadata undefined, so old ledgers replay unchanged.
+const attachmentSchema = z.object({
+    attachmentId: attachmentIdSchema,
+    name: z.string().min(1),
+    byteSize: z.number().int().nonnegative(),
+    mediaType: z.string().min(1),
+}).strict();
 const messageSchema = z.object({
     messageRef: messageRefSchema,
     channelRef: channelRefSchema,
@@ -53,6 +67,7 @@ const messageSchema = z.object({
     taskRef: taskRefSchema,
     sender: memberIdSchema,
     body: z.string().min(1),
+    attachments: z.array(attachmentSchema).optional(),
     topLevel: z.boolean(),
     sequence: z.number().int().positive(),
     occurredAt: z.string().datetime().optional(),
@@ -145,6 +160,7 @@ const taskActivitySchema = z.object({
     ...activityBase,
     kind: z.union([z.literal('accept'), z.literal('close'), z.literal('reopen')]),
     releasedClaimRefs: z.array(claimRefSchema).min(1).optional(),
+    completedClaimRefs: z.array(claimRefSchema).min(1).optional(),
 }).strict();
 const claimsReleasedActivitySchema = z.object({
     ...activityBase,
@@ -198,7 +214,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         ...operationBase,
         previousOperationId: operationIdSchema.nullable(),
         kind: z.literal('team/member-added'),
-        data: z.object({ member: memberSchema, channelRefs: z.array(channelRefSchema).min(1) }).strict(),
+        data: z.object({ member: memberSchema, channelRefs: z.array(channelRefSchema) }).strict(),
     }).strict(),
     z.object({
         ...operationBase,
@@ -212,6 +228,12 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         kind: z.literal('team/member-resumed'),
         data: z.object({ member: memberSchema }).strict(),
     }).strict(),
+    z.object({
+        ...operationBase,
+        previousOperationId: operationIdSchema.nullable(),
+        kind: z.literal('team/member-session-restarted'),
+        data: z.object({ member: memberSchema }).strict(),
+    }).strict(),
     z.object({
         ...operationBase,
         previousOperationId: operationIdSchema.nullable(),