@elizaos/agent 2.0.0-alpha.156 → 2.0.0-alpha.161

package/packages/typescript/src/runtime.js

@@ -2,19 +2,23 @@ import { v4 as uuidv4 } from "uuid";
 import Handlebars from "handlebars";
 import { withCanonicalActionDocs, withCanonicalEvaluatorDocs, } from "./action-docs";
 import { parseActionParams, validateActionParams } from "./actions";
+import { createBasicCapabilitiesPlugin, } from "./features/basic-capabilities/index";
 import { ensureConnection as ensureConnectionStandalone } from "./connection";
 import { InMemoryDatabaseAdapter } from "./database/inMemoryAdapter";
-import { createBasicCapabilitiesPlugin, } from "./features/basic-capabilities/index";
 import { createLogger } from "./logger";
+import { simpleHash } from "./optimization/ab-analysis";
+import { getOptimizationRootDir } from "./optimization-root-dir";
 import { installRuntimePluginLifecycle } from "./plugin-lifecycle";
 import { getNativeRuntimeFeaturePlugin, nativeRuntimeFeatureDefaults, nativeRuntimeFeaturePluginNames, resolveNativeRuntimeFeatureFromPluginName, } from "./plugins/native-features";
 import { BM25 } from "./search";
 import { redactWithSecrets } from "./security/redact.js";
 import { DefaultMessageService } from "./services/message";
 import { decryptSecret, getSalt } from "./settings";
-import { getStreamingContext, runWithStreamingContext, } from "./streaming-context";
+import { getStreamingContext, runInsideModelStreamChunkDelivery, runWithStreamingContext, } from "./streaming-context";
 import { getTrajectoryContext, setTrajectoryPurpose, } from "./trajectory-context";
 import { ChannelType, EventType, getModelFallbackChain, ModelType, } from "./types";
+import { afterMemoryPersistedPipelineHookContext, modelStreamChunkPipelineHookContext, modelStreamEndPipelineHookContext, outgoingPipelineHookContext, PIPELINE_HOOK_DEBUG_LOG_MS, PIPELINE_HOOK_ERROR_LOG_MS, PIPELINE_HOOK_WARN_MS, pipelineHookMetricRoomId, postModelPipelineHookContext, preModelPipelineHookContext, resolvePipelineHookSpec, sortPipelineHooksByPosition, } from "./types/pipeline-hooks";
+import { ScoreCard } from "./types/prompt-optimization-score-card";
 import { parseJSONObjectFromText, parseKeyValueXml, stringToUuid, } from "./utils";
 import { parseBooleanValue } from "./utils/boolean";
 import { BufferUtils } from "./utils/buffer";
@@ -56,6 +60,12 @@ const TOON_HEADER_PATTERN = /^TOON(?:\s+DOCUMENT)?[:\s-]*$/i;
 const TOON_FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]*(?:\[[^\]\n]*\])?(?:\{[^\n]*\})?:/m;
 const XML_LIKE_PATTERN = /<[/!?A-Za-z_][^>\n]*>/;
 const JSON_OBJECT_KEY_PATTERN = /(?:["'][^"'\n]+["']|[A-Za-z_][A-Za-z0-9_-]*)\s*:/;
