@llblab/pi-kit 0.24.0 → 0.25.0

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

@@ -5,15 +5,15 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getDurableRepositoryRoot } from "./durable.js";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.js";
 import { isObject } from "./json.js";
+import { isStateFlowMode } from "./snapshot.js";
 /** Read the repository-global config once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
 export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = getDurableRepositoryRoot(agentDir)) {
     const directory = repositoryRoot;
     const path = join(directory, "config.json");
     const defaults = {
         directory,
-        autoStart: false,
-        passiveBootstrap: true,
-        passiveTools: true,
+        mode: "off",
+        inactiveMode: "off",
         logging: false,
         showSuccessfulPatches: true,
         historyLimit: DEFAULT_HISTORY_LIMIT,
@@ -27,10 +27,13 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
     catch (error) {
         throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
     }
-    const allowed = new Set(["autoStart", "passiveBootstrap", "passiveTools", "logging", "showSuccessfulPatches", "historyLimit"]);
+    // autoStart/passiveBootstrap/passiveTools are read-only compatibility inputs; explicit mode is authoritative.
+    const allowed = new Set(["mode", "autoStart", "passiveBootstrap", "passiveTools", "logging", "showSuccessfulPatches", "historyLimit"]);
     if (!isObject(value) || Object.keys(value).some((key) => !allowed.has(key))) {
         throw new Error(`State Flow configuration contains unknown settings: ${path}`);
     }
+    if (Object.hasOwn(value, "mode") && !isStateFlowMode(value.mode))
+        throw new Error(`State Flow mode must be "active", "passive" or "off": ${path}`);
     if (Object.hasOwn(value, "autoStart") && typeof value.autoStart !== "boolean")
         throw new Error(`State Flow autoStart must be a boolean: ${path}`);
     if (Object.hasOwn(value, "passiveBootstrap") && typeof value.passiveBootstrap !== "boolean")
@@ -43,13 +46,19 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
         throw new Error(`State Flow showSuccessfulPatches must be a boolean: ${path}`);
     if (Object.hasOwn(value, "historyLimit") && (!Number.isSafeInteger(value.historyLimit) || value.historyLimit < 0 || value.historyLimit > MAX_HISTORY_LIMIT))
         throw new Error(`State Flow historyLimit must be an integer from 0 to ${MAX_HISTORY_LIMIT}: ${path}`);
+    const legacyInactive = value.passiveBootstrap !== false || value.passiveTools !== false ? "passive" : "off";
+    const hasLegacyMode = Object.hasOwn(value, "autoStart") || Object.hasOwn(value, "passiveBootstrap") || Object.hasOwn(value, "passiveTools");
+    const mode = isStateFlowMode(value.mode) ? value.mode : value.autoStart === true ? "active" : hasLegacyMode ? legacyInactive : "off";
     return {
         directory,
-        autoStart: value.autoStart === true,
-        passiveBootstrap: value.passiveBootstrap !== false,
-        passiveTools: value.passiveTools !== false,
+        mode,
+        inactiveMode: isStateFlowMode(value.mode) ? inactiveModeFor(value.mode) : hasLegacyMode ? legacyInactive : "off",
         logging: value.logging === true,
         showSuccessfulPatches: value.showSuccessfulPatches !== false,
         historyLimit: typeof value.historyLimit === "number" ? value.historyLimit : DEFAULT_HISTORY_LIMIT,
     };
 }
+/** Explicit modes never carry a separate passive policy: only Off stays off when inactive. */
+export function inactiveModeFor(mode) {
+    return mode === "off" ? "off" : "passive";
+}

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

@@ -4,12 +4,12 @@ import type { RecentTransitionWindow } from "./history.ts";
 import { type JsonValue } from "./json.ts";
 import type { Snapshot } from "./snapshot.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
