@salesforce/sfdx-agent-harness-mastra 0.1.0

package/dist/mastra-harness.js

@@ -0,0 +1,838 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import path from 'node:path';
+import { Agent } from '@mastra/core/agent';
+import { Mastra } from '@mastra/core/mastra';
+import { Memory } from '@mastra/memory';
+import { LibSQLStore } from '@mastra/libsql';
+import { MCPClient } from '@mastra/mcp';
+import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, HarnessBusOwner, McpServerStatus, } from '@salesforce/sfdx-agent-sdk';
+import { MastraEventAdapter } from './mastra-event-adapter.js';
+import { mapMastraToMessage, mapMessageToMastra, partToTranscriptText } from './mastra-message-mapper.js';
+import { mapToolDefinitionsToMastraTools } from './mastra-tool-mapper.js';
+import { hasEnabledServers, mapToMastraMCPServers } from './mcp-config-mapper.js';
+import { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
+import { Clock, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { makeAbortable } from './utils.js';
+import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, } from '@mastra/core/workspace';
+/**
+ * The literal prefix Mastra prepends to every workspace tool name (e.g.
+ * `mastra_workspace_read_file`). Stripping this prefix yields the
+ * provider-neutral name we expose to consumers.
+ */
+const MASTRA_PREFIX = `${WORKSPACE_TOOLS_PREFIX}_`;
+/**
+ * Every Mastra workspace tool, flattened from `WORKSPACE_TOOLS`. Used to
+ * auto-generate the `Workspace({ tools })` config so every built-in is
+ * registered under its prefix-stripped name without per-tool maintenance.
+ */
+const ALL_MASTRA_WORKSPACE_TOOL_NAMES = [
+    ...Object.values(WORKSPACE_TOOLS.FILESYSTEM),
+    ...Object.values(WORKSPACE_TOOLS.SANDBOX),
+    ...Object.values(WORKSPACE_TOOLS.SEARCH),
+    ...Object.values(WORKSPACE_TOOLS.LSP),
+];
+/**
+ * Strip Mastra's `mastra_workspace_` prefix from a tool name, returning the
+ * sanitized public name. Non-prefixed names (custom tools, MCP tools) pass
+ * through unchanged.
+ */
+function stripMastraWorkspacePrefix(name) {
+    return name.startsWith(MASTRA_PREFIX) ? name.slice(MASTRA_PREFIX.length) : name;
+}
+/**
+ * Predicate used by the MCP discovery `.then` / `.catch` chains to distinguish a benign
+ * post-shutdown `DISPOSED` error (which we swallow because the bus owner was torn down before
+ * the background promise resolved) from any other error that should propagate.
+ */
+function isDisposedError(err) {
+    return err instanceof AgentSDKError && err.type === AgentSDKErrorType.DISPOSED;
+}
+/**
+ * Mastra-backed implementation of {@link AgentHarness}.
+ *
+ * ### Mastra Concepts
+ *
+ * | Our Concept            | Mastra Concept                                          |
+ * | ---------------------- | ------------------------------------------------------- |
+ * | `initialize()`         | `new Mastra({ storage, gateways })`                     |
+ * | `createAgent()`        | `new Agent({ id, instructions, model, tools, memory })` |
+ * | `createThread()`       | `memory.createThread({ threadId, resourceId })`         |
+ * | `stream()`             | `agent.stream(message, { memory: { thread, resource } })`|
+ * | `approveToolCall()`    | `agent.approveToolCall({ toolCallId, runId, threadId })` |
+ * | `getMessages()`        | `memory.recall({ threadId, perPage, page })`            |
+ */
+/**
+ * Production memory strategy for v1.
+ *
+ * Memory is configured once at the MastraHarness level and shared by all agents.
+ * This is an intentional design choice: Mastra's Memory is an agent-level
+ * construct, not a session-level one. Per-thread memory configuration is not
+ * natively supported through Mastra's public API. Data isolation between
+ * sessions is handled by Mastra's threadId/resourceId scoping, not by
+ * separate Memory instances.
+ *
+ * Configuration:
+ *  - lastMessages: 40 — sliding window of recent messages included in context.
+ *  - workingMemory: enabled, scope 'thread' — structured state persists across
+ *    turns within a single chat session only. We use thread scope (not Mastra's
+ *    default resource scope) so each conversation is isolated: resource-scoped
+ *    working memory would be shared across all threads for the same agent.
+ *  - semanticRecall: disabled — no embedding provider or vector store is
+ *    configured for v1. RAG-based retrieval of past messages can be enabled
+ *    later by adding an embedder and vector store to the Memory constructor.
+ *  - observationalMemory: disabled (default) — Mastra's Observational Memory
+ *    runs background Observer and Reflector LLM calls to compress long context.
+ *    Those calls consume model requests beyond the user's visible conversation;
+ *    we avoid enabling OM until customers can afford silent background usage or
+ *    we have dedicated infrastructure budget. See:
+ *    https://mastra.ai/docs/memory/observational-memory
+ *  - generateTitle: disabled (default) — Mastra can auto-generate thread titles
+ *    via an extra LLM call per new thread. We leave it off for the same budget
+ *    rationale as observational memory; apps can set titles explicitly if needed.
+ *
+ * This configuration is internal and is NOT exposed through the SDK's public
+ * API surface (src/index.ts).
+ */
+const LAST_MESSAGES_WINDOW = 40;
+/**
+ * Maximum flattened-transcript length (in characters) sent to the model in a
+ * single summarization call. Transcripts above this size are split into
+ * roughly-equal chunks, each chunk is summarized separately, and the
+ * concatenated chunk-summaries are then summarized into a final summary.
+ *
+ * Rationale: ~400k characters maps to ~100k tokens at a conservative 4:1
+ * chars-per-token ratio for English plus JSON tool args. That leaves headroom
+ * under typical 200k-token gateway model context windows for the prompt
+ * scaffolding and the model's own response. The ratio is rough but errs
+ * toward "fits" — a tokenizer can be swapped in later behind the same
+ * constant if precise budgeting becomes necessary.
+ */
+const MAX_TRANSCRIPT_CHARS = 400_000;
+/**
+ * Default timeout (in milliseconds) for MCP server connections and requests.
+ * 10 minutes accommodates first-run `npx` installs and long-running operations
+ * like deploys. Per-server `timeout` in MCPServerConfig still overrides this.
+ */
+const DEFAULT_MCP_TIMEOUT_MS = 600_000;
+export class MastraHarness {
+    storageRootFolder;
+    modelConfigFactory;
+    clock;
+    idGenerator;
+    harnessId = 'mastra';
+    protocolVersion = 1;
+    /**
+     * Registry of agentId → Mastra state. Holds per-agent MCPClient instances
+     * so each agent has isolated server connections; sharing across agents
+     * would mix process state.
+     */
+    activeAgents = new Map();
+    storage;
+    memory;
+    mastra;
+    buses = new HarnessBusOwner();
+    constructor(storageRootFolder, modelConfigFactory = new DefaultMastraModelConfigFactory(), clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+        this.storageRootFolder = storageRootFolder;
+        this.modelConfigFactory = modelConfigFactory;
+        this.clock = clock;
+        this.idGenerator = idGenerator;
+        this.storage = new LibSQLStore({
+            id: 'mastra-storage',
+            url: `file:${this.storageRootFolder}/mastra.db`,
+        });
+        this.memory = new Memory({
+            storage: this.storage,
+            options: {
+                lastMessages: LAST_MESSAGES_WINDOW,
+                semanticRecall: false,
+                workingMemory: {
+                    enabled: true,
+                    scope: 'thread',
+                },
+            },
+        });
+        this.mastra = new Mastra({
+            storage: this.storage,
+            memory: { shared: this.memory },
+        });
+    }
+    /**
+     * @requirements
+     * - MUST disconnect the mcpClient for every active agent before clearing state.
+     * - MUST clear the `activeAgents` map.
+     * - MUST shut down the global `this.mastra` orchestrator.
+     */
+    async shutdown() {
+        await Promise.all([...this.activeAgents.values()].map(async (state) => {
+            await Promise.allSettled(Array.from(state.mcpServers.values()).map(async (s) => {
+                await s.ready.catch(() => undefined);
+                await s.client.disconnect();
+            }));
+        }));
+        this.activeAgents.clear();
+        await this.mastra?.shutdown();
+        this.buses.dispose();
+    }
+    onTelemetry(callback) {
+        return this.buses.onTelemetry(callback);
+    }
+    onLog(callback) {
+        return this.buses.onLog(callback);
+    }
+    // ── Agent Lifecycle ──────────────────────────────────────────────
+    /**
+     * @requirements
+     * - MUST throw an error if the harness has not been initialized.
+     * - MUST throw an error if an agent with the given `config.agentId` is already registered.
+     * - MUST instantiate a Mastra `Agent` with instructions, model, and memory.
+     * - MUST provide a fallback model string if modelId is absent.
+     * - MUST register the agent with the Mastra instance for gateway resolution.
+     * - MUST construct a per-agent `MCPClient` if `config.mcpServers` has enabled servers and
+     *   kick off `listToolsetsWithErrors()` in the background (non-blocking). MCP tools become available
+     *   once discovery completes; until then the agent operates with custom tools only.
+     * - MUST use a tools function (DynamicArgument) so the agent picks up MCP tools dynamically.
+     * - MUST disconnect and discard the `MCPClient` if tool discovery fails, to avoid orphaned processes.
+     * - MUST respect the `abortSignal` option: check before MCP setup, race listToolsetsWithErrors() against it.
+     * - MUST namespace MCP tool names as `${serverName}_${toolName}` to avoid collisions with custom tools.
+     * - MUST convert `config.tools` (SDK `ToolDefinition[]`) to Mastra `ToolAction` entries via
+     *   `mapToolDefinitionsToMastraTools()` and merge with namespaced MCP-discovered tools.
+     * - MUST store the original `MCPConfiguration` so getMcpServerInfo can report disabled servers.
+     */
+    async createAgent(agentId, projectRoot, llmGatewayClient, config = {}, options) {
+        if (this.activeAgents.has(agentId)) {
+            throw new Error(`Agent with id "${agentId}" is already registered`);
+        }
+        // ── MCP setup (non-blocking, per-server) ──────────────────────────
+        const mcpServerStates = new Map();
+        if (hasEnabledServers(config.mcpServers)) {
+            options?.abortSignal?.throwIfAborted();
+            const enabledServers = mapToMastraMCPServers(config.mcpServers, config.orgJwt);
+            for (const [serverName, serverDef] of Object.entries(enabledServers)) {
+                const client = new MCPClient({
+                    id: `${agentId}:${serverName}`,
+                    servers: { [serverName]: serverDef },
+                    // Fallback only — per-server MCPServerConfig.timeout (in serverDef) takes precedence.
+                    timeout: DEFAULT_MCP_TIMEOUT_MS,
+                });
+                const startTime = this.clock.now().getTime();
+                this.buses.emitTelemetry({
+                    type: 'mcp-server-discovery-started',
+                    timestamp: this.clock.now(),
+                    agentId,
+                    serverName,
+                });
+                const ready = makeAbortable(client.listToolsetsWithErrors(), options?.abortSignal)
+                    .then(({ toolsets, errors }) => {
+                    const serverError = errors[serverName];
+                    if (serverError) {
+                        throw new Error(serverError);
+                    }
+                    const tools = toolsets[serverName] ?? {};
+                    const namespacedTools = {};
+                    for (const [toolName, toolConfig] of Object.entries(tools)) {
+                        namespacedTools[`${serverName}_${toolName}`] = toolConfig;
+                    }
+                    mcpServerStates.get(serverName).tools = namespacedTools;
+                    // listToolsetsWithErrors() runs in the background and can resolve
+                    // after `shutdown()` has disposed the buses. Swallow only `DISPOSED`
+                    // so a real listener exception still surfaces.
+                    try {
+                        this.buses.emitTelemetry({
+                            type: 'mcp-server-discovery-completed',
+                            timestamp: this.clock.now(),
+                            agentId,
+                            serverName,
+                            toolCount: Object.keys(namespacedTools).length,
+                            durationMs: this.clock.now().getTime() - startTime,
+                        });
+                    }
+                    catch (emitErr) {
+                        if (!isDisposedError(emitErr))
+                            throw emitErr;
+                    }
+                })
+                    .catch(async (err) => {
+                    if (options?.abortSignal?.aborted) {
+                        await client.disconnect().catch(() => undefined);
+                        mcpServerStates.delete(serverName);
+                    }
+                    else {
+                        const s = mcpServerStates.get(serverName);
+                        if (s)
+                            s.error = err instanceof Error ? err.message : String(err);
+                        this.buses.getLogBus()?.warn('MCP server discovery failed', {
+                            serverName,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        try {
+                            this.buses.emitTelemetry({
+                                type: 'mcp-server-discovery-failed',
+                                timestamp: this.clock.now(),
+                                agentId,
+                                serverName,
+                                durationMs: this.clock.now().getTime() - startTime,
+                                error: err instanceof Error ? err : new Error(String(err)),
+                            });
+                        }
+                        catch (emitErr) {
+                            if (!isDisposedError(emitErr))
+                                throw emitErr;
+                        }
+                    }
+                })
+                    .finally(() => {
+                    const s = mcpServerStates.get(serverName);
+                    if (s)
+                        s.settled = true;
+                });
+                mcpServerStates.set(serverName, { client, ready, settled: false, tools: {} });
+            }
+        }
+        const customTools = config.tools?.length ? mapToolDefinitionsToMastraTools(config.tools) : {};
+        const { model: resolvedModel } = this.modelConfigFactory.create(llmGatewayClient);
+        let mastraWorkspace;
+        let agent;
+        let mastraAgentAdded = false;
+        try {
+            const allowedPaths = (config.skills ?? []).filter((s) => path.isAbsolute(s));
+            const localFs = new LocalFilesystem({ basePath: projectRoot, allowedPaths });
+            const sandbox = new LocalSandbox({
+                workingDirectory: projectRoot,
+            });
+            mastraWorkspace = new Workspace({
+                filesystem: localFs,
+                skills: config.skills,
+                sandbox,
+                tools: Object.fromEntries(ALL_MASTRA_WORKSPACE_TOOL_NAMES.map((nativeName) => [
+                    nativeName,
+                    { name: stripMastraWorkspacePrefix(nativeName) },
+                ])),
+            });
+            await mastraWorkspace.init();
+            agent = new Agent({
+                id: agentId,
+                name: config.name || agentId,
+                instructions: config.instructions || '',
+                model: resolvedModel,
+                memory: this.memory,
+                tools: () => {
+                    const mcpTools = [...mcpServerStates.values()].reduce((acc, s) => ({ ...acc, ...s.tools }), {});
+                    return { ...customTools, ...mcpTools };
+                },
+                workspace: mastraWorkspace,
+            });
+            this.mastra.addAgent(agent);
+            mastraAgentAdded = true;
+            this.activeAgents.set(agentId, {
+                agent,
+                mcpServers: mcpServerStates,
+                mcpConfig: config.mcpServers,
+                mastraWorkspace,
+                activeRuns: new Map(),
+            });
+        }
+        catch (error) {
+            if (mastraAgentAdded) {
+                this.mastra.removeAgent(agentId);
+            }
+            await mastraWorkspace?.destroy().catch(() => undefined);
+            await Promise.allSettled(Array.from(mcpServerStates.values()).map((s) => s.client.disconnect().catch(() => undefined)));
+            throw error;
+        }
+    }
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST disconnect all per-server MCP clients to terminate any spawned processes.
+     * - MUST remove the agent from the internal `activeAgents` map.
+     */
+    async destroyAgent(agentId) {
+        const state = this.getAgentStateOrThrow(agentId);
+        await Promise.allSettled(Array.from(state.mcpServers.values()).map(async (s) => {
+            await s.ready.catch(() => undefined);
+            await s.client.disconnect();
+        }));
+        await state.mastraWorkspace?.destroy();
+        this.mastra.removeAgent(agentId);
+        return this.activeAgents.delete(agentId);
+    }
+    /**
+     * @requirements
+     * - MUST return an array of strings representing the keys currently present in `activeAgents`.
+     */
+    async getAgentIds() {
+        return Array.from(this.activeAgents.keys());
+    }
+    getMcpServerInfo(agentId) {
+        const state = this.getAgentStateOrThrow(agentId);
+        const results = [];
+        for (const [name, serverState] of state.mcpServers) {
+            if (!serverState.settled) {
+                results.push({ name, status: McpServerStatus.Connecting, tools: [] });
+            }
+            else if (serverState.error) {
+                results.push({ error: serverState.error, name, status: McpServerStatus.Error, tools: [] });
+            }
+            else {
+                results.push({ name, status: McpServerStatus.Connected, tools: Object.keys(serverState.tools) });
+            }
+        }
+        if (state.mcpConfig) {
+            for (const [name, serverConfig] of Object.entries(state.mcpConfig)) {
+                if (serverConfig.enabled === false) {
+                    results.push({ name, status: McpServerStatus.Disabled, tools: [] });
+                }
+            }
+        }
+        return results;
+    }
+    // ── Thread (Chat Session) Lifecycle ──────────────────────────────
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST call `memory.createThread()` with the resourceId scoped to this agent.
+     * - MUST use the provided `threadId` if supplied, otherwise generate a new one.
+     * - MUST return the ID of the created thread.
+     */
+    async createThread(agentId, threadId) {
+        const memory = await this.getMemoryOrThrow(agentId);
+        const thread = await memory.createThread({
+            threadId: threadId || this.idGenerator.getUniqueId(),
+            resourceId: this.agentResourceId(agentId),
+        });
+        return thread.id;
+    }
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST delete the thread and its history from the storage backend.
+     * - MUST remove any active run tracked for this thread to prevent stale references.
+     */
+    async destroyThread(agentId, threadId) {
+        this.getAgentStateOrThrow(agentId).activeRuns.delete(threadId);
+        const memory = await this.getMemoryOrThrow(agentId);
+        await memory.deleteThread(threadId);
+    }
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST query threads scoped to this agent and return their IDs.
+     */
+    async getThreadIds(agentId) {
+        const memory = await this.getMemoryOrThrow(agentId);
+        const { threads } = await memory.listThreads({
+            filter: { resourceId: this.agentResourceId(agentId) },
+            perPage: false,
+        });
+        return threads.map((t) => t.id);
+    }
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST clone the source thread's messages into a new thread.
+     */
+    async cloneThread(agentId, sourceThreadId, targetThreadId) {
+        const memory = await this.getMemoryOrThrow(agentId);
+        const { thread } = await memory.cloneThread({
+            sourceThreadId,
+            newThreadId: targetThreadId,
+        });
+        return thread.id;
+    }
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST create a new thread seeded with an LLM-generated summary.
+     * - MUST chunk-summarize transcripts that exceed `MAX_TRANSCRIPT_CHARS`
+     *   to keep any single model call inside the context window.
+     * - MUST surface summarization or seeding failures as `AgentSDKError`
+     *   with type `COMPACTION_FAILED` and leave the source thread intact on
+     *   failure.
+     * - MUST destroy the source thread on success so it no longer appears in
+     *   `getThreadIds()`. Cleanup of the source thread is best-effort: if the
+     *   delete fails the new thread is still returned, since the user's data
+     *   has already been persisted there. An orphaned source thread is
+     *   hygiene, not correctness.
+     * - MUST seed the summary as a user/assistant turn pair where the user
+     *   turn carries the summary content and the assistant turn is a brief
+     *   acknowledgment. Storing the summary as an assistant turn (even with
+     *   a preceding user prompt) is empirically unreliable: the model
+     *   recognizes it has no record of producing that summary and rejects
+     *   it as fabricated, refusing to use the facts on follow-up turns.
+     *   User turns are treated as authoritative input.
+     */
+    async compactThread(agentId, threadId) {
+        this.getAgentStateOrThrow(agentId);
+        const messages = await this.getMessages(agentId, threadId);
+        if (messages.length === 0) {
+            return this.createThread(agentId);
+        }
+        const transcript = messages
+            .map((m) => {
+            const text = typeof m.content === 'string' ? m.content : m.content.map((p) => partToTranscriptText(p)).join(' ');
+            return `${m.role}: ${text}`;
+        })
+            .join('\n');
+        let newThreadId;
+        try {
+            const summaryText = transcript.length <= MAX_TRANSCRIPT_CHARS
+                ? await this.summarize(agentId, this.buildSummaryPrompt(transcript))
+                : await this.summarizeInChunks(agentId, transcript);
+            newThreadId = await this.createThread(agentId);
+            const userTs = this.clock.now();
+            const assistantTs = this.clock.nextAfter(userTs);
+            await this.addContext(agentId, newThreadId, [
+                {
+                    id: this.idGenerator.getUniqueId(),
+                    role: 'user',
+                    content: `The following is a summary of our prior conversation, provided as context for this session:\n\n${summaryText}`,
+                    createdAt: userTs,
+                },
+                {
+                    id: this.idGenerator.getUniqueId(),
+                    role: 'assistant',
+                    content: 'Understood. I have the context from our prior conversation and am ready to continue.',
+                    createdAt: assistantTs,
+                },
+            ]);
+        }
+        catch (err) {
+            throw new AgentSDKError(`Failed to compact thread "${threadId}" for agent "${agentId}": ${err instanceof Error ? err.message : String(err)}`, AgentSDKErrorType.COMPACTION_FAILED, { cause: err });
+        }
+        // Source-thread cleanup is best-effort. The user's data is already
+        // safely seeded into newThreadId; a failed delete leaves an orphan
+        // but does not invalidate the compaction outcome.
+        await this.destroyThread(agentId, threadId).catch(() => undefined);
+        return newThreadId;
+    }
+    // ── Core Messaging ───────────────────────────────────────────────
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST invoke `agent.stream()` with memory context for the thread.
+     * - MUST capture the `runId` for tool approval flows.
+     * - MUST return a `ChatStreamResult` with `textStream` and `eventStream`.
+     * - On pre-stream rejection from `agent.stream()`, MUST re-throw without emitting telemetry —
+     *   the SDK's chat-session boundary catches the rejection and emits `chat-stream-error`.
+     */
+    async stream(agentId, threadId, message, options) {
+        const agentState = this.getAgentStateOrThrow(agentId);
+        const output = await agentState.agent.stream(message, {
+            memory: {
+                thread: threadId,
+                resource: this.agentResourceId(agentId),
+            },
+            maxSteps: options?.maxSteps ?? DEFAULT_MAX_STEPS,
+            abortSignal: options?.abortSignal,
+            requireToolApproval: options?.requireToolApproval,
+        });
+        return this.toChatStreamResult(agentState, threadId, output);
+    }
+    // ── Tool Execution ───────────────────────────────────────────────
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST throw an error if no active run exists for `threadId` (the consumer must
+     *   have started a stream via `stream()` first).
+     * - MUST drain the previous stream before resuming to avoid reader-lock conflicts.
+     * - MUST call `agent.resumeStream()` with the client-provided tool result packed
+     *   into `resumeData` (`{ approved: true, result, isError }`). The bridge execute
+     *   handler registered in the tool mapper reads this data and returns it, allowing
+     *   the result to flow through Mastra's native agentic loop.
+     * - MUST update `activeRuns` with the new `runId` from the continuation output.
+     * - MUST return a `ChatStreamResult` with `textStream` and `eventStream`.
+     * - On pre-stream rejection from `agent.resumeStream()`, MUST re-throw without emitting
+     *   telemetry — the SDK's chat-session boundary catches the rejection and emits
+     *   `chat-stream-error`.
+     */
+    async submitToolResult(agentId, threadId, toolResult) {
+        const agentState = this.getAgentStateOrThrow(agentId);
+        const activeRun = agentState.activeRuns.get(threadId);
+        if (!activeRun) {
+            throw new Error(`MastraHarness.submitToolResult(): no active run found for thread "${threadId}" on agent "${agentId}"`);
+        }
+        await this.drainReadableStream(activeRun.fullStream);
+        const output = await agentState.agent.resumeStream({ approved: true, result: toolResult.result, isError: toolResult.isError }, {
+            runId: activeRun.runId,
+            toolCallId: toolResult.toolCallId,
+            memory: {
+                thread: threadId,
+                resource: this.agentResourceId(agentId),
+            },
+        });
+        return this.toChatStreamResult(agentState, threadId, output);
+    }
+    // ── Tool Approval ────────────────────────────────────────────────
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST throw an error if no active `runId` is stored for `threadId` in `activeRuns`
+     *   (i.e. the caller has not yet started a stream on that thread).
+     * - MUST invoke `agent.approveToolCall()` with the stored `runId`, the `toolCallId`, and
+     *   the thread's memory context (`thread: threadId`, `resource: AGENT_INSTANCE:<agentId>`).
+     *   Mastra then unblocks the suspended tool execution, runs the tool, and generates the
+     *   continuation response.
+     * - MUST update `activeRuns` with the new `runId` from the continuation output so that
+     *   any subsequent `approveToolCall()` / `declineToolCall()` calls within the same thread
+     *   reference the most recent run.
+     * - MUST return a `ChatStreamResult` with `textStream` and `eventStream` from the
+     *   continuation output, following the same pattern as AI SDK, ACP, and Mastra's own
+     *   streaming APIs where approval produces a new continuation stream.
+     * - On pre-stream rejection from `agent.approveToolCall()`, MUST re-throw without emitting
+     *   telemetry — the SDK's chat-session boundary catches the rejection and emits
+     *   `chat-stream-error`.
+     */
+    async approveToolCall(agentId, threadId, toolCallId) {
+        const agentState = this.getAgentStateOrThrow(agentId);
+        const activeRun = agentState.activeRuns.get(threadId);
+        if (!activeRun) {
+            throw new Error(`MastraHarness.approveToolCall(): no active run found for thread "${threadId}" on agent "${agentId}"`);
+        }
+        await this.drainReadableStream(activeRun.fullStream);
+        const output = await agentState.agent.approveToolCall({
+            runId: activeRun.runId,
+            toolCallId,
+            memory: {
+                thread: threadId,
+                resource: this.agentResourceId(agentId),
+            },
+        });
+        return this.toChatStreamResult(agentState, threadId, output);
+    }
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
+     * - MUST throw an error if no active `runId` is stored for `threadId` in `activeRuns`.
+     * - MUST invoke `agent.declineToolCall()` with the stored `runId`, the `toolCallId`, and
+     *   the thread's memory context. Mastra cancels the pending tool call and generates a
+     *   continuation response acknowledging the decline.
+     * - MUST update `activeRuns` with the new `runId` from the continuation output.
+     * - MUST return a `ChatStreamResult` with `textStream` and `eventStream` from the
+     *   continuation output.
+     * - On pre-stream rejection from `agent.declineToolCall()`, MUST re-throw without emitting
+     *   telemetry — the SDK's chat-session boundary catches the rejection and emits
+     *   `chat-stream-error`.
+     */
+    async declineToolCall(agentId, threadId, toolCallId) {
+        const agentState = this.getAgentStateOrThrow(agentId);
+        const activeRun = agentState.activeRuns.get(threadId);
+        if (!activeRun) {
+            throw new Error(`MastraHarness.declineToolCall(): no active run found for thread "${threadId}" on agent "${agentId}"`);
+        }
+        await this.drainReadableStream(activeRun.fullStream);
+        const output = await agentState.agent.declineToolCall({
+            runId: activeRun.runId,
+            toolCallId,
+            memory: {
+                thread: threadId,
+                resource: this.agentResourceId(agentId),
+            },
+        });
+        return this.toChatStreamResult(agentState, threadId, output);
+    }
+    // ── Message History ──────────────────────────────────────────────
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found.
+     * - MUST retrieve messages via `memory.recall()` and map to our `Message` format.
+     */
+    async getMessages(agentId, threadId) {
+        const memory = await this.getMemoryOrThrow(agentId);
+        const { messages } = await memory.recall({
+            threadId,
+            resourceId: this.agentResourceId(agentId),
+            perPage: false,
+        });
+        const logBus = this.buses.getLogBus();
+        return messages
+            .map((m) => mapMastraToMessage(m, logBus))
+            .sort((a, b) => (a.createdAt?.getTime() ?? 0) - (b.createdAt?.getTime() ?? 0));
+    }
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found.
+     * - MUST delete all messages in the thread.
+     */
+    async clearMessages(agentId, threadId) {
+        const memory = await this.getMemoryOrThrow(agentId);
+        const { messages } = await memory.recall({
+            threadId,
+            resourceId: this.agentResourceId(agentId),
+            perPage: false,
+        });
+        if (messages.length > 0) {
+            await memory.deleteMessages(messages.map((m) => m.id));
+        }
+    }
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found.
+     * - MUST save context messages without triggering an LLM response.
+     */
+    async addContext(agentId, threadId, messages) {
+        const memory = await this.getMemoryOrThrow(agentId);
+        const resourceId = this.agentResourceId(agentId);
+        const mapped = messages.map((m) => mapMessageToMastra(m, threadId, resourceId, this.clock));
+        await memory.saveMessages({ messages: mapped });
+    }
+    // ── Private Helpers ──────────────────────────────────────────────
+    /**
+     * Issue a single non-agentic model call (`maxSteps: 1`) for one-shot
+     * summarization. Used internally by `compactThread()`; not part of the
+     * `AgentHarness` contract because the SDK never calls summarization
+     * directly.
+     */
+    async summarize(agentId, prompt) {
+        const agentState = this.getAgentStateOrThrow(agentId);
+        const result = await agentState.agent.generate(prompt, { maxSteps: 1 });
+        return result.text;
+    }
+    buildSummaryPrompt(transcript) {
+        return ('Summarize the following conversation into a concise context summary. ' +
+            'Preserve key decisions, facts, and action items. ' +
+            'Write in third person as a factual record.\n\n' +
+            transcript);
+    }
+    /**
+     * Two-pass summarization for transcripts above the char budget. The
+     * transcript is split into roughly-equal chunks each ≤ MAX_TRANSCRIPT_CHARS,
+     * each chunk is summarized, and the concatenated chunk summaries are
+     * summarized again into the final summary.
+     */
+    async summarizeInChunks(agentId, transcript) {
+        const chunks = this.splitIntoChunks(transcript, MAX_TRANSCRIPT_CHARS);
+        const chunkSummaries = [];
+        for (const chunk of chunks) {
+            const summary = await this.summarize(agentId, this.buildSummaryPrompt(chunk));
+            chunkSummaries.push(summary);
+        }
+        const merged = chunkSummaries.map((s, i) => `Part ${i + 1}:\n${s}`).join('\n\n');
+        // The merged summaries will almost always fit, but a pathologically
+        // long chat could in principle still exceed budget. If so, recurse;
+        // otherwise final-summarize.
+        return merged.length <= MAX_TRANSCRIPT_CHARS
+            ? this.summarize(agentId, this.buildSummaryPrompt(merged))
+            : this.summarizeInChunks(agentId, merged);
+    }
+    /**
+     * Splits a string into ≤ `maxChars`-sized chunks, preferring line
+     * boundaries so message turns are not torn across chunks. Falls back to
+     * a hard slice if a single line itself exceeds the budget.
+     */
+    splitIntoChunks(text, maxChars) {
+        const chunks = [];
+        const lines = text.split('\n');
+        let current = '';
+        for (const line of lines) {
+            if (line.length > maxChars) {
+                if (current.length > 0) {
+                    chunks.push(current);
+                    current = '';
+                }
+                for (let i = 0; i < line.length; i += maxChars) {
+                    chunks.push(line.slice(i, i + maxChars));
+                }
+                continue;
+            }
+            const candidate = current.length === 0 ? line : current + '\n' + line;
+            if (candidate.length > maxChars) {
+                chunks.push(current);
+                current = line;
+            }
+            else {
+                current = candidate;
+            }
+        }
+        if (current.length > 0) {
+            chunks.push(current);
+        }
+        return chunks;
+    }
+    getAgentStateOrThrow(agentId) {
+        const state = this.activeAgents.get(agentId);
+        if (!state) {
+            throw new Error(`Agent with id "${agentId}" is not registered`);
+        }
+        return state;
+    }
+    toChatStreamResult(agentState, threadId, output) {
+        // Entries are keyed by threadId so each thread holds at most one entry.
+        // Stale entries are overwritten here on the next stream; explicit cleanup
+        // happens via destroyThread() / destroyAgent() / shutdown(). Proactive
+        // removal on stream completion is not safe because the suspend/resume
+        // flow (submitToolResult, approveToolCall) needs the entry after the stream closes.
+        agentState.activeRuns.set(threadId, { runId: output.runId, fullStream: output.fullStream });
+        const adapter = new MastraEventAdapter(this.buses.getLogBus());
+        return {
+            eventStream: this.createEventStream(output.fullStream, adapter),
+            textStream: this.readableStreamToAsyncGenerator(output.textStream),
+        };
+    }
+    async getMemoryOrThrow(agentId) {
+        const agentState = this.getAgentStateOrThrow(agentId);
+        const memory = await agentState.agent.getMemory();
+        if (!memory) {
+            throw new Error(`Agent "${agentId}" has no memory configured`);
+        }
+        return memory;
+    }
+    agentResourceId(agentId) {
+        return `AGENT_INSTANCE:${agentId}`;
+    }
+    async *createEventStream(fullStream, adapter) {
+        for await (const chunk of this.readableStreamToAsyncGenerator(fullStream)) {
+            const event = adapter.toChatEvent(chunk);
+            if (!event)
+                continue;
+            yield event;
+        }
+    }
+    async *readableStreamToAsyncGenerator(stream) {
+        const reader = stream.getReader();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                yield value;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Consume any remaining chunks from a ReadableStream, discarding them.
+     *
+     * Mastra persists workflow snapshots asynchronously after emitting the
+     * last stream chunk. If the consumer broke out of the event stream early
+     * (e.g. on `tool-approval-request`), the reader lock was released but
+     * the snapshot may not yet be persisted. Draining the remaining chunks
+     * guarantees the snapshot is ready before we call `agent.approveToolCall()`
+     * or `agent.declineToolCall()`.
+     *
+     * If the stream was already fully consumed (normal finish, no break),
+     * this is a no-op — the reader gets `done` immediately.
+     *
+     * No timeout guard: this stream is always the `fullStream` from a Mastra
+     * agent call backed by a bounded LLM completion. The model will always
+     * emit a stop reason and Mastra will close the stream. A true hang (e.g.,
+     * network drop with no gateway timeout) would surface as a rejected
+     * promise from `reader.read()`, not an infinite loop.
+     */
+    async drainReadableStream(stream) {
+        const reader = stream.getReader();
+        try {
+            while (!(await reader.read()).done) {
+                /* discard */
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
+//# sourceMappingURL=mastra-harness.js.map