@jigging/agent-method 0.0.0 → 0.1.0-alpha.3

package/src/api.ts

@@ -0,0 +1,191 @@
+import { AgentMethodError } from './errors.js'
+import type { AgentTransportResult, PreparedAgent } from './index.js'
+import { canonicalJson, type JsonObject } from './json.js'
+import { projectResponseSchema } from './schema.js'
+import { ordinaryRecord, snapshot } from './values.js'
+
+type Api = 'chat-completions' | 'responses'
+
+/** One finite text request. API settings choose syntax, never endpoint authority. */
+export function prepareApiRequest(
+  prepared: PreparedAgent,
+  settings: unknown,
+): { readonly api: Api; readonly body: JsonObject } {
+  const value = ordinaryRecord(snapshot(settings, 'INVALID_INPUT'))
+  if (
+    value === undefined ||
+    Object.keys(value).some(
+      (key) => !['model', 'maxCompletionTokens', 'api', 'structuredOutput'].includes(key),
+    ) ||
+    typeof value.model !== 'string' ||
+    value.model.trim().length === 0 ||
+    value.model.length > 256
+  ) {
+    throw new AgentMethodError('INVALID_INPUT', 'Configure the Agent model in Binding settings')
+  }
+  const tokens = Object.hasOwn(value, 'maxCompletionTokens') ? value.maxCompletionTokens : 4096
+  if (!Number.isSafeInteger(tokens) || typeof tokens !== 'number' || tokens < 1 || tokens > 65536)
+    throw new AgentMethodError('INVALID_INPUT', 'maxCompletionTokens must be between 1 and 65536')
+  const api = Object.hasOwn(value, 'api') ? value.api : 'chat-completions'
+  if (api !== 'chat-completions' && api !== 'responses')
+    throw new AgentMethodError('INVALID_INPUT', 'api must be chat-completions or responses')
+  const structuredOutput = Object.hasOwn(value, 'structuredOutput')
+    ? value.structuredOutput
+    : 'prompt'
+  if (structuredOutput !== 'prompt' && structuredOutput !== 'json-schema')
+    throw new AgentMethodError('INVALID_INPUT', 'structuredOutput must be prompt or json-schema')
+  const format =
+    structuredOutput === 'json-schema' && prepared.request.responseSchema !== undefined
+      ? {
+          type: 'json_schema',
+          name: 'flow_agent_result',
+          schema: projectResponseSchema(prepared.request.responseSchema),
+          strict: true,
+        }
+      : undefined
+  const body: JsonObject =
+    api === 'responses'
+      ? {
+          model: value.model,
+          input: prepared.request.prompt,
+          max_output_tokens: tokens,
+          stream: false,
+          store: false,
+          ...(format === undefined ? {} : { text: { format } }),
+        }
+      : {
+          model: value.model,
+          messages: [{ role: 'user', content: prepared.request.prompt }],
+          max_completion_tokens: tokens,
+          n: 1,
+          stream: false,
+          store: false,
+          ...(format === undefined
+            ? {}
+            : {
+                response_format: {
+                  type: format.type,
+                  json_schema: { name: format.name, schema: format.schema, strict: format.strict },
+                },
+              }),
+        }
+  if (canonicalJson(body).byteLength > 8_388_608)
+    throw new AgentMethodError(
+      'RESOURCE_EXHAUSTED',
+      'Rendered request exceeds the 8 MiB HTTP body ceiling',
+    )
+  return { api, body }
+}
+
+/** Interpret only complete HTTP evidence. Never echo an arbitrary provider error body. */
+export function parseApiResult(result: unknown, api: Api): AgentTransportResult {
+  const record = ordinaryRecord(snapshot(result, 'INVALID_RESULT'))
+  const http = record === undefined ? undefined : ordinaryRecord(record.output)
+  if (
+    record?.outcome !== 'done' ||
+    http === undefined ||
+    typeof http.status !== 'number' ||
+    !Number.isInteger(http.status) ||
+    http.status < 200 ||
+    http.status > 599 ||
+    !Object.hasOwn(http, 'body')
+  )
+    return invalid('HTTP slot returned invalid response evidence')
+  if (http.status !== 200)
+    return invalid(`Agent endpoint returned HTTP ${http.status}; no automatic retry was attempted`)
+  if (canonicalJson(http.body as JsonObject).byteLength > 12_582_912)
+    throw new AgentMethodError('RESOURCE_EXHAUSTED', 'Agent HTTP response exceeds 12 MiB')
+  const body = ordinaryRecord(http.body)
+  if (api === 'responses') return responsesResult(body)
+  return chatResult(body)
+}
+
+function chatResult(body: Record<string, unknown> | undefined): AgentTransportResult {
+  const choices = body?.choices
+  if (body?.object !== 'chat.completion' || !Array.isArray(choices) || choices.length !== 1)
+    return invalid('Expected one complete Chat Completions choice')
+  const choice = ordinaryRecord(choices[0])
+  const message = ordinaryRecord(choice?.message)
+  if (
+    choice?.index !== 0 ||
+    message?.role !== 'assistant' ||
+    (message.tool_calls !== undefined &&
+      message.tool_calls !== null &&
+      !(Array.isArray(message.tool_calls) && message.tool_calls.length === 0)) ||
+    (message.function_call !== undefined && message.function_call !== null)
+  )
+    return invalid('Agent returned an unsupported message or tool request')
+  const content = message.content
+  const refusal = message.refusal
+  if (
+    (content !== null && typeof content !== 'string') ||
+    (refusal !== undefined && refusal !== null && typeof refusal !== 'string')
+  )
+    return invalid('Agent response must contain text or an explicit refusal')
+  const reason = choice.finish_reason
+  if (reason !== 'stop' && reason !== 'length' && reason !== 'content_filter')
+    return invalid('Agent response has no supported terminal stop reason')
+  const refused = reason === 'content_filter' || (typeof refusal === 'string' && refusal.length > 0)
+  if (content === null && !refused && reason !== 'length')
+    return invalid('Completed Agent response omitted text')
+  return {
+    outcome: 'done',
+    output: {
+      text: refused ? refusal || content || 'The Agent response was filtered.' : (content ?? ''),
+      stop: refused ? 'refusal' : reason === 'length' ? 'limit' : 'end-turn',
+    },
+  }
+}
+
+function responsesResult(body: Record<string, unknown> | undefined): AgentTransportResult {
+  if (
+    body?.object !== 'response' ||
+    (body.status !== 'completed' && body.status !== 'incomplete') ||
+    (body.error !== undefined && body.error !== null) ||
+    !Array.isArray(body.output)
+  )
+    return invalid('Agent endpoint returned no completed or limited Responses result')
+  const reason = ordinaryRecord(body.incomplete_details)?.reason
+  if (body.status === 'incomplete' && reason !== 'max_output_tokens' && reason !== 'content_filter')
+    return invalid('Agent response has no supported incomplete reason')
+  if (body.status === 'completed' && body.incomplete_details != null)
+    return invalid('Completed Agent response includes incomplete details')
+
+  const texts: string[] = []
+  const refusals: string[] = []
+  for (const raw of body.output) {
+    const item = ordinaryRecord(raw)
+    if (item?.type === 'reasoning') continue
+    if (
+      item?.type !== 'message' ||
+      item.role !== 'assistant' ||
+      !Array.isArray(item.content) ||
+      (item.status !== 'completed' && item.status !== 'incomplete') ||
+      (body.status === 'completed' && item.status !== 'completed')
+    )
+      return invalid('Agent returned an unsupported Responses output or tool request')
+    for (const rawPart of item.content) {
+      const part = ordinaryRecord(rawPart)
+      if (part?.type === 'output_text' && typeof part.text === 'string') texts.push(part.text)
+      else if (part?.type === 'refusal' && typeof part.refusal === 'string')
+        refusals.push(part.refusal)
+      else return invalid('Agent response must contain text or an explicit refusal')
+    }
+  }
+  if (body.status === 'completed' && texts.length === 0 && refusals.length === 0)
+    return invalid('Completed Agent response omitted text')
+  const refused = refusals.length > 0 || reason === 'content_filter'
+  return {
+    outcome: 'done',
+    output: {
+      text: refused
+        ? refusals.join('\n') || texts.join('') || 'The Agent response was filtered.'
+        : texts.join(''),
+      stop: refused ? 'refusal' : body.status === 'incomplete' ? 'limit' : 'end-turn',
+    },
+  }
+}
+
+function invalid(message: string): never {
+  throw new AgentMethodError('INVALID_RESULT', message)
+}

