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

package/contracts/agent-commands.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://flow.jig.md/schemas/channel-contract-0.schema.json",
+  "id": "https://jig.md/contracts/agent-commands",
+  "version": "0.1.0",
+  "semantics": "Direct controls for an explicitly conversational Agent Run. Initial invocation input starts turn 0. Prompt names the next sequential turn; interrupt names the running turn; close names the last settled turn. Controls are accepted or rejected separately from turn settlement and final invocation cleanup. Delivery is not dispatch or completion. No automatic queue or replay.",
+  "item": {
+    "oneOf": [
+      {
+        "type": "object",
+        "properties": {
+          "type": {
+            "const": "prompt"
+          },
+          "turn": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 7
+          },
+          "input": {
+            "type": "object",
+            "properties": {
+              "instructions": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1048576
+              },
+              "responseSchema": {
+                "type": "object"
+              },
+              "guidance": {
+                "type": "array",
+                "maxItems": 64,
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "label": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "text": {
+                      "type": "string"
+                    }
+                  },
+                  "required": ["label", "text"],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "required": ["instructions"],
+            "additionalProperties": false
+          }
+        },
+        "required": ["type", "turn", "input"],
+        "additionalProperties": false
+      },
+      {
+        "type": "object",
+        "properties": {
+          "type": {
+            "enum": ["interrupt", "close"]
+          },
+          "turn": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 7
+          }
+        },
+        "required": ["type", "turn"],
+        "additionalProperties": false
+      }
+    ]
+  }
+}

package/contracts/agent-replies.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://flow.jig.md/schemas/channel-contract-0.schema.json",
+  "id": "https://jig.md/contracts/agent-replies",
+  "version": "0.1.0",
+  "semantics": "Essential direct replies for conversational Agent Run. accepted acknowledges a control, not completed work; result is one settled Agent answer; cancelled settles a cancelled turn without an answer; error reports a settled but invalid answer. rejected performs no requested action. All items are at most 64 KiB; lost, oversized or persistently blocked replies fail the conversation rather than truncate results. End of stream is not native cleanup: await the enclosing invocation.",
+  "item": {
+    "oneOf": [
+      {
+        "type": "object",
+        "properties": {
+          "type": {
+            "const": "accepted"
+          },
+          "command": {
+            "enum": ["prompt", "interrupt", "close"]
+          },
+          "turn": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 7
+          }
+        },
+        "required": ["type", "command", "turn"],
+        "additionalProperties": false
+      },
+      {
+        "type": "object",
+        "properties": {
+          "type": {
+            "const": "rejected"
+          },
+          "command": {
+            "enum": ["prompt", "interrupt", "close"]
+          },
+          "turn": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "code": {
+            "enum": ["BUSY", "STALE_TURN", "TURN_LIMIT", "INVALID_INPUT", "NOT_RUNNING"]
+          }
+        },
+        "required": ["type", "command", "turn", "code"],
+        "additionalProperties": false
+      },
+      {
+        "type": "object",
+        "properties": {
+          "type": {
+            "const": "result"
+          },
+          "turn": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 7
+          },
+          "result": {
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "outcome": {
+                    "const": "done"
+                  },
+                  "output": {
+                    "$ref": "#/$defs/AgentOutput"
+                  }
+                },
+                "required": ["outcome", "output"],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "outcome": {
+                    "const": "blocked"
+                  },
+                  "output": {
+                    "$ref": "#/$defs/AgentOutput"
+                  }
+                },
+                "required": ["outcome", "output"],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "outcome": {
+                    "const": "limit"
+                  },
+                  "output": {
+                    "$ref": "#/$defs/AgentOutput"
+                  }
+                },
+                "required": ["outcome", "output"],
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "required": ["type", "turn", "result"],
+        "additionalProperties": false
+      },
+      {
+        "type": "object",
+        "properties": {
+          "type": {
+            "const": "cancelled"
+          },
+          "turn": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 7
+          }
+        },
+        "required": ["type", "turn"],
+        "additionalProperties": false
+      },
+      {
+        "type": "object",
+        "properties": {
+          "type": {
+            "const": "error"
+          },
+          "turn": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 7
+          },
+          "code": {
+            "const": "INVALID_RESULT"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": ["type", "turn", "code", "message"],
+        "additionalProperties": false
+      }
+    ]
+  },
+  "$defs": {
+    "AgentOutput": {
+      "type": "object",
+      "properties": {
+        "text": {
+          "type": "string",
+          "maxLength": 8388608
+        },
+        "structured": true
+      },
+      "required": ["text"],
+      "additionalProperties": false
+    }
+  }
+}

