@llblab/pi-kit 0.3.1 → 0.4.0

package/node_modules/@llblab/pi-state-flow/AGENTS.md

@@ -0,0 +1,28 @@
+# Agent Instructions
+
+- Keep independent domain modules under `lib/`, mirror every domain with a same-named file under `tests/`, place cross-domain architecture checks in `tests/invariants.test.ts`, and keep `index.ts` as a minimal composition/public-export boundary.
+- Keep the extension opt-in and preserve clear attribution to SKILL.state wherever the inherited explicit-state approach is described.
+- Preserve Pi's native tool loop and complete inspectable session trace; project completed-run history only at user-run boundaries. Retain persistent and current-run context-bearing custom messages from other extensions, plus the complete current-run trajectory, except State Flow's own validation feedback when it is represented separately.
+- Expose one fully materialized state with exactly `contract`, `working`, and `response`; the first two are flexible memory objects and the third is the latest complete user-facing answer string.
+- Require no State Flow patch on tool-bearing assistant responses; retain the current run's user message, assistant tool calls, and tool results until one terminal response commits state.
+- Accept a non-empty ordinary terminal answer without a State Flow comment as an empty memory patch: preserve `contract` and `working`, replace `response`, and use the same staging, Skill-compilation validation, and commit lifecycle. Explicit comment markers (including malformed or embedded ones) must not silently fall back to ordinary text. When a patch is present, require one top-level transcript-private `<!-- state_flow … -->` comment containing only `contract` and `working`, one separating blank line, then the user-facing answer exactly once. At `message_end`, remove the comment and stage the transition; at `turn_end`, reconcile `response` with Pi's finalized assistant message after all chained handlers by concatenating finalized text blocks without inserted characters, then commit. Route missing text or a tool call added after terminal validation through the same bounded regeneration chain. Transcript-private does not mean confidential during streaming.
+- Treat terminal state as a decision-relevant handoff, not narration: compile stable requirements, decisions, rejected approaches, interface commitments, and reusable operational knowledge into `contract`; retain verified facts, artifacts, validation, failures, current domain state, unresolved work, and exact continuation in `working`.
+- Preserve active constraints, unresolved questions, consequential negative results, and the next discriminating check before compression. Distinguish observations, user requirements, assistant decisions, and hypotheses; do not promote assistant conclusions to user requirements. Retain useful source locators and validity conditions for consequential facts without mandatory per-value metadata. Keep rejection reasons and reconsideration conditions. Reconcile contradictions through evidence or user clarification instead of silently overwriting established constraints or observations; retain unresolved conflicts and decision-relevant hypotheses as uncertain. These are protocol obligations, not deterministic semantic validation gates.
+- Treat `working` as last observations, not a live workspace. Revalidate volatile facts before consequential actions; after interruption or branch navigation inspect relevant external effects before repeating operations. Failed state commits and restored memory do not undo tool effects. Missing evidence proves neither success nor absence of effects: retain uncertainty and the next check. Keep revalidation targeted, without routine Skill rereads, action ledgers, or runtime freshness/rollback guarantees.
+- Treat each successful `SKILL.md` read as episode-level acquisition using the finalized tool-execution arguments after mutable interception: require a non-empty `contract.compiled_skills[exactReadPath]`, keep its nested representation fully flexible without `coverage`/`rules` schema, reject the terminal commit when missing, treat complete matching compilations as authoritative, and forbid routine rereads without an uncovered detail, incomplete compilation, concrete source-change evidence, reconciliation failure, or explicit user request.
+- Make the model audit and optimize complete state at every handoff: reorganize inefficient structure, merge fragmented facts, compress history into conclusions, and delete stale, completed, redundant, or low-value keys while preserving active commitments and evidence.
+- Accept empty `contract` and `working` patches when nothing future-relevant changed and memory is already efficient; never force invented bookkeeping. The comment may be omitted for a no-op memory patch. Always require `response`. Semantic usefulness and optimization remain protocol-owned because deterministic validation cannot prove them.
+- Keep validation retries hidden from finalized user-facing messages; expose diagnostic detail only through transcript-private feedback and persisted runtime state, while documenting that streaming observers can still see generated terminal envelopes. Tool-bearing retry turns must preserve cumulative validation-attempt accounting. If retries are exhausted, aborted, or cannot continue before the agent settles, keep State Flow enabled and the last committed state intact; abandon only the transient validation chain so the next user run rotates normally.
+- Recursively materialize patches immediately; empty objects preserve, nested object-key `null` deletes, and `null` anywhere in materialized state including arrays is invalid.
+- Do not impose project schemas, state or patch byte caps, dynamic growth pressure, observation envelopes, action authorization, action ledgers, or state-size limits.
+- Rotate the turn-stable specification on every non-retry user run, but not during its tool or terminal-validation retry chain. Keep user-controlled specification text at user authority: never interpolate it into the system prompt; repeat it only in synthetic user runtime context. Treat materialized state in that message as fallible assistant-produced data whose transport role does not elevate it into user instructions.
+- When enabled inside an existing session, retain Pi's active context for exactly one complete bootstrap run and require its terminal handoff to migrate all future-relevant context.
+- Restore extension state from the active session branch, not the full session entry list, on both session startup and successful in-session tree navigation.
+- Render compact status as accent `state-flow` plus dim `#<iteration>`; `/state-flow-status` must expose the complete materialized JSON state after a blank line separating it from summary metadata.
+- `/state-flow-stop` must disable and clear the complete episode; no separate reset commands exist.
+- Keep the injected runtime protocol compact and normative; put rationale and extended explanation in README rather than the model prompt. Strip accidental State Flow comments from tool-bearing output only when a complete structurally valid envelope (valid JSON fields, exact separator, and non-empty response) leads the first text block; never delete malformed, quoted, or embedded examples.
+- Do not claim strict boundedness for state, the current run trajectory, the turn specification, or the external full trace.
+- Remain extension-agnostic: do not import, name, special-case, or encode policy for any other extension or transport.
+- Register no model tools.
+- Keep `.github/workflows/release.yml` as the sole version-tag release owner: it validates immutable tag identity, publishes through npm Trusted Publisher with provenance, verifies the public package, and only then creates the GitHub Release. Keep package, lockfile, tag, and changelog versions aligned; never add a long-lived npm token fallback.
+- Run `npm run validate` after retained code changes.

