@plaited/acp-harness 0.2.5

package/src/acp-utils.ts

@@ -0,0 +1,341 @@
+/**
+ * Internal utilities for ACP content manipulation.
+ *
+ * @remarks
+ * Low-level functions for building content blocks and extracting data
+ * from session responses. These are used internally by the higher-level
+ * helpers in acp-helpers.ts.
+ *
+ * @internal
+ */
+
+import type {
+  BlobResourceContents,
+  ContentBlock,
+  PlanEntry,
+  SessionNotification,
+  SessionUpdate,
+  TextContent,
+  TextResourceContents,
+  ToolCall,
+  ToolCallContent,
+} from '@agentclientprotocol/sdk'
+
+// ============================================================================
+// Content Block Builders
+// ============================================================================
+
+/**
+ * Creates a text content block.
+ *
+ * @param text - The text content
+ * @returns Text content block
+ */
+export const createTextContent = (text: string): ContentBlock => ({
+  type: 'text',
+  text,
+})
+
+/**
+ * Creates an image content block from base64 data.
+ *
+ * @param data - Base64-encoded image data
+ * @param mimeType - MIME type (e.g., 'image/png', 'image/jpeg')
+ * @returns Image content block
+ */
+export const createImageContent = (data: string, mimeType: string): ContentBlock => ({
+  type: 'image',
+  data,
+  mimeType,
+})
+
+/**
+ * Creates an audio content block from base64 data.
+ *
+ * @param data - Base64-encoded audio data
+ * @param mimeType - MIME type (e.g., 'audio/wav', 'audio/mp3')
+ * @returns Audio content block
+ */
+export const createAudioContent = (data: string, mimeType: string): ContentBlock => ({
+  type: 'audio',
+  data,
+  mimeType,
+})
+
+/** Parameters for creating a resource link */
+export type CreateResourceLinkParams = {
+  /** URI to the resource */
+  uri: string
+  /** Resource name (required by SDK) */
+  name: string
+  /** Optional MIME type */
+  mimeType?: string
+}
+
+/**
+ * Creates a resource link content block.
+ *
+ * @param params - Resource link parameters
+ * @returns Resource link content block
+ */
+export const createResourceLink = ({ uri, name, mimeType }: CreateResourceLinkParams): ContentBlock => ({
+  type: 'resource_link',
+  uri,
+  name,
+  ...(mimeType && { mimeType }),
+})
+
+/** Parameters for creating an embedded text resource */
+export type CreateTextResourceParams = {
+  /** URI identifying the resource */
+  uri: string
+  /** Text content of the resource */
+  text: string
+  /** Optional MIME type */
+  mimeType?: string
+}
+
+/**
+ * Creates an embedded text resource content block.
+ *
+ * @param params - Text resource parameters
+ * @returns Resource content block
+ */
+export const createTextResource = ({ uri, text, mimeType }: CreateTextResourceParams): ContentBlock => ({
+  type: 'resource',
+  resource: {
+    uri,
+    text,
+    ...(mimeType && { mimeType }),
+  } as TextResourceContents,
+})
+
+/** Parameters for creating an embedded blob resource */
+export type CreateBlobResourceParams = {
+  /** URI identifying the resource */
+  uri: string
+  /** Base64-encoded binary data */
+  blob: string
+  /** Optional MIME type */
+  mimeType?: string
+}
+
+/**
+ * Creates an embedded blob resource content block.
+ *
+ * @param params - Blob resource parameters
+ * @returns Resource content block
+ */
+export const createBlobResource = ({ uri, blob, mimeType }: CreateBlobResourceParams): ContentBlock => ({
+  type: 'resource',
+  resource: {
+    uri,
+    blob,
+    ...(mimeType && { mimeType }),
+  } as BlobResourceContents,
+})
+
+// ============================================================================
+// Content Extraction
+// ============================================================================
+
+/**
+ * Extracts all text from content blocks.
+ *
+ * @param content - Array of content blocks
+ * @returns Concatenated text content
+ */
+export const extractText = (content: ContentBlock[]): string => {
+  return content
+    .filter((block): block is TextContent & { type: 'text' } => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+}
+
+/**
+ * Helper to extract content from SessionUpdate (discriminated union)
+ */
+const getUpdateContent = (update: SessionUpdate): ContentBlock | undefined => {
+  if (
+    update.sessionUpdate === 'user_message_chunk' ||
+    update.sessionUpdate === 'agent_message_chunk' ||
+    update.sessionUpdate === 'agent_thought_chunk'
+  ) {
+    return update.content
+  }
+  return undefined
+}
+
+/**
+ * Helper to extract tool call from SessionUpdate
+ */
+const getUpdateToolCall = (update: SessionUpdate): ToolCall | undefined => {
+  if (update.sessionUpdate === 'tool_call') {
+    return update
+  }
+  return undefined
+}
+
+/**
+ * Helper to extract plan from SessionUpdate
+ */
+const getUpdatePlan = (update: SessionUpdate): PlanEntry[] | undefined => {
+  if (update.sessionUpdate === 'plan') {
+    return update.entries
+  }
+  return undefined
+}
+
+/**
+ * Extracts text from session notifications.
+ *
+ * @remarks
+ * Streaming produces partial tokens that should be concatenated directly.
+ * Uses empty string join to preserve the original text structure.
+ *
+ * @param notifications - Array of session notifications
+ * @returns Concatenated text from all updates
+ */
+export const extractTextFromUpdates = (notifications: SessionNotification[]): string => {
+  const texts: string[] = []
+  for (const notification of notifications) {
+    const content = getUpdateContent(notification.update)
+    if (content && content.type === 'text') {
+      texts.push(content.text)
+    }
+  }
+  // Join without separator - streaming chunks should be concatenated directly
+  return texts.join('')
+}
+
+/**
+ * Extracts all tool calls from session notifications.
+ *
+ * @param notifications - Array of session notifications
+ * @returns Array of all tool calls
+ */
+export const extractToolCalls = (notifications: SessionNotification[]): ToolCall[] => {
+  const calls: ToolCall[] = []
+  for (const notification of notifications) {
+    const toolCall = getUpdateToolCall(notification.update)
+    if (toolCall) {
+      calls.push(toolCall)
+    }
+  }
+  return calls
+}
+
+/**
+ * Extracts the latest state of each tool call (deduplicated by toolCallId).
+ *
+ * @param notifications - Array of session notifications
+ * @returns Map of tool call ID to latest tool call state
+ */
+export const extractLatestToolCalls = (notifications: SessionNotification[]): Map<string, ToolCall> => {
+  const latest = new Map<string, ToolCall>()
+  for (const notification of notifications) {
+    const toolCall = getUpdateToolCall(notification.update)
+    if (toolCall) {
+      latest.set(toolCall.toolCallId, toolCall)
+    }
+  }
+  return latest
+}
+
+/**
+ * Extracts the latest plan from session notifications.
+ *
+ * @param notifications - Array of session notifications
+ * @returns Latest plan entries or undefined if no plan
+ */
+export const extractPlan = (notifications: SessionNotification[]): PlanEntry[] | undefined => {
+  // Plans are replaced entirely, so find the last one
+  for (let i = notifications.length - 1; i >= 0; i--) {
+    const notification = notifications[i]
+    if (notification) {
+      const plan = getUpdatePlan(notification.update)
+      if (plan) {
+        return plan
+      }
+    }
+  }
+  return undefined
+}
+
+// ============================================================================
+// Tool Call Utilities
+// ============================================================================
+
+/**
+ * Filters tool calls by status.
+ *
+ * @param toolCalls - Array of tool calls
+ * @param status - Status to filter by
+ * @returns Filtered tool calls
+ */
+export const filterToolCallsByStatus = (toolCalls: ToolCall[], status: ToolCall['status']): ToolCall[] => {
+  return toolCalls.filter((call) => call.status === status)
+}
+
+/**
+ * Filters tool calls by title.
+ *
+ * @param toolCalls - Array of tool calls
+ * @param title - Tool title to filter by
+ * @returns Filtered tool calls
+ */
+export const filterToolCallsByTitle = (toolCalls: ToolCall[], title: string): ToolCall[] => {
+  return toolCalls.filter((call) => call.title === title)
+}
+
+/**
+ * Checks if any tool calls have failed.
+ *
+ * @param toolCalls - Array of tool calls
+ * @returns True if any tool call has 'failed' status
+ */
+export const hasToolCallErrors = (toolCalls: ToolCall[]): boolean => {
+  return toolCalls.some((call) => call.status === 'failed')
+}
+
+/**
+ * Gets completed tool calls with their output content.
+ *
+ * @param toolCalls - Array of tool calls
+ * @returns Tool calls that completed with content
+ */
+export const getCompletedToolCallsWithContent = (
+  toolCalls: ToolCall[],
+): Array<ToolCall & { content: ToolCallContent[] }> => {
+  return toolCalls.filter(
+    (call): call is ToolCall & { content: ToolCallContent[] } =>
+      call.status === 'completed' && call.content !== undefined && call.content.length > 0,
+  )
+}
+
+// ============================================================================
+// Plan Utilities
+// ============================================================================
+
+/**
+ * Gets plan entries by status.
+ *
+ * @param plan - Array of plan entries
+ * @param status - Status to filter by
+ * @returns Filtered plan entries
+ */
+export const filterPlanByStatus = (plan: PlanEntry[], status: PlanEntry['status']): PlanEntry[] => {
+  return plan.filter((entry) => entry.status === status)
+}
+
+/**
+ * Calculates plan completion percentage.
+ *
+ * @param plan - Array of plan entries
+ * @returns Percentage of completed entries (0-100)
+ */
+export const getPlanProgress = (plan: PlanEntry[]): number => {
+  if (plan.length === 0) return 100
+  const completed = plan.filter((entry) => entry.status === 'completed').length
+  return Math.round((completed / plan.length) * 100)
+}

package/src/acp.constants.ts

@@ -0,0 +1,56 @@
+/**
+ * ACP protocol constants.
+ *
+ * @remarks
+ * Contains all constant values used across the ACP client implementation:
+ * - Protocol method names
+ * - Protocol version
+ * - JSON-RPC error codes
+ */
+
+// ============================================================================
+// Protocol Methods
+// ============================================================================
+
+/** ACP method names */
+export const ACP_METHODS = {
+  // Lifecycle
+  INITIALIZE: 'initialize',
+  SHUTDOWN: 'shutdown',
+
+  // Sessions
+  CREATE_SESSION: 'session/new',
+  LOAD_SESSION: 'session/load',
+  PROMPT: 'session/prompt',
+  CANCEL: 'session/cancel',
+  UPDATE: 'session/update',
+  REQUEST_PERMISSION: 'session/request_permission',
+  SET_MODEL: 'session/set_model',
+
+  // Protocol-level
+  CANCEL_REQUEST: '$/cancel_request',
+} as const
+
+// ============================================================================
+// Protocol Version
+// ============================================================================
+
+/** Current protocol version - SDK uses number type */
+export const ACP_PROTOCOL_VERSION = 1 as const
+
+// ============================================================================
+// JSON-RPC Error Codes
+// ============================================================================
+
+/** Standard JSON-RPC error codes */
+export const JSON_RPC_ERRORS = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  REQUEST_CANCELLED: -32800,
+} as const
+
+/** Default ACP Client Name */
+export const DEFAULT_ACP_CLIENT_NAME = 'plaited-acp-client'

