@akagilnc/pi-workflow-roles 0.1.3565 → 0.1.3621

package/dist/run-terminal-artifacts.js

@@ -0,0 +1,195 @@
+/**
+ * Canonical reader for run-directory typed terminal artifacts.
+ * Layout owner is settlement publish*Artifacts (report.json / error.json /
+ * audit-incomplete.json under artifacts/, plus the same publisher's durable
+ * failure fallbacks). This module only reads presence and structural
+ * readability — it does not re-derive role outcomes or invent a second
+ * candidate algorithm.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+export const RUN_TERMINAL_ARTIFACT_FILES = [
+    "report.json",
+    "error.json",
+    "audit-incomplete.json",
+];
+/**
+ * Fixed durable failure paths publishFailureArtifacts may settle when the
+ * conventional artifacts/error.json name cannot be written. Shared face so the
+ * reader follows the publisher — not a parallel search algorithm.
+ * Relative to the run directory.
+ */
+export const RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS = [
+    "artifacts/error.settlement.json",
+    "error.settlement.json",
+];
+/** Unique open-ended failure names: error.<uuid>.json (publisher stem + uuid). */
+const UNIQUE_ERROR_FALLBACK_NAME = /^error\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$/i;
+function isMissingPathError(error) {
+    return (error instanceof Error
+        && "code" in error
+        && (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Minimum producer-owned face shared by settlement terminal artifacts
+ * (report / error / audit-incomplete). Consumer-driven: enough to identify a
+ * usable typed terminal artifact; null, arrays, primitives, and role-less
+ * objects are unreadable (ADR 0043).
+ */
+function readUsableTerminalArtifactBody(body) {
+    if (body === null) {
+        return { ok: false, reason: "terminal artifact JSON value is null" };
+    }
+    if (!isRecord(body)) {
+        return {
+            ok: false,
+            reason: `terminal artifact JSON value is not a typed object (${Array.isArray(body) ? "array" : typeof body})`,
+        };
+    }
+    if (typeof body.role !== "string" || body.role.trim() === "") {
+        return {
+            ok: false,
+            reason: "terminal artifact missing nonblank producer-owned role field",
+        };
+    }
+    return { ok: true, body };
+}
+async function readTerminalArtifactAtPath(path, file) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return undefined;
+        return {
+            status: "unreadable",
+            file,
+            path,
+            reason: errorText(error),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            status: "unreadable",
+            file,
+            path,
+            reason: error instanceof Error
+                ? error.message
+                : `terminal artifact JSON parse failed: ${String(error)}`,
+        };
+    }
+    const usable = readUsableTerminalArtifactBody(parsed);
+    if (!usable.ok) {
+        return {
+            status: "unreadable",
+            file,
+            path,
+            reason: usable.reason,
+        };
+    }
+    return { status: "present", file, path, body: usable.body };
+}
+async function listUniqueErrorFallbackPaths(directories) {
+    const found = [];
+    for (const dir of directories) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch (error) {
+            if (isMissingPathError(error))
+                continue;
+            throw error;
+        }
+        for (const name of names.sort((a, b) => a.localeCompare(b))) {
+            if (!UNIQUE_ERROR_FALLBACK_NAME.test(name))
+                continue;
+            found.push(join(dir, name));
+        }
+    }
+    return found;
+}
+/**
+ * Publisher run-directory face is `<runId>@<role>`. Parent-directory unique
+ * fallbacks are shared across sibling runs, so binding uses this runId only.
+ * Sole authority for runDirectory → runId (last `@` split).
+ */
+export function runIdFromRunDirectory(runDirectory) {
+    const name = basename(runDirectory);
+    const at = name.lastIndexOf("@");
+    if (at <= 0 || at === name.length - 1)
+        return undefined;
+    return name.slice(0, at);
+}
+/**
+ * Shared parent-directory unique fallback may be adopted only when the
+ * publisher-owned body.runId equals this run directory's runId. Same-run
+ * artifactsDir / runDirectory candidates keep path ownership and skip this.
+ */
+function presentUniqueFallbackBoundToRun(body, expectedRunId) {
+    if (expectedRunId === undefined)
+        return false;
+    return typeof body.runId === "string" && body.runId === expectedRunId;
+}
+/**
+ * Read the first present typed terminal artifact for a run directory.
+ * Order:
+ * 1) conventional artifacts/{report,error,audit-incomplete}.json
+ * 2) publisher fixed failure fallbacks (error.settlement.json faces)
+ * 3) publisher unique error.<uuid>.json fallbacks under same-run dirs
+ * 4) shared parent-directory unique fallbacks bound by body.runId
+ *
+ * Absence of every known durable face is a valid no-receipt state (not unreadable).
+ * A present file that cannot be parsed as a usable typed JSON object is unreadable.
+ */
+export async function readRunTerminalArtifact(runDirectory) {
+    const artifactsDir = join(runDirectory, "artifacts");
+    for (const file of RUN_TERMINAL_ARTIFACT_FILES) {
+        const path = join(artifactsDir, file);
+        const read = await readTerminalArtifactAtPath(path, file);
+        if (read !== undefined)
+            return read;
+    }
+    // Publisher settled a durable failure outside the conventional error.json name.
+    for (const relative of RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS) {
+        const path = join(runDirectory, relative);
+        const read = await readTerminalArtifactAtPath(path, "error.json");
+        if (read !== undefined)
+            return read;
+    }
+    // Same-run unique faces: path ownership is the run itself — no cross-run risk.
+    for (const path of await listUniqueErrorFallbackPaths([artifactsDir, runDirectory])) {
+        const read = await readTerminalArtifactAtPath(path, "error.json");
+        if (read !== undefined)
+            return read;
+    }
+    // Shared parent (runs/) unique faces: require publisher runId binding.
+    const expectedRunId = runIdFromRunDirectory(runDirectory);
+    for (const path of await listUniqueErrorFallbackPaths([dirname(runDirectory)])) {
+        const read = await readTerminalArtifactAtPath(path, "error.json");
+        if (read === undefined)
+            continue;
+        if (read.status === "present") {
+            if (!presentUniqueFallbackBoundToRun(read.body, expectedRunId))
+                continue;
+            return read;
+        }
+        // Unreadable parent unique file cannot prove run identity — do not adopt.
+    }
+    return { status: "absent" };
+}
+/** Test/helper: basename face of a unique fallback path, if any. */
+export function isUniqueErrorFallbackName(name) {
+    return UNIQUE_ERROR_FALLBACK_NAME.test(basename(name));
+}

