@mono-agent/agent-app 0.3.0 → 0.4.0

package/dist/memory-recall-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-recall-main.js","sourceRoot":"","sources":["../src/memory-recall-main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAE9G,KAAK,UAAU,IAAI;IACjB,MAAM,QAAQ,GAAG,2BAA2B,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC/C,4FAA4F;IAC5F,4EAA4E;IAC5E,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,KAAK,KAAK;aACP,KAAK,EAAE;aACP,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,2FAA2F;YAC3F,2DAA2D;YAC3D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oDAAoD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvI,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAChC,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrH,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/memory-recall.d.ts

@@ -0,0 +1,111 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { BujoMemoryStore } from "@mono-agent/memory-bujo";
+import type { MonoAgentConfig } from "@mono-agent/config";
+/**
+ * Read-only memory recall, wired from the SINGLE `config.memory` block.
+ *
+ * When `config.memory.recallTool.enabled` is true, the app exposes a `memory_recall` MCP tool
+ * (server name {@link MEMORY_RECALL_MCP_SERVER_NAME}) to the agent. Recall needs only embeddings +
+ * FTS — no chat LLM — so the recall server is built with embeddings alone. When embeddings are
+ * absent (lite tier, or an explicit opt-in on a no-embeddings store) recall still serves FTS-only
+ * (lexical) results. Capture stays in-app (unchanged); this module never touches it.
+ *
+ * Embeddings parity with the in-app store (`createConfiguredMemory`): the recall child applies the
+ * SAME resilience wrapping — a per-call timeout plus a circuit breaker — so a slow/failing backend
+ * cannot stall or repeatedly block recall in the child process either.
+ *
+ * Secret handling: the raw embeddings api key is NOT copied into the recall child's env. When the
+ * key was sourced from a named environment variable (`apiKeyEnv`) we forward only the NAME and the
+ * child re-reads the value from its inherited process env at runtime. An inline literal key (no
+ * `apiKeyEnv`) still has to transit the child env as a value — that residual is documented on
+ * {@link memoryRecallMcpEnv}.
+ *
+ * A stdio MCP server is injected purely as an `mcpServers` entry via the per-request runtime
+ * options. MCP tools are not gated by `tools.allowedTools`, so no allowlist entry is required.
+ */
+export declare const MEMORY_RECALL_MCP_SERVER_NAME = "mono-agent-memory";
+/** Circuit-breaker tuning carried into the recall child. Mirrors `config.memory.embeddings.circuitBreaker`. */
+export interface MemoryRecallEmbeddingsCircuitBreaker {
+    readonly failureThreshold?: number;
+    readonly cooldownMs?: number;
+}
+/** Embeddings the recall server needs. Mirrors the resolved `config.memory.embeddings` slice. */
+export interface MemoryRecallEmbeddings {
+    readonly provider: "ollama" | "openai";
+    readonly model: string;
+    readonly endpoint?: string;
+    /** Resolved key value. Only used as a last resort (inline apiKey, no apiKeyEnv). */
+    readonly apiKey?: string;
+    /** Name of the env var the key was read from; forwarded instead of the raw value when present. */
+    readonly apiKeyEnv?: string;
+    readonly dim?: number;
+    /** Per-call embeddings timeout in ms; mirrors the host default when unset (see createRecallStore). */
+    readonly timeoutMs?: number;
+    /** Circuit-breaker overrides; unset fields fall back to the breaker defaults. */
+    readonly circuitBreaker?: MemoryRecallEmbeddingsCircuitBreaker;
+}
+export interface MemoryRecallSettings {
+    /** Memory root directory (config.memory.path). */
+    readonly root: string;
+    /** Embeddings for semantic recall. Omitted for an FTS-only (lite) recall store. */
+    readonly embeddings?: MemoryRecallEmbeddings;
+}
+export interface MemoryRecallRuntimeExtension {
+    readonly runtimeOptions: {
+        readonly mcpServers: Record<string, unknown>;
+    };
+    readonly cleanup: () => Promise<void>;
+}
+/**
+ * Bound embeddings calls in the recall child so a slow/cold backend cannot stall a turn for the
+ * provider default. Mirrors the in-app `createConfiguredMemory` host default (agent-host).
+ */
+export declare const DEFAULT_RECALL_EMBEDDINGS_TIMEOUT_MS = 10000;
+/**
+ * Resolve recall settings from the single in-app memory block. Returns `undefined` (recall off) only
+ * when memory is unconfigured or the recall tool is disabled. When the operator explicitly enables
+ * recall on a no-embeddings store (lite tier), settings are returned WITHOUT embeddings so the child
+ * serves FTS-only recall — the config layer deliberately supports this forced-on opt-in.
+ */
+export declare function resolveMemoryRecallSettings(config: MonoAgentConfig): MemoryRecallSettings | undefined;
+/**
+ * Re-read recall settings from the recall server's own environment (the stdio child process).
+ *
+ * Only `MONO_AGENT_MEMORY_PATH` is required. When the embeddings provider/model are both absent the
+ * child runs FTS-only (no embedding provider). When present, the embeddings slice — including the
+ * resilience knobs (timeout + circuit breaker) — is rehydrated. The api key is resolved from the
+ * inherited env var named by `MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY_ENV` when set, falling back to a
+ * literal `MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY` (the inline-key case).
+ */
+export declare function memoryRecallSettingsFromEnv(env: Record<string, string | undefined>): MemoryRecallSettings;
+/**
+ * Env passed to the recall stdio child. Reuses the MONO_AGENT_MEMORY_* names the old memory-mcp used.
+ *
+ * With no embeddings the child runs FTS-only and only the memory path is emitted. The embeddings
+ * resilience knobs (timeout + circuit breaker) are forwarded so the child wraps its provider exactly
+ * like the in-app store. SECRET HANDLING (F13): when `apiKeyEnv` is present the env-var NAME is
+ * forwarded (NOT the value) and the child re-reads it from its inherited process env; the raw
+ * `MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY` value is emitted ONLY for the inline-key residual (an inline
+ * `apiKey` with no `apiKeyEnv`), where there is no name to forward.
+ */
+export declare function memoryRecallMcpEnv(settings: MemoryRecallSettings): Record<string, string>;
+export declare function memoryRecallMcpServerSpec(settings: MemoryRecallSettings, cwd: string): Record<string, unknown>;
+/**
+ * Build the per-request runtime extension that injects the recall server. The cleanup is a no-op:
+ * the stdio child owns its store lifecycle and drains on signal (see memory-recall-main).
+ */
+export declare function createMemoryRecallRuntimeExtension(settings: MemoryRecallSettings, cwd: string): () => Promise<MemoryRecallRuntimeExtension>;
+/**
+ * Build a RECALL-ONLY store: embeddings + FTS, no chat LLM (recall needs none, so capture/reflect
+ * stay disabled here). With no embeddings (lite tier / explicit FTS-only opt-in) the store is built
+ * without an embedding provider and serves FTS-only recall.
+ *
+ * The embedding provider is wrapped with the SAME resilience as the in-app store
+ * (`createConfiguredMemory`): a bounded per-call timeout (default
+ * {@link DEFAULT_RECALL_EMBEDDINGS_TIMEOUT_MS}) keeps a slow backend from stalling recall, and a
+ * circuit breaker fast-fails after repeated failures so a sustained outage stops blocking it.
+ */
+export declare function createRecallStore(settings: MemoryRecallSettings): BujoMemoryStore;
+/** Register the single read-only `memory_recall` tool against a store. */
+export declare function createMemoryRecallServer(store: BujoMemoryStore): McpServer;
+//# sourceMappingURL=memory-recall.d.ts.map

