@llblab/pi-kit 0.13.0 → 0.14.1

package/node_modules/@llblab/pi-state-flow/dist/lib/telegram.js

@@ -0,0 +1,234 @@
+// Domain: optional pi-telegram presentation adapter for the State Flow main-menu section.
+//
+// This is a leaf adapter. Core semantics, storage, and inference never depend on it; when
+// pi-telegram is absent or its registry is not ready, registration fails open and retries.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+export const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
+/** Resolve the package export or the compiled sibling-extension layout used in local development. */
+export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url) {
+    return [
+        "@llblab/pi-telegram/sections",
+        new URL("../../../pi-telegram/dist/api/sections.js", moduleUrl).href,
+    ];
+}
+/** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
+export function formatStateFlowSectionLabel(snapshot) {
+    return `🌀 State Flow: ${stateFlowLabelValue(snapshot)}`;
+}
+/** Shared live value: plain in the button label, monospaced in the submenu state line. */
+function stateFlowLabelValue(snapshot) {
+    return snapshot.enabled ? `#${snapshot.step}` : "off";
+}
+/** Submenu state line: the same identity as the button label, with the live value in monospace. */
+function formatStateFlowSectionHeader(snapshot) {
+    return `<b>🌀 State Flow: <code>${stateFlowLabelValue(snapshot)}</code></b>`;
+}
+/** Short help under the state line: what State Flow is and why its action button exists. */
+const STATE_FLOW_SECTION_HELP = "Records the latest accepted state after every turn, so a new session resumes from the last committed point.";
+/** The submenu header repeats the button's state line; the single action matches the current state. */
+export function buildStateFlowSectionView(snapshot, callbackData) {
+    const action = snapshot.enabled
+        ? { text: "⏹ Stop", callback_data: callbackData("stop") }
+        : { text: "▶️ Start", callback_data: callbackData("start") };
+    return {
+        text: [formatStateFlowSectionHeader(snapshot), "", STATE_FLOW_SECTION_HELP].join("\n"),
+        parseMode: "html",
+        replyMarkup: { inline_keyboard: [
+                [action],
+                [{ text: "👁 Show state", callback_data: callbackData("show-state") }],
+            ] },
+    };
+}
+const STATE_FLOW_SCOPE_LABELS = {
+    global: "🌐 Global",
+    cwd: "📂 CWD",
+    session: "💬 Session",
+    effective: "🧬 Effective",
+};
+export function buildStateFlowScopeChooser(callbackData) {
+    return {
+        text: "<b>👁 Show state:</b>",
+        parseMode: "html",
+        replyMarkup: { inline_keyboard: [
+                ...["global", "cwd", "session", "effective"].map((scope) => [
+                    { text: STATE_FLOW_SCOPE_LABELS[scope], callback_data: callbackData("inspect", scope) },
+                ]),
+            ] },
+    };
+}
+// The complete message serializes each preformatted field one additional time;
+// 3,000 leaves safe headroom for worst-case JSON escaping across all four fields.
+const STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS = 3_000;
+function renderStateFlowTelegramField(value) {
+    const json = JSON.stringify(value, null, 2);
+    if (json.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS)
+        return json;
+    let low = 0;
+    let high = json.length;
+    let rendered = "";
+    while (low <= high) {
+        const length = Math.floor((low + high) / 2);
+        const candidate = JSON.stringify({
+            truncated: true,
+            preview: json.slice(0, length),
+            omittedChars: json.length - length,
+        }, null, 2);
+        if (candidate.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
+            rendered = candidate;
+            low = length + 1;
+        }
+        else {
+            high = length - 1;
+        }
+    }
+    return rendered;
+}
+export function renderStateFlowRichState(scope, step, state) {
+    const fields = ["artifacts", "contract", "working", "response"];
+    return {
+        blocks: [
+            { type: "heading", text: `${STATE_FLOW_SCOPE_LABELS[scope]}: \`#${step}\``, size: 3 },
+            ...fields.map((field) => ({
+                type: "details",
+                summary: { type: "code", text: field },
+                blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
+            })),
+        ],
+        skip_entity_detection: true,
+    };
+}
+function isStateFlowTelegramScope(value) {
+    return value === "global" || value === "cwd" || value === "session" || value === "effective";
+}
+function buildStateFlowTelegramSection(port) {
+    return {
+        id: STATE_FLOW_TELEGRAM_ID,
+        label: "🌀 State Flow",
+        getLabel: () => formatStateFlowSectionLabel(port.snapshot()),
+        render: (ctx) => buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)),
+        handleCallback: async (ctx) => {
+            // cancel/refresh remain routable for keyboards sent by earlier versions.
+            if (ctx.action !== "start" && ctx.action !== "stop" && ctx.action !== "cancel" && ctx.action !== "refresh" && ctx.action !== "show-state" && ctx.action !== "inspect" && ctx.action !== "back")
+                return "pass";
+            let notice;
+            try {
+                if (ctx.action === "show-state") {
+                    await ctx.answerCallback();
+                    await ctx.edit(buildStateFlowScopeChooser((action, payload) => ctx.callbackData(action, payload)));
+                    return "handled";
+                }
+                if (ctx.action === "inspect") {
+                    if (!isStateFlowTelegramScope(ctx.payload))
+                        throw new Error("Unknown State Flow scope");
+                    await ctx.openRich(renderStateFlowRichState(ctx.payload, port.snapshot().step, port.state(ctx.payload)));
+                    await ctx.answerCallback();
+                    return "handled";
+                }
+                if (ctx.action === "start") {
+                    if (port.canStartNow())
+                        notice = port.start().message;
+                    else {
+                        port.deferStart();
+                        notice = "State Flow will start after the current turn";
+                    }
+                }
+                else if (ctx.action === "stop") {
+                    notice = port.stop().message;
+                }
+                else if (ctx.action === "cancel") {
+                    port.cancelStart();
+                    notice = "Pending start cancelled";
+                }
+            }
+            catch (error) {
+                notice = error instanceof Error ? error.message : String(error);
+            }
+            await ctx.answerCallback(notice);
+            await ctx.edit(buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)));
+            return "handled";
+        },
+    };
+}
+async function importTelegramModule(specifiers, guard) {
+    for (const specifier of specifiers) {
+        try {
+            const imported = await import(__rewriteRelativeImportExtension(specifier));
+            if (guard(imported))
+                return imported;
+        }
+        catch {
+            // pi-telegram is optional; its absence only disables the Telegram surface.
+        }
+    }
+    return undefined;
+}
+/** Default loader; injectable so tests and embedded hosts can control transport presence. */
+export async function loadStateFlowTelegramModules() {
+    const sections = await importTelegramModule(stateFlowTelegramSectionSpecifiers(), (module) => typeof module?.registerTelegramSection === "function");
+    return { ...(sections === undefined ? {} : { sections }) };
+}
+export function createStateFlowTelegramAdapter(options) {
+    const load = options.load ?? loadStateFlowTelegramModules;
+    let generation = 0;
+    let sectionRegistered = false;
+    let registration;
+    const disposers = [];
+    const register = async () => {
+        const epoch = generation;
+        let modules;
+        try {
+            modules = await load();
+        }
+        catch {
+            return false;
+        }
+        // A shutdown during loading must not leave a registration behind.
+        if (epoch !== generation)
+            return false;
+        if (!sectionRegistered && modules.sections) {
+            try {
+                const dispose = modules.sections.registerTelegramSection(buildStateFlowTelegramSection(options.port));
+                if (epoch === generation) {
+                    disposers.push(dispose);
+                    sectionRegistered = true;
+                }
+                else {
+                    dispose();
+                }
+            }
+            catch {
+                // Registry not initialized yet; the next ensure retries.
+            }
+        }
+        return sectionRegistered;
+    };
+    return {
+        async ensure() {
+            if (sectionRegistered)
+                return true;
+            registration ??= register().finally(() => {
+                registration = undefined;
+            });
+            return registration;
+        },
+        dispose() {
+            generation += 1;
+            for (const dispose of disposers.splice(0)) {
+                try {
+                    dispose();
+                }
+                catch {
+                    // Disposal is best-effort; pi-telegram owns its registry lifetime.
+                }
+            }
+            sectionRegistered = false;
+        },
+    };
+}

