@llblab/pi-state-flow 0.26.0 → 0.26.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/BACKLOG.md CHANGED
@@ -1,34 +1,3 @@
1
1
  # Backlog
2
2
 
3
- The **0.25.5: Active Restoration Fence and Codemode Compaction** hotfix is published (exact-tag workflow, GitHub Release and npm commit verified) and bundled in published Pi Kit 0.27.6. **0.26.0: Stable Modes** is prepared and validated locally but not committed, tagged or published; Pi Kit sync follows its release. Outcomes belong in [CHANGELOG.md](CHANGELOG.md). This backlog retains installed-client gates and deferred decisions.
4
-
5
- ## Out of scope
6
-
7
- - Changing what a cascade deletes, including writes into an owned target made by the closing patch. That stays deleted by design and already appears in the receipt.
8
- - Nested `lazy_navigation` and intent-ownership warnings, validation or rejection. Authored missing-deletion hints do not change cascade behavior.
9
- - Any reduction of lifecycle state; the tagged-union question stays deferred.
10
-
11
- ## 0.26.0 acceptance
12
-
13
- - **Installed stable-mode smoke (operator-owned).** After separately authorized reload, use disposable storage to confirm `/tree` to an old step and reload keep current memory writable in Active and Passive; a fork copies the parent's current memory; unreadable current files show `active (blocked)` in terminal/Telegram, Passive retries and Off releases inference only. Local/native validation does not certify the installed client.
14
-
15
- ## 0.25.5 acceptance
16
-
17
- - **Installed restoration/compaction smoke (operator-owned).** After separately authorized reload, use disposable storage to confirm failed Active restoration blocks provider inference across tree/reload, explicit mode recovery remains available, and native Codemode values/deletions survive completed-history compaction. Local/native tests do not certify the installed client.
18
-
19
- ## Carried gates
20
-
21
- - **Installed 0.25.4 cleanup smoke (operator-owned).** After separately authorized installation/reload, use disposable storage to confirm missing-deletion hints, recursive empty-object cleanup, inherited fallback and preserved array slots. Local validation and publication do not certify installed clients.
22
- - **Installed 0.25.3 inspection smoke (operator-owned).** After separately authorized installation/reload, inspect a large nested field: real layout newlines/quotes, separate omitted-character notice and intact genuine JSON string escapes. Use disposable storage; local adapter tests do not certify installed Telegram clients.
23
- - **Installed 0.25.2 smoke (operator-owned).** Disposable store: confirm one patch argument block followed by changed/no-op acknowledgements, compact rows with `showSuccessfulPatches: false`, and visible rejected arguments/errors.
24
- - **Installed 0.25.1 smoke (operator-owned).** Disposable store: close an intent that owns a nested lazy key and confirm the receipt lists it under `cascaded`. May be combined with the open 0.25.0 smoke.
25
- - **Installed 0.22.0, 0.23.0, 0.24.0 and 0.25.0 smokes** remain open as recorded.
26
-
27
- ## Deferred (decision inputs, not commitments)
28
-
29
- - **Closing-patch losses.** In real sessions, look for closing patches that write into a target the same patch cascades. If frequent, revisit the closing sentence in the protocol, not the mechanism.
30
- - Convention uptake, behavioural evaluation, lifecycle real-use measurement, lifecycle tagged union, Skill compilation fidelity and compaction threshold carry over unchanged from the 0.25.0 backlog.
31
-
32
- ## Release boundary
33
-
34
- Installation/reload requires separate authorization and disposable storage. Local validation and publication do not certify installed clients.
3
+ No open work.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  > Each release keeps at most 8 outcome records of at most 512 characters.
4
4
 
5
+ ## 0.26.2: Automatic Response Guidance
6
+
7
+ - `Response ownership`: Active/bootstrap and Passive prompts explicitly forbid patching `response`; the `patch_state` guidelines forbid it in Global, CWD and Session, including clearing/deleting it, and explain that Active mode captures the final answer automatically. Runtime validation and answer capture are unchanged. No migration or configuration change is required.
8
+
9
+ ## 0.26.1: Consistent Temporary Paths and Mode Colors
10
+
11
+ - `Telegram mode colors`: The selected mode uses 🟣 Off, 🟡 Passive or 🟢 Active; unselected options remain ⚫️. Mode behavior and callbacks are unchanged.
12
+ - `Diagnostic directory`: New diagnostics and Git push failure logs use `<agentDir>/tmp/pi-state-flow/logs.jsonl`, matching the Pi extension temporary-directory naming convention. Older `tmp/state-flow` logs are left untouched; canonical `state-flow/` memory storage is unchanged.
13
+
5
14
  ## 0.26.0: Stable Modes