package/dist/memory-recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-recall.d.ts","sourceRoot":"","sources":["../src/memory-recall.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE,+GAA+G;AAC/G,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,iGAAiG;AACjG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sGAAsG;IACtG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,cAAc,CAAC,EAAE,oCAAoC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,QAAQ,CAAC,UAAU,CAAC,EAAE,sBAAsB,CAAC;CAC9C;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,cAAc,EAAE;QACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC9C,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;;;GAGG;AACH,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,oBAAoB,GAAG,SAAS,CA6BrG;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,oBAAoB,CAuDzG;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuBzF;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ9G;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,oBAAoB,EAC9B,GAAG,EAAE,MAAM,GACV,MAAM,OAAO,CAAC,4BAA4B,CAAC,CAS7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,eAAe,CAwBjF;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CA0B1E"}

package/dist/memory-recall.js

@@ -0,0 +1,275 @@
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createBujoMemoryStore } from "@mono-agent/memory-bujo";
+import { createCircuitBreakerEmbeddingProvider, createEmbeddingProvider } from "@mono-agent/memory-search";
+import * as z from "zod/v4";
+/**
+ * Read-only memory recall, wired from the SINGLE `config.memory` block.
+ *
+ * When `config.memory.recallTool.enabled` is true, the app exposes a `memory_recall` MCP tool
+ * (server name {@link MEMORY_RECALL_MCP_SERVER_NAME}) to the agent. Recall needs only embeddings +
+ * FTS — no chat LLM — so the recall server is built with embeddings alone. When embeddings are
+ * absent (lite tier, or an explicit opt-in on a no-embeddings store) recall still serves FTS-only
+ * (lexical) results. Capture stays in-app (unchanged); this module never touches it.
+ *
+ * Embeddings parity with the in-app store (`createConfiguredMemory`): the recall child applies the
+ * SAME resilience wrapping — a per-call timeout plus a circuit breaker — so a slow/failing backend
+ * cannot stall or repeatedly block recall in the child process either.
+ *
+ * Secret handling: the raw embeddings api key is NOT copied into the recall child's env. When the
+ * key was sourced from a named environment variable (`apiKeyEnv`) we forward only the NAME and the
+ * child re-reads the value from its inherited process env at runtime. An inline literal key (no
+ * `apiKeyEnv`) still has to transit the child env as a value — that residual is documented on
+ * {@link memoryRecallMcpEnv}.
+ *
+ * A stdio MCP server is injected purely as an `mcpServers` entry via the per-request runtime
+ * options. MCP tools are not gated by `tools.allowedTools`, so no allowlist entry is required.
+ */
+export const MEMORY_RECALL_MCP_SERVER_NAME = "mono-agent-memory";
+/**
+ * Bound embeddings calls in the recall child so a slow/cold backend cannot stall a turn for the
+ * provider default. Mirrors the in-app `createConfiguredMemory` host default (agent-host).
+ */
+export const DEFAULT_RECALL_EMBEDDINGS_TIMEOUT_MS = 10_000;
+/**
+ * Resolve recall settings from the single in-app memory block. Returns `undefined` (recall off) only
+ * when memory is unconfigured or the recall tool is disabled. When the operator explicitly enables
+ * recall on a no-embeddings store (lite tier), settings are returned WITHOUT embeddings so the child
+ * serves FTS-only recall — the config layer deliberately supports this forced-on opt-in.
+ */
+export function resolveMemoryRecallSettings(config) {
+    const memory = config.memory;
+    if (memory === undefined) {
+        return undefined;
+    }
+    if (memory.recallTool?.enabled !== true) {
+        return undefined;
+    }
+    const embeddings = memory.embeddings;
+    if (embeddings === undefined) {
+        // Explicit opt-in without embeddings → FTS-only recall (no embedding provider built).
+        return { root: memory.path };
+    }
+    return {
+        root: memory.path,
+        embeddings: {
+            provider: embeddings.provider,
+            model: embeddings.model,
+            ...(embeddings.endpoint === undefined ? {} : { endpoint: embeddings.endpoint }),
+            // Prefer forwarding the env-var NAME over the resolved secret value (F13): when apiKeyEnv is
+            // present the child re-reads the key from its inherited env, so the raw key never lands in the
+            // child's spec env. The literal apiKey is kept only as a fallback for the inline-key case.
+            ...(embeddings.apiKeyEnv === undefined ? {} : { apiKeyEnv: embeddings.apiKeyEnv }),
+            ...(embeddings.apiKey === undefined ? {} : { apiKey: embeddings.apiKey }),
+            ...(embeddings.dim === undefined ? {} : { dim: embeddings.dim }),
+            ...(embeddings.timeoutMs === undefined ? {} : { timeoutMs: embeddings.timeoutMs }),
+            ...(embeddings.circuitBreaker === undefined ? {} : { circuitBreaker: embeddings.circuitBreaker }),
+        },
+    };
+}
+/**
+ * Re-read recall settings from the recall server's own environment (the stdio child process).
+ *
+ * Only `MONO_AGENT_MEMORY_PATH` is required. When the embeddings provider/model are both absent the
+ * child runs FTS-only (no embedding provider). When present, the embeddings slice — including the
+ * resilience knobs (timeout + circuit breaker) — is rehydrated. The api key is resolved from the
+ * inherited env var named by `MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY_ENV` when set, falling back to a
+ * literal `MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY` (the inline-key case).
+ */
+export function memoryRecallSettingsFromEnv(env) {
+    const root = optionalString(env.MONO_AGENT_MEMORY_PATH);
+    if (root === undefined) {
+        throw new Error("memory-recall: missing required environment (MONO_AGENT_MEMORY_PATH).");
+    }
+    const provider = optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_PROVIDER);
+    const model = optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_MODEL);
+    if (provider === undefined && model === undefined) {
+        // No embeddings configured → FTS-only recall store.
+        return { root };
+    }
+    if (provider === undefined || model === undefined) {
+        throw new Error("memory-recall: incomplete embeddings environment (MONO_AGENT_MEMORY_EMBEDDINGS_PROVIDER and MONO_AGENT_MEMORY_EMBEDDINGS_MODEL must be set together).");
+    }
+    if (provider !== "ollama" && provider !== "openai") {
+        throw new Error(`memory-recall: unsupported MONO_AGENT_MEMORY_EMBEDDINGS_PROVIDER "${provider}" (expected "ollama" or "openai").`);
+    }
+    const endpoint = optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_ENDPOINT);
+    const apiKeyEnv = optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY_ENV);
+    // Resolve the key from the named inherited var first (F13); fall back to a literal value.
+    const apiKey = (apiKeyEnv === undefined ? undefined : optionalString(env[apiKeyEnv])) ??
+        optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY);
+    const dim = parseDim(optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_DIM));
+    const timeoutMs = parsePositiveInt(optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_TIMEOUT_MS), "MONO_AGENT_MEMORY_EMBEDDINGS_TIMEOUT_MS");
+    const failureThreshold = parsePositiveInt(optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_CIRCUIT_BREAKER_FAILURE_THRESHOLD), "MONO_AGENT_MEMORY_EMBEDDINGS_CIRCUIT_BREAKER_FAILURE_THRESHOLD");
+    const cooldownMs = parsePositiveInt(optionalString(env.MONO_AGENT_MEMORY_EMBEDDINGS_CIRCUIT_BREAKER_COOLDOWN_MS), "MONO_AGENT_MEMORY_EMBEDDINGS_CIRCUIT_BREAKER_COOLDOWN_MS");
+    const circuitBreaker = failureThreshold === undefined && cooldownMs === undefined
+        ? undefined
+        : {
+            ...(failureThreshold === undefined ? {} : { failureThreshold }),
+            ...(cooldownMs === undefined ? {} : { cooldownMs }),
+        };
+    return {
+        root,
+        embeddings: {
+            provider,
+            model,
+            ...(endpoint === undefined ? {} : { endpoint }),
+            ...(apiKeyEnv === undefined ? {} : { apiKeyEnv }),
+            ...(apiKey === undefined ? {} : { apiKey }),
+            ...(dim === undefined ? {} : { dim }),
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            ...(circuitBreaker === undefined ? {} : { circuitBreaker }),
+        },
+    };
+}
+/**
+ * Env passed to the recall stdio child. Reuses the MONO_AGENT_MEMORY_* names the old memory-mcp used.
+ *
+ * With no embeddings the child runs FTS-only and only the memory path is emitted. The embeddings
+ * resilience knobs (timeout + circuit breaker) are forwarded so the child wraps its provider exactly
+ * like the in-app store. SECRET HANDLING (F13): when `apiKeyEnv` is present the env-var NAME is
+ * forwarded (NOT the value) and the child re-reads it from its inherited process env; the raw
+ * `MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY` value is emitted ONLY for the inline-key residual (an inline
+ * `apiKey` with no `apiKeyEnv`), where there is no name to forward.
+ */
+export function memoryRecallMcpEnv(settings) {
+    const { embeddings } = settings;
+    if (embeddings === undefined) {
+        return { MONO_AGENT_MEMORY_PATH: settings.root };
+    }
+    // Forward the secret only as a last resort: prefer the env-var name passthrough.
+    const forwardLiteralApiKey = embeddings.apiKeyEnv === undefined && embeddings.apiKey !== undefined;
+    return {
+        MONO_AGENT_MEMORY_PATH: settings.root,
+        MONO_AGENT_MEMORY_EMBEDDINGS_PROVIDER: embeddings.provider,
+        MONO_AGENT_MEMORY_EMBEDDINGS_MODEL: embeddings.model,
+        ...(embeddings.endpoint === undefined ? {} : { MONO_AGENT_MEMORY_EMBEDDINGS_ENDPOINT: embeddings.endpoint }),
+        ...(embeddings.apiKeyEnv === undefined ? {} : { MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY_ENV: embeddings.apiKeyEnv }),
+        ...(forwardLiteralApiKey ? { MONO_AGENT_MEMORY_EMBEDDINGS_API_KEY: embeddings.apiKey } : {}),
+        ...(embeddings.dim === undefined ? {} : { MONO_AGENT_MEMORY_EMBEDDINGS_DIM: String(embeddings.dim) }),
+        ...(embeddings.timeoutMs === undefined ? {} : { MONO_AGENT_MEMORY_EMBEDDINGS_TIMEOUT_MS: String(embeddings.timeoutMs) }),
+        ...(embeddings.circuitBreaker?.failureThreshold === undefined
+            ? {}
+            : { MONO_AGENT_MEMORY_EMBEDDINGS_CIRCUIT_BREAKER_FAILURE_THRESHOLD: String(embeddings.circuitBreaker.failureThreshold) }),
+        ...(embeddings.circuitBreaker?.cooldownMs === undefined
+            ? {}
+            : { MONO_AGENT_MEMORY_EMBEDDINGS_CIRCUIT_BREAKER_COOLDOWN_MS: String(embeddings.circuitBreaker.cooldownMs) }),
+    };
+}
+export function memoryRecallMcpServerSpec(settings, cwd) {
+    return {
+        type: "stdio",
+        command: process.execPath,
+        args: [fileURLToPath(new URL("./memory-recall-main.js", import.meta.url))],
+        cwd,
+        env: memoryRecallMcpEnv(settings),
+    };
+}
+/**
+ * Build the per-request runtime extension that injects the recall server. The cleanup is a no-op:
+ * the stdio child owns its store lifecycle and drains on signal (see memory-recall-main).
+ */
+export function createMemoryRecallRuntimeExtension(settings, cwd) {
+    return async () => ({
+        runtimeOptions: {
+            mcpServers: {
+                [MEMORY_RECALL_MCP_SERVER_NAME]: memoryRecallMcpServerSpec(settings, cwd),
+            },
+        },
+        cleanup: async () => { },
+    });
+}
+/**
+ * Build a RECALL-ONLY store: embeddings + FTS, no chat LLM (recall needs none, so capture/reflect
+ * stay disabled here). With no embeddings (lite tier / explicit FTS-only opt-in) the store is built
+ * without an embedding provider and serves FTS-only recall.
+ *
+ * The embedding provider is wrapped with the SAME resilience as the in-app store
+ * (`createConfiguredMemory`): a bounded per-call timeout (default
+ * {@link DEFAULT_RECALL_EMBEDDINGS_TIMEOUT_MS}) keeps a slow backend from stalling recall, and a
+ * circuit breaker fast-fails after repeated failures so a sustained outage stops blocking it.
+ */
+export function createRecallStore(settings) {
+    const { embeddings } = settings;
+    if (embeddings === undefined) {
+        // FTS-only recall: no embedding provider, no dim (mirrors the lite-tier store shape).
+        return createBujoMemoryStore({ root: settings.root });
+    }
+    const providerConfig = {
+        provider: embeddings.provider,
+        model: embeddings.model,
+        ...(embeddings.endpoint === undefined ? {} : { endpoint: embeddings.endpoint }),
+        ...(embeddings.apiKey === undefined ? {} : { apiKey: embeddings.apiKey }),
+        timeoutMs: embeddings.timeoutMs ?? DEFAULT_RECALL_EMBEDDINGS_TIMEOUT_MS,
+    };
+    const breakerOptions = {
+        ...(embeddings.circuitBreaker?.failureThreshold === undefined
+            ? {}
+            : { failureThreshold: embeddings.circuitBreaker.failureThreshold }),
+        ...(embeddings.circuitBreaker?.cooldownMs === undefined ? {} : { cooldownMs: embeddings.circuitBreaker.cooldownMs }),
+    };
+    return createBujoMemoryStore({
+        root: settings.root,
+        embeddings: createCircuitBreakerEmbeddingProvider(createEmbeddingProvider(providerConfig), breakerOptions),
+        dim: embeddings.dim ?? 768,
+    });
+}
+/** Register the single read-only `memory_recall` tool against a store. */
+export function createMemoryRecallServer(store) {
+    const server = new McpServer({ name: "agent-memory", version: "0.3.0" });
+    server.registerTool("memory_recall", {
+        title: "Recall from memory",
+        description: "Read-only hybrid (keyword + semantic) search over long-term memory. Use to recall facts, decisions, and context.",
+        inputSchema: {
+            query: z.string().min(1).describe("Natural-language description of what to recall."),
+            limit: z.number().int().min(1).max(50).optional().describe("Max results (default 8)."),
+        },
+    }, async (args) => {
+        const topK = clampLimit(args.limit, 8);
+        const hits = await store.recall(args.query, { topK });
+        if (hits.length === 0) {
+            return { content: [{ type: "text", text: `No memories matched "${args.query}".` }], structuredContent: { hits: [] } };
+        }
+        const text = hits.map((hit) => `${hit.score.toFixed(3)}  ${hit.record.text}`).join("\n");
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: { hits: hits.map((hit) => ({ id: hit.record.id, score: hit.score, text: hit.record.text })) },
+        };
+    });
+    return server;
+}
+function clampLimit(limit, fallback) {
+    if (limit === undefined || !Number.isFinite(limit)) {
+        return fallback;
+    }
+    return Math.min(50, Math.max(1, Math.trunc(limit)));
+}
+function optionalString(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function parseDim(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`memory-recall: invalid MONO_AGENT_MEMORY_EMBEDDINGS_DIM "${raw}" (expected a positive integer).`);
+    }
+    return parsed;
+}
+function parsePositiveInt(raw, name) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`memory-recall: invalid ${name} "${raw}" (expected a positive integer).`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=memory-recall.js.map

