@llblab/pi-kit 0.15.0 → 0.17.0

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

@@ -1,14 +1,16 @@
-// Domain: agent-level State Flow configuration, independent of session runtime and semantic state.
+// Domain: repository-global State Flow configuration, independent of session runtime and semantic state.
 import { lstatSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getDurableRepositoryRoot } from "./durable.ts";
 import { isObject } from "./json.ts";
 
 export interface StateFlowConfig {
+	/** Canonical State Flow repository. SDK callers may still override it explicitly. */
 	directory: string;
 	autoStart: boolean;
+	passiveBootstrap: boolean;
+	passiveTools: boolean;
 	/** Opt-in local capture of rejected patch attempts and unresolved terminal drafts. */
 	logging: boolean;
 	/** Show successful patch_state arguments in the interactive tool row. */
@@ -16,12 +18,15 @@ export interface StateFlowConfig {
 	remotePublication?: "off" | "turn-end" | "transition";
 }
 
-/** Read once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
-export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
-	const path = resolve(agentDir, "state-flow.json");
+/** 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)): StateFlowConfig {
+	const directory = repositoryRoot;
+	const path = join(directory, "config.json");
 	const defaults: StateFlowConfig = {
-		directory: getDurableRepositoryRoot(agentDir),
+		directory,
 		autoStart: false,
+		passiveBootstrap: true,
+		passiveTools: true,
 		logging: false,
 		showSuccessfulPatches: true,
 	};
@@ -32,25 +37,23 @@ export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
 	} catch (error) {
 		throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
 	}
-	const allowed = new Set(["directory", "autoStart", "logging", "showSuccessfulPatches", "remotePublication"]);
+	const allowed = new Set(["autoStart", "passiveBootstrap", "passiveTools", "logging", "showSuccessfulPatches", "remotePublication"]);
 	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, "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") throw new Error(`State Flow passiveBootstrap must be a boolean: ${path}`);
+	if (Object.hasOwn(value, "passiveTools") && typeof value.passiveTools !== "boolean") throw new Error(`State Flow passiveTools must be a boolean: ${path}`);
 	if (Object.hasOwn(value, "logging") && typeof value.logging !== "boolean") throw new Error(`State Flow logging must be a boolean: ${path}`);
 	if (Object.hasOwn(value, "showSuccessfulPatches") && typeof value.showSuccessfulPatches !== "boolean") throw new Error(`State Flow showSuccessfulPatches must be a boolean: ${path}`);
 	if (Object.hasOwn(value, "remotePublication") && value.remotePublication !== "off" && value.remotePublication !== "turn-end" && value.remotePublication !== "transition") {
 		throw new Error(`State Flow remotePublication must be off, turn-end, or transition: ${path}`);
 	}
-	if (Object.hasOwn(value, "directory") && (typeof value.directory !== "string" || !value.directory.trim() || value.directory.includes("\0"))) {
-		throw new Error(`State Flow directory must be a non-empty path: ${path}`);
-	}
-	const directory = value.directory as string | undefined;
-	if (directory?.startsWith("~") && directory !== "~" && !directory.startsWith("~/")) throw new Error(`State Flow directory supports ~ or ~/ paths, not named-user expansion: ${path}`);
-	const expanded = directory === "~" ? homedir() : directory?.startsWith("~/") ? resolve(homedir(), directory.slice(2)) : directory;
 	return {
-		directory: expanded === undefined ? defaults.directory : resolve(dirname(path), expanded),
+		directory,
 		autoStart: value.autoStart === true,
+		passiveBootstrap: value.passiveBootstrap !== false,
+		passiveTools: value.passiveTools !== false,
 		logging: value.logging === true,
 		showSuccessfulPatches: value.showSuccessfulPatches !== false,
 		...(value.remotePublication === undefined ? {} : { remotePublication: value.remotePublication as "off" | "turn-end" | "transition" }),

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

@@ -7,6 +7,29 @@ import type { RehydrationPhase } from "./rehydration.ts";
 import { projectStateForModel, type MaterializedState } from "./state.ts";
 
 export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+const LAZY_HINT_PATH = "effective.lazy";
+const LAZY_HINT_MAX_KEYS = 32;
+const LAZY_HINT_MAX_JSON_CHARS = 1024;
+
+type LazyValueKind = "array" | "boolean" | "null" | "number" | "object" | "string";
+
+function lazyValueKind(value: Exclude<MaterializedState["lazy"], undefined>): LazyValueKind {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	if (typeof value === "object") return "object";
+	return typeof value as Exclude<LazyValueKind, "array" | "object">;
+}
+
+/** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
+export function lazyNavigationHint(state: MaterializedState): { available: boolean; path: string; keys?: Record<string, LazyValueKind> } {
+	const base = { available: Object.hasOwn(state, "lazy"), path: LAZY_HINT_PATH };
+	if (!base.available || typeof state.lazy !== "object" || state.lazy === null || Array.isArray(state.lazy)) return base;
+	const entries = Object.entries(state.lazy);
+	if (entries.length > LAZY_HINT_MAX_KEYS) return base;
+	const keys = Object.fromEntries(entries.map(([key, value]) => [key, lazyValueKind(value)]));
+	return JSON.stringify(keys).length <= LAZY_HINT_MAX_JSON_CHARS ? { ...base, keys } : base;
+}
+
 
 /** Bounded context retained after semantic State Flow is stopped in this physical session. */
 export interface PassiveContinuation {
@@ -85,6 +108,7 @@ export function runtimeContextMessage(
 	const context = {
 		specification: snapshot.meta.specification,
 		state: projectStateForModel(state),
+		lazy_navigation: lazyNavigationHint(state),
 		...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
 		...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, reason }) => ({ path, reason })) }),
 		...(recentTransitions.length === 0 ? {} : { recent_transitions: projectRecentForModel(recentTransitions) }),

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

