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

package/src/skills.ts

@@ -0,0 +1,138 @@
+import { constants } from 'node:fs'
+import { lstat, open, opendir, realpath } from 'node:fs/promises'
+import { dirname, isAbsolute, join, parse, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { AgentMethodError } from './errors.js'
+import type { SkillText } from './index.js'
+import { compareUtf8, localName, snapshot } from './values.js'
+
+/** Read explicit selections from an immutable package root, never from the CWD. */
+export async function readPackageSkills(
+  packageRoot: URL,
+  names: readonly string[],
+): Promise<readonly SkillText[]> {
+  const selection = snapshot(names, 'INVALID_INPUT')
+  if (
+    !Array.isArray(selection) ||
+    selection.some((name) => !localName(name)) ||
+    new Set(selection).size !== selection.length
+  )
+    invalid('Select unique Skill LocalNames')
+  if (selection.length > 64) exhausted('Skill selection exceeds 64 groups')
+  if (
+    !(packageRoot instanceof URL) ||
+    packageRoot.protocol !== 'file:' ||
+    packageRoot.search !== '' ||
+    packageRoot.hash !== '' ||
+    !packageRoot.pathname.endsWith('/')
+  ) {
+    invalid('Supply an absolute file URL for the package directory')
+  }
+  let root: string
+  try {
+    root = fileURLToPath(packageRoot)
+    await assertRealDirectory(root)
+  } catch {
+    invalid('Package root must be a real directory without symlink components')
+  }
+  if (selection.length === 0) return Object.freeze([])
+  let fileCount = 0
+  let contentBytes = 0
+  let entries = 0
+  const skills: SkillText[] = []
+  const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+  try {
+    for (const name of [...selection].sort((a, b) =>
+      compareUtf8(a as string, b as string),
+    ) as string[]) {
+      const directory = join(root!, 'skills', name)
+      await assertRealDirectory(directory)
+      const files: { path: string; text: string }[] = []
+      const visit = async (current: string): Promise<void> => {
+        const reader = await opendir(current)
+        for await (const entry of reader) {
+          entries += 1
+          if (entries > 4096) exhausted('Skill traversal exceeds 4,096 entries')
+          const path = join(current, entry.name)
+          if (Buffer.byteLength(relative(directory, path)) > 4096)
+            exhausted('Skill path exceeds 4,096 bytes')
+          const info = await lstat(path)
+          if (info.isSymbolicLink()) invalid('Skill trees must not contain symlinks')
+          if (info.isDirectory()) {
+            await assertRealDirectory(path)
+            await visit(path)
+          } else if (info.isFile()) {
+            fileCount += 1
+            contentBytes += info.size
+            if (fileCount > 1024 || contentBytes > 1_048_576)
+              exhausted('Selected Skills exceed 1,024 files or 1 MiB content')
+            if ((await realpath(path)) !== path) invalid('Skill file path contains a symlink')
+            const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+            try {
+              const opened = await handle.stat()
+              if (
+                !opened.isFile() ||
+                opened.dev !== info.dev ||
+                opened.ino !== info.ino ||
+                opened.size !== info.size
+              ) {
+                invalid('Skill file changed during reading')
+              }
+              const bytes = new Uint8Array(info.size + 1)
+              let length = 0
+              while (length < bytes.length) {
+                const chunk = await handle.read(bytes, length, bytes.length - length, length)
+                if (chunk.bytesRead === 0) break
+                length += chunk.bytesRead
+              }
+              if (length !== info.size || (await realpath(path)) !== path)
+                invalid('Skill file changed during reading')
+              files.push(
+                Object.freeze({
+                  path: relative(directory, path).split('\\').join('/'),
+                  text: decoder.decode(bytes.subarray(0, length)),
+                }),
+              )
+            } finally {
+              await handle.close()
+            }
+          } else {
+            invalid('Skill trees may contain only directories and regular files')
+          }
+        }
+      }
+      await visit(directory)
+      if (!files.some((file) => file.path === 'SKILL.md'))
+        invalid('Selected Skill requires SKILL.md')
+      files.sort((a, b) => compareUtf8(a.path, b.path))
+      skills.push(Object.freeze({ name, files: Object.freeze(files) }))
+    }
+  } catch (error) {
+    if (error instanceof AgentMethodError) throw error
+    invalid('Selected Skill is unavailable or is not valid UTF-8 text')
+  }
+  return Object.freeze(skills)
+}
+
+async function assertRealDirectory(path: string): Promise<void> {
+  const absolute = resolve(path)
+  if (!isAbsolute(path)) invalid('Package path must be absolute')
+  let cursor = parse(absolute).root
+  for (const part of relative(cursor, absolute).split('/').filter(Boolean)) {
+    cursor = join(cursor, part)
+    const info = await lstat(cursor)
+    if (!info.isDirectory() || info.isSymbolicLink())
+      invalid('Package directory path contains a symlink or non-directory')
+  }
+  if ((await realpath(absolute)) !== absolute || dirname(absolute) === absolute)
+    invalid('Select a package directory')
+}
+
+function invalid(message: string): never {
+  throw new AgentMethodError('INVALID_INPUT', message)
+}
+
+function exhausted(message: string): never {
+  throw new AgentMethodError('RESOURCE_EXHAUSTED', message)
+}

package/src/values.ts

@@ -0,0 +1,77 @@
+import { AgentMethodError, type AgentMethodErrorCode } from './errors.js'
+import { canonicalJson, decodeJson1, type JsonValue } from './json.js'
+
+export function ordinaryRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype !== Object.prototype && prototype !== null) return undefined
+  return value as Record<string, unknown>
+}
+
+export function exactKeys(value: object, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort()
+  const sorted = [...expected].sort()
+  return actual.length === sorted.length && actual.every((name, index) => name === sorted[index])
+}
+
+export function sessionReference(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length === 36 &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value)
+  )
+}
+
+export function validSessionReceipt(value: unknown): boolean {
+  const record = ordinaryRecord(value)
+  return (
+    record !== undefined &&
+    ((exactKeys(record, ['status', 'reason']) &&
+      record.status === 'unavailable' &&
+      ['not-cleanly-closed', 'missing-history', 'unsupported-history', 'capacity'].includes(
+        record.reason as string,
+      )) ||
+      (exactKeys(record, ['status', 'reference']) &&
+        record.status === 'retained' &&
+        sessionReference(record.reference)))
+  )
+}
+
+export function snapshot(value: unknown, code: AgentMethodErrorCode): JsonValue {
+  try {
+    return decodeJson1(canonicalJson(value as JsonValue))
+  } catch {
+    throw new AgentMethodError(code, 'Agent method values must be ordinary bounded JSON/0 data')
+  }
+}
+
+export function freezeJson<T extends JsonValue>(value: T): T {
+  if (value !== null && typeof value === 'object') {
+    for (const child of Object.values(value)) freezeJson(child)
+    Object.freeze(value)
+  }
+  return value
+}
+
+export function compareUtf8(left: string, right: string): number {
+  const a = new TextEncoder().encode(left)
+  const b = new TextEncoder().encode(right)
+  for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+    if (a[index] !== b[index]) return a[index]! - b[index]!
+  }
+  return a.length - b.length
+}
+
+export function localName(name: unknown): name is string {
+  return typeof name === 'string' && name.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)
+}
+
+export function skillPath(path: unknown): path is string {
+  return (
+    typeof path === 'string' &&
+    new TextEncoder().encode(path).byteLength <= 4096 &&
+    !path.includes('\\') &&
+    !path.includes('\0') &&
+    path.split('/').every((part) => part.length > 0 && part !== '.' && part !== '..')
+  )
+}