package/dist/memory-recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-recall.js","sourceRoot":"","sources":["../src/memory-recall.ts"],"names":[],"mappings":"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"}

package/dist/sessions.d.ts

@@ -0,0 +1,21 @@
+import type { MonoAgentAppConfigInput } from "./app-config.js";
+export interface PurgeSessionsResult {
+    /** The resolved sessions root, or undefined when sessions are in-memory only. */
+    readonly root?: string;
+    /** True when an on-disk sessions store existed and was removed. */
+    readonly removed: boolean;
+    /** Count of removed `*.jsonl` session files (best-effort; 0 when none/unknown). */
+    readonly files: number;
+}
+/**
+ * Remove the durable pi-session store so the next start begins with fresh sessions
+ * instead of resuming persisted transcripts. A no-op (`removed: false`) when no
+ * on-disk store is configured (in-memory sessions) or the directory does not exist.
+ *
+ * The runtime recreates the directory on the next session, and the agent's durable
+ * memory lives elsewhere (`memory.path`), so this drops only resumable conversation
+ * transcripts — not the knowledge base. Stop the worker before calling this so it is
+ * not writing sessions while they are deleted.
+ */
+export declare function purgeSessions(input: MonoAgentAppConfigInput): Promise<PurgeSessionsResult>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgBhG"}

