@botbotgo/agent-harness 0.0.308 → 0.0.310

package/dist/protocol/a2a/task-state.d.ts

@@ -0,0 +1,29 @@
+import type { AgentHarnessRuntime } from "../../runtime/harness.js";
+import type { ApprovalRecord, RequestRecord, RequestResult, SessionRecord } from "../../contracts/types.js";
+import type { A2aSendMessageResponse, A2aTask, A2aTaskList, A2aTaskState, A2aStreamingResult, StoredA2aPushNotificationConfig, A2aPushNotificationConfig } from "./http.js";
+export declare function mapRequestState(state: string): A2aTaskState;
+export declare function mapTaskStatusToRequestState(state: string | undefined): RequestResult["state"] | undefined;
+export declare function toTextParts(text: string | undefined): Array<{
+    text: string;
+    mediaType: "text/plain";
+}>;
+export declare function toSessionRecord(session: Awaited<ReturnType<AgentHarnessRuntime["getSessionRecord"]>>): SessionRecord | null;
+export declare function toRequestRecord(request: Awaited<ReturnType<AgentHarnessRuntime["getRequest"]>>): RequestRecord | null;
+export declare function buildTaskFromSessionAndRequest(session: SessionRecord | null, request: RequestRecord | null, approvals: ApprovalRecord[], output?: string, failureMessage?: string): A2aTask | null;
+export declare function buildTaskFromRuntime(runtime: AgentHarnessRuntime, requestId: string): Promise<A2aTask | null>;
+export declare function hydrateTaskStateFromEvents(runtime: AgentHarnessRuntime, task: A2aTask | null): Promise<A2aTask | null>;
+export declare function listTasksFromRuntime(runtime: AgentHarnessRuntime, params: {
+    agentId?: string;
+    contextId?: string;
+    state?: string;
+    limit: number;
+    cursor?: string;
+}): Promise<A2aTaskList>;
+export declare function isV1Method(method: string): boolean;
+export declare function toSendMessageResult(method: string, task: A2aTask | null): A2aTask | A2aSendMessageResponse | null;
+export declare function toStreamingResult(method: string, task: A2aTask | null, mode: "task" | "status-update"): A2aStreamingResult;
+export declare function withStreamingStatusText(task: A2aTask | null, text: string | undefined): A2aTask | null;
+export declare function withRunResult(task: A2aTask | null, result: RequestResult, streamedText?: string): A2aTask | null;
+export declare function isTerminalTaskState(state: A2aTaskState): boolean;
+export declare function clonePushNotificationConfig(config: StoredA2aPushNotificationConfig): A2aPushNotificationConfig;
+export declare function fingerprintTaskForPush(task: A2aTask): string;

package/dist/protocol/a2a/task-state.js

