@panagos/jojoscript 0.9.3 → 1.0.0

package/src/pipeline-parser.js

@@ -234,16 +234,38 @@ function parsePipelineStatement(source, statementStart, statementEnd) {
       throw new SyntaxError(`Empty pipeline stage in:\n${statement}`)
     }
 
-    stages.push(parseStage(statement, stageTokens))
+    stages.push(parseStageWithId(statement, stageTokens))
     i = stageEnd - 1
   }
 
+  const ids = stages.map(stage => stage.id).filter(Boolean)
+  const duplicate = ids.find((id, index) => ids.indexOf(id) !== index)
+  if (duplicate) throw new SyntaxError(`Duplicate stage id: @${duplicate}`)
+
   const prefixTokens = tokens.slice(0, inputStartIndex)
   const prefix = prefixTokens.length ? text(statement, prefixTokens).trim() : ''
 
   return { expression, stages, prefix }
 }
 
+export const STAGE_ID = /^[A-Za-z_][\w-]*$/
+
+// A trailing `@id` labels a stage without changing what it computes.
+function parseStageWithId(source, tokens) {
+  let depth = 0
+  for (let i = 0; i < tokens.length; i++) {
+    const value = tokens[i].value
+    if (value === '(' || value === '[' || value === '{') depth++
+    else if (value === ')' || value === ']' || value === '}') depth--
+    else if (value === '@' && depth === 0) {
+      const id = source.slice(tokens[i].end, tokens[tokens.length - 1].end).trim()
+      if (!STAGE_ID.test(id)) throw new SyntaxError(`Invalid stage id: @${id}`)
+      return { ...parseStage(source, tokens.slice(0, i)), id }
+    }
+  }
+  return parseStage(source, tokens)
+}
+
 function metaLiteral(pipelineId, nodeId, type, extra = {}) {
   return JSON.stringify({ id: nodeId, pipelineId, type, ...extra })
 }
