@astrosheep/keiyaku 4.0.0 → 4.0.2

package/build/src/akuma/heart/timeline.js

@@ -0,0 +1,86 @@
+import { decodeActivityRow, decodeCallRow, decodeTurnRow, } from "./rows.js";
+import { decodeTellAtSequence, pendingTellProtectionSql, pendingTellSequencesSql } from "./tells.js";
+export function pruneActivityFacts(database, limit) {
+    const count = database.prepare("SELECT COUNT(*) AS count FROM timeline").get();
+    if (count.count <= limit + 500)
+        return;
+    const cutoff = database.prepare(`SELECT sequence FROM timeline ORDER BY sequence DESC LIMIT 1 OFFSET ?`)
+        .get(limit - 1);
+    if (cutoff === undefined)
+        return;
+    database.prepare(`WITH protected_turns(sequence) AS (
+      SELECT sequence FROM turns WHERE end_sequence IS NULL
+      UNION SELECT turn_sequence FROM calls WHERE sequence >= ?
+      UNION SELECT turn_sequence FROM activity WHERE sequence >= ?
+      UNION SELECT sequence FROM turns WHERE end_sequence >= ?
+      UNION ${pendingTellProtectionSql}
+    ), protected(sequence) AS (
+      SELECT sequence FROM protected_turns
+      UNION SELECT sequence FROM calls WHERE turn_sequence IN (SELECT sequence FROM protected_turns)
+      UNION SELECT end_sequence FROM turns WHERE sequence IN (SELECT sequence FROM protected_turns) AND end_sequence IS NOT NULL
+      UNION ${pendingTellSequencesSql}
+    )
+    DELETE FROM timeline WHERE sequence < ? AND sequence NOT IN protected`)
+        .run(cutoff.sequence, cutoff.sequence, cutoff.sequence, cutoff.sequence);
+}
+function turn(database, sequence) {
+    const row = database.prepare(`SELECT sequence, body_sequence, started_at, end_sequence, outcome,
+    history_id, session_json, answer, diagnostic, completed_at FROM turns WHERE sequence = ?`)
+        .get(sequence);
+    if (row === undefined)
+        throw new Error(`Akuma timeline references missing Turn ${sequence}`);
+    return decodeTurnRow(row);
+}
+function turnStart(database, sequence) {
+    const row = database.prepare("SELECT sequence, body_sequence, started_at FROM turns WHERE sequence = ?")
+        .get(sequence);
+    if (row === undefined)
+        throw new Error(`Akuma timeline references missing Turn ${sequence}`);
+    return { kind: "turn-start", sequence: row.sequence, bodySequence: row.body_sequence, startedAt: row.started_at };
+}
+function decodeTimelineRow(database, row) {
+    if (row.kind === "turn-start")
+        return turnStart(database, row.sequence);
+    if (row.kind === "turn-end") {
+        const source = database.prepare("SELECT sequence FROM turns WHERE end_sequence = ?").get(row.sequence);
+        const fact = source === undefined ? undefined : turn(database, source.sequence).end;
+        if (fact === undefined)
+            throw new Error(`Akuma timeline references missing Turn end ${row.sequence}`);
+        return fact;
+    }
+    if (row.kind === "call") {
+        const value = database.prepare("SELECT sequence, turn_sequence, body, at FROM calls WHERE sequence = ?")
+            .get(row.sequence);
+        if (value === undefined)
+            throw new Error(`Akuma timeline references missing call ${row.sequence}`);
+        return decodeCallRow(value);
+    }
+    if (row.kind === "activity") {
+        const value = database.prepare("SELECT sequence, turn_sequence, event_json, at FROM activity WHERE sequence = ?")
+            .get(row.sequence);
+        if (value === undefined)
+            throw new Error(`Akuma timeline references missing activity ${row.sequence}`);
+        return decodeActivityRow(value);
+    }
+    return decodeTellAtSequence(database, row.sequence);
+}
+export function activityFactSlice(database, input) {
+    const bounds = database.prepare("SELECT MIN(sequence) AS lowest, MAX(sequence) AS highest FROM timeline")
+        .get();
+    let rows;
+    if (input.before !== undefined) {
+        rows = database.prepare(`SELECT * FROM (
+      SELECT sequence, kind FROM timeline WHERE sequence < ? ORDER BY sequence DESC LIMIT ?
+    ) ORDER BY sequence`).all(input.before, input.limit);
+    }
+    else if (input.since !== undefined) {
+        rows = database.prepare(`SELECT sequence, kind FROM timeline WHERE sequence > ? ORDER BY sequence LIMIT ?`)
+            .all(input.since, input.limit);
+    }
+    else {
+        rows = database.prepare(`SELECT * FROM (
+      SELECT sequence, kind FROM timeline ORDER BY sequence DESC LIMIT ?
+    ) ORDER BY sequence`).all(input.limit);
+    }
+    return { rows: rows.map((row) => decodeTimelineRow(database, row)), lowestRetained: bounds.lowest, highest: bounds.highest };
+}