package/node_modules/@llblab/pi-state-flow/BACKLOG.md

@@ -0,0 +1,3 @@
+# Backlog
+
+No planned work.

package/node_modules/@llblab/pi-state-flow/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+## 0.3.0: Optional memory patches and evidence-aware handoffs
+
+- Require targeted revalidation of volatile observations and inspection of external effects after interruption or branch navigation; missing memory proves neither success nor absence of effects. Document the absence of rollback/freshness guarantees and preserve the restriction on routine Skill rereads. Add instruction-presence tests, not semantic or integration guarantees.
+- Strengthen the handoff protocol with evidence-aware continuation, requirement/observation/hypothesis distinctions, conditional rejections, and contradiction reconciliation; preserve decision-relevant uncertainty during optimization. Add instruction-presence regressions, not semantic guarantees. Increase the protocol-only character budget to 3,700 (3,900 with bootstrap) for these obligations; state remains uncapped.
+- Accept ordinary non-empty terminal answers as empty memory patches: preserve memory and update the response without unnecessary regeneration, including answers split across text blocks.
+- Keep malformed explicit envelopes and missing Skill compilations on the existing bounded validation path.
+- Clear the backlog; documented integration and continuation-quality limitations remain, not release commitments.
+
+## 0.2.3: Document protocol and validation limitations
+
+- Document that duplicate-comment detection also rejects literal State Flow envelope examples inside fenced or inline code in terminal answers, and provide a plain-JSON workaround.
+- Clarify that mock lifecycle tests are not real Pi scheduler integration checks and that structural validation cannot guarantee semantic memory retention.
+- No runtime behavior changes.
+
+## 0.2.2: README structure hotfix
+
+- Separate installation from usage, remove the redundant quick-start section, and move architecture details after the user-facing documentation.
+
+## 0.2.1: README banner hotfix
+
+- Add the project banner to the README.
+
+## 0.2.0: Modular runtime hardening
+
+- Add a task-first README quick start with explicit compatibility, opt-in behavior, one-off trial instructions, and Pi package security guidance.
+- Tighten the normative runtime protocol and enforce a regression-tested character budget; omit absent validation feedback from synthetic runtime context instead of serializing a redundant `null`.
+- Redistribute lifecycle coverage from the former monolithic extension suite into the corresponding mirrored domain suites, leaving `extension.test.ts` focused on composition and using one shared test harness.
+- Split the runtime into independent `json`, `state`, `episode`, `snapshot`, `session`, `recovery`, `status`, `context`, `skills`, `terminal`, `validation`, `transition`, and `extension` modules under `lib/`; isolate explicit episode transitions, active-branch selection and recovery, status rendering, bounded retry decisions, atomic state staging, and compare-and-swap commits; mirror each domain under `tests/`, enforce an acyclic dependency graph with cross-domain invariant tests, and reduce `index.ts` to composition and public exports.
+- Register lifecycle commands in the canonical start, status, stop order.
+- Centralize synthetic runtime-context construction and private validation-message filtering in the independently tested context domain, keeping user-controlled specifications out of system-prompt composition.
+- Keep State Flow enabled and preserve the last committed state when terminal-validation retries are exhausted; only the transient retry chain is abandoned so the next user request can continue reliably.
+- Track Skill reads through an independently tested lifecycle correlator in Pi's actual `tool_execution_start` → `tool_call` event order while retaining the mutable intercepted input reference, so later argument rewrites are attributed to the executed path.
+- Discard mismatched lifecycle records defensively so a stale or reused tool-call id cannot produce false Skill acquisition.
+- Bound restored iteration and validation-attempt counters before incrementing them, reject exhausted live iteration counters explicitly, and cover both safe-integer boundaries so malformed branch metadata cannot corrupt retry accounting or status output.
+- Reject restored non-JSON state values such as non-finite numbers before they can break hashing or silently materialize as `null`.
+- Fall back past malformed newer checkpoints to the newest valid active-branch snapshot, while still failing closed on cyclic or hostile snapshot objects when no valid checkpoint remains.
+- Reject malformed three-field state shapes rather than reinterpreting them as legacy working memory, and contain failures while enumerating hostile branch entries.
+- Make canonical serialization and exported patch validation reject lossy or cyclic non-JSON inputs explicitly instead of returning invalid results or silently rewriting values.
+
+## 0.1.5: Skill attribution and state model clarification
+
+- Attribute successful Skill acquisition to finalized `tool_execution_start` arguments, with a tested compatibility fallback to the intercepted `tool_call` input.
+- Clarify that the three-field materialized handoff coexists with mutable exogenous project and runtime state that can also shape model behavior.
+- Remove the obsolete `/reload` step from the usage instructions.
+
+## 0.1.4: Release verification hotfix
+
+- Kept npm pack lifecycle output out of release inventory JSON so Trusted Publisher releases can complete public verification and GitHub Release creation.
+
+## 0.1.3: Trusted Publisher release automation
+
+- Added immutable-tag GitHub Actions automation that validates the package, publishes and verifies npm through Trusted Publisher with provenance, and creates the matching GitHub Release.
+
+## 0.1.2: Repository identity hotfix
+
+- Aligned GitHub repository, package metadata, installation documentation, and release links under the canonical `llblab/pi-state-flow` identity.
+
+## 0.1.1: Public npm distribution
+
+- Enabled public npm distribution for `@llblab/pi-state-flow`, including registry access and verified GitHub package metadata.
+- Clarified that compiled Skill knowledge is stored persistently under `contract.compiled_skills`, never as another top-level state field.
+
+## 0.1.0
+
+- Added an opt-in State Flow runtime inspired by SKILL.state, with argument-free lifecycle commands, per-user-run specifications, active-branch persistence, and one materialized explicit state.
+- Added native Pi tool-loop preservation: tool-bearing responses require no patch, current-run tool trajectory remains model-visible, and one terminal handoff commits state after the complete agent run.
+- Added required flexible `contract` and `working` objects plus the required latest user-facing `response` string, recursive materialization, nested object-key `null` deletion, materialized-null rejection, and deterministic state compare-and-swap.
+- Kept arbitrary response content outside the transcript-private `<!-- state_flow … -->` memory-patch frame; the runtime strictly anchors the frame at the start of one terminal text block, requires exactly one blank separator, reconciles materialized `response` with Pi's finalized post-handler text at `turn_end`, and routes post-handler finalization failures through the same bounded hidden regeneration chain. Documented that the frame remains observable to streaming consumers before finalization.
+- Kept user-controlled turn specifications at user authority by moving their repeated representation out of the system prompt and into synthetic user runtime context, including support for empty text in image-only prompts.
+- Added active-branch restoration after `/tree` navigation, clean abandonment of interrupted terminal-validation retries before the next user run, and cumulative retry accounting across intervening tool-bearing turns.
+- Preserved persistent and current-run custom context from other Pi extensions, attributed Skill acquisition from finalized executed arguments after mutable tool interception, and limited accidental intermediate-envelope stripping to a structurally valid leading frame.
+- Hardened recursive patch materialization so JSON keys such as `__proto__` remain ordinary own data without changing object prototypes.
+- Added an explicit release file allowlist, Pi package discovery keywords, package-safe README targets, Pi/Node compatibility bounds, and a prepack validation gate so generated packages contain only runtime and human-facing release files.
+- Added bootstrap migration for enabling State Flow inside an existing session, per-run specification rotation, schema-free episode-level Skill compilation in `contract.compiled_skills` keyed by exact source path, and model-owned memory optimization that reorganizes inefficient structure and deletes stale, redundant, speculative, or low-value state.
+- Removed per-tool state commits, action authorization, Delta Window, observation envelopes, action ledgers, project schemas, state and patch byte caps, dynamic growth pressure, and all coupling to other extensions.
+- Compressed the static runtime protocol while retaining terminal, handoff, Skill-compilation, authority, and memory-optimization invariants.
+- Added stop-as-complete-episode-reset semantics, a compact accent `state-flow` plus dim `#<iteration>` status, and complete pretty-formatted state JSON output from `/state-flow-status`.