package/node_modules/@llblab/pi-state-flow/dist/lib/temporal.d.ts

@@ -0,0 +1,39 @@
+import { type RecentScopePatch } from "./history.ts";
+import { type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
+/** Owns hot temporal algebra; excludes filesystem, Git, identity allocation, and Pi lifecycle. */
+export interface TransitionBoundary {
+    id: string;
+    /** Branch-local order only. Identity and parent links distinguish forks at equal positions. */
+    position: number;
+    parent: string | null;
+}
+export interface ScopeCheckpoint {
+    through: TransitionBoundary;
+    state: MaterializedState;
+}
+export interface TemporalPatch {
+    transition: TransitionBoundary;
+    patch: RecentScopePatch["patch"];
+}
+export interface ScopeStream {
+    checkpoint: ScopeCheckpoint;
+    patches: TemporalPatch[];
+}
+export interface TemporalState {
+    /** Oldest to newest, including the boundary immediately before the retained transitions. */
+    lineage: TransitionBoundary[];
+    scopes: Record<StateScope, ScopeStream>;
+}
+/** Replay validation is shared by disk codecs and active-lineage materialization. */
+export declare function validateScopeStream(value: unknown, scope: StateScope): asserts value is ScopeStream;
+export declare function validateTemporalLineage(value: unknown): asserts value is TransitionBoundary[];
+/** Validate one revision-selected cohort. Its older ancestry must be bound by the durable loader. */
+export declare function validateTemporalState(view: TemporalState): void;
+/** Adopt revision-proven inherited streams without rewriting their checkpoints or tails. */
+export declare function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id: string): TemporalState;
+/** New or migrated state starts at a proven current boundary, with no invented past. */
+export declare function createTemporalState(states: ScopedStates, id: string): TemporalState;
+/** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
+export declare function readTemporalState(view: TemporalState, offset?: number, scope?: StateScope): MaterializedState;
+/** Allocate the identity outside this algebra; only materially effective patches accept it. */
+export declare function advanceTemporalState(view: TemporalState, transitions: readonly RecentScopePatch[], id: string): TemporalState;