package/contracts/finite-acp/contract.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://flow.jig.md/schemas/invocation-contract-0.schema.json",
+  "id": "https://jig.md/contracts/finite-acp",
+  "version": "0.1.0",
+  "input": {
+    "oneOf": [
+      { "type": "null" },
+      {
+        "type": "object",
+        "properties": { "session": { "$ref": "#/$defs/SessionRequest" } },
+        "required": ["session"],
+        "additionalProperties": false
+      }
+    ]
+  },
+  "result": {
+    "type": "object",
+    "properties": {
+      "outcome": {
+        "const": "done"
+      },
+      "output": {
+        "type": "object",
+        "properties": {
+          "exitCode": {
+            "type": ["integer", "null"]
+          },
+          "signal": {
+            "type": ["string", "null"]
+          },
+          "cleanup": {
+            "const": "complete"
+          },
+          "stopReason": {
+            "enum": ["exited", "closed"]
+          },
+          "session": {
+            "$ref": "#/$defs/SessionReceipt"
+          }
+        },
+        "required": ["exitCode", "signal", "cleanup", "stopReason"],
+        "additionalProperties": false
+      }
+    },
+    "required": ["outcome", "output"],
+    "additionalProperties": false
+  },
+  "$defs": {
+    "SessionRequest": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": { "retain": { "const": true }, "lifetime": { "const": "run" } },
+          "required": ["retain"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "restore": { "type": "string", "minLength": 36, "maxLength": 36 }
+          },
+          "required": ["restore"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "SessionReceipt": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "status": { "const": "retained" },
+            "reference": { "type": "string", "minLength": 36, "maxLength": 36 }
+          },
+          "required": ["status", "reference"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "status": { "const": "unavailable" },
+            "reason": {
+              "enum": ["not-cleanly-closed", "missing-history", "unsupported-history", "capacity"]
+            }
+          },
+          "required": ["status", "reason"],
+          "additionalProperties": false
+        }
+      ]
+    }
+  },
+  "channels": {
+    "requests": {
+      "direction": "receive",
+      "required": true,
+      "contract": "./requests.json"
+    },
+    "responses": {
+      "direction": "send",
+      "required": true,
+      "contract": "./responses.json"
+    }
+  }
+}

package/contracts/finite-acp/requests.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://flow.jig.md/schemas/channel-contract-0.schema.json",
+  "id": "https://jig.md/contracts/finite-acp-requests",
+  "version": "0.1.0",
+  "semantics": "Required direct requests for one host-authorized finite ACP conversation. Each data item carries 1 to 8192 UTF-8 bytes, cut only between Unicode scalars. Concatenate in order until end:true to obtain one JSON/0 ACP frame. There is no interleaving, replay, binary data, or independent chunk identity. The host validates the complete frame and reviewed authority before dispatch; accepting a fragment does not establish dispatch. EOF inside a frame fails the resource. Clean EOF requests process settlement only after the allowed conversation has settled. Bounds and the finite operation profile are specified by the finite-acp contract documentation.",
+  "item": {
+    "type": "object",
+    "properties": {
+      "kind": {
+        "const": "data"
+      },
+      "text": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 8192
+      },
+      "end": {
+        "type": "boolean"
+      }
+    },
+    "required": ["kind", "text", "end"],
+    "additionalProperties": false
+  }
+}

