@wowyuarm/dsh-agent-team 0.1.10 → 0.1.12

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

@@ -216,6 +216,48 @@ const claimOperation = (kind) => z.object({
         inbox: inboxDeltaSchema,
     }).strict(),
 }).strict();
+/**
+ * The five departure-fact collections a releasing operation persists. All four
+ * release kinds carry this snapshot under their own `kind` literal and their own
+ * identifying fields; the durable half that must stay identical lives here once,
+ * so a new release kind cannot silently drop or invent a field.
+ */
+const releaseSnapshotFields = {
+    claims: z.array(claimSchema),
+    activities: z.array(claimsReleasedActivitySchema),
+    tasks: z.array(taskSchema),
+    threads: z.array(threadSchema),
+    inbox: inboxDeltaSchema,
+};
+/** The receipt form every new read writes: the progress it made and the Inbox delta it consumed. */
+const threadReadReceiptDataSchema = z.object({
+    workspaceId: workspaceIdSchema,
+    memberId: memberIdSchema,
+    threadRef: threadRefSchema,
+    taskRef: taskRefSchema.optional(),
+    readThroughSequence: z.number().int().nonnegative(),
+    inbox: inboxDeltaSchema,
+}).strict().transform(omitUndefined);
+/**
+ * The pre-receipt Thread-read snapshot. Still accepted so a ledger written
+ * before the receipt form keeps opening; both shapes are strict, so a stored
+ * record parses as exactly one of them.
+ */
+const threadReadSnapshotDataSchema = z.object({
+    workspaceId: workspaceIdSchema,
+    memberId: memberIdSchema,
+    task: taskSchema.optional(),
+    thread: threadSchema,
+    claims: z.array(claimSchema),
+    anchor: messageSchema,
+    anchorMentions: z.array(memberIdSchema),
+    facts: z.array(readFactSchema),
+    readThroughSequence: z.number().int().nonnegative(),
+    remainingUnreadCount: z.number().int().nonnegative(),
+    earlierFactCount: z.number().int().nonnegative().optional(),
+    attention: attentionSchema.optional(),
+    inbox: inboxDeltaSchema,
+}).strict().transform(omitUndefined);
 /** Closed Agent Team operation union before occurrence stamping. */
 const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
     z.object({
@@ -258,11 +300,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         kind: z.literal('team/member-archived'),
         data: z.object({
             member: memberSchema,
-            claims: z.array(claimSchema),
-            activities: z.array(claimsReleasedActivitySchema),
-            tasks: z.array(taskSchema),
-            threads: z.array(threadSchema),
-            inbox: inboxDeltaSchema,
+            ...releaseSnapshotFields,
         }).strict(),
     }).strict(),
     z.object({
@@ -324,11 +362,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
             workspaceId: workspaceIdSchema,
             channelRef: channelRefSchema,
             memberId: memberIdSchema,
-            claims: z.array(claimSchema),
-            activities: z.array(claimsReleasedActivitySchema),
-            tasks: z.array(taskSchema),
-            threads: z.array(threadSchema),
-            inbox: inboxDeltaSchema,
+            ...releaseSnapshotFields,
         }).strict(),
     }).strict(),
     z.object({
@@ -338,11 +372,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         data: z.object({
             workspaceId: workspaceIdSchema,
             channel: channelSchema,
-            claims: z.array(claimSchema),
-            activities: z.array(claimsReleasedActivitySchema),
-            tasks: z.array(taskSchema),
-            threads: z.array(threadSchema),
-            inbox: inboxDeltaSchema,
+            ...releaseSnapshotFields,
         }).strict(),
     }).strict(),
     z.object({
@@ -419,20 +449,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         ...operationBase,
         previousOperationId: operationIdSchema.nullable(),
         kind: z.literal('team/thread-read'),
-        data: z.object({
-            workspaceId: workspaceIdSchema,
-            memberId: memberIdSchema,
-            task: taskSchema.optional(),
-            thread: threadSchema,
-            claims: z.array(claimSchema),
-            anchor: messageSchema,
-            anchorMentions: z.array(memberIdSchema),
-            facts: z.array(readFactSchema),
-            readThroughSequence: z.number().int().nonnegative(),
-            remainingUnreadCount: z.number().int().nonnegative(),
-            attention: attentionSchema.optional(),
-            inbox: inboxDeltaSchema,
-        }).strict().transform(omitUndefined),
+        data: z.union([threadReadReceiptDataSchema, threadReadSnapshotDataSchema]),
     }).strict(),
     z.object({
         ...operationBase,
@@ -440,11 +457,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         kind: z.literal('team/member-removed'),
         data: z.object({
             member: memberSchema,
-            claims: z.array(claimSchema),
-            activities: z.array(claimsReleasedActivitySchema),
-            tasks: z.array(taskSchema),
-            threads: z.array(threadSchema),
-            inbox: inboxDeltaSchema,
+            ...releaseSnapshotFields,
         }).strict(),
     }).strict(),
     z.object({

package/packages/agent-team/lib/stored-session-reader.js

@@ -0,0 +1,138 @@
+/**
+ * The Team's single seam for reading stored Sessions.
+ *
+ * Every per-Session read the Host performs goes through here: one
+ * `open → read → close` cycle whose handle lifecycle is guaranteed closed,
+ * and whose failures are normalized into the five categories consumers choose
+ * policy by. Callers never touch a `SessionHandle`, an artifact path, a
+ * format generation, or Harness error message text.
+ *
+ * The reader owns reading and classification only — not Member lifecycle,
+ * Agent create/resume, UI, ledger, or remediation (which reads raw artifact
+ * bytes through its own repair path).
+ *
+ * Classification notes: the shipped JSONL backend throws its
+ * `corrupt session log` family as plain `Error`s, so corruption is detected by
+ * that stable message prefix (an upstream gap; if the text ever changes the
+ * failure degrades to `unknown`, which consumers treat conservatively —
+ * blocking rather than silently skipping). Typed refusals are also matched
+ * through `error.cause` chains because the Harness agent layer wraps
+ * persistence failures during resume.
+ * @module @wowyuarm/dsh-agent-team/stored-session-reader
+ */
+import { SessionFormatUnsupportedError, SessionPersistenceCorruptionError, SessionPersistenceNotFoundError, } from '@deepseek-ai/dsh-session-persistence';
+/**
+ * A call site's session-read failure, carrying the typed classification so
+ * activation can route the diagnostic without re-matching error text.
+ */
+export class StoredSessionReadError extends Error {
+    failure;
+    constructor(message, failure) {
+        super(message);
+        this.failure = failure;
+        this.name = 'StoredSessionReadError';
+    }
+}
+/** How deep to follow `error.cause` chains looking for a typed session failure. */
+const MAX_CAUSE_DEPTH = 4;
+/** The JSONL backend's stable corruption-message prefix (plain `Error`s, not typed). */
+const CORRUPT_SESSION_LOG_TEXT = /corrupt session log/;
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The deterministic session-shaped classification of one error value:
+ * typed Harness failures plus the corruption message family. A system error
+ * code is deliberately NOT matched here — outside the reader an fs error may
+ * come from unrelated work (private memory, attachment cache), so only the
+ * reader itself, where the failed operation is known to be a session read,
+ * may classify an fs error as `io`.
+ */
+function sessionClassOf(error) {
+    if (error instanceof SessionPersistenceNotFoundError)
+        return { kind: 'missing' };
+    if (error instanceof SessionFormatUnsupportedError) {
+        return { kind: 'refused', ...(error.location === undefined ? {} : { location: error.location }) };
+    }
+    if (error instanceof SessionPersistenceCorruptionError)
+        return { kind: 'corrupt' };
+    if (error instanceof Error && CORRUPT_SESSION_LOG_TEXT.test(error.message))
+        return { kind: 'corrupt' };
+    return undefined;
+}
+/** The first session-shaped classification in an error's cause chain, with the matched error for its message. */
+function sessionClassInChain(error) {
+    let current = error;
+    for (let depth = 0; current !== undefined && current !== null && depth <= MAX_CAUSE_DEPTH; depth += 1) {
+        const classified = sessionClassOf(current);
+        if (classified !== undefined)
+            return { classified, matched: current };
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return undefined;
+}
+/**
+ * Classify any failure as a stored-Session read failure. Total: unmatched
+ * errors become `unknown`, and a direct system error code becomes `io` —
+ * call this only where the failed operation is known to be a session read.
+ */
+export function classifyStoredSessionFailure(error, sessionId) {
+    const inChain = sessionClassInChain(error);
+    if (inChain !== undefined) {
+        return { kind: inChain.classified.kind, sessionId, detail: messageOf(inChain.matched), ...('location' in inChain.classified ? { location: inChain.classified.location } : {}) };
+    }
+    if (error !== null && typeof error === 'object' && typeof error.code === 'string') {
+        return { kind: 'io', sessionId, detail: messageOf(error) };
+    }
+    return { kind: 'unknown', sessionId, detail: messageOf(error) };
+}
+/**
+ * The session-shaped failure carried by an arbitrary error, when it carries
+ * one at all: deterministic markers (typed classes, the corruption message
+ * family) are matched through the cause chain; transient fs errors are not —
+ * outside the reader they are not provably session-related. Activation uses
+ * this to route diagnostics; `undefined` means the failure is not
+ * session-shaped.
+ */
+export function sessionFailureOf(error, sessionId) {
+    const inChain = sessionClassInChain(error);
+    if (inChain === undefined)
+        return undefined;
+    return { kind: inChain.classified.kind, sessionId, detail: messageOf(inChain.matched), ...('location' in inChain.classified ? { location: inChain.classified.location } : {}) };
+}
+/** Read stored Sessions through one seam: full validated reads with normalized failures. */
+export class StoredSessionReader {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Read one stored Session completely. The handle is closed on every path;
+     * any failure of open, read, or close is returned as its normalized
+     * category, never thrown.
+     */
+    async read(sessionId) {
+        try {
+            const handle = await this.ctx.sessionPersistence.open(sessionId, 'read');
+            try {
+                const { events } = await handle.read();
+                return { ok: true, inspection: { header: handle.header, inheritedEventCount: handle.inheritedEventCount, events } };
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            return { ok: false, failure: classifyStoredSessionFailure(error, sessionId) };
+        }
+    }
+    /**
+     * Whether one stored Session has durable persisted content, decided through
+     * `stat`: the backend reports a still-draining session through its pending
+     * header, so this is the existence probe activation relies on. Only the
+     * missing case returns `false`; unexpected errors propagate as before.
+     */
+    async exists(sessionId) {
+        return (await this.ctx.sessionPersistence.stat(sessionId)) !== undefined;
+    }
+}