@jungjaehoon/mama-os 0.51.2 → 0.52.0

package/dist/agent/gateway-tool-executor.js

@@ -1,16 +1,4 @@
 "use strict";
-/**
- * MAMA Tool Executor for MAMA Standalone
- *
- * Executes MAMA gateway tools (mama_search, mama_save, mama_update, mama_load_checkpoint, Read, discord_send).
- * NOT MCP - uses Claude Messages API tool definitions.
- * Supports both direct API integration and mock API for testing.
- *
- * Role-Based Permission Control:
- * - Each tool execution is checked against the current AgentContext's role
- * - Blocked tools return permission errors instead of executing
- * - Path-based tools (Read, Write) also check path permissions
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -50,6 +38,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GatewayToolExecutor = void 0;
 exports.serializeCodeActModelResult = serializeCodeActModelResult;
+const skill_loader_js_1 = require("./skill-loader.js");
+const experience_evidence_js_1 = require("../operator/experience-evidence.js");
+/**
+ * MAMA Tool Executor for MAMA Standalone
+ *
+ * Executes MAMA gateway tools (mama_search, mama_save, mama_update, mama_load_checkpoint, Read, discord_send).
+ * NOT MCP - uses Claude Messages API tool definitions.
+ * Supports both direct API integration and mock API for testing.
+ *
+ * Role-Based Permission Control:
+ * - Each tool execution is checked against the current AgentContext's role
+ * - Blocked tools return permission errors instead of executing
+ * - Path-based tools (Read, Write) also check path permissions
+ */
+const procedure_runtime_js_1 = require("../operator/procedure-runtime.js");
+const host_bridge_js_1 = require("./code-act/host-bridge.js");
 const fs_1 = require("fs");
 const async_hooks_1 = require("async_hooks");
 const crypto_1 = require("crypto");
@@ -62,7 +66,7 @@ const mama_core_1 = require("@jungjaehoon/mama-core");
 const security_monitor_js_1 = require("../security/security-monitor.js");
 const node_fs_1 = require("node:fs");
 const secret_filter_js_1 = require("../memory/secret-filter.js");
-const learning_context_js_1 = require("../operator/learning-context.js");
+const board_slot_instructions_js_1 = require("../operator/board-slot-instructions.js");
 const file_export_js_1 = require("../operator/file-export.js");
 const repair_request_js_1 = require("../operator/repair-request.js");
 const scope_context_js_1 = require("../memory/scope-context.js");
@@ -463,6 +467,9 @@ function sanitizeCommandForAudit(command) {
  */
 const tool_registry_js_1 = require("./tool-registry.js");
 const VALID_TOOLS = tool_registry_js_1.ToolRegistry.getValidToolNames();
+const TOOL_CATALOG_REVISION = (0, crypto_1.createHash)('sha256')
+    .update(JSON.stringify(tool_registry_js_1.ToolRegistry.getAllTools()))
+    .digest('hex');
 /**
  * Sensitive patterns that should be masked in config output
  */
@@ -487,7 +494,35 @@ function isExactTelegramDeliveryReceipt(value, deliveryId, variant) {
         Number.isFinite(value.confirmedAt) &&
         value.confirmedAt >= 0);
 }
