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

package/AGENTS.md

@@ -0,0 +1,98 @@
+# Reusable Agent method
+
+## Purpose
+
+Make a bounded Agent procedure independently reusable as a library and an
+ordinary Flow, preserving operator ownership of Agent execution.
+
+## Ownership
+
+- `src/` owns prompt preparation, structured schema checking, JSON/0 decoding,
+  result assembly, the optional package Skill reader, and ordinary Run/0 wiring.
+- The root `FLOW.ts` invokes the bundled runtime; it performs no implicit Skill reads.
+- `contracts/http-request/` mirrors the ordinary
+  Flow's exact delegated HTTP interface. Canonical descriptors live under
+  `docs/jig/spec/contracts/`.
+- Package source, declarations, built runtime, licenses, tests, and build
+  instructions form one release artifact.
+- `justfile` owns explicit builds and ordinary `bun pm pack` distribution.
+  Bun converts declared workspace versions to registry versions when packing;
+  no dependency archives or private installation convention are included.
+
+## Local Contracts
+
+- Pure exports perform no provider dispatch or filesystem access. The separate
+  `./skills` export reads only explicitly selected package-local Skill trees.
+- `./conversation` composes the public Agent Run contract through ordinary
+  calls and channels. It owns correlation, local endpoint disposal and an
+  uncancelled invocation waiter; it imports no native or private host code.
+  Received turn outcomes and final invocation settlement remain distinct.
+  Final receipt presence must match the initial session request; malformed or
+  unsolicited receipts fail without discarding settled turn evidence.
+  Callback or cleanup failures retain received turns in `AgentConversationError`.
+  Optional synchronous `onEvent` owns its public update channel and reports
+  observation loss separately from execution settlement. It never privately
+  echoes filtered data or requires a Log grant. Async routing uses `events`.
+  Resolve commands, replies and updates through the caller's declared Agent
+  slot; callers do not supply a separately synchronized contract directory.
+- Session requests are invocation metadata, separate from rendered instructions
+  and transport requests. `prepareAgent` validates and snapshots them;
+  `finishAgent` assembles answer facts only. `checkAgentResult` validates optional
+  final session receipts without granting authority or reading retained state.
+  Unavailable receipts require one of the contract's closed retention reasons;
+  neither missing reasons nor arbitrary diagnostic text are accepted.
+  Follow-up conversation prompts cannot change session intent; the receipt belongs
+  to final invocation settlement, never an individual turn reply.
+  Optional `lifetime: 'run'` on a new retention request restricts continuation
+  to its owning root. Restore inherits lifetime; the host owns enforcement and
+  deletion, not this library or the method.
+- The HTTP Flow rejects conversational mode and any session request before resource dispatch. Its
+  shared Agent contract does not imply support for native continuing sessions.
+  Its metadata declares `supports: []`; one-shot consumers need no optional
+  feature requirements. The shared descriptor catalog never grants a feature.
+- The ordinary Flow owns one non-streaming text-only Chat Completions or
+  Responses exchange through its HTTP slot. Closed API/model/token settings
+  are checked before dispatch. `structuredOutput: 'json-schema'` explicitly
+  adds the API's strict schema request; prompt mode is the default. Both modes
+  check results locally and never fall back or retry on rejection.
+  Endpoint, credentials and request policy belong to the host grant. No retries,
+  native Agent dependency, channel projection or direct networking. Skill contents
+  and guidance arrive as explicit caller data, not host-authenticated provenance.
+  `FLOW.contract.json` offers the exact Agent Run interface; an unsupported
+  optional channel rejects before HTTP dispatch.
+- `settings.schema.json` owns API/model/token/output-mode authoring validation.
+  The HTTP call requests decoded JSON/0 responses. Its 8 MiB request / 12 MiB
+  response ceilings do not increase the operator's smaller default grant or
+  JSON/0 value limits; reject oversized requests before dispatch, never truncate.
+- Preserve the shared 64-group, 1,024-item, 1 MiB content and 1 MiB rendered
+  prompt limits. Reject duplicate selections, invalid UTF-8 and symlinks.
+- Runtime dependencies are bundled; installed consumers need no build hook.
+- The source workspace uses `workspace:*` for SDK development. Extracted source
+  uses the packed versioned development dependencies and an ordinary Bun lock.
+  Publish dependencies before packages that require them for source rebuilds.
+- 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.
+
+## Work Guidance
+
+- Keep the bounded JSON/0 codec and schema profile local; no sibling private
+  imports or general provider/schema framework.
+- Update source and rebuild the corresponding packed runtime when adapting the
+  method. Do not edit generated `dist/` files.
+
+## Verification
+
+- The build clears only generated `dist/` before compiling, so removed source
+  cannot survive in the packed runtime or declaration files.
+
+- `just build` compiles declarations and bundles the ordinary runtime.
+- `just test` checks the method, JSON/0, bounded reader, and Flow wiring.
+  Session tests cover strict opaque references, immutable metadata and receipts,
+  unchanged model prompts, and pre-dispatch HTTP refusal.
+- `just pack --destination <directory>` builds the complete archive explicitly.
+- After building, `bun pm pack --ignore-scripts --destination <directory>` packs
+  existing output. Package tests verify source, ordinary dependency versions,
+  standalone runtime imports and repacking without mutating workspace manifests.
+
+## Child DOX Index

