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

package/contracts/agent-replies.json

@@ -0,0 +1,202 @@
+{
+  "$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/http-request/contract.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://flow.jig.md/schemas/invocation-contract-0.schema.json",
+  "id": "https://jig.md/contracts/http-request",
+  "version": "0.1.0",
+  "input": {
+    "type": "object",
+    "properties": {
+      "body": {},
+      "response": { "const": "json" }
+    },
+    "required": [],
+    "additionalProperties": false
+  },
+  "result": {
+    "type": "object",
+    "properties": {
+      "outcome": {
+        "const": "done"
+      },
+      "output": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "integer",
+            "minimum": 200,
+            "maximum": 599
+          },
+          "body": {}
+        },
+        "required": ["status", "body"],
+        "additionalProperties": false
+      }
+    },
+    "required": ["outcome", "output"],
+    "additionalProperties": false
+  }
+}

package/dist/api.d.ts

@@ -0,0 +1,11 @@
+import type { AgentTransportResult, PreparedAgent } from './index.js';
+import { type JsonObject } from './json.js';
+type Api = 'chat-completions' | 'responses';
+/** One finite text request. API settings choose syntax, never endpoint authority. */
+export declare function prepareApiRequest(prepared: PreparedAgent, settings: unknown): {
+    readonly api: Api;
+    readonly body: JsonObject;
+};
+/** Interpret only complete HTTP evidence. Never echo an arbitrary provider error body. */
+export declare function parseApiResult(result: unknown, api: Api): AgentTransportResult;
+export {};

package/dist/api.js

@@ -0,0 +1,164 @@
+import { AgentMethodError } from './errors.js';
+import { canonicalJson } from './json.js';
+import { projectResponseSchema } from './schema.js';
+import { ordinaryRecord, snapshot } from './values.js';
+/** One finite text request. API settings choose syntax, never endpoint authority. */
+export function prepareApiRequest(prepared, settings) {
+    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 = 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, api) {
+    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).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) {
+    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) {
+    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 = [];
+    const refusals = [];
+    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) {
+    throw new AgentMethodError('INVALID_RESULT', message);
+}

package/dist/conversation.d.ts

@@ -0,0 +1,68 @@
+import type { ChannelSender, RunContext, RunResult } from '@jigging/flow';
+import type { AgentCallInput, AgentInput } from './index.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 declare class AgentConversationError extends AggregateError {
+    readonly turns: readonly AgentTurn[];
+    readonly settlement?: RunResult | undefined;
+    constructor(errors: readonly unknown[], turns: readonly AgentTurn[], settlement?: RunResult | undefined);
+}
+/** Ordinary Agent Run caller logic: no ACP implementation, host imports, or provider access. */
+export declare function withAgentConversation<T>(run: RunContext, options: ConversationOptions, use: (conversation: AgentConversation) => Promise<T>): Promise<ConversationResult<T>>;