package/src/conversation.ts

@@ -0,0 +1,387 @@
+import type { ChannelPair, ChannelSender, JsonValue, RunContext, RunResult } from '@jigging/flow'
+import type { AgentCallInput, AgentInput } from './index.js'
+import { exactKeys, ordinaryRecord, validSessionReceipt } from './values.js'
+
+export type AgentTurn =
+  | { readonly type: 'result'; readonly turn: number; readonly result: RunResult }
+  | { readonly type: 'cancelled'; readonly turn: number }
+  | {
+      readonly type: 'error'
+      readonly turn: number
+      readonly code: 'INVALID_RESULT'
+      readonly message: string
+    }
+
+export interface AgentConversation {
+  readonly initial: Promise<AgentTurn>
+  prompt(input: Omit<AgentInput, 'session'>): Promise<AgentTurn>
+  /** Acknowledges control, not cancellation. Await the turn for its actual outcome. */
+  interrupt(): Promise<'accepted' | 'not-running'>
+}
+
+export interface ConversationOptions {
+  readonly operationId: string
+  readonly slot: string
+  readonly input: AgentCallInput
+  /** Optional caller-created public update writer; observation stays application-owned. */
+  readonly events?: ChannelSender
+  /** Synchronous filtering/presentation of public updates; no channel setup required. */
+  readonly onEvent?: (event: AgentUpdate) => void
+}
+
+export type AgentUpdate =
+  | {
+      readonly sessionUpdate: 'agent_message_chunk'
+      readonly turn?: number
+      readonly messageId?: string
+      readonly content: { readonly type: 'text'; readonly text: string }
+    }
+  | {
+      readonly sessionUpdate: 'plan'
+      readonly turn?: number
+      readonly entries: readonly {
+        readonly content: string
+        readonly priority: 'high' | 'medium' | 'low'
+        readonly status: 'pending' | 'in_progress' | 'completed'
+      }[]
+    }
+
+export type AgentObservation =
+  | { readonly status: 'complete' }
+  | { readonly status: 'incomplete'; readonly errors: readonly unknown[] }
+
+export interface ConversationResult<T> {
+  readonly value: T
+  readonly turns: readonly AgentTurn[]
+  readonly settlement: RunResult
+  /** Present only with onEvent. Observation never stands in for execution settlement. */
+  readonly observation?: AgentObservation
+}
+
+/** Retains received answers and every primary/cleanup failure; never manufactures success. */
+export class AgentConversationError extends AggregateError {
+  constructor(
+    errors: readonly unknown[],
+    readonly turns: readonly AgentTurn[],
+    readonly settlement?: RunResult,
+  ) {
+    super(errors, 'Agent conversation did not complete cleanly', { cause: errors[0] })
+    this.name = 'AgentConversationError'
+  }
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((yes, no) => {
+    resolve = yes
+    reject = no
+  })
+  // A caller may inspect another part of a turn first. Rejections are still
+  // returned to every waiter; this is not a global failure acknowledgement ledger.
+  void promise.catch(() => undefined)
+  return { promise, resolve, reject }
+}
+
+function invalid(message: string): Error {
+  return new Error(message)
+}
+
+/** Ordinary Agent Run caller logic: no ACP implementation, host imports, or provider access. */
+export async function withAgentConversation<T>(
+  run: RunContext,
+  options: ConversationOptions,
+  use: (conversation: AgentConversation) => Promise<T>,
+): Promise<ConversationResult<T>> {
+  if (options.events && options.onEvent)
+    throw new TypeError('Choose onEvent or an external events writer, not both')
+  const requestedSession = options.input.session !== undefined
+  const turns: AgentTurn[] = []
+  const errors: unknown[] = []
+  const record = (error: unknown) => {
+    if (!errors.includes(error)) errors.push(error)
+  }
+  const reads = new AbortController()
+  const pending = new Set<ReturnType<typeof deferred<unknown>>>()
+  const tracked = <V>() => {
+    const value = deferred<V>()
+    pending.add(value as ReturnType<typeof deferred<unknown>>)
+    void value.promise.then(
+      () => pending.delete(value as ReturnType<typeof deferred<unknown>>),
+      () => pending.delete(value as ReturnType<typeof deferred<unknown>>),
+    )
+    return value
+  }
+  const fail = (error: unknown) => {
+    record(error)
+    reads.abort(error)
+    for (const value of pending) value.reject(error)
+  }
+  let commands: ChannelPair | undefined
+  let replies: ChannelPair | undefined
+  let events: ChannelPair | undefined
+  let observer: Promise<void> | undefined
+  const observerStop = new AbortController()
+  const observationErrors: unknown[] = []
+  let offered = false
+  let work: Promise<{ result: RunResult } | { error: unknown }> | undefined
+  let pump: Promise<void> | undefined
+  let settlement: RunResult | undefined
+  let writerClosed = false
+  let value!: T
+  let active = true
+  let current = { turn: 0, result: tracked<AgentTurn>() }
+  let promptControl:
+    | { accepted: ReturnType<typeof deferred<void>>; previous: typeof current }
+    | undefined
+  let interruptControl: ReturnType<typeof deferred<'accepted' | 'not-running'>> | undefined
+  let closeControl: ReturnType<typeof deferred<void>> | undefined
+  let controls = 0
+  let finished = false
+  const send = async (message: JsonValue) => {
+    if (++controls > 64) throw invalid('Conversation control limit is 64 commands')
+    await commands!.send.send(message, { signal: run.signal })
+  }
+  try {
+    commands = await run.channel({
+      contract: { slot: options.slot, channel: 'commands' },
+    })
+    replies = await run.channel({
+      contract: { slot: options.slot, channel: 'replies' },
+    })
+    if (options.onEvent) {
+      events = await run.channel({
+        contract: { slot: options.slot, channel: 'events' },
+      })
+    }
+    offered = true
+    // Do not cancel this local waiter to stop a conversation. Its real terminal
+    // is the evidence that lets a healthy parent subsequently use the capacity.
+    work = run
+      .call({
+        operationId: options.operationId,
+        slot: options.slot,
+        input: { ...options.input, conversation: true } as unknown as JsonValue,
+        channels: {
+          commands: commands.receive,
+          replies: replies.send,
+          ...(events ? { events: events.send } : options.events ? { events: options.events } : {}),
+        },
+      })
+      .then(
+        (result) => ({ result }),
+        (error) => {
+          fail(error)
+          observerStop.abort(error)
+          return { error }
+        },
+      )
+    if (events) {
+      observer = (async () => {
+        try {
+          for (;;) {
+            const item = await events!.receive.next({
+              signal: AbortSignal.any([run.signal, observerStop.signal]),
+            })
+            if (item.done) break
+            const returned: unknown = options.onEvent!(item.value as unknown as AgentUpdate)
+            if (returned && typeof (returned as PromiseLike<unknown>).then === 'function') {
+              void Promise.resolve(returned).catch(() => undefined)
+              throw new TypeError(
+                'onEvent must be synchronous; use events for asynchronous channel processing',
+              )
+            }
+          }
+        } catch (error) {
+          observationErrors.push(error)
+        } finally {
+          try {
+            await events!.receive.close()
+          } catch (error) {
+            if (!observationErrors.includes(error)) observationErrors.push(error)
+          }
+        }
+      })()
+    }
+    pump = (async () => {
+      try {
+        for (;;) {
+          const item = await replies!.receive.next({
+            signal: AbortSignal.any([run.signal, reads.signal]),
+          })
+          if (item.done) throw invalid('Agent replies ended before accepted conversation close')
+          const message = item.value as Record<string, JsonValue>
+          if (
+            !message ||
+            Array.isArray(message) ||
+            typeof message !== 'object' ||
+            message.turn !== current.turn
+          )
+            throw invalid('Agent reply has an unexpected turn')
+          if (message.type === 'accepted' || message.type === 'rejected') {
+            if (message.command === 'prompt' && promptControl) {
+              const control = promptControl
+              promptControl = undefined
+              if (message.type === 'accepted') control.accepted.resolve()
+              else {
+                const error = invalid(`Agent rejected prompt: ${String(message.code)}`)
+                current.result.reject(error)
+                current = control.previous
+                active = false
+                control.accepted.reject(error)
+              }
+            } else if (message.command === 'interrupt' && interruptControl) {
+              const control = interruptControl
+              interruptControl = undefined
+              if (message.type === 'accepted') control.resolve('accepted')
+              else if (message.code === 'NOT_RUNNING') control.resolve('not-running')
+              else control.reject(invalid(`Agent rejected interruption: ${String(message.code)}`))
+            } else if (message.command === 'close' && closeControl) {
+              if (message.type !== 'accepted') throw invalid('Agent rejected conversation close')
+              closeControl.resolve()
+              return
+            } else throw invalid('Agent sent an unexpected control reply')
+          } else {
+            if (!active || promptControl) throw invalid('Agent sent an out-of-order turn result')
+            if (message.type === 'result') {
+              const result = message.result as unknown as RunResult
+              if (!result || typeof result.outcome !== 'string' || !Object.hasOwn(result, 'output'))
+                throw invalid('Agent omitted its complete turn result')
+            } else if (
+              message.type !== 'cancelled' &&
+              !(
+                message.type === 'error' &&
+                message.code === 'INVALID_RESULT' &&
+                typeof message.message === 'string'
+              )
+            )
+              throw invalid('Agent sent an invalid turn terminal')
+            const turn = item.value as unknown as AgentTurn
+            if (turns.length >= 8) throw invalid('Agent exceeded the eight-turn conversation limit')
+            turns.push(turn)
+            active = false
+            current.result.resolve(turn)
+          }
+        }
+      } catch (error) {
+        if (!reads.signal.aborted) fail(error)
+      }
+    })()
+    const conversation: AgentConversation = {
+      initial: current.result.promise,
+      prompt(input) {
+        if (finished || active || interruptControl || errors.length)
+          return Promise.reject(invalid('Conversation is not ready for another prompt'))
+        if (current.turn >= 7) return Promise.reject(invalid('Conversation turn limit reached'))
+        const previous = current
+        current = { turn: previous.turn + 1, result: tracked<AgentTurn>() }
+        const result = current.result.promise
+        active = true
+        promptControl = { accepted: tracked<void>(), previous }
+        void send({
+          type: 'prompt',
+          turn: current.turn,
+          input: input as unknown as JsonValue,
+        }).catch(fail)
+        return result
+      },
+      async interrupt() {
+        if (finished || errors.length) throw invalid('Conversation is closing or failed')
+        if (promptControl) await promptControl.accepted.promise
+        if (!active) return 'not-running'
+        if (interruptControl) return interruptControl.promise
+        const control = tracked<'accepted' | 'not-running'>()
+        interruptControl = control
+        void send({ type: 'interrupt', turn: current.turn }).catch(fail)
+        return control.promise
+      },
+    }
+    try {
+      value = await use(conversation)
+    } catch (error) {
+      record(error)
+    }
+    finished = true
+    if (active) record(invalid('Application left a live Agent turn unfinished'))
+    if (!active && !reads.signal.aborted && !run.signal.aborted) {
+      if (interruptControl) await interruptControl.promise
+      closeControl = tracked<void>()
+      await send({ type: 'close', turn: current.turn })
+      await commands.send.close({ signal: run.signal })
+      writerClosed = true
+      await closeControl.promise
+    }
+  } catch (error) {
+    record(error)
+  } finally {
+    finished = true
+    // A failed callback/transport stops delivery to the Agent through ordinary
+    // channel closure, while preserving the non-cancelled invocation waiter.
+    if (commands && !writerClosed) {
+      try {
+        await commands.send.close({ error: 'LAGGED', signal: run.signal })
+      } catch (error) {
+        record(error)
+      }
+    }
+    reads.abort()
+    await pump
+    if (work) {
+      const terminal = await work
+      if ('error' in terminal) record(terminal.error)
+      else settlement = terminal.result
+    }
+    await observer
+    if (events && !offered) {
+      try {
+        await events.send.close({ error: 'LAGGED', signal: run.signal })
+      } catch (error) {
+        record(error)
+      }
+      try {
+        await events.receive.close()
+      } catch (error) {
+        record(error)
+      }
+    }
+    if (replies) {
+      try {
+        await replies.receive.close()
+      } catch (error) {
+        record(error)
+      }
+    }
+    // An allocated receiver that was never offered is still ours.
+    if (commands && !offered) {
+      try {
+        await commands.receive.close()
+      } catch (error) {
+        record(error)
+      }
+    }
+  }
+  if (run.signal.aborted) record(run.signal.reason ?? invalid('Run cancelled'))
+  const output = ordinaryRecord(settlement?.output)
+  if (
+    !settlement ||
+    settlement.outcome !== 'done' ||
+    !output ||
+    output.turns !== turns.length ||
+    !exactKeys(output, ['turns', ...(requestedSession ? ['session'] : [])]) ||
+    (requestedSession && !validSessionReceipt(output.session))
+  )
+    record(invalid('Agent omitted matching conversation settlement'))
+  if (errors.length) throw new AgentConversationError(errors, Object.freeze(turns), settlement)
+  return {
+    value,
+    turns: Object.freeze(turns),
+    settlement: settlement!,
+    ...(options.onEvent
+      ? {
+          observation: observationErrors.length
+            ? { status: 'incomplete' as const, errors: Object.freeze(observationErrors) }
+            : { status: 'complete' as const },
+        }
+      : {}),
+  }
+}

