@llblab/pi-state-flow 0.6.0 → 0.8.0

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/lib/extension.ts CHANGED
@@ -2,20 +2,20 @@ import { execFile } from "node:child_process";
2
2
  import type { AgentMessage } from "@earendil-works/pi-agent-core";
3
3
  import { StringEnum, Type } from "@earendil-works/pi-ai";
4
4
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
5
- import { assistantToolCallCount, finalizedAssistantResponse, parseTerminalPatch, stateFlowProtocol, stripStateComments } from "./terminal.ts";
6
- import { currentRunTrajectory, runtimeContextMessage, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation } from "./context.ts";
5
+ import { getAgentDir } from "@earendil-works/pi-coding-agent";
6
+ import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./terminal.ts";
7
+ import { createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, runtimeContextMessage, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
7
8
  import { ArtifactReadTracker } from "./acquisition.ts";
8
9
  import { loadStateFlowConfig } from "./config.ts";
9
- import { resolve } from "node:path";
10
+ import { isAbsolute, relative, resolve, sep } from "node:path";
10
11
  import { SkillReadTracker } from "./skills.ts";
11
12
  import { emptySnapshot, migrationFailure, persistableSnapshot, type Snapshot } from "./snapshot.ts";
12
13
  import { inspectSnapshotRevision, TemporalRuntime, type RuntimePublication } from "./runtime.ts";
13
- import { emptyState, overlayStates, type MaterializedState, type ScopePatch, type ScopedStates, type StateScope } from "./state.ts";
14
- import { commitScopedTransition, stageScopedPatch, stageScopedTransition, type StagedScopedTransition } from "./transition.ts";
15
- import { MAX_VALIDATION_RETRIES, nextValidation } from "./validation.ts";
14
+ import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
15
+ import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, validateFinalEligibility, type StagedScopedTransition } from "./transition.ts";
16
16
  import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
17
17
  import { compactStatus, detailedStatus, STATUS_KEY, type PendingPublicationDiagnostic, type StatusDiagnostics } from "./status.ts";