@@ -223,11 +223,12 @@ export function inspectStateFlowContinuationProvenance(
 	const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
 	try {
 		const config = readRegular(paths.config);
+		const runtimeSource = readRegular(paths.runtime);
 		const meta = readRegular(paths.meta);
-		if (config === undefined && meta === undefined) {
+		if (config === undefined && runtimeSource === undefined && meta === undefined) {
 			return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
 		}
-		const runtime = parseSessionRuntime(config, meta, header.cwd, header.id);
+		const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id, meta);
 		if (!runtime) return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
 		if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
 		if (runtime.meta.publication === "files") {
@@ -238,7 +239,7 @@ export function inspectStateFlowContinuationProvenance(
 			validateTemporalState({ lineage: runtime.meta.lineage, scopes: { global, cwd, session } });
 			return { stateFlow: { enabled: true, restorable: true }, reason: "exact file-only runtime cohort is restorable" };
 		}
-		const runtimePath = relative(resolve(repositoryRoot), paths.meta);
+		const runtimePath = relative(resolve(repositoryRoot), runtimeSource === undefined ? paths.meta : paths.runtime);
 		if (runtimePath.startsWith("..")) throw new Error("runtime provenance escapes repository");
 		const owner = execFileSync("git", ["-C", repositoryRoot, "log", "-1", "--format=%H", "--", runtimePath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
 		if (!owner) throw new Error("runtime owner commit is unavailable");

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

@@ -20,13 +20,14 @@ import {
 } from "./artifact.ts";
 import { canonicalJson, isJsonValue, isObject } from "./json.ts";
 import { validateScopeStream, validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
-import type { StateScope } from "./state.ts";
+import { migratePreIntentState, type StateScope } from "./state.ts";
 
 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";
 const PATCHES_FILE = "patches.jsonl";
 const META_FILE = "meta.json";
+const RUNTIME_FILE = "runtime.json";
 
 /** Canonical semantic sources plus runtime-owned temporal metadata. */
 export interface ScopeStreamSources {
@@ -99,6 +100,7 @@ export function classifyScopeStream(
 	}
 	const temporal = meta?.temporal;
 	if (isObject(temporal) && Object.hasOwn(temporal, "checkpoint") && Array.isArray(temporal.patches)) {
+		checkpoint = migratePreIntentState(checkpoint) ?? checkpoint;
 		const owner = meta?.owner;
 		if (scope === "cwd" && expectedCwd !== undefined
 			&& (!isObject(owner) || Object.keys(owner).join(",") !== "cwd" || owner.cwd !== resolve(expectedCwd))) {
@@ -125,6 +127,10 @@ export function classifyScopeStream(
 	} else if (scope === "cwd" && expectedCwd !== undefined) {
 		throw new Error("State Flow CWD scope identity is missing");
 	}
+	if (isObject(legacyCheckpoint) && isObject(legacyCheckpoint.state)) {
+		const migrated = migratePreIntentState(legacyCheckpoint.state);
+		if (migrated) legacyCheckpoint = { ...legacyCheckpoint, state: migrated };
+	}
 	const stream = { checkpoint: legacyCheckpoint, patches };
 	validateScopeStream(stream, scope);
 	return { kind: "present", stream };
@@ -159,9 +165,9 @@ export function temporalScopePaths(cwd: string, sessionId: string, scope: StateS
 	return { directory, checkpoint: join(directory, CHECKPOINT_FILE), patches: join(directory, PATCHES_FILE), meta: join(directory, META_FILE) };
 }
 
-export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): { config: string; meta: string } {
+export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): { config: string; runtime: string; meta: string } {
 	const directory = sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).directory;
-	return { config: join(directory, "config.json"), meta: join(directory, META_FILE) };
+	return { config: join(directory, "config.json"), runtime: join(directory, RUNTIME_FILE), meta: join(directory, META_FILE) };
 }
 
 /** Unsupported state.json presence never becomes an anchored checkpoint. */
@@ -178,7 +184,7 @@ export function captureTemporalFileBases(cwd: string, sessionId: string, reposit
 	const paths = (["global", "cwd", "session"] as const).flatMap((scope) => {
 		const pair = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
 		const runtime = scope === "session" ? sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey) : undefined;
-		return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.meta])];
+		return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.runtime, runtime.meta])];
 	});
 	return captureOwnedFileBases(paths, repositoryRoot);
 }
