@salesforce/sfdx-agent-sdk 0.1.0

package/dist/chat-session.js

@@ -0,0 +1,407 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { AgentSDKError, AgentSDKErrorType } from './errors.js';
+/**
+ * Default implementation of {@link ChatSession} that delegates all operations
+ * to an {@link AgentHarness}. The session holds its agent ID and thread ID
+ * and forwards calls with appropriate scoping.
+ */
+export class DefaultChatSession {
+    harness;
+    agentId;
+    threadId;
+    chatEventBus = new EventBus();
+    telemetryBus = new EventBus();
+    logBus = new LogBus();
+    inboundUnsubs;
+    parentUnsubs;
+    clock;
+    idGenerator;
+    disposed = false;
+    /**
+     * @param harness - The agent harness managing thread and message lifecycle.
+     * @param agentId - ID of the agent this session belongs to.
+     * @param threadId - ID of the conversation thread backing this session.
+     * @param inbound - Router slice delivering harness events routed to this session.
+     * @param parent - Parent agent's buses; this session forwards its events upward into them.
+     * @param clock - Source of monotonic timestamps for telemetry events. Defaults to `RealClock`.
+     * @param idGenerator - Source of message ids for `addContext()`. Defaults to `UUIDGenerator`.
+     */
+    constructor(harness, agentId, threadId, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+        this.harness = harness;
+        this.agentId = agentId;
+        this.threadId = threadId;
+        this.clock = clock;
+        this.idGenerator = idGenerator;
+        this.inboundUnsubs = [inbound.telemetry.forwardTo(this.telemetryBus), inbound.log.forwardTo(this.logBus)];
+        this.parentUnsubs = [this.telemetryBus.forwardTo(parent.telemetry), this.logBus.forwardTo(parent.log)];
+    }
+    getId() {
+        this.assertNotDisposed();
+        return this.threadId;
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.stream()`, passing `this.agentId` and `this.threadId`.
+     * - MUST pass the `message` string and `options` arguments directly to the harness.
+     * - MUST wrap the returned `eventStream` using `this.wrapEventStream()` so that listeners are notified.
+     * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
+     * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
+     *   before returning a stream result.
+     */
+    async chat(message, options) {
+        this.assertNotDisposed();
+        const startedAt = this.emitChatStreamStarted('chat');
+        try {
+            const result = await this.harness.stream(this.agentId, this.threadId, message, options);
+            return {
+                textStream: result.textStream,
+                eventStream: this.wrapEventStream(result.eventStream, startedAt),
+            };
+        }
+        catch (err) {
+            this.notifyPreStreamError(err, startedAt);
+            throw err;
+        }
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.submitToolResult()`, passing `this.agentId` and `this.threadId`.
+     * - MUST pass the `toolResult` argument directly to the harness.
+     * - MUST wrap the returned `eventStream` using `this.wrapEventStream()` so that listeners are notified.
+     * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
+     * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
+     *   before returning a stream result.
+     */
+    async submitToolResult(toolResult) {
+        this.assertNotDisposed();
+        const startedAt = this.emitChatStreamStarted('submit-tool-result');
+        try {
+            const result = await this.harness.submitToolResult(this.agentId, this.threadId, toolResult);
+            return {
+                textStream: result.textStream,
+                eventStream: this.wrapEventStream(result.eventStream, startedAt),
+            };
+        }
+        catch (err) {
+            this.notifyPreStreamError(err, startedAt);
+            throw err;
+        }
+    }
+    /**
+     * @requirements
+     * - MUST yield each event from the provided `stream`.
+     * - MUST emit the event to the internal `chatEventBus`.
+     * - MUST always yield a `FinishEvent` with `finishReason: 'error'` after any error path
+     *   (in-stream `ErrorEvent` or thrown exception) if no `FinishEvent` was already emitted.
+     * - MUST emit `chat-stream-completed` telemetry on natural completion (no error path).
+     * - MUST emit `chat-stream-error` telemetry exactly once when an error occurred (in-stream
+     *   `ErrorEvent` or thrown exception). Mutually exclusive with `chat-stream-completed`.
+     * - MUST derive `tool-execution-started`, `tool-execution-completed`, and
+     *   `tool-approval-requested` telemetry from the corresponding `ChatEvent` types so harness
+     *   implementations don't reimplement this. `tool-execution-completed.durationMs` is measured
+     *   between the matching `tool-call` and `tool-result`; an unmatched `tool-result` (e.g. from
+     *   a resume flow that crosses a stream boundary) is skipped.
+     *
+     * `chat-stream-started` is emitted by the entry-point method (chat / submitToolResult /
+     * approveToolCall / declineToolCall) before the harness call so that pre-stream rejections
+     * still produce a started+error pair. `startedAt` is captured there and threaded down so
+     * `durationMs` measures real elapsed time on both terminal events.
+     */
+    async *wrapEventStream(stream, startedAt) {
+        const toolStartMs = new Map();
+        let sawFinish = false;
+        let lastError;
+        let finishUsage;
+        try {
+            for await (const event of stream) {
+                this.chatEventBus.emit(event);
+                this.deriveToolTelemetry(event, toolStartMs);
+                yield event;
+                if (event.type === 'finish') {
+                    sawFinish = true;
+                    finishUsage = event.usage;
+                }
+                if (event.type === 'error')
+                    lastError = event.error;
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            const errorEvent = { type: 'error', error };
+            this.chatEventBus.emit(errorEvent);
+            yield errorEvent;
+            lastError = error;
+        }
+        if (!sawFinish && lastError !== undefined) {
+            const finishEvent = { type: 'finish', finishReason: 'error' };
+            this.chatEventBus.emit(finishEvent);
+            yield finishEvent;
+        }
+        const finishedAt = this.clock.now();
+        const durationMs = finishedAt.getTime() - startedAt.getTime();
+        if (lastError !== undefined) {
+            this.telemetryBus.emit({
+                type: 'chat-stream-error',
+                timestamp: finishedAt,
+                agentId: this.agentId,
+                threadId: this.threadId,
+                durationMs,
+                error: lastError,
+            });
+        }
+        else {
+            this.telemetryBus.emit({
+                type: 'chat-stream-completed',
+                timestamp: finishedAt,
+                agentId: this.agentId,
+                threadId: this.threadId,
+                durationMs,
+                usage: finishUsage,
+            });
+        }
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.approveToolCall()`, passing `this.agentId`, `this.threadId`, and `toolCallId`.
+     * - MUST wrap the returned `eventStream` using `this.wrapEventStream()` so that listeners are notified.
+     * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
+     * - MUST emit `tool-approval-resolved` telemetry with `approved: true` only after the harness
+     *   call resolves. Pre-stream rejections produce `chat-stream-error` via `notifyPreStreamError`
+     *   and intentionally skip approval-resolved emission — consumers correlate the prior
+     *   `tool-approval-requested` by `toolCallId` and observe the failure on the chat-stream contract.
+     * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
+     *   before returning a stream result.
+     * - The `options.remember` flag is consumer-only metadata — the harness does not use it.
+     */
+    async approveToolCall(toolCallId, _options) {
+        this.assertNotDisposed();
+        const startedAt = this.emitChatStreamStarted('approve-tool-call');
+        try {
+            const result = await this.harness.approveToolCall(this.agentId, this.threadId, toolCallId);
+            this.emitToolApprovalResolved(toolCallId, true);
+            return {
+                textStream: result.textStream,
+                eventStream: this.wrapEventStream(result.eventStream, startedAt),
+            };
+        }
+        catch (err) {
+            this.notifyPreStreamError(err, startedAt);
+            throw err;
+        }
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.declineToolCall()`, passing `this.agentId`, `this.threadId`, and `toolCallId`.
+     * - MUST wrap the returned `eventStream` using `this.wrapEventStream()` so that listeners are notified.
+     * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
+     * - MUST emit `tool-approval-resolved` telemetry with `approved: false` only after the harness
+     *   call resolves. Pre-stream rejections produce `chat-stream-error` via `notifyPreStreamError`
+     *   and intentionally skip approval-resolved emission.
+     * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
+     *   before returning a stream result.
+     */
+    async declineToolCall(toolCallId) {
+        this.assertNotDisposed();
+        const startedAt = this.emitChatStreamStarted('decline-tool-call');
+        try {
+            const result = await this.harness.declineToolCall(this.agentId, this.threadId, toolCallId);
+            this.emitToolApprovalResolved(toolCallId, false);
+            return {
+                textStream: result.textStream,
+                eventStream: this.wrapEventStream(result.eventStream, startedAt),
+            };
+        }
+        catch (err) {
+            this.notifyPreStreamError(err, startedAt);
+            throw err;
+        }
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.getMessages()`, passing `this.agentId` and `this.threadId`.
+     * - MUST return the result directly.
+     */
+    async getMessageHistory() {
+        this.assertNotDisposed();
+        return this.harness.getMessages(this.agentId, this.threadId);
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.clearMessages()`, passing `this.agentId` and `this.threadId`.
+     */
+    async clearHistory() {
+        this.assertNotDisposed();
+        await this.harness.clearMessages(this.agentId, this.threadId);
+    }
+    /**
+     * @requirements
+     * - IF `message` is a `string`, it MUST be formatted into a standard `Message` object array containing exactly one message.
+     * - The formatted message MUST have `role: 'user'`.
+     * - The formatted message MUST have a newly generated `id` from the injected `idGenerator`.
+     * - The formatted message MUST have a `createdAt` timestamp from the injected `clock`.
+     * - IF `message` is already an array of `Message` objects, it MUST be used directly.
+     * - MUST delegate the final array of messages to `this.harness.addContext()`, passing `this.agentId` and `this.threadId`.
+     */
+    async addContext(message) {
+        this.assertNotDisposed();
+        const messages = typeof message === 'string'
+            ? [
+                {
+                    id: this.idGenerator.getUniqueId(),
+                    role: 'user',
+                    content: message,
+                    createdAt: this.clock.now(),
+                },
+            ]
+            : message;
+        await this.harness.addContext(this.agentId, this.threadId, messages);
+    }
+    /**
+     * @requirements
+     * - MUST register the provided `callback` on the internal `chatEventBus`.
+     * - MUST return an `Unsubscribe` closure that removes the callback when called.
+     */
+    subscribe(callback) {
+        this.assertNotDisposed();
+        return this.chatEventBus.on(callback);
+    }
+    onTelemetry(callback) {
+        this.assertNotDisposed();
+        return this.telemetryBus.on(callback);
+    }
+    onLog(callback) {
+        this.assertNotDisposed();
+        return this.logBus.on(callback);
+    }
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.telemetryBus.emit({
+            type: 'session-destroyed',
+            timestamp: this.clock.now(),
+            agentId: this.agentId,
+            threadId: this.threadId,
+        });
+        for (const unsub of this.inboundUnsubs)
+            unsub();
+        for (const unsub of this.parentUnsubs)
+            unsub();
+        this.chatEventBus.dispose();
+        this.telemetryBus.dispose();
+        this.logBus.dispose();
+        this.disposed = true;
+    }
+    emitToolApprovalResolved(toolCallId, approved) {
+        this.telemetryBus.emit({
+            type: 'tool-approval-resolved',
+            timestamp: this.clock.now(),
+            agentId: this.agentId,
+            threadId: this.threadId,
+            toolCallId,
+            approved,
+        });
+    }
+    /**
+     * Derives `tool-execution-*` and `tool-approval-requested` telemetry from `ChatEvent`s as
+     * they pass through the stream wrapper. Centralizing the derivation here keeps every harness
+     * implementation free of telemetry plumbing — they just yield the right `ChatEvent` shapes.
+     *
+     * `tool-execution-completed.durationMs` is measured between the matching `tool-call` and
+     * `tool-result` using `this.clock`. An unmatched `tool-result` (e.g. a resume flow that
+     * crosses a stream boundary so the original `tool-call` was on a previous stream) is skipped
+     * — the consumer correlates by `toolCallId` against the earlier `tool-execution-started`.
+     */
+    deriveToolTelemetry(event, toolStartMs) {
+        if (event.type === 'tool-call') {
+            toolStartMs.set(event.toolCallId, this.clock.now().getTime());
+            this.telemetryBus.emit({
+                type: 'tool-execution-started',
+                timestamp: this.clock.now(),
+                agentId: this.agentId,
+                threadId: this.threadId,
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+            });
+        }
+        else if (event.type === 'tool-result') {
+            const start = toolStartMs.get(event.toolCallId);
+            if (start === undefined)
+                return;
+            toolStartMs.delete(event.toolCallId);
+            this.telemetryBus.emit({
+                type: 'tool-execution-completed',
+                timestamp: this.clock.now(),
+                agentId: this.agentId,
+                threadId: this.threadId,
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                durationMs: this.clock.now().getTime() - start,
+                isError: event.isError === true,
+            });
+        }
+        else if (event.type === 'tool-approval-request') {
+            this.telemetryBus.emit({
+                type: 'tool-approval-requested',
+                timestamp: this.clock.now(),
+                agentId: this.agentId,
+                threadId: this.threadId,
+                toolCallId: event.toolCall.toolCallId,
+                toolName: event.toolCall.toolName,
+            });
+        }
+    }
+    /**
+     * Emits a `chat-stream-started` telemetry event and returns the `startedAt` timestamp the
+     * caller threads through to the stream wrapper / pre-stream error notifier so terminal
+     * events report real elapsed time.
+     *
+     * Hoisting this above the harness call keeps the `chat-stream-*` contract honest under
+     * pre-stream failures: every `chat-stream-error` follows a `chat-stream-started` for the
+     * same `(agentId, threadId)` pair.
+     */
+    emitChatStreamStarted(trigger) {
+        const startedAt = this.clock.now();
+        this.telemetryBus.emit({
+            type: 'chat-stream-started',
+            timestamp: startedAt,
+            agentId: this.agentId,
+            threadId: this.threadId,
+            trigger,
+        });
+        return startedAt;
+    }
+    /**
+     * Emits an `ErrorEvent` + `FinishEvent` to all `subscribe()` listeners and a `chat-stream-error`
+     * telemetry event for a failure that occurred before a stream was established. The caller is
+     * responsible for re-throwing the original error after calling this — the method itself does
+     * not throw.
+     *
+     * `startedAt` is the timestamp captured by {@link emitChatStreamStarted} so `durationMs`
+     * measures real elapsed time even for pre-stream rejections.
+     */
+    notifyPreStreamError(err, startedAt) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.chatEventBus.emit({ type: 'error', error });
+        this.chatEventBus.emit({ type: 'finish', finishReason: 'error' });
+        const finishedAt = this.clock.now();
+        this.telemetryBus.emit({
+            type: 'chat-stream-error',
+            timestamp: finishedAt,
+            agentId: this.agentId,
+            threadId: this.threadId,
+            durationMs: finishedAt.getTime() - startedAt.getTime(),
+            error,
+        });
+    }
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw new AgentSDKError('ChatSession has been disposed.', AgentSDKErrorType.DISPOSED);
+        }
+    }
+}
+//# sourceMappingURL=chat-session.js.map