package/build/src/akuma/identity.d.ts

@@ -35,12 +35,12 @@ export declare function akuIdFromDirectoryName(name: string): Readonly<{
     archetype: string;
     suffix: string;
 }>;
-export declare function ensureAkumaRunRoot(worldRoot: string): string;
+export declare function ensureAkumaRunRoot(worldRoot: string): Promise<string>;
 export declare function allocateAkumaDirectory(input: Readonly<{
     worldRoot: string;
     archetype: string;
     draw?: () => string;
-}>): AllocatedAkuma;
+}>): Promise<AllocatedAkuma>;
 export declare function pathsForAkuId(worldRoot: string, id: AkuId): AkumaPaths;
 export declare function worldRootForAkumaPaths(paths: AkumaPaths): string;
 export {};

package/build/src/akuma/identity.js

@@ -1,12 +1,12 @@
 import { randomBytes } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { identityCoordinate, identitySegments } from "../identity/coordinates.js";
 import { normalizeIdentityStem } from "../identity/normalize.js";
 const HEX8 = /^[0-9a-f]{8}$/u;
 export function archetypeName(value) {
     if (value.length === 0 || normalizeIdentityStem({ source: value }) !== value) {
-        throw new TypeError("Akuma archetype must be one normalized human identity segment");
+        throw new TypeError("Akuma name must be one normalized human identity segment");
     }
     return value;
 }