@@ -0,0 +1,317 @@
+export function mapRequestState(state) {
+    switch (state) {
+        case "queued":
+            return "TASK_STATE_SUBMITTED";
+        case "running":
+            return "TASK_STATE_WORKING";
+        case "waiting_for_approval":
+            return "TASK_STATE_INPUT_REQUIRED";
+        case "completed":
+            return "TASK_STATE_COMPLETED";
+        case "cancelled":
+            return "TASK_STATE_CANCELED";
+        case "failed":
+        default:
+            return "TASK_STATE_FAILED";
+    }
+}
+export function mapTaskStatusToRequestState(state) {
+    switch (state?.toLowerCase().replace(/^task_state_/, "").replace(/_/g, "-")) {
+        case "submitted":
+            return "queued";
+        case "working":
+            return "running";
+        case "input-required":
+            return "waiting_for_approval";
+        case "completed":
+            return "completed";
+        case "failed":
+            return "failed";
+        case "canceled":
+        case "cancelled":
+            return "cancelled";
+        default:
+            return undefined;
+    }
+}
+export function toTextParts(text) {
+    if (typeof text !== "string" || text.length === 0) {
+        return [];
+    }
+    return [{ text, mediaType: "text/plain" }];
+}
+function contentToText(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return undefined;
+    }
+    const text = content
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n\n")
+        .trim();
+    return text.length > 0 ? text : undefined;
+}
+export function toSessionRecord(session) {
+    return session ? toSessionRecordInternal(session) : null;
+}
+function toSessionRecordInternal(session) {
+    return {
+        sessionId: session.sessionId,
+        entryAgentId: session.entryAgentId,
+        currentAgentId: session.currentAgentId,
+        currentState: session.currentState,
+        latestRequestId: session.latestRequestId,
+        createdAt: session.createdAt,
+        updatedAt: session.updatedAt,
+        messages: session.messages,
+        requests: session.requests.map((request) => ({
+            requestId: request.requestId,
+            sessionId: request.sessionId,
+            agentId: request.agentId,
+            executionMode: request.executionMode,
+            adapterKind: request.adapterKind,
+            createdAt: request.createdAt,
+            updatedAt: request.updatedAt,
+            state: request.state,
+            checkpointRef: request.checkpointRef,
+            resumable: request.resumable,
+            startedAt: request.startedAt,
+            endedAt: request.endedAt,
+            lastActivityAt: request.lastActivityAt,
+            currentAgentId: request.currentAgentId,
+            delegationChain: request.delegationChain,
+            runtimeSnapshot: request.runtimeSnapshot,
+            traceItems: request.traceItems,
+            runtimeTimeline: request.runtimeTimeline,
+        })),
+        pendingDecision: session.pendingDecision,
+    };
+}
+export function toRequestRecord(request) {
+    if (!request) {
+        return null;
+    }
+    return {
+        requestId: request.requestId,
+        sessionId: request.sessionId,
+        agentId: request.agentId,
+        executionMode: request.executionMode,
+        adapterKind: request.adapterKind,
+        createdAt: request.createdAt,
+        updatedAt: request.updatedAt,
+        state: request.state,
+        checkpointRef: request.checkpointRef,
+        resumable: request.resumable,
+        startedAt: request.startedAt,
+        endedAt: request.endedAt,
+        lastActivityAt: request.lastActivityAt,
+        currentAgentId: request.currentAgentId,
+        delegationChain: request.delegationChain,
+        runtimeSnapshot: request.runtimeSnapshot,
+        traceItems: request.traceItems,
+        runtimeTimeline: request.runtimeTimeline,
+    };
+}
+export function buildTaskFromSessionAndRequest(session, request, approvals, output, failureMessage) {
+    if (!session || !request) {
+        return null;
+    }
+    const latestUserMessage = [...session.messages].reverse().find((message) => message.role === "user");
+    const latestAgentMessage = [...session.messages].reverse().find((message) => message.role === "assistant");
+    const approval = approvals.find((item) => item.status === "pending");
+    const latestAgentText = contentToText(latestAgentMessage?.content);
+    const latestUserText = contentToText(latestUserMessage?.content);
+    const statusText = request.state === "waiting_for_approval"
+        ? approval
+            ? `Approval required for tool ${approval.toolName}.`
+            : "Approval required."
+        : output ?? latestAgentText ?? failureMessage;
+    return {
+        id: request.requestId,
+        contextId: session.sessionId,
+        kind: "task",
+        status: {
+            state: mapRequestState(request.state),
+            timestamp: request.updatedAt,
+            ...(statusText ? {
+                message: {
+                    role: "ROLE_AGENT",
+                    messageId: `${request.requestId}:status`,
+                    parts: toTextParts(statusText),
+                },
+            } : {}),
+        },
+        history: [
+            ...(latestUserText
+                ? [{
+                        role: "ROLE_USER",
+                        messageId: `${request.requestId}:user`,
+                        parts: toTextParts(latestUserText),
+                    }]
+                : []),
+            ...(latestAgentText
+                ? [{
+                        role: "ROLE_AGENT",
+                        messageId: `${request.requestId}:agent`,
+                        parts: toTextParts(latestAgentText),
+                    }]
+                : []),
+        ],
+        artifacts: [],
+        metadata: {
+            agentId: request.agentId,
+            sessionId: session.sessionId,
+            requestId: request.requestId,
+            state: request.state,
+            approvalIds: approvals.map((item) => item.approvalId),
+        },
+    };
+}
+export async function buildTaskFromRuntime(runtime, requestId) {
+    const request = await runtime.getRequest(requestId);
+    if (!request) {
+        return null;
+    }
+    const session = await runtime.getSessionRecord(request.sessionId);
+    const approvals = await runtime.listApprovals({ sessionId: request.sessionId, requestId: request.requestId });
+    return buildTaskFromSessionAndRequest(toSessionRecord(session), toRequestRecord(request), approvals);
+}
+export async function hydrateTaskStateFromEvents(runtime, task) {
+    if (!task) {
+        return null;
+    }
+    const events = await runtime.listRequestEvents(task.contextId, task.id);
+    const lastStateChange = [...events].reverse().find((event) => event.eventType === "request.state.changed");
+    const observedState = typeof lastStateChange?.payload?.state === "string" ? lastStateChange.payload.state : undefined;
+    if (!observedState) {
+        return task;
+    }
+    return {
+        ...task,
+        status: {
+            ...task.status,
+            state: mapRequestState(observedState),
+        },
+        metadata: {
+            ...task.metadata,
+            state: observedState,
+        },
+    };
+}
+export async function listTasksFromRuntime(runtime, params) {
+    const runState = mapTaskStatusToRequestState(params.state);
+    const requests = await runtime.listRequests({
+        ...(params.agentId ? { agentId: params.agentId } : {}),
+        ...(params.contextId ? { sessionId: params.contextId } : {}),
+        ...(runState ? { state: runState } : {}),
+    });
+    const startIndex = params.cursor ? Number.parseInt(Buffer.from(params.cursor, "base64url").toString("utf8"), 10) || 0 : 0;
+    const page = requests.slice(startIndex, startIndex + params.limit);
+    const tasks = (await Promise.all(page.map((request) => buildTaskFromRuntime(runtime, request.requestId)))).filter((task) => Boolean(task));
+    const nextIndex = startIndex + page.length;
+    const nextPageToken = nextIndex < requests.length ? Buffer.from(String(nextIndex), "utf8").toString("base64url") : "";
+    return {
+        tasks,
+        pageSize: params.limit,
+        totalSize: requests.length,
+        nextPageToken,
+        ...(nextPageToken ? { nextCursor: nextPageToken } : {}),
+    };
+}
+export function isV1Method(method) {
+    return /^[A-Z]/.test(method);
+}
+export function toSendMessageResult(method, task) {
+    if (!task || !isV1Method(method)) {
+        return task;
+    }
+    return { task };
+}
+function toStatusUpdate(task) {
+    return {
+        taskId: task.id,
+        contextId: task.contextId,
+        kind: "status-update",
+        status: task.status,
+        final: isTerminalTaskState(task.status.state),
+        metadata: task.metadata,
+    };
+}
+export function toStreamingResult(method, task, mode) {
+    if (!task) {
+        return null;
+    }
+    if (!isV1Method(method)) {
+        return task;
+    }
+    if (mode === "status-update") {
+        return {
+            statusUpdate: toStatusUpdate(task),
+        };
+    }
+    return { task };
+}
+export function withStreamingStatusText(task, text) {
+    if (!task || typeof text !== "string" || text.length === 0) {
+        return task;
+    }
+    return {
+        ...task,
+        status: {
+            ...task.status,
+            message: {
+                role: "ROLE_AGENT",
+                messageId: `${task.id}:status`,
+                parts: toTextParts(text),
+            },
+        },
+    };
+}
+export function withRunResult(task, result, streamedText) {
+    if (!task) {
+        return null;
+    }
+    const statusText = streamedText || result.output;
+    return {
+        ...task,
+        status: {
+            ...task.status,
+            state: mapRequestState(result.state),
+            ...(statusText
+                ? {
+                    message: {
+                        role: "ROLE_AGENT",
+                        messageId: `${task.id}:status`,
+                        parts: toTextParts(statusText),
+                    },
+                }
+                : {}),
+        },
+        metadata: {
+            ...task.metadata,
+            state: result.state,
+        },
+    };
+}
+export function isTerminalTaskState(state) {
+    return state === "TASK_STATE_COMPLETED" || state === "TASK_STATE_FAILED" || state === "TASK_STATE_CANCELED";
+}
+export function clonePushNotificationConfig(config) {
+    return {
+        id: config.id,
+        taskId: config.taskId,
+        url: config.url,
+        ...(config.token ? { token: config.token } : {}),
+        ...(config.authentication ? { authentication: config.authentication } : {}),
+    };
+}
+export function fingerprintTaskForPush(task) {
+    return JSON.stringify({
+        state: task.status.state,
+        timestamp: task.status.timestamp,
+        message: task.status.message,
+    });
+}

