@llblab/pi-kit 0.22.2 → 0.23.0

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

@@ -1,8 +1,10 @@
 // Domain: exact file-cohort publication, current-only recovery, and cooperating worktree exclusion.
 // Excludes: temporal algebra, Pi lifecycle, Git objects/remotes, and backend fallback policy.
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import { assertOwnedFileUpdates, captureTemporalFileBases, parseScopeProvenance, parseScopeStream, restoreDurableFileBases, serializeScopeMetadata, sessionRuntimePaths, temporalScopePaths, temporalStateFileUpdates, writeOwnedFileUpdates, } from "./durable.js";
 import { MAX_HISTORY_LIMIT } from "./history.js";
 import { hashJson, sameJson } from "./json.js";
@@ -17,7 +19,7 @@ export function assertStorageDirectory(path) {
         assertStorageDirectory(parent);
     const stat = lstatSync(root, { throwIfNoEntry: false });
     if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
-        throw new Error(`State Flow repository path is not a regular directory: ${root}`);
+        throw new Error(`State Flow repository path is not a regular directory: ${JSON.stringify(root)}`);
 }
 /** Explicit creation only; existing bytes and unrelated files are never adopted or rewritten here. */
 export function initializeFileStore(root) {
@@ -27,27 +29,34 @@ export function initializeFileStore(root) {
 const PUBLICATION_LOCK_WAIT_MS = 2_000;
 const PUBLICATION_LOCK_POLL_MS = 25;
 const publicationLockWait = new Int32Array(new SharedArrayBuffer(4));
-function liveForeignLockOwner(path) {
+function publicationLockOwner(path, allowCurrentProcess) {
     let owner;
     try {
-        owner = readFileSync(path, "utf8").trim();
+        const stat = lstatSync(path, { throwIfNoEntry: false });
+        if (!stat)
+            return "absent";
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return "unavailable";
+        owner = readFileSync(path, { encoding: "utf8", flag: constants.O_RDONLY | constants.O_NOFOLLOW }).trim();
     }
-    catch {
-        return true;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "absent";
+        throw error;
     }
     if (owner.length === 0)
-        return true;
+        return "pending";
     if (!/^[1-9]\d*$/.test(owner))
-        return false;
+        return "unavailable";
     const pid = Number(owner);
-    if (!Number.isSafeInteger(pid) || pid === process.pid)
-        return false;
+    if (!Number.isSafeInteger(pid) || (pid === process.pid && !allowCurrentProcess))
+        return "unavailable";
     try {
         process.kill(pid, 0);
-        return true;
+        return "live";
     }
     catch (error) {
-        return error.code === "EPERM";
+        return error.code === "EPERM" ? "live" : "unavailable";
     }
 }
 /** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
@@ -58,7 +67,16 @@ export function acquirePublicationLock(path, unavailable) {
             return openSync(path, "wx", 0o600);
         }
         catch (error) {
-            if (error.code !== "EEXIST" || !liveForeignLockOwner(path) || Date.now() >= deadline)
+            if (error.code !== "EEXIST")
+                throw unavailable(error);
+            let owner;
+            try {
+                owner = publicationLockOwner(path, false);
+            }
+            catch (cause) {
+                throw unavailable(cause);
+            }
+            if (owner === "unavailable" || Date.now() >= deadline)
                 throw unavailable(error);
             Atomics.wait(publicationLockWait, 0, 0, Math.min(PUBLICATION_LOCK_POLL_MS, deadline - Date.now()));
         }
@@ -69,7 +87,7 @@ export function withStoragePublicationLock(repositoryRoot, action) {
     const root = resolve(repositoryRoot);
     assertStorageDirectory(root);
     const path = resolve(root, ".state-flow-publication.lock");
-    const descriptor = acquirePublicationLock(path, (cause) => new RevisionUnavailableError(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause }));
+    const descriptor = acquirePublicationLock(path, (cause) => new RevisionUnavailableError(`State Flow publication lock is unavailable at ${JSON.stringify(path)}`, { cause }));
     try {
         writeFileSync(descriptor, `${process.pid}\n`);
         return action(root);
@@ -79,6 +97,112 @@ export function withStoragePublicationLock(repositoryRoot, action) {
         rmSync(path);
     }
 }
+export class PublicationBusyError extends Error {
+    constructor(path) { super(`State Flow publication lock is busy at ${JSON.stringify(path)}`); }
+}
+const storageLockContext = new AsyncLocalStorage();
+/** Await an exact file mutex; shared by canonical transactions and the independent Git backup owner. */
+export async function withFilePublicationLock(lockPath, action, signal, unavailable = (cause) => new RevisionUnavailableError(`State Flow publication lock is unavailable at ${JSON.stringify(resolve(lockPath))}`, { cause }), waitForLock = true) {
+    const path = resolve(lockPath);
+    const inherited = storageLockContext.getStore();
+    if (inherited?.some((held) => held.active && held.path === path))
+        throw new Error(`Recursive State Flow publication lock at ${JSON.stringify(path)}`);
+    let descriptor;
+    let pendingSince;
+    while (true) {
+        signal?.throwIfAborted();
+        assertStorageDirectory(dirname(path));
+        try {
+            descriptor = openSync(path, "wx", 0o600);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw unavailable(error);
+            let owner;
+            try {
+                owner = publicationLockOwner(path, true);
+            }
+            catch (cause) {
+                throw unavailable(cause);
+            }
+            if (owner === "unavailable")
+                throw unavailable(error);
+            if (!waitForLock)
+                throw new PublicationBusyError(path);
+            // An empty file may be between exclusive creation and PID publication, but not forever.
+            if (owner === "pending")
+                pendingSince ??= performance.now();
+            else
+                pendingSince = undefined;
+            if (pendingSince !== undefined && performance.now() - pendingSince >= PUBLICATION_LOCK_WAIT_MS)
+                throw unavailable(error);
+        }
+        await delay(PUBLICATION_LOCK_POLL_MS, undefined, { signal });
+    }
+    let identity;
+    const held = { path, active: true };
+    let failed;
+    try {
+        identity = fstatSync(descriptor);
+        writeFileSync(descriptor, `${process.pid}\n`);
+        signal?.throwIfAborted();
+        return await storageLockContext.run([...(inherited?.filter((owner) => owner.active) ?? []), held], action);
+    }
+    catch (error) {
+        failed = { error };
+        throw error;
+    }
+    finally {
+        held.active = false;
+        try {
+            const current = lstatSync(path, { throwIfNoEntry: false });
+            if (!identity || !current?.isFile() || current.dev !== identity.dev || current.ino !== identity.ino
+                || readFileSync(path, { encoding: "utf8", flag: constants.O_RDONLY | constants.O_NOFOLLOW }) !== `${process.pid}\n`) {
+                throw new Error(`State Flow publication lock changed during transaction at ${JSON.stringify(path)}; current owner preserved`);
+            }
+            rmSync(path);
+        }
+        catch (error) {
+            if (failed)
+                throw new AggregateError([failed.error, error], "State Flow storage transaction and lock release failed");
+            throw error;
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    }
+}
+/** Await store-wide exclusion, then capture/apply/publish through callback-scoped operations. */
+export async function withStorageTransaction(repositoryRoot, action, signal, waitForLock = true) {
+    const root = resolve(repositoryRoot);
+    return withFilePublicationLock(resolve(root, ".state-flow-publication.lock"), async () => {
+        let active = true;
+        const guard = (requestedRoot) => {
+            if (!active)
+                throw new Error("State Flow storage transaction has ended");
+            if (resolve(requestedRoot) !== root)
+                throw new Error("State Flow storage transaction belongs to a different store");
+            signal?.throwIfAborted();
+        };
+        const transaction = Object.freeze({
+            capture: (cwd, sessionId, requestedRoot, sessionKey = sessionId) => {
+                guard(requestedRoot);
+                return { files: captureTemporalFileBases(cwd, sessionId, root, sessionKey) };
+            },
+            publish: (cwd, sessionId, view, scopes, base, requestedRoot, runtime, sessionKey, provenance, runtimeOnly) => {
+                guard(requestedRoot);
+                return publishLockedTemporalStateToFiles(cwd, sessionId, view, scopes, base, root, runtime, sessionKey, provenance, runtimeOnly);
+            },
+        });
+        try {
+            return await action(transaction);
+        }
+        finally {
+            active = false;
+        }
+    }, signal, undefined, waitForLock);
+}
 export function assertTemporalFileBase(expected, current) {
     if (expected.files.length !== current.files.length || current.files.some((file, index) => {
         const previous = expected.files[index];
@@ -191,16 +315,18 @@ export function loadTemporalFileRevision(cwd, sessionId, root, revision, session
 }
 /** Publish a validated canonical cohort; runtimeOnly owns only session config/runtime files. */
 export function publishTemporalStateToFiles(cwd, sessionId, view, scopes, base, root, runtime, sessionKey = sessionId, provenance, runtimeOnly = false) {
-    return withStoragePublicationLock(root, (locked) => {
-        const current = { files: captureTemporalFileBases(cwd, sessionId, locked, sessionKey) };
-        assertTemporalFileBase(base, current);
-        const { updates } = planTemporalPublication(cwd, sessionId, view, scopes, current, locked, runtime, runtimeOnly, sessionKey, provenance);
-        const next = { files: temporalFileReceipts(current, updates) };
-        decodeFileCohort(cwd, sessionId, locked, next, sessionKey);
-        const revision = fileRevision(next, locked);
-        publishFileUpdates(current.files, updates, locked);
-        return { base: next, revision, changed: updates.length > 0 };
-    });
+    return withStoragePublicationLock(root, (locked) => publishLockedTemporalStateToFiles(cwd, sessionId, view, scopes, base, locked, runtime, sessionKey, provenance, runtimeOnly));
+}
+/** Shared publication owner; callers must hold the matching store lock for the complete cohort. */
+function publishLockedTemporalStateToFiles(cwd, sessionId, view, scopes, base, root, runtime, sessionKey = sessionId, provenance, runtimeOnly = false) {
+    const current = { files: captureTemporalFileBases(cwd, sessionId, root, sessionKey) };
+    assertTemporalFileBase(base, current);
+    const { updates } = planTemporalPublication(cwd, sessionId, view, scopes, current, root, runtime, runtimeOnly, sessionKey, provenance);
+    const next = { files: temporalFileReceipts(current, updates) };
+    decodeFileCohort(cwd, sessionId, root, next, sessionKey);
+    const revision = fileRevision(next, root);
+    publishFileUpdates(current.files, updates, root);
+    return { base: next, revision, changed: updates.length > 0 };
 }
 function publishFileUpdates(bases, updates, root) {
     writeOwnedFileUpdates(updates, bases, root);

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

@@ -78,6 +78,14 @@ export type StateFlowTelegramLoader = () => Promise<StateFlowTelegramModules>;
 export interface StateFlowTelegramControlResult {
     ok: boolean;
     message: string;
+    /** A completed control can lose its presentation authority after a mode or selection change. */
+    signal?: AbortSignal;
+}
+export interface StateFlowTelegramInspection {
+    state: StateFlowTelegramState;
+    revisions: ScopeRevisions;
+    /** A selection can revoke a completed observation before the adapter presents it. */
+    signal?: AbortSignal;
 }
 export interface StateFlowTelegramPort {
     snapshot(): StateFlowTelegramSnapshot;
@@ -90,6 +98,11 @@ export interface StateFlowTelegramPort {
     deferStart(): void;
     cancelStart(): void;
 }
+export interface StateFlowTelegramInspectionPort extends Omit<StateFlowTelegramPort, "state" | "revisions" | "start" | "stop"> {
+    inspect(scope: StateFlowTelegramScope): StateFlowTelegramInspection | Promise<StateFlowTelegramInspection>;
+    start(): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
+    stop(): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
+}
 export interface StateFlowTelegramAdapter {
     ensure(): Promise<boolean>;
     dispose(): void;
@@ -103,6 +116,6 @@ export declare function renderStateFlowRichState(scope: StateFlowTelegramScope,
 /** Default loader; injectable so tests and embedded hosts can control transport presence. */
 export declare function loadStateFlowTelegramModules(): Promise<StateFlowTelegramModules>;
 export declare function createStateFlowTelegramAdapter(options: {
-    port: StateFlowTelegramPort;
+    port: StateFlowTelegramPort | StateFlowTelegramInspectionPort;
     load?: StateFlowTelegramLoader;
 }): StateFlowTelegramAdapter;

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

@@ -10,6 +10,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { conciseDiagnostic, diagnosticText } from "./protocol.js";
 import { formatScopeRevisionVector } from "./status.js";
 export const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
 /** Resolve the package export or the compiled sibling-extension layout used in local development. */
@@ -124,7 +125,8 @@ export function renderStateFlowRichState(scope, revisions, state) {
 function isStateFlowTelegramScope(value) {
     return value === "global" || value === "cwd" || value === "session" || value === "effective";
 }
-function buildStateFlowTelegramSection(port) {
+function buildStateFlowTelegramSection(port, isActive) {
+    let interaction = 0;
     return {
         id: STATE_FLOW_TELEGRAM_ID,
         label: "🌀 State Flow",
@@ -134,7 +136,9 @@ function buildStateFlowTelegramSection(port) {
             // 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";
+            const request = ++interaction;
             let notice;
+            let acknowledged = false;
             try {
                 if (ctx.action === "show-state") {
                     await ctx.answerCallback();
@@ -144,23 +148,44 @@ function buildStateFlowTelegramSection(port) {
                 if (ctx.action === "inspect") {
                     if (!isStateFlowTelegramScope(ctx.payload))
                         throw new Error("Unknown State Flow scope");
-                    const state = port.state(ctx.payload);
-                    const live = port.snapshot();
-                    const revisions = port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step };
-                    await ctx.openRich(renderStateFlowRichState(ctx.payload, revisions, state));
-                    await ctx.answerCallback();
+                    let observation;
+                    if ("inspect" in port) {
+                        await ctx.answerCallback("Reading State Flow memory");
+                        acknowledged = true;
+                        observation = await port.inspect(ctx.payload);
+                    }
+                    else {
+                        const state = port.state(ctx.payload);
+                        const live = port.snapshot();
+                        observation = { state, revisions: port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step } };
+                    }
+                    observation.signal?.throwIfAborted();
+                    if (request !== interaction || !isActive())
+                        return "handled";
+                    await ctx.openRich(renderStateFlowRichState(ctx.payload, observation.revisions, observation.state));
+                    if (!acknowledged)
+                        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";
+                const action = ctx.action === "stop" || (ctx.action === "start" && port.canStartNow()) ? ctx.action : undefined;
+                if (action) {
+                    if ("inspect" in port) {
+                        acknowledged = true;
+                        // Start the control immediately and acknowledge in parallel; neither promise can reject unobserved.
+                        const [, result] = await Promise.all([
+                            ctx.answerCallback(action === "stop" ? "Stopping State Flow" : "Starting State Flow"),
+                            Promise.resolve().then(() => port[action]()),
+                        ]);
+                        if (result.signal?.aborted)
+                            return "handled";
+                        notice = result.message;
                     }
+                    else
+                        notice = port[action]().message;
                 }
-                else if (ctx.action === "stop") {
-                    notice = port.stop().message;
+                else if (ctx.action === "start") {
+                    port.deferStart();
+                    notice = "State Flow will start after the current turn";
                 }
                 else if (ctx.action === "cancel") {
                     port.cancelStart();
@@ -168,10 +193,19 @@ function buildStateFlowTelegramSection(port) {
                 }
             }
             catch (error) {
-                notice = error instanceof Error ? error.message : String(error);
+                notice = diagnosticText(error);
+            }
+            if (request !== interaction || !isActive())
+                return "handled";
+            const summary = notice === undefined ? undefined : conciseDiagnostic(notice, 200);
+            const view = buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action));
+            if (acknowledged && summary !== undefined) {
+                // Callback queries can expire during storage waits; retain errors in the existing menu instead.
+                view.text += `\n\n${summary.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}`;
             }
-            await ctx.answerCallback(notice);
-            await ctx.edit(buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)));
+            else if (!acknowledged)
+                await ctx.answerCallback(summary);
+            await ctx.edit(view);
             return "handled";
         },
     };
@@ -214,7 +248,7 @@ export function createStateFlowTelegramAdapter(options) {
             return false;
         if (!sectionRegistered && modules.sections) {
             try {
-                const dispose = modules.sections.registerTelegramSection(buildStateFlowTelegramSection(options.port));
+                const dispose = modules.sections.registerTelegramSection(buildStateFlowTelegramSection(options.port, () => epoch === generation));
                 if (epoch === generation) {
                     disposers.push(dispose);
                     sectionRegistered = true;

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

@@ -31,16 +31,16 @@ function validateSkillCompilerOutput(scope, path, output) {
         problems.push("artifact entry is missing");
     else {
         if (typeof output.description !== "string" || output.description.trim().length === 0)
-            problems.push("description must be a non-empty string");
+            problems.push("description must be non-empty");
         if (output.kind !== "skill")
             problems.push('kind must be "skill"');
         if (!isObject(output.compilation) || Object.keys(output.compilation).length === 0)
-            problems.push("compilation must be a non-empty object");
+            problems.push("compilation object must be non-empty");
     }
     if (problems.length === 0)
         return;
     const target = `${scope}.artifacts[${JSON.stringify(path)}]`;
-    throw new Error(`Skill compiler output at ${target} is invalid: ${problems.join("; ")}. Example: {${JSON.stringify(scope)}:{"artifacts":{${JSON.stringify(path)}:{"description":"What this Skill provides","kind":"skill","compilation":{"rules":["Operational rule retained from the Skill"]}}}}}`);
+    throw new Error(`Invalid Skill at ${target}: ${problems.join("; ")}`);
 }
 function validateSkillCompilerTargets(patches, successfulSkillReads) {
     for (const read of successfulSkillReads) {
@@ -64,7 +64,7 @@ function compileReadSkills(scope, nextState, patch, successfulSkillReads, proven
         const output = patch.artifacts[read.path];
         validateSkillCompilerOutput(scope, read.path, output);
         const compiled = compileArtifact({
-            source: { path: read.path, hash: read.hash },
+            source: { path: read.path, scope, hash: read.hash },
             compiler: SKILL_ARTIFACT_COMPILER,
             output: { ...structuredClone(output), kind: "skill" },
         });
@@ -81,11 +81,11 @@ function compileReadSkills(scope, nextState, patch, successfulSkillReads, proven
         }
     }
 }
-function validateMaterializedTransition(nextState) {
+function validateMaterializedTransition(nextState, scope) {
     if (containsNull(nextState)) {
         throw new Error("Materialized state cannot contain null; use null only as an object-key deletion marker");
     }
-    validateArtifactRegistry(nextState.artifacts);
+    validateArtifactRegistry(nextState.artifacts, `${scope}.artifacts`);
     if (Object.hasOwn(nextState.contract, "compiled_skills")) {
         throw new Error("contract.compiled_skills is retired; Skill compilations belong only in source-addressed artifacts");
     }
@@ -109,7 +109,7 @@ function validateScopePatch(scope, patch) {
         throw new Error("Scoped State Flow patch field lazy must be a JSON object");
     }
     if (isObject(patch.artifacts))
-        validateModelArtifactPatch(patch.artifacts);
+        validateModelArtifactPatch(patch.artifacts, `${scope}.artifacts`);
 }
 function completePatch(patch, response) {
     return {
@@ -153,7 +153,7 @@ function stageScopedSemanticTransition(currentStates, transition, successfulSkil
         const nextState = applyPatch(currentStates[scope], patch);
         compileReadArtifacts(nextState, { artifacts: authored.artifacts ?? {} }, artifactReads.filter((read) => (read.scope ?? "global") === scope), provenanceUpdates[scope]);
         compileReadSkills(scope, nextState, { artifacts: authored.artifacts ?? {} }, skillReads.filter((read) => read.scope === scope), provenanceUpdates[scope]);
-        validateMaterializedTransition(nextState);
+        validateMaterializedTransition(nextState, scope);
         nextStates[scope] = nextState;
     }
     return {

package/node_modules/@llblab/pi-state-flow/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
   "keywords": [

package/node_modules/@llblab/pi-state-flow/dist/skills/state-flow-guide/SKILL.md

@@ -48,7 +48,9 @@ Unscoped paths use effective state. `cwd[1].working` reads the preceding causal
 
 ## Write
 
-Call `patch_state` alone per assistant response; await acceptance before dependent work. Supply one or more of `global`, `cwd`, and `session`; supplied scopes commit atomically. Omit unchanged scopes.
+Call `patch_state` alone per assistant response; await acceptance before dependent work. Supply one or more of `global`, `cwd`, and `session`; supplied scopes commit atomically. Default to Session for current work, CWD for reusable project knowledge, and Global for established cross-project knowledge. Omit unchanged scopes.
+
+The runtime waits cancelably for publication ownership, then applies authored Global/CWD operations to current canonical values. Untouched fields survive; overlapping targets follow successful acceptance order. Correct repeats succeed as `State already current.` without another semantic revision. Do not repeat external actions during a memory wait, or rebuild an entire scope from an older snapshot. Session ownership/history fences remain private, not a universal merge.
 
 Semantic planes `intents`, `contract`, `working`, `artifacts`, and the required `lazy` root are objects; nested lazy values may contain ordinary JSON without stored nulls. Objects merge, arrays/scalars replace, omitted fields persist. Nested `null` removes an owned object key; inherited content may reappear. Canonical `"[N]"` keys patch array elements; indexed deletion is forbidden.