@llblab/pi-kit 0.13.0 → 0.14.0

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

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import { containsNull, isJsonValue, isObject } from "./json.js";
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const MODEL_FORBIDDEN_PROVENANCE_FIELDS = ["hash", "compiler", "sourceHash", "compilerRevision", "compiledAt", "source_hash_verified"];
+/** Current compiler protocol for ordinary source artifacts such as Knowledge Markdown. */
+export const ORDINARY_ARTIFACT_COMPILER = "artifact-v1";
+export function hashArtifactSource(source) {
+    return `sha256:${createHash("sha256").update(source).digest("hex")}`;
+}
+export function isArtifactHash(value) {
+    return typeof value === "string" && SHA256_PATTERN.test(value);
+}
+export function validateArtifactMetadata(value, path = "<unknown>") {
+    if (!isObject(value) || !isJsonValue(value)) {
+        throw new Error(`Artifact metadata at ${path} must be finite, acyclic JSON data`);
+    }
+    if (containsNull(value))
+        throw new Error(`Artifact metadata at ${path} cannot contain null`);
+    if (typeof value.description !== "string" || value.description.trim().length === 0) {
+        throw new Error(`Artifact metadata at ${path} must have a non-empty description`);
+    }
+    if (Object.hasOwn(value, "compilation") && !isObject(value.compilation)) {
+        throw new Error(`Artifact metadata at ${path} compilation must be an object`);
+    }
+    if (Object.hasOwn(value, "kind")
+        && (typeof value.kind !== "string" || value.kind.trim().length === 0)) {
+        throw new Error(`Artifact metadata at ${path} kind must be a non-empty string`);
+    }
+    if (Object.hasOwn(value, "tags") && (!Array.isArray(value.tags)
+        || value.tags.some((tag) => typeof tag !== "string" || tag.trim().length === 0 || tag !== tag.trim())
+        || new Set(value.tags).size !== value.tags.length)) {
+        throw new Error(`Artifact metadata at ${path} tags must be unique non-empty trimmed strings`);
+    }
+    if (Object.hasOwn(value, "hash") && !isArtifactHash(value.hash)) {
+        throw new Error(`Artifact metadata at ${path} must have a sha256:<64 lowercase hex characters> hash`);
+    }
+    if (Object.hasOwn(value, "compiler") && (typeof value.compiler !== "string" || value.compiler.trim().length === 0)) {
+        throw new Error(`Artifact metadata at ${path} must have a non-empty compiler revision`);
+    }
+    if (Object.hasOwn(value, "compiled_at") && typeof value.compiled_at !== "string") {
+        throw new Error(`Artifact metadata at ${path} compiled_at must be a string`);
+    }
+}
+export function isArtifactMetadata(value) {
+    try {
+        validateArtifactMetadata(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function validateArtifactRegistry(value) {
+    if (!isObject(value))
+        throw new Error("Artifacts must be a path-keyed JSON object");
+    for (const [path, metadata] of Object.entries(value)) {
+        if (path.trim().length === 0)
+            throw new Error("Artifact path keys must be non-empty");
+        validateArtifactMetadata(metadata, path);
+    }
+}
+export function selectArtifactsByTags(registry, tags, match = "all") {
+    validateArtifactRegistry(registry);
+    if (tags.length === 0 || tags.some((tag) => typeof tag !== "string" || tag.trim().length === 0 || tag !== tag.trim())) {
+        throw new Error("Artifact tag query requires one or more non-empty trimmed strings");
+    }
+    const requested = new Set(tags);
+    return Object.entries(registry)
+        .filter(([, metadata]) => {
+        const available = new Set(metadata.tags ?? []);
+        return match === "all"
+            ? [...requested].every((tag) => available.has(tag))
+            : [...requested].some((tag) => available.has(tag));
+    })
+        .map(([path]) => path)
+        .sort();
+}
+export function isArtifactRegistry(value) {
+    try {
+        validateArtifactRegistry(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function validateSourceIdentity(source) {
+    if (typeof source.path !== "string" || source.path.trim().length === 0) {
+        throw new Error("Artifact source path must be non-empty");
+    }
+    if (!isArtifactHash(source.hash)) {
+        throw new Error(`Artifact source at ${source.path} must have a sha256:<64 lowercase hex characters> hash`);
+    }
+}
+function validateCompilerRevision(compiler, path) {
+    if (typeof compiler !== "string" || compiler.trim().length === 0) {
+        throw new Error(path === undefined
+            ? "Artifact compiler revision must be non-empty"
+            : `Artifact compiler revision at ${path} must be non-empty`);
+    }
+}
+function refreshRequested(path, explicitRefresh) {
+    if (explicitRefresh === true)
+        return true;
+    if (!explicitRefresh || typeof explicitRefresh !== "object" || typeof explicitRefresh.has !== "function")
+        return false;
+    return explicitRefresh.has(path);
+}
+function isProvenanceEntry(value) {
+    return isObject(value) && (value.malformed === undefined || value.malformed === true);
+}
+/** Parse one scope `meta.json` provenance registry; missing input means no recorded evidence. */
+export function parseArtifactProvenanceRegistry(value, context = "Artifact provenance") {
+    if (value === undefined)
+        return {};
+    if (!isObject(value))
+        throw new Error(`${context} must be a path-keyed JSON object`);
+    const registry = {};
+    for (const [path, entry] of Object.entries(value)) {
+        if (path.trim().length === 0)
+            throw new Error(`${context} path keys must be non-empty`);
+        if (!isObject(entry) || !isJsonValue(entry)) {
+            registry[path] = { malformed: true };
+            continue;
+        }
+        const known = new Set(["sourceHash", "compilerRevision", "compiledAt"]);
+        if (Object.keys(entry).some((key) => !known.has(key))) {
+            registry[path] = { malformed: true };
+            continue;
+        }
+        registry[path] = {
+            ...(Object.hasOwn(entry, "sourceHash") ? { sourceHash: entry.sourceHash } : {}),
+            ...(Object.hasOwn(entry, "compilerRevision") ? { compilerRevision: entry.compilerRevision } : {}),
+            ...(Object.hasOwn(entry, "compiledAt") ? { compiledAt: entry.compiledAt } : {}),
+        };
+    }
+    return registry;
+}
+/** Canonical retained form; uninterpretable entries cannot round-trip and are omitted. */
+export function serializeArtifactProvenanceRegistry(registry) {
+    const artifacts = {};
+    for (const [path, entry] of Object.entries(registry)) {
+        if (entry.malformed === true)
+            continue;
+        const fields = {};
+        if (entry.sourceHash !== undefined)
+            fields.sourceHash = entry.sourceHash;
+        if (entry.compilerRevision !== undefined)
+            fields.compilerRevision = entry.compilerRevision;
+        if (entry.compiledAt !== undefined)
+            fields.compiledAt = entry.compiledAt;
+        if (Object.keys(fields).length === 0)
+            continue;
+        artifacts[path] = fields;
+    }
+    return artifacts;
+}
+function invalidField(value, validate) {
+    return value !== undefined && !validate(value);
+}
+const INVALID_EVIDENCE = Symbol("invalid-evidence");
+/** Later authority wins per field; absent runtime evidence falls back to retired embedded values. */
+function fieldEvidence(entry, field, legacy) {
+    if (entry?.malformed === true)
+        return INVALID_EVIDENCE;
+    if (entry !== undefined && Object.hasOwn(entry, field))
+        return entry[field];
+    return legacy;
+}
+/** Classify freshness from semantic state and runtime provenance without acquiring the source body. */
+export function classifyArtifactFreshness(source, metadata, compiler, explicitRefresh = false, provenance) {
+    validateSourceIdentity(source);
+    validateCompilerRevision(compiler);
+    if (metadata === undefined)
+        return { kind: "requires-compilation", reason: "new" };
+    if (!isArtifactMetadata(metadata))
+        return { kind: "requires-compilation", reason: "invalid-metadata" };
+    const entry = isProvenanceEntry(provenance) ? provenance : undefined;
+    const runtime = entry?.malformed === true;
+    const sourceHash = runtime ? INVALID_EVIDENCE : fieldEvidence(entry, "sourceHash", metadata.hash);
+    if (sourceHash === INVALID_EVIDENCE || invalidField(sourceHash, (value) => isArtifactHash(value))) {
+        return { kind: "requires-compilation", reason: "invalid-metadata" };
+    }
+    if (typeof sourceHash === "string" && sourceHash !== source.hash) {
+        return { kind: "requires-compilation", reason: "source-changed" };
+    }
+    const compilerRevision = runtime ? INVALID_EVIDENCE : fieldEvidence(entry, "compilerRevision", metadata.compiler);
+    if (compilerRevision === INVALID_EVIDENCE || invalidField(compilerRevision, (value) => typeof value === "string" && value.trim().length > 0)) {
+        return { kind: "requires-compilation", reason: "invalid-metadata" };
+    }
+    if (typeof compilerRevision === "string" && compilerRevision !== compiler) {
+        return { kind: "requires-compilation", reason: "compiler-changed" };
+    }
+    if (explicitRefresh)
+        return { kind: "requires-compilation", reason: "explicit-refresh" };
+    return { kind: "fresh" };
+}
+/** Produce a deterministic acquisition plan from path/hash candidates and retained evidence. */
+export function planArtifactInvalidation(sources, registry, compiler, options = {}, provenance = {}) {
+    if (!isObject(registry))
+        throw new Error("Artifacts must be a path-keyed JSON object");
+    validateCompilerRevision(compiler);
+    const ordered = [...sources].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    const seen = new Set();
+    const fresh = [];
+    const requiresCompilation = [];
+    for (const source of ordered) {
+        if (seen.has(source.path))
+            throw new Error(`Duplicate artifact source path: ${source.path}`);
+        seen.add(source.path);
+        const metadata = Object.hasOwn(registry, source.path) ? registry[source.path] : undefined;
+        const entry = Object.hasOwn(provenance, source.path) ? provenance[source.path] : undefined;
+        const freshness = classifyArtifactFreshness(source, metadata, compiler, refreshRequested(source.path, options.explicitRefresh), entry);
+        const identity = { path: source.path, hash: source.hash };
+        if (freshness.kind === "fresh")
+            fresh.push(identity);
+        else
+            requiresCompilation.push({ ...identity, reason: freshness.reason });
+    }
+    if (options.removed !== undefined && !Array.isArray(options.removed))
+        throw new Error("Removed artifact paths must be an array");
+    const removed = [...new Set(options.removed ?? [])];
+    for (const path of removed) {
+        if (typeof path !== "string" || path.trim().length === 0)
+            throw new Error("Removed artifact paths must be non-empty");
+        if (seen.has(path))
+            throw new Error(`Artifact source cannot be both present and removed: ${path}`);
+    }
+    return { fresh, requiresCompilation, removed: removed.filter((path) => Object.hasOwn(registry, path)).sort() };
+}
+/** Split one compiler output into model-visible semantics and runtime-owned provenance. */
+export function compileArtifact(update) {
+    validateSourceIdentity(update.source);
+    validateCompilerRevision(update.compiler, update.source.path);
+    if (!isObject(update.output) || MODEL_FORBIDDEN_PROVENANCE_FIELDS.some((field) => Object.hasOwn(update.output, field))) {
+        throw new Error(`Artifact compiler output at ${update.source.path} cannot set runtime-owned provenance fields`);
+    }
+    // Timestamps are runtime evidence; the model-visible entry never retains them.
+    const semantic = structuredClone(update.output);
+    delete semantic.compiled_at;
+    validateArtifactMetadata(semantic, update.source.path);
+    return {
+        semantic,
+        provenance: {
+            sourceHash: update.source.hash,
+            compilerRevision: update.compiler,
+            ...(typeof update.output.compiled_at === "string" ? { compiledAt: update.output.compiled_at } : {}),
+        },
+    };
+}
+/** Merge one compilation/removal cohort into the runtime-owned provenance registry. */
+export function updateArtifactProvenance(registry, updates, removed = []) {
+    const next = structuredClone(registry);
+    for (const update of updates)
+        next[update.source.path] = compileArtifact(update).provenance;
+    for (const path of removed)
+        delete next[path];
+    return next;
+}
+/** Keep only provenance whose artifact path still exists in the given semantic registry. */
+export function pruneArtifactProvenance(registry, semantic) {
+    const next = {};
+    for (const [path, entry] of Object.entries(registry)) {
+        if (Object.hasOwn(semantic, path))
+            next[path] = structuredClone(entry);
+    }
+    return next;
+}
+/** Validate and apply a whole compilation/removal cohort of model-visible artifacts. */
+export function updateArtifactRegistry(registry, updates, removed = []) {
+    validateArtifactRegistry(registry);
+    const compiled = new Map();
+    for (const update of updates) {
+        if (compiled.has(update.source.path))
+            throw new Error(`Duplicate artifact compilation: ${update.source.path}`);
+        compiled.set(update.source.path, compileArtifact(update).semantic);
+    }
+    const removals = new Set();
+    for (const path of removed) {
+        if (typeof path !== "string" || path.trim().length === 0)
+            throw new Error("Removed artifact paths must be non-empty");
+        if (removals.has(path))
+            throw new Error(`Duplicate artifact removal: ${path}`);
+        if (compiled.has(path))
+            throw new Error(`Artifact cannot be compiled and removed atomically: ${path}`);
+        removals.add(path);
+    }
+    const next = structuredClone(registry);
+    for (const path of removals)
+        delete next[path];
+    for (const [path, metadata] of compiled) {
+        Object.defineProperty(next, path, {
+            value: metadata,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return next;
+}
+/** Runtime-owned artifact fields that never belong in ordinary model context. */
+const RUNTIME_ARTIFACT_FIELDS = [...MODEL_FORBIDDEN_PROVENANCE_FIELDS, "compiled_at"];
+/** Validate authored fields only: legacy retained evidence stays readable but cannot be model-edited. */
+export function validateModelArtifactPatch(patch) {
+    for (const [path, entry] of Object.entries(patch)) {
+        if (!isObject(entry))
+            continue; // Whole-artifact deletion and materialized shape belong to the transition owner.
+        const field = RUNTIME_ARTIFACT_FIELDS.find((field) => Object.hasOwn(entry, field));
+        if (field !== undefined)
+            throw new Error(`Artifact patch at ${path} cannot set runtime-owned provenance field ${field}`);
+    }
+}
+/** Strip retained runtime bookkeeping from one model-visible artifact entry. */
+export function projectArtifactForModel(entry) {
+    if (!isObject(entry))
+        return entry;
+    const projected = structuredClone(entry);
+    for (const field of RUNTIME_ARTIFACT_FIELDS)
+        delete projected[field];
+    return projected;
+}
+/** Strip retained runtime bookkeeping from a model-visible artifact registry. */
+export function projectArtifactsForModel(registry) {
+    const projected = {};
+    for (const [path, entry] of Object.entries(registry)) {
+        Object.defineProperty(projected, path, {
+            value: projectArtifactForModel(entry),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return projected;
+}

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

@@ -0,0 +1,49 @@
+import type { CompactionResult } from "@earendil-works/pi-coding-agent";
+export declare const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its durable revision and projected separately; use the retained native entries for subsequent work.";
+/** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
+export declare const STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24000;
+export interface StateFlowCompactionDetails {
+    version: 1;
+    owner: "state-flow";
+    revision: string;
+    step: number;
+}
+export interface StateFlowCompactionPlan {
+    leafId: string;
+    firstKeptEntryId: string;
+    details: StateFlowCompactionDetails;
+}
+type ActiveEntry = {
+    id?: unknown;
+    type?: unknown;
+    customType?: unknown;
+    message?: {
+        role?: unknown;
+        stopReason?: unknown;
+        content?: unknown;
+    };
+};
+export declare function shouldRequestStateFlowCompaction(usage: {
+    tokens: number | null;
+} | undefined): boolean;
+/**
+ * Pi's public usage includes the system prompt, while native compaction can only
+ * shorten persisted messages. Avoid requesting a visibly failing manual
+ * compaction when that transcript is still below the useful-history floor.
+ */
+export declare function hasCompactionSizedTranscript(entries: readonly ActiveEntry[]): boolean;
+/** Retain the complete latest accepted user iteration without hiding foreign extension context. */
+export declare function planStateFlowCompaction(entries: readonly ActiveEntry[], revision: string, step: number): StateFlowCompactionPlan | undefined;
+/** Customize only the extension-owned manual request and only while its planned leaf remains selected. */
+export declare function stateFlowCompactionResult(plan: StateFlowCompactionPlan, marker: string, event: {
+    reason: "manual" | "threshold" | "overflow";
+    customInstructions?: string;
+    branchEntries: readonly ActiveEntry[];
+    preparation: {
+        tokensBefore: number;
+    };
+    signal: AbortSignal;
+}): CompactionResult<StateFlowCompactionDetails> | {
+    cancel: true;
+} | undefined;
+export {};

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

@@ -0,0 +1,67 @@
+import { estimateTokens } from "@earendil-works/pi-agent-core";
+export const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its durable revision and projected separately; use the retained native entries for subsequent work.";
+/** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
+export const STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24_000;
+function stateFlowEntry(entry) {
+    return entry.type === "custom"
+        && typeof entry.customType === "string"
+        && entry.customType.startsWith("state-flow-");
+}
+export function shouldRequestStateFlowCompaction(usage) {
+    return typeof usage?.tokens === "number"
+        && Number.isFinite(usage.tokens)
+        && usage.tokens >= STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS;
+}
+/**
+ * Pi's public usage includes the system prompt, while native compaction can only
+ * shorten persisted messages. Avoid requesting a visibly failing manual
+ * compaction when that transcript is still below the useful-history floor.
+ */
+export function hasCompactionSizedTranscript(entries) {
+    let tokens = 0;
+    for (const entry of entries) {
+        if (entry.type !== "message" || typeof entry.message?.role !== "string")
+            continue;
+        tokens += estimateTokens(entry.message);
+        if (tokens >= STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS)
+            return true;
+    }
+    return false;
+}
+/** Retain the complete latest accepted user iteration without hiding foreign extension context. */
+export function planStateFlowCompaction(entries, revision, step) {
+    if (!/^[0-9a-f]{40,64}$/.test(revision) && !/^file:[0-9a-f]{64}$/.test(revision))
+        return undefined;
+    if (!Number.isSafeInteger(step) || step < 0 || entries.length === 0)
+        return undefined;
+    const terminal = entries.findLastIndex((entry) => entry.type === "message" && entry.message?.role === "assistant");
+    if (terminal < 0 || entries[terminal]?.message?.stopReason === "aborted"
+        || entries[terminal]?.message?.stopReason === "error"
+        || entries[terminal]?.message?.stopReason === "length")
+        return undefined;
+    let keep = terminal;
+    while (keep >= 0 && !(entries[keep]?.type === "message" && entries[keep]?.message?.role === "user"))
+        keep--;
+    if (keep < 0)
+        return undefined;
+    if (entries.slice(0, keep).some((entry) => entry.type === "custom" && !stateFlowEntry(entry)))
+        return undefined;
+    const firstKeptEntryId = entries[keep]?.id;
+    const leafId = entries.at(-1)?.id;
+    if (typeof firstKeptEntryId !== "string" || typeof leafId !== "string")
+        return undefined;
+    return { leafId, firstKeptEntryId, details: { version: 1, owner: "state-flow", revision, step } };
+}
+/** Customize only the extension-owned manual request and only while its planned leaf remains selected. */
+export function stateFlowCompactionResult(plan, marker, event) {
+    if (event.reason !== "manual" || event.customInstructions !== marker)
+        return undefined;
+    if (event.signal.aborted || event.branchEntries.at(-1)?.id !== plan.leafId)
+        return { cancel: true };
+    return {
+        summary: STATE_FLOW_COMPACTION_SUMMARY,
+        firstKeptEntryId: plan.firstKeptEntryId,
+        tokensBefore: event.preparation.tokensBefore,
+        details: structuredClone(plan.details),
+    };
+}

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

@@ -0,0 +1,11 @@
+export interface StateFlowConfig {
+    directory: string;
+    autoStart: 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. */
+    showSuccessfulPatches: boolean;
+    remotePublication?: "off" | "turn-end" | "transition";
+}
+/** Read once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
+export declare function loadStateFlowConfig(agentDir?: string): StateFlowConfig;

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

@@ -0,0 +1,53 @@
+// Domain: agent-level 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 { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getDurableRepositoryRoot } from "./durable.js";
+import { isObject } from "./json.js";
+/** Read once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
+export function loadStateFlowConfig(agentDir = getAgentDir()) {
+    const path = resolve(agentDir, "state-flow.json");
+    const defaults = {
+        directory: getDurableRepositoryRoot(agentDir),
+        autoStart: false,
+        logging: false,
+        showSuccessfulPatches: true,
+    };
+    let value;
+    try {
+        if (!lstatSync(path, { throwIfNoEntry: false }))
+            return defaults;
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
+    }
+    const allowed = new Set(["directory", "autoStart", "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, "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;
+    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),
+        autoStart: value.autoStart === true,
+        logging: value.logging === true,
+        showSuccessfulPatches: value.showSuccessfulPatches !== false,
+        ...(value.remotePublication === undefined ? {} : { remotePublication: value.remotePublication }),
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { type ArtifactInvalidationNotice } from "./artifact.ts";
+import type { RecentTransitionWindow } from "./history.ts";
+import type { Snapshot } from "./snapshot.ts";
+import type { RehydrationPhase } from "./rehydration.ts";
+import { type MaterializedState } from "./state.ts";
+export declare const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+/** Bounded context retained after semantic State Flow is stopped in this physical session. */
+export interface PassiveContinuation {
+    startedAt: number;
+    activeRunStartedAt?: number;
+    handoff: AgentMessage;
+}
+export declare function syntheticUser(text: string): AgentMessage;
+export declare function withoutPrivateValidation(messages: AgentMessage[]): AgentMessage[];
+export declare function createPassiveContinuation(state: MaterializedState, startedAt?: number, activeRunStartedAt?: number): 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, resolutionPending?: boolean): AgentMessage;
+export declare function currentRunTrajectory(messages: AgentMessage[], specification: string, anchorTimestamp: number | undefined): {
+    messages: AgentMessage[];
+    anchorTimestamp?: number;
+};

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

@@ -0,0 +1,109 @@
+import { projectArtifactForModel } from "./artifact.js";
+import { canonicalJson } from "./json.js";
+import { projectStateForModel } from "./state.js";
+export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+export function syntheticUser(text) {
+    return { role: "user", content: [{ type: "text", text }], timestamp: Date.now() };
+}
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((part) => {
+        if (typeof part !== "object" || part === null)
+            return "";
+        const block = part;
+        return block.type === "text" && typeof block.text === "string" ? block.text : "";
+    }).filter(Boolean).join("\n");
+}
+function messageText(message) {
+    return contentText(message.content);
+}
+export function withoutPrivateValidation(messages) {
+    return messages.filter((message) => {
+        return !(message.role === "custom" && message.customType === VALIDATION_MESSAGE_TYPE);
+    });
+}
+export function createPassiveContinuation(state, startedAt = Date.now(), activeRunStartedAt) {
+    return {
+        startedAt,
+        ...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
+        handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${canonicalJson({ state, continuation: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
+    };
+}
+/** Keep the interrupted run through later results; an idle stop retains only later conversation. */
+export function passiveContinuationMessages(messages, continuation) {
+    let start = continuation.activeRunStartedAt === undefined ? -1
+        : messages.findIndex((message) => message.role === "user" && message.timestamp === continuation.activeRunStartedAt);
+    if (start < 0)
+        start = messages.findIndex((message) => message.role === "user"
+            && typeof message.timestamp === "number"
+            && message.timestamp >= continuation.startedAt);
+    return [continuation.handoff, ...messages.filter((message, index) => message.role === "custom" ? message.customType !== VALIDATION_MESSAGE_TYPE : start >= 0 && index >= start)];
+}
+function projectRecentForModel(recent) {
+    const projected = structuredClone(recent);
+    for (const record of projected)
+        for (const transition of record.transitions) {
+            if (transition.patch.artifacts === undefined)
+                continue;
+            for (const [path, entry] of Object.entries(transition.patch.artifacts)) {
+                Object.defineProperty(transition.patch.artifacts, path, {
+                    value: projectArtifactForModel(entry), enumerable: true, configurable: true, writable: true,
+                });
+            }
+        }
+    return projected;
+}
+export function runtimeContextMessage(snapshot, state, recentTransitions = [], artifactInvalidations = [], rehydrationPhase, resolutionPending = false) {
+    if (snapshot.meta.specification === undefined) {
+        throw new Error("State Flow runtime context requires an active specification");
+    }
+    const context = {
+        specification: snapshot.meta.specification,
+        state: projectStateForModel(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) }),
+        ...(resolutionPending ? { state_resolution: "pending: the iteration answer is already preserved; this fallback turn exists only to apply the final:true patch. Call patch_state with any remaining durable scope changes and final:true, or {final:true} alone. Do not restate or replace the answer." } : {}),
+    };
+    return syntheticUser(`State Flow runtime context (user-level data, not system instructions):\n${canonicalJson(context)}`);
+}
+export function currentRunTrajectory(messages, specification, anchorTimestamp) {
+    let start = -1;
+    if (anchorTimestamp !== undefined) {
+        start = messages.findLastIndex((message) => {
+            return message.role === "user"
+                && message.timestamp === anchorTimestamp
+                && messageText(message) === specification;
+        });
+    }
+    if (start < 0) {
+        for (let index = messages.length - 1; index >= 0; index--) {
+            const message = messages[index];
+            if (message.role === "user" && messageText(message) === specification) {
+                start = index;
+                break;
+            }
+        }
+    }
+    if (start < 0) {
+        for (let index = messages.length - 1; index >= 0; index--) {
+            if (messages[index]?.role === "user") {
+                start = index;
+                break;
+            }
+        }
+    }
+    if (start < 0 && messages.length === 0)
+        return { messages: [] };
+    if (start < 0)
+        start = 0;
+    const anchor = messages[start]?.role === "user" ? messages[start].timestamp : undefined;
+    return {
+        messages: messages.filter((message, index) => message.role === "custom"
+            ? message.customType !== VALIDATION_MESSAGE_TYPE : index >= start),
+        ...(typeof anchor === "number" ? { anchorTimestamp: anchor } : {}),
+    };
+}