@gtrabanco/agentic-workflow 0.2.0 → 0.5.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.
@@ -0,0 +1,388 @@
1
+ /**
2
+ * Bounded memory-substrate health probe (feature 66, P1 — AC2).
3
+ *
4
+ * Answers one question before a session's first memory read: is the Engram
5
+ * memory layer healthy enough to trust, and if not, exactly which layer is
6
+ * degraded? Five checks, one verdict:
7
+ *
8
+ * http-health GET :7437/health — the HTTP server pi talks to.
9
+ * mcp-runner one `initialize` round-trip to a spawned
10
+ * `engram mcp --tools=agent` — the stdio transport.
11
+ * binary-version `engram --version` — the CLI both transports ride on.
12
+ * sync-staleness `engram sync --status` — pending import work.
13
+ * session-ambiguity `engram doctor --json --check` on the two findings
14
+ * that make a session id unreliable or a sync target
15
+ * unreachable.
16
+ *
17
+ * Two design rules ride on measured failure modes, not guesses:
18
+ *
19
+ * - **Exit code is not a health signal.** `engram doctor` exits 0 while its
20
+ * JSON says `status: "error"`, so every check parses the answer it gets and
21
+ * never trusts a zero exit.
22
+ * - **A responding server that has not synced is not `ok`** (AC2's staleness
23
+ * signal), which is why `sync-staleness` is a check and not a footnote.
24
+ * - **One answer never hides another.** The session check asks both scoped
25
+ * `doctor --check` ids and reports every non-`ok` finding: the first is
26
+ * non-`ok` permanently on a machine with session-attribution ambiguity, so
27
+ * stopping at it would silence the sync signal there forever.
28
+ *
29
+ * The five checks are independent, so they are launched together and each keeps
30
+ * its own bound: the worst case is the slowest bound, never the sum of five
31
+ * (4+4+4+10+10 = 32 s, which the 30 s ceiling could not fit). The probe never
32
+ * issues an MCP *tool* call — only `initialize` — so running it can never mutate
33
+ * the memory layer. Bounds: 4 s for the HTTP/runner/version calls, 10 s for the
34
+ * two CLI-backed calls, and a 30 s ceiling over the whole probe, which stops any
35
+ * dependency that ignored its own bound. A bound hit fails that check and the
36
+ * verdict becomes `degraded` — never a hang, never a blocked unit (D1).
37
+ *
38
+ * `runProbe` takes its side effects by injection (`fetchImpl`, `runImpl`,
39
+ * `timeoutMs`, `totalTimeoutMs`) — the crate's existing shape
40
+ * (`src/doc/embeddings.mjs`'s `fetchImpl ?? fetch`) — so the suite drives
41
+ * every degraded path with fakes and millisecond bounds: no network, no PATH,
42
+ * no real engram process.
43
+ */
44
+
45
+ import { spawn } from "node:child_process";
46
+
47
+ export const PROBE_SCHEMA = "memory-probe@1";
48
+
49
+ /** Per-check timeout bounds (ms), and the ceiling over the whole probe. */
50
+ export const PROBE_TIMEOUTS = Object.freeze({
51
+ httpHealth: 4_000,
52
+ mcpRunner: 4_000,
53
+ binaryVersion: 4_000,
54
+ syncStaleness: 10_000,
55
+ sessionAmbiguity: 10_000,
56
+ total: 30_000,
57
+ });
58
+
59
+ const HEALTH_URL = "http://127.0.0.1:7437/health";
60
+ const ENGRAM_BIN = "engram";
61
+ const RUNNER_ARGS = ["mcp", "--tools=agent"];
62
+ const INITIALIZE = {
63
+ jsonrpc: "2.0",
64
+ id: 1,
65
+ method: "initialize",
66
+ params: {
67
+ protocolVersion: "2024-11-05",
68
+ capabilities: {},
69
+ clientInfo: { name: "agentic-workflow-memory-probe", version: "1" },
70
+ },
71
+ };
72
+
73
+ const CHECK_IDS = Object.freeze([
74
+ "http-health",
75
+ "mcp-runner",
76
+ "binary-version",
77
+ "sync-staleness",
78
+ "session-ambiguity",
79
+ ]);
80
+
81
+ function pass(id, detail) {
82
+ return { id, status: "ok", detail };
83
+ }
84
+
85
+ function fail(id, reason, detail) {
86
+ return { id, status: "failed", reason, detail };
87
+ }
88
+
89
+ /**
90
+ * Run one child process under a bound. Resolves to
91
+ * `{code, stdout, stderr, timedOut, spawnError}` — it never rejects, because
92
+ * every failure mode here is an answer, not an exception.
93
+ *
94
+ * `stdin` is written and the stream closed immediately: the MCP runner would
95
+ * otherwise wait forever for its client, which is the hang this probe exists
96
+ * to avoid.
97
+ */
98
+ function runBounded(command, args, { timeoutMs, stdin = null } = {}) {
99
+ return new Promise((resolve) => {
100
+ let settled = false;
101
+ let child;
102
+ const done = (result) => {
103
+ if (settled) return;
104
+ settled = true;
105
+ clearTimeout(timer);
106
+ resolve(result);
107
+ };
108
+ const timer = setTimeout(() => {
109
+ if (child) {
110
+ try {
111
+ child.kill("SIGKILL");
112
+ } catch {
113
+ // the process already exited — the settle below is what matters
114
+ }
115
+ }
116
+ done({ code: null, stdout: "", stderr: "", timedOut: true, spawnError: null });
117
+ }, timeoutMs);
118
+
119
+ try {
120
+ child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
121
+ } catch (error) {
122
+ done({ code: null, stdout: "", stderr: "", timedOut: false, spawnError: error });
123
+ return;
124
+ }
125
+
126
+ let stdout = "";
127
+ let stderr = "";
128
+ child.stdout?.on("data", (chunk) => (stdout += chunk));
129
+ child.stderr?.on("data", (chunk) => (stderr += chunk));
130
+ child.on("error", (error) => done({ code: null, stdout, stderr, timedOut: false, spawnError: error }));
131
+ child.on("close", (code) => done({ code, stdout, stderr, timedOut: false, spawnError: null }));
132
+
133
+ if (child.stdin) {
134
+ child.stdin.on("error", () => {
135
+ // the runner died before reading — reported by close/error
136
+ });
137
+ child.stdin.end(stdin ?? "");
138
+ }
139
+ });
140
+ }
141
+
142
+ /** First JSON object found in a text stream (doctor/mcp may pad with noise). */
143
+ function firstJsonObject(text) {
144
+ const start = text.indexOf("{");
145
+ if (start === -1) return null;
146
+ let depth = 0;
147
+ let inString = false;
148
+ let escaped = false;
149
+ for (let i = start; i < text.length; i++) {
150
+ const ch = text[i];
151
+ if (inString) {
152
+ if (escaped) escaped = false;
153
+ else if (ch === "\\") escaped = true;
154
+ else if (ch === '"') inString = false;
155
+ continue;
156
+ }
157
+ if (ch === '"') inString = true;
158
+ else if (ch === "{") depth += 1;
159
+ else if (ch === "}") {
160
+ depth -= 1;
161
+ if (depth === 0) {
162
+ try {
163
+ return JSON.parse(text.slice(start, i + 1));
164
+ } catch {
165
+ return null;
166
+ }
167
+ }
168
+ }
169
+ }
170
+ return null;
171
+ }
172
+
173
+ /** `engram sync --status` reports pending work as a fixed text block. */
174
+ export function parseSyncStatus(text) {
175
+ const match = text.match(/Pending import:\s*(\d+)/i);
176
+ if (!match) return { parsed: false, pending: null };
177
+ return { parsed: true, pending: Number(match[1]) };
178
+ }
179
+
180
+ async function checkHttpHealth(fetchImpl, timeoutMs) {
181
+ const id = "http-health";
182
+ const controller = new AbortController();
183
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
184
+ try {
185
+ const response = await fetchImpl(HEALTH_URL, { signal: controller.signal });
186
+ if (!response.ok) return fail(id, "http-status", `HTTP ${response.status}`);
187
+ let body = null;
188
+ try {
189
+ body = JSON.parse(await response.text());
190
+ } catch {
191
+ return fail(id, "http-unparseable", "health body is not JSON");
192
+ }
193
+ if (body?.status !== "ok") return fail(id, "http-unhealthy", `status ${body?.status ?? "missing"}`);
194
+ return pass(id, `engram ${body?.version ?? "unknown"} answering`);
195
+ } catch (error) {
196
+ if (error?.name === "AbortError") return fail(id, "timeout", `no HTTP answer within ${timeoutMs} ms`);
197
+ return fail(id, "http-unreachable", error?.message ?? String(error));
198
+ } finally {
199
+ clearTimeout(timer);
200
+ }
201
+ }
202
+
203
+ async function checkMcpRunner(runImpl, timeoutMs) {
204
+ const id = "mcp-runner";
205
+ const result = await runImpl(ENGRAM_BIN, RUNNER_ARGS, {
206
+ timeoutMs,
207
+ stdin: JSON.stringify(INITIALIZE) + "\n",
208
+ });
209
+ if (result.spawnError) return fail(id, "runner-missing", result.spawnError.message);
210
+ if (result.timedOut) return fail(id, "timeout", `no initialize answer within ${timeoutMs} ms`);
211
+ const reply = firstJsonObject(result.stdout ?? "");
212
+ if (!reply) return fail(id, "runner-silent", `exit ${result.code}, no JSON-RPC reply`);
213
+ if (reply.error) return fail(id, "runner-error", reply.error.message ?? "JSON-RPC error");
214
+ const info = reply.result?.serverInfo;
215
+ if (!info?.name) return fail(id, "runner-silent", "initialize reply carries no serverInfo");
216
+ return pass(id, `${info.name} ${info.version ?? "unknown"} initialized`);
217
+ }
218
+
219
+ async function checkBinaryVersion(runImpl, timeoutMs) {
220
+ const id = "binary-version";
221
+ const result = await runImpl(ENGRAM_BIN, ["--version"], { timeoutMs });
222
+ if (result.spawnError) return fail(id, "binary-missing", result.spawnError.message);
223
+ if (result.timedOut) return fail(id, "timeout", `no version answer within ${timeoutMs} ms`);
224
+ const match = (result.stdout ?? "").match(/\d+\.\d+\.\d+\S*/);
225
+ if (!match) return fail(id, "binary-unreadable", `exit ${result.code}, no version string`);
226
+ if (result.code !== 0) return fail(id, "binary-unreadable", `exit ${result.code}`);
227
+ return pass(id, `engram ${match[0]}`);
228
+ }
229
+
230
+ async function checkSyncStaleness(runImpl, timeoutMs) {
231
+ const id = "sync-staleness";
232
+ const result = await runImpl(ENGRAM_BIN, ["sync", "--status"], { timeoutMs });
233
+ if (result.spawnError) return fail(id, "binary-missing", result.spawnError.message);
234
+ if (result.timedOut) return fail(id, "timeout", `no sync answer within ${timeoutMs} ms`);
235
+ // A non-zero exit here is usually "ambiguous project" — the status is
236
+ // unreadable, which is a degradation, not a pass.
237
+ if (result.code !== 0) {
238
+ const detail = (result.stderr ?? "").trim().split("\n").pop() || `exit ${result.code}`;
239
+ return fail(id, "sync-unreadable", detail);
240
+ }
241
+ const parsed = parseSyncStatus(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
242
+ if (!parsed.parsed) return fail(id, "sync-unreadable", "no pending-import line in the status block");
243
+ if (parsed.pending > 0) return fail(id, "sync-pending", `${parsed.pending} pending import(s)`);
244
+ return pass(id, "no pending import work");
245
+ }
246
+
247
+ /** One check-scoped `engram doctor --json --check <id>` answer, classified. */
248
+ async function askDoctor(runImpl, checkId, timeoutMs) {
249
+ const result = await runImpl(ENGRAM_BIN, ["doctor", "--json", "--check", checkId], { timeoutMs });
250
+ if (result.spawnError) return { checkId, reason: "binary-missing", detail: result.spawnError.message, structural: true };
251
+ if (result.timedOut) return { checkId, reason: "timeout", detail: `no answer within ${timeoutMs} ms`, structural: true };
252
+ const report = firstJsonObject(result.stdout ?? "");
253
+ if (!report) return { checkId, reason: "doctor-unreadable", detail: "no JSON report", structural: true };
254
+ const entry = (report.checks ?? []).find((c) => c.check_id === checkId) ?? report.checks?.[0];
255
+ if (!entry) return { checkId, reason: "doctor-unreadable", detail: "report carries no check", structural: true };
256
+ if (entry.result !== "ok") {
257
+ return { checkId, reason: `doctor-${entry.result}`, detail: entry.message ?? entry.result, structural: false };
258
+ }
259
+ return { checkId, ok: true };
260
+ }
261
+
262
+ /**
263
+ * Which finding leads the reason code when more than one answer is not `ok`.
264
+ * An `error` outranks a `blocked` target, which outranks a `warning`; a check
265
+ * that could not be answered at all outranks any finding (see the caller).
266
+ */
267
+ const RESULT_RANK = { error: 3, blocked: 2, warning: 1 };
268
+
269
+ async function checkSessionAmbiguity(runImpl, timeoutMs) {
270
+ const id = "session-ambiguity";
271
+ // Both scoped checks are asked, every time, and in parallel: each is bounded
272
+ // on its own, so pairing them costs no extra wall time, and an answer is
273
+ // never dropped because an earlier finding was already enough to degrade.
274
+ const answers = await Promise.all(DOCTOR_CHECKS.map((checkId) => askDoctor(runImpl, checkId, timeoutMs)));
275
+ const failures = answers.filter((answer) => answer.ok !== true);
276
+ if (failures.length === 0) return pass(id, "no session or sync-target findings");
277
+ // A check that could not be answered at all says more about the layer than a
278
+ // finding does, so a structural failure leads the reason code; otherwise the
279
+ // most severe finding leads, and every finding is listed in the detail.
280
+ const severity = (failure) => (failure.structural ? 4 : RESULT_RANK[failure.reason.replace("doctor-", "")] ?? 0);
281
+ const leading = failures.reduce((best, current) => (severity(current) > severity(best) ? current : best));
282
+ const detail = failures.map((failure) => `${failure.checkId}: ${failure.detail}`).join(" · ");
283
+ return fail(id, leading.reason, detail);
284
+ }
285
+
286
+ /**
287
+ * The two scoped `doctor --json --check <id>` ids the session check asks, named
288
+ * by the plan (P1) and never the full sweep: the first makes a write's session
289
+ * attribution unreliable, the second says a sync target cannot be reached.
290
+ */
291
+ const DOCTOR_CHECKS = Object.freeze(["ambiguous_active_runtime_sessions", "sync_target_closed_space"]);
292
+
293
+ /** The detail a check carries when the ceiling, not its own bound, stopped it. */
294
+ const CEILING_DETAIL = "probe ceiling reached before this check answered";
295
+
296
+ const CHECKS = [
297
+ { id: "http-health", timeout: PROBE_TIMEOUTS.httpHealth, run: (deps, ms) => checkHttpHealth(deps.fetchImpl, ms) },
298
+ { id: "mcp-runner", timeout: PROBE_TIMEOUTS.mcpRunner, run: (deps, ms) => checkMcpRunner(deps.runImpl, ms) },
299
+ { id: "binary-version", timeout: PROBE_TIMEOUTS.binaryVersion, run: (deps, ms) => checkBinaryVersion(deps.runImpl, ms) },
300
+ { id: "sync-staleness", timeout: PROBE_TIMEOUTS.syncStaleness, run: (deps, ms) => checkSyncStaleness(deps.runImpl, ms) },
301
+ { id: "session-ambiguity", timeout: PROBE_TIMEOUTS.sessionAmbiguity, run: (deps, ms) => checkSessionAmbiguity(deps.runImpl, ms) },
302
+ ];
303
+
304
+ /**
305
+ * Run the five checks and return the verdict:
306
+ *
307
+ * {schema, verdict: "ok" | "degraded", checks: [{id, status, reason?, detail}],
308
+ * degraded: [check ids], ceilingHit: boolean}
309
+ *
310
+ * `ok` only when every check passes. The checks are independent, so they run
311
+ * together, each under its own bound; the ceiling is the hard stop over the
312
+ * whole probe and answers for any check whose dependency ignored its bound, so a
313
+ * slow machine can never masquerade as healthy and never hangs.
314
+ *
315
+ * `timeoutMs` overrides every per-check bound (tests use milliseconds);
316
+ * `totalTimeoutMs` overrides the ceiling.
317
+ */
318
+ export async function runProbe({ fetchImpl, runImpl, timeoutMs, totalTimeoutMs } = {}) {
319
+ const deps = {
320
+ fetchImpl: fetchImpl ?? ((url, init) => fetch(url, init)),
321
+ runImpl: runImpl ?? ((command, args, opts) => runBounded(command, args, opts)),
322
+ };
323
+ const perCheck = timeoutMs ?? null;
324
+ const ceiling = totalTimeoutMs ?? PROBE_TIMEOUTS.total;
325
+ const startedAt = Date.now();
326
+ const remaining = () => ceiling - (Date.now() - startedAt);
327
+
328
+ const answers = new Array(CHECKS.length).fill(null);
329
+ let stopped = false;
330
+ // Set when the ceiling — not a check's own bound — is what ran out. Tracked
331
+ // directly instead of read back out of a detail string, so the wording of a
332
+ // failure can never change what `ceilingHit` reports.
333
+ let ceilingConstrained = false;
334
+ const launched = CHECKS.map(async (check, index) => {
335
+ const budget = perCheck ?? check.timeout;
336
+ const left = remaining();
337
+ if (left <= 0) {
338
+ ceilingConstrained = true;
339
+ answers[index] = fail(check.id, "timeout", CEILING_DETAIL);
340
+ return;
341
+ }
342
+ // The ceiling clamps the bound a check runs under; a timeout that is really
343
+ // the ceiling running out is reported as the ceiling, not as a hung check.
344
+ const bound = Math.min(budget, left);
345
+ const clamped = bound < budget;
346
+ let entry;
347
+ try {
348
+ entry = await check.run(deps, bound);
349
+ } catch (error) {
350
+ entry = fail(check.id, "probe-error", error?.message ?? String(error));
351
+ }
352
+ if (stopped) return;
353
+ if (clamped && entry.status === "failed" && entry.reason === "timeout") {
354
+ ceilingConstrained = true;
355
+ entry = { ...entry, detail: `${CEILING_DETAIL} (bound cut from ${budget} ms to ${bound} ms)` };
356
+ }
357
+ answers[index] = entry;
358
+ });
359
+
360
+ const left = Math.max(remaining(), 0);
361
+ let timer = null;
362
+ const ceilingFired = await new Promise((resolve) => {
363
+ timer = setTimeout(() => {
364
+ stopped = true;
365
+ resolve(true);
366
+ }, left);
367
+ Promise.allSettled(launched).then(() => resolve(false));
368
+ });
369
+ if (timer) clearTimeout(timer);
370
+
371
+ const results = CHECKS.map((check, index) => {
372
+ if (answers[index] !== null) return answers[index];
373
+ // The ceiling fired while this check was still outstanding: its dependency
374
+ // ignored the bound it was given, and the probe answers for it.
375
+ ceilingConstrained = true;
376
+ return fail(check.id, "timeout", CEILING_DETAIL);
377
+ });
378
+ const degraded = results.filter((r) => r.status !== "ok").map((r) => r.id);
379
+ return {
380
+ schema: PROBE_SCHEMA,
381
+ verdict: degraded.length === 0 ? "ok" : "degraded",
382
+ checks: results,
383
+ degraded,
384
+ ceilingHit: ceilingFired === true || ceilingConstrained === true,
385
+ };
386
+ }
387
+
388
+ export { CHECK_IDS, HEALTH_URL, RUNNER_ARGS, ENGRAM_BIN };