package/src/errors.ts

@@ -0,0 +1,11 @@
+export type AgentMethodErrorCode = 'INVALID_INPUT' | 'RESOURCE_EXHAUSTED' | 'INVALID_RESULT'
+
+export class AgentMethodError extends Error {
+  constructor(
+    readonly code: AgentMethodErrorCode,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'AgentMethodError'
+  }
+}

package/src/flow.ts

@@ -0,0 +1,66 @@
+import { handle, OperationError, type RunContext, type RunResult } from '@jigging/flow'
+import { parseApiResult, prepareApiRequest } from './api.js'
+import {
+  type AgentInput,
+  AgentMethodError,
+  finishAgent,
+  prepareAgent,
+  type SkillText,
+} from './index.js'
+import { ordinaryRecord, snapshot } from './values.js'
+
+export async function agentFlow(run: RunContext): Promise<RunResult> {
+  try {
+    const input = ordinaryRecord(snapshot(run.input, 'INVALID_INPUT'))
+    if (input && Object.hasOwn(input, 'session'))
+      throw new OperationError(
+        'UNAVAILABLE',
+        'This HTTP Agent cannot retain or restore native sessions',
+      )
+    if (input?.conversation === true)
+      throw new OperationError(
+        'UNAVAILABLE',
+        'This Agent supports one-shot calls, not continuing conversations',
+      )
+    if (
+      input === undefined ||
+      Object.keys(input).some(
+        (name) => !['instructions', 'guidance', 'responseSchema', 'skills'].includes(name),
+      )
+    ) {
+      throw new AgentMethodError(
+        'INVALID_INPUT',
+        'Supply instructions and optional explicit guidance, skills or responseSchema',
+      )
+    }
+    if (Object.keys(run.attachments).length > 0 || Object.keys(run.channels).length > 0) {
+      throw new OperationError(
+        'UNAVAILABLE',
+        'This text-only Agent method accepts no attachments or channels',
+      )
+    }
+    const { skills, ...methodInput } = input
+    const prepared = prepareAgent(
+      methodInput as unknown as AgentInput,
+      (skills === undefined ? [] : skills) as unknown as readonly SkillText[],
+    )
+    const { api, body } = prepareApiRequest(prepared, run.settings)
+    const result = await run.call(
+      {
+        operationId: 'completion',
+        slot: 'http',
+        input: { body, response: 'json' },
+      },
+      { signal: run.signal },
+    )
+    const resultValue = finishAgent(prepared, parseApiResult(result, api))
+    return { outcome: resultValue.outcome, output: { ...resultValue.output } }
+  } catch (error) {
+    if (error instanceof AgentMethodError) throw new OperationError(error.code, error.message)
+    throw error
+  }
+}
+
+export async function runAgentFlow(): Promise<void> {
+  await handle(agentFlow)
+}