package/dist/run-ticket-number.js

@@ -0,0 +1,40 @@
+/**
+ * Typed ticketNumber reader for a retained run's durable pages.
+ * admitted-request.json first, invocation.json fallback. Missing page (ENOENT)
+ * → try next / undefined; damage and non-ENOENT IO failures propagate.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+function isEnoent(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function ticketFromRecord(record) {
+    const ticketNumber = record.ticketNumber;
+    if (typeof ticketNumber === "number" &&
+        Number.isSafeInteger(ticketNumber) &&
+        ticketNumber >= 1) {
+        return ticketNumber;
+    }
+    return undefined;
+}
+async function readPageTicketNumber(runDirectory, page) {
+    try {
+        const raw = JSON.parse(await readFile(join(runDirectory, page), "utf8"));
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            return undefined;
+        }
+        return ticketFromRecord(raw);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Sole reader of ticketNumber from a retained run's admitted then invocation pages. */
+export async function readRunTicketNumber(runDirectory) {
+    return ((await readPageTicketNumber(runDirectory, "admitted-request.json")) ??
+        (await readPageTicketNumber(runDirectory, "invocation.json")));
+}

package/dist/session-assistant-usage.js

@@ -0,0 +1,107 @@
+import { join } from "node:path";
+export async function readAssistantUsageFromSessionFile(sessionFile) {
+    const { readFile } = await import("node:fs/promises");
+    let text;
+    try {
+        text = await readFile(sessionFile, "utf8");
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    let rows;
+    try {
+        rows = text
+            .trim()
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch (error) {
+        throw new Error(`session usage parse failed (${sessionFile}): ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    let total = 0;
+    let input = 0;
+    let output = 0;
+    let cacheRead = 0;
+    let cacheWrite = 0;
+    let costInput = 0;
+    let costOutput = 0;
+    let costCacheRead = 0;
+    let costCacheWrite = 0;
+    let costTotal = 0;
+    let sawCost = false;
+    for (const row of rows) {
+        if (row.type !== "message" || row.message?.role !== "assistant")
+            continue;
+        const usage = row.message.usage;
+        if (usage === undefined)
+            continue;
+        total += usage.totalTokens ?? 0;
+        input += usage.input ?? 0;
+        output += usage.output ?? 0;
+        cacheRead += usage.cacheRead ?? 0;
+        cacheWrite += usage.cacheWrite ?? 0;
+        if (usage.cost !== undefined) {
+            sawCost = true;
+            costInput += usage.cost.input ?? 0;
+            costOutput += usage.cost.output ?? 0;
+            costCacheRead += usage.cost.cacheRead ?? 0;
+            costCacheWrite += usage.cost.cacheWrite ?? 0;
+            costTotal += usage.cost.total ?? 0;
+        }
+    }
+    if (total <= 0 && input <= 0 && output <= 0)
+        return undefined;
+    const base = {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        totalTokens: total > 0 ? total : input + output + cacheRead + cacheWrite,
+    };
+    // Cost only when session rows carried it — unknown stays absent (not zero).
+    if (!sawCost)
+        return base;
+    return {
+        ...base,
+        cost: {
+            input: costInput,
+            output: costOutput,
+            cacheRead: costCacheRead,
+            cacheWrite: costCacheWrite,
+            total: costTotal,
+        },
+    };
+}
+/**
+ * Resolve the independent role run's session.jsonl from a public summon result.
+ * Prefers explicit runDirectory, then terminal artifacts, then no_receipt runPointer.
+ */
+export function sessionFileFromPublicSummon(summoned) {
+    if (typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== "") {
+        return join(summoned.runDirectory, "session", "session.jsonl");
+    }
+    const fromArtifacts = summoned.terminal?.artifacts
+        ?.map((a) => a.path)
+        .find((p) => typeof p === "string" && p.endsWith("session.jsonl"));
+    if (fromArtifacts !== undefined)
+        return fromArtifacts;
+    const outcome = summoned.terminal?.roleOutcome;
+    if (outcome === undefined)
+        return undefined;
+    const facts = outcome.decisiveFacts;
+    const pointer = facts?.runPointer;
+    if (typeof pointer === "string" && pointer.trim() !== "") {
+        return join(pointer, "session", "session.jsonl");
+    }
+    return undefined;
+}
+/** Shared usage projection for nested public summons — undefined when unknown. */
+export async function usageFromPublicSummon(summoned) {
+    const sessionFile = sessionFileFromPublicSummon(summoned);
+    if (sessionFile === undefined)
+        return undefined;
+    return readAssistantUsageFromSessionFile(sessionFile);
+}

package/dist/shape-unreadable-failure.js

@@ -0,0 +1,34 @@
+/**
+ * Single authoritative shape-unreadable marker (#675 / ADR 0055).
+ * Settlement stamps it; consumers only read it — never re-derive from cause=output.
+ */
+export const SHAPE_UNREADABLE_KEY = "shapeUnreadable";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Settlement seat path: stamp retained candidate as shape-unreadable (not infrastructure). */
+export function stampShapeUnreadableDetails(candidate) {
+    return {
+        [SHAPE_UNREADABLE_KEY]: true,
+        candidate,
+        acceptedReceipt: false,
+    };
+}
+/**
+ * Read the settlement-stamped shape candidate from a failure decisiveFacts payload.
+ * Looks at root and secondaryEvidence only for the typed marker — no cause inference.
+ */
+export function retainedShapeUnreadable(decisiveFacts) {
+    if (!isRecord(decisiveFacts))
+        return undefined;
+    if (decisiveFacts[SHAPE_UNREADABLE_KEY] === true) {
+        return { candidate: decisiveFacts.candidate };
+    }
+    const secondary = isRecord(decisiveFacts.secondaryEvidence)
+        ? decisiveFacts.secondaryEvidence
+        : undefined;
+    if (secondary !== undefined && secondary[SHAPE_UNREADABLE_KEY] === true) {
+        return { candidate: secondary.candidate };
+    }
+    return undefined;
+}

package/dist/submission-errors.js

@@ -3,6 +3,9 @@ function gatekeeperNonPassMessage(result) {
         const findings = result.findings.length === 0 ? "（无 findings）" : result.findings.join("; ");
         return `门下省打回重写，findings：${findings}`;
     }
+    if (result.status === "unreadable") {
+        return `门下省官回执形状不可读（${result.officer}）：${result.reason}`;
+    }
     return `门下省 ${result.status}（${result.stage}）：${result.reason}`;
 }
 /** Structured non-pass; `.result` is session-projected via tool_result, message feeds the model. */