@kalera/munin-runtime 1.5.0 → 1.6.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.
@@ -1,4 +1,4 @@
1
1
 
2
- > @kalera/munin-runtime@1.5.0 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
2
+ > @kalera/munin-runtime@1.6.0 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
3
3
  > tsc -p tsconfig.json
4
4
 
package/dist/index.js CHANGED
@@ -117,6 +117,9 @@ export async function executeWithRetry(task, retries, backoffMs) {
117
117
  }
118
118
  catch (error) {
119
119
  lastError = error;
120
+ // The SDK already retried a maintenance refusal (and queued a write): never resend it here.
121
+ if (error?.retryable === false)
122
+ break;
120
123
  attempt += 1;
121
124
  if (attempt >= retries)
122
125
  break;
@@ -136,7 +139,7 @@ export function safeError(error) {
136
139
  // callers can branch on the code, but redact any secrets nested in details
137
140
  // (both secret-named keys and inline `token=...` patterns in values).
138
141
  const sdkError = error;
139
- if (error.name === "MuninSdkError") {
142
+ if (error.name === "MuninSdkError" || error.name === "MuninMaintenanceError") {
140
143
  if (sdkError.code !== undefined)
141
144
  safe.code = sdkError.code;
142
145
  if (sdkError.details !== undefined)
@@ -1,7 +1,8 @@
1
1
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
2
2
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
3
  import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
4
- import { MuninClient } from "@kalera/munin-sdk";
4
+ import { MuninClient, MuninMaintenanceError } from "@kalera/munin-sdk";
5
+ import { createFileWriteQueue } from "@kalera/munin-sdk/node";
5
6
  import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
6
7
  function hasSingleIdentifier(args) {
7
8
  const hasKey = typeof args.key === "string" && args.key.length > 0;
@@ -12,14 +13,40 @@ export function createMcpServerInstance(env, opts) {
12
13
  if (!env.apiKey && !opts?.allowMissingApiKey) {
13
14
  throw new Error("MUNIN_API_KEY is required. Set it in your environment, or in a .env.local / .env file in your project directory (walked up automatically).");
14
15
  }
16
+ const writeQueue = createFileWriteQueue();
15
17
  const client = new MuninClient({
16
18
  baseUrl: env.baseUrl,
17
19
  apiKey: env.apiKey,
18
20
  timeoutMs: env.timeoutMs,
21
+ writeQueue,
22
+ // The queue never stores encryptionKey; the flush re-adds the environment
23
+ // key like a live call does. Without one the stored payload is sent as is
24
+ // (the server ignores payload.encryptionKey on /api/mcp/action).
25
+ rehydratePayload: (payload, strippedKeys) => {
26
+ if (!strippedKeys.includes("encryptionKey"))
27
+ return payload;
28
+ const encryptionKey = resolveEncryptionKey();
29
+ return encryptionKey ? { ...payload, encryptionKey } : null;
30
+ },
19
31
  });
32
+ // Process start: send whatever a maintenance window left behind.
33
+ void client.flushPendingWrites().catch(() => undefined);
34
+ /** Queued writes dead-lettered since the last tool result, reported once. */
35
+ const queueNotice = () => {
36
+ const deadLettered = client.takeDeadLetterCount();
37
+ if (deadLettered === 0)
38
+ return {};
39
+ return {
40
+ queueNotice: {
41
+ deadLettered,
42
+ file: writeQueue.deadLetterFile,
43
+ message: `${deadLettered} Munin write(s) queued during maintenance could not be delivered (rejected, still failing, or older than 24 h) and were moved to ${writeQueue.deadLetterFile}.`,
44
+ },
45
+ };
46
+ };
20
47
  const server = new Server({
21
48
  name: "munin-mcp-server",
22
- version: "1.5.0",
49
+ version: "1.6.0",
23
50
  }, {
24
51
  capabilities: {
25
52
  tools: {},
@@ -312,16 +339,33 @@ export function createMcpServerInstance(env, opts) {
312
339
  default:
313
340
  throw new Error(`Unknown tool: ${request.params.name}`);
314
341
  }
342
+ const notice = queueNotice();
343
+ const annotated = result && typeof result === "object" && !Array.isArray(result) ? { ...result, ...notice } : result;
315
344
  return {
316
345
  content: [
317
346
  {
318
347
  type: "text",
319
- text: JSON.stringify(result, null, 2),
348
+ text: JSON.stringify(annotated, null, 2),
320
349
  },
321
350
  ],
322
351
  };
323
352
  }
324
353
  catch (error) {
354
+ // A queued write is a successful, clearly worded result so an agent does
355
+ // not hammer the server; a refused read is an error.
356
+ if (error instanceof MuninMaintenanceError) {
357
+ const pendingWrites = await writeQueue.size().catch(() => undefined);
358
+ const body = { ok: false, maintenance: true, queued: error.queued, message: error.message, pendingWrites, ...queueNotice() };
359
+ return {
360
+ content: [
361
+ {
362
+ type: "text",
363
+ text: JSON.stringify(body, null, 2),
364
+ },
365
+ ],
366
+ isError: !error.queued,
367
+ };
368
+ }
325
369
  const errObj = safeError(error);
326
370
  return {
327
371
  content: [
package/package.json CHANGED
@@ -10,16 +10,21 @@
10
10
  "@types/node": "^24.3.0",
11
11
  "tsx": "^4.20.5",
12
12
  "typescript": "^5.9.2",
13
- "@kalera/munin-shared-version": "1.5.0"
13
+ "@kalera/munin-shared-version": "1.6.0"
14
14
  },
15
15
  "dependencies": {
16
16
  "@modelcontextprotocol/sdk": "^1.27.1",
17
- "@kalera/munin-sdk": "1.5.0"
17
+ "@kalera/munin-sdk": "1.6.0"
18
+ },
19
+ "version": "1.6.0",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/kalera-labs/munin-for-agents.git",
23
+ "directory": "packages/runtime"
18
24
  },
19
- "version": "1.5.0",
20
25
  "scripts": {
21
26
  "build": "tsc -p tsconfig.json",
22
27
  "lint": "tsc -p tsconfig.json --noEmit",
23
- "test": "tsx test/schema.test.ts && tsx test/validation.test.ts"
28
+ "test": "tsx test/schema.test.ts && tsx test/validation.test.ts && tsx test/maintenance.test.ts"
24
29
  }
25
30
  }
package/src/index.ts CHANGED
@@ -145,6 +145,8 @@ export async function executeWithRetry<T>(
145
145
  return await task();
146
146
  } catch (error) {
147
147
  lastError = error;
148
+ // The SDK already retried a maintenance refusal (and queued a write): never resend it here.
149
+ if ((error as { retryable?: unknown } | null)?.retryable === false) break;
148
150
  attempt += 1;
149
151
  if (attempt >= retries) break;
150
152
  const jitter = Math.floor(Math.random() * 100);
@@ -166,7 +168,7 @@ export function safeError(error: unknown): Record<string, unknown> {
166
168
  // callers can branch on the code, but redact any secrets nested in details
167
169
  // (both secret-named keys and inline `token=...` patterns in values).
168
170
  const sdkError = error as Error & { code?: unknown; details?: unknown };
169
- if (error.name === "MuninSdkError") {
171
+ if (error.name === "MuninSdkError" || error.name === "MuninMaintenanceError") {
170
172
  if (sdkError.code !== undefined) safe.code = sdkError.code;
171
173
  if (sdkError.details !== undefined) safe.details = redactValue(sdkError.details);
172
174
  }
package/src/mcp-server.ts CHANGED
@@ -4,7 +4,8 @@ import {
4
4
  CallToolRequestSchema,
5
5
  ListToolsRequestSchema,
6
6
  } from "@modelcontextprotocol/sdk/types.js";
7
- import { MuninClient } from "@kalera/munin-sdk";
7
+ import { MuninClient, MuninMaintenanceError } from "@kalera/munin-sdk";
8
+ import { createFileWriteQueue } from "@kalera/munin-sdk/node";
8
9
  import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
9
10
 
10
11
  function hasSingleIdentifier(args: Record<string, unknown>): args is Record<string, unknown> & { key?: string; id?: string } {
@@ -23,16 +24,41 @@ export function createMcpServerInstance(
23
24
  );
24
25
  }
25
26
 
27
+ const writeQueue = createFileWriteQueue();
26
28
  const client = new MuninClient({
27
29
  baseUrl: env.baseUrl,
28
30
  apiKey: env.apiKey,
29
31
  timeoutMs: env.timeoutMs,
32
+ writeQueue,
33
+ // The queue never stores encryptionKey; the flush re-adds the environment
34
+ // key like a live call does. Without one the stored payload is sent as is
35
+ // (the server ignores payload.encryptionKey on /api/mcp/action).
36
+ rehydratePayload: (payload, strippedKeys) => {
37
+ if (!strippedKeys.includes("encryptionKey")) return payload;
38
+ const encryptionKey = resolveEncryptionKey();
39
+ return encryptionKey ? { ...payload, encryptionKey } : null;
40
+ },
30
41
  });
42
+ // Process start: send whatever a maintenance window left behind.
43
+ void client.flushPendingWrites().catch(() => undefined);
44
+
45
+ /** Queued writes dead-lettered since the last tool result, reported once. */
46
+ const queueNotice = () => {
47
+ const deadLettered = client.takeDeadLetterCount();
48
+ if (deadLettered === 0) return {};
49
+ return {
50
+ queueNotice: {
51
+ deadLettered,
52
+ file: writeQueue.deadLetterFile,
53
+ message: `${deadLettered} Munin write(s) queued during maintenance could not be delivered (rejected, still failing, or older than 24 h) and were moved to ${writeQueue.deadLetterFile}.`,
54
+ },
55
+ };
56
+ };
31
57
 
32
58
  const server = new Server(
33
59
  {
34
60
  name: "munin-mcp-server",
35
- version: "1.5.0",
61
+ version: "1.6.0",
36
62
  },
37
63
  {
38
64
  capabilities: {
@@ -337,15 +363,32 @@ export function createMcpServerInstance(
337
363
  throw new Error(`Unknown tool: ${request.params.name}`);
338
364
  }
339
365
 
366
+ const notice = queueNotice();
367
+ const annotated = result && typeof result === "object" && !Array.isArray(result) ? { ...result, ...notice } : result;
340
368
  return {
341
369
  content: [
342
370
  {
343
371
  type: "text",
344
- text: JSON.stringify(result, null, 2),
372
+ text: JSON.stringify(annotated, null, 2),
345
373
  },
346
374
  ],
347
375
  };
348
376
  } catch (error) {
377
+ // A queued write is a successful, clearly worded result so an agent does
378
+ // not hammer the server; a refused read is an error.
379
+ if (error instanceof MuninMaintenanceError) {
380
+ const pendingWrites = await writeQueue.size().catch(() => undefined);
381
+ const body = { ok: false, maintenance: true, queued: error.queued, message: error.message, pendingWrites, ...queueNotice() };
382
+ return {
383
+ content: [
384
+ {
385
+ type: "text",
386
+ text: JSON.stringify(body, null, 2),
387
+ },
388
+ ],
389
+ isError: !error.queued,
390
+ };
391
+ }
349
392
  const errObj = safeError(error);
350
393
  return {
351
394
  content: [
@@ -0,0 +1,178 @@
1
+ import assert from "node:assert/strict";
2
+ import fs from "node:fs/promises";
3
+ import os from "node:os";
4
+ import path from "node:path";
5
+ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
6
+ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
7
+ import { MuninMaintenanceError, keyFingerprint } from "@kalera/munin-sdk";
8
+ import { createMcpServerInstance } from "../src/mcp-server.js";
9
+ import { executeWithRetry, safeError } from "../src/index.js";
10
+
11
+ interface ToolResult {
12
+ isError?: boolean;
13
+ content?: Array<{ type: string; text: string }>;
14
+ }
15
+
16
+ const BASE_URL = "http://munin.test";
17
+ const CAPABILITIES = {
18
+ ok: true,
19
+ data: {
20
+ specVersion: "v1.0.0",
21
+ actions: { core: ["store", "retrieve", "search", "list", "recent"], optional: ["share"] },
22
+ features: {},
23
+ metadata: { serverVersion: "test", timestamp: new Date(0).toISOString() },
24
+ },
25
+ };
26
+
27
+ /** Answers every /api/mcp/action call with `actionStatus`; retryAfter 0 keeps the SDK backoff at 1 s + 2 s. */
28
+ function stubFetch(mode: "maintenance" | "ok", seen: Array<Record<string, any>>): typeof fetch {
29
+ return (async (input: RequestInfo | URL, init?: RequestInit) => {
30
+ const url = String(input);
31
+ if (url.endsWith("/api/mcp/capabilities")) {
32
+ return new Response(JSON.stringify(CAPABILITIES), { status: 200, headers: { "Content-Type": "application/json" } });
33
+ }
34
+ seen.push(JSON.parse(String(init?.body)));
35
+ const body = mode === "maintenance"
36
+ ? { ok: false, error: "MAINTENANCE_READ_ONLY", retryAfter: 0 }
37
+ : { ok: true, data: { stored: true } };
38
+ return new Response(JSON.stringify(body), {
39
+ status: mode === "maintenance" ? 503 : 200,
40
+ headers: { "Content-Type": "application/json" },
41
+ });
42
+ }) as typeof fetch;
43
+ }
44
+
45
+ async function connect() {
46
+ const server = createMcpServerInstance({ baseUrl: BASE_URL, apiKey: "key-a", timeoutMs: 5_000, retries: 0, backoffMs: 0 });
47
+ const client = new Client({ name: "runtime-maintenance-test-client", version: "0.0.0" }, { capabilities: {} });
48
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
49
+ await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
50
+ return {
51
+ call: async (name: string, args: Record<string, unknown>) => (await client.callTool({ name, arguments: args })) as ToolResult,
52
+ close: () => Promise.all([client.close(), server.close()]),
53
+ };
54
+ }
55
+
56
+ async function waitFor(predicate: () => Promise<boolean>, timeoutMs = 5_000): Promise<void> {
57
+ const deadline = Date.now() + timeoutMs;
58
+ while (!(await predicate())) {
59
+ if (Date.now() > deadline) throw new Error("condition not met in time");
60
+ await new Promise((resolve) => setTimeout(resolve, 20));
61
+ }
62
+ }
63
+
64
+ async function run() {
65
+ const queueDir = await fs.mkdtemp(path.join(os.tmpdir(), "munin-runtime-queue-"));
66
+ process.env.MUNIN_QUEUE_DIR = queueDir;
67
+ process.env.MUNIN_ENCRYPTION_KEY = "env-e2ee-key";
68
+ const queueFile = path.join(queueDir, "pending-writes.jsonl");
69
+ const realFetch = globalThis.fetch;
70
+
71
+ try {
72
+ // 1. executeWithRetry does not retry an error that says it is not retryable.
73
+ {
74
+ let calls = 0;
75
+ await assert.rejects(
76
+ executeWithRetry(async () => {
77
+ calls += 1;
78
+ throw new MuninMaintenanceError({ queued: true, action: "store", retryAfterMs: null });
79
+ }, 3, 0),
80
+ MuninMaintenanceError,
81
+ );
82
+ assert.equal(calls, 1, "the SDK already retried and queued; the CLI must not resend");
83
+ }
84
+
85
+ // 2. safeError keeps code and details for MuninSdkError subclasses.
86
+ {
87
+ const safe = safeError(new MuninMaintenanceError({ queued: false, action: "search", retryAfterMs: 900_000 }));
88
+ assert.equal(safe.code, "MAINTENANCE_READ_ONLY");
89
+ assert.equal((safe.details as Record<string, unknown>).action, "search");
90
+ }
91
+
92
+ // 3. During the freeze a store is answered as a queued, non-error result,
93
+ // and the queue on disk holds no E2EE key; a read is an error, never queued.
94
+ {
95
+ const seen: Array<Record<string, any>> = [];
96
+ globalThis.fetch = stubFetch("maintenance", seen);
97
+ const mcp = await connect();
98
+ const stored = await mcp.call("munin_store_memory", { projectId: "p1", key: "k", content: "c" });
99
+ assert.equal(stored.isError, false);
100
+ const storedBody = JSON.parse(stored.content?.[0]?.text ?? "{}");
101
+ assert.equal(storedBody.maintenance, true);
102
+ assert.equal(storedBody.queued, true);
103
+ assert.match(storedBody.message, /maintenance/i);
104
+ assert.equal(seen.filter((r) => r.action === "store").length, 3, "first attempt + 2 bounded retries");
105
+ assert.equal(seen[0].payload.encryptionKey, "env-e2ee-key", "a live call still sends the key");
106
+ const onDisk = await fs.readFile(queueFile, "utf8");
107
+ assert.equal(onDisk.trim().split("\n").length, 1);
108
+ assert.equal(onDisk.includes("env-e2ee-key"), false, "the E2EE key never reaches the queue");
109
+
110
+ const searched = await mcp.call("munin_search_memories", { projectId: "p1", query: "q" });
111
+ assert.equal(searched.isError, true);
112
+ assert.equal(JSON.parse(searched.content?.[0]?.text ?? "{}").queued, false);
113
+ assert.equal((await fs.readFile(queueFile, "utf8")).trim().split("\n").length, 1, "reads are never queued");
114
+ await mcp.close();
115
+ }
116
+
117
+ // 4. A new MCP server process flushes the queue at start, with the key re-resolved from the environment.
118
+ {
119
+ const seen: Array<Record<string, any>> = [];
120
+ globalThis.fetch = stubFetch("ok", seen);
121
+ const mcp = await connect();
122
+ await waitFor(async () => (await fs.readFile(queueFile, "utf8")).trim() === "");
123
+ const replayed = seen.find((r) => r.action === "store");
124
+ assert.equal(replayed?.payload.key, "k");
125
+ assert.equal(replayed?.payload.encryptionKey, "env-e2ee-key");
126
+ await mcp.close();
127
+ }
128
+
129
+ // 5. A queued write that could not be delivered (here: older than 24 h) is
130
+ // reported once in the next tool result, with the dead-letter file.
131
+ {
132
+ const stale = {
133
+ id: "stale-1",
134
+ queuedAt: new Date(Date.now() - 25 * 60 * 60_000).toISOString(),
135
+ baseUrl: BASE_URL,
136
+ keyFingerprint: await keyFingerprint("key-a"),
137
+ projectId: "p1",
138
+ action: "store",
139
+ payload: { key: "old" },
140
+ strippedKeys: [],
141
+ };
142
+ await fs.writeFile(queueFile, `${JSON.stringify(stale)}\n`, { mode: 0o600 });
143
+ const seen: Array<Record<string, any>> = [];
144
+ globalThis.fetch = stubFetch("ok", seen);
145
+ const mcp = await connect();
146
+ await waitFor(async () => (await fs.readFile(queueFile, "utf8")).trim() === "");
147
+ const first = JSON.parse((await mcp.call("munin_search_memories", { projectId: "p1", query: "q" })).content?.[0]?.text ?? "{}");
148
+ assert.equal(first.queueNotice?.deadLettered, 1);
149
+ assert.match(first.queueNotice?.message ?? "", /could not be delivered/);
150
+ assert.equal(first.queueNotice?.file, path.join(queueDir, "pending-writes.dead.jsonl"));
151
+ const second = JSON.parse((await mcp.call("munin_search_memories", { projectId: "p1", query: "q" })).content?.[0]?.text ?? "{}");
152
+ assert.equal(second.queueNotice, undefined, "reported once");
153
+ assert.equal(seen.some((r) => r.payload?.key === "old"), false, "a stale write is never replayed");
154
+ await mcp.close();
155
+ }
156
+
157
+ // 6. A queued result says how many writes wait locally.
158
+ {
159
+ globalThis.fetch = stubFetch("maintenance", []);
160
+ const mcp = await connect();
161
+ await mcp.call("munin_store_memory", { projectId: "p1", key: "a", content: "c" });
162
+ const body = JSON.parse((await mcp.call("munin_store_memory", { projectId: "p1", key: "b", content: "c" })).content?.[0]?.text ?? "{}");
163
+ assert.equal(body.queued, true);
164
+ assert.equal(body.pendingWrites, 2);
165
+ await mcp.close();
166
+ }
167
+ } finally {
168
+ globalThis.fetch = realFetch;
169
+ await fs.rm(queueDir, { recursive: true, force: true });
170
+ }
171
+
172
+ console.log("runtime maintenance tests passed");
173
+ }
174
+
175
+ void run().catch((error) => {
176
+ console.error(error);
177
+ process.exitCode = 1;
178
+ });
@@ -19,7 +19,7 @@ async function run() {
19
19
  const client = new Client(
20
20
  {
21
21
  name: "runtime-schema-test-client",
22
- version: "1.5.0",
22
+ version: "1.6.0",
23
23
  },
24
24
  {
25
25
  capabilities: {},
@@ -64,7 +64,7 @@ async function run() {
64
64
  );
65
65
 
66
66
  const client = new Client(
67
- { name: "runtime-validation-test-client", version: "1.5.0" },
67
+ { name: "runtime-validation-test-client", version: "1.6.0" },
68
68
  { capabilities: {} },
69
69
  );
70
70