@arnilo/prism 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.2.5] - 2026-08-15
+
+### Changed
+- **Release 0.2.5 (plan 025)** is the maintainability-and-bounded-performance cut on the 0.2.x review-remediation line. API surface **additive-only** (plain reviewed compat gate at 0.2.5: expected deltas are the version literal plus 105 additive internal-helper exports — 84 Task 1 cross-family helpers across core/coding-agent/workflows/server/ag-ui and 21 `prism-session-store-codecs` helpers; zero removals; no `--allow-break`). Five roadmap items, no runtime contract change and no migration: (1) **god-module splits** (`god-module-split`, 0.1.4 precedent) — the six remaining implementation god-modules split along cohesive boundaries into internal family files behind preserved barrels: `src/contracts-core.ts` (1,719 L → 10 families, max 403 L), `src/agent-session.ts` (2,049 L → 4 modules; the 1,686-L `RuntimeAgentSession` class kept intact — a single TS class cannot span files without exporting private methods, recorded reason), `packages/workflows/src/run.ts` (1,227 L → 6 families, max 417 L), `packages/server/src/handler.ts` (1,005 L → 8 families, max 444 L), `packages/coding-agent/src/repository.ts` (974 L → 7 families, max 299 L), `packages/ag-ui/src/acp/agent.ts` (836 L → 8 families, max 386 L); no `exports`-map subpath added; `ponytail:` comments preserved; zero breaking compat deltas (`scripts/phase25-compat-diff.mjs`). (2) **persistence-mechanics dedup** (`session-store-codecs`) — 21 pure helpers (ownership scope/assertion, checkpoint stale/encode/decode, branch cursors, lifecycle quota/reason/page-limit, search metadata/clipping, deepFreeze/string-array/throwIfAborted, feedback row mapping) moved into the dependency-free codecs package (426 → 624 L, stdlib only); the postgres/sqlite adapters shrank 273 lines total; SQL dialect/DDL/query execution stay per-adapter; no persisted-shape change; cross-store conformance green before/after. (3) **quadratic accumulation removed** (`bounded-accumulation`) — the per-push `Buffer.concat` loops in `LspFrameReader` (language framing) and `summarizeTarStream` (tar parsing) became chunk-array readers (two-phase header parse, offset-advance drop, take/drop sliding window); caps + fail-closed overflow byte-identical; framing ~100–200× faster at 4,000 chunks (1,298.4 ms → 11.2 ms), tar linear at 8 MiB; CLI `collectOutput` audited and kept (already linear, plan 020); the 10-test near-limit probe `scripts/phase25-bounded-accumulation.test.mjs` is wired into the npm test gate segment and asserts linear copying by byte-count instrumentation. (4) **dead-code cleanup, internal-only** (`dead-code`) — the 62 `dead-exports.mjs` candidates triaged in `docs/_evidence/phase25-dead-exports-triage.md`: 2 internal removals (`PostgresPersistenceCloseOptions`, `SqlitePersistenceCloseOptions` — never re-exported from their adapter indexes), 37 test-used false positives, 20 dead-but-compat-tracked + 3 public type aliases deferred to the 0.3.0 breaking cut; the named-internal audit (`agent-session`/`cache-telemetry`/`skill-load`) recorded clean at 0.2.4; no public export removed. (5) **coverage close, behavior-backed** (`coverage`) — 76 focused regressions (approval 43, conversations 22, artifacts 6, tool-effect-store conformance 5; compaction via its 17 existing package suites); core coverage 90.53/84.20/90.54 → **91.43/84.80/91.60** lines/branches/functions (gate 60/70/75; all 39 non-protected packages above their evidence thresholds). Release graph stays **50** publishable manifests at exact **0.2.5**; zero new runtime dependency names (core remains dependency-free). Store compatibility with 0.2.4: **compatible, no migration** (no persisted-shape change; rollback = restore the 0.2.4 manifests/tag — downgrade is store-safe and code-safe, the added exports simply disappear). Exit gate green (core + script gates incl. `phase24-truth` 12 + `phase25-bounded-accumulation` 10, coverage gate, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain reviewed compat gate at 0.2.5 — version literal + additive exports only, protected Postgres durable + cross-store conformance evidence per the release skip manifest, release-evidence manifest with zero blocked surfaces, evidence in `scripts/phase25-baseline.json`). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.2.5 publish handoff` — signed `v0.2.5` tag + npm OIDC).
+
 ## [0.2.4] - 2026-08-14
 
 ### Changed

package/dist/agent-session/create-agent.d.ts

@@ -0,0 +1,6 @@
+/** create-agent (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
+import type { Agent, AgentConfig, AgentSession, AgentSessionConfig } from "../contracts.js";
+export declare function createAgent(config: AgentConfig): Agent;
+export declare function createAgentSession(config: AgentSessionConfig & {
+    readonly agent: Agent;
+}): AgentSession;

package/dist/agent-session/create-agent.js

@@ -0,0 +1,13 @@
+import { RuntimeAgentSession } from "./session.js";
+export function createAgent(config) {
+    return {
+        config,
+        createSession(sessionConfig = {}) {
+            return createAgentSession({ ...sessionConfig, agent: this });
+        },
+    };
+}
+export function createAgentSession(config) {
+    return new RuntimeAgentSession(config);
+}
+//# sourceMappingURL=create-agent.js.map

package/dist/agent-session/event-subscriber.d.ts

@@ -0,0 +1,17 @@
+/** event-subscriber (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
+import type { AgentEvent, SubscribeOptions } from "../contracts.js";
+export declare class EventSubscriber implements AsyncIterable<AgentEvent>, AsyncIterator<AgentEvent> {
+    private readonly sessionId;
+    private readonly onClose;
+    private readonly queue;
+    private readonly waiters;
+    private readonly maxQueuedEvents;
+    private readonly overflow;
+    private closed;
+    constructor(sessionId: string, options: SubscribeOptions, onClose: () => void);
+    [Symbol.asyncIterator](): AsyncIterator<AgentEvent>;
+    next(): Promise<IteratorResult<AgentEvent>>;
+    return(): Promise<IteratorResult<AgentEvent>>;
+    push(event: AgentEvent): void;
+    close(): void;
+}

package/dist/agent-session/event-subscriber.js

@@ -0,0 +1,68 @@
+export class EventSubscriber {
+    sessionId;
+    onClose;
+    queue = [];
+    waiters = [];
+    maxQueuedEvents;
+    overflow;
+    closed = false;
+    constructor(sessionId, options, onClose) {
+        this.sessionId = sessionId;
+        this.onClose = onClose;
+        const maxQueuedEvents = options.maxQueuedEvents ?? 1024;
+        this.maxQueuedEvents = Number.isFinite(maxQueuedEvents) ? Math.max(1, Math.floor(maxQueuedEvents)) : 1024;
+        this.overflow = options.overflow ?? "close";
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    next() {
+        const event = this.queue.shift();
+        if (event)
+            return Promise.resolve({ value: event, done: false });
+        if (this.closed)
+            return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    return() {
+        this.close();
+        this.onClose();
+        return Promise.resolve({ value: undefined, done: true });
+    }
+    push(event) {
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({ value: event, done: false });
+            return;
+        }
+        if (this.closed)
+            return;
+        if (this.queue.length < this.maxQueuedEvents) {
+            this.queue.push(event);
+            return;
+        }
+        if (this.overflow === "drop_oldest") {
+            this.queue.shift();
+            this.queue.push(event);
+            return;
+        }
+        if (this.overflow === "drop_newest")
+            return;
+        const droppedEvents = this.queue.length + 1;
+        this.queue.splice(0, this.queue.length, {
+            type: "event_subscriber_overflow",
+            sessionId: this.sessionId,
+            droppedEvents,
+            maxQueuedEvents: this.maxQueuedEvents,
+            overflow: this.overflow,
+        });
+        this.close();
+        this.onClose();
+    }
+    close() {
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0))
+            waiter({ value: undefined, done: true });
+    }
+}
+//# sourceMappingURL=event-subscriber.js.map

package/dist/agent-session/helpers.d.ts

@@ -0,0 +1,44 @@
+/** helpers (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
+import type { CompactionOptions, ContentBlock, ErrorInfo, Guardrails, Message, ProviderEvent, RetryOptions, ToolCallContent, Usage } from "../contracts.js";
+import type { AgentInput } from "../input.js";
+import { createId } from "../ids.js";
+export declare function providerContent(event: Extract<ProviderEvent, {
+    type: "content_delta" | "tool_call";
+}>): ContentBlock;
+export declare function reconstructMissingToolCalls(deltas: readonly ProviderEvent[], calls: readonly ToolCallContent[]): readonly ToolCallContent[];
+export declare function inputToMessages(input: AgentInput): Message[];
+export declare function messageTextBytes(message: Message): number;
+export declare class SteerSoftInterrupt extends Error {
+    readonly code = "steer_soft_interrupt";
+    constructor();
+}
+export declare function isSteerSoftInterrupt(error: unknown): boolean;
+export declare function finalAssistantMessage(history: readonly Message[]): {
+    readonly message?: Message;
+    readonly content: readonly ContentBlock[];
+    readonly text: string;
+};
+export declare function errorFromInfo(error: ErrorInfo): Error;
+export declare class ProviderTurnFailure extends Error {
+    readonly info: ErrorInfo;
+    readonly observable: boolean;
+    constructor(info: ErrorInfo, observable: boolean);
+}
+export declare function mergeRetry(agent: false | RetryOptions | undefined, run: false | RetryOptions | undefined): RetryOptions | undefined;
+export declare function mergeCompaction(agent: false | CompactionOptions | undefined, run: false | CompactionOptions | undefined): CompactionOptions | undefined;
+/**
+ * Durable-run gate: built-in option forms and the single-shot singleton are durable via the
+ * pending-call mechanism; a custom strategy must declare both snapshot and restore hooks.
+ */
+export declare function isDurableLoop(loop: import("../contracts.js").AgentLoopStrategy | import("../contracts.js").AgentLoopOptions): boolean;
+export declare function mergeGuardrails(agent: Guardrails | undefined, run: Guardrails | undefined): Guardrails | undefined;
+export declare function withoutTrailingInput(messages: readonly Message[], input: readonly Message[]): Message[];
+export declare function bridgeAbort(signal: AbortSignal | undefined, controller: AbortController): () => void;
+export declare function throwIfAborted(signal: AbortSignal): void;
+export declare function throwIfAbortedSignal(signal: AbortSignal | undefined): void;
+export declare function jsonBytes(value: unknown): number;
+export declare function createUsageAccumulator(): {
+    add(usage: Usage): void;
+    value(): Usage | undefined;
+};
+export declare const randomId: typeof createId;

package/dist/agent-session/helpers.js

@@ -0,0 +1,194 @@
+import { createId } from "../ids.js";
+import { reconstructToolCallDeltas } from "../provider-events.js";
+import { singleShotLoop } from "../agent-loops.js";
+export function providerContent(event) {
+    return event.type === "content_delta" ? event.content : event.call;
+}
+export function reconstructMissingToolCalls(deltas, calls) {
+    if (deltas.length === 0)
+        return [];
+    const seen = new Set(calls.map((call) => call.id));
+    return reconstructToolCallDeltas(deltas).filter((call) => !seen.has(call.id));
+}
+export function inputToMessages(input) {
+    if (typeof input === "string")
+        return [{ role: "user", content: [{ type: "text", text: input }] }];
+    if ("role" in input)
+        return [input];
+    return [...input];
+}
+const steerTextEncoder = new TextEncoder();
+export function messageTextBytes(message) {
+    let total = 0;
+    for (const block of message.content) {
+        if (block.type === "text")
+            total += steerTextEncoder.encode(block.text).byteLength;
+    }
+    return total;
+}
+const STEER_SOFT_INTERRUPT_CODE = "steer_soft_interrupt";
+export class SteerSoftInterrupt extends Error {
+    code = STEER_SOFT_INTERRUPT_CODE;
+    constructor() {
+        super("Provider turn soft-interrupted by steer");
+        this.name = "SteerSoftInterrupt";
+    }
+}
+export function isSteerSoftInterrupt(error) {
+    return (error instanceof SteerSoftInterrupt ||
+        (typeof error === "object" && error !== null && error.code === STEER_SOFT_INTERRUPT_CODE));
+}
+export function finalAssistantMessage(history) {
+    for (let index = history.length - 1; index >= 0; index -= 1) {
+        const message = history[index];
+        if (message.role !== "assistant")
+            continue;
+        const text = message.content
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("");
+        return { message, content: message.content, text };
+    }
+    return { content: [], text: "" };
+}
+export function errorFromInfo(error) {
+    return Object.assign(new Error(error.message), { name: error.name ?? "Error", cause: error.cause, code: error.code });
+}
+export class ProviderTurnFailure extends Error {
+    info;
+    observable;
+    constructor(info, observable) {
+        super(info.message);
+        this.info = info;
+        this.observable = observable;
+    }
+}
+export function mergeRetry(agent, run) {
+    if (run === false)
+        return undefined;
+    if (run)
+        return { ...(agent || {}), ...run };
+    return agent || undefined;
+}
+export function mergeCompaction(agent, run) {
+    if (run === false)
+        return undefined;
+    if (run)
+        return { ...(agent || {}), ...run };
+    return agent || undefined;
+}
+/**
+ * Durable-run gate: built-in option forms and the single-shot singleton are durable via the
+ * pending-call mechanism; a custom strategy must declare both snapshot and restore hooks.
+ */
+export function isDurableLoop(loop) {
+    if (typeof loop !== "object" || loop === null)
+        return true;
+    if ("strategy" in loop)
+        return true;
+    if (loop === singleShotLoop)
+        return true;
+    return typeof loop.snapshot === "function" && typeof loop.restore === "function";
+}
+export function mergeGuardrails(agent, run) {
+    if (!agent && !run)
+        return undefined;
+    return {
+        input: [...(agent?.input ?? []), ...(run?.input ?? [])],
+        output: [...(agent?.output ?? []), ...(run?.output ?? [])],
+        toolInput: [...(agent?.toolInput ?? []), ...(run?.toolInput ?? [])],
+        toolOutput: [...(agent?.toolOutput ?? []), ...(run?.toolOutput ?? [])],
+        maxConcurrency: run?.maxConcurrency ?? agent?.maxConcurrency,
+    };
+}
+export function withoutTrailingInput(messages, input) {
+    const next = [...messages];
+    for (let i = input.length - 1; i >= 0; i -= 1) {
+        const last = next.at(-1);
+        if (last && stableMessageKey(last) === stableMessageKey(input[i]))
+            next.pop();
+    }
+    return next;
+}
+// Key-order-insensitive comparison: a redacted-then-reassembled message with reordered
+// keys must still dedupe against the trailing input, or auto-compaction duplicates it.
+function stableMessageKey(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableMessageKey).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableMessageKey(record[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+export function bridgeAbort(signal, controller) {
+    if (!signal)
+        return () => undefined;
+    const abort = () => controller.abort(signal.reason);
+    if (signal.aborted)
+        abort();
+    else
+        signal.addEventListener("abort", abort, { once: true });
+    return () => signal.removeEventListener("abort", abort);
+}
+export function throwIfAborted(signal) {
+    throwIfAbortedSignal(signal);
+}
+export function throwIfAbortedSignal(signal) {
+    if (signal?.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
+}
+const jsonTextEncoder = new TextEncoder();
+export function jsonBytes(value) {
+    try {
+        return jsonTextEncoder.encode(JSON.stringify(value)).byteLength;
+    }
+    catch {
+        throw new TypeError("Provider request or event must be JSON-serializable for run limits");
+    }
+}
+export function createUsageAccumulator() {
+    const sums = new Map();
+    let costCurrency;
+    let costCompatible = true;
+    return {
+        add(usage) {
+            for (const key of ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"]) {
+                const value = usage[key];
+                if (value !== undefined)
+                    sums.set(key, (sums.get(key) ?? 0) + value);
+            }
+            const total = usage.totalTokens ??
+                (usage.inputTokens !== undefined || usage.outputTokens !== undefined
+                    ? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
+                    : undefined);
+            if (total !== undefined)
+                sums.set("totalTokens", (sums.get("totalTokens") ?? 0) + total);
+            if (usage.cost !== undefined && costCompatible) {
+                if (!sums.has("cost"))
+                    costCurrency = usage.currency;
+                else if (usage.currency !== costCurrency)
+                    costCompatible = false;
+                if (costCompatible)
+                    sums.set("cost", (sums.get("cost") ?? 0) + usage.cost);
+            }
+        },
+        value() {
+            if (sums.size === 0)
+                return undefined;
+            const usage = {};
+            for (const [key, value] of sums) {
+                if (key !== "cost" || costCompatible)
+                    usage[key] = value;
+            }
+            if (costCompatible && sums.has("cost") && costCurrency !== undefined)
+                usage.currency = costCurrency;
+            return Object.keys(usage).length > 0 ? usage : undefined;
+        },
+    };
+}
+export const randomId = createId;
+//# sourceMappingURL=helpers.js.map

package/dist/agent-session/session.d.ts

@@ -0,0 +1,101 @@
+/** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
+import type { Agent, AgentEvent, AgentRunResult, AgentRunStateOptions, AgentSession, AgentSessionConfig, CompactionOptions, CompactionResult, OwnershipScope, RunDecision, RunOptions, SessionEntry, SteerOptions, SubscribeOptions } from "../contracts.js";
+import type { AgentInput } from "../input.js";
+import type { LoadedSkillBodiesEntry } from "../skill-load.js";
+import type { StoredAgentRunState } from "../agent-run-state.js";
+export declare class RuntimeAgentSession implements AgentSession {
+    readonly id: string;
+    private readonly agent;
+    private readonly metadata?;
+    private readonly store;
+    private readonly subscribers;
+    private currentLeafId?;
+    private history;
+    private activeRun?;
+    private activeRunId?;
+    private activeProviderTurnAbort?;
+    private pendingSoftInterrupt;
+    private pendingSteers;
+    private pendingSteerBytes;
+    private activeRedactor?;
+    private activeProvider?;
+    private activeLedger?;
+    private activeEffectStore?;
+    private activeOwnership?;
+    private activeIdentity?;
+    private activeIdempotencyKey?;
+    private activeGuardrails?;
+    private activeMetadata?;
+    private activeLimits?;
+    private activeLimitOutputBuffer;
+    private activeDurable?;
+    private activeLoop?;
+    /** Gated calls of the current tool round awaiting one collected suspension. */
+    private activeGatedRound?;
+    private activeLoopTurn;
+    private readonly loadedSkills;
+    /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
+    private restoredSkillBodies;
+    /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
+    private activeRunSkills;
+    /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
+    restoreLoadedSkills(names: readonly string[]): void;
+    /** Plan 018 Task 6: restore persisted loaded-skill bodies (already validated fail-closed at load). */
+    restoreLoadedSkillBodies(bodies: readonly LoadedSkillBodiesEntry[]): void;
+    private ledgerChain;
+    private ledgerFailure;
+    private snapshotGeneration;
+    private snapshotCache?;
+    constructor(config: AgentSessionConfig & {
+        readonly agent: Agent;
+    });
+    get leafId(): string | undefined;
+    subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
+    run(input: AgentInput, options?: RunOptions): Promise<AgentRunResult>;
+    steer(input: AgentInput, options?: SteerOptions): void;
+    resumeDurable(state: StoredAgentRunState, runState: AgentRunStateOptions, ownership?: OwnershipScope, signal?: AbortSignal, decisions?: ReadonlyMap<string, RunDecision>): Promise<AgentRunResult>;
+    recordDurableResumption(runId: string, interruption: import("../contracts.js").AgentRunInterruption, version: number, ownership?: OwnershipScope): Promise<void>;
+    recordDurableDenial(runId: string, interruption: import("../contracts.js").AgentRunInterruption, version: number, ownership?: OwnershipScope): Promise<void>;
+    private runInternal;
+    prompt(input: string, options?: RunOptions): Promise<AgentRunResult>;
+    stream(input: AgentInput, options?: RunOptions & SubscribeOptions): AsyncGenerator<AgentEvent>;
+    private buildRunResult;
+    private suspendDurable;
+    /** First attributed sticky whose scope and delegation path exactly match a nested decision. */
+    private matchNestedSticky;
+    /** First sticky decision whose scope exactly matches this call, if any. */
+    private matchStickyDecision;
+    /** Redacted pending-decision descriptor for one gated call; never carries raw arguments. */
+    private buildPendingDecision;
+    private persistDurable;
+    compact(options?: CompactionOptions): Promise<CompactionResult>;
+    abort(reason?: unknown): void;
+    entries(): Promise<readonly SessionEntry[]>;
+    checkout(leafId?: string): Promise<void>;
+    fork(options?: {
+        readonly leafId?: string;
+    }): AgentSession;
+    clone(options?: {
+        readonly id?: string;
+        readonly leafId?: string;
+    }): Promise<AgentSession>;
+    private branchReader;
+    private resolveRunProvider;
+    private resolveRunSkills;
+    private emit;
+    private closeSubscribers;
+    private drainLedger;
+    private generateWithRetry;
+    private generateProviderTurn;
+    private applyPendingSteers;
+    private applyProviderRequestPolicies;
+    private appendMessage;
+    private autoCompact;
+    private compactBranch;
+    private appendEntry;
+    private invalidateSnapshot;
+    private redact;
+    private redactProviderRequest;
+    private rebuildHistory;
+    private snapshot;
+}