@@ -218,6 +224,9 @@ export function serializeScopeMetadata(
 	cwdIdentity?: string, existingSource?: string,
 ): string {
 	const existing = parseMetadataDocument(existingSource, `State Flow metadata`);
+	if (scope === "session") {
+		for (const key of ["identity", "lineage", "step", "specification", "validation", "bootstrap", "remotePublication", "revision", "temporalRevision", "publication"]) delete existing[key];
+	}
 	const sources = serializeScopeStream(stream, scope, cwdIdentity);
 	const value = {
 		...existing,
@@ -359,7 +368,7 @@ export function isStateFlowOwnedPath(candidate: string, repositoryRoot = getDura
 		return cwdKey(segments[0]!)
 			&& sessionKey(segments[1]!)
 			&& (segments[2] === STATE_FILE || segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
-				|| segments[2] === "config.json" || segments[2] === META_FILE);
+				|| segments[2] === "config.json" || segments[2] === RUNTIME_FILE || segments[2] === META_FILE);
 	}
 	return false;
 }

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

@@ -27,3 +27,8 @@ export function prepareRun(snapshot: Snapshot, prompt: string): boolean {
 	snapshot.meta.validation = undefined;
 	return true;
 }
+
+/** Retain the full prompt only while its run remains recoverable and unfinished. */
+export function completeRun(snapshot: Snapshot): void {
+	delete snapshot.meta.specification;
+}