6
15
 
7
16
  - `Step-independent memory`: Memory no longer depends on the Pi step. Startup, reload, resume and `/tree` attach the current same-session JSON state; native checkpoints supply only mode and run lifecycle. Old or expired branch points never block or rewind memory. Forks copy the parent's current memory. Past values remain readable through `read_state` offsets within retained history.
@@ -15,7 +15,7 @@ import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, SettledTurnBack
15
15
  import { projectRecentTransitionsWithLimit } from "./history.js";
16
16
  import { isObject, presentationJson, sameJson } from "./json.js";
17
17
  import { StateFlowDiagnosticWriter, stateFlowLogPath } from "./logging.js";
18
- import { assistantToolCallCount, conciseDiagnostic, diagnosticText, finalizedAssistantResponse, formatPatchStateArguments, PASSIVE_MEMORY_PROTOCOL, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.js";
18
+ import { assistantToolCallCount, conciseDiagnostic, diagnosticText, finalizedAssistantResponse, formatPatchStateArguments, PASSIVE_MEMORY_PROTOCOL, RESPONSE_PATCH_GUIDELINE, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.js";
19
19
  import { OwnedOperationSlot, RenewableLifetime } from "./operation.js";
20
20
  import { readProjectedState, readStatePath } from "./query.js";
21
21
  import { selectedBoundaryFailure, selectRetainedCheckpoint, waitForRecovery } from "./recovery.js";
@@ -728,6 +728,7 @@ export default function stateFlowExtension(pi, options = {}) {
728
728
  description: "The sole State Flow semantic mutation protocol. Supply one or more global, cwd, or session patches; all supplied scopes commit atomically. This call must be the only State Flow barrier in its assistant response. Deleting an intent also deletes same-scope working/lazy keys its {\"$ref\"} values own unless another intent refs them. Name keys in ASCII ([A-Za-z_$][A-Za-z0-9_$-]*) so read paths and refs resolve; values may use any language.",
729
729
  promptSnippet: "Atomically patch one or more global/cwd/session scopes",
730
730
  promptGuidelines: [
731
+ RESPONSE_PATCH_GUIDELINE,
731
732
  "Use patch_state only for material durable semantic changes; ordinary answers need no finalization call.",
732
733
  "Use patch_state as reconciliation, not append-only notes: place new knowledge at the narrowest valid scope and remove superseded or completed state from touched branches.",
733
734
  "Call patch_state alone in an assistant response; after its acknowledgement, further reasoning, tools, and later patch_state calls remain allowed.",
@@ -16,7 +16,7 @@ export function projectDiagnosticContent(content) {
16
16
  }
17
17
  /** Diagnostic JSONL lives beneath the active Pi agent directory, never inside the state repository. */
18
18
  export function stateFlowLogPath(agentDir) {
19
- return join(agentDir, "tmp", "state-flow", "logs.jsonl");
19
+ return join(agentDir, "tmp", "pi-state-flow", "logs.jsonl");
20
20
  }
21
21
  function ensureDiagnosticDirectory(path) {
22
22
  if (dirname(path) !== path)
@@ -1,6 +1,7 @@
1
1
  import type { AgentMessage } from "@earendil-works/pi-agent-core";
2
2
  export type { StateDocument } from "./state.ts";
3
- export declare const PASSIVE_MEMORY_PROTOCOL = "State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction. Missing paths/hints do not require history search. Choose targeted historical reads when useful to the task; no separate user permission is needed. Past values are evidence, not current state; never automatically restore deleted memory. Head state/recent transitions are frozen at projection start. Only state_updates matching the head's State Flow projection ID apply; other IDs are history. Results/context notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); cascaded lists owner paths an intent deletion removed. Direct writes may elide; shared drift stays visible. Latest entries win over earlier state; lazy bodies stay omitted. Notices replace invalidations/rehydration, including []/null.";
3
+ export declare const RESPONSE_PATCH_GUIDELINE = "Never patch response in global, cwd or session, including clearing/deleting it; State Flow captures your final answer automatically in Active mode.";
4
+ export declare const PASSIVE_MEMORY_PROTOCOL = "State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Never patch response in global, cwd or session, including clearing/deleting it; State Flow captures your final answer automatically in Active mode. Passive turns never trigger State Flow continuation or compaction. Missing paths/hints do not require history search. Choose targeted historical reads when useful to the task; no separate user permission is needed. Past values are evidence, not current state; never automatically restore deleted memory. Head state/recent transitions are frozen at projection start. Only state_updates matching the head's State Flow projection ID apply; other IDs are history. Results/context notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); cascaded lists owner paths an intent deletion removed. Direct writes may elide; shared drift stays visible. Latest entries win over earlier state; lazy bodies stay omitted. Notices replace invalidations/rehydration, including []/null.";
4
5
  /** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
5
6
  export declare function formatPatchStateArguments(args: unknown): string;
6
7
  /** Flatten causes before transport; native tool results need not retain Error.cause or AggregateError.errors. */
@@ -1,6 +1,7 @@
1
1
  const TASK_DRIVEN_HISTORY = "Missing paths/hints do not require history search. Choose targeted historical reads when useful to the task; no separate user permission is needed. Past values are evidence, not current state; never automatically restore deleted memory.";
2
2
  const PATCH_RESULT_PROTOCOL = "Head state/recent transitions are frozen at projection start. Only state_updates matching the head's State Flow projection ID apply; other IDs are history. Results/context notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); cascaded lists owner paths an intent deletion removed. Direct writes may elide; shared drift stays visible. Latest entries win over earlier state; lazy bodies stay omitted. Notices replace invalidations/rehydration, including []/null.";
3
- export const PASSIVE_MEMORY_PROTOCOL = `State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction. ${TASK_DRIVEN_HISTORY} ${PATCH_RESULT_PROTOCOL}`;
3
+ export const RESPONSE_PATCH_GUIDELINE = "Never patch response in global, cwd or session, including clearing/deleting it; State Flow captures your final answer automatically in Active mode.";
4
+ export const PASSIVE_MEMORY_PROTOCOL = `State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. ${RESPONSE_PATCH_GUIDELINE} Passive turns never trigger State Flow continuation or compaction. ${TASK_DRIVEN_HISTORY} ${PATCH_RESULT_PROTOCOL}`;
4
5
  const PATCH_DISPLAY_SECTION_KEYS = new Set(["global", "cwd", "session", "intents", "contract", "working", "artifacts", "response", "lazy"]);
5
6
  /** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
6
7
  export function formatPatchStateArguments(args) {
@@ -88,7 +89,7 @@ ${bootstrapProtocol}STATE:
88
89
  - contract: durable requirements, decisions, rejections, interfaces.
89
90
  - working: temporary context of intents: facts, validation, failures, domain state.
90
91
  - artifacts: source-path routing metadata; descriptions do not imply body acquisition.
91
- - response: previous answer; runtime stores the exact accepted answer at turn_end (empty="").
92
+ - response: read-only prior answer; never patch it in any scope. Auto-stored at turn_end (empty="").
92
93
  - lazy: retrieve explicitly.
93
94
 
94
95
  SCOPES: Use the narrowest scope: session=branch/run continuation by default; cwd=reusable project truth; global=established cross-project/user/environment knowledge.
@@ -26,7 +26,7 @@ export function formatStateFlowSectionLabel(snapshot) {
26
26
  }
27
27
  export const STATE_FLOW_MODES = ["off", "passive", "active"];
28
28
  const STATE_FLOW_MODE_LABELS = { off: "Off", passive: "Passive", active: "Active" };
29
- const STATE_FLOW_SELECTED_MARKERS = { off: "🟡", passive: "🟣", active: "🟢" };
29
+ const STATE_FLOW_SELECTED_MARKERS = { off: "🟣", passive: "🟡", active: "🟢" };
30
30
  function isStateFlowModeAction(value) {
31
31
  return STATE_FLOW_MODES.includes(value);
32
32
  }
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.26.0",
3
+ "version": "0.26.2",
4
4
  "license": "MIT",
5
5
  "private": false,
6
6
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
@@ -59,7 +59,7 @@ This is the source-bound **paragraph-to-owner parity map** for the 8,141-word pr
59
59
  - L43 terminal status and read-only scope inspection → [status and controls](usage.md#status-and-controls), [observability](architecture.md#observability).
60
60
  - L48 system section, context refresh and foreign prompt precedence → [Pi lifecycle](architecture.md#pi-lifecycle), [host context compatibility](compatibility.md#context-tools-and-provider-input).
61
61
  - L50 extension-agnostic core and Telegram controls/receipts → [composition](architecture.md#composition), [observability](architecture.md#observability), [Telegram compatibility](compatibility.md#telegram-adapter).
62
- - L52 tag release authority and version alignment → [release workflow](../.github/workflows/release.yml), [release boundary](../BACKLOG.md#release-boundary). Retain the durable no-token constraint in compact `AGENTS.md` until a permanent developer contract owns it.
62
+ - L52 tag release authority and version alignment → [release workflow](../.github/workflows/release.yml), [release boundary](../AGENTS.md#delivery-discipline). Retain the durable no-token constraint in compact `AGENTS.md` until a permanent developer contract owns it.
63
63
  - L53 opt-in benchmark location and source identity → [benchmark guide](../benchmarks/README.md), [performance validation](performance.md#validation-and-reporting).
64
64
  - L54 provider callback completion witness → [temporal acceptance](temporal-acceptance.md#required-properties-and-witnesses), [integration tests](../tests/integration.test.ts).
65
65
  - L55 awaited fixture handlers and withdrawal witness → [temporal acceptance](temporal-acceptance.md#required-properties-and-witnesses), [extension tests](../tests/extension.test.ts).
package/docs/usage.md CHANGED
@@ -144,7 +144,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
144
144
  - Active initializes missing storage when safe.
145
145
  - Passive reads existing memory without publishing; its first explicit patch may initialize absent storage without starting an episode or compaction.
146
146
  - Off exposes neither memory tools nor State Flow context.
147
- - `logging`: Defaults to `false`. When enabled, rejected patch executions, active barrier blocks, preparation failures and accepted-answer reconciliation failures are recorded locally at `tmp/state-flow/logs.jsonl` beneath the agent directory. Asynchronous Git push failures are recorded there even when this setting is off.
147
+ - `logging`: Defaults to `false`. When enabled, rejected patch executions, active barrier blocks, preparation failures and accepted-answer reconciliation failures are recorded locally at `tmp/pi-state-flow/logs.jsonl` beneath the agent directory. Older `tmp/state-flow` logs are left untouched and are not migrated. Asynchronous Git push failures are recorded there even when this setting is off.
148
148
  - `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, `patch_state` rows show pretty-printed JSON arguments once in the call, with blank lines between adjacent memory sections; the result shows the acceptance or no-op acknowledgement, never a second patch. Set it to `false` to hide call arguments and keep the compact acknowledgement. Rejected calls retain their arguments and error acknowledgement; State Flow adds no private validation turn.
149
149
  - `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It counts accepted semantic transitions, **not elapsed time or conversation length**, and bounds materialized-history and scope patch-history offsets.
150
150
  - Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window become unavailable.
@@ -208,7 +208,7 @@ When `pi-telegram` is available, its main-menu section shows `State Flow: active
208
208
 
209
209
  **Mode controls:**
210
210
 
211
- - A horizontal radio row presents `Off | Passive | Active`. The selected option uses 🟡, 🟣 or 🟢 respectively; each inactive option uses ⚫️.
211
+ - A horizontal radio row presents `Off | Passive | Active`. The selected option uses 🟣, 🟡 or 🟢 respectively; each inactive option uses ⚫️.
212
212
  - Telegram Active requested during a run waits for settlement; Passive and Off apply immediately.
213
213
  - Ordinary successful controls add no redundant mode receipt; diagnostic outcomes stay visible.
214
214
  - Off exposes neither tool nor State Flow model context.
package/lib/extension.ts CHANGED
@@ -22,7 +22,7 @@ import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, SettledTurnBack
22
22
  import { projectRecentTransitionsWithLimit } from "./history.ts";
23
23
  import { isObject, presentationJson, sameJson } from "./json.ts";
24
24
  import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
25
- import { assistantToolCallCount, conciseDiagnostic, diagnosticText, finalizedAssistantResponse, formatPatchStateArguments, PASSIVE_MEMORY_PROTOCOL, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.ts";
25
+ import { assistantToolCallCount, conciseDiagnostic, diagnosticText, finalizedAssistantResponse, formatPatchStateArguments, PASSIVE_MEMORY_PROTOCOL, RESPONSE_PATCH_GUIDELINE, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.ts";
26
26
  import { OwnedOperationSlot, RenewableLifetime, type OwnedOperation } from "./operation.ts";
27
27
  import { readProjectedState, readStatePath } from "./query.ts";
28
28
  import { selectedBoundaryFailure, selectRetainedCheckpoint, waitForRecovery } from "./recovery.ts";
@@ -746,6 +746,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
746
746
  description: "The sole State Flow semantic mutation protocol. Supply one or more global, cwd, or session patches; all supplied scopes commit atomically. This call must be the only State Flow barrier in its assistant response. Deleting an intent also deletes same-scope working/lazy keys its {\"$ref\"} values own unless another intent refs them. Name keys in ASCII ([A-Za-z_$][A-Za-z0-9_$-]*) so read paths and refs resolve; values may use any language.",
747
747
  promptSnippet: "Atomically patch one or more global/cwd/session scopes",
748
748
  promptGuidelines: [
749
+ RESPONSE_PATCH_GUIDELINE,
749
750
  "Use patch_state only for material durable semantic changes; ordinary answers need no finalization call.",
750
751
  "Use patch_state as reconciliation, not append-only notes: place new knowledge at the narrowest valid scope and remove superseded or completed state from touched branches.",
751
752
  "Call patch_state alone in an assistant response; after its acknowledgement, further reasoning, tools, and later patch_state calls remain allowed.",
package/lib/logging.ts CHANGED
@@ -38,7 +38,7 @@ export function projectDiagnosticContent(content: unknown): StateFlowDiagnosticB
38
38
 
39
39
  /** Diagnostic JSONL lives beneath the active Pi agent directory, never inside the state repository. */
40
40
  export function stateFlowLogPath(agentDir: string): string {
41
- return join(agentDir, "tmp", "state-flow", "logs.jsonl");
41
+ return join(agentDir, "tmp", "pi-state-flow", "logs.jsonl");
42
42
  }
43
43
 
44
44
  function ensureDiagnosticDirectory(path: string): void {
package/lib/protocol.ts CHANGED
@@ -6,7 +6,9 @@ const TASK_DRIVEN_HISTORY = "Missing paths/hints do not require history search.
6
6
 
7
7
  const PATCH_RESULT_PROTOCOL = "Head state/recent transitions are frozen at projection start. Only state_updates matching the head's State Flow projection ID apply; other IDs are history. Results/context notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); cascaded lists owner paths an intent deletion removed. Direct writes may elide; shared drift stays visible. Latest entries win over earlier state; lazy bodies stay omitted. Notices replace invalidations/rehydration, including []/null.";
8
8
 
9
- export const PASSIVE_MEMORY_PROTOCOL = `State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction. ${TASK_DRIVEN_HISTORY} ${PATCH_RESULT_PROTOCOL}`;
9
+ export const RESPONSE_PATCH_GUIDELINE = "Never patch response in global, cwd or session, including clearing/deleting it; State Flow captures your final answer automatically in Active mode.";
10
+
11
+ export const PASSIVE_MEMORY_PROTOCOL = `State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. ${RESPONSE_PATCH_GUIDELINE} Passive turns never trigger State Flow continuation or compaction. ${TASK_DRIVEN_HISTORY} ${PATCH_RESULT_PROTOCOL}`;
10
12
 
11
13
  const PATCH_DISPLAY_SECTION_KEYS = new Set(["global", "cwd", "session", "intents", "contract", "working", "artifacts", "response", "lazy"]);
12
14
 
@@ -92,7 +94,7 @@ ${bootstrapProtocol}STATE:
92
94
  - contract: durable requirements, decisions, rejections, interfaces.
93
95
  - working: temporary context of intents: facts, validation, failures, domain state.
94
96
  - artifacts: source-path routing metadata; descriptions do not imply body acquisition.
95
- - response: previous answer; runtime stores the exact accepted answer at turn_end (empty="").
97
+ - response: read-only prior answer; never patch it in any scope. Auto-stored at turn_end (empty="").
96
98
  - lazy: retrieve explicitly.
97
99
 
98
100
  SCOPES: Use the narrowest scope: session=branch/run continuation by default; cwd=reusable project truth; global=established cross-project/user/environment knowledge.
package/lib/telegram.ts CHANGED
@@ -139,7 +139,7 @@ export function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot)
139
139
 
140
140
  export const STATE_FLOW_MODES = ["off", "passive", "active"] as const satisfies readonly StateFlowMode[];
141
141
  const STATE_FLOW_MODE_LABELS: Record<StateFlowMode, string> = { off: "Off", passive: "Passive", active: "Active" };
142
- const STATE_FLOW_SELECTED_MARKERS: Record<StateFlowMode, string> = { off: "🟡", passive: "🟣", active: "🟢" };
142
+ const STATE_FLOW_SELECTED_MARKERS: Record<StateFlowMode, string> = { off: "🟣", passive: "🟡", active: "🟢" };
143
143
 
144
144
  function isStateFlowModeAction(value: string): value is StateFlowMode {
145
145
  return (STATE_FLOW_MODES as readonly string[]).includes(value);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.26.0",
3
+ "version": "0.26.2",
4
4
  "license": "MIT",
5
5
  "private": false,
6
6
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",