@jungjaehoon/mama-os 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-05-01
+
+### Added
+
+- **Reactive envelope runtime** — Standalone now issues and stores signed gateway envelopes, exposes
+  public health separately from authenticated envelope status, and audits scope mismatches through
+  `agent_activity`
+- **Worker evidence APIs** — Added authenticated memory provenance, raw search, agent situation,
+  and agent graph/entity API handlers so workers can retrieve bounded evidence without direct DB
+  access
+- **Envelope-aware gateway tooling** — Code-Act, gateway execution, internal agent-loop calls, and
+  model/tool trace paths now propagate envelope context for trusted provenance
+- **Strict `mama_search` controls** — Gateway, MCP, Code-Act, ToolRegistry, and generated tool docs
+  now expose `scopes`, `strict`, `strictness`, `threshold`, `disableRecency`, `includeRelated`,
+  `topicPrefix`, `minLexicalSupport`, and `diagnostics`
+- **Persistent process cleanup settings** — `timeouts.persistent_process_idle_ms`,
+  `timeouts.persistent_process_cleanup_ms`, and `timeouts.persistent_process_pending_tool_ms`
+  let operators tune how aggressively idle CLI processes are reclaimed
+
+### Changed
+
+- **Gateway executor architecture** — Delegation execution and gateway tool execution were split
+  into clearer modules, with ToolRegistry kept as the valid-tool source of truth for generated
+  prompts and executor validation
+- **Connector raw stores** — Raw connector persistence now writes provenance and unified indexes so
+  worker APIs can query raw evidence consistently
+- **Envelope-aware memory search** — `mama_search` now defaults to effective envelope scopes and
+  rejects caller scopes outside the active envelope before searching
+- **Search diagnostics preservation** — Standalone search result types and handler responses now
+  keep `diagnostics`, `retrieval_diagnostics`, and `contributing_leaf_diagnostics` instead of
+  dropping them at API boundaries
+
+### Fixed
+
+- **Envelope hardening** — Reactive envelope startup, internal tool contexts, scope mismatch
+  logging, authenticated status reporting, worker graph/entity visibility, and graph API internal
+  error responses now have review-driven regression coverage
+- **Scoped recent-list search** — No-query `mama_search` now passes scopes into recent decision
+  listing instead of returning global recent decisions
+- **Long-lived Claude process buildup** — Persistent CLI processes are now reclaimed after idle
+  timeouts while active tool-result loops keep a bounded lease; `mama stop` also avoids unsafe
+  broad kills and handles large `ps` output safely
+
 ## [0.19.1] - 2026-04-20
 
 ### Fixed

package/README.md

@@ -1,22 +1,28 @@
 # @jungjaehoon/mama-os
 
-> Your scattered knowledge, organized by AI agents that never sleep.
+> Bounded, provenance-backed working context for AI agents running on your machine.
 
 ## The Problem
 
 Your knowledge is everywhere — Slack threads, email chains, code reviews, meeting notes, spreadsheets, Telegram messages. No human can track all of it. Important decisions get buried. Context gets lost between tools. When you need to make a decision, the information that would help is scattered across ten different apps and three months of history.
 
-This isn't a memory problem. It's an intelligence problem. You don't just need to _store_ information — you need something that reads everything, connects the dots, identifies what matters, and tells you what you're missing.
+This isn't just a memory problem. It's a bounded context problem. You don't just need to
+_store_ information — you need something that reads everything, connects the dots, identifies what
+matters, proves where it came from, and keeps agents inside the scope they were given.
 
 ## What MAMA OS Does
 
-MAMA OS is a local AI runtime that connects to your apps, reads everything continuously, and turns scattered records into organized knowledge.
+MAMA OS is a local AI runtime that connects to your apps, reads continuously, and turns scattered
+records into scoped, auditable context for agents and humans.
 
 **What the agents actually do:**
 
 - **Identify what matters** — Out of thousands of daily messages, surface the decisions, deadlines, and changes that affect your work
 - **Connect across sources** — A Slack conversation + a Trello card + an email attachment about the same project are linked automatically
 - **Track decision evolution** — Not just what was decided, but what it replaced, what it builds on, and what it contradicts