@@ -24,7 +24,7 @@ export function akuId(input) {
 export function parseAkuId(value) {
     const segments = identitySegments({ family: "aku", value });
     if (segments.length !== 2)
-        throw new TypeError("Akuma identity must be aku/<archetype>/<hex8>");
+        throw new TypeError("Akuma identity must be aku/<akuma>/<hex8>");
     const archetype = archetypeName(segments[0]);
     const suffix = suffixSegment(segments[1]);
     return { id: akuId({ archetype, suffix }), archetype, suffix };
@@ -48,11 +48,11 @@ export function akuIdFromDirectoryName(name) {
     const suffix = name.slice(-8);
     return { id: akuId({ archetype, suffix }), archetype, suffix };
 }
-export function ensureAkumaRunRoot(worldRoot) {
+export async function ensureAkumaRunRoot(worldRoot) {
     const runRoot = akumaRunRoot(worldRoot);
-    mkdirSync(runRoot, { recursive: true });
+    await mkdir(runRoot, { recursive: true });
     try {
-        writeFileSync(join(runRoot, ".gitignore"), "*\n", { flag: "wx" });
+        await writeFile(join(runRoot, ".gitignore"), "*\n", { flag: "wx" });
     }
     catch (error) {
         if (error.code !== "EEXIST")
@@ -60,14 +60,14 @@ export function ensureAkumaRunRoot(worldRoot) {
     }
     return runRoot;
 }
-export function allocateAkumaDirectory(input) {
+export async function allocateAkumaDirectory(input) {
     const archetype = archetypeName(input.archetype);
-    const runRoot = ensureAkumaRunRoot(input.worldRoot);
+    const runRoot = await ensureAkumaRunRoot(input.worldRoot);
     for (;;) {
         const suffix = suffixSegment(input.draw?.() ?? randomBytes(4).toString("hex"));
         const paths = akumaPaths({ runRoot, archetype, suffix });
         try {
-            mkdirSync(paths.directory);
+            await mkdir(paths.directory);
             return { id: akuId({ archetype, suffix }), archetype, suffix, paths };
         }
         catch (error) {

package/build/src/akuma/index.d.ts

@@ -1,7 +1,14 @@
+import { type AkuId } from "./identity.js";
+import type { WorldRoot } from "../world.js";
 export { Akuma, AkumaHandle, AkumaNotBornError } from "./akuma.js";
-export { AkumaArchetypeError } from "./archetype.js";
+export type { WorldRoot } from "../world.js";
+export declare function probeBornAkuma(worldPath: WorldRoot, id: AkuId): Promise<boolean>;
+export { AkumaArchetypeError, listArchetypeDefinitions, listArchetypes } from "./archetype.js";
+export type { ArchetypeCatalogRow } from "./archetype.js";
 export { AkumaBodyRequestError } from "./requests.js";
-export type { AkumaList, AkumaListRow, AkumaStatus, ActivityHistory, ActivityRow, ActivitySnapshot, ForkReceipt, InterruptReceipt, TellReceipt, UnbornAkumaListRow, } from "./akuma.js";
+export type { AkumaList, AkumaListInput, AkumaListRow, AkumaStatus, ActivityHistory, ActivityRow, ActivitySnapshot, ActivitySnapshotEntry, ForkReceipt, InterruptReceipt, TellResult, UnbornAkumaListRow, } from "./akuma.js";
+export type { ActiveToolRow, ClosedTurn, ClosedTurnRow, CompletedToolRow, HistoryCursor, HistoryPage, IdleSnapshotRow, OpenSnapshotRow, OpenTurn, OpenTurnRow, OutcomeRow, RetainedWindow, Snapshot, SnapshotRow, TellRow, TurnLedger, TurnOutcome, TurnStartRow, UnsettledToolRow, } from "./akuma.js";
 export type { AgentEvent, ToolCall, ToolEvent, ToolResult } from "./provider.js";
 export type { AkuId } from "./identity.js";
-export type { Confinement, KillEvidence, ProviderOptions, ResumeCoordinate, TurnFact, } from "./heart/index.js";
+export type { Confinement, KillEvidence, ResumeCoordinate, TurnFact, } from "./heart/index.js";
+export type { ProviderOptions, ReadonlyRestraint } from "./provider-recipe.js";

package/build/src/akuma/index.js

@@ -1,3 +1,9 @@
+import { readSoul } from "./heart/index.js";
+import { pathsForAkuId } from "./identity.js";
 export { Akuma, AkumaHandle, AkumaNotBornError } from "./akuma.js";
-export { AkumaArchetypeError } from "./archetype.js";
+export async function probeBornAkuma(worldPath, id) {
+    const soul = await readSoul(pathsForAkuId(worldPath, id));
+    return soul !== null;
+}
+export { AkumaArchetypeError, listArchetypeDefinitions, listArchetypes } from "./archetype.js";
 export { AkumaBodyRequestError } from "./requests.js";

package/build/src/akuma/projection.d.ts

@@ -0,0 +1,176 @@
+import { type ToolCall, type ToolResult } from "./provider.js";
+import type { TellDelivery, TellFact, TimelineFact, TurnEndFact } from "./heart/index.js";
+export type TurnOutcome = TurnEndFact["outcome"];
+export type TurnStartRow = Readonly<{
+    kind: "turn";
+    sequence: number;
+    turnSequence: number;
+    bodySequence: number;
+    at: string;
+}>;
+type CallRow = Readonly<{
+    kind: "call";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    text: string;
+}>;
+type SaidRow = Readonly<{
+    kind: "said";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    text: string;
+    truncated?: true;
+}>;
+type ThoughtRow = Readonly<{
+    kind: "thought";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    text: string;
+    truncated?: true;
+}>;
+type NoteRow = Readonly<{
+    kind: "note";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    text: string;
+    truncated?: true;
+}>;
+type TurnNarrationRow = CallRow | SaidRow | ThoughtRow | NoteRow;
+export type TellRow = Readonly<{
+    kind: "tell";
+    sequence: number;
+    at: string;
+    tellId: string;
+    text: string;
+    state: TellFact["state"];
+    deliveries: readonly TellDelivery[];
+}>;
+export type OutcomeRow = Readonly<{
+    kind: "outcome";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    outcome: TurnOutcome;
+}>;
+export type ActiveToolRow = Readonly<{
+    kind: "tool";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    name: string;
+    call: ToolCall;
+    state: "active";
+    truncated?: true;
+}>;
+export type CompletedToolRow = Readonly<{
+    kind: "tool";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    completedAt?: string;
+    durationMs?: number;
+    name: string;
+    call: ToolCall;
+    state: ToolResult;
+    truncated?: true;
+}>;
+export type UnsettledToolRow = Readonly<{
+    kind: "tool";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    name: string;
+    call: ToolCall;
+    state: "unsettled";
+    truncated?: true;
+}>;
+export type OpenTurnRow = TurnNarrationRow | ActiveToolRow | CompletedToolRow;
+export type ClosedTurnRow = TurnNarrationRow | UnsettledToolRow | CompletedToolRow;
+export type OpenTurn = Readonly<{
+    kind: "open";
+    turn: TurnStartRow;
+    rows: readonly OpenTurnRow[];
+}>;
+export type ClosedTurn = Readonly<{
+    kind: "closed";
+    turn: TurnStartRow;
+    rows: readonly ClosedTurnRow[];
+    outcome: OutcomeRow;
+}>;
+export type ProjectedTurn = OpenTurn | ClosedTurn;
+export type ActivityRow = TurnStartRow | OpenTurnRow | ClosedTurnRow | TellRow | OutcomeRow;
+type SnapshotFactRow = TurnNarrationRow | TellRow;
+export type OpenSnapshotRow = SnapshotFactRow | ActiveToolRow | CompletedToolRow;
+export type IdleSnapshotRow = SnapshotFactRow | CompletedToolRow;
+export type SnapshotRow = OpenSnapshotRow | IdleSnapshotRow;
+export type ActivitySnapshotEntry<Row extends SnapshotRow = SnapshotRow> = Readonly<{
+    kind: "row";
+    row: Row;
+}> | Readonly<{
+    kind: "gap";
+    count: number;
+}>;
+export type Snapshot = Readonly<{
+    kind: "unborn";
+    entries: readonly [];
+    omitted: 0;
+}> | Readonly<{
+    kind: "open";
+    turn: TurnStartRow;
+    entries: readonly ActivitySnapshotEntry<OpenSnapshotRow>[];
+    omitted: number;
+}> | Readonly<{
+    kind: "idle";
+    outcome?: OutcomeRow;
+    entries: readonly ActivitySnapshotEntry<IdleSnapshotRow>[];
+    omitted: number;
+}>;
+export type ActivitySnapshot = Snapshot;
+export type ActivityHistory = Readonly<{
+    rows: readonly ActivityRow[];
+    omitted: number;
+    hasEarlier: boolean;
+    hasLater: boolean;
+    historyLost: boolean;
+    lowestRetained: number | null;
+    highest: number | null;
+}>;
+export type HistoryPage = ActivityHistory;
+export type HistoryCursor = Readonly<{
+    before?: number;
+    since?: number;
+    limit: number;
+}>;
+export type RetainedWindow = Readonly<{
+    lowestRetained: number | null;
+    highest: number | null;
+}>;
+export type TurnLedger = Readonly<{
+    rows: readonly ActivityRow[];
+    turns: readonly ProjectedTurn[];
+    retained: RetainedWindow;
+    openTurn?: OpenTurn;
+    latestOutcome?: OutcomeRow;
+}>;
+/** Fold the retained fact timeline into Turn-owned rows without inventing provider facts. */
+export declare function projectTurns(facts: readonly TimelineFact[], retained?: RetainedWindow): TurnLedger;
+/** Split one nonnegative ordinary allowance into newest tail first, then pre-tail voice. */
+export declare function ordinarySnapshotBudget(ordinaryBudget: number): Readonly<{
+    tail: number;
+    voice: number;
+}>;
+/** Count selected ordinary rows; active tools and pending tells stay outside this total. */
+export declare function ordinarySelectedCount(snapshot: ActivitySnapshot): number;
+/** Select one current Turn, one latest outcome, or no focus; pending tells stay actionable. */
+export declare function selectSnapshot(ledger: TurnLedger, budget?: Readonly<{
+    tail: number;
+    voice?: number;
+}>): ActivitySnapshot;
+/** Apply the one snapshot policy used by every public observation consumer. */
+export declare function selectActivitySnapshot(facts: readonly TimelineFact[]): ActivitySnapshot;
+export declare function selectHistory(ledger: TurnLedger, cursor: HistoryCursor): HistoryPage;
+export {};

package/build/src/akuma/projection.js

@@ -0,0 +1,256 @@
+import { decodeAgentEvent } from "./provider.js";
+const DEFAULT_TAIL = 3;
+const DEFAULT_VOICE = 3;
+function duration(startedAt, completedAt) {
+    const start = Date.parse(startedAt);
+    const end = Date.parse(completedAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end < start)
+        return undefined;
+    return end - start;
+}
+function toolKey(turnSequence, id) {
+    return `${turnSequence}:${id}`;
+}
+function narrationRow(fact, event) {
+    if (event.type === "assistant") {
+        return { kind: "said", sequence: fact.sequence, turnSequence: fact.turnSequence, at: fact.at, text: event.text,
+            ...(event.truncated === true ? { truncated: true } : {}) };
+    }
+    if (event.type === "thought" || event.type === "note") {
+        return { kind: event.type, sequence: fact.sequence, turnSequence: fact.turnSequence, at: fact.at, text: event.text,
+            ...(event.truncated === true ? { truncated: true } : {}) };
+    }
+    return null;
+}
+function projectToolEvent(rows, running, fact, event, phase) {
+    const key = toolKey(fact.turnSequence, event.id);
+    if (event.phase === "started") {
+        running.set(key, rows.length);
+        rows.push({
+            kind: "tool",
+            sequence: fact.sequence,
+            turnSequence: fact.turnSequence,
+            at: fact.at,
+            name: event.name,
+            call: event.call,
+            state: phase === "open" ? "active" : "unsettled",
+            ...(event.truncated === true ? { truncated: true } : {}),
+        });
+        return;
+    }
+    const index = running.get(key);
+    const started = index === undefined ? undefined : rows[index];
+    if (started?.kind !== "tool") {
+        rows.push({ kind: "tool", sequence: fact.sequence, turnSequence: fact.turnSequence, at: fact.at, name: event.name, call: event.call, state: event.result, ...(event.truncated === true ? { truncated: true } : {}) });
+        return;
+    }
+    const durationMs = duration(started.at, fact.at);
+    rows[index] = {
+        kind: "tool",
+        sequence: started.sequence,
+        turnSequence: fact.turnSequence,
+        at: started.at,
+        completedAt: fact.at,
+        ...(durationMs === undefined ? {} : { durationMs }),
+        name: event.name,
+        call: event.call,
+        state: event.result,
+        ...(started.truncated === true || event.truncated === true ? { truncated: true } : {}),
+    };
+    running.delete(key);
+}
+function projectActivityEvent(state, fact) {
+    const event = decodeAgentEvent(fact.event);
+    const narration = narrationRow(fact, event);
+    if (narration !== null) {
+        const turn = state.turnsBySequence.get(fact.turnSequence);
+        if (turn === undefined)
+            state.orphanRows.push(narration);
+        else
+            turn.rows.push(narration);
+        return;
+    }
+    if (event.type !== "tool")
+        return;
+    const turn = state.turnsBySequence.get(fact.turnSequence);
+    if (turn === undefined)
+        projectToolEvent(state.orphanRows, state.orphanRunning, fact, event, "closed");
+    else
+        projectToolEvent(turn.rows, turn.running, fact, event, turn.phase);
+}
+function demoteActive(row) {
+    if (row.kind !== "tool" || row.state !== "active")
+        return row;
+    return { ...row, state: "unsettled" };
+}
+function foldOutcomeVoice(rows, outcome) {
+    if (outcome?.outcome.kind !== "answered")
+        return rows;
+    const finalVoice = rows.findLast((row) => row.kind === "said");
+    return finalVoice?.text === outcome.outcome.answer && finalVoice.truncated !== true
+        ? rows.filter((row) => row !== finalVoice)
+        : rows;
+}
+function finishTurn(turn) {
+    const rows = foldOutcomeVoice(turn.rows, turn.outcome);
+    if (turn.phase === "closed" && turn.outcome !== undefined) {
+        return { kind: "closed", turn: turn.turn, rows: rows.map(demoteActive), outcome: turn.outcome };
+    }
+    if (rows.some((row) => row.kind === "tool" && row.state === "unsettled")) {
+        throw new Error(`open Turn ${turn.turn.turnSequence} contains an unsettled tool`);
+    }
+    return { kind: "open", turn: turn.turn, rows: rows };
+}
+/** Fold the retained fact timeline into Turn-owned rows without inventing provider facts. */
+export function projectTurns(facts, retained = {
+    lowestRetained: facts[0]?.sequence ?? null,
+    highest: facts.at(-1)?.sequence ?? null,
+}) {
+    const state = {
+        turns: [],
+        turnsBySequence: new Map(),
+        tells: [],
+        orphanRows: [],
+        orphanOutcomes: [],
+        orphanRunning: new Map(),
+    };
+    for (const fact of facts) {
+        if (fact.kind === "turn-start") {
+            const turn = { kind: "turn", sequence: fact.sequence, turnSequence: fact.sequence, bodySequence: fact.bodySequence, at: fact.startedAt };
+            const projected = { phase: "open", turn, rows: [], running: new Map() };
+            state.turns.push(projected);
+            state.turnsBySequence.set(turn.turnSequence, projected);
+        }
+        else if (fact.kind === "turn-end") {
+            const outcome = { kind: "outcome", sequence: fact.sequence, turnSequence: fact.turnSequence, at: fact.completedAt, outcome: fact.outcome };
+            const turn = state.turnsBySequence.get(fact.turnSequence);
+            if (turn === undefined)
+                state.orphanOutcomes.push(outcome);
+            else {
+                turn.phase = "closed";
+                turn.rows = turn.rows.map(demoteActive);
+                turn.outcome = outcome;
+            }
+        }
+        else if (fact.kind === "call") {
+            const row = { kind: "call", sequence: fact.sequence, turnSequence: fact.turnSequence, at: fact.at, text: fact.body };
+            const turn = state.turnsBySequence.get(fact.turnSequence);
+            if (turn === undefined)
+                state.orphanRows.push(row);
+            else
+                turn.rows.push(row);
+        }
+        else if (fact.kind === "tell") {
+            state.tells.push({ kind: "tell", sequence: fact.sequence, at: fact.recordedAt, tellId: fact.id, text: fact.body, state: fact.state, deliveries: fact.deliveries });
+        }
+        else {
+            projectActivityEvent(state, fact);
+        }
+    }
+    const turns = state.turns.map(finishTurn);
+    const rows = [
+        ...turns.flatMap((turn) => [turn.turn, ...turn.rows, ...(turn.kind === "closed" ? [turn.outcome] : [])]),
+        ...state.tells,
+        ...state.orphanRows,
+        ...state.orphanOutcomes,
+    ].sort((left, right) => left.sequence - right.sequence);
+    const frontier = turns.at(-1);
+    const openTurn = frontier?.kind === "open" ? frontier : undefined;
+    const latestOutcome = rows.findLast((row) => row.kind === "outcome");
+    return { rows, turns, retained, ...(openTurn === undefined ? {} : { openTurn }), ...(latestOutcome === undefined ? {} : { latestOutcome }) };
+}
+function entries(rows) {
+    return rows.map((row) => ({ kind: "row", row }));
+}
+function openEntries(ledger, window, selected) {
+    const windowRows = new Set(window);
+    const result = [];
+    let hidden = 0;
+    const flushGap = () => {
+        if (hidden === 0)
+            return;
+        result.push({ kind: "gap", count: hidden });
+        hidden = 0;
+    };
+    for (const row of ledger.rows) {
+        if (windowRows.has(row) && !selected.has(row)) {
+            hidden += 1;
+            continue;
+        }
+        if (!selected.has(row))
+            continue;
+        flushGap();
+        if (row.kind !== "turn" && row.kind !== "outcome" && !(row.kind === "tool" && row.state === "unsettled")) {
+            result.push({ kind: "row", row });
+        }
+    }
+    flushGap();
+    return result;
+}
+/** Split one nonnegative ordinary allowance into newest tail first, then pre-tail voice. */
+export function ordinarySnapshotBudget(ordinaryBudget) {
+    const tail = Math.min(DEFAULT_TAIL, Math.max(0, ordinaryBudget));
+    return { tail, voice: Math.min(DEFAULT_VOICE, Math.max(0, ordinaryBudget) - tail) };
+}
+/** Count selected ordinary rows; active tools and pending tells stay outside this total. */
+export function ordinarySelectedCount(snapshot) {
+    return snapshot.entries.reduce((count, entry) => {
+        if (entry.kind !== "row")
+            return count;
+        if (entry.row.kind === "tool" && entry.row.state === "active")
+            return count;
+        if (entry.row.kind === "tell" && entry.row.state === "pending")
+            return count;
+        return count + 1;
+    }, 0);
+}
+/** Select one current Turn, one latest outcome, or no focus; pending tells stay actionable. */
+export function selectSnapshot(ledger, budget = { tail: DEFAULT_TAIL, voice: DEFAULT_VOICE }) {
+    if (ledger.turns.length === 0 && !ledger.rows.some((row) => row.kind === "tell"))
+        return { kind: "unborn", entries: [], omitted: 0 };
+    const pending = ledger.rows.filter((row) => row.kind === "tell" && row.state === "pending");
+    if (ledger.openTurn !== undefined) {
+        const window = ledger.openTurn.rows;
+        const active = window.filter((row) => row.kind === "tool" && row.state === "active");
+        const ordinary = window.filter((row) => !(row.kind === "tool" && row.state === "active"));
+        const tailCount = Math.max(0, budget.tail);
+        const tail = tailCount === 0 ? [] : ordinary.slice(-tailCount);
+        const tailSet = new Set(tail);
+        const voiceCount = Math.max(0, budget.voice ?? DEFAULT_VOICE);
+        const voiceCandidates = ordinary
+            .filter((row) => !tailSet.has(row) && (row.kind === "said" || row.kind === "thought"));
+        const voice = voiceCount === 0 ? [] : voiceCandidates.slice(-voiceCount);
+        const selected = new Set([...tail, ...voice, ...active, ...pending]);
+        const omitted = window.filter((row) => !selected.has(row)).length;
+        return { kind: "open", turn: ledger.openTurn.turn, entries: openEntries(ledger, window, selected), omitted };
+    }
+    return {
+        kind: "idle",
+        ...(ledger.latestOutcome === undefined ? {} : { outcome: ledger.latestOutcome }),
+        entries: entries(pending),
+        omitted: 0,
+    };
+}
+/** Apply the one snapshot policy used by every public observation consumer. */
+export function selectActivitySnapshot(facts) {
+    return selectSnapshot(projectTurns(facts));
+}
+export function selectHistory(ledger, cursor) {
+    const eligible = ledger.rows.filter((row) => cursor.before !== undefined
+        ? row.sequence < cursor.before
+        : cursor.since !== undefined ? row.sequence > cursor.since : true);
+    const rows = cursor.since !== undefined ? eligible.slice(0, cursor.limit) : eligible.slice(-cursor.limit);
+    const omitted = Math.max(0, eligible.length - rows.length);
+    const historyLost = cursor.since !== undefined
+        ? (ledger.rows[0] !== undefined && ledger.rows[0].sequence > cursor.since + 1)
+        : (ledger.retained.lowestRetained !== null && ledger.retained.lowestRetained > 1 && omitted === 0);
+    return {
+        rows,
+        omitted,
+        hasEarlier: cursor.since === undefined && eligible.length > rows.length,
+        hasLater: cursor.since !== undefined && eligible.length > rows.length,
+        historyLost,
+        lowestRetained: ledger.retained.lowestRetained,
+        highest: ledger.retained.highest,
+    };
+}

package/build/src/akuma/provider-recipe.d.ts

@@ -0,0 +1,24 @@
+export type ProviderOptions = Readonly<{
+    model?: string;
+    effort?: string;
+    readonly?: true;
+    network?: "disabled" | "enabled";
+    systemPrompt?: string;
+}>;
+export type ReadonlyRestraint = Readonly<{
+    enforcement: "native";
+    diagnostic?: never;
+} | {
+    enforcement: "none";
+    diagnostic: string;
+}>;
+export type ProviderExecution = Readonly<{
+    name: string;
+    kind: "acp" | "claude-agent-sdk" | "codex-app-server" | "grok-build" | "opencode-sdk" | "pi";
+    executable?: string;
+    config?: Readonly<Record<string, unknown>>;
+    env?: Readonly<Record<string, string>>;
+}>;
+export declare function decodeProviderOptions(value: unknown): ProviderOptions;
+export declare function decodeReadonlyRestraint(value: unknown): ReadonlyRestraint;
+export declare function decodeProviderRecipe(input: unknown): ProviderExecution;