@llblab/pi-state-flow 0.14.0 → 0.16.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.
Files changed (48) hide show
  1. package/AGENTS.md +4 -4
  2. package/BACKLOG.md +3 -1
  3. package/CHANGELOG.md +16 -0
  4. package/README.md +5 -2
  5. package/dist/lib/durable.d.ts +1 -1
  6. package/dist/lib/durable.js +7 -0
  7. package/dist/lib/extension.d.ts +2 -4
  8. package/dist/lib/extension.js +31 -239
  9. package/dist/lib/history.js +1 -1
  10. package/dist/lib/logging.d.ts +18 -0
  11. package/dist/lib/logging.js +44 -1
  12. package/dist/lib/migration.d.ts +2 -2
  13. package/dist/lib/migration.js +21 -3
  14. package/dist/lib/protocol.d.ts +7 -0
  15. package/dist/lib/protocol.js +55 -5
  16. package/dist/lib/publication.d.ts +17 -0
  17. package/dist/lib/publication.js +102 -0
  18. package/dist/lib/query.d.ts +16 -0
  19. package/dist/lib/query.js +98 -12
  20. package/dist/lib/session.d.ts +17 -0
  21. package/dist/lib/session.js +38 -0
  22. package/dist/lib/state.d.ts +5 -0
  23. package/dist/lib/state.js +10 -2
  24. package/dist/lib/telegram.d.ts +1 -0
  25. package/dist/lib/telegram.js +1 -1
  26. package/dist/lib/transition.js +4 -3
  27. package/dist/package.json +1 -1
  28. package/dist/skills/state-flow-guide/SKILL.md +79 -0
  29. package/dist/skills/state-flow-memory/SKILL.md +23 -129
  30. package/docs/architecture.md +22 -17
  31. package/docs/compatibility.md +1 -1
  32. package/docs/lazy-state.md +15 -6
  33. package/docs/usage.md +2 -2
  34. package/lib/durable.ts +6 -1
  35. package/lib/extension.ts +33 -228
  36. package/lib/history.ts +1 -1
  37. package/lib/logging.ts +53 -1
  38. package/lib/migration.ts +18 -4
  39. package/lib/protocol.ts +51 -5
  40. package/lib/publication.ts +96 -0
  41. package/lib/query.ts +99 -11
  42. package/lib/session.ts +45 -0
  43. package/lib/state.ts +13 -2
  44. package/lib/telegram.ts +2 -1
  45. package/lib/transition.ts +4 -3
  46. package/package.json +1 -1
  47. package/skills/state-flow-guide/SKILL.md +79 -0
  48. package/skills/state-flow-memory/SKILL.md +23 -129
package/lib/extension.ts CHANGED
@@ -4,27 +4,24 @@ import { StringEnum, Type } from "@earendil-works/pi-ai";
4
4
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
5
5
  import { getAgentDir } from "@earendil-works/pi-coding-agent";
6
6
  import { Text } from "@earendil-works/pi-tui";
7
- import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./protocol.ts";
7
+ import { assistantToolCallCount, finalizedAssistantResponse, formatPatchStateArguments, normalizePatchStateArguments, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.ts";
8
8
  import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, runtimeContextMessage, syntheticUser, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
9
9
  import { ArtifactReadTracker } from "./acquisition.ts";
10
10
  import { loadStateFlowConfig } from "./config.ts";
11
11
  import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader } from "./telegram.ts";
12
- import { isAbsolute, relative, resolve, sep } from "node:path";
12
+ import { isAbsolute, resolve } from "node:path";
13
13
  import { SkillReadTracker } from "./skills.ts";
14
14
  import { emptySnapshot, migrationFailure, persistableSnapshot, RevisionUnavailableError, type Snapshot } from "./snapshot.ts";
15
15
  import { readNativeSessionHeader } from "./continuation.ts";
16
16
  import { MissingSessionRuntimeError, SharedScopeRemovalConflictError, TemporalRuntime, type RuntimePublication } from "./runtime.ts";
17
17
  import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
18
18
  import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, validateFinalEligibility, type StagedScopedTransition } from "./transition.ts";