+- **Operate inside envelopes** — Gateway and worker calls carry signed scope boundaries and audit rows
+- **Preserve provenance** — Memory writes can point back to source refs, model runs, tool traces, and envelope hashes
+- **Search with evidence** — Strict memory search can reject vector-only noise and show which lexical, entity, scope, or graph signals confirmed a result
 - **Compile actionable knowledge** — Raw conversations become structured wiki pages with priorities, gaps, and suggested next steps
 - **Brief you proactively** — When you start working, relevant context from all sources is already there — you didn't ask for it
 
@@ -28,7 +34,8 @@ With MAMA:     Agents already read everything. You get a briefing with
                what changed, what's at risk, and what needs your decision.
 ```
 
-**This is what AI agents can do that humans can't** — read every channel, every thread, every document, every day, and never miss a connection.
+**This is what local AI agents should do** — read every channel, every thread, every document, every
+day, then explain exactly which evidence they used and which permission boundary they were inside.
 
 - **Private by design** — All data stays on your device. Nothing leaves your machine.
 - **AI-independent** — Works with Claude, Codex, or any future backend. Your memory outlives any AI provider.
@@ -49,6 +56,10 @@ mama start   # That's it. MAMA uses your existing CLI authentication.
 MAMA OS has full system access — so security is not optional, it's foundational.
 
 - **Local-only by default** — Binds to localhost. External access requires explicit tunnel setup with authentication (Cloudflare Zero Trust).
+- **Signed runtime envelopes** — Gateway and worker tool calls carry verifiable scope, expiry, and
+  actor context before irreversible side effects are allowed.
+- **Provenance ledger** — Memory writes, raw refs, model runs, and tool traces can be audited after
+  the fact without exposing prompt bodies or hidden connector payloads.
 - **5-layer prompt injection defense** — Output sanitization, channel trust boundaries, silent mode for unknown sources, bulk extraction limits. Built from a real incident, not theory.
 - **Intrusion detection** — Honeypot traps for scanner probes (`.git`, `.env`, `wp-login.php`), per-IP suspicion scoring, automatic tarpit delays, and IP deny-listing when thresholds are exceeded.
 - **Agent permission tiers** — Tier 1 (full access), Tier 2 (read-only), Tier 3 (scoped read-only). Each agent only gets the tools it needs.
@@ -139,20 +150,21 @@ Run MAMA as a bot in Discord, Slack, Telegram, or Chatwork. Configure via `mama
 ## Architecture
 
 ```
-Connectors (15)          Gateways (4)
-Slack, Gmail, Sheets...  Discord, Slack, Telegram, Chatwork
-       |                        |
-       v                        v
- 3-Pass Extraction       Multi-Agent System
-       |                        |
-       +--------+-------+------+
-                |
-         MAMA Core (mama-memory.db)
-         Local SQLite + 1024-dim embeddings
-                |
-         +------+------+
-         |             |
-    Viewer UI     Claude Code Plugin
+Connectors (15)              Gateways (4)
+Slack, Gmail, Sheets...      Discord, Slack, Telegram, Chatwork
+       |                            |
+       v                            v
+ 3-Pass Extraction          Reactive Runtime Envelopes
+       |                    scope, expiry, signature, audit
+       +------------+---------------+
+                    |
+             MAMA Core (mama-memory.db)
+             memory, raw refs, model runs,
+             tool traces, twin edges, packets
+                    |
+             +------+------+
+             |             |
+        Viewer UI     Claude Code Plugin / MCP
 ```
 
 ## CLI
@@ -176,6 +188,14 @@ Main config: `~/.mama/config.yaml`
 | `MAMA_HTTP_PORT` | `3847`                   |
 | `MAMA_WORKSPACE` | `~/.mama/workspace`      |
 
