@wowyuarm/dsh-agent-team 0.1.9 → 0.1.11

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;
+    }
+}

package/packages/agent-team/lib/time-format.js

@@ -0,0 +1,56 @@
+/**
+ * The one agent-facing Team timestamp formatter.
+ *
+ * Ledger storage keeps UTC ISO instants (`occurredAt` on every operation);
+ * rendering converts them into the fixed Team coordination zone UTC+8 with
+ * an explicit offset (`2026-09-08T17:00:00+08:00`). The conversion is a
+ * fixed offset with no daylight-saving component, so the same stored instant
+ * renders byte-identically on every reread path — the context-cache
+ * invariant. The Web Client keeps its own browser-local rendering and never
+ * passes through this module; a future configuration layer may make the
+ * zone configurable, but the render must stay a single deterministic
+ * formatter per stored instant.
+ * @module @wowyuarm/dsh-agent-team/time-format
+ */
+/** The fixed Team coordination offset from UTC, in minutes. */
+const TEAM_ZONE_OFFSET_MINUTES = 8 * 60;
+/** Rendered offset text, e.g. `+08:00`. */
+const OFFSET_TEXT = '+08:00';
+/**
+ * Format one stored UTC ISO instant as the agent-facing Team timestamp.
+ * @param occurredAt - stored UTC ISO 8601 instant (ledger `occurredAt`).
+ * @returns the fixed-offset UTC+8 rendering, or the input unchanged when it
+ * cannot be parsed (never a fabricated time).
+ */
+export function formatTeamTimestamp(occurredAt) {
+    const instant = Date.parse(occurredAt);
+    if (!Number.isFinite(instant))
+        return occurredAt;
+    const shifted = new Date(instant + TEAM_ZONE_OFFSET_MINUTES * 60_000);
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${shifted.getUTCFullYear()}-${pad(shifted.getUTCMonth() + 1)}-${pad(shifted.getUTCDate())}`
+        + `T${pad(shifted.getUTCHours())}:${pad(shifted.getUTCMinutes())}:${pad(shifted.getUTCSeconds())}${OFFSET_TEXT}`;
+}
+/**
+ * Format a non-negative elapsed millisecond count as compact whole-second
+ * units (`2d 3h 12m 8s`), mirroring the shipped harness time-context
+ * vocabulary so both clock families read the same way.
+ */
+export function formatTeamDuration(elapsedMs) {
+    let seconds = Math.floor(Math.max(0, elapsedMs) / 1000);
+    const days = Math.floor(seconds / 86_400);
+    seconds %= 86_400;
+    const hours = Math.floor(seconds / 3600);
+    seconds %= 3600;
+    const minutes = Math.floor(seconds / 60);
+    seconds %= 60;
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    parts.push(`${seconds}s`);
+    return parts.join(' ');
+}