@llblab/pi-state-flow 0.15.0 → 0.16.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/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 {
@@ -977,8 +782,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
977
782
  );
978
783
  }
979
784
  branchHasSnapshot = true;
785
+ // Activation reasserts the selected session stream as a complete cohort. A resumed
786
+ // branch may have no reusable temporal revision after an extension upgrade; a
787
+ // runtime-only write would then reject its selected session as an omitted change.
980
788
  const publication = runtime.view
981
- ? runtime.promote(snapshot) ?? runtime.publish(snapshot)
789
+ ? runtime.promote(snapshot) ?? runtime.publish(snapshot, true)
982
790
  : runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
983
791
  recordPolicyPublication(publication, ctx);
984
792
  installScopeStates();
@@ -1193,7 +1001,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1193
1001
 
1194
1002
  pi.on("tool_call", (event, ctx) => {
1195
1003
  if (!snapshot.config.enabled) return;
1196
- const batch = assistantToolBatch(ctx, event.toolCallId);
1004
+ const batch = findAssistantToolBatch(ctx.sessionManager, event.toolCallId);
1197
1005
  const patchCalls = batch?.filter((name) => name === PATCH_STATE_TOOL_NAME).length ?? 0;
1198
1006
  if (patchCalls > 0) {
1199
1007
  if (patchCalls !== 1) {
@@ -1264,8 +1072,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1264
1072
  responseCommitted = true;
1265
1073
  bootstrapContinuation = undefined;
1266
1074
  rehydrationPhase = "step";
1267
- enqueueTurnPublication(ctx);
1268
- if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
1075
+ enqueueTurnPublication();
1076
+ if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
1269
1077
  completedRunAccepted = !wasBootstrap;
1270
1078
  } catch (error) {
1271
1079
  if (!responseCommitted && specification !== undefined) snapshot.meta.specification = specification;
@@ -1292,7 +1100,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1292
1100
  telegramStartPending = false;
1293
1101
  startStateFlow(ctx);
1294
1102
  }
1295
- if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
1103
+ if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
1296
1104
  if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap || resolutionPending
1297
1105
  || compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase
1298
1106
  || !shouldRequestStateFlowCompaction(ctx.getContextUsage())) return;
@@ -1314,7 +1122,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1314
1122
  rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
1315
1123
  restoreActiveBranch(ctx, event.reason);
1316
1124
  retryPendingPush(ctx);
1317
- if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
1125
+ if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
1318
1126
  updateUi(ctx);
1319
1127
  void telegram.ensure();
1320
1128
  });
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/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
  }
@@ -26,7 +69,7 @@ WRITE: patch_state is the sole model-authored semantic mutation mechanism. Suppl
26
69
 
27
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.
28
71
 
29
- INTENTS: Store selected actions, not requirements, observations, possibilities, alternatives, or completed work. Preserve them across handoffs at the narrowest scope; detail may stay lazy. A {"$ref":"cwd.lazy.plan"} is an ordinary pointer: follow it with read_state only when needed; infer no dependency, hydration, execution, or completion.
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.
30
73
 
31
74
  SCOPES: global=cross-project; cwd=project and Skills; session=branch/run. Deleting an override may reveal its parent.
32
75
 
@@ -360,3 +360,99 @@ export async function runPublicationWorker(
360
360
  };
361
361
  }
362
362
  }
363
+
364
+ export interface PublicationWorkerControllerPorts {
365
+ resolveDestination(): RemotePublicationDestination | undefined;
366
+ isAncestor(ancestor: string, descendant: string): boolean;
367
+ push(destination: RemotePublicationDestination, target: string, signal: AbortSignal): Promise<void>;
368
+ onDiverged(previous: PublicationQueueState, target: string): void;
369
+ }
370
+
371
+ /** Own durable queue coalescing, worker leases, retries, generation fencing, and bounded shutdown. */
372
+ export class PublicationWorkerController {
373
+ private readonly active = new Map<string, { controller: AbortController; done: Promise<void> }>();
374
+ private readonly ports: PublicationWorkerControllerPorts;
375
+ private stopped = false;
376
+ private shutdownPromise: Promise<boolean> | undefined;
377
+
378
+ constructor(ports: PublicationWorkerControllerPorts) {
379
+ this.ports = ports;
380
+ }
381
+
382
+ enqueue(target: string): void {
383
+ const destination = this.ports.resolveDestination();
384
+ if (!destination) return;
385
+ const path = publicationQueuePath(destination);
386
+ const previous = loadPublicationQueue(path);
387
+ const next = previous
388
+ ? coalescePublicationTarget(previous, destination, target, this.ports.isAncestor, {
389
+ onDivergedLineage: (dropped) => this.ports.onDiverged(dropped, target),
390
+ })
391
+ : createPublicationQueue(destination, target);
392
+ savePublicationQueue(path, next, previous);
393
+ }
394
+
395
+ launch(): void {
396
+ if (this.stopped) return;
397
+ let destination: RemotePublicationDestination | undefined;
398
+ try { destination = this.ports.resolveDestination(); }
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 (this.active.has(path)) return;
406
+ let queued: PublicationQueueState | undefined;
407
+ let lease: PublicationWorkerLease | undefined;
408
+ try {
409
+ queued = loadPublicationQueue(path);
410
+ if (!queued) return;
411
+ lease = acquirePublicationWorkerLease(path);
412
+ } catch { return; }
413
+ if (!lease) return;
414
+ const controller = new AbortController();
415
+ const done = runPublicationWorker(
416
+ queued,
417
+ ({ target }) => this.ports.push(destination, target, controller.signal),
418
+ () => loadPublicationQueue(path) ?? queued,
419
+ this.ports.isAncestor,
420
+ ).then((result) => {
421
+ if (this.stopped) return;
422
+ const current = loadPublicationQueue(path);
423
+ if (!current) return;
424
+ if (result.next === undefined) {
425
+ if (current.target === result.attempted.target) removePublicationQueue(path, current);
426
+ return;
427
+ }
428
+ if (current.target === result.attempted.target || result.next.target === current.target) savePublicationQueue(path, result.next, current);
429
+ }).catch(() => {
430
+ // Queue/CAS truth remains durable; status and a later activation expose retry.
431
+ }).finally(() => {
432
+ this.active.delete(path);
433
+ try {
434
+ lease.release();
435
+ if (!this.stopped && loadPublicationQueue(path)?.status === "pending") this.launch();
436
+ } catch {
437
+ // Failed lease cleanup or malformed persistence stays inert until retry or repair.
438
+ }
439
+ });
440
+ this.active.set(path, { controller, done });
441
+ }
442
+
443
+ shutdown(waitMs: number): Promise<boolean> {
444
+ this.stopped = true;
445
+ return this.shutdownPromise ??= (async () => {
446
+ const workers = [...this.active.values()];
447
+ for (const { controller } of workers) controller.abort();
448
+ if (workers.length === 0) return true;
449
+ let timeout: ReturnType<typeof setTimeout> | undefined;
450
+ try {
451
+ return await Promise.race([
452
+ Promise.all(workers.map(({ done }) => done)).then(() => true),
453
+ new Promise<false>((resolve) => { timeout = setTimeout(() => resolve(false), waitMs); }),
454
+ ]);
455
+ } finally { clearTimeout(timeout); }
456
+ })();
457
+ }
458
+ }