@wowyuarm/dsh-agent-team 0.1.0 → 0.1.1

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);
@@ -199,6 +191,31 @@ export class AgentTeamLedger {
     resumeMember(request) {
         return this.setMemberState(request, 'enabled');
     }
+    /**
+     * Audit record of one in-place Member session restart. The operation changes
+     * no projection state — identity, transcript, and memory are untouched — so
+     * replay treats it as a marker while the Host re-mints the live handle.
+     */
+    restartMember(request) {
+        return this.enqueue(async () => {
+            const existing = this.state.byRequest.get(request.requestId);
+            if (existing !== undefined) {
+                this.assertSameMemberRestart(existing, request);
+                return this.resolved(this.memberResult(existing));
+            }
+            this.assertHumanActor(request.actor);
+            const member = this.requireMember(request.memberId);
+            if (member.state !== 'enabled')
+                throw new Error(`Agent Member '${member.handle}' is ${member.state}; only enabled Members can be restarted`);
+            const operation = Object.freeze({
+                ...this.operationBase(request, this.nextSequence()), kind: 'team/member-session-restarted',
+                data: Object.freeze({ member }),
+            });
+            await this.table.put(operation.operationId, operation);
+            this.apply(operation);
+            return this.committed(this.memberResult(operation));
+        });
+    }
     getMember(memberId) {
         return this.state.members.get(memberId);
     }
@@ -292,7 +309,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 +364,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));
@@ -684,6 +705,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);
@@ -814,6 +846,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 }];
@@ -987,6 +1020,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);
@@ -1367,6 +1408,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;
@@ -1941,6 +1987,11 @@ export class AgentTeamLedger {
             || !this.sameList(operation.data.channelRefs, this.normalizeUnique(request.channelRefs, 'initial Member Channels')))
             this.throwRequestCollision(request.requestId);
     }
+    assertSameMemberRestart(operation, request) {
+        if (operation.kind !== 'team/member-session-restarted' || !this.sameActor(operation.actor, request.actor)
+            || operation.data.member.memberId !== request.memberId)
+            this.throwRequestCollision(request.requestId);
+    }
     assertSameMemberState(operation, request, state) {
         const kind = state === 'suspended' ? 'team/member-suspended' : 'team/member-resumed';
         if (operation.kind !== kind || !this.sameActor(operation.actor, request.actor) || operation.data.member.memberId !== request.memberId)
@@ -1972,7 +2023,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(),
@@ -45,7 +46,15 @@ const channelSchema = z.object({
     description: z.string().min(1),
     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 +62,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(),
@@ -212,6 +222,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(),