package/contracts/finite-acp/responses.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://flow.jig.md/schemas/channel-contract-0.schema.json",
+  "id": "https://jig.md/contracts/finite-acp-responses",
+  "version": "0.1.0",
+  "semantics": "Required direct responses for one host-authorized finite ACP conversation. Exactly one ready item precedes data. Ready describes non-secret reviewed configuration and an armed transport, not completed authentication or an Agent result. Data items frame host-validated and authority-filtered ACP responses and public updates using the same bounded framing as finite-acp-requests. Thoughts, tools, permissions, credentials and raw diagnostic fields are not forwarded. This stream is essential: loss or incomplete framing fails the resource, not merely observation. EOF is not successful execution; await the separate resource result and interpret the Agent result separately.",
+  "item": {
+    "oneOf": [
+      {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "const": "ready"
+          },
+          "protocolVersion": {
+            "const": 1
+          },
+          "cwd": {
+            "const": "/work"
+          },
+          "configuration": {
+            "type": "array",
+            "maxItems": 16,
+            "items": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "configId": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 1024
+                    },
+                    "value": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 1024
+                    }
+                  },
+                  "required": ["configId", "value"],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "configId": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 1024
+                    },
+                    "type": {
+                      "const": "boolean"
+                    },
+                    "value": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": ["configId", "type", "value"],
+                  "additionalProperties": false
+                }
+              ]
+            }
+          },
+          "modeId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "restoreSessionId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "maxTurns": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 8
+          }
+        },
+        "required": ["kind", "protocolVersion", "cwd", "configuration", "maxTurns"],
+        "additionalProperties": false
+      },
+      {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "const": "data"
+          },
+          "text": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 8192
+          },
+          "end": {
+            "type": "boolean"
+          }
+        },
+        "required": ["kind", "text", "end"],
+        "additionalProperties": false
+      }
+    ]
+  }
+}

package/dist/conversation.d.ts

@@ -0,0 +1,8 @@
+import { prepareAgent } from '@jigging/agent-method';
+import { type ChannelReceiver, type ChannelSender, type RunResult } from '@jigging/flow';
+export interface ConversationPeer {
+    prompt(input: ReturnType<typeof prepareAgent>, turn?: number): Promise<RunResult>;
+    interrupt(): Promise<boolean>;
+}
+/** Application dialogue only. Native dispatch and settlement are enforced by the resource. */
+export declare function converse(peer: ConversationPeer, initial: ReturnType<typeof prepareAgent>, commands: ChannelReceiver, replies: ChannelSender, maxTurns: number, signal: AbortSignal): Promise<RunResult>;

package/dist/conversation.js