package/src/acp.schemas.ts

@@ -0,0 +1,161 @@
+/**
+ * JSON-RPC 2.0 Zod schemas with runtime validation.
+ *
+ * @remarks
+ * These schemas provide runtime validation for JSON-RPC messages at the
+ * transport boundary. While the ACP SDK handles protocol-level types,
+ * the JSON-RPC framing layer is our responsibility since we implement
+ * a custom stdio transport.
+ *
+ * The schemas follow JSON-RPC 2.0 specification:
+ * - Requests have `id` and `method`
+ * - Notifications have `method` but no `id`
+ * - Responses have `id` and either `result` or `error`
+ */
+
+import type { RequestPermissionRequest, SessionNotification } from '@agentclientprotocol/sdk'
+import { z } from 'zod'
+
+// ============================================================================
+// Inlined Type Utilities
+// ============================================================================
+
+/** Precise type detection beyond typeof operator */
+const trueTypeOf = (obj?: unknown): string => Object.prototype.toString.call(obj).slice(8, -1).toLowerCase()
+
+/** Type guard for precise type checking with TypeScript narrowing */
+const isTypeOf = <T>(obj: unknown, type: string): obj is T => trueTypeOf(obj) === type
+
+// ============================================================================
+// JSON-RPC Base Schemas
+// ============================================================================
+
+/** JSON-RPC version literal */
+const JsonRpcVersionSchema = z.literal('2.0')
+
+/** Request/response identifier */
+const RequestIdSchema = z.union([z.string(), z.number()])
+
+/**
+ * JSON-RPC 2.0 error object schema.
+ *
+ * @remarks
+ * Standard error codes:
+ * - `-32700`: Parse error
+ * - `-32600`: Invalid request
+ * - `-32601`: Method not found
+ * - `-32602`: Invalid params
+ * - `-32603`: Internal error
+ * - `-32800`: Request cancelled (ACP extension)
+ */
+export const JsonRpcErrorSchema = z.object({
+  code: z.number(),
+  message: z.string(),
+  data: z.unknown().optional(),
+})
+
+/** JSON-RPC 2.0 request schema */
+export const JsonRpcRequestSchema = z.object({
+  jsonrpc: JsonRpcVersionSchema,
+  id: RequestIdSchema,
+  method: z.string(),
+  params: z.unknown().optional(),
+})
+
+/** JSON-RPC 2.0 notification schema (no id, no response expected) */
+export const JsonRpcNotificationSchema = z.object({
+  jsonrpc: JsonRpcVersionSchema,
+  method: z.string(),
+  params: z.unknown().optional(),
+})
+
+/** JSON-RPC 2.0 success response schema */
+export const JsonRpcSuccessResponseSchema = z.object({
+  jsonrpc: JsonRpcVersionSchema,
+  id: RequestIdSchema,
+  result: z.unknown(),
+})
+
+/** JSON-RPC 2.0 error response schema */
+export const JsonRpcErrorResponseSchema = z.object({
+  jsonrpc: JsonRpcVersionSchema,
+  id: z.union([RequestIdSchema, z.null()]),
+  error: JsonRpcErrorSchema,
+})
+
+/** Union of all JSON-RPC response types */
+export const JsonRpcResponseSchema = z.union([JsonRpcSuccessResponseSchema, JsonRpcErrorResponseSchema])
+
+/**
+ * Union of all JSON-RPC message types.
+ *
+ * @remarks
+ * Use `safeParse` at transport boundaries for runtime validation.
+ * See transport tests for usage patterns.
+ */
+export const JsonRpcMessageSchema = z.union([JsonRpcRequestSchema, JsonRpcNotificationSchema, JsonRpcResponseSchema])
+
+// ============================================================================
+// Inferred Types
+// ============================================================================
+
+/** JSON-RPC 2.0 error object */
+export type JsonRpcError = z.infer<typeof JsonRpcErrorSchema>
+
+/** JSON-RPC 2.0 request structure */
+export type JsonRpcRequest<T = unknown> = Omit<z.infer<typeof JsonRpcRequestSchema>, 'params'> & {
+  params?: T
+}
+
+/** JSON-RPC 2.0 notification structure (no id, no response expected) */
+export type JsonRpcNotification<T = unknown> = Omit<z.infer<typeof JsonRpcNotificationSchema>, 'params'> & {
+  params?: T
+}
+
+/** JSON-RPC 2.0 success response */
+export type JsonRpcSuccessResponse<T = unknown> = Omit<z.infer<typeof JsonRpcSuccessResponseSchema>, 'result'> & {
+  result: T
+}
+
+/** JSON-RPC 2.0 error response */
+export type JsonRpcErrorResponse = z.infer<typeof JsonRpcErrorResponseSchema>
+
+/** Union of all JSON-RPC response types */
+export type JsonRpcResponse<T = unknown> = JsonRpcSuccessResponse<T> | JsonRpcErrorResponse
+
+/** Union of all JSON-RPC message types */
+export type JsonRpcMessage<T = unknown> = JsonRpcRequest<T> | JsonRpcNotification<T> | JsonRpcResponse<T>
+
+// ============================================================================
+// ACP SDK Type Schemas
+// ============================================================================
+
+/**
+ * These schemas use z.custom() to validate SDK types at runtime.
+ * They validate only the fields we actually use, keeping SDK types
+ * as the source of truth while adding runtime safety.
+ */
+
+/** Type guard for object shape validation */
+const isRecord = (val: unknown): val is Record<string, unknown> => isTypeOf<Record<string, unknown>>(val, 'object')
+
+/**
+ * Schema for session update notifications.
+ *
+ * @remarks
+ * Validates `sessionId` and `update` fields used in notification handling.
+ */
+export const SessionNotificationSchema = z.custom<SessionNotification>(
+  (val): val is SessionNotification =>
+    isRecord(val) && 'sessionId' in val && typeof val.sessionId === 'string' && 'update' in val && isRecord(val.update),
+)
+
+/**
+ * Schema for permission requests from agent.
+ *
+ * @remarks
+ * Validates `options` array used in permission handling.
+ */
+export const RequestPermissionRequestSchema = z.custom<RequestPermissionRequest>(
+  (val): val is RequestPermissionRequest => isRecord(val) && 'options' in val && Array.isArray(val.options),
+)