18
- import { abandonValidation, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
18
+ import { prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
19
19
  import { recoverSnapshot } from "./recovery.ts";
20
20
  import type { RehydrationPhase } from "./rehydration.ts";
21
21
  import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.ts";
@@ -23,13 +23,15 @@ import { coalescePublicationTarget, createPublicationQueue, type PublicationQueu
23
23
  import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.ts";
24
24
  import { runPublicationWorker } from "./publication.ts";
25
25
  import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.ts";
26
+ import { isObject, sameJson } from "./json.ts";
26
27
  import {
27
28
  cwdScopeKey,
28
29
  resolveSessionAddress,
29
30
  sessionScopeKey,
30
31
  type SessionAddress,
31
32
  } from "./durable.ts";
32
- import { projectRecentTransitionsWithLimit } from "./history.ts";
33
+ import { projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT } from "./history.ts";
34
+ import { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath, type StateFlowDiagnosticCategory } from "./logging.ts";
33
35
  import { isGitCommitAncestor, pushGitCommit, resolveGitPushDestination } from "./git.ts";
34
36
  import {
35
37
  ORDINARY_ARTIFACT_COMPILER,
@@ -46,15 +48,30 @@ export interface StateFlowExtensionOptions {
46
48
 
47
49
  export const PATCH_STATE_TOOL_NAME = "patch_state";
48
50
  export const READ_STATE_TOOL_NAME = "read_state";
51
+ export const MAX_RESOLUTION_ATTEMPTS = 3;
52
+ const PASSIVE_STOP_ENTRY_TYPE = "state-flow-passive-stop";
53
+
54
+ /** Keep a failed tool invocation visually separated from its rendered error without changing error semantics. */
55
+ function separatedFailure(error: unknown): Error {
56
+ const message = error instanceof Error ? error.message : String(error);
57
+ return new Error(`\n${message}`, error instanceof Error ? { cause: error } : undefined);
58
+ }
49
59
 
50
60
  export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowExtensionOptions = {}): void {
51
- const config = loadStateFlowConfig(options.agentDir);
61
+ const agentDir = options.agentDir ?? getAgentDir();
62
+ const config = loadStateFlowConfig(agentDir);
52
63
  let snapshot: Snapshot = emptySnapshot();
53
64
  let scopeStates: ScopedStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
54
65
  let branchHasSnapshot = false;
55
66
  let branchStartsWithoutRuntime = false;
56
- let stagedFinal: StagedScopedTransition | undefined;
57
- let retryQueued = false;
67
+ let terminalEligible = false;
68
+ let terminalDraftIntercepted = false;
69
+ let resolutionAttempts = 0;
70
+ let resolutionFailureReported = false;
71
+ let responseAwaitingReconciliation = false;
72
+ let passiveContinuation: PassiveContinuation | undefined;
73
+ let bootstrapContinuation: PassiveContinuation | undefined;
74
+ let artifactRefreshPending = false;
58
75
  let runAnchorTimestamp: number | undefined;
59
76
  let runtime: TemporalRuntime | undefined;
60
77
  let activeContext: ExtensionContext | undefined;
@@ -65,8 +82,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
65
82
  const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
66
83
  const skillReads = new SkillReadTracker();
67
84
  const artifactReads = new ArtifactReadTracker();
68
- const globalMarkdown = new GlobalMarkdownDiscovery(options.knowledgeRoot ?? getKnowledgeRoot(options.agentDir));
85
+ const globalMarkdown = new GlobalMarkdownDiscovery(options.knowledgeRoot ?? getKnowledgeRoot(agentDir));
69
86
  let artifactInvalidations: ArtifactInvalidationRequest[] = [];
87
+ let loggingWarningReported = false;
70
88
 
71
89
  function sessionAddress(ctx: ExtensionContext): SessionAddress {
72
90
  return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
@@ -78,7 +96,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
78
96
 
79
97
  options.onRuntime?.({ read: (offset, scope) => {
80
98
  if (!runtime) throw new Error("State Flow temporal runtime is unavailable");
81
- return runtime.read(offset, scope);
99
+ return projectStateForModel(runtime.read(offset, scope));
82
100
  } });
83
101
 
84
102
  function persist(): void {
@@ -105,14 +123,41 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
105
123
  }
106
124
 
107
125
  function clearRunTransient(): void {
108
- stagedFinal = undefined;
109
- retryQueued = false;
126
+ terminalEligible = false;
127
+ terminalDraftIntercepted = false;
128
+ resolutionAttempts = 0;
129
+ resolutionFailureReported = false;
130
+ responseAwaitingReconciliation = false;
110
131
  runAnchorTimestamp = undefined;
111
132
  skillReads.clear();
112
133
  artifactReads.clear();
113
134
  }
114
135
 
136
+ function passiveStopTimestamp(ctx: ExtensionContext): number | undefined {
137
+ for (const entry of [...ctx.sessionManager.getBranch()].reverse()) {
138
+ try {
139
+ if (entry?.type !== "custom" || entry.customType !== PASSIVE_STOP_ENTRY_TYPE) continue;
140
+ const at = (entry.data as { at?: unknown } | undefined)?.at;
141
+ if (typeof at === "number" && Number.isSafeInteger(at) && at >= 0) return at;
142
+ } catch {
143
+ // A hostile unrelated branch entry cannot manufacture or suppress a valid marker.
144
+ }
145
+ }
146
+ return undefined;
147
+ }
148
+
149
+ function retainsPhysicalSessionProjection(reason: unknown): boolean {
150
+ return reason === undefined || reason === "startup" || reason === "reload" || reason === "resume";
151
+ }
152
+
153
+ function deferArtifactRefresh(): void {
154
+ artifactInvalidations = [];
155
+ artifactReads.setCandidates([]);
156
+ artifactRefreshPending = true;
157
+ }
158
+
115
159
  function refreshArtifactInvalidations(ctx: ExtensionContext): void {
160
+ artifactRefreshPending = false;
116
161
  if (!snapshot.config.enabled) {
117
162
  artifactInvalidations = [];
118
163
  artifactReads.setCandidates([]);
@@ -124,13 +169,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
124
169
  discovery.sources,
125
170
  scopeStates.global.artifacts,
126
171
  ORDINARY_ARTIFACT_COMPILER,
172
+ {},
173
+ runtime?.artifactProvenance("global") ?? {},
127
174
  );
128
175
  artifactInvalidations = structuredClone(plan.requiresCompilation);
129
176
  if (plan.removed.length > 0) {
130
177
  const removals = Object.fromEntries(plan.removed.map((path) => [path, null]));
131
- const stage = stageScopedPatch(
178
+ const stage = stageAtomicScopePatches(
132
179
  scopeStates,
133
- { scope: "global", patch: { artifacts: removals } },
180
+ { global: { artifacts: removals } },
134
181
  [],
135
182
  runtime!.causalBasis(),
136
183
  );
@@ -193,12 +240,34 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
193
240
  }
194
241
  }
195
242
 
243
+ /** Accept an activation or lifecycle commit locally; turn-end policy queues it for the asynchronous worker. */
244
+ function recordPolicyPublication(publication: RuntimePublication | undefined, ctx: ExtensionContext): void {
245
+ if (!publication) return;
246
+ recordPublication(publication, ctx);
247
+ const mode = snapshot.meta.remotePublication?.mode ?? "transition";
248
+ const target = publication.commit ?? publication.revision;
249
+ if (mode !== "turn-end" || target === undefined || !/^[0-9a-f]{40,64}$/.test(target)) return;
250
+ turnPublicationTarget = target;
251
+ try {
252
+ enqueueTurnPublication();
253
+ launchPublicationWorker();
254
+ } catch (error) {
255
+ ctx.ui.notify(
256
+ `State Flow accepted the local commit; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`,
257
+ "warning",
258
+ );
259
+ }
260
+ }
261
+
196
262
  function commitStage(stage: StagedScopedTransition, ctx: ExtensionContext, finalizeRun: boolean): boolean {
197
263
  const acquiredArtifactPaths = new Set(artifactReads.successful.keys());
198
264
  const committed = commitScopedTransition(snapshot, scopeStates, stage, (accepted, nextSnapshot) => {
199
265
  if (!runtime?.view) throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
200
266
  const mode = nextSnapshot.meta.remotePublication?.mode ?? "transition";
201
- const publication = runtime.publish(nextSnapshot, accepted !== undefined, accepted, { pushRemote: mode === "transition" });
267
+ const publication = runtime.publish(nextSnapshot, accepted !== undefined, accepted, {
268
+ pushRemote: mode === "transition",
269
+ provenance: stage.provenanceUpdates,
270
+ });
202
271
  if (publication?.commit && mode === "turn-end") turnPublicationTarget = publication.commit;
203
272
  if (publication) recordPublication(publication, ctx);
204
273
  }, runtime!.causalBasis(), { finalizeRun });
@@ -272,12 +341,31 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
272
341
  }).finally(() => {
273
342
  activePublicationWorkers.delete(path);
274
343
  lease.release();
275
- if (loadPublicationQueue(path)?.status === "pending") launchPublicationWorker();
344
+ try {
345
+ if (loadPublicationQueue(path)?.status === "pending") launchPublicationWorker();
346
+ } catch {
347
+ // Malformed queue persistence stays inert until an explicit retry or repair.
348
+ }
276
349
  });
277
350
  }
278
351
 
279
352
  function retryPendingPush(ctx: ExtensionContext): void {
280
353
  if (pendingPublication === undefined || !runtime?.view) return;
354
+ const mode = snapshot.meta.remotePublication?.mode ?? "transition";
355
+ if (mode !== "transition") {
356
+ const target = pendingPublication.commit;
357
+ setPendingPublication(undefined);
358
+ if (mode === "turn-end") {
359
+ turnPublicationTarget = target;
360
+ try {
361
+ enqueueTurnPublication();
362
+ launchPublicationWorker();
363
+ } catch (error) {
364
+ ctx.ui.notify(`State Flow retained local state; asynchronous publication recovery is deferred: ${error instanceof Error ? error.message : String(error)}`, "warning");
365
+ }
366
+ }
367
+ return;
368
+ }
281
369
  const result = pushGitCommit(repositoryRoot, pendingPublication.commit);
282
370
  if (result.status !== "pending") {
283
371
  setPendingPublication(undefined);
@@ -314,6 +402,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
314
402
  discovery.sources,
315
403
  diagnosticStates.global.artifacts,
316
404
  ORDINARY_ARTIFACT_COMPILER,
405
+ {},
406
+ runtime?.artifactProvenance("global") ?? {},
317
407
  );
318
408
  staleArtifacts = [
319
409
  ...plan.requiresCompilation.map(({ path, reason }) => ({ scope: "global" as const, path, reason })),
@@ -349,7 +439,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
349
439
  ...(artifactFreshnessError === undefined ? {} : { artifactFreshnessError }),
350
440
  ...(durableStateError === undefined ? {} : { durableStateError }),
351
441
  ...(pendingPublication === undefined ? {} : { pendingPublication }),
352
- retryQueued,
353
442
  ...(publicationQueue === undefined ? {} : { publicationQueue }),
354
443
  ...(publicationQueueError === undefined ? {} : { publicationQueueError }),
355
444
  };
@@ -357,6 +446,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
357
446
 
358
447
  function restoreActiveBranch(ctx: ExtensionContext, sessionStartReason?: unknown): void {
359
448
  clearRunTransient();
449
+ passiveContinuation = undefined;
450
+ bootstrapContinuation = undefined;
451
+ artifactInvalidations = [];
452
+ artifactReads.setCandidates([]);
453
+ artifactRefreshPending = false;
360
454
  activeContext = ctx;
361
455
  const session = sessionAddress(ctx);
362
456
  runtime = new TemporalRuntime(ctx.cwd, session, repositoryRoot);
@@ -383,7 +477,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
383
477
  if (snapshot.meta.durableBase !== selectedRevision) persist();
384
478
  } else if (branchHasSnapshot && snapshot.config.enabled) {
385
479
  const publication = runtime.initialize(snapshot, true);
386
- if (publication) recordPublication(publication, ctx);
480
+ recordPolicyPublication(publication, ctx);
387
481
  delete snapshot.legacySession;
388
482
  }
389
483
  installScopeStates();
@@ -394,7 +488,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
394
488
  );
395
489
  runtime.prepare();
396
490
  const initialization = runtime.initialize(snapshot, true);
397
- if (initialization) recordPublication(initialization, ctx);
491
+ recordPolicyPublication(initialization, ctx);
398
492
  if (!runtime.view) snapshot = emptySnapshot();
399
493
  installScopeStates();
400
494
  if (snapshot.config.enabled) {
@@ -432,47 +526,66 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
432
526
  if (!snapshot.config.enabled && snapshot.meta.validation?.attempt === 0) {
433
527
  ctx.ui.notify(`State Flow restored disabled: ${snapshot.meta.validation.error}`, "error");
434
528
  }
529
+ if (retainsPhysicalSessionProjection(sessionStartReason) && runtime?.view) {
530
+ const stoppedAt = passiveStopTimestamp(ctx);
531
+ if (stoppedAt !== undefined) {
532
+ const continuation = createPassiveContinuation(
533
+ projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)),
534
+ stoppedAt,
535
+ );
536
+ if (!snapshot.config.enabled) passiveContinuation = continuation;
537
+ else if (snapshot.meta.bootstrap) bootstrapContinuation = continuation;
538
+ }
539
+ }
540
+ if (snapshot.config.enabled) deferArtifactRefresh();
435
541
  syncStateFlowTools();
436
542
  updateUi(ctx);
437
543
  }
438
544
 
439
- function abandonRun(ctx: ExtensionContext): void {
440
- const changed = abandonValidation(snapshot);
441
- clearRunTransient();
442
- if (changed) persist();
443
- updateUi(ctx);
545
+ interface DiagnosticExtras {
546
+ content?: unknown;
547
+ input?: unknown;
548
+ tool?: string;
549
+ toolCallId?: string;
550
+ resolutionAttempt?: number;
551
+ terminalEligible?: boolean;
444
552
  }
445
553
 
446
- function queueTerminalRegeneration(error: string, ctx: ExtensionContext): void {
447
- const decision = nextValidation(snapshot.meta.validation, error);
448
- if (decision.kind === "retry") {
449
- snapshot.meta.validation = decision.feedback;
450
- persist();
451
- retryQueued = true;
452
- pi.sendMessage({
453
- customType: VALIDATION_MESSAGE_TYPE,
454
- content: `State Flow rejected the terminal response (attempt ${decision.feedback.attempt}/${MAX_VALIDATION_RETRIES}). ${decision.feedback.instruction}`,
455
- display: false,
456
- }, { deliverAs: "steer", triggerTurn: true });
457
- return;
554
+ function recordDiagnostic(error: string, category: StateFlowDiagnosticCategory, ctx: ExtensionContext, extras: DiagnosticExtras = {}): void {
555
+ if (!config.logging) return;
556
+ try {
557
+ const path = stateFlowLogPath(agentDir);
558
+ const fromRepository = relative(repositoryRoot, path);
559
+ if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
560
+ throw new Error("diagnostic path overlaps the State Flow repository");
561
+ }
562
+ appendStateFlowDiagnostic(path, {
563
+ at: new Date().toISOString(),
564
+ sessionId: sessionAddress(ctx).id,
565
+ cwd: resolve(ctx.cwd),
566
+ category,
567
+ error,
568
+ ...(extras.content === undefined ? {} : { content: projectDiagnosticContent(extras.content) }),
569
+ ...(extras.input === undefined ? {} : { input: extras.input }),
570
+ ...(extras.tool === undefined ? {} : { tool: extras.tool }),
571
+ ...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
572
+ ...(extras.resolutionAttempt === undefined ? {} : { resolutionAttempt: extras.resolutionAttempt }),
573
+ ...(extras.terminalEligible === undefined ? {} : { terminalEligible: extras.terminalEligible }),
574
+ });
575
+ } catch (failure) {
576
+ if (loggingWarningReported) return;
577
+ loggingWarningReported = true;
578
+ ctx.ui.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`, "warning");
458
579
  }
459
- retryQueued = false;
460
- snapshot.meta.validation = undefined;
461
- skillReads.clear();
462
- artifactReads.clear();
463
- persist();
464
- ctx.ui.notify(`State Flow remains enabled after ${MAX_VALIDATION_RETRIES} automatic regeneration attempts; the last committed state was preserved: ${decision.error}`, "error");
465
580
  }
466
581
 
467
- function rejectTerminal(message: { role: "assistant"; content?: unknown }, error: string, ctx: ExtensionContext) {
468
- queueTerminalRegeneration(error, ctx);
469
- return {
470
- message: {
471
- ...message,
472
- role: "assistant" as const,
473
- content: [],
474
- },
475
- };
582
+ function continueForResolution(): void {
583
+ terminalDraftIntercepted = true;
584
+ pi.sendMessage({
585
+ customType: VALIDATION_MESSAGE_TYPE,
586
+ content: "Before completing this turn, make the State Flow iteration terminal-eligible. Call patch_state with any durable scope changes and final:true, or call patch_state with {\"final\":true} when no semantic update is needed. Then provide the final answer normally.",
587
+ display: false,
588
+ }, { deliverAs: "steer", triggerTurn: true });
476
589
  }
477
590
 
478
591
  pi.registerTool({
@@ -485,51 +598,89 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
485
598
  scope: Type.Optional(StringEnum(["effective", "global", "cwd", "session"] as const, { description: "Projection at that same boundary; defaults to effective" })),
486
599
  }, { additionalProperties: false }),
487
600
  async execute(_toolCallId, params, signal) {
488
- if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
489
- if (signal?.aborted) throw new Error("State Flow read was aborted");
490
- if (!runtime?.view) throw new Error("State Flow temporal runtime is unavailable");
491
- const { offset = 0, scope = "effective" } = params;
492
- const state = runtime.read(offset, scope === "effective" ? undefined : scope);
493
- const boundary = runtime.view.lineage.at(-1 - offset)!;
494
- return {
495
- content: [{ type: "text", text: JSON.stringify({ offset, scope, boundary, state }) }],
496
- details: { offset, scope, transitionId: boundary.id },
497
- };
601
+ try {
602
+ if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
603
+ if (signal?.aborted) throw new Error("State Flow read was aborted");
604
+ if (!runtime?.view) throw new Error("State Flow temporal runtime is unavailable");
605
+ const { offset = 0, scope = "effective" } = params;
606
+ const state = runtime.read(offset, scope === "effective" ? undefined : scope);
607
+ const boundary = runtime.view.lineage.at(-1 - offset)!;
608
+ return {
609
+ content: [{ type: "text", text: `\n${JSON.stringify({ offset, scope, boundary, state: projectStateForModel(state) })}` }],
610
+ details: { offset, scope, transitionId: boundary.id },
611
+ };
612
+ } catch (error) {
613
+ throw separatedFailure(error);
614
+ }
498
615
  },
499
616
  });
500
617
 
501
618
  pi.registerTool({
502
619
  name: PATCH_STATE_TOOL_NAME,
503
620
  label: "Patch State",
504
- description: "Materialize established future-relevant semantic state at a session, CWD, or global barrier, including a necessary write-and-verify step during explicitly requested curation. Do not use for scratchpad, narration, routine progress, or speculative churn. This call must be the only State Flow barrier in its assistant response; sibling tool calls are blocked and reconsidered after rematerialization.",
505
- promptSnippet: "Materialize established future-relevant state as an immediate inference barrier",
621
+ description: "The sole State Flow semantic mutation protocol. Supply any combination of global, cwd, and session patches; all supplied scopes commit atomically. Set final:true when the current iteration may finish at a later turn_end. final:true does not stop reasoning, tools, or later patch_state calls. Use {final:true} when no semantic update is needed. This call must be the only State Flow barrier in its assistant response.",
622
+ promptSnippet: "Atomically patch global/cwd/session; final:true permits a later turn_end",
506
623
  promptGuidelines: [
507
- "Use patch_state when established future-relevant information would face meaningful loss or recovery risk if delayed until terminal reconciliation, or for a necessary write-and-verify step in explicitly requested curation.",
508
- "Call patch_state alone in an assistant response; choose subsequent actions only after its compact acknowledgement and rematerialized State Flow context.",
624
+ "Use patch_state for durable semantic changes. Before a final answer, make the iteration terminal-eligible with final:true, optionally alongside atomic global/cwd/session patches.",
625
+ "Call patch_state alone in an assistant response; after its acknowledgement, further reasoning, tools, and later patch_state calls remain allowed.",
509
626
  ],
510
627
  executionMode: "sequential",
511
628
  parameters: Type.Object({
512
- scope: StringEnum(["session", "cwd", "global"] as const),
513
- patch: Type.Record(Type.String(), Type.Unknown()),
629
+ global: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional global semantic patch" })),
630
+ cwd: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional project semantic patch" })),
631
+ session: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional session semantic patch" })),
632
+ final: Type.Optional(Type.Boolean({ description: "Set exactly true to permit this iteration to finish at a later turn_end" })),
514
633
  }, { additionalProperties: false }),
515
- async execute(_toolCallId, params, signal, _onUpdate, ctx) {
516
- if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
517
- if (signal?.aborted) throw new Error("State Flow patch was aborted before materialization");
518
- const transition = { scope: params.scope as StateScope, patch: params.patch as ScopePatch };
519
- const stage = stageScopedPatch(
520
- scopeStates,
521
- transition,
522
- skillReads.successful.values(),
523
- runtime!.causalBasis(),
524
- artifactReads.successful.values(),
525
- );
526
- commitStage(stage, ctx, false);
527
- updateUi(ctx);
528
- const publication = pendingPublication === undefined ? "" : "; durable publication pending";
529
- return {
530
- content: [{ type: "text", text: `\nState materialized at ${params.scope} scope${publication}.` }],
531
- details: { scope: params.scope, step: snapshot.meta.step },
532
- };
634
+ async execute(toolCallId, params, signal, _onUpdate, ctx) {
635
+ try {
636
+ if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
637
+ if (signal?.aborted) throw new Error("State Flow patch was aborted before materialization");
638
+ if (!isObject(params)) throw new Error("patch_state requires an object");
639
+ const allowed = new Set(["global", "cwd", "session", "final"]);
640
+ for (const key of Object.keys(params)) {
641
+ if (!allowed.has(key)) throw new Error(`patch_state does not accept field ${key}`);
642
+ }
643
+ if (Object.hasOwn(params, "final") && params.final !== true) throw new Error("patch_state final must be exactly true when supplied");
644
+ const patches: AtomicScopePatches = {};
645
+ for (const scope of ["global", "cwd", "session"] as const) {
646
+ if (!Object.hasOwn(params, scope)) continue;
647
+ const patch = params[scope];
648
+ if (!isObject(patch)) throw new Error(`patch_state ${scope} must be a semantic patch object`);
649
+ if (Object.keys(patch).length === 0) throw new Error(`patch_state ${scope} cannot be empty; omit it when unchanged`);
650
+ patches[scope] = patch;
651
+ }
652
+ const scopes = Object.keys(patches) as StateScope[];
653
+ if (scopes.length === 0) {
654
+ if (params.final !== true) throw new Error('patch_state requires at least one scope patch or {"final":true}');
655
+ validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
656
+ terminalEligible = true;
657
+ terminalDraftIntercepted = false;
658
+ return { content: [{ type: "text", text: "\nState iteration is terminal-eligible." }], details: { final: true } };
659
+ }
660
+ const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
661
+ const semanticChange = (["global", "cwd", "session"] as const).some((scope) => !sameJson(scopeStates[scope], stage.nextStates[scope]));
662
+ const provenanceChange = Object.values(stage.provenanceUpdates).some((updates) => Object.keys(updates).length > 0);
663
+ if (!semanticChange && !provenanceChange) throw new Error('patch_state scope patches must materially update state or required provenance; omit them and use {"final":true} when unchanged');
664
+ commitStage(stage, ctx, false);
665
+ if (params.final === true) {
666
+ terminalEligible = true;
667
+ terminalDraftIntercepted = false;
668
+ }
669
+ updateUi(ctx);
670
+ const publication = pendingPublication === undefined ? "" : "; durable publication pending";
671
+ return { content: [{ type: "text", text: `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}${publication}.` }], details: { scopes, final: params.final === true, step: snapshot.meta.step } };
672
+ } catch (error) {
673
+ let attempted: unknown;
674
+ try { attempted = structuredClone(params); } catch { attempted = undefined; }
675
+ recordDiagnostic(error instanceof Error ? error.message : String(error), /concurrently|advanced/.test(String(error)) ? "publication-conflict" : "invalid-patch", ctx, {
676
+ input: attempted,
677
+ tool: PATCH_STATE_TOOL_NAME,
678
+ toolCallId,
679
+ resolutionAttempt: resolutionAttempts,
680
+ terminalEligible,
681
+ });
682
+ throw separatedFailure(error);
683
+ }
533
684
  },
534
685
  });
535
686
 
@@ -538,6 +689,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
538
689
  handler: async (_args, ctx) => {
539
690
  if (!activeContext) restoreActiveBranch(ctx);
540
691
  const previousSnapshot = structuredClone(snapshot);
692
+ const previousPassiveContinuation = passiveContinuation;
693
+ const previousBootstrapContinuation = bootstrapContinuation;
694
+ const previousArtifactRefreshPending = artifactRefreshPending;
695
+ const previousArtifactInvalidations = structuredClone(artifactInvalidations);
541
696
  try {
542
697
  if (!runtime?.view && !snapshot.meta.durableBase && !branchStartsWithoutRuntime) {
543
698
  throw new Error("Selected branch revision is unavailable; restore its original Git history before starting State Flow");
@@ -547,7 +702,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
547
702
  runtime ??= createRuntime(ctx);
548
703
  if (branchStartsWithoutRuntime) runtime.prepare();
549
704
  const bootstrap = (!branchHasSnapshot || !snapshot.config.enabled)
550
- && hasPriorConversation(branch);
705
+ && (hasPriorConversation(branch) || previousPassiveContinuation !== undefined);
551
706
  if (!runtime.view && snapshot.meta.durableBase) {
552
707
  snapshot = runtime.restore(snapshot.meta.durableBase, snapshot);
553
708
  setPendingPublication(snapshot.meta.pendingPublication);
@@ -566,11 +721,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
566
721
  const publication = runtime.view
567
722
  ? runtime.promote(snapshot) ?? runtime.publish(snapshot)
568
723
  : runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
569
- if (publication) recordPublication(publication, ctx);
724
+ recordPolicyPublication(publication, ctx);
570
725
  installScopeStates();
571
726
  delete snapshot.legacySession;
572
727
  clearRunTransient();
573
- refreshArtifactInvalidations(ctx);
728
+ passiveContinuation = undefined;
729
+ bootstrapContinuation = snapshot.meta.bootstrap
730
+ ? previousPassiveContinuation ?? previousBootstrapContinuation
731
+ : undefined;
732
+ deferArtifactRefresh();
574
733
  syncStateFlowTools();
575
734
  persist();
576
735
  updateUi(ctx);
@@ -582,6 +741,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
582
741
  );
583
742
  } catch (error) {
584
743
  snapshot = previousSnapshot;
744
+ passiveContinuation = previousPassiveContinuation;
745
+ bootstrapContinuation = previousBootstrapContinuation;
746
+ artifactRefreshPending = previousArtifactRefreshPending;
747
+ artifactInvalidations = previousArtifactInvalidations;
748
+ artifactReads.setCandidates(artifactInvalidations);
585
749
  syncStateFlowTools();
586
750
  ctx.ui.notify(
587
751
  `State Flow could not initialize CWD state: ${error instanceof Error ? error.message : String(error)}`,
@@ -608,6 +772,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
608
772
  selected = createRuntime(ctx);
609
773
  current = selected.restore(snapshot.meta.durableBase, snapshot);
610
774
  }
775
+ const stoppedAt = Date.now();
776
+ const exitStates = selected?.view ? selected.states() : undefined;
777
+ const exitHandoff = current.config.enabled && exitStates
778
+ ? createPassiveContinuation(
779
+ projectStateForModel(overlayStates(exitStates.global, exitStates.cwd, exitStates.session)),
780
+ stoppedAt,
781
+ )
782
+ : undefined;
783
+ const retainedHandoff = exitHandoff ?? (!current.config.enabled ? passiveContinuation : undefined);
611
784
  const stopped = stopEpisode(current);
612
785
  const publication = selected?.view ? selected.publish(stopped) : undefined;
613
786
  if (selected !== runtime) {
@@ -615,24 +788,34 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
615
788
  installScopeStates();
616
789
  }
617
790
  snapshot = stopped;
618
- if (publication) recordPublication(publication, ctx);
791
+ recordPolicyPublication(publication, ctx);
619
792
  branchHasSnapshot = true;
620
793
  clearRunTransient();
794
+ passiveContinuation = retainedHandoff;
795
+ bootstrapContinuation = undefined;
796
+ artifactInvalidations = [];
797
+ artifactReads.setCandidates([]);
798
+ artifactRefreshPending = false;
799
+ if (exitHandoff) pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { at: stoppedAt });
621
800
  syncStateFlowTools();
622
801
  persist();
623
802
  updateUi(ctx);
624
803
  },
625
804
  });
626
805
 
627
- pi.on("before_agent_start", (event) => {
806
+ pi.on("before_agent_start", (event, ctx) => {
628
807
  if (!snapshot.config.enabled) return;
629
- if (!retryQueued) {
630
- skillReads.clear();
631
- artifactReads.clear();
632
- }
633
- const rotatesRun = snapshot.meta.specification !== undefined && !retryQueued;
634
- if (rotatesRun) rehydrationPhase = "step";
635
- if (prepareRun(snapshot, event.prompt, retryQueued)) {
808
+ skillReads.clear();
809
+ artifactReads.clear();
810
+ if (artifactRefreshPending) refreshArtifactInvalidations(ctx);
811
+ terminalEligible = false;
812
+ terminalDraftIntercepted = false;
813
+ resolutionAttempts = 0;
814
+ resolutionFailureReported = false;
815
+ responseAwaitingReconciliation = false;
816
+ const rotatesRun = snapshot.meta.specification !== undefined;
817
+ if (rotatesRun && rehydrationPhase !== "new-bootstrap" && rehydrationPhase !== "resume-bootstrap") rehydrationPhase = "step";
818
+ if (prepareRun(snapshot, event.prompt)) {
636
819
  if (rotatesRun) runAnchorTimestamp = undefined;
637
820
  persist();
638
821
  }
@@ -642,16 +825,23 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
642
825
  });
643
826
 
644
827
  pi.on("context", (event) => {
828
+ if (passiveContinuation) {
829
+ return { messages: passiveContinuationMessages(event.messages as AgentMessage[], passiveContinuation) };
830
+ }
645
831
  if (!snapshot.config.enabled || snapshot.meta.specification === undefined) return;
646
- const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
832
+ const effectiveState = projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session));
833
+ const invalidations = artifactInvalidations.map(({ path, reason }) => ({ path, reason }));
647
834
  const recentTransitions = projectRecentTransitionsWithLimit(
648
- snapshot.config.transitionWindow,
835
+ RECENT_TRANSITION_LIMIT,
649
836
  runtime?.recent() ?? [],
650
837
  );
651
838
  const activeRehydrationPhase = currentRehydrationPhase();
652
839
  if (snapshot.meta.bootstrap) {
653
- const messages = withoutPrivateValidation(event.messages as AgentMessage[]);
654
- return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, artifactInvalidations, activeRehydrationPhase), ...messages] };
840
+ const sourceMessages = bootstrapContinuation
841
+ ? passiveContinuationMessages(event.messages as AgentMessage[], bootstrapContinuation)
842
+ : event.messages as AgentMessage[];
843
+ const messages = withoutPrivateValidation(sourceMessages);
844
+ return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, terminalDraftIntercepted), ...messages] };
655
845
  }
656
846
  const trajectory = currentRunTrajectory(
657
847
  event.messages as AgentMessage[],
@@ -661,7 +851,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
661
851
  runAnchorTimestamp = trajectory.anchorTimestamp;
662
852
  return {
663
853
  messages: [
664
- runtimeContextMessage(snapshot, effectiveState, recentTransitions, artifactInvalidations, activeRehydrationPhase),
854
+ runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, terminalDraftIntercepted),
665
855
  ...trajectory.messages,
666
856
  ],
667
857
  };
@@ -705,70 +895,80 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
705
895
 
706
896
  pi.on("message_end", (event, ctx): any => {
707
897
  if (!snapshot.config.enabled || event.message.role !== "assistant") return;
708
- stagedFinal = undefined;
709
898
  const message = event.message as unknown as { role: "assistant"; stopReason?: string; content?: unknown };
710
- if (message.stopReason === "aborted") {
711
- abandonRun(ctx);
899
+ if (message.stopReason === "aborted" || assistantToolCallCount(message.content) > 0 || message.stopReason === "toolUse") {
900
+ responseAwaitingReconciliation = false;
712
901
  return;
713
902
  }
714
903
  if (message.stopReason === "length" || message.stopReason === "error") {
715
- return rejectTerminal(message, `Assistant response ended with ${message.stopReason}`, ctx);
904
+ responseAwaitingReconciliation = false;
905
+ recordDiagnostic(`Assistant response ended with ${message.stopReason}`, "finalization", ctx, { content: message.content, terminalEligible });
906
+ return;
716
907
  }
717
- if (assistantToolCallCount(message.content) > 0 || message.stopReason === "toolUse") {
718
- retryQueued = snapshot.meta.validation !== undefined;
719
- const cleaned = stripStateComments(message.content);
720
- return cleaned.changed
721
- ? { message: { ...message, role: "assistant" as const, content: cleaned.content } }
722
- : undefined;
908
+ if (!terminalEligible) {
909
+ responseAwaitingReconciliation = false;
910
+ terminalDraftIntercepted = true;
911
+ resolutionAttempts = Math.min(MAX_RESOLUTION_ATTEMPTS, resolutionAttempts + 1);
912
+ recordDiagnostic(`Terminal draft intercepted before State Flow eligibility (attempt ${resolutionAttempts}/${MAX_RESOLUTION_ATTEMPTS})`, "terminal-pending", ctx, {
913
+ content: message.content,
914
+ resolutionAttempt: resolutionAttempts,
915
+ terminalEligible,
916
+ });
917
+ if (resolutionAttempts < MAX_RESOLUTION_ATTEMPTS) {
918
+ continueForResolution();
919
+ } else if (!resolutionFailureReported) {
920
+ resolutionFailureReported = true;
921
+ ctx.ui.notify(`State Flow could not obtain final:true after ${MAX_RESOLUTION_ATTEMPTS} terminal attempts; committed state was preserved and no draft was accepted.`, "error");
922
+ }
923
+ return { message: { ...message, role: "assistant" as const, content: [] } };
723
924
  }
724
925
  try {
725
- const parsed = parseTerminalPatch(message.content);
726
- stagedFinal = stageScopedTransition(
727
- scopeStates,
728
- parsed.transition,
729
- skillReads.successful.values(),
730
- runtime!.causalBasis(),
731
- artifactReads.successful.values(),
732
- );
733
- retryQueued = false;
734
- return { message: { ...message, role: "assistant" as const, content: parsed.responseContent } };
926
+ validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
735
927
  } catch (error) {
736
- return rejectTerminal(message, error instanceof Error ? error.message : String(error), ctx);
928
+ responseAwaitingReconciliation = false;
929
+ terminalDraftIntercepted = true;
930
+ recordDiagnostic(error instanceof Error ? error.message : String(error), "terminal-pending", ctx, { content: message.content, terminalEligible });
931
+ continueForResolution();
932
+ return { message: { ...message, role: "assistant" as const, content: [] } };
737
933
  }
934
+ responseAwaitingReconciliation = true;
738
935
  });
739
936
 
740
937
  pi.on("turn_end", (event, ctx) => {
741
- if (!snapshot.config.enabled || !stagedFinal) {
938
+ if (!snapshot.config.enabled || !responseAwaitingReconciliation) {
742
939
  updateUi(ctx);
743
940
  return;
744
941
  }
745
942
  try {
746
- stagedFinal.nextStates.session.response = finalizedAssistantResponse(event.message);
747
- commitStage(stagedFinal, ctx, true);
943
+ const response = finalizedAssistantResponse(event.message);
944
+ const stage = stageScopedTransition(scopeStates, { transitions: [], response }, [], runtime!.causalBasis());
945
+ commitStage(stage, ctx, true);
946
+ bootstrapContinuation = undefined;
947
+ rehydrationPhase = "step";
748
948
  enqueueTurnPublication();
749
949
  if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
750
950
  } catch (error) {
751
- queueTerminalRegeneration(error instanceof Error ? error.message : String(error), ctx);
951
+ recordDiagnostic(error instanceof Error ? error.message : String(error), "finalization", ctx);
952
+ ctx.ui.notify(`State Flow could not reconcile the final response: ${error instanceof Error ? error.message : String(error)}`, "error");
953
+ } finally {
954
+ responseAwaitingReconciliation = false;
955
+ terminalDraftIntercepted = false;
752
956
  }
753
- stagedFinal = undefined;
754
957
  updateUi(ctx);
755
958
  });
756
959
 
757
- pi.on("agent_settled", (_event, ctx) => {
758
- if (snapshot.config.enabled && retryQueued) abandonRun(ctx);
960
+ pi.on("agent_settled", (_event, _ctx) => {
759
961
  if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
760
962
  });
761
963
 
762
964
  pi.on("session_start", (event, ctx) => {
763
965
  rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
764
966
  restoreActiveBranch(ctx, event.reason);
765
- refreshArtifactInvalidations(ctx);
766
967
  retryPendingPush(ctx);
767
968
  if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
768
969
  updateUi(ctx);
769
970
  });
770
971
  pi.on("session_tree", (_event, ctx) => {
771
972
  restoreActiveBranch(ctx);
772
- refreshArtifactInvalidations(ctx);
773
973
  });
774
974
  }