-import { type AtomicScopePatches, type MaterializedState, type ModelState } from "./state.ts";
+import { type AtomicScopePatches, type SemanticState } from "./state.ts";
 /** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
 export declare function projectSystemProtocol(messages: AgentMessage[], protocol: string | undefined): AgentMessage[];
 type LazyValueKind = "array" | "boolean" | "null" | "number" | "object" | "string";
 /** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
-export declare function lazyNavigationHint(state: MaterializedState): {
+export declare function lazyNavigationHint(state: SemanticState): {
     available: boolean;
     path: string;
     keys?: Record<string, LazyValueKind>;
@@ -22,7 +22,7 @@ export type ModelStateUpdate = {
     deleted: true;
 });
 /** Exact projected replacements, not authored merge patches; paths are unambiguous key/index segments. */
-export declare function acceptedStateUpdates(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches): {
+export declare function acceptedStateUpdates(before: SemanticState, after: SemanticState, patches: AtomicScopePatches): {
     effective: ModelStateUpdate[];
     lazy_navigation?: {
         available: boolean;
@@ -31,14 +31,14 @@ export declare function acceptedStateUpdates(before: MaterializedState, after: M
     } | undefined;
 };
 export interface ContextView {
-    state: ModelState;
+    state: SemanticState;
     lazy_navigation?: ReturnType<typeof lazyNavigationHint>;
     artifact_invalidations: readonly ArtifactInvalidationNotice[];
     knowledge_rehydration: {
         phase: RehydrationPhase;
     } | null;
 }
-export declare function contextView(state: MaterializedState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase): ContextView;
+export declare function contextView(state: SemanticState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase): ContextView;
 /** Volatile model projection only. Native messages own trajectory; this cache owns no persistence or lifecycle. */
 export declare class ContextProjection {
     private identity;
@@ -48,7 +48,7 @@ export declare class ContextProjection {
     private notices;
     reset(): void;
     /** Called only after successful publication and ancillary acceptance, immediately before returning the native result. */
-    acceptPatch(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches, hints: ArtifactModelHints): {
+    acceptPatch(before: SemanticState, after: SemanticState, patches: AtomicScopePatches, hints: ArtifactModelHints): {
         effective: ModelStateUpdate[];
         lazy_navigation?: {
             available: boolean;
@@ -65,13 +65,13 @@ export interface PassiveContinuation {
     activeRunStartedAt?: number;
     preserveContext?: true;
     handoff: AgentMessage;
-    state: ModelState;
+    state: SemanticState;
 }
 export declare function syntheticUser(text: string): AgentMessage;
-export declare function createPassiveContinuation(state: ModelState, startedAt?: number, activeRunStartedAt?: number, preserveContext?: boolean): PassiveContinuation;
+export declare function createPassiveContinuation(state: SemanticState, startedAt?: number, activeRunStartedAt?: number, preserveContext?: boolean): PassiveContinuation;
 /** Keep the interrupted run through later results; an idle stop retains only later conversation. */
 export declare function passiveContinuationMessages(messages: AgentMessage[], continuation: PassiveContinuation): AgentMessage[];
-export declare function runtimeContextMessage(snapshot: Snapshot, state: MaterializedState, recentTransitions?: RecentTransitionWindow, artifactInvalidations?: readonly ArtifactInvalidationNotice[], rehydrationPhase?: RehydrationPhase, artifactHints?: ArtifactModelHints): AgentMessage;
+export declare function runtimeContextMessage(snapshot: Snapshot, state: SemanticState, recentTransitions?: RecentTransitionWindow, artifactInvalidations?: readonly ArtifactInvalidationNotice[], rehydrationPhase?: RehydrationPhase, artifactHints?: ArtifactModelHints): AgentMessage;
 /** Render a view already projected by this domain without cloning the full semantic overlay twice. */
 export declare function runtimeContextHead(snapshot: Snapshot, view: ContextView, recentTransitions?: RecentTransitionWindow): AgentMessage;
 /** Captured identity survives text decoration; an uncertain boundary retains available context. */

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { projectArtifactForModel } from "./artifact.js";
 import { applyPatch, isObject, presentationJson, sameJson } from "./json.js";
-import { projectStateForModel } from "./state.js";
+import { projectSemanticPatch, projectStateForModel } from "./state.js";
 /** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
 export function projectSystemProtocol(messages, protocol) {
     let lastSystem = -1;
@@ -74,8 +74,8 @@ function projectedStateUpdates(previous, current, patches, beforeNavigation, nav
     const diff = (left, right, path) => {
         if (left === undefined && right === undefined || left !== undefined && right !== undefined && sameJson(left, right))
             return;
-        if (isObject(left) && isObject(right)) {
-            for (const key of new Set([...Object.keys(left), ...Object.keys(right)]))
+        if (isObject(right) && (isObject(left) || left === undefined && path.length === 1 && Object.keys(right).length > 0)) {
+            for (const key of new Set([...Object.keys(left ?? {}), ...Object.keys(right)]))
                 diff(child(left, key), child(right, key), [...path, key]);
         }
         else if (Array.isArray(left) && Array.isArray(right) && left.length === right.length) {
@@ -336,8 +336,9 @@ function projectRecentForModel(recent) {
     const projected = structuredClone(recent);
     for (const record of projected)
         for (const transition of record.transitions) {
+            transition.patch = projectSemanticPatch(transition.patch);
             delete transition.patch.lazy;
-            if (transition.patch.artifacts === undefined)
+            if (!isObject(transition.patch.artifacts))
                 continue;
             for (const [path, entry] of Object.entries(transition.patch.artifacts)) {
                 Object.defineProperty(transition.patch.artifacts, path, {

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

@@ -149,8 +149,8 @@ export async function inspectStateFlowContinuationProvenance(header, repositoryR
             const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), selected.cwd, selected.id);
             if (!runtime)
                 throw new Error("incomplete canonical session runtime");
-            if (!runtime.config.enabled)
-                return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
+            if (runtime.config.mode !== "active")
+                return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow is not active on selected runtime" };
             const streams = ["global", "cwd", "session"].map((scope) => {
                 const owned = temporalScopePaths(selected.cwd, selected.id, scope, root, sessionKey);
                 return parseScopeStream(files.get(owned.checkpoint), files.get(owned.patches), scope, scope === "cwd" ? selected.cwd : undefined, files.get(owned.meta));

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

@@ -1,6 +1,6 @@
 import { type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { type ScopeStream, type TemporalState } from "./temporal.ts";
-import type { StateScope } from "./state.ts";
+import { type StateScope } from "./state.ts";
 /** Canonical semantic sources plus runtime-owned temporal metadata. */
 export interface ScopeStreamSources {
     checkpoint: string;

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

@@ -6,6 +6,7 @@ import { parseArtifactProvenanceRegistry, serializeArtifactProvenanceRegistry, }
 import { MAX_HISTORY_LIMIT } from "./history.js";
 import { canonicalJson, isJsonValue, isObject } from "./json.js";
 import { validateScopeStream, validateTemporalState } from "./temporal.js";
+import { selectSemanticFields } from "./state.js";
 const SESSION_KEY_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 const STATE_FILE = "state.json";
 const CHECKPOINT_FILE = "checkpoint.json";
@@ -33,8 +34,8 @@ export function serializeScopeStream(stream, scope, cwdIdentity) {
     if (scope !== "cwd" && cwdIdentity !== undefined)
         throw new Error("Only State Flow CWD scope serialization accepts a CWD identity");
     return {
-        checkpoint: `${canonicalJson(stream.checkpoint.state)}\n`,
-        patches: stream.patches.map((record) => `${canonicalJson(record.patch)}\n`).join(""),
+        checkpoint: `${canonicalJson(selectSemanticFields(stream.checkpoint.state))}\n`,
+        patches: stream.patches.map((record) => `${canonicalJson(selectSemanticFields(record.patch))}\n`).join(""),
         temporal: {
             revision: stream.revision,
             checkpoint: structuredClone(stream.checkpoint.through),
@@ -96,8 +97,10 @@ export function classifyScopeStream(checkpointSource, patchesSource, scope, expe
         // 0.17.4 and earlier did not persist scope revisions. Credit only their still-retained
         // semantic tail; discarded ancestry cannot be reconstructed without inventing history.
         revision: temporal.revision === undefined ? patches.length : temporal.revision,
-        checkpoint: { through: temporal.checkpoint, state: checkpoint },
-        patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
+        checkpoint: { through: temporal.checkpoint, state: isObject(checkpoint) ? selectSemanticFields(checkpoint) : checkpoint },
+        patches: patches.map((patch, index) => ({
+            transition: boundaries[index], patch: isObject(patch) ? selectSemanticFields(patch) : patch,
+        })),
     };
     validateScopeStream(stream, scope, MAX_HISTORY_LIMIT);
     return { kind: "present", stream };

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

@@ -1,9 +1,9 @@
-import { type Snapshot } from "./snapshot.ts";
+import { type InactiveMode, type Snapshot } from "./snapshot.ts";
 export declare function startEpisode(bootstrap: boolean): Snapshot;
 /** Re-enable a branch checkpoint without discarding its runtime config or provenance. */
 export declare function resumeEpisode(snapshot: Snapshot, bootstrap: boolean): Snapshot;
-/** Disable only this branch; durable defaults and session history remain intact. */
-export declare function stopEpisode(snapshot: Snapshot): Snapshot;
+/** Select an inactive mode for only this branch; durable defaults and session history remain intact. */
+export declare function deactivateEpisode(snapshot: Snapshot, mode: InactiveMode): Snapshot;
 /** Apply one user-run boundary while preserving checkpoint-owned runtime state. */
 export declare function prepareRun(snapshot: Snapshot, prompt: string): boolean;
 /** Retain the full prompt only while its run remains recoverable and unfinished. */

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

@@ -1,6 +1,6 @@
 import { emptySnapshot } from "./snapshot.js";
 export function startEpisode(bootstrap) {
-    const snapshot = emptySnapshot(true);
+    const snapshot = emptySnapshot("active");
     if (bootstrap)
         snapshot.meta.bootstrap = true;
     return snapshot;
@@ -8,15 +8,15 @@ export function startEpisode(bootstrap) {
 /** Re-enable a branch checkpoint without discarding its runtime config or provenance. */
 export function resumeEpisode(snapshot, bootstrap) {
     const next = structuredClone(snapshot);
-    next.config.enabled = true;
+    next.config.mode = "active";
     if (bootstrap)
         next.meta.bootstrap = true;
     return next;
 }
-/** Disable only this branch; durable defaults and session history remain intact. */
-export function stopEpisode(snapshot) {
+/** Select an inactive mode for only this branch; durable defaults and session history remain intact. */
+export function deactivateEpisode(snapshot, mode) {
     const next = structuredClone(snapshot);
-    next.config.enabled = false;
+    next.config.mode = mode;
     return next;
 }
 /** Apply one user-run boundary while preserving checkpoint-owned runtime state. */

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

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatPatchStateArguments } from "./protocol.ts";
+import { type StateFlowMode } from "./snapshot.ts";
 import { type ModelState, type StateScope } from "./state.ts";
 import { type StateFlowTelegramLoader } from "./telegram.ts";
 export interface StateFlowExtensionOptions {
@@ -11,11 +12,8 @@ export interface StateFlowExtensionOptions {
     telegram?: {
         load?: StateFlowTelegramLoader;
     };
-    /** Test/SDK capability override; repository config remains the Pi default. */
-    passive?: {
-        bootstrap?: boolean;
-        tools?: boolean;
-    };
+    /** Test/SDK override of the default mode for new sessions; repository config remains the Pi default. */
+    mode?: StateFlowMode;
 }
 export { formatPatchStateArguments };
 export declare const PATCH_STATE_TOOL_NAME = "patch_state";