19
- import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
19
+ import { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
20
20
  import { compactStatus, detailedStatus, STATUS_KEY, type PendingPublicationDiagnostic, type StatusDiagnostics } from "./status.ts";
21
21
  import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
22
22
  import { recoverSnapshot } from "./recovery.ts";
23
23
  import type { RehydrationPhase } from "./rehydration.ts";
24
- import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.ts";
25
- import { coalescePublicationTarget, createPublicationQueue, type PublicationQueueState } from "./publication.ts";
26
- import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.ts";
27
- import { runPublicationWorker } from "./publication.ts";
24
+ import { loadPublicationQueue, publicationQueuePath, PublicationWorkerController, resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument, type PublicationQueueState } from "./publication.ts";
28
25
  import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.ts";
29
26
  import { canonicalJson, isObject, sameJson } from "./json.ts";
30
27
  import { readProjectedState, readStatePath } from "./query.ts";
@@ -35,7 +32,7 @@ import {
35
32
  type SessionAddress,
36
33
  } from "./durable.ts";
37
34
  import { projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT } from "./history.ts";
38
- import { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath, type StateFlowDiagnosticCategory } from "./logging.ts";
35
+ import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
39
36
  import { isGitCommitAncestor, pushGitCommit, pushGitTarget, resolveGitPushDestination } from "./git.ts";
40
37
  import {
41
38
  ORDINARY_ARTIFACT_COMPILER,
@@ -54,64 +51,13 @@ export interface StateFlowExtensionOptions {
54
51
  passive?: { bootstrap?: boolean; tools?: boolean };
55
52
  }
56
53
 
54
+ export { formatPatchStateArguments, normalizePatchStateArguments };
55
+
57
56
  export const PATCH_STATE_TOOL_NAME = "patch_state";
58
57
  export const READ_STATE_TOOL_NAME = "read_state";
59
58
  export const MAX_FALLBACK_ATTEMPTS: number = 2;
60
59
  const PASSIVE_STOP_ENTRY_TYPE = "state-flow-passive-stop";
61
60
  const PUBLICATION_SHUTDOWN_WAIT_MS = 2_000;
62
- const PATCH_DISPLAY_SECTION_KEYS = new Set([
63
- "global",
64
- "cwd",
65
- "session",
66
- "artifacts",
67
- "contract",
68
- "working",
69
- "response",
70
- "final",
71
- ]);
72
-
73
- /** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
74
- export function formatPatchStateArguments(args: unknown): string {
75
- const seenAtIndent = new Set<number>();
76
- return JSON.stringify(args, null, 2).split("\n").flatMap((line) => {
77
- const indent = line.length - line.trimStart().length;
78
- const match = /^(\s+)"([^"]+)":/.exec(line);
79
- if (match === null || !PATCH_DISPLAY_SECTION_KEYS.has(match[2])) {
80
- for (const seenIndent of seenAtIndent) {
81
- if (seenIndent > indent) seenAtIndent.delete(seenIndent);
82
- }
83
- return [line];
84
- }
85
- const separator = seenAtIndent.has(indent) ? [""] : [];
86
- seenAtIndent.add(indent);
87
- return [...separator, line];
88
- }).join("\n");
89
- }
90
-
91
- /** Normalize a bounded compatibility superset without advertising aliases in the model-facing contract. */
92
- export function normalizePatchStateArguments(args: unknown): any {
93
- if (!isObject(args) || !Object.hasOwn(args, "final")) return args;
94
- const value = args.final;
95
- let final: boolean;
96
- if (typeof value === "boolean") final = value;
97
- else if (value === 1) final = true;
98
- else if (value === 0) final = false;
99
- else if (typeof value === "string" && value.trim().toLowerCase() === "true") final = true;
100
- else if (typeof value === "string" && value.trim().toLowerCase() === "false") final = false;
101
- else return args;
102
- return { ...args, final };
103
- }
104
-
105
- /** Keep tool output visually separated from its heading with exactly one leading newline. */
106
- function separatedOutput(text: string): string {
107
- return `\n${text.replace(/^\n+/, "")}`;
108
- }
109
-
110
- /** Keep a failed tool invocation visually separated from its rendered error without changing error semantics. */
111
- function separatedFailure(error: unknown): Error {
112
- const message = error instanceof Error ? error.message : String(error);
113
- return new Error(separatedOutput(message), error instanceof Error ? { cause: error } : undefined);
114
- }
115
61
 
116
62
  export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowExtensionOptions = {}): void {
117
63
  const agentDir = options.agentDir ?? getAgentDir();
@@ -145,15 +91,22 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
145
91
  let pendingPublication: PendingPublicationDiagnostic | undefined;
146
92
  let rehydrationPhase: RehydrationPhase | undefined;
147
93
  let turnPublicationTarget: string | undefined;
148
- const activePublicationWorkers = new Map<string, { controller: AbortController; done: Promise<void> }>();
149
- let publicationStopped = false;
150
94
  let publicationShutdown: Promise<void> | undefined;
151
95
  const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
96
+ const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => activeContext?.ui.notify(message, "warning"));
97
+ const publicationWorker = new PublicationWorkerController({
98
+ resolveDestination: () => resolveGitPushDestination(repositoryRoot),
99
+ isAncestor: (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant),
100
+ push: (destination, target, signal) => pushGitTarget(repositoryRoot, destination, target, signal),
101
+ onDiverged: (dropped, target) => activeContext && recordDiagnostic(
102
+ `Retired publication queue target ${dropped.target} after a journal lineage rewrite; retargeting to ${target}`,
103
+ "publication-conflict", activeContext,
104
+ ),
105
+ });
152
106
  const skillReads = new SkillReadTracker();
153
107
  const artifactReads = new ArtifactReadTracker();
154
108
  const globalMarkdown = new GlobalMarkdownDiscovery(options.knowledgeRoot ?? getKnowledgeRoot(agentDir));
155
109
  let artifactInvalidations: ArtifactInvalidationRequest[] = [];
156
- let loggingWarningReported = false;
157
110
  let telegramStartPending = false;
158
111
 
159
112
  function sessionAddress(ctx: ExtensionContext): SessionAddress {
@@ -206,27 +159,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
206
159
  artifactReads.clear();
207
160
  }
208
161
 
209
- function passiveStopBoundary(ctx: ExtensionContext): { at: number; from?: number } | undefined {
210
- for (const entry of [...ctx.sessionManager.getBranch()].reverse()) {
211
- try {
212
- if (entry?.type !== "custom" || entry.customType !== PASSIVE_STOP_ENTRY_TYPE) continue;
213
- const { at, from, reset, owner } = (entry.data as { at?: unknown; from?: unknown; reset?: unknown; owner?: unknown } | undefined) ?? {};
214
- if (reset === true && owner === ctx.sessionManager.getSessionId()) return undefined;
215
- if (typeof at === "number" && Number.isSafeInteger(at) && at >= 0) return {
216
- at,
217
- ...(typeof from === "number" && Number.isSafeInteger(from) && from >= 0 ? { from } : {}),
218
- };
219
- } catch {
220
- // A hostile unrelated branch entry cannot manufacture or suppress a valid marker.
221
- }
222
- }
223
- return undefined;
224
- }
225
-
226
- function retainsPhysicalSessionProjection(reason: unknown): boolean {
227
- return reason === undefined || reason === "startup" || reason === "reload" || reason === "resume";
228
- }
229
-
230
162
  function deferArtifactRefresh(): void {
231
163
  artifactInvalidations = [];
232
164
  artifactReads.setCandidates([]);
@@ -289,21 +221,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
289
221
  : active.filter((name) => !owned.includes(name)));
290
222
  }