+/** Gateway tools whose completed execution leaves a durable effect (ledger, memory, file, send). */
+const DURABLE_WRITE_TOOL = /_(?:create|update|publish|send|save|reclassify|retire|observe|bind|reconcile|export|upload|write)$|^console_brief_update$|^Write$|^Bash$/;
 class GatewayToolExecutor {
+    procedureRuntime = null;
+    setProcedureStore(store) {
+        this.procedureRuntime = new procedure_runtime_js_1.ProcedureRuntime(store);
+    }
+    /**
+     * Turn-1 hints for the thread this prompt goes to (procedure-runtime.ts prepareContext).
+     * Skills stay in the system prompt and execution evidence behind experience_read and the
+     * experience_ref on each tool result: neither is re-sent per turn.
+     */
+    prepareProcedureContext(state, turn) {
+        return this.procedureRuntime?.prepareContext(state, turn) ?? { text: '', hints: [] };
+    }
+    /** Did this run complete any tool that durably writes? null when traces are unavailable. */
+    async runHadDurableWrite(modelRunId) {
+        const api = await this.initializeMAMAApi();
+        if (!api.listToolTracesForRun)
+            return null;
+        const traces = await api.listToolTracesForRun(modelRunId);
+        return traces.some((trace) => trace.execution_status === 'completed' && DURABLE_WRITE_TOOL.test(trace.tool_name));
+    }
+    releaseProcedureRun(state) {
+        this.procedureRuntime?.releaseRun(state);
+    }
+    readCanonicalProcedureBrief(state) {
+        return this.procedureRuntime?.canonicalBrief(state) ?? null;
+    }
     driveTools;
     imageTranslationTools;
     driveDestinationCapabilities = new Map();
@@ -668,6 +703,8 @@ class GatewayToolExecutor {
             executionSurface: executionContext?.executionSurface,
             sourceTurnId: executionContext?.sourceTurnId,
             sourceMessageRef: executionContext?.sourceMessageRef,
+            procedureStimulus: executionContext?.procedureStimulus,
+            procedureRefs: executionContext?.procedureRefs,
             modelRunId: executionContext?.modelRunId ?? null,
             gatewayCallId: executionContext?.gatewayCallId,
             workorderAttemptId: executionContext?.workorderAttemptId,
@@ -708,6 +745,8 @@ class GatewayToolExecutor {
             executionSurface: active.executionSurface ?? fallback.executionSurface,
             sourceTurnId: active.sourceTurnId ?? fallback.sourceTurnId,
             sourceMessageRef: active.sourceMessageRef ?? fallback.sourceMessageRef,
+            procedureStimulus: active.procedureStimulus,
+            procedureRefs: active.procedureRefs,
             modelRunId: active.modelRunId ?? fallback.modelRunId,
             gatewayCallId: active.gatewayCallId ?? fallback.gatewayCallId,
             // Never merged from fallback - attempt identity is issued for one claimed run only.
@@ -999,6 +1038,8 @@ class GatewayToolExecutor {
                 getModelRun: mama.getModelRun?.bind(mama),
                 appendToolTrace: mama.appendToolTrace?.bind(mama),
                 listToolTracesForRun: mama.listToolTracesForRun?.bind(mama),
+                listToolTraces: mama.listToolTraces?.bind(mama),
+                readToolTrace: mama.readToolTrace?.bind(mama),
                 createAuditFinding: mama.createAuditFinding?.bind(mama),
                 listOpenAuditFindings: (mama.listOpenAuditFindings ?? mama.listAuditFindings)?.bind(mama),
                 listAuditFindings: mama.listAuditFindings?.bind(mama),
@@ -1313,6 +1354,8 @@ class GatewayToolExecutor {
         const activeCtx = traceState ? { ...ctx, modelRunId: traceState.modelRunId } : ctx;
         let result;
         let auditResult;
+        let executionEvidence;
+        let experienceRef;
         try {
             const rawResult = await this.executionContextStorage.run(activeCtx, () => this.executeWithEnvelopeAndPermissions(toolName, effectiveInput, gatewayCallId));
             if (activeCtx.temporalWorkContext &&
@@ -1322,6 +1365,13 @@ class GatewayToolExecutor {
                     this.requireActiveTemporalAuthority(toolName);
                 });
             }
+            const inspectedEvidence = toolName === 'experience_read' ||
+                (toolName === 'code_act' &&
+                    Array.isArray(rawResult.hostToolExecutions) &&
+                    rawResult.hostToolExecutions.some((call) => call.name === 'experience_read'));
+            if ((0, procedure_runtime_js_1.deriveProcedureAccess)(activeCtx) && !inspectedEvidence) {
+                executionEvidence = (0, experience_evidence_js_1.captureExecutionEvidence)(effectiveInput, rawResult);
+            }
             const rawFailure = rawResult;
             if (rawFailure.success === false) {
                 // Captured BEFORE sanitizeGatewayFailureResult: the raw text only exists here, and
@@ -1366,7 +1416,12 @@ class GatewayToolExecutor {
             const auditError = shouldSanitizeAuditFailure
                 ? sanitizeGatewayError(error, Boolean(activeCtx.temporalWorkContext))
                 : error;
-            await this.appendToolTraceIfNeeded(traceState, activeCtx, toolName, undefined, Date.now() - startedAt, gatewayCallId, auditError).catch((appendError) => {
+            await this.appendToolTraceIfNeeded(traceState, activeCtx, toolName, undefined, Date.now() - startedAt, gatewayCallId, auditError, (0, procedure_runtime_js_1.deriveProcedureAccess)(activeCtx)
+                ? (0, experience_evidence_js_1.captureExecutionEvidence)(effectiveInput, {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                })
+                : undefined).catch((appendError) => {
                 securityLogger.warn('[model-run] failed to append failed tool trace before finalization', appendError);
             });
             await this.failDirectModelRunIfNeeded(traceState, toolName, auditError).catch((finalizationError) => {
@@ -1380,7 +1435,7 @@ class GatewayToolExecutor {
         }
         try {
             try {
-                await this.appendToolTraceIfNeeded(traceState, activeCtx, toolName, auditResult, Date.now() - startedAt, gatewayCallId);
+                experienceRef = await this.appendToolTraceIfNeeded(traceState, activeCtx, toolName, auditResult, Date.now() - startedAt, gatewayCallId, undefined, executionEvidence);
             }
             finally {
                 await this.completeDirectModelRunIfNeeded(traceState, toolName, auditResult);
@@ -1397,7 +1452,9 @@ class GatewayToolExecutor {
         if (scopeAudit.mismatch) {
             this.alarmScopeMismatch(activeCtx, toolName);
         }
-        return result;
+        return experienceRef && executionEvidence
+            ? { ...result, experience_ref: experienceRef }
+            : result;
     }
     /**
      * External lifecycle decisions are only valid while the host-created model run that owns the
@@ -1548,16 +1605,17 @@ class GatewayToolExecutor {
         }
         return api;
     }
-    async appendToolTraceIfNeeded(traceState, ctx, toolName, result, durationMs, gatewayCallId, error) {
+    async appendToolTraceIfNeeded(traceState, ctx, toolName, result, durationMs, gatewayCallId, error, evidence) {
         if (!traceState) {
             return;
         }
-        await traceState.api.appendToolTrace({
+        const access = (0, procedure_runtime_js_1.deriveProcedureAccess)(ctx);
+        const stored = await traceState.api.appendToolTrace({
             model_run_id: traceState.modelRunId,
             gateway_call_id: gatewayCallId,
             tool_name: toolName,
             input_summary: `tool:${toolName}`,
-            output_summary: this.summarizeToolTraceOutput(result, error),
+            output_summary: (0, experience_evidence_js_1.safeExperienceSummary)(this.summarizeToolTraceOutput(result, error)),
             execution_status: error || result?.success === false ? 'failed' : 'completed',
             duration_ms: durationMs,
             envelope_hash: ctx.envelope?.envelope_hash ?? null,
@@ -1565,7 +1623,27 @@ class GatewayToolExecutor {
             // preserves `code`); the trace was the one place that dropped it,
             // leaving only sha256 digests. Carried, never invented: no code = NULL.
             failure_code: this.extractFailureCode(result, error),
+            ...(access
+                ? {
+                    owner_scope: access.ownerScope,
+                    project_id: access.projectId,
+                    channel_id: access.channelId ?? null,
+                    catalog_revision: TOOL_CATALOG_REVISION,
+                    diagnostic_json: JSON.stringify({
+                        tool: toolName,
+                        status: error || result?.success === false ? 'failed' : 'completed',
+                        failureCode: this.extractFailureCode(result, error),
+                        evidenceCompleteness: evidence?.completeness ?? 'unavailable',
+                        sourceRefs: [
+                            ctx.sourceMessageRef,
+                            ctx.parentToolName ? `parent-tool:${ctx.parentToolName}` : undefined,
+                        ].filter(Boolean),
+                    }),
+                    ...(evidence ? { evidence_json: JSON.stringify(evidence) } : {}),
+                }
+                : {}),
         });
+        return stored?.trace_id;
     }
     extractFailureCode(result, error) {
         const candidate = error instanceof types_js_1.AgentError && typeof error.code === 'string'
@@ -2028,6 +2106,14 @@ class GatewayToolExecutor {
             }
         }
         try {
+            // A selected running revision remains fixed, but retirement/revocation wins before effects.
+            if (this.procedureRuntime &&
+                toolName !== 'code_act' &&
+                !toolName.startsWith('procedure_') &&
+                toolName !== 'console_brief_update' &&
+                (0, host_bridge_js_1.isCodeActMutatingTool)(toolName)) {
+                this.procedureRuntime.assertWritable(activeState);
+            }
             // Lazy MAMA API init — only for tools that need it
             const getApi = () => this.initializeMAMAApi();
             // Handle non-MAMA tools first
@@ -2375,16 +2461,6 @@ class GatewayToolExecutor {
                             error: `Refusing to save: content matches secret pattern(s): ${saveSecretScan.matches.join(', ')}. Secrets must never enter memory.`,
                         };
                     }
-                    if ((0, learning_context_js_1.isLearningTopic)(saveInput.topic)) {
-                        // Standing policy and lessons come from the OWNER through the turn observer.
-                        // An agent that could write policy: would grant itself instructions injected
-                        // into every later turn. Refuse at the choke, like secrets.
-                        return {
-                            success: false,
-                            code: 'learning_topic_refused',
-                            error: 'Topics starting with policy: or lesson: are written by the host from owner instructions, never by the agent.',
-                        };
-                    }
                     const api = await getApi();
                     await this.recordMemoryWriteWarnings(api, 'mama_save', saveSecretScan.warnings);
                     let trustedOptions;
@@ -2506,41 +2582,148 @@ class GatewayToolExecutor {
                         if (acceptedSlotIds.length === 0) {
                             throw new types_js_1.AgentError('Report publisher accepted no slots', 'TOOL_ERROR', undefined, false);
                         }
+                        // Observability, not enforcement: a board slot is a reversible
+                        // durable write, so HTML that misses the board class vocabulary is
+                        // published as supplied and reported back as a warning. Without
+                        // this the slot silently renders as unstyled plain text.
+                        const runLabel = activeState.modelRunId ?? 'unknown';
+                        const vocabularyWarnings = [];
+                        for (const slotId of acceptedSlotIds) {
+                            const html = slotsInput[slotId];
+                            if (typeof html !== 'string' || !html.trim())
+                                continue;
+                            if ((0, board_slot_instructions_js_1.htmlUsesBoardVocabulary)(html))
+                                continue;
+                            vocabularyWarnings.push(`slot ${slotId} uses none of the board structural classes (report-summary / report-card / report-section-title / report-table) and will render as plain text; republish using the report_publish contract (tool_describe report_publish)`);
+                            console.warn(`[board] slot ${slotId} published without the board vocabulary (run ${runLabel})`);
+                        }
                         return {
                             success: true,
                             acceptedSlotIds,
                             changedSlotIds,
                             message: `Dashboard report accepted: ${acceptedSlotIds.join(', ')} (${acceptedSlotIds.length} accepted, ${changedSlotIds.length} changed)`,
+                            ...(vocabularyWarnings.length > 0
+                                ? {
+                                    warnings: vocabularyWarnings,
+                                    // The shape and classes in hand once, not per slot, so the
+                                    // republish needs no second lookup.
+                                    contract: (0, board_slot_instructions_js_1.buildReportPublishToolContract)(),
+                                }
+                                : {}),
                         };
                     }
                     throw new types_js_1.AgentError('Report publisher not configured', 'TOOL_ERROR', undefined, false);
                 }
-                case 'console_brief_update': {
-                    const { appendConsoleBriefLesson } = await import('../operator/console-brief.js');
-                    // Append-only (live incident 2026-07-24): a full-replace contract had
-                    // the model overwrite the entire seeded manual with its one new
-                    // lesson. Accept `lesson`, with `content` as a lenient alias for
-                    // threads still anchored on the old schema.
-                    const rawInput = input;
-                    const lessonInput = rawInput.lesson ?? rawInput.content;
-                    if (typeof lessonInput !== 'string') {
-                        return { success: false, error: 'console_brief_update requires a string lesson' };
-                    }
-                    let briefAfter;
-                    try {
-                        briefAfter = appendConsoleBriefLesson(lessonInput);
+                case 'experience_read': {
+                    const access = (0, procedure_runtime_js_1.deriveProcedureAccess)(activeState);
+                    if (!access)
+                        throw new Error('Execution evidence authority required');
+                    const args = input;
+                    const allowed = new Set([
+                        'kind',
+                        'trace_id',
+                        'run_id',
+                        'tool_name',
+                        'cursor',
+                        'limit',
+                        'offset',
+                        'chars',
+                    ]);
+                    if (Object.keys(args).some((key) => !allowed.has(key)))
+                        throw new Error('Execution evidence scope is host-owned; unknown argument');
+                    for (const key of ['trace_id', 'run_id', 'tool_name', 'cursor']) {
+                        if (args[key] !== undefined &&
+                            (typeof args[key] !== 'string' || !String(args[key]).trim()))
+                            throw new Error(`Execution evidence ${key} invalid`);
+                    }
+                    if (args.kind !== undefined && args.kind !== 'skills' && args.kind !== 'executions')
+                        throw new Error('Execution evidence kind invalid');
+                    if (args.kind === 'skills') {
+                        if (access.ownerScope !== 'owner:runtime')
+                            throw new Error('Installed skill catalog owner scope required');
+                        if (['trace_id', 'run_id', 'tool_name', 'cursor', 'chars'].some((key) => args[key] !== undefined))
+                            throw new Error('Skill catalog accepts offset and limit only');
+                        const offset = args.offset ?? 0;
+                        const limit = args.limit ?? 20;
+                        if (typeof offset !== 'number' ||
+                            !Number.isSafeInteger(offset) ||
+                            offset < 0 ||
+                            typeof limit !== 'number' ||
+                            !Number.isSafeInteger(limit) ||
+                            limit < 1 ||
+                            limit > 100)
+                            throw new Error('Skill catalog offset/limit invalid');
+                        const skills = (0, skill_loader_js_1.filterSkillCatalogForContext)((0, skill_loader_js_1.loadInstalledSkills)(false, { includePaths: true }), activeState.agentContext);
+                        const end = Math.min(offset + limit, skills.length);
+                        return {
+                            success: true,
+                            skills: skills.slice(offset, end),
+                            total: skills.length,
+                            next_offset: end < skills.length ? end : null,
+                        };
                     }
-                    catch (err) {
-                        return { success: false, error: err instanceof Error ? err.message : String(err) };
+                    const api = await this.initializeMAMAApi();
+                    if (!api.listToolTraces || !api.readToolTrace)
+                        throw new Error('Execution evidence storage unavailable');
+                    const scope = (0, experience_evidence_js_1.traceReadScope)(access);
+                    if (typeof args.trace_id === 'string') {
+                        const trace = await api.readToolTrace(args.trace_id, scope);
+                        if (!trace)
+                            throw new Error('Execution evidence unavailable');
+                        const offset = args.offset ?? 0;
+                        const chars = args.chars ?? 4000;
+                        if (typeof offset !== 'number' ||
+                            !Number.isSafeInteger(offset) ||
+                            offset < 0 ||
+                            typeof chars !== 'number' ||
+                            !Number.isSafeInteger(chars) ||
+                            chars < 1 ||
+                            chars > 8000) {
+                            throw new Error('Execution evidence offset/chars invalid');
+                        }
+                        const text = Array.from(trace.evidence_json ?? '');
+                        if (offset > text.length)
+                            throw new Error('Execution evidence offset out of range');
+                        const end = Math.min(offset + chars, text.length);
+                        return {
+                            success: true,
+                            trace: { ...trace, evidence_json: null },
+                            content: text.slice(offset, end).join(''),
+                            offset,
+                            total_chars: text.length,
+                            next_offset: end < text.length ? end : null,
+                            behaviorVerified: false,
+                        };
                     }
-                    // Observability over restriction: the agent editing its own operating
-                    // brief is logged loudly, never silently absorbed. The next NEW/re-anchored
-                    // owner session picks it up via the policy fingerprint.
-                    console.log(`[console-brief] agent appended a lesson (brief now ${briefAfter.length} chars)`);
-                    return {
-                        success: true,
-                        message: 'Lesson appended to your operating brief; it applies from the next session re-anchor.',
-                    };
+                    const limit = args.limit;
+                    if (limit !== undefined &&
+                        (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < 1 || limit > 100)) {
+                        throw new Error('Execution evidence limit invalid');
+                    }
+                    const page = await api.listToolTraces({
+                        ...scope,
+                        ...(typeof args.run_id === 'string' ? { model_run_id: args.run_id } : {}),
+                        ...(typeof args.tool_name === 'string' ? { tool_name: args.tool_name } : {}),
+                        ...(typeof args.cursor === 'string' ? { cursor: args.cursor } : {}),
+                        ...(limit === undefined ? {} : { limit }),
+                    });
+                    return { success: true, ...page, behaviorVerified: false };
+                }
+                case 'procedure_list':
+                case 'procedure_read':
+                case 'procedure_update':
+                case 'procedure_retire':
+                case 'procedure_observe': {
+                    if (!this.procedureRuntime) {
+                        throw new Error('Procedure store not configured');
+                    }
+                    return this.procedureRuntime.execute(toolName, input, activeState);
+                }
+                case 'console_brief_update': {
+                    if (!this.procedureRuntime) {
+                        return { success: false, error: 'procedure store unavailable' };
+                    }
+                    return this.procedureRuntime.execute(toolName, input, activeState);
                 }
                 case 'member_candidates': {
                     const candidates = (0, member_candidate_store_js_1.getMemberCandidateStore)()