package/test/api.test.ts

@@ -0,0 +1,326 @@
+import { expect, test } from 'bun:test'
+import { readFile } from 'node:fs/promises'
+import { parseApiResult, prepareApiRequest } from '../src/api.js'
+import { finishAgent, prepareAgent } from '../src/index.js'
+
+const prepared = prepareAgent({ instructions: 'Answer.' })
+const chatResult = (value: unknown) => parseApiResult(value, 'chat-completions')
+const response = (content: unknown = 'Answer.', reason: unknown = 'stop', extra = {}) => ({
+  outcome: 'done',
+  output: {
+    status: 200,
+    body: {
+      object: 'chat.completion',
+      choices: [
+        { index: 0, finish_reason: reason, message: { role: 'assistant', content, ...extra } },
+      ],
+    },
+  },
+})
+
+test('request uses reviewed settings, has a token cap and no endpoint, key or tools', () => {
+  const { api, body } = prepareApiRequest(prepared, {
+    model: 'chosen-model',
+    maxCompletionTokens: 32,
+  })
+  expect(api).toBe('chat-completions')
+  expect(body).toEqual({
+    model: 'chosen-model',
+    max_completion_tokens: 32,
+    n: 1,
+    stream: false,
+    store: false,
+    messages: [{ role: 'user', content: prepared.request.prompt }],
+  })
+  for (const settings of [
+    {},
+    { model: '' },
+    { model: 'x', endpoint: 'https://example.org' },
+    { model: 'x', maxCompletionTokens: 0 },
+    { model: 'x', maxCompletionTokens: 65537 },
+    { model: 'x', maxCompletionTokens: 1.5 },
+    { model: 'x', maxCompletionTokens: null },
+    { model: 'x', api: 'automatic' },
+    { model: 'x', api: null },
+    { model: 'x', structuredOutput: 'automatic' },
+    { model: 'x', structuredOutput: null },
+    { model: 'x', max_tokens: 32 },
+    { model: 'x', tools: [] },
+  ])
+    expect(() => prepareApiRequest(prepared, settings)).toThrow()
+  expect(() =>
+    prepareApiRequest(prepareAgent({ instructions: 'é'.repeat(150000) }), { model: 'x' }),
+  ).not.toThrow()
+})
+
+test('Responses requests select the exact wire format without changing endpoint authority', () => {
+  expect(prepareApiRequest(prepared, { api: 'responses', model: 'chosen-model' })).toEqual({
+    api: 'responses',
+    body: {
+      model: 'chosen-model',
+      input: prepared.request.prompt,
+      max_output_tokens: 4096,
+      stream: false,
+      store: false,
+    },
+  })
+})
+
+const schema = {
+  $schema: 'https://flow.jig.md/schemas/schema-0.json',
+  type: 'object',
+  properties: { answer: { type: 'string' } },
+  required: ['answer'],
+  additionalProperties: false,
+}
+
+test('provider-enforced schemas require explicit selection and never replace local checking', () => {
+  const structured = prepareAgent({ instructions: 'Answer.', responseSchema: schema })
+  const { $schema: _removed, ...projected } = schema
+  for (const api of ['chat-completions', 'responses'] as const) {
+    const ordinary = prepareApiRequest(structured, { api, model: 'x' }).body
+    expect(ordinary.response_format).toBeUndefined()
+    expect(ordinary.text).toBeUndefined()
+    expect(
+      prepareApiRequest(structured, { api, model: 'x', structuredOutput: 'prompt' }).body,
+    ).toEqual(ordinary)
+    const body = prepareApiRequest(structured, {
+      api,
+      model: 'x',
+      structuredOutput: 'json-schema',
+    }).body
+    const definition = { name: 'flow_agent_result', schema: projected, strict: true }
+    if (api === 'responses')
+      expect(body.text).toEqual({ format: { type: 'json_schema', ...definition } })
+    else expect(body.response_format).toEqual({ type: 'json_schema', json_schema: definition })
+    expect(
+      prepareApiRequest(prepared, { api, model: 'x', structuredOutput: 'json-schema' }).body,
+    ).toEqual(prepareApiRequest(prepared, { api, model: 'x' }).body)
+  }
+  expect(structured.request.responseSchema?.$schema).toBe(schema.$schema)
+})
+
+test('HTTP and malformed replies remain failures, without echoing provider data', () => {
+  for (const status of [301, 400, 401, 429, 500]) {
+    expect(() =>
+      chatResult({ outcome: 'done', output: { status, body: 'private-provider-error' } }),
+    ).toThrow(`HTTP ${status}`)
+  }
+  for (const result of [
+    response(null),
+    response('x', 'tool_calls'),
+    response('x', null),
+    response('x', 'stop', { tool_calls: [{ id: 'call', type: 'function' }] }),
+    response(['not text']),
+    { outcome: 'done', output: { status: 200, body: '{"choices":[],"choices":[]}' } },
+    { outcome: 'done', output: { status: 200, body: 'not json' } },
+  ])
+    expect(() => chatResult(result)).toThrow()
+})
+
+test('complete answers, refusals and exhausted completions retain distinct outcomes', () => {
+  expect(chatResult(response('Answer.', 'stop', { tool_calls: [] })).output.text).toBe('Answer.')
+  expect(finishAgent(prepared, chatResult(response()))).toEqual({
+    outcome: 'done',
+    output: { text: 'Answer.' },
+  })
+  expect(finishAgent(prepared, chatResult(response('partial', 'length')))).toEqual({
+    outcome: 'limit',
+    output: { text: 'partial' },
+  })
+  expect(
+    finishAgent(prepared, chatResult(response(null, 'stop', { refusal: 'Cannot comply.' }))),
+  ).toEqual({ outcome: 'blocked', output: { text: 'Cannot comply.' } })
+  expect(finishAgent(prepared, chatResult(response(null, 'content_filter'))).outcome).toBe(
+    'blocked',
+  )
+})
+
+test('the method validates structured output independently of the provider finish reason', () => {
+  const request = prepareAgent({
+    instructions: 'Answer.',
+    responseSchema: {
+      $schema: 'https://flow.jig.md/schemas/schema-0.json',
+      type: 'object',
+      properties: { answer: { type: 'string' } },
+      required: ['answer'],
+      additionalProperties: false,
+    },
+  })
+  expect(finishAgent(request, chatResult(response('{"answer":"yes"}'))).output.structured).toEqual({
+    answer: 'yes',
+  })
+  expect(() => finishAgent(request, chatResult(response('{"answer":42}')))).toThrow(
+    'responseSchema',
+  )
+  expect(() => finishAgent(request, chatResult(response('not JSON')))).toThrow('JSON/0')
+})
+
+test('ordinary Agent declares its packaged HTTP descriptor', async () => {
+  const contract = JSON.parse(
+    await readFile(new URL('../contracts/http-request/contract.json', import.meta.url), 'utf8'),
+  )
+  expect(contract.id).toBe('https://jig.md/contracts/http-request')
+  const meta = JSON.parse(await readFile(new URL('../FLOW.meta.json', import.meta.url), 'utf8'))
+  expect(meta.uses).toEqual({ http: { contract: './contracts/http-request/contract.json' } })
+})
+
+const responsesResult = (value: unknown) => parseApiResult(value, 'responses')
+const responses = (output: unknown, status: unknown = 'completed', extra = {}) => ({
+  outcome: 'done',
+  output: {
+    status: 200,
+    body: { object: 'response', status, output, ...extra },
+  },
+})
+const message = (content: unknown, status = 'completed', role = 'assistant') => ({
+  type: 'message',
+  role,
+  status,
+  content,
+})
+const text = (value: unknown) => ({ type: 'output_text', text: value })
+
+test('Responses separates completed text, explicit refusal and actual token exhaustion', () => {
+  expect(
+    finishAgent(
+      prepared,
+      responsesResult(
+        responses([
+          { type: 'reasoning', summary: [{ type: 'summary_text', text: 'not public output' }] },
+          message([text('First '), text('answer.')]),
+          message([text(' Second answer.')]),
+        ]),
+      ),
+    ),
+  ).toEqual({ outcome: 'done', output: { text: 'First answer. Second answer.' } })
+  expect(
+    finishAgent(
+      prepared,
+      responsesResult(responses([message([{ type: 'refusal', refusal: 'Cannot comply.' }])])),
+    ),
+  ).toEqual({ outcome: 'blocked', output: { text: 'Cannot comply.' } })
+  expect(
+    finishAgent(
+      prepared,
+      responsesResult(
+        responses([message([text('Partial')], 'incomplete')], 'incomplete', {
+          incomplete_details: { reason: 'max_output_tokens' },
+        }),
+      ),
+    ),
+  ).toEqual({
+    outcome: 'limit',
+    output: { text: 'Partial' },
+  })
+  expect(
+    finishAgent(
+      prepared,
+      responsesResult(
+        responses([], 'incomplete', {
+          incomplete_details: { reason: 'max_output_tokens' },
+        }),
+      ),
+    ),
+  ).toEqual({ outcome: 'limit', output: { text: '' } })
+  expect(
+    finishAgent(
+      prepared,
+      responsesResult(
+        responses([], 'incomplete', {
+          incomplete_details: { reason: 'content_filter' },
+        }),
+      ),
+    ),
+  ).toEqual({ outcome: 'blocked', output: { text: 'The Agent response was filtered.' } })
+})
+
+test('Responses rejects unsettled, failed, tool-bearing, malformed and inconsistent results', () => {
+  for (const value of [
+    responses([], 'queued'),
+    responses([], 'in_progress'),
+    responses([], 'failed', { error: { message: 'private-provider-error' } }),
+    responses([], 'cancelled'),
+    responses([message([text('Answer.')])], 'completed', {
+      error: { message: 'private-provider-error' },
+    }),
+    responses([], 'incomplete'),
+    responses([], 'incomplete', { incomplete_details: { reason: 'steered' } }),
+    responses([message([text('Answer.')])], 'completed', {
+      incomplete_details: { reason: 'max_output_tokens' },
+    }),
+    responses([message([text('Partial')], 'incomplete')]),
+    responses([message([text('Answer.')], 'in_progress')]),
+    responses([message([text('Answer.')], 'completed', 'user')]),
+    responses([message([text('Answer.')]), { type: 'function_call', name: 'run' }]),
+    responses([message([{ type: 'audio', data: 'secret' }])]),
+    responses([message([text(42)])]),
+    responses([null]),
+    responses([]),
+    responses([{ type: 'reasoning' }]),
+    response(),
+  ]) {
+    let error: unknown
+    try {
+      responsesResult(value)
+    } catch (failure) {
+      error = failure
+    }
+    expect(error).toBeInstanceOf(Error)
+    expect(String(error)).not.toContain('private-provider-error')
+  }
+  expect(() => chatResult(responses([message([text('Answer.')])]))).toThrow()
+})
+
+test('Responses structured results are independently checked even after a completed response', () => {
+  const request = prepareAgent({ instructions: 'Answer.', responseSchema: schema })
+  expect(
+    finishAgent(request, responsesResult(responses([message([text('{"answer":"yes"}')])]))).output
+      .structured,
+  ).toEqual({ answer: 'yes' })
+  for (const body of ['{"answer":42}', 'not JSON', '{"answer":"one","answer":"two"}'])
+    expect(() =>
+      finishAgent(request, responsesResult(responses([message([text(body)])]))),
+    ).toThrow()
+})
+
+test('both APIs preserve the complete HTTP byte bounds and JSON/0 failure behavior', () => {
+  for (const api of ['chat-completions', 'responses'] as const) {
+    expect(() =>
+      prepareApiRequest(prepareAgent({ instructions: 'x'.repeat(262144) }), { api, model: 'x' }),
+    ).not.toThrow()
+    expect(() =>
+      parseApiResult({ outcome: 'done', output: { status: 200, body: 'x'.repeat(1048577) } }, api),
+    ).toThrow()
+    for (const body of [
+      '{"object":"response","object":"response"}',
+      '{"unsafe":9007199254740992}',
+      '{"bad":"\\ud800"}',
+      'not json',
+    ])
+      expect(() =>
+        parseApiResult({ outcome: 'done', output: { status: 200, body } }, api),
+      ).toThrow()
+    for (const status of [400, 401, 429, 500])
+      expect(() =>
+        parseApiResult(
+          { outcome: 'done', output: { status, body: 'private-provider-error' } },
+          api,
+        ),
+      ).toThrow(`HTTP ${status}`)
+  }
+})
+
+test('decoded HTTP data preserves the full 8 MiB Agent text bound without JSON-string wrapping', () => {
+  const maximum = 'x'.repeat(8_388_608)
+  const replies = [
+    ['chat-completions', response(maximum)],
+    ['responses', responses([message([text(maximum)])])],
+  ] as const
+  for (const [api, reply] of replies) {
+    expect(finishAgent(prepared, parseApiResult(reply, api)).output.text.length).toBe(
+      maximum.length,
+    )
+  }
+  expect(() => chatResult(response(`${maximum}x`))).toThrow('JSON/0')
+})