package/node_modules/@llblab/pi-state-flow/dist/lib/temporal.js

@@ -0,0 +1,203 @@
+import { RECENT_TRANSITION_LIMIT, validateRecentTransition } from "./history.js";
+import { applyPatch, containsNull, isJsonValue, isObject, sameJson } from "./json.js";
+import { isMaterializedState, overlayStates } from "./state.js";
+const SCOPES = ["global", "cwd", "session"];
+function validateBoundary(boundary) {
+    if (!isObject(boundary) || Object.keys(boundary).sort().join(",") !== "id,parent,position"
+        || typeof boundary.id !== "string" || boundary.id.trim().length === 0
+        || !Number.isSafeInteger(boundary.position) || boundary.position < 0
+        || (boundary.parent !== null && (typeof boundary.parent !== "string" || boundary.parent.trim().length === 0))
+        || boundary.parent === boundary.id || (boundary.position === 0 && boundary.parent !== null)) {
+        throw new Error("Invalid State Flow temporal boundary");
+    }
+}
+function validateState(state) {
+    if (!isJsonValue(state) || !isMaterializedState(state) || containsNull(state)) {
+        throw new Error("Invalid temporal materialized semantic state");
+    }
+}
+function apply(state, patch) {
+    const next = applyPatch(state, patch);
+    validateState(next);
+    return next;
+}
+function sameBoundary(left, right) {
+    return left.id === right.id && left.position === right.position && left.parent === right.parent;
+}
+/** Replay validation is shared by disk codecs and active-lineage materialization. */
+export function validateScopeStream(value, scope) {
+    if (!SCOPES.includes(scope))
+        throw new Error("Unknown temporal scope");
+    if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "checkpoint,patches"
+        || !isObject(value.checkpoint) || Object.keys(value.checkpoint).sort().join(",") !== "state,through"
+        || !Array.isArray(value.patches)) {
+        throw new Error("Invalid temporal checkpoint/tail envelope");
+    }
+    const stream = value;
+    validateBoundary(stream.checkpoint.through);
+    validateState(stream.checkpoint.state);
+    if (stream.patches.length > RECENT_TRANSITION_LIMIT)
+        throw new Error("Temporal scope tail exceeds seven patches");
+    let previous = stream.checkpoint.through;
+    let state = stream.checkpoint.state;
+    const identities = new Set([previous.id]);
+    for (const record of stream.patches) {
+        if (!isObject(record) || Object.keys(record).sort().join(",") !== "patch,transition") {
+            throw new Error("Invalid temporal patch envelope");
+        }
+        validateBoundary(record.transition);
+        if (record.transition.position <= previous.position || identities.has(record.transition.id)) {
+            throw new Error("Temporal scope tail is not ordered after its checkpoint");
+        }
+        if (record.transition.position === previous.position + 1 && record.transition.parent !== previous.id) {
+            throw new Error("Disconnected State Flow temporal ancestry");
+        }
+        validateRecentTransition({ id: record.transition.id, at: 0, transitions: [{ scope, patch: record.patch }] });
+        const next = apply(state, record.patch);
+        if (sameJson(next, state))
+            throw new Error("Temporal scope tail contains a semantic no-op");
+        state = next;
+        previous = record.transition;
+        identities.add(previous.id);
+    }
+}
+export function validateTemporalLineage(value) {
+    if (!isJsonValue(value) || !Array.isArray(value) || value.length === 0 || value.length > RECENT_TRANSITION_LIMIT + 1) {
+        throw new Error("Temporal lineage must contain between one and eight boundaries");
+    }
+    const seen = new Set();
+    for (let index = 0; index < value.length; index++) {
+        const boundary = value[index];
+        validateBoundary(boundary);
+        if (seen.has(boundary.id))
+            throw new Error("Duplicate State Flow temporal boundary");
+        seen.add(boundary.id);
+        const previous = value[index - 1];
+        if (previous && (boundary.position !== previous.position + 1 || boundary.parent !== previous.id)) {
+            throw new Error("Disconnected State Flow temporal lineage");
+        }
+    }
+}
+/** Validate one revision-selected cohort. Its older ancestry must be bound by the durable loader. */
+export function validateTemporalState(view) {
+    validateTemporalLineage(view.lineage);
+    const oldest = view.lineage[0];
+    const identities = new Map();
+    const positions = new Map();
+    const remember = (boundary) => {
+        validateBoundary(boundary);
+        const identity = identities.get(boundary.id);
+        const position = boundary.position >= oldest.position ? positions.get(boundary.position) : undefined;
+        if ((identity && !sameBoundary(identity, boundary)) || (position && !sameBoundary(position, boundary))) {
+            throw new Error("Conflicting State Flow temporal lineage");
+        }
+        identities.set(boundary.id, boundary);
+        if (boundary.position >= oldest.position)
+            positions.set(boundary.position, boundary);
+    };
+    for (const boundary of view.lineage)
+        remember(boundary);
+    const head = view.lineage.at(-1);
+    for (const scope of SCOPES) {
+        const stream = view.scopes[scope];
+        validateScopeStream(stream, scope);
+        remember(stream.checkpoint.through);
+        if (stream.checkpoint.through.position > oldest.position) {
+            throw new Error("Scope checkpoint is newer than the guaranteed hot boundary");
+        }
+        for (const record of stream.patches) {
+            remember(record.transition);
+            if (record.transition.position > head.position)
+                throw new Error("Temporal scope patch is beyond the active head");
+        }
+    }
+    for (const boundary of identities.values()) {
+        const previous = positions.get(boundary.position - 1);
+        if (previous && boundary.parent !== previous.id)
+            throw new Error("Disconnected State Flow temporal ancestry");
+    }
+    for (const boundary of view.lineage.slice(1)) {
+        if (!SCOPES.some((scope) => view.scopes[scope].patches.some((record) => record.transition.id === boundary.id))) {
+            throw new Error("Temporal boundary has no semantic patch");
+        }
+    }
+}
+/** Adopt revision-proven inherited streams without rewriting their checkpoints or tails. */
+export function adoptTemporalStreams(scopes, id) {
+    const boundaries = Object.values(scopes).flatMap((stream) => [stream.checkpoint.through, ...stream.patches.map((record) => record.transition)]);
+    const origin = { id, position: Math.max(...boundaries.map((boundary) => boundary.position)) + 1, parent: null };
+    const view = { lineage: [origin], scopes: structuredClone(scopes) };
+    validateTemporalState(view);
+    return view;
+}
+/** New or migrated state starts at a proven current boundary, with no invented past. */
+export function createTemporalState(states, id) {
+    const through = { id, position: 0, parent: null };
+    const stream = (scope) => ({
+        checkpoint: { through: structuredClone(through), state: structuredClone(states[scope]) },
+        patches: [],
+    });
+    const view = { lineage: [through], scopes: { global: stream("global"), cwd: stream("cwd"), session: stream("session") } };
+    validateTemporalState(view);
+    return view;
+}
+function scopeAt(stream, boundary) {
+    let state = structuredClone(stream.checkpoint.state);
+    for (const record of stream.patches) {
+        if (record.transition.position > boundary.position)
+            break;
+        state = apply(state, record.patch);
+    }
+    return state;
+}
+/** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
+export function readTemporalState(view, offset = 0, scope) {
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > RECENT_TRANSITION_LIMIT) {
+        throw new Error("State Flow hot-history offset must be an integer from 0 to 7");
+    }
+    if (scope !== undefined && !SCOPES.includes(scope))
+        throw new Error("Unknown temporal scope");
+    validateTemporalState(view);
+    const boundary = view.lineage[view.lineage.length - 1 - offset];
+    if (!boundary)
+        throw new Error("Requested history predates the proven temporal origin");
+    if (scope !== undefined)
+        return scopeAt(view.scopes[scope], boundary);
+    return overlayStates(...SCOPES.map((owner) => scopeAt(view.scopes[owner], boundary)));
+}
+/** Allocate the identity outside this algebra; only materially effective patches accept it. */
+export function advanceTemporalState(view, transitions, id) {
+    validateTemporalState(view);
+    if (transitions.length === 0)
+        return view;
+    validateRecentTransition({ id, at: 0, transitions });
+    const head = view.lineage.at(-1);
+    const changes = transitions.filter(({ scope, patch }) => {
+        const current = scopeAt(view.scopes[scope], head);
+        return !sameJson(current, apply(current, patch));
+    });
+    if (changes.length === 0)
+        return view;
+    const knownIds = new Set(view.lineage.map((boundary) => boundary.id));
+    for (const scope of SCOPES) {
+        knownIds.add(view.scopes[scope].checkpoint.through.id);
+        for (const record of view.scopes[scope].patches)
+            knownIds.add(record.transition.id);
+    }
+    if (knownIds.has(id))
+        throw new Error("State Flow transition identity has already been used");
+    const boundary = { id, position: head.position + 1, parent: head.id };
+    validateBoundary(boundary);
+    const next = structuredClone(view);
+    for (const { scope, patch } of changes) {
+        const stream = next.scopes[scope];
+        if (stream.patches.length === RECENT_TRANSITION_LIMIT) {
+            const folded = stream.patches.shift();
+            stream.checkpoint = { through: folded.transition, state: apply(stream.checkpoint.state, folded.patch) };
+        }
+        stream.patches.push({ transition: structuredClone(boundary), patch: structuredClone(patch) });
+    }
+    next.lineage = [...next.lineage, boundary].slice(-(RECENT_TRANSITION_LIMIT + 1));
+    validateTemporalState(next);
+    return next;
+}