package/dist/sessions.js

@@ -0,0 +1,45 @@
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveAppSessionsRoot } from "./app-config.js";
+/**
+ * Remove the durable pi-session store so the next start begins with fresh sessions
+ * instead of resuming persisted transcripts. A no-op (`removed: false`) when no
+ * on-disk store is configured (in-memory sessions) or the directory does not exist.
+ *
+ * The runtime recreates the directory on the next session, and the agent's durable
+ * memory lives elsewhere (`memory.path`), so this drops only resumable conversation
+ * transcripts — not the knowledge base. Stop the worker before calling this so it is
+ * not writing sessions while they are deleted.
+ */
+export async function purgeSessions(input) {
+    const root = await resolveAppSessionsRoot(input);
+    if (root === undefined) {
+        return { removed: false, files: 0 };
+    }
+    let files = 0;
+    try {
+        files = await countSessionFiles(root);
+    }
+    catch {
+        // The store may not exist yet; treat it as nothing to remove.
+        return { root, removed: false, files: 0 };
+    }
+    await rm(root, { recursive: true, force: true });
+    return { root, removed: true, files };
+}
+/** Recursively count `*.jsonl` session files under a sessions root. */
+async function countSessionFiles(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    let total = 0;
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            total += await countSessionFiles(full);
+        }
+        else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+            total += 1;
+        }
+    }
+    return total;
+}
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAYzD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAA8B;IAChE,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;QAC9D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACxC,CAAC;AAED,uEAAuE;AACvE,KAAK,UAAU,iBAAiB,CAAC,GAAW;IAC1C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,KAAK,IAAI,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/ui.d.ts