@@ -0,0 +1,155 @@
+import { AgentMethodError, prepareAgent } from '@jigging/agent-method';
+import { OperationError, } from '@jigging/flow';
+/** Application dialogue only. Native dispatch and settlement are enforced by the resource. */
+export async function converse(peer, initial, commands, replies, maxTurns, signal) {
+    const reads = new AbortController();
+    const readSignal = AbortSignal.any([signal, reads.signal]);
+    const read = () => commands.next({ signal: readSignal }).then((item) => ({ kind: 'command', item }), (error) => ({ kind: 'read-error', error }));
+    const reply = async (value) => {
+        if (new TextEncoder().encode(JSON.stringify(value)).byteLength > 65_536)
+            throw new OperationError('RESOURCE_EXHAUSTED', 'A conversation reply exceeds 64 KiB; request a smaller answer');
+        const timeout = AbortSignal.timeout(5_000);
+        try {
+            await replies.send(value, { signal: AbortSignal.any([signal, timeout]) });
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (timeout.aborted)
+                throw new OperationError('DEADLINE_EXCEEDED', 'Conversation reply delivery did not settle within five seconds');
+            throw error;
+        }
+    };
+    let turn = 0;
+    let settledTurns = 0;
+    let interrupted = false;
+    let receivedCommands = 0;
+    const start = (input) => peer.prompt(input, turn).then((result) => ({ kind: 'turn', result }), (error) => ({ kind: 'turn-error', error }));
+    let active = start(initial);
+    let command = read();
+    try {
+        for (;;) {
+            const next = await Promise.race(active ? [active, command] : [command]);
+            signal.throwIfAborted();
+            if (next.kind === 'read-error')
+                throw next.error;
+            if (next.kind === 'turn' || next.kind === 'turn-error') {
+                active = undefined;
+                settledTurns += 1;
+                if (next.kind === 'turn') {
+                    await reply({ type: 'result', turn, result: next.result });
+                }
+                else if (next.error instanceof OperationError && next.error.code === 'CANCELLED') {
+                    await reply({ type: 'cancelled', turn });
+                }
+                else if (next.error instanceof AgentMethodError && next.error.code === 'INVALID_RESULT') {
+                    await reply({
+                        type: 'error',
+                        turn,
+                        code: 'INVALID_RESULT',
+                        message: 'The settled Agent answer does not match the requested result',
+                    });
+                }
+                else
+                    throw next.error;
+                continue;
+            }
+            if (next.item.done)
+                throw new OperationError('DISCONNECTED', 'Conversation commands ended without an accepted close');
+            if (++receivedCommands > 64)
+                throw new OperationError('RESOURCE_EXHAUSTED', 'Conversation control limit is 64 commands');
+            command = read();
+            const received = next.item.value;
+            if (received === null || typeof received !== 'object' || Array.isArray(received))
+                throw new OperationError('INVALID_INPUT', 'Expected a conversation command');
+            const value = received;
+            const type = value.type;
+            if (!['prompt', 'interrupt', 'close'].includes(type) ||
+                typeof value.turn !== 'number' ||
+                !Number.isSafeInteger(value.turn) ||
+                value.turn < 0 ||
+                Object.keys(value).some((key) => !['type', 'turn', ...(type === 'prompt' ? ['input'] : [])].includes(key)))
+                throw new OperationError('INVALID_INPUT', 'Invalid conversation command');
+            const reject = (code) => reply({ type: 'rejected', command: type, turn: value.turn, code });
+            if (type === 'prompt') {
+                if (active) {
+                    await reject('BUSY');
+                    continue;
+                }
+                if (value.turn !== turn + 1) {
+                    await reject('STALE_TURN');
+                    continue;
+                }
+                if (settledTurns >= maxTurns) {
+                    await reject('TURN_LIMIT');
+                    continue;
+                }
+                let prepared;
+                try {
+                    // Initial context remains in the native conversation; these are new turn instructions.
+                    prepared = prepareAgent(value.input);
+                    if (prepared.session !== undefined)
+                        throw new AgentMethodError('INVALID_INPUT', 'Session requests belong to the initial invocation');
+                }
+                catch (error) {
+                    if (!(error instanceof AgentMethodError))
+                        throw error;
+                    await reject('INVALID_INPUT');
+                    continue;
+                }
+                turn += 1;
+                interrupted = false;
+                active = start(prepared);
+            }
+            else if (type === 'interrupt') {
+                if (value.turn !== turn) {
+                    await reject('STALE_TURN');
+                    continue;
+                }
+                if (!active || interrupted) {
+                    await reject('NOT_RUNNING');
+                    continue;
+                }
+                if (!(await peer.interrupt())) {
+                    await reject('NOT_RUNNING');
+                    continue;
+                }
+                interrupted = true;
+            }
+            else {
+                if (active) {
+                    await reject('BUSY');
+                    continue;
+                }
+                if (value.turn !== turn) {
+                    await reject('STALE_TURN');
+                    continue;
+                }
+                await reply({ type: 'accepted', command: 'close', turn });
+                // Let the caller seal its writer before releasing this receiver. Merely
+                // cancelling our pending read would make a racing clean writer close fail.
+                const timeout = setTimeout(() => reads.abort(), 5_000);
+                try {
+                    const end = await command;
+                    signal.throwIfAborted();
+                    if (reads.signal.aborted)
+                        throw new OperationError('DEADLINE_EXCEEDED', 'Conversation command closure did not settle within five seconds');
+                    if (end.kind === 'read-error')
+                        throw end.error;
+                    if (!end.item.done)
+                        throw new OperationError('INVALID_INPUT', 'Conversation commands continued after accepted close');
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+                return { outcome: 'done', output: { turns: settledTurns } };
+            }
+            await reply({ type: 'accepted', command: type, turn });
+        }
+    }
+    finally {
+        reads.abort();
+        await command;
+        // Every native prompt promise has a rejection handler. The enclosing owner
+        // cancels and settles the resource before disposing its endpoints on error.
+    }
+}

package/dist/flow.d.ts

@@ -0,0 +1,4 @@
+import { type RunContext, type RunResult } from '@jigging/flow';
+/** One replaceable method; process, credentials and reviewed policy stay outside. */
+export declare function agentAcpFlow(run: RunContext): Promise<RunResult>;
+export declare function runAgentAcpFlow(): Promise<void>;