package/FLOW.contract.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://flow.jig.md/schemas/invocation-contract-0.schema.json",
+  "id": "https://jig.md/contracts/agent-run",
+  "version": "0.1.0",
+  "features": {
+    "events": "Implements the optional public-update protocol, including honest observation loss.",
+    "conversation": "Implements conversational commands, replies, turn results and final settlement; prompt allowances remain separately granted.",
+    "sessions": "Implements retain/restore requests and final receipts, including run-scoped state and honest unavailability; authority and successful retention are separate."
+  },
+  "input": {
+    "$ref": "#/$defs/RunInput"
+  },
+  "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
+      },
+      {
+        "type": "object",
+        "properties": {
+          "outcome": {
+            "const": "done"
+          },
+          "output": {
+            "type": "object",
+            "properties": {
+              "session": {
+                "$ref": "#/$defs/SessionReceipt"
+              },
+              "turns": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 8
+              }
+            },
+            "required": ["turns"],
+            "additionalProperties": false
+          }
+        },
+        "required": ["outcome", "output"],
+        "additionalProperties": false
+      }
+    ]
+  },
+  "outcomes": {
+    "blocked": "The Agent completed its bounded response but reported that the requested work is blocked.",
+    "limit": "The Agent completed its bounded response but reported an Agent limit; host deadline and cancellation remain operational failures."
+  },
+  "channels": {
+    "events": {
+      "direction": "send",
+      "required": false,
+      "contract": "./contracts/acp-public-updates.json"
+    },
+    "commands": {
+      "direction": "receive",
+      "required": false,
+      "delivery": "direct",
+      "contract": "./contracts/agent-commands.json"
+    },
+    "replies": {
+      "direction": "send",
+      "required": false,
+      "delivery": "direct",
+      "contract": "./contracts/agent-replies.json"
+    }
+  },
+  "$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
+        }
+      ]
+    },
+    "RunInput": {
+      "type": "object",
+      "properties": {
+        "instructions": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1048576
+        },
+        "skills": {
+          "$ref": "#/$defs/SkillContents"
+        },
+        "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
+          }
+        },
+        "conversation": {
+          "const": true
+        },
+        "session": {
+          "$ref": "#/$defs/SessionRequest"
+        }
+      },
+      "required": ["instructions"],
+      "additionalProperties": false
+    },
+    "AgentOutput": {
+      "type": "object",
+      "properties": {
+        "text": {
+          "type": "string",
+          "maxLength": 8388608
+        },
+        "structured": true,
+        "session": {
+          "$ref": "#/$defs/SessionReceipt"
+        }
+      },
+      "required": ["text"],
+      "additionalProperties": false
+    },
+    "SkillContents": {
+      "type": "array",
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "files": {
+            "type": "array",
+            "maxItems": 1024,
+            "items": {
+              "type": "object",
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 4096
+                },
+                "text": {
+                  "type": "string",
+                  "maxLength": 1048576
+                }
+              },
+              "required": ["path", "text"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": ["name", "files"],
+        "additionalProperties": false
+      }
+    }
+  }
+}

package/FLOW.meta.json

@@ -0,0 +1,8 @@
+{
+  "name": "agent-method",
+  "supports": [],
+  "description": "Prepare instructions and guidance, request one text response through an HTTP slot, and check the result.",
+  "uses": {
+    "http": { "contract": "./contracts/http-request/contract.json" }
+  }
+}

package/FLOW.ts

@@ -0,0 +1,3 @@
+import { runAgentFlow } from './dist/flow.js'
+
+await runAgentFlow()