+function coerceOutgoingMessageText(text) {
+    if (text === null || text === undefined) {
+        return "";
+    }
+    return String(text);
+}
 function resolveDynamicPromptModelType(modelType, modelSize) {
     if (modelType) {
         return modelType;
@@ -106,6 +116,17 @@ export class AgentRuntime {
     taskWorkers = new Map();
     sendHandlers = new Map();
     eventHandlers = new Map();
+    /**
+     * In-flight execution traces keyed by trace.id (unique uuid).
+     * A single run can produce multiple DPE calls; each gets its own trace.
+     * `runToTraces` maps runId -> set of trace ids for enrichment lookup.
+     */
+    activeTraces = new Map();
+    runToTraces = new Map();
+    /** Optional DPE-side prompt optimization I/O (merge, registry, baseline/failure traces). */
+    promptOptimizationHooks = null;
+    pipelineHookEntries = [];
+    pipelineHookIdToIndex = new Map();
     // A map of all plugins available to the runtime, keyed by name, for dependency resolution.
     allAvailablePlugins = new Map();
     // The initial list of plugins specified by the character configuration.
@@ -352,6 +373,245 @@ export class AgentRuntime {
     isTrajectoriesEnabled() {
         return this.hasNativeRuntimeFeature("trajectories");
     }
+    hooksForPhase(phase) {
+        return this.pipelineHookEntries.filter((e) => e.phase === phase);
+    }
+    upsertPipelineHook(entry) {
+        const existing = this.pipelineHookIdToIndex.get(entry.id);
+        if (existing !== undefined) {
+            this.pipelineHookEntries[existing] = entry;
+            return;
+        }
+        this.pipelineHookIdToIndex.set(entry.id, this.pipelineHookEntries.length);
+        this.pipelineHookEntries.push(entry);
+    }
+    async invokePipelineHooks(phase, ctx, logLabel, pipelineHookTelemetry = true) {
+        const hooks = sortPipelineHooksByPosition(this.hooksForPhase(phase));
+        if (!hooks.length) {
+            return;
+        }
+        const runtime = this;
+        const roomId = pipelineHookMetricRoomId(ctx);
+        const runOne = async (entry) => {
+            const t0 = performance.now();
+            let errorMessage;
+            try {
+                await entry.handler(runtime, ctx);
+            }
+            catch (error) {
+                errorMessage = error instanceof Error ? error.message : String(error);
+                this.logger.error({
+                    src: "agent",
+                    agentId: this.agentId,
+                    hookId: entry.id,
+                    phase: entry.phase,
+                    error: errorMessage,
+                }, `${logLabel} threw; continuing`);
+            }
+            {
+                const durationMs = Math.round(performance.now() - t0);
+                if (!pipelineHookTelemetry) {
+                    const baseLite = {
+                        src: "pipeline_hook",
+                        agentId: this.agentId,
+                        hookId: entry.id,
+                        phase,
+                        roomId,
+                        durationMs,
+                    };
+                    if (durationMs >= PIPELINE_HOOK_WARN_MS) {
+                        this.logger.warn(baseLite, `PIPELINE HOOK SLOW (${durationMs}ms): ${entry.id} phase=${phase}`);
+                    }
+                    if (durationMs >= PIPELINE_HOOK_ERROR_LOG_MS) {
+                        this.logger.error(baseLite, `PIPELINE HOOK VERY SLOW (${durationMs}ms): ${entry.id} phase=${phase}`);
+                    }
+                }
+                else {
+                    const slow = durationMs >= PIPELINE_HOOK_WARN_MS;
+                    const baseFields = {
+                        src: "pipeline_hook",
+                        agentId: this.agentId,
+                        hookId: entry.id,
+                        phase,
+                        roomId,
+                        durationMs,
+                    };
+                    if (durationMs >= PIPELINE_HOOK_DEBUG_LOG_MS) {
+                        this.logger.debug(baseFields, "Pipeline hook timing");
+                    }
+                    if (slow) {
+                        this.logger.warn(baseFields, `PIPELINE HOOK SLOW (${durationMs}ms): ${entry.id} phase=${phase}`);
+                    }
+                    if (durationMs >= PIPELINE_HOOK_ERROR_LOG_MS) {
+                        this.logger.error(baseFields, `PIPELINE HOOK VERY SLOW (${durationMs}ms): ${entry.id} phase=${phase}`);
+                    }
+                    try {
+                        await this.emitEvent(EventType.PIPELINE_HOOK_METRIC, {
+                            phase,
+                            hookId: entry.id,
+                            durationMs,
+                            roomId,
+                            slow,
+                            ...(errorMessage !== undefined ? { error: errorMessage } : {}),
+                        });
+                    }
+                    catch (metricError) {
+                        this.logger.debug({
+                            src: "pipeline_hook",
+                            agentId: this.agentId,
+                            hookId: entry.id,
+                            phase,
+                            error: metricError instanceof Error
+                                ? metricError.message
+                                : String(metricError),
+                        }, "PIPELINE_HOOK_METRIC listener failed");
+                    }
+                }
+            }
+        };
+        if (phase === "parallel_with_should_respond" ||
+            phase === "model_stream_chunk") {
+            await Promise.all(hooks.map((h) => runOne(h)));
+            return;
+        }
+        const mutators = hooks.filter((h) => h.mutatesPrimary);
+        const serialReaders = hooks.filter((h) => !h.mutatesPrimary && h.schedule === "serial");
+        const concurrentReaders = hooks.filter((h) => !h.mutatesPrimary && h.schedule === "concurrent");
+        for (const h of mutators) {
+            await runOne(h);
+        }
+        for (const h of serialReaders) {
+            await runOne(h);
+        }
+        await Promise.all(concurrentReaders.map((h) => runOne(h)));
+    }
+    registerPipelineHook(spec) {
+        this.upsertPipelineHook(resolvePipelineHookSpec(spec));
+    }
+    unregisterPipelineHook(id) {
+        const idx = this.pipelineHookIdToIndex.get(id);
+        if (idx === undefined) {
+            return;
+        }
+        this.pipelineHookEntries.splice(idx, 1);
+        this.pipelineHookIdToIndex.clear();
+        for (let i = 0; i < this.pipelineHookEntries.length; i++) {
+            const e = this.pipelineHookEntries[i];
+            this.pipelineHookIdToIndex.set(e.id, i);
+        }
+    }
+    /**
+     * Run pipeline hooks for a phase (skip metadata, ordering, and outgoing redact).
+     * @param pipelineHookTelemetry When false, skips debug logs / `PIPELINE_HOOK_METRIC` per hook
+     * (still logs warn/error for slow hooks). Defaults to false for `model_stream_chunk` only.
+     */
+    async applyPipelineHooks(phase, ctx, pipelineHookTelemetry) {
+        if (ctx.phase !== phase) {
+            throw new Error(`applyPipelineHooks: phase mismatch (expected ${phase}, ctx.phase=${ctx.phase})`);
+        }
+        const hookTelemetry = pipelineHookTelemetry !== undefined
+            ? pipelineHookTelemetry
+            : phase !== "model_stream_chunk";
+        const hasHooks = this.hooksForPhase(phase).length > 0;
+        switch (phase) {
+            case "incoming_before_compose": {
+                if (!hasHooks) {
+                    return;
+                }
+                const c = ctx;
+                const md = c.message.content?.metadata;
+                const meta = typeof md === "object" && md !== null
+                    ? md
+                    : null;
+                if (meta?.skipIncomingMessageHooks === true) {
+                    return;
+                }
+                const messageId = c.message.id;
+                await this.invokePipelineHooks(phase, c, "Incoming pipeline hook", hookTelemetry);
+                if (messageId) {
+                    this.stateCache.delete(messageId);
+                    this.stateCache.delete(`${messageId}_action_results`);
+                }
+                return;
+            }
+            case "pre_should_respond": {
+                if (!hasHooks) {
+                    return;
+                }
+                const c = ctx;
+                const md = c.message.content?.metadata;
+                const meta = typeof md === "object" && md !== null
+                    ? md
+                    : null;
+                if (meta?.skipPreShouldRespondHooks === true) {
+                    return;
+                }
+                await this.invokePipelineHooks(phase, c, "Pre-should-respond pipeline hook", hookTelemetry);
+                return;
+            }
+            case "parallel_with_should_respond": {
+                if (!hasHooks) {
+                    return;
+                }
+                const c = ctx;
+                const md = c.message.content?.metadata;
+                const meta = typeof md === "object" && md !== null
+                    ? md
+                    : null;
+                if (meta?.skipParallelWithShouldRespondHooks === true) {
+                    return;
+                }
+                await this.invokePipelineHooks(phase, c, "Parallel should-respond pipeline hook", hookTelemetry);
+                return;
+            }
+            case "outgoing_before_deliver": {
+                const c = ctx;
+                if (hasHooks) {
+                    await this.invokePipelineHooks(phase, c, "Outgoing pipeline hook", hookTelemetry);
+                }
+                c.content.text = this.redactSecrets(coerceOutgoingMessageText(c.content.text));
+                return;
+            }
+            case "pre_model":
+            case "post_model": {
+                if (!hasHooks) {
+                    return;
+                }
+                await this.invokePipelineHooks(phase, ctx, phase === "pre_model"
+                    ? "Pre-model pipeline hook"
+                    : "Post-model pipeline hook", hookTelemetry);
+                return;
+            }
+            case "after_memory_persisted": {
+                if (!hasHooks) {
+                    return;
+                }
+                const c = ctx;
+                const md = c.memory.content?.metadata;
+                const meta = typeof md === "object" && md !== null
+                    ? md
+                    : null;
+                if (meta?.skipAfterMemoryPersistedHooks === true) {
+                    return;
+                }
+                await this.invokePipelineHooks(phase, c, "After-memory-persisted pipeline hook", hookTelemetry);
+                return;
+            }
+            case "model_stream_chunk":
+            case "model_stream_end": {
+                if (!hasHooks) {
+                    return;
+                }
+                await this.invokePipelineHooks(phase, ctx, phase === "model_stream_chunk"
+                    ? "Model stream chunk pipeline hook"
+                    : "Model stream end pipeline hook", hookTelemetry);
+                return;
+            }
+            default: {
+                throw new Error(`Unknown pipeline hook phase: ${String(phase)}`);
+            }
+        }
+    }
     async registerPlugin(plugin) {
         if (!plugin.name) {
             // Ensure plugin.name is defined
@@ -465,14 +725,13 @@ export class AgentRuntime {
         }
         if (pluginToRegister.routes) {
             for (const route of pluginToRegister.routes) {
+                // namespace plugin name infront of paths
                 const routePath = route.path.startsWith("/")
                     ? route.path
                     : `/${route.path}`;
                 this.routes.push({
                     ...route,
-                    path: route.rawPath
-                        ? routePath
-                        : `/${pluginToRegister.name}${routePath}`,
+                    path: `/${pluginToRegister.name}${routePath}`,
                 });
             }
         }
@@ -1005,6 +1264,125 @@ export class AgentRuntime {
         // Default to true (check should respond is enabled)
         return true;
     }
+    getOptimizationDir() {
+        const setting = this.getSetting("OPTIMIZATION_DIR");
+        return getOptimizationRootDir(typeof setting === "string" ? setting : null);
+    }
+    registerPromptOptimizationHooks(hooks) {
+        this.promptOptimizationHooks = hooks;
+    }
+    getPromptOptimizationHooks() {
+        return this.promptOptimizationHooks;
+    }
+    resolveProviderModelString(resolvedModelType, optionsModel, effectiveModelId) {
+        if (effectiveModelId)
+            return effectiveModelId;
+        if (optionsModel)
+            return optionsModel;
+        const slotToSetting = {
+            TEXT_NANO: "NANO_MODEL",
+            TEXT_MINI: "MINI_MODEL",
+            TEXT_SMALL: "SMALL_MODEL",
+            TEXT_LARGE: "LARGE_MODEL",
+            TEXT_MEGA: "MEGA_MODEL",
+            RESPONSE_HANDLER: "RESPONSE_HANDLER_MODEL",
+            ACTION_PLANNER: "ACTION_PLANNER_MODEL",
+            REASONING_SMALL: "REASONING_SMALL_MODEL",
+            REASONING_LARGE: "REASONING_LARGE_MODEL",
+            TEXT_COMPLETION: "COMPLETION_MODEL",
+        };
+        const providerPrefixes = ["OLLAMA_", "OPENAI_", "ANTHROPIC_", ""];
+        for (const candidate of getModelFallbackChain(resolvedModelType)) {
+            const settingKey = slotToSetting[candidate];
+            if (!settingKey)
+                continue;
+            for (const prefix of providerPrefixes) {
+                const val = this.getSetting(`${prefix}${settingKey}`);
+                if (typeof val === "string" && val)
+                    return val;
+            }
+        }
+        return resolvedModelType;
+    }
+    enrichTrace(runId, signal) {
+        const traceIds = this.runToTraces.get(runId);
+        if (!traceIds)
+            return;
+        const targetTraceId = signal.traceId;
+        for (const tid of traceIds) {
+            if (targetTraceId && tid !== targetTraceId)
+                continue;
+            const trace = this.activeTraces.get(tid);
+            if (!trace)
+                continue;
+            trace.scoreCard.signals.push(signal);
+            const card = ScoreCard.fromJSON(trace.scoreCard);
+            trace.scoreCard.compositeScore = card.composite();
+            trace.enrichedAt = Date.now();
+        }
+    }
+    getActiveTrace(runId) {
+        const traceIds = this.runToTraces.get(runId);
+        if (!traceIds)
+            return undefined;
+        let latest;
+        for (const tid of traceIds) {
+            const t = this.activeTraces.get(tid);
+            if (t)
+                latest = t;
+        }
+        return latest;
+    }
+    getActiveTracesForRun(runId) {
+        const traceIds = this.runToTraces.get(runId);
+        if (!traceIds)
+            return [];
+        const traces = [];
+        for (const tid of traceIds) {
+            const t = this.activeTraces.get(tid);
+            if (t)
+                traces.push(t);
+        }
+        return traces;
+    }
+    deleteActiveTrace(runId) {
+        const traceIds = this.runToTraces.get(runId);
+        if (traceIds) {
+            for (const tid of traceIds) {
+                this.activeTraces.delete(tid);
+            }
+            this.runToTraces.delete(runId);
+        }
+    }
+    deleteActiveTraceById(traceId) {
+        this.activeTraces.delete(traceId);
+        for (const [rid, tids] of this.runToTraces) {
+            if (tids.delete(traceId) && tids.size === 0) {
+                this.runToTraces.delete(rid);
+            }
+        }
+    }
+    static ACTIVE_TRACE_TTL_MS = 5 * 60 * 1000;
+    activeTraceTtlPurgeCounter = 0;
+    purgeStaleActiveTraces() {
+        const now = Date.now();
+        const ttl = AgentRuntime.ACTIVE_TRACE_TTL_MS;
+        for (const [id, t] of this.activeTraces) {
+            if (now - t.createdAt <= ttl)
+                continue;
+            this.activeTraces.delete(id);
+            for (const [rid, tids] of this.runToTraces) {
+                tids.delete(id);
+                if (tids.size === 0)
+                    this.runToTraces.delete(rid);
+            }
+        }
+    }
+    maybeRunActiveTraceTTLPurge() {
+        if (++this.activeTraceTtlPurgeCounter % 100 !== 0)
+            return;
+        this.purgeStaleActiveTraces();
+    }
     /**
      * Get the messaging adapter if available
      *
@@ -1415,10 +1793,34 @@ export class AgentRuntime {
                             const textToStream = currentFilter.push(chunk);
                             if (textToStream && onStreamChunk) {
                                 filteredAccumulated += textToStream;
+                                await this.applyPipelineHooks("model_stream_chunk", modelStreamChunkPipelineHookContext({
+                                    source: "process_actions",
+                                    chunk: textToStream,
+                                    messageId: msgId,
+                                    roomId: message.roomId,
+                                    runId,
+                                    responseId: responseMessageId,
+                                    accumulated: filteredAccumulated,
+                                }));
                                 await onStreamChunk(textToStream, msgId, filteredAccumulated);
                             }
                         },
                         onStreamEnd: () => {
+                            const textSnapshot = filteredAccumulated;
+                            void this.applyPipelineHooks("model_stream_end", modelStreamEndPipelineHookContext({
+                                source: "process_actions",
+                                roomId: message.roomId,
+                                runId,
+                                responseId: responseMessageId,
+                                messageId: responseMessageId,
+                                text: textSnapshot,
+                            })).catch((err) => {
+                                this.logger.debug({
+                                    src: "agent",
+                                    agentId: this.agentId,
+                                    error: err instanceof Error ? err.message : String(err),
+                                }, "model_stream_end pipeline hook failed");
+                            });
                             // Reset filter and local accumulator for next useModel call
                             currentFilter = null;
                             filteredAccumulated = "";
@@ -1558,10 +1960,13 @@ export class AgentRuntime {
                 }
                 if (callback) {
                     for (const content of storedCallbackData) {
-                        // Redact any secrets from callback content before sending
-                        if (content.text) {
-                            content.text = this.redactSecrets(content.text);
-                        }
+                        await this.applyPipelineHooks("outgoing_before_deliver", outgoingPipelineHookContext(content, {
+                            source: "action",
+                            roomId: message.roomId,
+                            message,
+                            actionName: action.name,
+                            responseId: content.responseId,
+                        }));
                         await callback(content);
                     }
                 }
@@ -2018,6 +2423,8 @@ export class AgentRuntime {
         }));
         if (trajectoryStepId && trajLogger) {
             const userText = typeof message.content?.text === "string" ? message.content.text : "";
+            const trajCtx = getTrajectoryContext();
+            const providerTraceId = this.getActiveTrace(this.getCurrentRunId())?.id;
             for (const r of providerData) {
                 try {
                     const textLen = typeof r.text === "string" ? r.text.length : 0;
@@ -2027,6 +2434,10 @@ export class AgentRuntime {
                         data: { textLength: textLen },
                         purpose: "compose_state",
                         query: { message: userText.slice(0, 2000) },
+                        runId: trajCtx?.runId,
+                        roomId: trajCtx?.roomId,
+                        messageId: trajCtx?.messageId,
+                        executionTraceId: providerTraceId,
                     });
                 }
                 catch {
@@ -2696,11 +3107,20 @@ export class AgentRuntime {
             paramsAsStreaming.stream = shouldStream;
             delete paramsAsStreaming.onStreamChunk;
         }
-        const response = await handler(this, modelParams);
+        await this.invokePipelineHooks("pre_model", preModelPipelineHookContext({
+            requestedModelType: String(modelType),
+            resolvedModelKey,
+            provider: resolvedModel?.provider ?? provider,
+            roomId: getTrajectoryContext()?.roomId,
+            params: modelParams,
+        }), "Pre-model pipeline hook");
+        const rawResponse = await handler(this, modelParams);
+        const resultRef = { current: rawResponse };
+        const modelOutToTrajectoryString = (v) => typeof v === "string" ? v : JSON.stringify(v);
         // Stream: broadcast to callbacks if streaming
         if (shouldStream &&
             (paramsChunk || ctxChunk) &&
-            isTextStreamResult(response)) {
+            isTextStreamResult(rawResponse)) {
             // WHY undefined for accumulated: raw LLM tokens have no field-level
             // extraction — accumulated text is only meaningful after an XML
             // extractor (ValidationStreamExtractor) has parsed and isolated a
@@ -2708,25 +3128,61 @@ export class AgentRuntime {
             // accumulated data get it from the extractor's onChunk bridge in
             // dynamicPromptExecFromState, not from the raw token loop.
             let fullText = "";
-            for await (const chunk of response.textStream) {
+            for await (const chunk of rawResponse.textStream) {
                 if (abortSignal?.aborted)
                     break;
                 fullText += chunk;
-                if (paramsChunk)
-                    await paramsChunk(chunk, msgId, undefined);
-                if (ctxChunk)
-                    await ctxChunk(chunk, msgId, undefined);
+                const trajStream = getTrajectoryContext();
+                await this.invokePipelineHooks("model_stream_chunk", modelStreamChunkPipelineHookContext({
+                    source: "use_model",
+                    chunk,
+                    messageId: msgId,
+                    roomId: trajStream?.roomId ??
+                        this.currentRoomId ??
+                        this.agentId,
+                    runId: this.getCurrentRunId(),
+                    ...(trajStream?.messageId
+                        ? { responseId: trajStream.messageId }
+                        : {}),
+                    accumulated: fullText,
+                }), "Model stream chunk (useModel)", false);
+                await runInsideModelStreamChunkDelivery(async () => {
+                    if (paramsChunk)
+                        await paramsChunk(chunk, msgId, undefined);
+                    if (ctxChunk)
+                        await ctxChunk(chunk, msgId, undefined);
+                });
             }
+            const trajStreamEnd = getTrajectoryContext();
+            await this.invokePipelineHooks("model_stream_end", modelStreamEndPipelineHookContext({
+                source: "use_model",
+                roomId: trajStreamEnd?.roomId ??
+                    this.currentRoomId ??
+                    this.agentId,
+                runId: this.getCurrentRunId(),
+                messageId: msgId ?? trajStreamEnd?.messageId,
+                text: fullText,
+            }), "Model stream end (useModel)", true);
             // Signal stream end to allow context to reset state between useModel calls
             const streamingCtxEnd = getStreamingContext();
             const ctxEnd = streamingCtxEnd?.onStreamEnd;
             if (ctxEnd)
                 ctxEnd();
-            // Log the completed stream
+            resultRef.current = fullText;
             const elapsedTime = (typeof performance !== "undefined" &&
                 typeof performance.now === "function"
                 ? performance.now()
                 : Date.now()) - startTime;
+            await this.invokePipelineHooks("post_model", postModelPipelineHookContext({
+                requestedModelType: String(modelType),
+                resolvedModelKey,
+                provider: resolvedModel?.provider ?? provider,
+                roomId: getTrajectoryContext()?.roomId,
+                durationMs: Math.round(elapsedTime),
+                params: modelParams,
+                result: resultRef,
+                streaming: true,
+            }), "Post-model pipeline hook");
             this.logger.trace({
                 src: "agent",
                 agentId: this.agentId,
@@ -2734,7 +3190,7 @@ export class AgentRuntime {
                 duration: Number(elapsedTime.toFixed(2)),
                 streaming: true,
             }, "Model output (stream with callback complete)");
-            this.logModelCall(String(modelType), resolvedModelKey, params, promptContent, elapsedTime, resolvedModel?.provider ?? provider, fullText);
+            this.logModelCall(String(modelType), resolvedModelKey, params, promptContent, elapsedTime, resolvedModel?.provider ?? provider, resultRef.current);
             // Optional trajectory logging: associate model calls with current trajectory step
             // Skip during initialization to avoid deadlock (_ensureServiceStarted awaits initPromise)
             if (!this.initResolver) {
@@ -2749,6 +3205,7 @@ export class AgentRuntime {
                         const maxTokensRaw = isPlainObject(modelParams)
                             ? modelParams.maxTokens
                             : undefined;
+                        const activeTrace = this.getActiveTrace(this.getCurrentRunId());
                         trajLogger.logLlmCall({
                             stepId,
                             model: String(resolvedModelKey),
@@ -2756,12 +3213,17 @@ export class AgentRuntime {
                                 ? this.character.system
                                 : "",
                             userPrompt: promptContent ?? "",
-                            response: fullText,
+                            response: modelOutToTrajectoryString(resultRef.current),
                             temperature: typeof tempRaw === "number" ? tempRaw : 0,
                             maxTokens: typeof maxTokensRaw === "number" ? maxTokensRaw : 0,
                             purpose: trajCtx?.purpose ?? "action",
                             actionType: "runtime.useModel",
                             latencyMs: Math.max(0, Math.round(elapsedTime)),
+                            modelSlot: String(modelType),
+                            runId: trajCtx?.runId,
+                            roomId: trajCtx?.roomId,
+                            messageId: trajCtx?.messageId,
+                            executionTraceId: activeTrace?.id,
                         });
                     }
                 }
@@ -2769,20 +3231,29 @@ export class AgentRuntime {
                     // Trajectory logging must never break core model flow.
                 }
             }
-            return fullText;
+            return resultRef.current;
         }
         const elapsedTime = (typeof performance !== "undefined" &&
             typeof performance.now === "function"
             ? performance.now()
             : Date.now()) - startTime;
-        // Log timing / response (keep debug log if useful)
+        await this.invokePipelineHooks("post_model", postModelPipelineHookContext({
+            requestedModelType: String(modelType),
+            resolvedModelKey,
+            provider: resolvedModel?.provider ?? provider,
+            roomId: getTrajectoryContext()?.roomId,
+            durationMs: Math.round(elapsedTime),
+            params: modelParams,
+            result: resultRef,
+            streaming: false,
+        }), "Post-model pipeline hook");
         this.logger.trace({
             src: "agent",
             agentId: this.agentId,
             model: resolvedModelKey,
             duration: Number(elapsedTime.toFixed(2)),
         }, "Model output");
-        this.logModelCall(String(modelType), resolvedModelKey, params, promptContent, elapsedTime, resolvedModel?.provider ?? provider, response);
+        this.logModelCall(String(modelType), resolvedModelKey, params, promptContent, elapsedTime, resolvedModel?.provider ?? provider, resultRef.current);
         // Optional trajectory logging: associate model calls with current trajectory step
         // Skip during initialization to avoid deadlock (_ensureServiceStarted awaits initPromise)
         if (!this.initResolver) {
@@ -2797,6 +3268,7 @@ export class AgentRuntime {
                     const maxTokensRaw = isPlainObject(modelParams)
                         ? modelParams.maxTokens
                         : undefined;
+                    const activeTrace = this.getActiveTrace(this.getCurrentRunId());
                     trajLogger.logLlmCall({
                         stepId,
                         model: String(resolvedModelKey),
@@ -2804,14 +3276,17 @@ export class AgentRuntime {
                             ? this.character.system
                             : "",
                         userPrompt: promptContent ?? "",
-                        response: typeof response === "string"
-                            ? response
-                            : JSON.stringify(response),
+                        response: modelOutToTrajectoryString(resultRef.current),
                         temperature: typeof tempRaw === "number" ? tempRaw : 0,
                         maxTokens: typeof maxTokensRaw === "number" ? maxTokensRaw : 0,
                         purpose: trajCtx2?.purpose ?? "action",
                         actionType: "runtime.useModel",
                         latencyMs: Math.max(0, Math.round(elapsedTime)),
+                        modelSlot: String(modelType),
+                        runId: trajCtx2?.runId,
+                        roomId: trajCtx2?.roomId,
+                        messageId: trajCtx2?.messageId,
+                        executionTraceId: activeTrace?.id,
                     });
                 }
             }
@@ -2819,7 +3294,7 @@ export class AgentRuntime {
                 // Trajectory logging must never break core model flow.
             }
         }
-        return response;
+        return resultRef.current;
     }
     /**
      * Simplified text generation with optional character context.
@@ -2982,7 +3457,8 @@ export class AgentRuntime {
      * 2. Streaming with safety: Enables streaming while detecting truncation
      * 3. Performance tracking: Tracks success/failure rates per model+schema
      */
-    async dynamicPromptExecFromState({ state, params, schema, options = {}, }) {
+    async dynamicPromptExecFromState({ state: stateArg, params, schema, options = {}, }) {
+        const state = stateArg ?? { values: {}, data: {}, text: "" };
         // Validate schema input
         if (!schema || schema.length === 0) {
             this.logger.error("dynamicPromptExecFromState: schema must have at least one entry");
@@ -3050,9 +3526,44 @@ export class AgentRuntime {
         let extractor;
         let contextLevel = defaultContextCheckLevel;
         const perFieldCodes = new Map();
+        let traceModelId;
+        let tracePromptKey;
+        let traceVariant = "baseline";
+        let traceArtifactVersion;
+        const traceStartTime = Date.now();
+        const optimizationHooks = this.getPromptOptimizationHooks();
+        if (optimizationHooks) {
+            traceModelId = this.resolveProviderModelString(resolvedModelType, options.model);
+            const schemaHash = this.buildSchemaMetricKey(schema)
+                .split("")
+                .reduce((h, c) => ((h * 31) ^ c.charCodeAt(0)) >>> 0, 5381)
+                .toString(16)
+                .slice(0, 8);
+            tracePromptKey = options.promptName ?? schemaHash;
+        }
         while (currentRetry <= maxRetries) {
             const template = params.prompt;
             const templateStr = typeof template === "function" ? template({ state }) : template;
+            let finalTemplateStr = templateStr;
+            if (optimizationHooks &&
+                traceModelId &&
+                tracePromptKey &&
+                currentRetry === 0) {
+                try {
+                    const merged = await optimizationHooks.mergePromptTemplate(this, {
+                        baselineTemplate: templateStr,
+                        modelId: traceModelId,
+                        modelSlot: resolvedModelType,
+                        promptKey: tracePromptKey,
+                    });
+                    finalTemplateStr = merged.template;
+                    traceVariant = merged.variant;
+                    traceArtifactVersion = merged.artifactVersion;
+                }
+                catch (optErr) {
+                    this.logger.warn({ error: optErr }, "Optimization artifact lookup failed");
+                }
+            }
             // Get keys from state (excluding text, values, data)
             const stateKeys = Object.keys(state);
             const filteredKeys = stateKeys.filter((key) => !["text", "values", "data"].includes(key));
@@ -3061,7 +3572,7 @@ export class AgentRuntime {
                 return acc;
             }, {});
             const templateContext = { ...filteredState, ...state.values };
-            const outputSegments = this.renderPromptTemplateSegments(templateStr, templateContext, state);
+            const outputSegments = this.renderPromptTemplateSegments(finalTemplateStr, templateContext, state);
             const output = outputSegments.map((segment) => segment.content).join("");
             // Process format options
             const hasNestedSchema = this.schemaHasNestedStructure(schema);
@@ -3386,6 +3897,10 @@ ${section_end}`;
             responseContent = this.normalizeStructuredResponse(responseContent);
             // Validate response
             let allGood = true;
+            let schemaValidation = {
+                missingPaths: [],
+                invalidPaths: [],
+            };
             if (!responseContent) {
                 validationIssues.push("No structured output could be parsed from the model response.");
                 this.logger.warn(`dynamicPromptExecFromState parse problem: ${cleanResponse}`);
@@ -3445,7 +3960,7 @@ ${section_end}`;
                         delete responseContent.two_end_code;
                     }
                 }
-                const schemaValidation = this.validateResponseAgainstSchema(responseContent, schema);
+                schemaValidation = this.validateResponseAgainstSchema(responseContent, schema);
                 if (schemaValidation.missingPaths.length > 0 ||
                     schemaValidation.invalidPaths.length > 0) {
                     if (schemaValidation.missingPaths.length > 0) {
@@ -3497,6 +4012,94 @@ ${section_end}`;
                 this.logger.debug(`dynamicPromptExecFromState success [${modelSchemaKey}]: ${outputTokenEst} tokens`);
                 // Clean up smart retry context from state
                 delete state._smartRetryContext;
+                if (optimizationHooks && traceModelId && tracePromptKey) {
+                    try {
+                        const scoreCard = new ScoreCard();
+                        scoreCard.add({
+                            source: "dpe",
+                            kind: "parseSuccess",
+                            value: 1.0,
+                            reason: "Structured output parsed successfully",
+                        });
+                        const schemaOk = schemaValidation.missingPaths.length === 0 &&
+                            schemaValidation.invalidPaths.length === 0;
+                        scoreCard.add({
+                            source: "dpe",
+                            kind: "schemaValid",
+                            value: schemaOk ? 1.0 : 0.0,
+                            reason: schemaOk
+                                ? "Response matched schema paths"
+                                : `Schema issues: missing [${schemaValidation.missingPaths.join(", ")}]; invalid [${schemaValidation.invalidPaths.join(", ")}]`,
+                        });
+                        scoreCard.add({
+                            source: "dpe",
+                            kind: "retriesUsed",
+                            value: Math.max(0, 1.0 - currentRetry / Math.max(maxRetries, 1)),
+                            reason: `Succeeded on attempt ${currentRetry + 1} of ${maxRetries + 1}`,
+                        });
+                        scoreCard.add({
+                            source: "dpe",
+                            kind: "tokenEfficiency",
+                            value: Math.min(1.0, 500 / Math.max(outputTokenEst, 1)),
+                            reason: `Estimated output tokens ${outputTokenEst} vs reference 500`,
+                        });
+                        const templateHashInput = typeof params.prompt === "string"
+                            ? params.prompt
+                            : tracePromptKey;
+                        const computedTemplateHash = simpleHash(templateHashInput);
+                        const trace = {
+                            id: uuidv4(),
+                            traceVersion: 1,
+                            type: "trace",
+                            promptKey: tracePromptKey,
+                            modelSlot: resolvedModelType,
+                            modelId: traceModelId,
+                            runId: this.getCurrentRunId?.() ?? undefined,
+                            templateHash: computedTemplateHash,
+                            schemaFingerprint: schemaKey,
+                            artifactVersion: traceArtifactVersion,
+                            variant: traceVariant,
+                            parseSuccess: true,
+                            schemaValid: schemaValidation.missingPaths.length === 0 &&
+                                schemaValidation.invalidPaths.length === 0,
+                            validationCodesMatched: true,
+                            retriesUsed: currentRetry,
+                            tokenEstimate: outputTokenEst,
+                            latencyMs: Date.now() - traceStartTime,
+                            response: responseContent,
+                            scoreCard: scoreCard.toJSON(),
+                            createdAt: Date.now(),
+                        };
+                        this.maybeRunActiveTraceTTLPurge();
+                        const runId = trace.runId;
+                        if (runId) {
+                            this.activeTraces.set(trace.id, trace);
+                            if (!this.runToTraces.has(runId)) {
+                                this.runToTraces.set(runId, new Set());
+                            }
+                            this.runToTraces.get(runId)?.add(trace.id);
+                        }
+                        void optimizationHooks
+                            .persistRegistryEntry(this, {
+                            promptKey: tracePromptKey,
+                            schemaFingerprint: schemaKey,
+                            templateHash: computedTemplateHash,
+                            promptTemplate: typeof params.prompt === "string" ? params.prompt : "",
+                            schema: JSON.parse(JSON.stringify(schema)),
+                        })
+                            .catch((err) => {
+                            this.logger.warn({ error: err, src: "dpe" }, "Failed to write prompt optimization registry");
+                        });
+                        void optimizationHooks
+                            .appendBaselineTrace(this, { trace })
+                            .catch((err) => {
+                            this.logger.warn("Failed to write optimization trace", err);
+                        });
+                    }
+                    catch (traceErr) {
+                        this.logger.warn({ error: traceErr }, "Failed to build optimization trace");
+                    }
+                }
                 this.clearStructuredOutputFailureState(state);
                 return responseContent;
             }
@@ -3602,6 +4205,71 @@ ${section_end}`;
         else {
             this.logger.error(finalFailureMessage, finalFailureSummary);
         }
+        if (optimizationHooks && traceModelId && tracePromptKey) {
+            try {
+                this.purgeStaleActiveTraces();
+                const scoreCard = new ScoreCard();
+                scoreCard.add({
+                    source: "dpe",
+                    kind: "parseSuccess",
+                    value: 0.0,
+                    reason: `No valid parse after ${maxRetries} retries`,
+                });
+                scoreCard.add({
+                    source: "dpe",
+                    kind: "schemaValid",
+                    value: 0.0,
+                    reason: "Parse or validation never succeeded",
+                });
+                scoreCard.add({
+                    source: "dpe",
+                    kind: "retriesUsed",
+                    value: 0.0,
+                    reason: "All retry attempts exhausted",
+                });
+                const failTemplateHash = simpleHash(typeof params.prompt === "string" ? params.prompt : tracePromptKey);
+                const trace = {
+                    id: uuidv4(),
+                    traceVersion: 1,
+                    type: "trace",
+                    promptKey: tracePromptKey,
+                    modelSlot: resolvedModelType,
+                    modelId: traceModelId,
+                    runId: this.getCurrentRunId?.() ?? undefined,
+                    templateHash: failTemplateHash,
+                    schemaFingerprint: schemaKey,
+                    artifactVersion: traceArtifactVersion,
+                    variant: traceVariant,
+                    parseSuccess: false,
+                    schemaValid: false,
+                    validationCodesMatched: false,
+                    retriesUsed: maxRetries,
+                    tokenEstimate: 0,
+                    latencyMs: Date.now() - traceStartTime,
+                    scoreCard: scoreCard.toJSON(),
+                    createdAt: Date.now(),
+                };
+                void optimizationHooks
+                    .persistRegistryEntry(this, {
+                    promptKey: tracePromptKey,
+                    schemaFingerprint: schemaKey,
+                    templateHash: failTemplateHash,
+                    promptTemplate: typeof params.prompt === "string" ? params.prompt : "",
+                    schema: JSON.parse(JSON.stringify(schema)),
+                })
+                    .catch((err) => {
+                    this.logger.warn({ error: err, src: "dpe" }, "Failed to write prompt optimization registry");
+                });
+                void optimizationHooks
+                    .appendFailureTrace(this, { trace })
+                    .catch((err) => {
+                    this.logger.warn("Failed to write failure trace", err);
+                });
+            }
+            catch (traceErr) {
+                this.logger.warn({ error: traceErr }, "Failed to build failure trace");
+            }
+        }
         // Clean up smart retry context from state
         delete state._smartRetryContext;
         if (lastStructuredFailure) {
@@ -5099,7 +5767,9 @@ ${section_end}`;
         const ids = await this.adapter.createMemories([
             { memory, tableName, unique },
         ]);
-        return ids[0];
+        const memoryId = ids[0];
+        await this.applyPipelineHooks("after_memory_persisted", afterMemoryPersistedPipelineHookContext(memory, tableName, memoryId));
+        return memoryId;
     }
     async updateMemory(memory) {
         await this.adapter.updateMemories([memory]);