+Timeout tuning lives under `timeouts` in `config.yaml`. The persistent CLI process pool supports:
+
+| Option                               | Default                     | Purpose                                     |
+| ------------------------------------ | --------------------------- | ------------------------------------------- |
+| `persistent_process_idle_ms`         | `session_ms`                | Reclaim idle Claude/Codex CLI processes     |
+| `persistent_process_cleanup_ms`      | `session_cleanup_ms`        | How often idle-process cleanup runs         |
+| `persistent_process_pending_tool_ms` | `max(4 * idle, 30 minutes)` | Max wait for pending tool-result handshakes |
+
 ## Related Packages
 
 | Package                      | Purpose                             |
@@ -189,7 +209,7 @@ Main config: `~/.mama/config.yaml`
 ```bash
 git clone https://github.com/jungjaehoon-lifegamez/MAMA.git
 cd MAMA && pnpm install && pnpm build
-pnpm test       # 2800+ tests across all packages
+pnpm test       # 3000+ tests across all packages
 ```
 
 ## Links
@@ -202,4 +222,4 @@ MIT
 
 ---
 
-**Last Updated:** 2026-04-20
+**Last Updated:** 2026-04-30

package/dist/agent/agent-loop.d.ts

@@ -10,7 +10,7 @@
  * - Loops until stop_reason is "end_turn" or max turns reached
  */
 import type { OAuthManager } from '../auth/index.js';
-import type { ContentBlock, ToolDefinition, AgentLoopOptions, AgentLoopResult, ClaudeClientOptions, GatewayToolExecutorOptions, AgentContext } from './types.js';
+import type { ContentBlock, ToolDefinition, AgentLoopOptions, AgentLoopResult, ClaudeClientOptions, GatewayToolExecutorOptions, AgentContext, GatewayToolExecutionContext } from './types.js';
 /**
  * Load composed system prompt with persona layers + CLAUDE.md + optional context
  * Tries to load persona files from ~/.mama/ in order:
@@ -32,6 +32,8 @@ import type { ContentBlock, ToolDefinition, AgentLoopOptions, AgentLoopResult, C
 export declare function loadBackendAgentsMd(backend?: string, verbose?: boolean): string;
 export declare function loadComposedSystemPrompt(verbose?: boolean, context?: AgentContext): string;
 export declare function getGatewayToolsPrompt(disallowed?: string[]): string;
+export type AgentToolExecutionContext = GatewayToolExecutionContext;
+export declare function buildAgentToolExecutionContext(options?: AgentLoopOptions): AgentToolExecutionContext | null;
 export declare class AgentLoop {
     private readonly agent;
     private readonly persistentCLI;
@@ -172,6 +174,10 @@ export declare class AgentLoop {
      * Internal implementation of runWithContent (without lane queueing)
      */
     private runWithContentInternal;
+    private shouldBeginModelRun;
+    private withBackgroundTaskRegistry;
+    private drainBackgroundTasks;
+    private buildModelRunInput;
     /**
      * Execute tools from response content blocks
      */

package/dist/agent/agent-loop.d.ts.map

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

package/dist/agent/agent-loop.js

@@ -48,6 +48,7 @@ exports.AgentLoop = void 0;
 exports.loadBackendAgentsMd = loadBackendAgentsMd;
 exports.loadComposedSystemPrompt = loadComposedSystemPrompt;
 exports.getGatewayToolsPrompt = getGatewayToolsPrompt;
+exports.buildAgentToolExecutionContext = buildAgentToolExecutionContext;
 const fs_1 = require("fs");
 const prompt_size_monitor_js_1 = require("./prompt-size-monitor.js");
 const skill_loader_js_1 = require("./skill-loader.js");
@@ -249,6 +250,53 @@ function getGatewayToolsPrompt(disallowed) {
     }
     return filtered;
 }