@@ -0,0 +1,54 @@
+import type { ValidationStatus } from "./doctor.js";
+/**
+ * Decide whether ANSI color should be emitted. `NO_COLOR` (any value) always
+ * wins per the no-color.org convention; `FORCE_COLOR` forces the decision when
+ * set to a recognized truthy/falsy value; otherwise color follows the TTY-ness
+ * of the stream. Pure and env-injected so it is trivially testable.
+ */
+export declare function computeColorEnabled(env: Record<string, string | undefined>, isTty: boolean | undefined): boolean;
+export declare function isColorEnabled(): boolean;
+/** Color/weight helpers. Each is the identity function when color is disabled. */
+export declare const style: {
+    readonly bold: (text: string) => string;
+    readonly dim: (text: string) => string;
+    readonly red: (text: string) => string;
+    readonly green: (text: string) => string;
+    readonly yellow: (text: string) => string;
+    readonly cyan: (text: string) => string;
+    readonly gray: (text: string) => string;
+};
+/**
+ * Render a status badge as a fixed-width prefix (badge + trailing space). With
+ * color on it is a green/yellow/dim/red glyph; with color off it falls back to
+ * an equal-width ASCII tag so columns still line up in plain output.
+ */
+export declare function badge(status: ValidationStatus): string;
+/**
+ * Render aligned `label  value` rows: labels are padded to the widest label so
+ * values line up, replacing the hand-tuned `padEnd` blocks. `indent` prefixes
+ * every row with that many spaces (used to nest rows under a section rule).
+ * Returns one string with a trailing newline per row (empty when there are no
+ * rows).
+ */
+export declare function keyValue(rows: ReadonlyArray<readonly [label: string, value: string]>, indent?: number): string;
+/**
+ * A horizontal section divider, optionally labeled — `── instance ────────`.
+ * Width tracks the terminal (read at call time so resizes are honored), capped
+ * for readability and falling back to a fixed width when stdout is not a TTY.
+ * Rendered dim/gray (identity when color is off); the label appears verbatim so
+ * it stays greppable. Always ends with a newline.
+ */
+export declare function rule(label?: string): string;
+/** Badge for a channel status *kind* string (running/waiting…/disabled/error). */
+export declare function channelBadge(kind: string): string;
+/** Badge for a trace-source health word (running/stale/stopped/…). */
+export declare function healthBadge(health: string): string;
+/** A bold/cyan section heading with a trailing newline. */
+export declare function heading(text: string): string;
+/** The CLI title block: bold title plus an optional dim subtitle. */
+export declare function banner(title: string, subtitle?: string): string;
+/** A red error line (✗ prefix) with a trailing newline — write to stderr. */
+export declare function errorLine(message: string): string;
+/** A dim hint line (→ prefix) with a trailing newline. */
+export declare function hint(message: string): string;
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAuBpD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,KAAK,EAAE,OAAO,GAAG,SAAS,GACzB,OAAO,CAYT;AAID,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAMD,kFAAkF;AAClF,eAAO,MAAM,KAAK;0BACH,MAAM,KAAG,MAAM;yBAChB,MAAM,KAAG,MAAM;yBACf,MAAM,KAAG,MAAM;2BACb,MAAM,KAAG,MAAM;4BACd,MAAM,KAAG,MAAM;0BACjB,MAAM,KAAG,MAAM;0BACf,MAAM,KAAG,MAAM;CACpB,CAAC;AAgBX;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAGtD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAC5D,MAAM,SAAI,GACT,MAAM,CASR;AAKD;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3C;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAcjD;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,2DAA2D;AAC3D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,qEAAqE;AACrE,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5C"}