@llblab/pi-state-flow 0.17.4 → 0.18.1
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/AGENTS.md +7 -7
- package/CHANGELOG.md +15 -0
- package/README.md +5 -5
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/lib/durable.d.ts +1 -0
- package/dist/lib/durable.js +7 -3
- package/dist/lib/extension.js +52 -11
- package/dist/lib/git.d.ts +10 -0
- package/dist/lib/git.js +122 -1
- package/dist/lib/logging.d.ts +3 -0
- package/dist/lib/logging.js +33 -7
- package/dist/lib/protocol.js +2 -5
- package/dist/lib/runtime.d.ts +2 -0
- package/dist/lib/runtime.js +11 -0
- package/dist/lib/status.d.ts +4 -2
- package/dist/lib/status.js +8 -2
- package/dist/lib/telegram.d.ts +6 -1
- package/dist/lib/telegram.js +19 -6
- package/dist/lib/temporal.d.ts +5 -0
- package/dist/lib/temporal.js +27 -3
- package/dist/lib/transition.js +2 -2
- package/dist/package.json +1 -1
- package/docs/architecture.md +10 -8
- package/docs/compatibility.md +1 -1
- package/docs/lazy-state.md +2 -2
- package/docs/performance.md +10 -2
- package/docs/temporal-acceptance.md +4 -3
- package/docs/usage.md +7 -7
- package/index.ts +2 -2
- package/lib/durable.ts +8 -3
- package/lib/extension.ts +50 -9
- package/lib/git.ts +106 -1
- package/lib/logging.ts +31 -6
- package/lib/protocol.ts +2 -4
- package/lib/runtime.ts +11 -0
- package/lib/status.ts +10 -4
- package/lib/telegram.ts +23 -6
- package/lib/temporal.ts +29 -3
- package/lib/transition.ts +2 -2
- package/package.json +1 -1
package/docs/usage.md
CHANGED
|
@@ -46,7 +46,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
|
|
|
46
46
|
- `autoStart`: Defaults to `false`. When `true`, genuinely new sessions use the same initialization as explicit Start, including fresh CWDs.
|
|
47
47
|
- `passiveBootstrap`: Defaults to `true`. Projects existing effective durable memory into ordinary model context without creating scopes, publishing, or starting an episode.
|
|
48
48
|
- `passiveTools`: Defaults to `true`. Exposes `read_state` and `patch_state` outside active episodes. Reads remain side-effect free; the first explicit patch may initialize absent canonical storage but never converts predecessor formats or enables an episode or State Flow compaction.
|
|
49
|
-
- `logging`: Defaults to `false`. When enabled, records rejected patches and accepted-answer reconciliation failures locally at `tmp/state-flow/logs.jsonl` beneath the agent directory.
|
|
49
|
+
- `logging`: Defaults to `false`. When enabled, records rejected patches and accepted-answer reconciliation failures locally at `tmp/state-flow/logs.jsonl` beneath the agent directory. Asynchronous Git push failures are recorded there even when this setting is off.
|
|
50
50
|
- `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, successful `patch_state` rows show only the applied pretty-printed JSON arguments, with blank lines between adjacent memory sections; set it to `false` to keep only the compact summary. Rejected calls still use ordinary error rendering; State Flow adds no private validation turn.
|
|
51
51
|
- `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It bounds materialized-history and scope patch-history offsets. Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window are unavailable. Zero retains only current checkpoints. Raising the limit affects only future retention and cannot reconstruct discarded history.
|
|
52
52
|
|
|
@@ -56,7 +56,7 @@ Settings are read once at extension load. After editing, use `/reload` or restar
|
|
|
56
56
|
|
|
57
57
|
### Diagnostic logging and privacy
|
|
58
58
|
|
|
59
|
-
Rejected-call records may contain exact attempted arguments and useful draft text, plus the error category and tool/call identity. Successful patches are not logged; reasoning bodies are excluded. Logs are not semantic state, scope metadata, Pi checkpoints, or publication input. If the log path overlaps a custom state repository, capture fails closed instead of committing it. A logging failure changes no accepted state and produces at most one local warning.
|
|
59
|
+
Rejected-call records may contain exact attempted arguments and useful draft text, plus the error category and tool/call identity. Asynchronous push failures retain the available redacted Git error there regardless of `logging`; interactive warnings stay short and appear once per failure streak, then reset on success. If logging the push failure is unavailable, one warning exposes the available detail instead. Successful patches are not logged; reasoning bodies are excluded. Logs are not semantic state, scope metadata, Pi checkpoints, or publication input. If the log path overlaps a custom state repository, capture fails closed instead of committing it. A logging failure changes no accepted state and produces at most one local warning.
|
|
60
60
|
|
|
61
61
|
Logs remain local unless you move them; rotation/deletion is operator-owned. Treat them and state files as private. Removing a secret from current state does not erase older offsets, Git history, native sessions, or remote copies.
|
|
62
62
|
|
|
@@ -64,14 +64,14 @@ Logs remain local unless you move them; rotation/deletion is operator-owned. Tre
|
|
|
64
64
|
|
|
65
65
|
`/state-flow-status` separates runtime configuration/metadata from semantic state. It reports:
|
|
66
66
|
|
|
67
|
-
- Selected CWD/session keys, step, temporal head, recovery failures, and available hot history.
|
|
67
|
+
- Selected CWD/session keys, internal step, independent scope revisions, temporal head, recovery failures, and available hot history.
|
|
68
68
|
- Per-scope retained patch tails and artifact counts, plus one JSON representation of effective global → CWD → session memory. Individual scope JSON is available through `read_state`, not duplicated in status.
|
|
69
69
|
- Already-known runtime hints or pending artifact invalidations; status does not discover or validate sources.
|
|
70
70
|
- Memory-bearing scopes. Promotion-shaped values receive no special interpretation.
|
|
71
71
|
|
|
72
72
|
Tail counts are not history depth: inherited records may predate the active origin. Failed inspection reports unavailable evidence, not invented empty state. Status is observational: it does not read source files, calculate fingerprints, create invalidations, or mutate semantic state.
|
|
73
73
|
|
|
74
|
-
The terminal indicator is `state-flow
|
|
74
|
+
The terminal indicator is `state-flow G15/C8/S31` only in active mode. Global, CWD and Session own independent semantic revisions; one atomic transition advances each materially changed scope once, including session-only response reconciliation. Effective has no scalar counter and uses the `G#/C#/S#` revision vector. When `pi-telegram` is available, its main-menu section shows that vector only while active and `State Flow: off` while passive. Requested owner-scope Rich snapshots show `#revision`; Effective shows the vector. Telegram inspection may lazily load or refresh live shared state from other instances even when passive model tools are disabled, but it does not initialize, publish, or advance storage. Start requested during a run waits for settlement; Stop currently applies immediately. The adapter is optional and the Pi commands remain available without it. Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
|
|
75
75
|
|
|
76
76
|
## Storage and recovery
|
|
77
77
|
|
|
@@ -92,19 +92,19 @@ Exactly one surviving pair member is corruption and fails closed. Present malfor
|
|
|
92
92
|
|
|
93
93
|
After a selected-boundary failure, configured passive access may still expose current global/CWD memory, but it never grants access to the unavailable session layer or permission to publish an empty replacement. Session reads, every `patch_state`, and Stop refuse without changing canonical files or appending substitute checkpoints. Status retains the restoration error even when shared reads work. Start retries the original selection; repair its missing or invalid evidence, select a still-retained boundary, or use a genuinely new Pi session instead of forcing a reset.
|
|
94
94
|
|
|
95
|
-
Missing artifact provenance inside an otherwise complete scope `meta.json` means compilation evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. An unavailable registered source path does not prove that durable artifact routing was deleted, and external files are never created. State Flow has no durable push queue or publication-worker lease. See the complete [filesystem recovery contract](filesystem-recovery.md).
|
|
95
|
+
Missing artifact provenance inside an otherwise complete scope `meta.json` means compilation evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. An unavailable registered source path does not prove that durable artifact routing was deleted, and external files are never created. State Flow has no durable push queue or publication-worker lease; failed replication is attempted again only after a later accepted turn. See the complete [filesystem recovery contract](filesystem-recovery.md).
|
|
96
96
|
|
|
97
97
|
### Canonical files and optional Git backup
|
|
98
98
|
|
|
99
99
|
Canonical scope/runtime files own current materialization and retained hot history regardless of Git availability. Pi checkpoints identify a retained semantic boundary, not a Git commit or arbitrary historical snapshot. Restart and branch restoration fail closed when the selected boundary has expired rather than substituting newer files as the selected past.
|
|
100
100
|
|
|
101
|
-
After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available.
|
|
101
|
+
After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. If the attached branch has an explicitly configured remote/ref, State Flow starts a non-interactive asynchronous push of the exact current commit without force. Settlement does not wait for the network. Within one Pi process, an in-flight push per repository skips overlapping attempts; a later accepted turn retries the latest backup without a durable queue. Session shutdown waits for that repository's in-flight push to close or time out, suppressing push-failure reporting after shutdown begins. Commit or push failure is diagnostic-only; repeated push failures warn once per failure streak and remain locally diagnosable. Git availability never changes semantic authority, step, or retained lineage.
|
|
102
102
|
|
|
103
103
|
### Moving a store and the 0.17 format boundary
|
|
104
104
|
|
|
105
105
|
An SDK `repositoryRoot` override or a different `PI_CODING_AGENT_DIR` selects a location; it does not relocate existing state or retained history. Copy the complete canonical store while all writers are quiescent, or use a genuinely new Pi session for an independent store. Copying only current checkpoints without their tails and metadata cannot preserve retained boundaries.
|
|
106
106
|
|
|
107
|
-
|
|
107
|
+
Starting with 0.17, State Flow accepts only its canonical checkpoint/tail, temporal metadata, and separate session config/runtime contract; that boundary still applies to current versions. A canonical 0.17 scope written before independent revisions remains readable: its initial counter uses only the retained semantic tail and is persisted in metadata version 2 on the next owned write, without inventing folded ancestry. Version 1 remains readable; older writers refuse version 2 through the existing provenance-version fence, so cooperating instances should upgrade together. Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoint envelopes fail as unsupported without rewriting existing bytes. State Flow does not provide an in-place converter; external conversion or a fresh store is operator-owned.
|
|
108
108
|
|
|
109
109
|
### Conflicts and interrupted publication
|
|
110
110
|
|
package/index.ts
CHANGED
|
@@ -71,7 +71,7 @@ export {
|
|
|
71
71
|
temporalStateFileUpdates, type ScopeStreamSources, type TemporalScopePaths
|
|
72
72
|
} from "./lib/durable.ts";
|
|
73
73
|
export { default, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
|
|
74
|
-
export { backupCurrentStateFlowFiles } from "./lib/git.ts";
|
|
74
|
+
export { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./lib/git.ts";
|
|
75
75
|
export {
|
|
76
76
|
createAcceptedTransition,
|
|
77
77
|
DEFAULT_HISTORY_LIMIT,
|
|
@@ -139,5 +139,5 @@ export {
|
|
|
139
139
|
type StateFlowTelegramSnapshot,
|
|
140
140
|
type StateFlowTelegramView
|
|
141
141
|
} from "./lib/telegram.ts";
|
|
142
|
-
export { advanceTemporalState, readTemporalState, type TemporalState } from "./lib/temporal.ts";
|
|
142
|
+
export { advanceTemporalState, readTemporalState, temporalScopeRevisions, type ScopeRevisions, type TemporalState } from "./lib/temporal.ts";
|
|
143
143
|
export { parseStateReadPath, readStatePath, type StateReadQuery, type StateReadResult } from "./lib/query.ts";
|
package/lib/durable.ts
CHANGED
|
@@ -50,6 +50,7 @@ export function hasCwdMaterialization(cwd: string, repositoryRoot: string): bool
|
|
|
50
50
|
}
|
|
51
51
|
|
|
52
52
|
export interface ScopeTemporalMetadata {
|
|
53
|
+
revision: number;
|
|
53
54
|
checkpoint: ScopeStream["checkpoint"]["through"];
|
|
54
55
|
patches: ScopeStream["patches"][number]["transition"][];
|
|
55
56
|
}
|
|
@@ -68,6 +69,7 @@ export function serializeScopeStream(stream: ScopeStream, scope: StateScope, cwd
|
|
|
68
69
|
checkpoint: `${canonicalJson(stream.checkpoint.state)}\n`,
|
|
69
70
|
patches: stream.patches.map((record) => `${canonicalJson(record.patch)}\n`).join(""),
|
|
70
71
|
temporal: {
|
|
72
|
+
revision: stream.revision,
|
|
71
73
|
checkpoint: structuredClone(stream.checkpoint.through),
|
|
72
74
|
patches: stream.patches.map((record) => structuredClone(record.transition)),
|
|
73
75
|
},
|
|
@@ -124,6 +126,9 @@ export function classifyScopeStream(
|
|
|
124
126
|
const boundaries = temporal.patches;
|
|
125
127
|
if (boundaries.length !== patches.length) throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
|
|
126
128
|
const stream = {
|
|
129
|
+
// 0.17.4 and earlier did not persist scope revisions. Credit only their still-retained
|
|
130
|
+
// semantic tail; discarded ancestry cannot be reconstructed without inventing history.
|
|
131
|
+
revision: temporal.revision === undefined ? patches.length : temporal.revision,
|
|
127
132
|
checkpoint: { through: temporal.checkpoint, state: checkpoint },
|
|
128
133
|
patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
|
|
129
134
|
};
|
|
@@ -219,7 +224,7 @@ export function serializeScopeMetadata(
|
|
|
219
224
|
const sources = serializeScopeStream(stream, scope, cwdIdentity);
|
|
220
225
|
const value = {
|
|
221
226
|
...existing,
|
|
222
|
-
version:
|
|
227
|
+
version: 2,
|
|
223
228
|
...(registry === undefined ? {} : { artifacts: serializeArtifactProvenanceRegistry(registry) }),
|
|
224
229
|
temporal: sources.temporal,
|
|
225
230
|
...(scope === "cwd" ? { owner: { cwd: resolve(cwdIdentity!) } } : {}),
|
|
@@ -229,7 +234,7 @@ export function serializeScopeMetadata(
|
|
|
229
234
|
|
|
230
235
|
/** Compatibility serializer retained for metadata-only callers. */
|
|
231
236
|
export function serializeScopeProvenance(registry: Readonly<ArtifactProvenanceRegistry>): string {
|
|
232
|
-
return `${canonicalJson({ version:
|
|
237
|
+
return `${canonicalJson({ version: 2, artifacts: serializeArtifactProvenanceRegistry(registry) })}\n`;
|
|
233
238
|
}
|
|
234
239
|
|
|
235
240
|
function parseMetadataDocument(source: string | undefined, label: string): Record<string, unknown> {
|
|
@@ -245,7 +250,7 @@ function parseMetadataDocument(source: string | undefined, label: string): Recor
|
|
|
245
250
|
export function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry {
|
|
246
251
|
const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
|
|
247
252
|
if (Object.keys(value).length === 0) return {};
|
|
248
|
-
if (value.version !== 1) throw new Error(`Invalid State Flow provenance document: ${path}`);
|
|
253
|
+
if (value.version !== 1 && value.version !== 2) throw new Error(`Invalid State Flow provenance document: ${path}`);
|
|
249
254
|
if (!Object.hasOwn(value, "artifacts")) return {};
|
|
250
255
|
return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
|
|
251
256
|
}
|
package/lib/extension.ts
CHANGED
|
@@ -25,7 +25,7 @@ import {
|
|
|
25
25
|
type SessionAddress,
|
|
26
26
|
} from "./durable.ts";
|
|
27
27
|
import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
|
|
28
|
-
import { backupCurrentStateFlowFiles } from "./git.ts";
|
|
28
|
+
import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, startStateFlowBackupPush } from "./git.ts";
|
|
29
29
|
import { projectRecentTransitionsWithLimit } from "./history.ts";
|
|
30
30
|
import { isObject, presentationJson, sameJson, type JsonObject } from "./json.ts";
|
|
31
31
|
import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
|
|
@@ -40,6 +40,7 @@ import { emptySnapshot, migrationFailure, type Snapshot } from "./snapshot.ts";
|
|
|
40
40
|
import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState, type ScopedStates, type StateScope } from "./state.ts";
|
|
41
41
|
import { compactStatus, detailedStatus, STATUS_KEY, type StatusDiagnostics } from "./status.ts";
|
|
42
42
|
import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader, type StateFlowTelegramScope } from "./telegram.ts";
|
|
43
|
+
import { temporalScopeRevisions, type ScopeRevisions } from "./temporal.ts";
|
|
43
44
|
import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, type StagedScopedTransition } from "./transition.ts";
|
|
44
45
|
|
|
45
46
|
export interface StateFlowExtensionOptions {
|
|
@@ -85,8 +86,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
85
86
|
let activeContext: ExtensionContext | undefined;
|
|
86
87
|
let rehydrationPhase: RehydrationPhase | undefined;
|
|
87
88
|
const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
|
|
88
|
-
const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) =>
|
|
89
|
+
const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => notifyActiveContext(message));
|
|
89
90
|
let backupPending = false;
|
|
91
|
+
let shuttingDown = false;
|
|
92
|
+
let pushFailureNotified = false;
|
|
90
93
|
const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
|
|
91
94
|
? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
|
|
92
95
|
: undefined);
|
|
@@ -100,6 +103,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
100
103
|
return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
|
|
101
104
|
}
|
|
102
105
|
|
|
106
|
+
function notifyActiveContext(message: string): void {
|
|
107
|
+
try {
|
|
108
|
+
activeContext?.ui.notify(message, "warning");
|
|
109
|
+
} catch {
|
|
110
|
+
// An asynchronous push attempt can outlive the Pi context that launched it.
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
103
114
|
function createRuntime(ctx: ExtensionContext): TemporalRuntime {
|
|
104
115
|
return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot, undefined, config.historyLimit);
|
|
105
116
|
}
|
|
@@ -134,8 +145,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
134
145
|
if ("boundary" in checkpoint) branchStartsWithoutRuntime = false;
|
|
135
146
|
}
|
|
136
147
|
|
|
148
|
+
function scopeRevisions(): ScopeRevisions {
|
|
149
|
+
return runtime?.view
|
|
150
|
+
? temporalScopeRevisions(runtime.view)
|
|
151
|
+
: { global: 0, cwd: 0, session: 0 };
|
|
152
|
+
}
|
|
153
|
+
|
|
137
154
|
function updateUi(ctx: ExtensionContext): void {
|
|
138
|
-
ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, (color, text) => ctx.ui.theme.fg(color, text)));
|
|
155
|
+
ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, scopeRevisions(), (color, text) => ctx.ui.theme.fg(color, text)));
|
|
139
156
|
}
|
|
140
157
|
|
|
141
158
|
function clearRunTransient(): void {
|
|
@@ -202,6 +219,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
202
219
|
if (Object.keys(removals).length > 0) {
|
|
203
220
|
const stage = stageAtomicScopePatches(scopeStates, removals, [], runtime.causalBasis());
|
|
204
221
|
commitStage(stage, ctx, false);
|
|
222
|
+
updateUi(ctx);
|
|
205
223
|
}
|
|
206
224
|
refreshArtifactHints();
|
|
207
225
|
}
|
|
@@ -217,10 +235,13 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
217
235
|
|
|
218
236
|
function refreshTelegramStateView(scope: StateFlowTelegramScope): void {
|
|
219
237
|
if (scope === "session" || scope === "effective") assertSelectedBranchAvailable();
|
|
220
|
-
if (runtime?.view)
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
238
|
+
if (!runtime?.view) {
|
|
239
|
+
if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
|
|
240
|
+
runtime ??= createRuntime(activeContext);
|
|
241
|
+
runtime.loadPassive();
|
|
242
|
+
} else if (scope !== "session") {
|
|
243
|
+
runtime.refreshShared();
|
|
244
|
+
}
|
|
224
245
|
installScopeStates();
|
|
225
246
|
}
|
|
226
247
|
|
|
@@ -319,6 +340,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
319
340
|
head: structuredClone(view.lineage.at(-1)!),
|
|
320
341
|
historyDepth: view.lineage.length - 1,
|
|
321
342
|
tailCounts: { global: view.scopes.global.patches.length, cwd: view.scopes.cwd.patches.length, session: view.scopes.session.patches.length },
|
|
343
|
+
revisions: temporalScopeRevisions(view),
|
|
322
344
|
} }),
|
|
323
345
|
staleArtifacts,
|
|
324
346
|
...(durableStateError === undefined ? {} : { durableStateError }),
|
|
@@ -699,6 +721,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
699
721
|
snapshot: () => ({
|
|
700
722
|
enabled: snapshot.config.enabled,
|
|
701
723
|
step: snapshot.meta.step,
|
|
724
|
+
revisions: scopeRevisions(),
|
|
702
725
|
bootstrap: snapshot.meta.bootstrap === true,
|
|
703
726
|
startPending: telegramStartPending,
|
|
704
727
|
}),
|
|
@@ -709,6 +732,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
709
732
|
: scopeStates[scope];
|
|
710
733
|
return { ...projectModelState(selected), lazy: structuredClone(selected.lazy) };
|
|
711
734
|
},
|
|
735
|
+
revisions: () => scopeRevisions(),
|
|
712
736
|
canStartNow: () => activeContext === undefined || activeContext.isIdle(),
|
|
713
737
|
start: () => {
|
|
714
738
|
if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
|
|
@@ -909,7 +933,21 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
909
933
|
if (!backupPending) return;
|
|
910
934
|
backupPending = false;
|
|
911
935
|
try {
|
|
912
|
-
if (existsSync(join(repositoryRoot, ".git")))
|
|
936
|
+
if (existsSync(join(repositoryRoot, ".git"))) {
|
|
937
|
+
backupCurrentStateFlowFiles(repositoryRoot);
|
|
938
|
+
const pushSessionId = sessionAddress(ctx).id;
|
|
939
|
+
const pushCwd = ctx.cwd;
|
|
940
|
+
startStateFlowBackupPush(repositoryRoot, (error) => {
|
|
941
|
+
if (shuttingDown) return;
|
|
942
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
943
|
+
const recorded = diagnosticWriter.recordBackupPushFailure(pushSessionId, pushCwd, message);
|
|
944
|
+
if (pushFailureNotified) return;
|
|
945
|
+
pushFailureNotified = true;
|
|
946
|
+
notifyActiveContext(recorded
|
|
947
|
+
? `State Flow Git backup push failed; state is saved locally. Details: ${stateFlowLogPath(agentDir)}. A later accepted turn retries.`
|
|
948
|
+
: `State Flow Git backup push failed; local diagnostics unavailable: ${message}`);
|
|
949
|
+
}, () => { pushFailureNotified = false; });
|
|
950
|
+
}
|
|
913
951
|
} catch (error) {
|
|
914
952
|
const message = error instanceof Error ? error.message : String(error);
|
|
915
953
|
recordDiagnostic(message, "publication-conflict", ctx);
|
|
@@ -950,10 +988,13 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
950
988
|
runAnchorTimestamp = undefined;
|
|
951
989
|
restoreActiveBranch(ctx);
|
|
952
990
|
});
|
|
953
|
-
pi.on("session_shutdown", (_event,
|
|
991
|
+
pi.on("session_shutdown", async (_event, _ctx) => {
|
|
992
|
+
shuttingDown = true;
|
|
954
993
|
telegramStartPending = false;
|
|
955
994
|
compactionStopped = true;
|
|
956
995
|
completedRunAccepted = false;
|
|
996
|
+
activeContext = undefined;
|
|
957
997
|
telegram.dispose();
|
|
998
|
+
await awaitInFlightBackupPushes(repositoryRoot);
|
|
958
999
|
});
|
|
959
1000
|
}
|
package/lib/git.ts
CHANGED
|
@@ -2,12 +2,19 @@
|
|
|
2
2
|
import { closeSync, constants, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
3
3
|
import { tmpdir } from "node:os";
|
|
4
4
|
import { dirname, join, relative, resolve, sep } from "node:path";
|
|
5
|
-
import { spawnSync } from "node:child_process";
|
|
5
|
+
import { spawn, spawnSync } from "node:child_process";
|
|
6
6
|
import { captureOwnedFileBases, isStateFlowOwnedPath } from "./durable.ts";
|
|
7
7
|
import { acquirePublicationLock, withStoragePublicationLock } from "./storage.ts";
|
|
8
8
|
|
|
9
9
|
const GIT_TIMEOUT_MS = 15_000;
|
|
10
10
|
const STATE_FLOW_COMMIT_TRAILER = "State-Flow-Durable: v1";
|
|
11
|
+
const activePushes = new Map<string, Promise<void>>();
|
|
12
|
+
|
|
13
|
+
function redactGitDiagnostic(value: string): string {
|
|
14
|
+
return value
|
|
15
|
+
.replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1***@")
|
|
16
|
+
.replace(/([?&](?:access_token|auth|password|token)=)[^&\s]+/gi, "$1***");
|
|
17
|
+
}
|
|
11
18
|
|
|
12
19
|
interface GitResult {
|
|
13
20
|
status: number;
|
|
@@ -134,6 +141,22 @@ function currentBranchRef(repositoryRoot: string): string {
|
|
|
134
141
|
return result.stdout.trim();
|
|
135
142
|
}
|
|
136
143
|
|
|
144
|
+
function configuredPushDestination(repositoryRoot: string): { remote: string; ref: string } | undefined {
|
|
145
|
+
const branchRef = currentBranchRef(repositoryRoot);
|
|
146
|
+
const branch = branchRef.slice("refs/heads/".length);
|
|
147
|
+
const configuredRemote = git(repositoryRoot, ["config", "--get", `branch.${branch}.remote`], { allowFailure: true });
|
|
148
|
+
if (configuredRemote.status > 1) throw new Error(configuredRemote.stderr || "Cannot inspect State Flow backup remote configuration");
|
|
149
|
+
if (configuredRemote.status !== 0 || configuredRemote.stdout.trim().length === 0) return undefined;
|
|
150
|
+
const remote = configuredRemote.stdout.trim();
|
|
151
|
+
if (remote === ".") throw new Error("State Flow backup replication requires a non-local Git remote");
|
|
152
|
+
const configuredMerge = git(repositoryRoot, ["config", "--get", `branch.${branch}.merge`], { allowFailure: true });
|
|
153
|
+
if (configuredMerge.status > 1) throw new Error(configuredMerge.stderr || "Cannot inspect State Flow backup branch configuration");
|
|
154
|
+
const ref = configuredMerge.status === 0 && configuredMerge.stdout.trim().length > 0
|
|
155
|
+
? configuredMerge.stdout.trim()
|
|
156
|
+
: branchRef;
|
|
157
|
+
return { remote, ref };
|
|
158
|
+
}
|
|
159
|
+
|
|
137
160
|
function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string | undefined): string | undefined {
|
|
138
161
|
const branchRef = currentBranchRef(repositoryRoot);
|
|
139
162
|
if (currentHead(repositoryRoot) !== expectedHead) throw new Error("State Flow backup Git base changed concurrently");
|
|
@@ -183,3 +206,85 @@ function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string |
|
|
|
183
206
|
export function backupCurrentStateFlowFiles(repositoryRoot: string): string | undefined {
|
|
184
207
|
return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root)));
|
|
185
208
|
}
|
|
209
|
+
|
|
210
|
+
/** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
|
|
211
|
+
export function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void): boolean {
|
|
212
|
+
const root = resolve(repositoryRoot);
|
|
213
|
+
if (activePushes.has(root)) return false;
|
|
214
|
+
const push = pushCurrentStateFlowBackup(root).then(
|
|
215
|
+
(result) => {
|
|
216
|
+
if (result) { try { onSuccess?.(); } catch { /* Reporting cannot change push acceptance. */ } }
|
|
217
|
+
},
|
|
218
|
+
(error) => {
|
|
219
|
+
try { onFailure(error); } catch { /* Reporting cannot revive a failed push. */ }
|
|
220
|
+
},
|
|
221
|
+
).finally(() => { activePushes.delete(root); });
|
|
222
|
+
activePushes.set(root, push);
|
|
223
|
+
return true;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** Resolve only after the push process has closed (including timeout termination). */
|
|
227
|
+
export async function awaitInFlightBackupPushes(repositoryRoot: string): Promise<void> {
|
|
228
|
+
const push = activePushes.get(resolve(repositoryRoot));
|
|
229
|
+
if (push) await push;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
|
|
233
|
+
export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ commit: string; remote: string; ref: string } | undefined> {
|
|
234
|
+
return new Promise((resolvePush, rejectPush) => {
|
|
235
|
+
let root: string;
|
|
236
|
+
let commit: string | undefined;
|
|
237
|
+
let destination: { remote: string; ref: string } | undefined;
|
|
238
|
+
try {
|
|
239
|
+
root = assertRepositoryRoot(repositoryRoot);
|
|
240
|
+
commit = currentHead(root);
|
|
241
|
+
destination = configuredPushDestination(root);
|
|
242
|
+
} catch (error) {
|
|
243
|
+
rejectPush(new Error(redactGitDiagnostic(error instanceof Error ? error.message : String(error))));
|
|
244
|
+
return;
|
|
245
|
+
}
|
|
246
|
+
if (commit === undefined || destination === undefined) {
|
|
247
|
+
resolvePush(undefined);
|
|
248
|
+
return;
|
|
249
|
+
}
|
|
250
|
+
const child = spawn("git", ["-C", root, "push", "--porcelain", "--", destination.remote, `${commit}:${destination.ref}`], {
|
|
251
|
+
detached: process.platform !== "win32",
|
|
252
|
+
stdio: ["ignore", "ignore", "pipe"],
|
|
253
|
+
windowsHide: true,
|
|
254
|
+
env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
|
|
255
|
+
});
|
|
256
|
+
let stderr = "";
|
|
257
|
+
let failure: Error | undefined;
|
|
258
|
+
let settled = false;
|
|
259
|
+
function terminate(error: Error): void {
|
|
260
|
+
failure ??= error;
|
|
261
|
+
if (child.exitCode !== null || child.signalCode !== null) {
|
|
262
|
+
child.stderr?.destroy();
|
|
263
|
+
return;
|
|
264
|
+
}
|
|
265
|
+
if (!child.pid) return;
|
|
266
|
+
try {
|
|
267
|
+
if (process.platform === "win32") child.kill("SIGKILL");
|
|
268
|
+
else process.kill(-child.pid, "SIGKILL");
|
|
269
|
+
} catch {
|
|
270
|
+
// Keep waiting for close: signalling failure is not proof that the process ended.
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
const timeout = setTimeout(() => terminate(new Error(`Git backup push timed out after ${GIT_TIMEOUT_MS}ms`)), GIT_TIMEOUT_MS);
|
|
274
|
+
function finish(error?: Error): void {
|
|
275
|
+
if (settled) return;
|
|
276
|
+
settled = true;
|
|
277
|
+
clearTimeout(timeout);
|
|
278
|
+
if (error) rejectPush(error);
|
|
279
|
+
else resolvePush({ commit: commit!, ...destination! });
|
|
280
|
+
}
|
|
281
|
+
child.stderr?.on("data", (chunk: Buffer) => { stderr = (stderr + chunk.toString("utf8")).slice(-1000); });
|
|
282
|
+
child.on("error", (error) => {
|
|
283
|
+
failure ??= error;
|
|
284
|
+
if (!child.pid) finish(error);
|
|
285
|
+
});
|
|
286
|
+
child.once("exit", () => { if (failure) child.stderr?.destroy(); });
|
|
287
|
+
child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
|
|
288
|
+
: new Error(`Git backup push failed (${endedBy ?? code}): ${redactGitDiagnostic(stderr.trim()) || "no diagnostic output"}`))));
|
|
289
|
+
});
|
|
290
|
+
}
|
package/lib/logging.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// Domain: opt-in diagnostic capture for rejected State Flow resolutions.
|
|
2
|
-
import { appendFileSync, mkdirSync } from "node:fs";
|
|
2
|
+
import { appendFileSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync } from "node:fs";
|
|
3
3
|
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
4
4
|
import { isObject } from "./json.ts";
|
|
5
5
|
|
|
@@ -39,9 +39,22 @@ export function stateFlowLogPath(agentDir: string): string {
|
|
|
39
39
|
return join(agentDir, "tmp", "state-flow", "logs.jsonl");
|
|
40
40
|
}
|
|
41
41
|
|
|
42
|
+
function ensureDiagnosticDirectory(path: string): void {
|
|
43
|
+
if (dirname(path) !== path) ensureDiagnosticDirectory(dirname(path));
|
|
44
|
+
if (!lstatSync(path, { throwIfNoEntry: false })) mkdirSync(path);
|
|
45
|
+
const stat = lstatSync(path);
|
|
46
|
+
if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`State Flow diagnostic directory is not a regular directory: ${path}`);
|
|
47
|
+
}
|
|
48
|
+
|
|
42
49
|
export function appendStateFlowDiagnostic(path: string, record: StateFlowDiagnosticRecord): void {
|
|
43
|
-
|
|
44
|
-
|
|
50
|
+
ensureDiagnosticDirectory(dirname(path));
|
|
51
|
+
const descriptor = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
|
|
52
|
+
try {
|
|
53
|
+
if (!fstatSync(descriptor).isFile()) throw new Error(`State Flow diagnostic destination is not a regular file: ${path}`);
|
|
54
|
+
appendFileSync(descriptor, `${JSON.stringify(record)}\n`, { encoding: "utf8" });
|
|
55
|
+
} finally {
|
|
56
|
+
closeSync(descriptor);
|
|
57
|
+
}
|
|
45
58
|
}
|
|
46
59
|
|
|
47
60
|
export interface DiagnosticExtras {
|
|
@@ -68,6 +81,15 @@ export class StateFlowDiagnosticWriter {
|
|
|
68
81
|
|
|
69
82
|
record(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras = {}): void {
|
|
70
83
|
if (!this.enabled) return;
|
|
84
|
+
this.write(sessionId, cwd, error, category, extras);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Push warnings stay short; retain the available Git failure detail locally even without opt-in logging. */
|
|
88
|
+
recordBackupPushFailure(sessionId: string, cwd: string, error: string): boolean {
|
|
89
|
+
return this.write(sessionId, cwd, error, "publication-conflict", {}, false);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
private write(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras, reportFailure = true): boolean {
|
|
71
93
|
try {
|
|
72
94
|
const fromRepository = relative(this.repositoryRoot, this.path);
|
|
73
95
|
if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
|
|
@@ -84,10 +106,13 @@ export class StateFlowDiagnosticWriter {
|
|
|
84
106
|
...(extras.tool === undefined ? {} : { tool: extras.tool }),
|
|
85
107
|
...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
|
|
86
108
|
});
|
|
109
|
+
return true;
|
|
87
110
|
} catch (failure) {
|
|
88
|
-
if (this.warningReported)
|
|
89
|
-
|
|
90
|
-
|
|
111
|
+
if (reportFailure && !this.warningReported) {
|
|
112
|
+
this.warningReported = true;
|
|
113
|
+
this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
|
|
114
|
+
}
|
|
115
|
+
return false;
|
|
91
116
|
}
|
|
92
117
|
}
|
|
93
118
|
}
|
package/lib/protocol.ts
CHANGED
|
@@ -56,7 +56,7 @@ READ: Use read_state for concrete scope/history gaps. lazy_navigation lists boun
|
|
|
56
56
|
|
|
57
57
|
WRITE: patch_state is the sole model-authored semantic mutation mechanism. Supply global/cwd/session patches in any combination; all supplied scopes are validated and durably accepted as one atomic transition. Call it alone in an assistant response, then continue only after its acknowledgement.
|
|
58
58
|
|
|
59
|
-
RESPONSE: Ordinary assistant completion needs no finalization patch.
|
|
59
|
+
RESPONSE: Ordinary assistant completion needs no finalization patch. At turn_end, runtime stores the exact accepted answer; empty becomes response "".
|
|
60
60
|
|
|
61
61
|
INTENTS: Keep chosen actions; detail may stay lazy. State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. If that resolution proves a dangling state ref, fix/drop it in owning text; never scan for broken refs.
|
|
62
62
|
|
|
@@ -88,10 +88,8 @@ export function finalizedAssistantResponse(message: AgentMessage): string {
|
|
|
88
88
|
if (message.content.some((block) => block.type === "toolCall")) {
|
|
89
89
|
throw new Error("Accepted State Flow response cannot contain a tool call");
|
|
90
90
|
}
|
|
91
|
-
|
|
91
|
+
return message.content
|
|
92
92
|
.filter((block) => block.type === "text")
|
|
93
93
|
.map((block) => block.text)
|
|
94
94
|
.join("");
|
|
95
|
-
if (response.trim().length === 0) throw new Error("Finalized State Flow response must contain non-empty text");
|
|
96
|
-
return response;
|
|
97
95
|
}
|
package/lib/runtime.ts
CHANGED
|
@@ -415,6 +415,17 @@ export class TemporalRuntime {
|
|
|
415
415
|
return { view: reconciledView(), base: captured, provenance };
|
|
416
416
|
}
|
|
417
417
|
|
|
418
|
+
/** Refresh live shared scopes in memory without publishing or advancing private semantic history. */
|
|
419
|
+
refreshShared(): boolean {
|
|
420
|
+
if (!this.view || !this.base) throw new Error("State Flow shared refresh requires a selected temporal runtime");
|
|
421
|
+
const before = this.view;
|
|
422
|
+
const reconciled = this.reconcileSharedDrift(new Set());
|
|
423
|
+
this.view = reconciled.view;
|
|
424
|
+
this.base = reconciled.base;
|
|
425
|
+
this.provenanceByScope = reconciled.provenance;
|
|
426
|
+
return before !== this.view;
|
|
427
|
+
}
|
|
428
|
+
|
|
418
429
|
/** Canonically accept a prepared retained-boundary origin before lifecycle-only persistence. */
|
|
419
430
|
acceptRestoredOrigin(snapshot: Snapshot): RuntimePublication {
|
|
420
431
|
if (!this.restoredOriginPending) throw new Error("State Flow has no prepared restored origin to accept");
|
package/lib/status.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { projectRecentTransitionsWithLimit, type RecentTransitionWindow } from "
|
|
|
3
3
|
import { retainedMemoryScopes } from "./memory.ts";
|
|
4
4
|
import type { Snapshot } from "./snapshot.ts";
|
|
5
5
|
import { overlayStates, type ScopedStates, type StateScope } from "./state.ts";
|
|
6
|
-
import type { TransitionBoundary } from "./temporal.ts";
|
|
6
|
+
import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
|
|
7
7
|
|
|
8
8
|
export const STATUS_KEY = "state-flow";
|
|
9
9
|
|
|
@@ -24,13 +24,18 @@ export interface StatusDiagnostics {
|
|
|
24
24
|
scopeStates: ScopedStates;
|
|
25
25
|
recent: RecentTransitionWindow;
|
|
26
26
|
historyLimit: number;
|
|
27
|
-
temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Record<StateScope, number
|
|
27
|
+
temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Record<StateScope, number>; revisions: ScopeRevisions };
|
|
28
28
|
staleArtifacts: readonly StaleArtifactDiagnostic[];
|
|
29
29
|
durableStateError?: string;
|
|
30
30
|
}
|
|
31
31
|
|
|
32
|
-
export function
|
|
33
|
-
return
|
|
32
|
+
export function formatScopeRevisionVector(revisions: ScopeRevisions): string {
|
|
33
|
+
return `G${revisions.global}/C${revisions.cwd}/S${revisions.session}`;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function compactStatus(snapshot: Snapshot, revisions: ScopeRevisions, colorize: Colorize): string | undefined {
|
|
37
|
+
if (!snapshot.config.enabled) return undefined;
|
|
38
|
+
return `${colorize("accent", "state-flow")} ${colorize("dim", formatScopeRevisionVector(revisions))}`;
|
|
34
39
|
}
|
|
35
40
|
|
|
36
41
|
function countArtifacts(states: ScopedStates, scope: StateScope): number {
|
|
@@ -62,6 +67,7 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
|
|
|
62
67
|
`Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`,
|
|
63
68
|
"Retained patch tails: unavailable"]
|
|
64
69
|
: [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
|
|
70
|
+
`Scope revisions: global #${temporal.revisions.global}; CWD #${temporal.revisions.cwd}; session #${temporal.revisions.session}; effective ${formatScopeRevisionVector(temporal.revisions)}`,
|
|
65
71
|
`Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`,
|
|
66
72
|
`Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
|
|
67
73
|
const artifacts = (scope: StateScope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";
|
package/lib/telegram.ts
CHANGED
|
@@ -3,6 +3,9 @@
|
|
|
3
3
|
// This is a leaf adapter. Core semantics, storage, and inference never depend on it; when
|
|
4
4
|
// pi-telegram is absent or its registry is not ready, registration fails open and retries.
|
|
5
5
|
|
|
6
|
+
import { formatScopeRevisionVector } from "./status.ts";
|
|
7
|
+
import type { ScopeRevisions } from "./temporal.ts";
|
|
8
|
+
|
|
6
9
|
export const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
|
|
7
10
|
|
|
8
11
|
/** Resolve the package export or the compiled sibling-extension layout used in local development. */
|
|
@@ -15,7 +18,9 @@ export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url):
|
|
|
15
18
|
|
|
16
19
|
export interface StateFlowTelegramSnapshot {
|
|
17
20
|
enabled: boolean;
|
|
21
|
+
/** Legacy branch step retained for existing adapter ports; current runtime ports also supply owner revisions. */
|
|
18
22
|
step: number;
|
|
23
|
+
revisions?: ScopeRevisions;
|
|
19
24
|
bootstrap: boolean;
|
|
20
25
|
startPending: boolean;
|
|
21
26
|
}
|
|
@@ -93,6 +98,8 @@ export interface StateFlowTelegramControlResult {
|
|
|
93
98
|
export interface StateFlowTelegramPort {
|
|
94
99
|
snapshot(): StateFlowTelegramSnapshot;
|
|
95
100
|
state(scope: StateFlowTelegramScope): StateFlowTelegramState;
|
|
101
|
+
/** Optional additive capability; absent legacy ports retain their branch-step presentation. */
|
|
102
|
+
revisions?(): ScopeRevisions;
|
|
96
103
|
canStartNow(): boolean;
|
|
97
104
|
start(): StateFlowTelegramControlResult;
|
|
98
105
|
stop(): StateFlowTelegramControlResult;
|
|
@@ -107,12 +114,14 @@ export interface StateFlowTelegramAdapter {
|
|
|
107
114
|
|
|
108
115
|
/** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
|
|
109
116
|
export function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string {
|
|
110
|
-
return
|
|
117
|
+
if (!snapshot.enabled) return "🌀 State Flow: off";
|
|
118
|
+
return `🌀 State Flow: ${snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`}`;
|
|
111
119
|
}
|
|
112
120
|
|
|
113
121
|
/** Shared live value: plain in the button label, monospaced in the submenu state line. */
|
|
114
122
|
function stateFlowLabelValue(snapshot: StateFlowTelegramSnapshot): string {
|
|
115
|
-
|
|
123
|
+
if (!snapshot.enabled) return "off";
|
|
124
|
+
return snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`;
|
|
116
125
|
}
|
|
117
126
|
|
|
118
127
|
/** Submenu state line: the same identity as the button label, with the live value in monospace. */
|
|
@@ -191,13 +200,18 @@ function renderStateFlowTelegramField(value: unknown): string {
|
|
|
191
200
|
return rendered;
|
|
192
201
|
}
|
|
193
202
|
|
|
194
|
-
export function renderStateFlowRichState(scope: StateFlowTelegramScope,
|
|
195
|
-
const fields =
|
|
203
|
+
export function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
|
|
204
|
+
const fields: Array<keyof StateFlowTelegramState> = scope === "global" || scope === "cwd"
|
|
205
|
+
? ["intents", "contract", "working", "artifacts", "lazy"]
|
|
206
|
+
: ["intents", "contract", "working", "artifacts", "response", "lazy"];
|
|
207
|
+
const revision = scope === "effective"
|
|
208
|
+
? formatScopeRevisionVector(revisions)
|
|
209
|
+
: `#${revisions[scope]}`;
|
|
196
210
|
return {
|
|
197
211
|
blocks: [
|
|
198
212
|
{
|
|
199
213
|
type: "heading",
|
|
200
|
-
text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text:
|
|
214
|
+
text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: revision }],
|
|
201
215
|
size: 3,
|
|
202
216
|
},
|
|
203
217
|
...fields.map((field) => ({
|
|
@@ -233,7 +247,10 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
|
|
|
233
247
|
}
|
|
234
248
|
if (ctx.action === "inspect") {
|
|
235
249
|
if (!isStateFlowTelegramScope(ctx.payload)) throw new Error("Unknown State Flow scope");
|
|
236
|
-
|
|
250
|
+
const state = port.state(ctx.payload);
|
|
251
|
+
const live = port.snapshot();
|
|
252
|
+
const revisions = port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step };
|
|
253
|
+
await ctx.openRich(renderStateFlowRichState(ctx.payload, revisions, state));
|
|
237
254
|
await ctx.answerCallback();
|
|
238
255
|
return "handled" as const;
|
|
239
256
|
}
|