package/node_modules/@llblab/pi-state-flow/README.md

@@ -0,0 +1,197 @@
+# Pi State Flow
+
+> Inspired by [SKILL.state](https://arxiv.org/html/2608.26263v2)
+
+![pi-state-flow banner](https://raw.githubusercontent.com/llblab/pi-state-flow/main/banner.jpg)
+
+An opt-in Pi extension for explicit, validated state handoffs between complete agent runs.
+
+State Flow preserves Pi's native tool loop inside each user request:
+
+```text
+user request
+  → model → tool → model → tool → model
+  → one terminal answer (memory patch when needed)
+  → committed state + displayed response
+```
+
+The current run keeps its user message, assistant tool calls, tool results, and persistent or current-run context-bearing custom messages from other Pi extensions model-visible. Only after the terminal handoff does the next run replace that trajectory with one materialized state. Pi's complete session trace remains inspectable.
+
+## Installation
+
+Requirements: Pi `0.84.4–0.84.x` and Node.js `22.19.0` or newer.
+
+Install from npm:
+
+```bash
+pi install npm:@llblab/pi-state-flow
+```
+
+Or install from GitHub:
+
+```bash
+pi install git:github.com/llblab/pi-state-flow
+```
+
+Pi packages execute with full user permissions; review the source before installing, as with any extension.
+
+## Usage
+
+```text
+/state-flow-start
+```
+
+In a fresh session, the next prompt starts the first stateful run. Each later non-retry user prompt becomes the current turn-stable specification while committed state remains intact. When enabled inside an existing session, the first complete run retains the active pre-Flow context and must migrate every future-relevant fact into its terminal handoff.
+
+The extension registers no model tools. Tool-bearing assistant responses use ordinary Pi tools and contain no State Flow patch. When memory changes, a terminal assistant response contains one transcript-private memory-patch comment, one separating blank line, and the user-facing answer exactly once. When memory is unchanged, an ordinary non-empty answer is sufficient: the runtime treats the missing comment as an empty memory patch, preserving `contract` and `working` while replacing `response`. Transcript-private means removed from the finalized message and later model context, not confidential during streaming:
+
+```html
+<!-- state_flow {"contract":{...},"working":{...}} -->
+
+Complete user-facing answer
+```
+
+At `message_end`, an explicit private comment must start the single terminal text block and be followed by exactly one blank line. Without a State Flow comment marker, ordinary text blocks are concatenated without inserted characters and preserved unchanged; no regeneration is triggered merely because the comment is absent. Malformed, incomplete, or embedded State Flow comment markers still fail explicit-envelope validation rather than silently becoming no-op patches. It removes only the comment and separator and stages all three state fields. At `turn_end`, it reconciles `response` with Pi's finalized assistant message after all chained `message_end` handlers, concatenating any text blocks without inserting characters, then commits. If a later handler removes all answer text or adds a tool call after terminal validation, the same hidden regeneration chain runs. Arbitrary response Markdown remains outside the HTML comment, so its own content cannot terminate the private frame. Invalid terminal commits are regenerated through hidden feedback up to three times. If all retries fail, State Flow remains enabled, preserves the last committed snapshot, abandons only the transient validation chain, and lets the next user request start cleanly from that state. Tool-bearing turns do not reset the attempt count. Aborting a regeneration has the same non-destructive behavior.
+
+Commands:
+
+```text
+/state-flow-start   # Start a fresh episode
+/state-flow-status  # Inspect iteration metadata and the complete state JSON
+/state-flow-stop    # Stop and clear the complete episode
+```
+
+The compact Pi status renders an accent `state-flow` label followed by the dimmed committed iteration number, for example `state-flow #7`. `/state-flow-status` reports iteration metadata, then separates the complete pretty-formatted materialized state JSON with a blank line for operator analysis.
+
+`/state-flow-stop` clears the specification, materialized state, validation feedback, and committed-run counter. A later `/state-flow-start` always begins a fresh episode. State follows the active Pi session branch and is restored immediately after `/tree` navigation. If the newest checkpoint is malformed, restoration walks backward to the newest valid checkpoint instead of resetting an otherwise recoverable episode. Entering a branch with no State Flow snapshot leaves the mode disabled there.
+
+## Materialized state
+
+The model sees one persistent state object before the current run trajectory:
+
+```json
+{
+  "contract": {},
+  "working": {},
+  "response": "Latest complete user-facing answer"
+}
+```
+
+Materialized state has exactly three fields:
+
+- `contract` is a flexible object containing durable user requirements, stable decisions, rejected approaches, interface commitments, and compact operational knowledge compiled from relevant Skills or documents.
+- `working` is a flexible object containing verified facts, artifacts, validation, failures, unresolved work, current environment or domain state, and the exact continuation point.
+- `response` is the exact non-empty answer body captured by the runtime. It replaces the previous response on every commit.
+
+The transcript-private wire patch contains only `contract` and `working`; the runtime derives `response` from Pi's finalized answer body. Memory patches merge recursively and materialize immediately. Empty objects preserve existing content; arrays and primitives replace. Nested object-key `null` deletes that key:
+
+```html
+<!-- state_flow {"contract":{},"working":{"move":null,"result":"ok"}} -->
+
+The operation completed.
+```
+
+This removes `working.move`, replaces `working.result`, preserves every other memory key, and stores `The operation completed.` as `response`. Materialized state cannot contain `null`, including inside arrays; represent semantic absence by omitting a key or using an explicit non-null domain value.
+
+State and patch size have no byte, growth, pressure, or project-schema limit. Patch history remains only in the Pi trace, not in model context.
+
+These three fields are the complete **materialized State Flow state**, but they are not the only state that can shape model behavior. A situational fourth, exogenous state lives outside the handoff: the current project, workspace, tools, processes, and runtime environment. It can change while work is in progress—including through the model's own tool effects—and later observations of those changes can alter subsequent behavior. State Flow neither snapshots nor rolls back this external state; `working` should retain only the decision-relevant facts needed to reconnect the next run to it.
+
+### Reconnecting to external state
+
+Treat `working` as the last observation, not a live workspace. Before consequential actions, revalidate the volatile facts that action depends on: for example, the current revision and dirty files before editing, or the remote publication status before retrying a release. This is targeted inspection, not a requirement to reread stable knowledge or compiled Skills routinely.
+
+After an interruption or session-branch navigation, inspect relevant external effects before repeating operations. A failed terminal commit does not undo file edits, running processes, or remote requests; restoring older memory does not restore the workspace. Missing memory is evidence of neither success nor absence of effects. If the effect cannot be verified, retain that uncertainty and the next discriminating check instead of blindly retrying or claiming completion.
+
+These are protocol obligations, not runtime freshness checks, rollback, or exactly-once execution guarantees. No action ledger or new evidence-retrieval tool is introduced.
+
+## Terminal handoff quality
+
+The terminal answer commits a handoff, not a progress phrase or transcript summary. A memory patch is required when future-relevant memory changes; omitting it is only shorthand for preserving existing memory, not a way to infer new memory from prose. The next run may see only this state plus its new user prompt. A fresh model should be able to continue without rereading, rediscovering, re-deriving decisions, or repeating failed approaches.
+
+Useful handoffs capture:
+
+- Stable requirements, constraints, decisions, rejected approaches, and compiled operational rules in `contract`.
+- Verified facts, changed artifacts, validation evidence, failures, unresolved work, current domain state, and exact continuation in `working`.
+
+Before compressing, preserve active constraints, unresolved questions, consequential negative results, and the next check that would distinguish competing explanations. Keep observations, user requirements, assistant decisions, and hypotheses distinguishable; an assistant conclusion is not a user requirement. Retain decision-relevant hypotheses as uncertain rather than deleting them merely because they are unverified.
+
+For consequential facts, include a compact source locator and validity condition when useful (for example, a test command and the revision it checked), not mandatory metadata on every value. Record why an approach was rejected and what would justify reconsidering it. When new information conflicts with an established constraint or observation, reconcile it using evidence or user clarification; neither an unsupported new claim nor fallible old memory wins automatically. If unresolved, preserve the conflict and the next discriminating check.
+
+These are model obligations, not semantic validation gates. Protocol tests check that the instructions remain present; only continuation evaluations can establish whether a fresh agent makes the next correct decision.
+
+Do not store raw source, logs, tool output, reasoning traces, or vague values such as `"continue work"` and `"in progress"`.
+
+### Skill compilation
+
+A successful `SKILL.md` read is treated as episode-level acquisition. Before terminal commit, the model compiles its future-relevant operational rules, applicability conditions, constraints, syntax, routing decisions, and failure conditions under the exact source path. This compilation lives inside persistent `contract` memory at `contract.compiled_skills`; `compiled_skills` never becomes a fourth top-level state field. The nested representation remains fully flexible:
+
+```json
+{
+  "contract": {
+    "compiled_skills": {
+      "/exact/path/to/SKILL.md": {
+        "routing": "...",
+        "syntax": { "...": "..." },
+        "constraints": ["..."],
+        "reread_when": ["..."]
+      }
+    }
+  }
+}
+```
+
+No `coverage`/`rules` schema is imposed. The model chooses the smallest structure that faithfully preserves the Skill's useful behavior. Raw Skill text is not copied. The runtime checks only that the exact successfully executed source path has a non-empty compilation and rejects a terminal commit when it is missing. Attribution follows Pi's lifecycle order: it retains the mutable `tool_call` input reference so later interception rewrites resolve to the path actually executed, with `tool_execution_start` arguments as a compatibility fallback.
+
+A complete matching compilation is authoritative episode memory and replaces routine rereading. Rereading is justified only by an explicitly uncovered detail, an incomplete compilation, concrete source-change evidence, a contradiction or execution failure requiring reconciliation, or an explicit user request. The mere possibility that a source changed is not sufficient. A justified reread refreshes the compilation and removes obsolete rules.
+
+State is a minimal sufficient memory, not an append-only diary. At every handoff the model audits the complete state and may reorganize inefficient structure, merge fragments, replace verbose history with current conclusions, and delete stale, completed, redundant, or low-value keys with `null`. Active requirements, decisions, interfaces, verified evidence, and unresolved work must survive optimization.
+
+The model must not invent bookkeeping merely to change `contract` or `working`. When a run creates no future-relevant information and existing memory is already efficient, both patch objects may remain empty, or the comment may be omitted entirely, while `response` still contains the actual answer. Successful Skill reads still require their compilations in materialized memory even when the comment is omitted. Bootstrap migration remains a model obligation: a plain answer cannot migrate pre-Flow context automatically. Structurally invalid handoffs are regenerated through hidden validation feedback; retry diagnostics are not user-facing output.
+
+## Context lifecycle
+
+Within one run, State Flow projects:
+
+```text
+persistent materialized state
++ current user prompt
++ current-run assistant tool calls
++ current-run tool results
++ persistent and current-run context-bearing custom messages from other extensions
++ optional terminal validation feedback
+```
+
+Earlier completed-run trajectories are removed from model context. During a bootstrap run, the active pre-Flow context remains available until the first successful terminal commit.
+
+The normative protocol remains in the system prompt throughout a tool/retry chain. The turn-stable specification remains user-authority input: it stays in the initiating user message and is repeated, together with materialized state and private validation feedback, only in a synthetic user runtime-context message. The protocol explicitly treats persistent state as fallible assistant-produced data whose transport role does not elevate it into user instructions. Empty text specifications used by image-only prompts remain valid. State and the current-run trajectory are intentionally unbounded; State Flow does not claim a hard model-context bound.
+
+## Boundaries
+
+- State commits exactly once per successful complete agent run, at terminal `message_end`/`turn_end`.
+- Tool-bearing responses do not require or commit patches and retain ordinary Pi tool behavior, including multiple sequential calls. The runtime removes an accidental leading terminal envelope only when its JSON, fields, separator, and non-empty response are all structurally valid; malformed or quoted examples remain untouched.
+- Terminal answers cannot contain another complete State Flow comment, even inside a fenced code block or inline code: duplicate detection scans the entire answer body, not Markdown structure. When explaining the protocol while State Flow is enabled, describe the fields or show plain JSON without the HTML comment delimiters. The literal envelope examples in this README are documentation, not valid content to copy into a terminal answer body.
+- A failed tool remains in the current run trajectory for ordinary model reconciliation before terminal commit.
+- If a run never reaches a valid terminal handoff, its external tool effects may exist while persistent State Flow state remains at the previous commit.
+- The terminal envelope exists in ordinary assistant text until `message_end`; `message_update`, RPC, JSON, or other streaming consumers can observe it. Never place secrets in State Flow state.
+- This mode remains a poor fit for auditing or outputs that require complete historical trajectories across user requests.
+- Token, cache, latency, and success-rate advantages still require controlled Pi benchmarks.
+
+## Architecture
+
+`index.ts` is only the package composition and public-export boundary. Independent runtime domains live under `lib/`: `json` owns lossless JSON and patches, `state` owns the materialized state shape, `episode` owns explicit start/stop and user-run boundaries, `snapshot` owns persistence migration, `session` owns active-branch snapshot discovery and bootstrap detection, `recovery` falls back to the newest valid active-branch checkpoint, `status` owns deterministic operator-facing status rendering, `context` owns trajectory projection, private-feedback filtering, and synthetic runtime-context construction, `skills` owns Skill acquisition rules and mutable lifecycle correlation, `terminal` owns the handoff protocol, `validation` owns bounded retry decisions, `transition` owns atomic staging and compare-and-swap commits, and `extension` coordinates these domains with Pi. Every domain has a same-named test under `tests/`; lifecycle scenarios are colocated with the domain whose contract they exercise, `tests/extension.test.ts` remains focused on composition, shared setup lives in `tests/harness.ts`, and cross-domain constraints live in `tests/invariants.test.ts`.
+
+## Validation
+
+```bash
+npm install
+npm run validate
+```
+
+Validation covers TypeScript checking, automated tests, and an extension import smoke check. Lifecycle tests use a mock Pi event harness; they do not establish behavior under the real Pi scheduler, queued prompts, abort/compaction interactions, or combinations of extensions. Those scenarios still need integration checks. Structural patch validation also cannot prove that a handoff preserved every important requirement or compiled a Skill faithfully.
+
+## Project status
+
+- [Open work](BACKLOG.md)
+- [Release history](CHANGELOG.md)
+- [Agent and contributor constraints](AGENTS.md)

package/node_modules/@llblab/pi-state-flow/index.ts

@@ -0,0 +1,4 @@
+export { applyPatch, canonicalJson, hashJson, isObject, validatePatch } from "./lib/json.ts";
+export type { JsonObject, JsonValue } from "./lib/json.ts";
+export { emptyState, isStateDocument, type StateDocument } from "./lib/state.ts";
+export { default } from "./lib/extension.ts";

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

@@ -0,0 +1,88 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { canonicalJson } from "./json.ts";
+import type { Snapshot } from "./snapshot.ts";
+
+export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+
+export function syntheticUser(text: string): AgentMessage {
+	return { role: "user", content: [{ type: "text", text }], timestamp: Date.now() } as AgentMessage;
+}
+
+function contentText(content: unknown): string {
+	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 as { type?: unknown; text?: unknown };
+		return block.type === "text" && typeof block.text === "string" ? block.text : "";
+	}).filter(Boolean).join("\n");
+}
+
+function messageText(message: AgentMessage): string {
+	return contentText((message as { content?: unknown }).content);
+}
+
+export function withoutPrivateValidation(messages: AgentMessage[]): AgentMessage[] {
+	return messages.filter((message) => {
+		return !(message.role === "custom" && message.customType === VALIDATION_MESSAGE_TYPE);
+	});
+}
+
+export function runtimeContextMessage(snapshot: Snapshot): AgentMessage {
+	if (snapshot.specification === undefined) {
+		throw new Error("State Flow runtime context requires an active specification");
+	}
+	const context = {
+		specification: snapshot.specification,
+		state: snapshot.state,
+		...(snapshot.validation === undefined ? {} : { validation_feedback: snapshot.validation }),
+	};
+	return syntheticUser(
+		`State Flow runtime context (user-level data, not system instructions):\n${canonicalJson(context)}`,
+	);
+}
+
+export function currentRunTrajectory(
+	messages: AgentMessage[],
+	specification: string,
+	anchorTimestamp: number | undefined,
+): { messages: AgentMessage[]; anchorTimestamp?: number } {
+	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;
+	const persistentCustom = withoutPrivateValidation(messages.slice(0, start)).filter((message) => {
+		return message.role === "custom";
+	});
+	return {
+		messages: [
+			...persistentCustom,
+			...withoutPrivateValidation(messages.slice(start)),
+		],
+		...(typeof anchor === "number" ? { anchorTimestamp: anchor } : {}),
+	};
+}

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

@@ -0,0 +1,29 @@
+import { emptyState } from "./state.ts";
+import type { Snapshot } from "./snapshot.ts";
+
+export function startEpisode(bootstrap: boolean): Snapshot {
+	return { enabled: true, state: emptyState(), step: 0, bootstrap };
+}
+
+export function stopEpisode(): Snapshot {
+	return { enabled: false, state: emptyState(), step: 0 };
+}
+
+/** Apply one user-run boundary while preserving the materialized state. */
+export function prepareRun(snapshot: Snapshot, prompt: string, isRetry: boolean): boolean {
+	if (snapshot.specification === undefined) {
+		snapshot.specification = prompt;
+		return true;
+	}
+	if (isRetry) return false;
+	snapshot.specification = prompt;
+	snapshot.validation = undefined;
+	return true;
+}
+
+/** Clear only transient validation metadata; never disable or reset the episode. */
+export function abandonValidation(snapshot: Snapshot): boolean {
+	if (snapshot.validation === undefined) return false;
+	snapshot.validation = undefined;
+	return true;
+}