291
223
 
292
- function assistantToolBatch(ctx: ExtensionContext, toolCallId: string): string[] | undefined {
293
- for (let cursor = ctx.sessionManager.getLeafEntry(); cursor; cursor = cursor.parentId ? ctx.sessionManager.getEntry(cursor.parentId) : undefined) {
294
- const entry = cursor as { type?: unknown; message?: { role?: unknown; content?: unknown } };
295
- if (entry.type !== "message" || entry.message?.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
296
- const calls = entry.message.content.filter((block): block is { type: "toolCall"; id: string; name: string } => {
297
- return typeof block === "object" && block !== null
298
- && (block as { type?: unknown }).type === "toolCall"
299
- && typeof (block as { id?: unknown }).id === "string"
300
- && typeof (block as { name?: unknown }).name === "string";
301
- });
302
- if (calls.some(({ id }) => id === toolCallId)) return calls.map(({ name }) => name);
303
- }
304
- return undefined;
305
- }
306
-
307
224
  function recordPublication(publication: RuntimePublication, ctx: ExtensionContext): void {
308
225
  const revision = publication.revision ?? publication.commit;
309
226
  if (revision !== undefined) snapshot.meta.durableBase = revision;
@@ -330,8 +247,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
330
247
  if (mode !== "turn-end" || target === undefined || !/^[0-9a-f]{40,64}$/.test(target)) return;
331
248
  turnPublicationTarget = target;
332
249
  try {
333
- enqueueTurnPublication(ctx);
334
- launchPublicationWorker();
250
+ enqueueTurnPublication();
251
+ publicationWorker.launch();
335
252
  } catch (error) {
336
253
  ctx.ui.notify(
337
254
  `State Flow accepted the local commit; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`,
@@ -372,95 +289,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
372
289
  return true;
373
290
  }
374
291
 
375
- function enqueueTurnPublication(ctx: ExtensionContext): void {
292
+ function enqueueTurnPublication(): void {
376
293
  const target = turnPublicationTarget;
377
294
  turnPublicationTarget = undefined;
378
- if (!target) return;
379
- const destination = resolveGitPushDestination(repositoryRoot);
380
- if (!destination) return;
381
- const path = publicationQueuePath(destination);
382
- const previous = loadPublicationQueue(path);
383
- const next = previous
384
- ? coalescePublicationTarget(previous, destination, target, (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant), {
385
- onDivergedLineage: (dropped) => recordDiagnostic(
386
- `Retired publication queue target ${dropped.target} after a journal lineage rewrite; retargeting to ${target}`,
387
- "publication-conflict", ctx,
388
- ),
389
- })
390
- : createPublicationQueue(destination, target);
391
- savePublicationQueue(path, next, previous);
392
- }
393
-
394
- function launchPublicationWorker(): void {
395
- if (publicationStopped) return;
396
- let destination: ReturnType<typeof resolveGitPushDestination>;
397
- try {
398
- destination = resolveGitPushDestination(repositoryRoot);
399
- } catch (error) {
400
- if (error instanceof Error && /ENOENT/.test(error.message)) return;
401
- throw error;
402
- }
403
- if (!destination) return;
404
- const path = publicationQueuePath(destination);
405
- if (activePublicationWorkers.has(path)) return;
406
- let queued: PublicationQueueState | undefined;
407
- let lease: ReturnType<typeof acquirePublicationWorkerLease>;
408
- try {
409
- queued = loadPublicationQueue(path);
410
- if (!queued) return;
411
- lease = acquirePublicationWorkerLease(path);
412
- } catch {
413
- return;
414
- }
415
- if (!lease) return;
416
- const controller = new AbortController();
417
- const done = runPublicationWorker(
418
- queued,
419
- ({ target }) => pushGitTarget(repositoryRoot, destination, target, controller.signal),
420
- () => loadPublicationQueue(path) ?? queued,
421
- (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant),
422
- ).then((result) => {
423
- if (publicationStopped) return; // Late outcomes belong to an unconfirmed queue, not the replacement generation.
424
- const current = loadPublicationQueue(path);
425
- if (!current) return;
426
- if (result.next === undefined) {
427
- if (current.target === result.attempted.target) removePublicationQueue(path, current);
428
- return;
429
- }
430
- if (current.target === result.attempted.target || result.next.target === current.target) {
431
- savePublicationQueue(path, result.next, current);
432
- }
433
- }).catch(() => {
434
- // Queue/CAS truth remains durable; status and a later activation expose retry.
435
- }).finally(() => {
436
- activePublicationWorkers.delete(path);
437
- try {
438
- lease.release();
439
- if (!publicationStopped && loadPublicationQueue(path)?.status === "pending") launchPublicationWorker();
440
- } catch {
441
- // Failed lease cleanup or malformed persistence stays inert until retry or repair.
442
- }
443
- });
444
- activePublicationWorkers.set(path, { controller, done });
295
+ if (target) publicationWorker.enqueue(target);
445
296
  }
446
297
 
447
298
  function shutdownPublicationWorkers(ctx: ExtensionContext): Promise<void> {
448
- publicationStopped = true;
449
- return publicationShutdown ??= (async () => {
450
- const workers = [...activePublicationWorkers.values()];
451
- for (const { controller } of workers) controller.abort();
452
- if (workers.length === 0) return;
453
- let timeout: ReturnType<typeof setTimeout> | undefined;
454
- try {
455
- const completed = await Promise.race([
456
- Promise.all(workers.map(({ done }) => done)).then(() => true),
457
- new Promise<false>((resolve) => { timeout = setTimeout(() => resolve(false), PUBLICATION_SHUTDOWN_WAIT_MS); }),
458
- ]);
459
- if (!completed) ctx.ui.notify(`State Flow push cleanup is unconfirmed after ${PUBLICATION_SHUTDOWN_WAIT_MS}ms; worker leases remain held until child exit.`, "warning");
460
- } finally {
461
- clearTimeout(timeout);
462
- }
463
- })();
299
+ return publicationShutdown ??= publicationWorker.shutdown(PUBLICATION_SHUTDOWN_WAIT_MS).then((completed) => {
300
+ if (!completed) ctx.ui.notify(`State Flow push cleanup is unconfirmed after ${PUBLICATION_SHUTDOWN_WAIT_MS}ms; worker leases remain held until child exit.`, "warning");
301
+ });
464
302
  }
465
303
 
466
304
  function retryPendingPush(ctx: ExtensionContext): void {
@@ -472,8 +310,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
472
310
  if (mode === "turn-end") {
473
311
  turnPublicationTarget = target;
474
312
  try {
475
- enqueueTurnPublication(ctx);
476
- launchPublicationWorker();
313
+ enqueueTurnPublication();
314
+ publicationWorker.launch();
477
315
  } catch (error) {
478
316
  ctx.ui.notify(`State Flow retained local state; asynchronous publication recovery is deferred: ${error instanceof Error ? error.message : String(error)}`, "warning");
479
317
  }
@@ -681,7 +519,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
681
519
  ctx.ui.notify(`State Flow restored disabled: ${snapshot.meta.validation.error}`, "error");
682
520
  }
683
521
  if (retainsPhysicalSessionProjection(sessionStartReason) && runtime?.view) {
684
- const boundary = passiveStopBoundary(ctx);
522
+ const boundary = findPassiveStopBoundary(ctx.sessionManager.getBranch(), ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE);
685
523
  if (boundary !== undefined) {
686
524
  const continuation = createPassiveContinuation(
687
525
  projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)),
@@ -705,41 +543,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
705
543
  updateUi(ctx);
706
544
  }
707
545
 
708
- interface DiagnosticExtras {
709
- content?: unknown;
710
- input?: unknown;
711
- tool?: string;
712
- toolCallId?: string;
713
- resolutionAttempt?: number;
714
- terminalEligible?: boolean;
715
- }
716
-
717
546
  function recordDiagnostic(error: string, category: StateFlowDiagnosticCategory, ctx: ExtensionContext, extras: DiagnosticExtras = {}): void {
718
- if (!config.logging) return;
719
- try {
720
- const path = stateFlowLogPath(agentDir);
721
- const fromRepository = relative(repositoryRoot, path);
722
- if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
723
- throw new Error("diagnostic path overlaps the State Flow repository");
724
- }
725
- appendStateFlowDiagnostic(path, {
726
- at: new Date().toISOString(),
727
- sessionId: sessionAddress(ctx).id,
728
- cwd: resolve(ctx.cwd),
729
- category,
730
- error,
731
- ...(extras.content === undefined ? {} : { content: projectDiagnosticContent(extras.content) }),
732
- ...(extras.input === undefined ? {} : { input: extras.input }),
733
- ...(extras.tool === undefined ? {} : { tool: extras.tool }),
734
- ...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
735
- ...(extras.resolutionAttempt === undefined ? {} : { resolutionAttempt: extras.resolutionAttempt }),
736
- ...(extras.terminalEligible === undefined ? {} : { terminalEligible: extras.terminalEligible }),
737
- });
738
- } catch (failure) {
739
- if (loggingWarningReported) return;
740
- loggingWarningReported = true;
741
- ctx.ui.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`, "warning");
742
- }
547
+ diagnosticWriter.record(sessionAddress(ctx).id, ctx.cwd, error, category, extras);
743
548
  }
744
549
 
745
550
  function continueFallbackResolution(lastWarning: boolean): void {
@@ -1193,7 +998,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1193
998
 
1194
999
  pi.on("tool_call", (event, ctx) => {
1195
1000
  if (!snapshot.config.enabled) return;
1196
- const batch = assistantToolBatch(ctx, event.toolCallId);
1001
+ const batch = findAssistantToolBatch(ctx.sessionManager, event.toolCallId);
1197
1002
  const patchCalls = batch?.filter((name) => name === PATCH_STATE_TOOL_NAME).length ?? 0;
1198
1003
  if (patchCalls > 0) {
1199
1004
  if (patchCalls !== 1) {
@@ -1264,8 +1069,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1264
1069
  responseCommitted = true;
1265
1070
  bootstrapContinuation = undefined;
1266
1071
  rehydrationPhase = "step";
1267
- enqueueTurnPublication(ctx);
1268
- if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
1072
+ enqueueTurnPublication();
1073
+ if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
1269
1074
  completedRunAccepted = !wasBootstrap;
1270
1075
  } catch (error) {
1271
1076
  if (!responseCommitted && specification !== undefined) snapshot.meta.specification = specification;
@@ -1292,7 +1097,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1292
1097
  telegramStartPending = false;
1293
1098
  startStateFlow(ctx);
1294
1099
  }
1295
- if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
1100
+ if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
1296
1101
  if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap || resolutionPending
1297
1102
  || compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase
1298
1103
  || !shouldRequestStateFlowCompaction(ctx.getContextUsage())) return;
@@ -1314,7 +1119,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1314
1119
  rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
1315
1120
  restoreActiveBranch(ctx, event.reason);
1316
1121
  retryPendingPush(ctx);
1317
- if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
1122
+ if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
1318
1123
  updateUi(ctx);
1319
1124
  void telegram.ensure();
1320
1125
  });
package/lib/history.ts CHANGED
@@ -22,7 +22,7 @@ export interface RecentTransition extends AcceptedTransition {
22
22
 
23
23
  export type RecentTransitionWindow = RecentTransition[];
24
24
  const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
25
- const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response", "lazy"]);
25
+ const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "response", "lazy"]);
26
26
 
27
27
  /** Normalize accepted replacements into recursive-merge replay, including removals. */
28
28
  function replayPatch(before: JsonObject, after: JsonObject): JsonObject {
package/lib/logging.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  // Domain: opt-in diagnostic capture for rejected State Flow resolutions.
2
2
  import { appendFileSync, mkdirSync } from "node:fs";
3
- import { dirname, join } from "node:path";
3
+ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
4
  import { isObject } from "./json.ts";
5
5
 
6
6
  export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "terminal-pending" | "finalization";
@@ -45,3 +45,55 @@ export function appendStateFlowDiagnostic(path: string, record: StateFlowDiagnos
45
45
  mkdirSync(dirname(path), { recursive: true });
46
46
  appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
47
47
  }
48
+
49
+ export interface DiagnosticExtras {
50
+ content?: unknown;
51
+ input?: unknown;
52
+ tool?: string;
53
+ toolCallId?: string;
54
+ resolutionAttempt?: number;
55
+ terminalEligible?: boolean;
56
+ }
57
+
58
+ /** Own diagnostic path safety, projection, persistence, and one-shot failure reporting. */
59
+ export class StateFlowDiagnosticWriter {
60
+ private warningReported = false;
61
+ private readonly enabled: boolean;
62
+ private readonly path: string;
63
+ private readonly repositoryRoot: string;
64
+ private readonly notify: (message: string) => void;
65
+
66
+ constructor(enabled: boolean, path: string, repositoryRoot: string, notify: (message: string) => void) {
67
+ this.enabled = enabled;
68
+ this.path = path;
69
+ this.repositoryRoot = repositoryRoot;
70
+ this.notify = notify;
71
+ }
72
+
73
+ record(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras = {}): void {
74
+ if (!this.enabled) return;
75
+ try {
76
+ const fromRepository = relative(this.repositoryRoot, this.path);
77
+ if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
78
+ throw new Error("diagnostic path overlaps the State Flow repository");
79
+ }
80
+ appendStateFlowDiagnostic(this.path, {
81
+ at: new Date().toISOString(),
82
+ sessionId,
83
+ cwd: resolve(cwd),
84
+ category,
85
+ error,
86
+ ...(extras.content === undefined ? {} : { content: projectDiagnosticContent(extras.content) }),
87
+ ...(extras.input === undefined ? {} : { input: extras.input }),
88
+ ...(extras.tool === undefined ? {} : { tool: extras.tool }),
89
+ ...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
90
+ ...(extras.resolutionAttempt === undefined ? {} : { resolutionAttempt: extras.resolutionAttempt }),
91
+ ...(extras.terminalEligible === undefined ? {} : { terminalEligible: extras.terminalEligible }),
92
+ });
93
+ } catch (failure) {
94
+ if (this.warningReported) return;
95
+ this.warningReported = true;
96
+ this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
97
+ }
98
+ }
99
+ }
package/lib/migration.ts CHANGED
@@ -13,7 +13,7 @@ import {
13
13
  type OwnedFileUpdate,
14
14
  } from "./durable.ts";
15
15
  import { parseSessionRuntime, serializeSessionRuntime } from "./snapshot.ts";
16
- import type { StateScope } from "./state.ts";
16
+ import { migratePreIntentState, type StateScope } from "./state.ts";
17
17
 
18
18
  export interface LegacyStorageMigration {
19
19
  bases: DurableFileBase[];
@@ -57,9 +57,14 @@ function migrationDirectories(cwd: string, sessionId: string, root: string, sess
57
57
  try { sessionScopeKey(entry.name); } catch { continue; }
58
58
  const directory = join(cwdDirectory, entry.name);
59
59
  let meta: unknown;
60
+ let runtime: unknown;
60
61
  try { meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8")); }
61
62
  catch { continue; }
62
- const identity = meta && typeof meta === "object" && !Array.isArray(meta) ? (meta as { identity?: unknown }).identity : undefined;
63
+ try { runtime = JSON.parse(readFileSync(join(directory, "runtime.json"), "utf8")); }
64
+ catch { /* predecessor sessions keep identity in meta.json */ }
65
+ const identity = meta && typeof meta === "object" && !Array.isArray(meta) && (meta as { identity?: unknown }).identity !== undefined
66
+ ? (meta as { identity?: unknown }).identity
67
+ : runtime && typeof runtime === "object" && !Array.isArray(runtime) ? (runtime as { identity?: unknown }).identity : undefined;
63
68
  if (!identity || typeof identity !== "object" || Array.isArray(identity)) continue;
64
69
  const owner = identity as { cwd?: unknown; sessionId?: unknown };
65
70
  if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0) {
@@ -85,7 +90,14 @@ export function hasCwdMaterialization(cwd: string, repositoryRoot: string): bool
85
90
  return false;
86
91
  }
87
92
 
88
- /** Detect predecessor snapshots or temporal envelopes without mutating the store. */
93
+ function checkpointNeedsIntentMigration(source: string): boolean {
94
+ const checkpoint = JSON.parse(source) as unknown;
95
+ if (migratePreIntentState(checkpoint) !== undefined) return true;
96
+ return checkpoint !== null && typeof checkpoint === "object" && !Array.isArray(checkpoint)
97
+ && migratePreIntentState((checkpoint as { state?: unknown }).state) !== undefined;
98
+ }
99
+
100
+ /** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
89
101
  export function hasLegacyStateSources(
90
102
  cwd: string,
91
103
  sessionId: string,
@@ -94,8 +106,10 @@ export function hasLegacyStateSources(
94
106
  ): boolean {
95
107
  const root = resolve(repositoryRoot);
96
108
  return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory, scope }) => {
97
- if (lstatSync(join(directory, "checkpoint.json"), { throwIfNoEntry: false }) === undefined) return false;
109
+ const checkpointPath = join(directory, "checkpoint.json");
110
+ if (lstatSync(checkpointPath, { throwIfNoEntry: false }) === undefined) return false;
98
111
  try {
112
+ if (checkpointNeedsIntentMigration(readFileSync(checkpointPath, "utf8"))) return true;
99
113
  const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
100
114
  if (meta === null || typeof meta !== "object" || !("temporal" in meta)) return true;
101
115
  return scope === "session"
package/lib/protocol.ts CHANGED
@@ -1,7 +1,50 @@
1
1
  import type { AgentMessage } from "@earendil-works/pi-agent-core";
2
+ import { isObject } from "./json.ts";
2
3
 
3
4
  export type { StateDocument } from "./state.ts";
4
5
 
6
+ const PATCH_DISPLAY_SECTION_KEYS = new Set(["global", "cwd", "session", "artifacts", "contract", "working", "response", "final"]);
7
+
8
+ /** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
9
+ export function formatPatchStateArguments(args: unknown): string {
10
+ const seenAtIndent = new Set<number>();
11
+ return JSON.stringify(args, null, 2).split("\n").flatMap((line) => {
12
+ const indent = line.length - line.trimStart().length;
13
+ const match = /^(\s+)"([^"]+)":/.exec(line);
14
+ if (match === null || !PATCH_DISPLAY_SECTION_KEYS.has(match[2])) {
15
+ for (const seenIndent of seenAtIndent) if (seenIndent > indent) seenAtIndent.delete(seenIndent);
16
+ return [line];
17
+ }
18
+ const separator = seenAtIndent.has(indent) ? [""] : [];
19
+ seenAtIndent.add(indent);
20
+ return [...separator, line];
21
+ }).join("\n");
22
+ }
23
+
24
+ /** Normalize a bounded compatibility superset without advertising aliases in the model-facing contract. */
25
+ export function normalizePatchStateArguments(args: unknown): any {
26
+ if (!isObject(args) || !Object.hasOwn(args, "final")) return args;
27
+ const value = args.final;
28
+ let final: boolean;
29
+ if (typeof value === "boolean") final = value;
30
+ else if (value === 1) final = true;
31
+ else if (value === 0) final = false;
32
+ else if (typeof value === "string" && value.trim().toLowerCase() === "true") final = true;
33
+ else if (typeof value === "string" && value.trim().toLowerCase() === "false") final = false;
34
+ else return args;
35
+ return { ...args, final };
36
+ }
37
+
38
+ /** Keep visible tool output separated from its heading without changing semantics. */
39
+ export function separatedOutput(text: string): string {
40
+ return `\n${text.replace(/^\n+/, "")}`;
41
+ }
42
+
43
+ export function separatedFailure(error: unknown): Error {
44
+ const message = error instanceof Error ? error.message : String(error);
45
+ return new Error(separatedOutput(message), error instanceof Error ? { cause: error } : undefined);
46
+ }
47
+
5
48
  function baselineMemoryProtocol(): string {
6
49
  return "MEMORY: State Flow owns durable memory while enabled. Put established cross-project/user/environment knowledge in global, reusable project truth in cwd, and branch/run continuation in session. Treat every patch as reconciliation rather than append-only notes: use the narrowest scope; merge superseded fragments; remove obsolete progress. Exclude secrets, raw history, transient progress, speculation, and unsupported claims; retain uncertainty only when decision-relevant.";
7
50
  }
@@ -13,25 +56,28 @@ export function stateFlowProtocol(bootstrap: boolean): string {
13
56
  : "";
14
57
  return `State Flow is enabled.
15
58
  ${bootstrapProtocol}
16
- STATE: {"artifacts":{},"contract":{},"working":{},"response":"latest complete answer"}
59
+ STATE: {"artifacts":{},"contract":{},"working":{},"intents":{},"response":"latest complete answer"}
17
60
  - artifacts: source-path routing metadata; descriptions do not imply body acquisition.
18
61
  - contract: durable requirements, decisions, rejections, interfaces, compiled knowledge.
19
62
  - working: facts, validation, failures, domain state, unresolved work, continuation.
63
+ - intents: active commitments; remove when fulfilled, abandoned, superseded, or impossible.
20
64
  - response: previous complete answer; runtime-owned.
21
65
 
22
- READ: Use read_state only for a concrete historical/scope gap. lazy_navigation gives the effective lazy root and bounded key kinds, never bodies or a partial catalog. Unscoped paths alias effective; effective/global/cwd/session select overlay or owner. Paths read cached values; arrays support zero-based indices and half-open [start..end]. keys returns minimal structure; patch returns the path-intersected change.
66
+ READ: Use read_state for concrete scope/history gaps. lazy_navigation exposes the effective lazy root's bounded key kinds, not bodies. Unscoped paths alias effective; effective/global/cwd/session select overlay or owner. Arrays support indices and [start..end]; keys gives structure and patch the intersected change.
23
67
 
24
68
  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.
25
69
 
26
- FINAL: Every enabled iteration starts terminal-ineligible. A successful patch_state with final:true permits a later turn_end but does not stop reasoning, tools, or later patches. Use {"final":true} if state needs no change. Without eligibility, runtime preserves the terminal answer and starts at most two fallback turns solely for a final:true patch; never restate or replace that answer. Exhaustion closes with the preserved answer/current state. A final-only call creates no semantic transition. Never patch response; runtime records the delivered answer.
70
+ FINAL: Every enabled iteration starts terminal-ineligible. Successful patch_state final:true permits a later turn_end without stopping later work; use {"final":true} when no state change is needed. Otherwise runtime preserves the answer and allows at most two fallback turns only for final:true; never restate it. A final-only call creates no transition. Runtime owns response.
71
+
72
+ 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.
27
73
 
28
74
  SCOPES: global=cross-project; cwd=project and Skills; session=branch/run. Deleting an override may reveal its parent.
29
75
 
30
76
  ${baselineMemoryProtocol()}
31
77
 
32
- PATCH: Optional global/cwd/session object patches plus optional final:true; require at least one. Omit empty/materially no-op scopes. Semantic fields are object-valued artifacts/contract/working and ordinary-JSON lazy; omitted fields persist. Never patch runtime config/meta/response. Objects merge recursively; arrays/primitives replace. An object containing only canonical "[N]" keys recursively patches array elements. Indexed deletion is forbidden; nested object null deletes; materialized null is forbidden.
78
+ PATCH: Optional global/cwd/session object patches plus optional final:true; require at least one. Omit empty/materially no-op scopes. Semantic fields are object-valued artifacts/contract/working/intents and ordinary-JSON lazy; omitted fields persist. Never patch runtime config/meta/response. Objects merge recursively; arrays/primitives replace. An object containing only canonical "[N]" keys recursively patches array elements. Indexed deletion is forbidden; nested object null deletes; materialized null is forbidden.
33
79
 
34
- HANDOFF: Preserve active commitments, unresolved questions, consequential results, and exact continuation. Distinguish requirements, decisions, observations, conclusions, and hypotheses. Before final handoff curate touched and obviously stale/mis-scoped state. On feature/release/campaign or project/version completion, do one bounded reconciliation: remove obsolete work, retain operative consequences, and use targeted read_state plus destination-verify-source-delete for ownership moves. Never invent memory changes or restyle unrelated state.
80
+ HANDOFF: Preserve active commitments, open questions, consequential results, and exact continuation; distinguish requirements, decisions, observations, conclusions, and hypotheses. Curate touched and obviously stale/mis-scoped state. At feature/release/campaign or project/version completion, reconcile once: remove obsolete work, retain consequences, and use targeted read_state plus destination-verify-source-delete for moves. Never invent memory changes.
35
81
 
36
82
  ACQUISITION: Start materialized. Read only for a compilation gap, exact source/edit, invalidation, contradiction/failure, or explicit request; changed hashes require rereading.
37
83
  ARTIFACTS: For each acquired new/invalidated ordinary artifact, patch global.artifacts[exact path] with a compact non-empty description. Runtime owns provenance.