@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/AGENTS.md +2 -2
- package/BACKLOG.md +2 -0
- package/CHANGELOG.md +12 -0
- package/README.md +3 -1
- package/dist/lib/extension.d.ts +2 -4
- package/dist/lib/extension.js +35 -240
- package/dist/lib/logging.d.ts +18 -0
- package/dist/lib/logging.js +44 -1
- package/dist/lib/protocol.d.ts +7 -0
- package/dist/lib/protocol.js +48 -1
- package/dist/lib/publication.d.ts +17 -0
- package/dist/lib/publication.js +102 -0
- package/dist/lib/query.d.ts +16 -0
- package/dist/lib/query.js +97 -11
- package/dist/lib/session.d.ts +17 -0
- package/dist/lib/session.js +38 -0
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-guide/SKILL.md +79 -0
- package/dist/skills/state-flow-memory/SKILL.md +23 -131
- package/docs/architecture.md +14 -11
- package/docs/compatibility.md +1 -1
- package/docs/lazy-state.md +13 -5
- package/docs/usage.md +2 -2
- package/lib/extension.ts +37 -229
- package/lib/logging.ts +53 -1
- package/lib/protocol.ts +44 -1
- package/lib/publication.ts +96 -0
- package/lib/query.ts +98 -10
- package/lib/session.ts +45 -0
- package/package.json +1 -1
- package/skills/state-flow-guide/SKILL.md +79 -0
- package/skills/state-flow-memory/SKILL.md +23 -131
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,
|
|
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 {
|
|
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(
|
|
334
|
-
|
|
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(
|
|
292
|
+
function enqueueTurnPublication(): void {
|
|
376
293
|
const target = turnPublicationTarget;
|
|
377
294
|
turnPublicationTarget = undefined;
|
|
378
|
-
if (
|
|
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
|
-
|
|
449
|
-
|
|
450
|
-
|
|
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(
|
|
476
|
-
|
|
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 =
|
|
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
|
-
|
|
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 =
|
|
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(
|
|
1268
|
-
if (snapshot.meta.remotePublication?.mode === "turn-end")
|
|
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")
|
|
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")
|
|
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:
|
|
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
|
|
package/lib/publication.ts
CHANGED
|
@@ -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
|
+
}
|