package/test/conversation-fixture.ts

@@ -0,0 +1,73 @@
+import { handle, type JsonValue } from '@jigging/flow'
+import { AgentConversationError, withAgentConversation } from '../src/conversation.js'
+
+await handle(async (run) => {
+  const displayed: string[] = []
+  try {
+    const result = await withAgentConversation(
+      run,
+      {
+        operationId: 'dialogue',
+        slot: 'agent',
+        ...(String(run.input).startsWith('observer')
+          ? {
+              onEvent(event: import('../src/conversation.js').AgentUpdate) {
+                if (run.input === 'observer-throws') throw new Error('display failed')
+                if (run.input === 'observer-async')
+                  return Promise.reject(new Error('async display failed'))
+                if (event.sessionUpdate === 'agent_message_chunk')
+                  displayed.push(event.content.text)
+              },
+            }
+          : {}),
+        input: {
+          instructions: 'Draft from these facts',
+          ...(['retained', 'missing-session', 'invalid-session'].includes(run.input as string)
+            ? { session: { retain: true as const } }
+            : {}),
+        },
+      },
+      async (conversation) => {
+        if (run.input === 'abandoned') return null
+        const first = await conversation.initial
+        if (run.input === 'callback-error') throw new Error('application rejected draft')
+        const second = conversation.prompt({ instructions: 'Apply this correction' })
+        const control = ['interrupt', 'completion-race', 'not-running-race'].includes(
+          run.input as string,
+        )
+          ? await conversation.interrupt()
+          : undefined
+        return { first, second: await second, ...(control === undefined ? {} : { control }) }
+      },
+    )
+    return {
+      outcome: 'done',
+      output: {
+        ...result,
+        displayed,
+        ...(result.observation?.status === 'incomplete'
+          ? {
+              observation: {
+                status: 'incomplete',
+                errors: result.observation.errors.map((e) =>
+                  e instanceof Error ? e.message : String(e),
+                ),
+              },
+            }
+          : {}),
+      } as unknown as JsonValue,
+    }
+  } catch (error) {
+    if (!(error instanceof AgentConversationError)) throw error
+    return {
+      outcome: 'done',
+      output: {
+        errors: Array.from(error.errors, (value) =>
+          value instanceof Error ? value.message : String(value),
+        ),
+        turns: error.turns as unknown as JsonValue,
+        settlement: (error.settlement as unknown as JsonValue) ?? null,
+      },
+    }
+  }
+})