+function buildAgentToolExecutionContext(options) {
+    if (!options ||
+        (options.agentContext === undefined &&
+            options.source === undefined &&
+            options.channelId === undefined &&
+            options.envelope === undefined &&
+            options.sourceTurnId === undefined &&
+            options.sourceMessageRef === undefined &&
+            options.modelRunId === undefined)) {
+        return null;
+    }
+    const agentContext = options.agentContext;
+    const context = {
+        agentContext,
+        agentId: agentContext
+            ? agentContext.source === 'viewer'
+                ? 'os-agent'
+                : agentContext.roleName
+            : undefined,
+        source: options.source,
+        channelId: options.channelId,
+        envelope: options.envelope,
+        executionSurface: 'model_tool',
+    };
+    if (options.sourceTurnId !== undefined) {
+        context.sourceTurnId = options.sourceTurnId;
+    }
+    if (options.sourceMessageRef !== undefined) {
+        context.sourceMessageRef = options.sourceMessageRef;
+    }
+    if (options.modelRunId !== undefined) {
+        context.modelRunId = options.modelRunId;
+    }
+    return context;
+}
+function withExecutionSurface(executionContext, executionSurface) {
+    if (!executionContext) {
+        return null;
+    }
+    if (executionContext.executionSurface === executionSurface) {
+        return executionContext;
+    }
+    return {
+        ...executionContext,
+        executionSurface,
+    };
+}
 class AgentLoop {
     agent;
     persistentCLI = null;
@@ -469,7 +517,7 @@ class AgentLoop {
         this.sessionPool = (0, session_pool_js_1.getSessionPool)();
         // Initialize PostToolHandler (fire-and-forget after tool execution)
         if (options.postToolUse?.enabled) {
-            this.postToolHandler = new post_tool_handler_js_1.PostToolHandler((name, input) => this.mcpExecutor.execute(name, input), { enabled: true, contractSaveLimit: options.postToolUse.contractSaveLimit });
+            this.postToolHandler = new post_tool_handler_js_1.PostToolHandler((name, input, executionContext) => this.mcpExecutor.execute(name, input, executionContext ?? undefined), { enabled: true, contractSaveLimit: options.postToolUse.contractSaveLimit });
             console.log('[AgentLoop] PostToolHandler enabled');
         }
         else {
@@ -477,7 +525,7 @@ class AgentLoop {
         }
         // Initialize PreCompactHandler (unsaved decision detection)
         if (options.preCompact?.enabled) {
-            this.preCompactHandler = new pre_compact_handler_js_1.PreCompactHandler((name, input) => this.mcpExecutor.execute(name, input), { enabled: true, maxDecisionsToDetect: options.preCompact.maxDecisionsToDetect });
+            this.preCompactHandler = new pre_compact_handler_js_1.PreCompactHandler((name, input, executionContext) => this.mcpExecutor.execute(name, input, executionContext ?? undefined), { enabled: true, maxDecisionsToDetect: options.preCompact.maxDecisionsToDetect });
             console.log('[AgentLoop] PreCompactHandler enabled');
         }
         else {
@@ -525,15 +573,7 @@ class AgentLoop {
         return SOURCE_GLOBAL_LANES[source];
     }
     buildToolExecutionContext(options) {
-        if (!options?.agentContext) {
-            return null;
-        }
-        return {
-            agentContext: options.agentContext,
-            agentId: options.agentContext.source === 'viewer' ? 'os-agent' : options.agentContext.roleName,
-            source: options.source,
-            channelId: options.channelId,
-        };
+        return buildAgentToolExecutionContext(options);
     }
     /**
      * Set system prompt override (for per-message context injection)
@@ -675,7 +715,19 @@ class AgentLoop {
         const totalUsage = { input_tokens: 0, output_tokens: 0 };
         let turn = 0;
         let stopReason = 'end_turn';
-        const toolExecutionContext = this.buildToolExecutionContext(options);
+        let ownedModelRunId = null;
+        let ownedModelRunCommitted = false;
+        const pendingBackgroundTasks = [];
+        const backgroundTasks = {
+            register(task) {
+                const observedTask = Promise.resolve(task);
+                observedTask.catch(() => {
+                    // Re-thrown later by drainBackgroundTasks; attach now to prevent unhandled rejections.
+                });
+                pendingBackgroundTasks.push(observedTask);
+            },
+        };
+        let toolExecutionContext = this.withBackgroundTaskRegistry(this.buildToolExecutionContext(options), backgroundTasks);
         // Track current tier for code-act execution and prompt sizing.
         if (options?.agentContext) {
             const rawTier = options.agentContext.tier ?? 1;
@@ -700,6 +752,7 @@ class AgentLoop {
         // Claude PersistentCLI: process alive → CONTINUE (stdin message), process dead → NEW (spawn with --session-id)
         // Codex: threadId alive → CONTINUE (codex-reply), threadId null → NEW (codex tool)
         const isCodex = this.backend === 'codex-mcp';
+        let resolvedCliSessionId = options?.cliSessionId ?? null;
         const sessionLabel = (isNew) => {
             if (isCodex) {
                 return isNew ? 'NEW thread' : 'CONTINUE thread';
@@ -719,10 +772,19 @@ class AgentLoop {
             }
             sessionIsNew = isNew;
             ownedSession = true;
+            resolvedCliSessionId = cliSessionId;
             this.agent.setSessionId(cliSessionId);
             console.log(`[AgentLoop] [${isCodex ? 'codex' : 'claude'}] ${channelKey} (${sessionLabel(isNew)})`);
         }
         try {
+            if (this.shouldBeginModelRun(options)) {
+                const modelRun = await this.mcpExecutor.beginRuntimeModelRun(this.buildModelRunInput(options, resolvedCliSessionId));
+                ownedModelRunId = modelRun.model_run_id;
+                toolExecutionContext = this.withBackgroundTaskRegistry(this.buildToolExecutionContext({
+                    ...options,
+                    modelRunId: ownedModelRunId,
+                }), backgroundTasks);
+            }
             if (options?.systemPrompt) {
                 // Skip gateway tools if already embedded in systemPrompt (e.g. by MessageRouter)
                 const alreadyHasTools = options.systemPrompt.includes('## Gateway Tools') ||
@@ -968,7 +1030,7 @@ class AgentLoop {
                                 .map((b) => b.text)
                                 .join('\n');
                         });
-                        const compactResult = await this.preCompactHandler.process(historyText);
+                        const compactResult = await this.preCompactHandler.process(historyText, withExecutionSurface(toolExecutionContext, 'reactive_internal'));
                         if (compactResult.compactionPrompt) {
                             history.push({
                                 role: 'user',
@@ -1061,13 +1123,39 @@ class AgentLoop {
             }
             // Extract final text response
             const finalResponse = this.extractTextResponse(history);
-            return {
+            const result = {
                 response: finalResponse,
                 turns: turn,
                 history,
                 totalUsage,
                 stopReason,
+                modelRunId: ownedModelRunId ?? options?.modelRunId ?? null,
             };
+            try {
+                await this.drainBackgroundTasks(pendingBackgroundTasks);
+                if (ownedModelRunId) {
+                    await this.mcpExecutor.commitRuntimeModelRun(ownedModelRunId, 'agent_loop completed');
+                    ownedModelRunCommitted = true;
+                }
+            }
+            catch (finalizationError) {
+                logger.warn(`AgentLoop post-run finalization failed: ${finalizationError instanceof Error
+                    ? finalizationError.message
+                    : String(finalizationError)}`);
+            }
+            return result;
+        }
+        catch (error) {
+            if (ownedModelRunId && !ownedModelRunCommitted) {
+                try {
+                    const summary = error instanceof Error ? error.message : String(error);
+                    await this.mcpExecutor.failRuntimeModelRun(ownedModelRunId, summary);
+                }
+                catch (failError) {
+                    logger.warn(`Failed to mark model run ${ownedModelRunId} failed: ${failError instanceof Error ? failError.message : String(failError)}`);
+                }
+            }
+            throw error;
         }
         finally {
             // Always release session lock, even on error
@@ -1078,10 +1166,51 @@ class AgentLoop {
             this.currentStreamCallbacks = undefined;
         }
     }
+    shouldBeginModelRun(options) {
+        return this.isGatewayMode && !options?.modelRunId;
+    }
+    withBackgroundTaskRegistry(context, backgroundTasks) {
+        if (!context) {
+            return null;
+        }
+        return {
+            ...context,
+            backgroundTasks,
+        };
+    }
+    async drainBackgroundTasks(tasks) {
+        for (let index = 0; index < tasks.length; index += 1) {
+            await tasks[index];
+        }
+    }
+    buildModelRunInput(options, resolvedCliSessionId) {
+        const agentContext = options?.agentContext;
+        return {
+            model_id: options?.model ?? this.model ?? null,
+            model_provider: this.backend,
+            agent_id: agentContext?.source === 'viewer'
+                ? 'os-agent'
+                : (agentContext?.roleName ?? options?.source ?? 'agent'),
+            instance_id: agentContext?.session?.sessionId ?? null,
+            envelope_hash: options?.envelope?.envelope_hash ?? null,
+            parent_model_run_id: options?.parentModelRunId ?? null,
+            status: 'running',
+            input_refs: {
+                source: options?.source ?? agentContext?.source ?? 'default',
+                channelId: options?.channelId ?? agentContext?.session?.channelId ?? this.sessionKey,
+                entrypoint: 'agent_loop',
+                ...(options?.sourceTurnId ? { sourceTurnId: options.sourceTurnId } : {}),
+                ...(options?.sourceMessageRef ? { sourceMessageRef: options.sourceMessageRef } : {}),
+                ...(resolvedCliSessionId ? { cliSessionId: resolvedCliSessionId } : {}),
+            },
+        };
+    }
     /**
      * Execute tools from response content blocks
      */
     async executeTools(content, stopAfterSuccessfulTools = [], executionContext = null) {
+        const modelToolContext = withExecutionSurface(executionContext, 'model_tool');
+        const reactiveInternalContext = withExecutionSurface(executionContext, 'reactive_internal');
         const toolUseBlocks = content.filter((block) => block.type === 'tool_use');
         const results = [];
         for (const toolUse of toolUseBlocks) {
@@ -1097,7 +1226,7 @@ class AgentLoop {
                     const codeInput = toolUse.input;
                     const code = typeof codeInput?.code === 'string' ? codeInput.code : '';
                     const codeActResult = code
-                        ? await this.executeCodeAct(code, this.currentTier)
+                        ? await this.executeCodeAct(code, this.currentTier, modelToolContext)
                         : {
                             success: false,
                             error: {
@@ -1118,9 +1247,9 @@ class AgentLoop {
                     // PreToolUse: search MAMA for contracts before Write operations
                     let contractContext = '';
                     if (toolUse.name === 'Write' && toolUse.input) {
-                        contractContext = await this.searchContractsForTool(toolUse.name, toolUse.input, executionContext);
+                        contractContext = await this.searchContractsForTool(toolUse.name, toolUse.input, reactiveInternalContext);
                     }
-                    const toolResult = await this.mcpExecutor.execute(toolUse.name, toolUse.input, executionContext ?? undefined);
+                    const toolResult = await this.mcpExecutor.execute(toolUse.name, toolUse.input, modelToolContext ?? undefined);
                     result = JSON.stringify(toolResult, null, 2);
                     // Check if tool execution failed
                     const hasSuccess = 'success' in toolResult;
@@ -1134,7 +1263,7 @@ class AgentLoop {
                     // Notify tool use callback
                     this.onToolUse?.(toolUse.name, toolUse.input, toolResult);
                     // PostToolUse: auto-extract contracts (fire-and-forget)
-                    this.postToolHandler?.processInBackground(toolUse.name, toolUse.input, toolResult);
+                    this.postToolHandler?.processInBackground(toolUse.name, toolUse.input, toolResult, reactiveInternalContext);
                     // Notify stream: tool completed (check actual status)
                     this.currentStreamCallbacks?.onToolComplete?.(toolUse.name, toolUse.id, isError);
                 }
@@ -1255,10 +1384,11 @@ class AgentLoop {
     /**
      * Execute Code-Act JS code in a sandboxed QuickJS environment
      */
-    async executeCodeAct(code, tier = 1) {
+    async executeCodeAct(code, tier = 1, executionContext = null) {
         try {
             const sandbox = new index_js_1.CodeActSandbox();
-            const bridge = new index_js_1.HostBridge(this.mcpExecutor);
+            const bridgeContext = withExecutionSurface(executionContext, 'code_act');
+            const bridge = new index_js_1.HostBridge(this.mcpExecutor, undefined, bridgeContext);
             bridge.onToolUse = (toolName, input, result) => {
                 if (result === undefined) {
                     // Tool starting — surface to stream