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

package/AGENTS.md

@@ -73,6 +73,8 @@ ordinary Flow, preserving operator ownership of Agent execution.
 - The ordinary ACP package imports this same method. `checkAgentResult` lets
   consumers independently check any selected
   Agent's dynamic structured result; it grants no authority or provenance.
+  Its validated `AgentResult` is assignable to portable FLOW JSON without a
+  cast; arbitrary exceptions and non-JSON values are not.
 
 ## Work Guidance
 

package/dist/index.d.ts

@@ -51,14 +51,14 @@ export interface PreparedAgent {
     readonly request: AgentTransportInput;
     readonly session?: AgentSessionRequest;
 }
-export interface AgentResult {
+export type AgentResult = {
     readonly outcome: 'done' | 'blocked' | 'limit';
     readonly output: {
         readonly text: string;
         readonly structured?: JsonValue;
         readonly session?: AgentSessionReceipt;
     };
-}
+};
 /** Independently check an Agent Flow result at its consumer's boundary. */
 export declare function checkAgentResult(value: unknown, responseSchema?: JsonObject): AgentResult;
 /** Prepare one bounded request. The returned data confers no execution authority. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigging/agent-method",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "A reusable bounded Agent method with an ordinary FLOW entrypoint",
   "license": "MPL-2.0",
   "repository": {
@@ -47,8 +47,8 @@
     "test"
   ],
   "devDependencies": {
-    "@jigging/flow": "0.1.0-alpha.12",
+    "@jigging/flow": "0.1.0-alpha.13",
     "@types/node": "24.13.3",
     "typescript": "7.0.2"
   }
-}
+}

package/src/index.ts

@@ -64,7 +64,7 @@ export interface PreparedAgent {
   readonly session?: AgentSessionRequest
 }
 
-export interface AgentResult {
+export type AgentResult = {
   readonly outcome: 'done' | 'blocked' | 'limit'
   readonly output: {
     readonly text: string

package/test/conversation-fixture.ts

@@ -1,5 +1,5 @@
 import { handle, type JsonValue } from '@jigging/flow'
-import { withAgentConversation, AgentConversationError } from '../src/conversation.js'
+import { AgentConversationError, withAgentConversation } from '../src/conversation.js'
 
 await handle(async (run) => {
   const displayed: string[] = []
@@ -32,9 +32,12 @@ await handle(async (run) => {
         const first = await conversation.initial
         if (run.input === 'callback-error') throw new Error('application rejected draft')
         const second = conversation.prompt({ instructions: 'Apply this correction' })
-        if (run.input === 'interrupt' || run.input === 'completion-race')
-          await conversation.interrupt()
-        return { first, second: await second }
+        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 {

package/test/conversation.test.ts

@@ -136,14 +136,27 @@ async function exercise(mode: string) {
         } else if (request.method === 'channel/send') {
           ok(request, null)
           const command = p.value
-          item({ type: 'accepted', command: command.type, turn: command.turn })
-          if (command.type === 'prompt') {
-            if (mode === 'late-error') {
-              nativeSettled = true
-              fail(call, 'EXECUTION_FAILED')
-            } else if (!['interrupt', 'completion-race'].includes(mode)) terminal(command.turn)
-          } else if (command.type === 'interrupt')
-            terminal(command.turn, mode === 'interrupt' ? 'cancelled' : 'result')
+          if (command.type === 'interrupt' && mode === 'not-running-race') {
+            // The turn finishes as the interruption reaches the Agent. The
+            // terminal result must remain distinct from the control rejection.
+            terminal(command.turn)
+            item({
+              type: 'rejected',
+              command: 'interrupt',
+              turn: command.turn,
+              code: 'NOT_RUNNING',
+            })
+          } else {
+            item({ type: 'accepted', command: command.type, turn: command.turn })
+            if (command.type === 'prompt') {
+              if (mode === 'late-error') {
+                nativeSettled = true
+                fail(call, 'EXECUTION_FAILED')
+              } else if (!['interrupt', 'completion-race', 'not-running-race'].includes(mode))
+                terminal(command.turn)
+            } else if (command.type === 'interrupt')
+              terminal(command.turn, mode === 'interrupt' ? 'cancelled' : 'result')
+          }
         } else if (request.method === 'channel/close') {
           expect(p.endpoint).toBe('commands:s')
           closed = true
@@ -230,11 +243,21 @@ async function exercise(mode: string) {
   }
 }
 
-for (const mode of ['normal', 'interrupt', 'completion-race']) {
+for (const mode of ['normal', 'interrupt', 'completion-race', 'not-running-race']) {
   test(`public conversation helper: ${mode}`, async () => {
-    const { output } = await exercise(mode)
+    const { output, operations } = await exercise(mode)
     expect(output.turns).toHaveLength(2)
     expect(output.value.second.type).toBe(mode === 'interrupt' ? 'cancelled' : 'result')
+    if (mode === 'interrupt' || mode === 'completion-race')
+      expect(output.value.control).toBe('accepted')
+    if (mode === 'not-running-race') {
+      expect(output.value.control).toBe('not-running')
+      expect(
+        operations
+          .filter((operation) => operation.method === 'channel/send')
+          .map((operation) => operation.params.value.type),
+      ).toEqual(['prompt', 'interrupt', 'close'])
+    }
     expect(output.settlement).toEqual({ outcome: 'done', output: { turns: 2 } })
   })
 }

package/test/fixtures/public-result-types.ts

@@ -0,0 +1,17 @@
+import { type AgentResult, checkAgentResult } from '@jigging/agent-method'
+import type { JsonValue, RunHandler } from '@jigging/flow'
+
+const result: AgentResult = checkAgentResult({ outcome: 'done', output: { text: 'answer' } })
+const direct: JsonValue = result
+const nested: JsonValue = { agent: result }
+const handler: RunHandler = async () => ({ outcome: 'done', output: result })
+
+void [direct, nested, handler]
+
+// @ts-expect-error Functions are not JSON values.
+const functionOutput: JsonValue = () => 'answer'
+// @ts-expect-error Undefined is not a JSON value.
+const undefinedOutput: JsonValue = undefined
+// @ts-expect-error Error objects are not JSON values.
+const errorOutput: JsonValue = new Error('unhandled')
+void [functionOutput, undefinedOutput, errorOutput]

package/test/public-result-types.test.ts

@@ -0,0 +1,41 @@
+import { test } from 'bun:test'
+import { execFileSync } from 'node:child_process'
+import { copyFile, mkdir, mkdtemp, rm, symlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+test('public Agent results compose with FLOW JSON without casts', async () => {
+  const method = fileURLToPath(new URL('../', import.meta.url))
+  const flow = fileURLToPath(new URL('../../flow-sdk/', import.meta.url))
+  const consumer = await mkdtemp(join(tmpdir(), 'agent-public-types-'))
+  try {
+    await mkdir(join(consumer, 'node_modules/@jigging'), { recursive: true })
+    await symlink(method, join(consumer, 'node_modules/@jigging/agent-method'))
+    await symlink(flow, join(consumer, 'node_modules/@jigging/flow'))
+    await copyFile(
+      new URL('./fixtures/public-result-types.ts', import.meta.url),
+      join(consumer, 'consumer.ts'),
+    )
+    execFileSync(
+      process.execPath,
+      [
+        join(method, 'node_modules/typescript/bin/tsc'),
+        '--ignoreConfig',
+        '--noEmit',
+        '--strict',
+        '--exactOptionalPropertyTypes',
+        '--target',
+        'ES2022',
+        '--module',
+        'NodeNext',
+        '--moduleResolution',
+        'NodeNext',
+        'consumer.ts',
+      ],
+      { cwd: consumer, stdio: 'pipe' },
+    )
+  } finally {
+    await rm(consumer, { recursive: true, force: true })
+  }
+})