package/node_modules/@llblab/pi-state-flow/dist/lib/transition.d.ts

@@ -0,0 +1,25 @@
+import { type ArtifactProvenance } from "./artifact.ts";
+import type { SuccessfulArtifactRead } from "./acquisition.ts";
+import { type AcceptedTransition } from "./history.ts";
+import { type SuccessfulSkillRead } from "./skills.ts";
+import type { Snapshot } from "./snapshot.ts";
+import type { AtomicScopePatches, ScopedStates, StateScope, TerminalTransition } from "./state.ts";
+export interface StagedScopedTransition {
+    nextStates: ScopedStates;
+    stateHashes: Record<StateScope, string>;
+    /** Fresh runtime-owned provenance for artifacts compiled in this transition. */
+    provenanceUpdates: Record<StateScope, Record<string, ArtifactProvenance>>;
+    causalBasis: string;
+    committed: boolean;
+}
+/** Validate that final eligibility has no pending acquisition/compilation obligation. */
+export declare function validateFinalEligibility(currentStates: ScopedStates, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): void;
+/** Stage one canonical atomic scope cohort without changing the finalized response. */
+export declare function stageAtomicScopePatches(currentStates: ScopedStates, patches: AtomicScopePatches, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
+export declare function stageScopedTransition(currentStates: ScopedStates, transition: TerminalTransition, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
+/** Commit one accepted transition; durable publication receives all changed scopes as one cohort. */
+export interface CommitScopedTransitionOptions {
+    /** Runtime response reconciliation finalizes bootstrap lifecycle state. */
+    finalizeRun?: boolean;
+}
+export declare function commitScopedTransition(snapshot: Snapshot, states: ScopedStates, stage: StagedScopedTransition, publishDurable: (accepted: AcceptedTransition | undefined, nextSnapshot: Snapshot) => void, causalBasis: string, options?: CommitScopedTransitionOptions): boolean;