@salesforce/sfdx-agent-harness-mastra 0.1.0

package/dist/mastra-harness.d.ts

@@ -0,0 +1,292 @@
+import { Agent } from '@mastra/core/agent';
+import type { ChunkType } from '@mastra/core/stream';
+import { MCPClient } from '@mastra/mcp';
+import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerInfo, type Message, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
+import type { MastraModelConfigFactory } from './model-config-factory.js';
+import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+import { Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
+import { type ToolsInput } from './utils.js';
+import { Workspace } from '@mastra/core/workspace';
+/**
+ * Tracks the active workflow run for a single thread.
+ *
+ * Mastra uses `runId` to locate the suspended workflow snapshot when
+ * `approveToolCall()` / `declineToolCall()` resume a stream. The
+ * `fullStream` reference is kept so we can drain any unconsumed chunks
+ * before resuming — Mastra persists its workflow snapshot asynchronously
+ * after emitting the last stream chunk (e.g. `tool-call-approval`), so
+ * if the consumer breaks out of the event stream early (common in
+ * approval UIs), we must finish reading the stream to ensure the
+ * snapshot is persisted before we attempt to resume.
+ */
+interface ActiveRun {
+    runId: string;
+    fullStream: ReadableStream<ChunkType>;
+}
+/**
+ * Per-server MCP state. Each enabled server gets its own MCPClient and
+ * independent discovery promise so readiness is tracked individually.
+ */
+interface McpServerState {
+    client: MCPClient;
+    error?: string;
+    ready: Promise<void>;
+    settled: boolean;
+    tools: ToolsInput;
+}
+/**
+ * Internal state for a single agent. Holds Mastra-specific instances so the
+ * generic API never sees them.
+ */
+interface MastraAgentState {
+    /** Mastra Agent instance. */
+    agent: Agent;
+    /** Per-server MCP state, keyed by server name. Empty map when no MCP servers are configured. */
+    mcpServers: Map<string, McpServerState>;
+    /** Original MCP configuration, retained so getMcpServerInfo can report disabled servers. */
+    mcpConfig?: MCPConfiguration;
+    /** Mastra Workspace providing built-in file tools to the agent. */
+    mastraWorkspace?: Workspace;
+    /** Tracks the active workflow run per thread for tool approval. */
+    activeRuns: Map<string, ActiveRun>;
+}
+export declare class MastraHarness implements AgentHarness {
+    private readonly storageRootFolder;
+    private readonly modelConfigFactory;
+    private readonly clock;
+    private readonly idGenerator;
+    readonly harnessId = "mastra";
+    readonly 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.
+     */
+    protected readonly activeAgents: Map<string, MastraAgentState>;
+    private readonly storage;
+    private readonly memory;
+    private readonly mastra;
+    private readonly buses;
+    constructor(storageRootFolder: string, modelConfigFactory?: MastraModelConfigFactory, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    /**
+     * @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.
+     */
+    shutdown(): Promise<void>;
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    /**
+     * @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.
+     */
+    createAgent(agentId: string, projectRoot: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * @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.
+     */
+    destroyAgent(agentId: string): Promise<boolean>;
+    /**
+     * @requirements
+     * - MUST return an array of strings representing the keys currently present in `activeAgents`.
+     */
+    getAgentIds(): Promise<string[]>;
+    getMcpServerInfo(agentId: string): McpServerInfo[];
+    /**
+     * @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.
+     */
+    createThread(agentId: string, threadId?: string): Promise<string>;
+    /**
+     * @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.
+     */
+    destroyThread(agentId: string, threadId: string): Promise<void>;
+    /**
+     * @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.
+     */
+    getThreadIds(agentId: string): Promise<string[]>;
+    /**
+     * @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.
+     */
+    cloneThread(agentId: string, sourceThreadId: string, targetThreadId?: string): Promise<string>;
+    /**
+     * @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.
+     */
+    compactThread(agentId: string, threadId: string): Promise<string>;
+    /**
+     * @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`.
+     */
+    stream(agentId: string, threadId: string, message: string, options?: StreamOptions): Promise<ChatStreamResult>;
+    /**
+     * @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`.
+     */
+    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    /**
+     * @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`.
+     */
+    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    /**
+     * @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`.
+     */
+    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found.
+     * - MUST retrieve messages via `memory.recall()` and map to our `Message` format.
+     */
+    getMessages(agentId: string, threadId: string): Promise<Message[]>;
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found.
+     * - MUST delete all messages in the thread.
+     */
+    clearMessages(agentId: string, threadId: string): Promise<void>;
+    /**
+     * @requirements
+     * - MUST throw an error if the specified `agentId` is not found.
+     * - MUST save context messages without triggering an LLM response.
+     */
+    addContext(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+    /**
+     * 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.
+     */
+    private summarize;
+    private buildSummaryPrompt;
+    /**
+     * 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.
+     */
+    private summarizeInChunks;
+    /**
+     * 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.
+     */
+    private splitIntoChunks;
+    private getAgentStateOrThrow;
+    private toChatStreamResult;
+    private getMemoryOrThrow;
+    private agentResourceId;
+    private createEventStream;
+    private readableStreamToAsyncGenerator;
+    /**
+     * 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.
+     */
+    private drainReadableStream;
+}
+export {};