package/dist/chat-session.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare const AgentSDKErrorType: {
+    readonly AGENT_NOT_FOUND: "AGENT_NOT_FOUND";
+    readonly CHAT_SESSION_NOT_FOUND: "CHAT_SESSION_NOT_FOUND";
+    readonly COMPACTION_FAILED: "COMPACTION_FAILED";
+    readonly DISPOSED: "DISPOSED";
+    readonly INCOMPATIBLE_HARNESS: "INCOMPATIBLE_HARNESS";
+};
+export type AgentSDKErrorType = (typeof AgentSDKErrorType)[keyof typeof AgentSDKErrorType];
+export declare class AgentSDKError extends Error {
+    readonly type: AgentSDKErrorType;
+    constructor(message: string, type: AgentSDKErrorType, options?: ErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export const AgentSDKErrorType = {
+    AGENT_NOT_FOUND: 'AGENT_NOT_FOUND',
+    CHAT_SESSION_NOT_FOUND: 'CHAT_SESSION_NOT_FOUND',
+    COMPACTION_FAILED: 'COMPACTION_FAILED',
+    DISPOSED: 'DISPOSED',
+    INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS',
+};
+export class AgentSDKError extends Error {
+    type;
+    constructor(message, type, options) {
+        super(message, options);
+        this.name = 'AgentSDKError';
+        this.type = type;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC7B,eAAe,EAAE,iBAAiB;IAClC,sBAAsB,EAAE,wBAAwB;IAChD,iBAAiB,EAAE,mBAAmB;IACtC,QAAQ,EAAE,UAAU;IACpB,oBAAoB,EAAE,sBAAsB;CACtC,CAAC;AAIX,MAAM,OAAO,aAAc,SAAQ,KAAK;IACpB,IAAI,CAAoB;IAExC,YAAY,OAAe,EAAE,IAAuB,EAAE,OAAsB;QACxE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ"}

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

@@ -0,0 +1,200 @@
+import type { LogRecord, Unsubscribe } from '@salesforce/agentic-common';
+import type { McpServerInfo } from '../mcp-config.js';
+import type { ChatStreamResult } from '../types/events.js';
+import type { Message } from '../types/messages.js';
+import type { TelemetryEventCallback } from '../types/telemetry-events.js';
+import type { ToolResultInfo } from '../types/tools.js';
+import type { HarnessAgentConfig, StreamOptions } from './harness-config.js';
+import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly [1];
+/**
+ * Harness-agnostic interface abstracting the agentic runtime.
+ *
+ * This is the core abstraction that allows swapping agent harnesses (Mastra,
+ * Gemini, or future implementations) without changing consumer code. It manages
+ * the full lifecycle: agent creation, thread management, streaming, tool
+ * execution, approval flows, and message history.
+ *
+ * This interface is our own design — no AI SDK or ACP equivalent exists at this
+ * framework layer. AI SDK operates at the model-provider level; ACP operates at
+ * the communication-protocol level. `AgentHarness` operates at the agentic-
+ * framework level that sits between them.
+ */
+export interface AgentHarness {
+    /** Unique identifier for this harness type (e.g., `'mastra'`). */
+    readonly harnessId: string;
+    /** Version of the SDK-to-harness protocol implemented by this harness. */
+    readonly protocolVersion: number;
+    /**
+     * Shut down the harness gracefully, releasing all resources.
+     * Disconnects MCP servers, closes storage connections, and
+     * deregisters all agents.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Subscribe to telemetry events emitted by the harness. Returns an unsubscribe function.
+     *
+     * Events carry `agentId` and (where applicable) `threadId` so the SDK can route them to the correct
+     * `Agent` / `ChatSession` scope. Implementors should not expose these buses directly to consumers —
+     * consumers subscribe at the SDK layer (`AgentManager` / `Agent` / `ChatSession`).
+     */
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    /**
+     * Subscribe to structured log records emitted by the harness. Returns an unsubscribe function.
+     *
+     * Records SHOULD carry `agentId` / `threadId` in their `context` when emitted from an agent- or
+     * thread-scoped code path, so the SDK can route them to the correct subscriber scope.
+     */
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    /**
+     * Create and register a new agent with the given configuration.
+     *
+     * ### MCP Auth Injection
+     *
+     * When `config.orgJwt` is present and the agent has remote MCP servers, implementers
+     * MUST call {@link resolveMcpServerHeaders} for each remote MCP server request. The utility
+     * detects Salesforce Hosted MCP Server URLs, checks for user-provided Authorization
+     * headers (opt-out), and injects a fresh Bearer token — returning the final resolved
+     * headers to use for the request.
+     *
+     * @param agentId - ID to register the agent under.
+     * @param projectRoot - Project folder the agent is allowed to manipulate files from.
+     * @param llmGatewayClient - Pre-configured LLM gateway client for this agent.
+     * @param config - Engine-facing agent configuration (org resolution omitted).
+     * @param options - Optional execution options, including abort signals.
+     */
+    createAgent(agentId: string, projectRoot: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Destroy an agent and release its resources (MCP connections, workspace, memory).
+     * @param agentId - ID of the agent to destroy.
+     */
+    destroyAgent(agentId: string): Promise<boolean>;
+    /**
+     * List the IDs of all currently registered agents.
+     */
+    getAgentIds(): Promise<string[]>;
+    /**
+     * Returns runtime information about MCP servers attached to the given agent,
+     * including connection status and discovered tool names. This is a synchronous
+     * snapshot — status is updated asynchronously by background discovery promises.
+     *
+     * @param agentId - ID of the agent whose MCP servers to inspect.
+     * @returns Info for each configured MCP server (empty array if none configured).
+     */
+    getMcpServerInfo(agentId: string): McpServerInfo[];
+    /**
+     * Create a new conversation thread for an agent.
+     * @param agentId - ID of the owning agent.
+     * @param threadId - Optional thread ID. If omitted, the harness generates one.
+     * @returns The ID of the created thread.
+     */
+    createThread(agentId: string, threadId?: string): Promise<string>;
+    /**
+     * Destroy a thread and its message history.
+     * @param agentId - ID of the owning agent.
+     * @param threadId - ID of the thread to destroy.
+     */
+    destroyThread(agentId: string, threadId: string): Promise<void>;
+    /**
+     * List all thread IDs for a given agent.
+     * @param agentId - ID of the agent whose threads to list.
+     */
+    getThreadIds(agentId: string): Promise<string[]>;
+    /**
+     * Clone an existing thread, creating a new thread with copied message history.
+     * Used to implement conversation forking.
+     * @param agentId - ID of the owning agent.
+     * @param sourceThreadId - ID of the thread to clone.
+     * @param targetThreadId - Optional ID for the new thread.
+     * @returns The ID of the cloned thread.
+     */
+    cloneThread(agentId: string, sourceThreadId: string, targetThreadId?: string): Promise<string>;
+    /**
+     * Compacts a thread's message history to reduce context window usage.
+     * Starts a new conversation thread seeded with an LLM-generated summary of the current session.
+     *
+     * Implementations MUST destroy the source thread on success and leave it
+     * intact on failure. Failures MUST surface as `AgentSDKError` with type
+     * `COMPACTION_FAILED`.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread to compact.
+     * @returns The ID of the new compacted thread.
+     */
+    compactThread(agentId: string, threadId: string): Promise<string>;
+    /**
+     * Stream a response from the agent for the given message.
+     * Returns a {@link ChatStreamResult} providing multiple ways to consume
+     * the stream (text-only or full events).
+     *
+     * @param agentId - ID of the agent to invoke.
+     * @param threadId - ID of the conversation thread.
+     * @param message - User message as a plain string.
+     * @param options - Per-call streaming options.
+     */
+    stream(agentId: string, threadId: string, message: string, options?: StreamOptions): Promise<ChatStreamResult>;
+    /**
+     * Feed the result of a client-side tool execution back into the conversation
+     * and resume stream generation.
+     *
+     * Resumes the suspended agentic loop from the most recent `stream()` call on
+     * the given thread. The harness feeds `toolResult` into the loop and returns
+     * a continuation stream.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread.
+     * @param toolResult - The completed tool execution result.
+     */
+    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    /**
+     * Approve a pending tool call, allowing the harness to execute it.
+     * Called after receiving a `tool-approval-request` event.
+     *
+     * Returns a `ChatStreamResult` containing the continuation stream — the harness
+     * executes the approved tool, generates the model's follow-up response, and
+     * streams both the text and events back to the caller.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread (needed for harness-internal state lookup).
+     * @param toolCallId - ID of the tool call to approve.
+     */
+    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    /**
+     * Decline a pending tool call. The harness resumes the stream with the
+     * model acknowledging the decline and potentially suggesting alternatives.
+     *
+     * Returns a `ChatStreamResult` containing the continuation stream — the harness
+     * cancels the pending tool call, generates the model's acknowledgement response,
+     * and streams both the text and events back to the caller.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread.
+     * @param toolCallId - ID of the tool call to decline.
+     */
+    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    /**
+     * Retrieve message history for a thread.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread.
+     * @returns All messages in chronological order (ascending by creation time).
+     */
+    getMessages(agentId: string, threadId: string): Promise<Message[]>;
+    /**
+     * Delete all messages in a thread (clear history).
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the thread to clear.
+     */
+    clearMessages(agentId: string, threadId: string): Promise<void>;
+    /**
+     * Save context messages to a thread without triggering an LLM response.
+     * Used for injecting system context, file contents, or prior conversation state.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread.
+     * @param messages - Messages to add to the thread history.
+     */
+    addContext(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+}

package/dist/harness/agent-harness.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = [1];
+//# sourceMappingURL=agent-harness.js.map

package/dist/harness/agent-harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-harness.js","sourceRoot":"","sources":["../../src/harness/agent-harness.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,CAAU,CAAC"}