package/src/acp.ts

@@ -0,0 +1,27 @@
+/**
+ * @plaited/acp-harness - ACP client and evaluation harness for TypeScript/Bun projects.
+ *
+ * @remarks
+ * This module provides a headless ACP client for programmatic agent interaction,
+ * optimized for testing, evaluation, and training data generation.
+ *
+ * **Primary exports:**
+ * - `createACPClient` - Factory for headless ACP client instances
+ * - `createPrompt`, `createPromptWithFiles`, `createPromptWithImage` - Prompt builders
+ * - `summarizeResponse` - Response analysis utility
+ *
+ * **Re-exports from acp-utils (for advanced usage):**
+ * - Content builders: `createTextContent`, `createImageContent`, `createAudioContent`,
+ *   `createResourceLink`, `createTextResource`, `createBlobResource`
+ * - Content extractors: `extractText`, `extractTextFromUpdates`, `extractToolCalls`,
+ *   `extractLatestToolCalls`, `extractPlan`
+ * - Tool call utilities: `filterToolCallsByStatus`, `filterToolCallsByTitle`,
+ *   `hasToolCallErrors`, `getCompletedToolCallsWithContent`
+ * - Plan utilities: `filterPlanByStatus`, `getPlanProgress`
+ *
+ * @packageDocumentation
+ */
+
+export * from './acp-client.ts'
+export * from './acp-helpers.ts'
+export * from './acp-utils.ts'

package/src/acp.types.ts

@@ -0,0 +1,28 @@
+/**
+ * ACP type definitions.
+ *
+ * @remarks
+ * This module contains types specific to the ACP client implementation.
+ * For SDK types (ToolCall, ContentBlock, SessionNotification, etc.), import
+ * directly from `@agentclientprotocol/sdk`.
+ *
+ * For runtime validation of JSON-RPC messages, import Zod schemas from
+ * `./acp.schemas.ts`.
+ *
+ * For protocol constants, import from `./acp.constants.ts`.
+ */
+
+import type { SessionId } from '@agentclientprotocol/sdk'
+
+// ============================================================================
+// Session Types
+// ============================================================================
+
+/**
+ * Session object returned from session creation.
+ * Contains the session ID for subsequent operations.
+ */
+export type Session = {
+  id: SessionId
+  _meta?: { [key: string]: unknown } | null
+}