@@ -312,7 +334,7 @@ export function emitPipeline(pipeline, options = {}) {
 
   const stagesWithIds = pipeline.stages.map((stage, index) => ({
     ...stage,
-    nodeId: `node-${index + 1}`
+    nodeId: stage.id ?? `node-${index + 1}`
   }))
 
   const stages = fuseRetryStages(stagesWithIds, pipelineId)

package/src/pipeline-plan.js

@@ -0,0 +1,203 @@
+import { compile } from './compiler.js'
+import { findAllPipelines, STAGE_ID } from './pipeline-parser.js'
+import { computePipelineId } from './pipeline-hash.js'
+import { inferPipelineName } from './pipeline-explain.js'
+import { transformNamedPipelines } from './named-pipelines.js'
+
+const PLAN_VERSION = 1
+
+const EXPRESSION_STAGES = new Set([
+  'map', 'filter', 'flatMap', 'tap', 'mapAsync', 'filterAsync', 'find', 'some',
+  'every', 'sortBy', 'distinctBy', 'groupBy', 'partition', 'catch'
+])
+
+const INTEGER_STAGE_FIELDS = { parallel: 'concurrency', batch: 'size' }
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/
+const STAGE_NAME = /^\.?[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/
+const SIMPLE_STRING = /^(["'])([^"'\\]*)\1$/
+
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+
+class PlanValidationError extends Error {
+  constructor(message) {
+    super(`Invalid plan: ${message}`)
+    this.name = 'PlanValidationError'
+  }
+}
+
+/*
+ * The canonical, machine-readable form of every pipeline in `source`.
+ * Arguments stay as source text, so the plan describes computation without
+ * evaluating it and `planToJojo` can reproduce it.
+ */
+export function planPipelines(jojoSource) {
+  const source = transformNamedPipelines(jojoSource)
+  return {
+    version: PLAN_VERSION,
+    pipelines: findAllPipelines(source).map(pipeline => ({
+      pipeline: inferPipelineName(source, pipeline),
+      id: computePipelineId(pipeline),
+      stages: [{ type: 'source', expression: pipeline.expression }, ...pipeline.stages.map(planStage)]
+    }))
+  }
+}
+
+function planStage(stage) {
+  const planned = plannedStage(stage)
+  return stage.id ? { ...planned, id: stage.id } : planned
+}
+
+function plannedStage(stage) {
+  const { name: type, args } = stage
+  const integerField = INTEGER_STAGE_FIELDS[type]
+
+  if (integerField && args.length === 1 && /^[1-9]\d*$/.test(args[0])) {
+    return { type, [integerField]: Number(args[0]) }
+  }
+  if (type === 'checkpoint' && args.length === 1 && SIMPLE_STRING.test(args[0])) {
+    return { type, name: args[0].match(SIMPLE_STRING)[2] }
+  }
+  if (EXPRESSION_STAGES.has(type) && args.length === 1) {
+    return { type, expression: args[0] }
+  }
+  if (stage.propertyCall || args.length) return { type, args }
+  return { type }
+}
+
+export function planToJojo(plan) {
+  validatePlan(plan)
+
+  return plan.pipelines.map((pipeline, index) => {
+    const source = emitPipeline(pipeline)
+    assertCompiles(source, `pipelines[${index}]`)
+    return source
+  }).join('\n\n') + '\n'
+}
+
+function emitPipeline({ pipeline, stages: [source, ...stages] }) {
+  const head = pipeline ? `${pipeline} := ${source.expression}` : source.expression
+  return [head, ...stages.map(stage => `  |> ${emitStage(stage)}`)].join('\n')
+}
+
+function emitStage(stage) {
+  const args = stageArgs(stage)
+  const call = args ? `${stage.type}(${args.join(', ')})` : stage.type
+  return stage.id ? `${call} @${stage.id}` : call
+}
+
+function stageArgs(stage) {
+  if ('expression' in stage) return [stage.expression]
+  if ('name' in stage) return [JSON.stringify(stage.name)]
+  if ('concurrency' in stage) return [String(stage.concurrency)]
+  if ('size' in stage) return [String(stage.size)]
+  return stage.args ?? null
+}
+
+// Building the function only parses the generated code; it is never called.
+function assertCompiles(source, path) {
+  const compiled = compile(source).replace(/^import .*\n/, '')
+  try {
+    new AsyncFunction(compiled)
+  } catch (error) {
+    throw new PlanValidationError(`${path} does not compile to valid JavaScript (${error.message})`)
+  }
+}
+
+function validatePlan(plan) {
+  if (!isObject(plan)) throw new PlanValidationError('plan must be an object')
+  assertKnownFields(plan, ['version', 'pipelines'], '')
+  if (plan.version !== PLAN_VERSION) throw new PlanValidationError(`version must be ${PLAN_VERSION}`)
+  if (!Array.isArray(plan.pipelines)) throw new PlanValidationError('pipelines must be an array')
+
+  const names = new Set()
+  plan.pipelines.forEach((pipeline, index) => {
+    const path = `pipelines[${index}]`
+    if (!isObject(pipeline)) throw new PlanValidationError(`${path} must be an object`)
+    assertKnownFields(pipeline, ['pipeline', 'id', 'stages'], path)
+
+    if (pipeline.pipeline !== null && !IDENTIFIER.test(pipeline.pipeline ?? '')) {
+      throw new PlanValidationError(`${path}.pipeline must be an identifier or null`)
+    }
+    if (names.has(pipeline.pipeline)) {
+      throw new PlanValidationError(`${path}.pipeline "${pipeline.pipeline}" is already declared`)
+    }
+    if (pipeline.pipeline) names.add(pipeline.pipeline)
+
+    if (!Array.isArray(pipeline.stages) || !pipeline.stages.length) {
+      throw new PlanValidationError(`${path}.stages must be a non-empty array`)
+    }
+    const stageIds = new Set()
+    pipeline.stages.forEach((stage, stageIndex) => {
+      const stagePath = `${path}.stages[${stageIndex}]`
+      validateStage(stage, stageIndex, stagePath)
+      if (stage.id === undefined) return
+      if (stageIds.has(stage.id)) throw new PlanValidationError(`${stagePath}.id "${stage.id}" is already used in this pipeline`)
+      stageIds.add(stage.id)
+    })
+  })
+}
+
+function validateStage(stage, index, path) {
+  if (!isObject(stage)) throw new PlanValidationError(`${path} must be an object`)
+
+  if (index === 0) {
+    if (stage.type !== 'source') throw new PlanValidationError(`${path} must be a source stage`)
+    assertKnownFields(stage, ['type', 'expression'], path)
+    assertNonEmptyString(stage.expression, `${path}.expression`)
+    return
+  }
+
+  if (stage.type === 'source') throw new PlanValidationError(`${path} must not be a source stage`)
+  if (typeof stage.type !== 'string' || !STAGE_NAME.test(stage.type)) {
+    throw new PlanValidationError(`${path}.type must be a stage name such as "map" or ".trim"`)
+  }
+
+  const fields = allowedFields(stage.type)
+  assertKnownFields(stage, ['type', 'id', ...fields], path)
+  if (stage.id !== undefined && (typeof stage.id !== 'string' || !STAGE_ID.test(stage.id))) {
+    throw new PlanValidationError(`${path}.id must be a stage id such as "enrich"`)
+  }
+
+  const used = fields.filter(field => field in stage)
+  if (used.length > 1) {
+    throw new PlanValidationError(`${path} must use only one of ${used.map(field => `"${field}"`).join(' or ')}`)
+  }
+
+  const [field] = used
+  if (field === 'concurrency' || field === 'size') {
+    if (!Number.isInteger(stage[field]) || stage[field] <= 0) {
+      throw new PlanValidationError(`${path}.${field} must be a positive integer`)
+    }
+  } else if (field === 'args') {
+    if (!Array.isArray(stage.args) || !stage.args.every(arg => typeof arg === 'string' && arg.trim())) {
+      throw new PlanValidationError(`${path}.args must be an array of non-empty strings`)
+    }
+  } else if (field) {
+    assertNonEmptyString(stage[field], `${path}.${field}`)
+  }
+}
+
+function allowedFields(type) {
+  if (INTEGER_STAGE_FIELDS[type]) return [INTEGER_STAGE_FIELDS[type], 'args']
+  if (type === 'checkpoint') return ['name', 'args']
+  if (EXPRESSION_STAGES.has(type)) return ['expression', 'args']
+  return ['args']
+}
+
+function assertKnownFields(value, fields, path) {
+  const unknown = Object.keys(value).find(key => !fields.includes(key))
+  if (unknown) {
+    throw new PlanValidationError(path ? `${path} has unknown field "${unknown}"` : `unknown field "${unknown}"`)
+  }
+}
+
+function assertNonEmptyString(value, path) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new PlanValidationError(`${path} must be a non-empty string`)
+  }
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/purity.js

@@ -0,0 +1,101 @@
+import { maskNonCode } from './lexer.js'
+import { findEffectDeclarations } from './effect-parser.js'
+
+const PURITY_DECLARATION = /^([ \t]*)(export[ \t]+)?(async[ \t]+)?(pure|effectful)[ \t]+(async[ \t]+)?fn[ \t]+([A-Za-z_$][\w$]*)/gm
+
+function lineAt(source, offset) {
+  return source.slice(0, offset).split('\n').length
+}
+
+function matchingBrace(code, openIndex) {
+  let depth = 0
+  for (let i = openIndex; i < code.length; i++) {
+    if (code[i] === '{' || code[i] === '(') depth++
+    else if ((code[i] === '}' || code[i] === ')') && --depth === 0) return i
+  }
+  return code.length
+}
+
+/*
+ * Body bounds come from the masked source so braces inside strings and
+ * comments never end a body early.
+ */
+function bodyRange(code, nameEnd) {
+  const paramsOpen = code.indexOf('(', nameEnd)
+  const paramsClose = matchingBrace(code, paramsOpen)
+  const rest = code.slice(paramsClose + 1)
+  const head = rest.search(/[{=]/)
+  const start = paramsClose + 1 + head
+
+  if (code[start] === '=') {
+    const lineEnd = code.indexOf('\n', start)
+    return { start, end: lineEnd === -1 ? code.length : lineEnd }
+  }
+  return { start, end: matchingBrace(code, start) + 1 }
+}
+
+export function findPurityDeclarations(source) {
+  const code = maskNonCode(source)
+  const regex = new RegExp(PURITY_DECLARATION.source, PURITY_DECLARATION.flags)
+  const declarations = []
+  let match
+
+  while ((match = regex.exec(code))) {
+    const nameEnd = match.index + match[0].length
+    declarations.push({
+      name: match[6],
+      purity: match[4],
+      line: lineAt(source, match.index),
+      body: bodyRange(code, nameEnd)
+    })
+  }
+
+  return declarations
+}
+
+/*
+ * Static and name-based: a pure function may not mention a declared effect
+ * or an effectful function outside strings, comments, and property access.
+ */
+export function findPurityViolations(source) {
+  const code = maskNonCode(source)
+  const declarations = findPurityDeclarations(source)
+  const forbidden = [
+    ...findEffectDeclarations(source).map(declaration => ({ name: declaration.name, kind: 'effect' })),
+    ...declarations
+      .filter(declaration => declaration.purity === 'effectful')
+      .map(declaration => ({ name: declaration.name, kind: 'effectful function' }))
+  ]
+
+  return declarations
+    .filter(declaration => declaration.purity === 'pure')
+    .flatMap(declaration => {
+      const body = code.slice(declaration.body.start, declaration.body.end)
+
+      return forbidden
+        .filter(({ name }) => name !== declaration.name)
+        .map(({ name, kind }) => ({ kind, name, index: body.search(new RegExp(`(?<![.\\w$])${name}(?![\\w$])`)) }))
+        .filter(({ index }) => index !== -1)
+        .map(({ name, kind, index }) => ({
+          function: declaration.name,
+          uses: name,
+          kind,
+          line: lineAt(source, declaration.body.start + index)
+        }))
+    })
+    .sort((a, b) => a.line - b.line)
+}
+
+export function transformPurityModifiers(source) {
+  const violation = findPurityViolations(source)[0]
+  if (violation) {
+    throw new SyntaxError(`pure fn "${violation.function}" uses ${violation.kind} "${violation.uses}" (line ${violation.line})`)
+  }
+
+  const code = maskNonCode(source)
+  return source.replace(PURITY_DECLARATION, (match, ...args) => {
+    const offset = args[args.length - 2]
+    if (code.slice(offset, offset + match.length) !== match) return match
+    return match.replace(/(pure|effectful)[ \t]+(?=(?:async[ \t]+)?fn[ \t])/, '')
+  })
+}

package/src/runtime/a2a.js

@@ -0,0 +1,322 @@
+const TERMINAL_TASK_STATES = new Set([
+  'TASK_STATE_COMPLETED',
+  'TASK_STATE_FAILED',
+  'TASK_STATE_CANCELED',
+  'TASK_STATE_REJECTED',
+  'TASK_STATE_INPUT_REQUIRED',
+  'TASK_STATE_AUTH_REQUIRED'
+])
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function taskIdFrom(task) {
+  const id = typeof task === 'string' ? task : task?.id
+  if (typeof id !== 'string' || !id) {
+    throw new TypeError('An A2A task id is required')
+  }
+  return id
+}
+
+function abortError(reason) {
+  if (reason instanceof A2AError) return reason
+  return new A2AError('A2A operation was aborted', {
+    code: 'ABORTED',
+    cause: reason
+  })
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError(signal.reason)
+}
+
+function waitForDelay(delayMs, signal) {
+  throwIfAborted(signal)
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, delayMs)
+    function done() {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }
+    function onAbort() {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      reject(abortError(signal.reason))
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+function createWaitSignal(signal, timeoutMs, taskId) {
+  const controller = new AbortController()
+  const abort = () => controller.abort(signal.reason)
+  const timer = setTimeout(() => {
+    controller.abort(new A2AError(`Timed out waiting for A2A task "${taskId}"`, {
+      code: 'TIMEOUT'
+    }))
+  }, timeoutMs)
+
+  signal?.addEventListener('abort', abort, { once: true })
+  if (signal?.aborted) abort()
+
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
+    }
+  }
+}
+
+export class A2AError extends Error {
+  constructor(message, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'A2AError'
+    this.code = options.code
+    this.data = options.data
+    this.status = options.status
+    this.remoteCode = options.remoteCode
+  }
+}
+
+export class A2AClient {
+  constructor(agentUrl, options = {}) {
+    if (typeof agentUrl !== 'string' || !agentUrl) {
+      throw new TypeError('An A2A agent URL is required')
+    }
+    if (options.headers !== undefined && !isObject(options.headers)) {
+      throw new TypeError('A2A headers must be an object')
+    }
+    if (options.bearerToken !== undefined &&
+      (typeof options.bearerToken !== 'string' || !options.bearerToken)) {
+      throw new TypeError('A2A bearerToken must be a non-empty string')
+    }
+
+    this.agentUrl = new URL(agentUrl)
+    this.fetch = options.fetch ?? globalThis.fetch
+    this.headers = {
+      ...(options.bearerToken ? { authorization: `Bearer ${options.bearerToken}` } : {}),
+      ...(options.headers ?? {})
+    }
+    this.agentCard = null
+    this.endpoint = null
+    this.requestId = 0
+
+    if (typeof this.fetch !== 'function') {
+      throw new TypeError('A fetch implementation is required')
+    }
+  }
+
+  async discover(options = {}) {
+    throwIfAborted(options.signal)
+
+    const cardUrl = new URL('/.well-known/agent-card.json', this.agentUrl)
+    const response = await this.#fetch(cardUrl.href, {
+      method: 'GET',
+      headers: this.headers,
+      signal: options.signal
+    }, 'Agent Card request')
+    if (!response.ok) {
+      throw new A2AError(`A2A Agent Card request failed with HTTP ${response.status}`, {
+        code: 'DISCOVERY_HTTP_ERROR',
+        status: response.status
+      })
+    }
+
+    const card = await this.#readJson(response, 'A2A Agent Card', 'INVALID_AGENT_CARD')
+    throwIfAborted(options.signal)
+    if (!isObject(card)) {
+      throw new A2AError('A2A Agent Card response must be a JSON object', {
+        code: 'INVALID_AGENT_CARD'
+      })
+    }
+
+    const jsonRpcInterface = card.supportedInterfaces?.find(
+      item => isObject(item) && item.protocolBinding === 'JSONRPC' && typeof item.url === 'string'
+    )
+    const endpoint = jsonRpcInterface?.url
+      ?? (card.preferredTransport === 'JSONRPC' ? card.url : null)
+
+    if (typeof endpoint !== 'string' || !endpoint) {
+      throw new A2AError('A2A Agent Card does not advertise a JSON-RPC interface', {
+        code: 'UNSUPPORTED_INTERFACE'
+      })
+    }
+
+    let endpointUrl
+    try {
+      endpointUrl = new URL(endpoint, cardUrl)
+    } catch (error) {
+      throw new A2AError('A2A Agent Card contains an invalid JSON-RPC endpoint', {
+        code: 'INVALID_AGENT_CARD',
+        cause: error
+      })
+    }
+    if (!['http:', 'https:'].includes(endpointUrl.protocol) ||
+      endpointUrl.username || endpointUrl.password) {
+      throw new A2AError('A2A Agent Card contains an unsafe JSON-RPC endpoint', {
+        code: 'INVALID_AGENT_CARD'
+      })
+    }
+
+    this.agentCard = card
+    this.endpoint = endpointUrl
+    return card
+  }
+
+  async sendMessage(message, configuration, options = {}) {
+    if (!isObject(message)) {
+      throw new TypeError('A2A message must be an object')
+    }
+
+    const params = { message }
+    if (configuration !== undefined) params.configuration = configuration
+    return this.#request('SendMessage', params, options)
+  }
+
+  async getTask(task, options = {}) {
+    const params = typeof task === 'string' ? { id: task } : task
+    taskIdFrom(params)
+    return this.#request('GetTask', params, options)
+  }
+
+  async cancelTask(task, options = {}) {
+    const id = taskIdFrom(task)
+    return this.#request('CancelTask', { id }, options)
+  }
+
+  async waitForTask(taskOrId, options = {}) {
+    const taskId = taskIdFrom(taskOrId)
+    const pollIntervalMs = options.pollIntervalMs ?? 1000
+    const maxPollIntervalMs = options.maxPollIntervalMs ?? 30000
+    const backoffMultiplier = options.backoffMultiplier ?? 1.5
+    const timeoutMs = options.timeoutMs ?? 300000
+
+    if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 0) {
+      throw new TypeError('pollIntervalMs must be a non-negative number')
+    }
+    if (!Number.isFinite(maxPollIntervalMs) || maxPollIntervalMs < pollIntervalMs) {
+      throw new TypeError('maxPollIntervalMs must be at least pollIntervalMs')
+    }
+    if (!Number.isFinite(backoffMultiplier) || backoffMultiplier < 1) {
+      throw new TypeError('backoffMultiplier must be at least 1')
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new TypeError('timeoutMs must be a positive number')
+    }
+
+    const waiting = createWaitSignal(options.signal, timeoutMs, taskId)
+    try {
+      let task = typeof taskOrId === 'string'
+        ? await this.getTask(taskId, { signal: waiting.signal })
+        : taskOrId
+      let intervalMs = pollIntervalMs
+
+      while (!TERMINAL_TASK_STATES.has(task?.status?.state)) {
+        if (!isObject(task) || !isObject(task.status) || typeof task.status.state !== 'string') {
+          throw new A2AError(`A2A task "${taskId}" has an invalid status`, {
+            code: 'INVALID_TASK'
+          })
+        }
+
+        await waitForDelay(intervalMs, waiting.signal)
+        task = await this.getTask(taskId, { signal: waiting.signal })
+        intervalMs = Math.min(maxPollIntervalMs, intervalMs * backoffMultiplier)
+      }
+
+      return task
+    } finally {
+      waiting.cleanup()
+    }
+  }
+
+  async #fetch(url, options, description) {
+    try {
+      const response = await this.fetch(url, options)
+      throwIfAborted(options.signal)
+      return response
+    } catch (error) {
+      if (options.signal?.aborted) throw abortError(options.signal.reason)
+      if (error instanceof A2AError) throw error
+      throw new A2AError(`A2A ${description} failed`, {
+        code: 'NETWORK_ERROR',
+        cause: error
+      })
+    }
+  }
+
+  async #readJson(response, description, code) {
+    try {
+      return await response.json()
+    } catch (error) {
+      throw new A2AError(`${description} response is not valid JSON`, {
+        code,
+        cause: error
+      })
+    }
+  }
+
+  async #request(method, params, options = {}) {
+    if (!this.endpoint) {
+      throw new A2AError('Call discover() before making A2A requests', {
+        code: 'NOT_DISCOVERED'
+      })
+    }
+    throwIfAborted(options.signal)
+
+    const requestId = ++this.requestId
+    const response = await this.#fetch(this.endpoint.href, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...this.headers
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: requestId,
+        method,
+        params
+      }),
+      signal: options.signal
+    }, `${method} request`)
+    if (!response.ok) {
+      throw new A2AError(`A2A ${method} request failed with HTTP ${response.status}`, {
+        code: 'HTTP_ERROR',
+        status: response.status
+      })
+    }
+
+    const payload = await this.#readJson(response, `A2A ${method}`, 'INVALID_RPC_RESPONSE')
+    throwIfAborted(options.signal)
+    if (
+      !isObject(payload)
+      || payload.jsonrpc !== '2.0'
+      || payload.id !== requestId
+      || (!Object.hasOwn(payload, 'result') && !Object.hasOwn(payload, 'error'))
+    ) {
+      throw new A2AError(`Invalid JSON-RPC response for A2A method "${method}"`, {
+        code: 'INVALID_RPC_RESPONSE'
+      })
+    }
+    if (payload.error) {
+      if (!isObject(payload.error)) {
+        throw new A2AError(`Invalid JSON-RPC error for A2A method "${method}"`, {
+          code: 'INVALID_RPC_RESPONSE'
+        })
+      }
+      throw new A2AError(payload.error.message ?? 'A2A JSON-RPC request failed', {
+        code: 'REMOTE_ERROR',
+        remoteCode: payload.error.code,
+        data: payload.error.data
+      })
+    }
+
+    return payload.result
+  }
+}
+
+export function createA2AClient(agentUrl, options = {}) {
+  return new A2AClient(agentUrl, options)
+}