package/dist/protocol/acp/client.js

@@ -210,7 +210,7 @@ export function createAcpHttpClient(options) {
                                         listener(parsed);
                                     }
                                     catch {
-                                        // Ignore listener failures so one subscriber cannot tear down the transport.
+                                        // Ignore malformed listener failures.
                                     }
                                 }
                             }

package/dist/protocol/acp/harness-client.d.ts

@@ -0,0 +1,50 @@
+import { type AcpHttpClientOptions, type AcpStdioClient, type AcpStdioClientOptions } from "./client.js";
+import type { Approval, OperatorOverview, RequestEvent, RequestPlanState, RequestTraceItem } from "../../api.js";
+import type { CancelOptions, RequestSummary, RuntimeHealthSnapshot, SessionListSummary, SessionRecord, SessionSummary } from "../../contracts/types.js";
+import type { HarnessClient, HarnessClientApprovalFilter, HarnessClientRequestFilter, HarnessClientRequestOptions, HarnessClientRequestResult } from "../../client/types.js";
+export type AcpHarnessTransport = Pick<AcpStdioClient, "request" | "subscribe" | "close">;
+export declare class AcpHarnessClient implements HarnessClient {
+    private readonly transport;
+    private streamSequence;
+    constructor(transport: AcpHarnessTransport);
+    request(options: HarnessClientRequestOptions): Promise<HarnessClientRequestResult>;
+    private hasStreamingListeners;
+    private streamRequestInternal;
+    private requestWithStreamingListeners;
+    resolveApproval(options: Parameters<HarnessClient["resolveApproval"]>[0]): Promise<HarnessClientRequestResult>;
+    cancelRequest(options: CancelOptions): Promise<HarnessClientRequestResult>;
+    subscribe(listener: (event: RequestEvent) => void | Promise<void>): () => void;
+    listSessions(filter?: {
+        agentId?: string;
+        status?: RequestSummary["state"];
+    }): Promise<SessionSummary[]>;
+    listSessionSummaries(filter?: {
+        agentId?: string;
+        status?: RequestSummary["state"];
+    }): Promise<SessionListSummary[]>;
+    listRequests(filter?: HarnessClientRequestFilter): Promise<RequestSummary[]>;
+    getSession(sessionId: string): Promise<SessionRecord | null>;
+    getRequest(requestId: string): Promise<RequestSummary | null>;
+    listApprovals(filter?: HarnessClientApprovalFilter): Promise<Approval[]>;
+    getApproval(approvalId: string): Promise<Approval | null>;
+    getRequestPlanState(input: {
+        sessionId: string;
+        requestId: string;
+    }): Promise<RequestPlanState | null>;
+    listRequestEvents(input: {
+        sessionId: string;
+        requestId: string;
+    }): Promise<RequestEvent[]>;
+    listRequestTraceItems(input: {
+        sessionId: string;
+        requestId: string;
+    }): Promise<RequestTraceItem[]>;
+    getHealth(): Promise<RuntimeHealthSnapshot>;
+    getOperatorOverview(options?: {
+        limit?: number;
+    }): Promise<OperatorOverview>;
+    stop(): Promise<void>;
+}
+export declare function createAcpHarnessClient(transport: AcpHarnessTransport): HarnessClient;
+export declare function createAcpStdioHarnessClient(options: AcpStdioClientOptions): HarnessClient;
+export declare function createAcpHttpHarnessClient(options: AcpHttpClientOptions): HarnessClient;

package/dist/protocol/acp/harness-client.js

@@ -0,0 +1,219 @@
+import { createAcpHttpClient, createAcpStdioClient, } from "./client.js";
+import { applyRequestStreamItemToSnapshot, createInitialRequestEventSnapshot, toRequestDataEvent, } from "../../projections/request-events.js";
+function toEvent(notification) {
+    return notification.params.event;
+}
+function isRuntimeEventNotification(notification) {
+    return notification.method === "events.runtime";
+}
+function isStreamNotification(notification) {
+    return notification.method === "requests.stream";
+}
+export class AcpHarnessClient {
+    transport;
+    streamSequence = 0;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    request(options) {
+        if (this.hasStreamingListeners(options)) {
+            return this.requestWithStreamingListeners(options);
+        }
+        return this.transport.request("requests.submit", options);
+    }
+    hasStreamingListeners(options) {
+        return Boolean(("eventListener" in options && options.eventListener)
+            || ("dataListener" in options && options.dataListener)
+            || options.listeners);
+    }
+    async *streamRequestInternal(options) {
+        const streamId = `harness-stream-${++this.streamSequence}`;
+        const queued = [];
+        let notify;
+        let settled = false;
+        let streamedResult = false;
+        let responseResolved = false;
+        let failure;
+        let fallbackTimer;
+        const waitForItem = () => new Promise((resolve) => {
+            notify = resolve;
+        });
+        const push = (item) => {
+            queued.push(item);
+            notify?.();
+            notify = undefined;
+        };
+        const settle = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            notify?.();
+            notify = undefined;
+        };
+        const unsubscribe = this.transport.subscribe((notification) => {
+            if (!isStreamNotification(notification) || notification.params.streamId !== streamId) {
+                return;
+            }
+            if (notification.params.item.type === "result") {
+                streamedResult = true;
+                if (fallbackTimer) {
+                    clearTimeout(fallbackTimer);
+                    fallbackTimer = undefined;
+                }
+                if (responseResolved) {
+                    settle();
+                }
+            }
+            push(notification.params.item);
+        });
+        const resultPromise = this.transport.request("requests.submit", {
+            ...options,
+            streamId,
+            listeners: undefined,
+            eventListener: undefined,
+            dataListener: undefined,
+        });
+        resultPromise
+            .then((result) => {
+            responseResolved = true;
+            if (streamedResult) {
+                settle();
+                return;
+            }
+            fallbackTimer = setTimeout(() => {
+                push({
+                    type: "result",
+                    result,
+                });
+                settle();
+            }, 50);
+        })
+            .catch((error) => {
+            failure = error;
+            settle();
+        })
+            .finally(() => undefined);
+        try {
+            while (!settled || queued.length > 0) {
+                if (queued.length === 0) {
+                    await waitForItem();
+                    continue;
+                }
+                const item = queued.shift();
+                if (item) {
+                    yield item;
+                }
+            }
+            if (failure) {
+                throw failure;
+            }
+        }
+        finally {
+            if (fallbackTimer) {
+                clearTimeout(fallbackTimer);
+            }
+            unsubscribe();
+        }
+    }
+    async requestWithStreamingListeners(options) {
+        const legacyListeners = options.listeners;
+        const eventListener = "eventListener" in options ? options.eventListener : undefined;
+        const dataListener = "dataListener" in options ? options.dataListener : undefined;
+        let snapshot = createInitialRequestEventSnapshot();
+        let finalResult;
+        for await (const item of this.streamRequestInternal(options)) {
+            snapshot = applyRequestStreamItemToSnapshot(snapshot, item);
+            if (item.type === "event") {
+                await legacyListeners?.onEvent?.(item.event);
+            }
+            else if (item.type === "upstream-event") {
+                await legacyListeners?.onUpstreamEvent?.(item.event);
+                if (item.surfaceItem) {
+                    await legacyListeners?.onTraceItem?.({
+                        sessionId: item.sessionId,
+                        requestId: item.requestId,
+                        surfaceItem: item.surfaceItem,
+                        event: item.event,
+                    });
+                }
+            }
+            else if (item.type === "plan-state") {
+                await legacyListeners?.onPlanState?.(item.planState);
+            }
+            else if (item.type === "result") {
+                finalResult = item.result;
+            }
+            const dataEvent = toRequestDataEvent(item);
+            if (dataEvent) {
+                await dataListener?.(dataEvent);
+            }
+            await eventListener?.(snapshot);
+        }
+        if (!finalResult) {
+            throw new Error("ACP streaming request completed without a terminal result.");
+        }
+        return finalResult;
+    }
+    resolveApproval(options) {
+        return this.transport.request("approvals.resolve", options);
+    }
+    cancelRequest(options) {
+        return this.transport.request("requests.cancel", options);
+    }
+    subscribe(listener) {
+        return this.transport.subscribe((notification) => {
+            if (isRuntimeEventNotification(notification)) {
+                void listener(toEvent(notification));
+            }
+        });
+    }
+    listSessions(filter) {
+        return this.transport.request("sessions.list", filter);
+    }
+    listSessionSummaries(filter) {
+        return this.transport.request("sessions.summaries", filter);
+    }
+    listRequests(filter) {
+        return this.transport.request("requests.list", filter);
+    }
+    getSession(sessionId) {
+        return this.transport.request("sessions.get", { sessionId });
+    }
+    getRequest(requestId) {
+        return this.transport.request("requests.get", { requestId });
+    }
+    listApprovals(filter) {
+        return this.transport.request("approvals.list", filter);
+    }
+    getApproval(approvalId) {
+        return this.transport.request("approvals.get", { approvalId });
+    }
+    getRequestPlanState(input) {
+        return this.transport.request("requests.plan.get", input);
+    }
+    listRequestEvents(input) {
+        return this.transport.request("events.list", input);
+    }
+    listRequestTraceItems(input) {
+        return this.transport.request("requests.trace.list", input);
+    }
+    getHealth() {
+        return this.transport.request("runtime.health");
+    }
+    getOperatorOverview(options) {
+        return this.transport.request("runtime.overview", options);
+    }
+    stop() {
+        return this.transport.close();
+    }
+}
+export function createAcpHarnessClient(transport) {
+    return new AcpHarnessClient(transport);
+}
+export function createAcpStdioHarnessClient(options) {
+    return new AcpHarnessClient(createAcpStdioClient(options));
+}
+export function createAcpHttpHarnessClient(options) {
+    return new AcpHarnessClient(createAcpHttpClient(options));
+}