@jigging/agent-acp 0.1.0-alpha.5 → 0.1.0-alpha.7

package/AGENTS.md

@@ -33,6 +33,8 @@ retains credential, process, and dispatch authority.
 - Jig consumers may select this declared dependency with `npm:@jigging/agent-acp`
   in a local Binding; the Binding still grants the exact native client.
   Contract-keyed project selection does not create that grant or choose a vendor.
+  The README teaches package-selected caller creation and offline contract import
+  from ordinary root/member installs; consumers do not name physical installer paths.
 - Reuse `@jigging/agent-method` for prompt preparation and result validation.
   Complete ACP dialogue and resource settlement are separate requirements.
 - Locally detected invalid ACP cancels the resource while preserving that
@@ -45,6 +47,9 @@ retains credential, process, and dispatch authority.
   closes the writer with `error: 'LAGGED'`; no clean EOF hides incomplete output.
   Closed native warning notices go to console diagnostics, not answer text or
   public events; the host strips raw metadata and rejects authoritative errors.
+- A native request rejection reports its known finite ACP method with
+  `EXECUTION_FAILED`, never the client's error text or data. That phase does not
+  establish the private cause, remote dispatch or permission to retry.
 - Optional conversational mode owns bounded direct commands/replies and per-turn
   results in `src/conversation.ts`. Native maxTurns, serial dispatch and interruption
   settlement remain host-enforced. One-shot calls retain their simple interface.

package/README.md

@@ -38,6 +38,10 @@ filesystem context are not supplied.
 
 Native warnings are separate, sanitized console diagnostics rather than answer
 text or Agent events. Authoritative native errors remain invocation failures.
+Rejected native requests report the failed ACP step, such as `session/new` or
+`session/prompt`, with `EXECUTION_FAILED`. The client's private error text and
+data are withheld. The step identifies where the rejection was received; it
+does not establish its cause, remote effects, or permission to repeat the call.
 
 For conversational use, add `conversation: true` to input and connect direct
 `commands` and `replies` channels from the complete contract bundle. Initial
@@ -127,6 +131,30 @@ The example's client is a choice, not a Jig default; `codex`, `claude` and `pi`
 use the same grant interface. The operator configures the native installation, model and
 authentication described in [Choose an Agent](https://jig.md/guide/agents).
 
+To call this Agent from a new Flow, install the declared project dependency
+with `bun install`, then select its complete contract when creating the caller:
+
+```sh
+jig new worker --use agent=npm:@jigging/agent-acp
+```
+
+For an existing caller, create its `contracts/` parent and import the bundle:
+
+```sh
+mkdir -p flows/worker/contracts
+jig import-contract npm:@jigging/agent-acp flows/worker/contracts/agent
+```
+
+Declare `uses.agent.contract: './contracts/agent/FLOW.contract.json'` in that
+caller's metadata. Selection uses the nearest ordinary project or member-local
+installation, copies all referenced channel descriptors offline, and runs no
+package code. The copied contract belongs to the caller: an installation update
+does not replace it or grant new authority. An existing destination is refused;
+choose a new directory to inspect a changed contract before updating the caller.
+See the [conversation walkthrough](https://jig.md/guide/conversations) for a
+complete two-turn caller and the separate native turn grant. These authoring
+commands require the matching Jig source candidate until its alpha is published.
+
 ```sh
 jig review
 jig run binding:agent --input '{"instructions":"Explain one useful check."}' --receive events

package/dist/flow.js

@@ -1,9 +1,11 @@
 // ../agent-method/dist/errors.js
 class AgentMethodError extends Error {
   code;
-  constructor(code, message) {
+  details;
+  constructor(code, message, details) {
     super(message);
     this.code = code;
+    this.details = details;
     this.name = "AgentMethodError";
   }
 }
@@ -3215,7 +3217,7 @@ class FinitePeer {
       if (frame.id !== id || Object.hasOwn(frame, "result") === Object.hasOwn(frame, "error"))
         failure("Native ACP response does not match its request");
       if (frame.error !== undefined)
-        throw new OperationError("EXECUTION_FAILED", "Native ACP request failed");
+        throw new OperationError("EXECUTION_FAILED", `Native ACP request failed during ${method}; private client details were withheld.`);
       return object2(frame.result);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigging/agent-acp",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "description": "An ordinary Agent Flow over a finite, host-authorized ACP resource",
   "license": "MPL-2.0",
   "repository": {
@@ -37,7 +37,7 @@
   ],
   "devDependencies": {
     "@jigging/flow": "0.1.0-alpha.13",
-    "@jigging/agent-method": "0.1.0-alpha.5",
+    "@jigging/agent-method": "0.1.0-alpha.6",
     "@types/node": "24.13.3",
     "typescript": "7.0.2"
   }

package/src/flow.ts

@@ -32,6 +32,13 @@ const RESPONSES = './contracts/finite-acp/responses.json'
 const MAX_TEXT_BYTES = 8_388_608
 
 type Settlement = { result: RunResult } | { error: unknown }
+type NativeRequestMethod =
+  | 'initialize'
+  | 'session/new'
+  | 'session/resume'
+  | 'session/set_config_option'
+  | 'session/set_mode'
+  | 'session/prompt'
 
 /** One replaceable method; process, credentials and reviewed policy stay outside. */
 export async function agentAcpFlow(run: RunContext): Promise<RunResult> {
@@ -261,7 +268,7 @@ class FinitePeer {
     private readonly updates: OptionalUpdates,
   ) {}
 
-  async request(method: string, params: JsonObject): Promise<JsonObject> {
+  async request(method: NativeRequestMethod, params: JsonObject): Promise<JsonObject> {
     const id = ++this.operation
     await this.write({ jsonrpc: '2.0', id, method, params })
     for (;;) {
@@ -275,7 +282,10 @@ class FinitePeer {
       if (frame.id !== id || Object.hasOwn(frame, 'result') === Object.hasOwn(frame, 'error'))
         failure('Native ACP response does not match its request')
       if (frame.error !== undefined)
-        throw new OperationError('EXECUTION_FAILED', 'Native ACP request failed')
+        throw new OperationError(
+          'EXECUTION_FAILED',
+          `Native ACP request failed during ${method}; private client details were withheld.`,
+        )
       return object(frame.result)
     }
   }

package/test/flow.test.ts

@@ -248,6 +248,54 @@ function fixture(options: Options = {}) {
   }
 }
 
+describe('native request failure diagnostics', () => {
+  test.each([
+    'initialize',
+    'session/new',
+    'session/resume',
+    'session/set_config_option',
+    'session/set_mode',
+    'session/prompt',
+  ])(
+    'identifies %s without exposing native error text or sending further requests',
+    async (method) => {
+      const restoring = method === 'session/resume'
+      const f = fixture({
+        ...(restoring
+          ? {
+              input: {
+                instructions: 'Continue.',
+                session: { restore: '013579ab-cdef-4567-89ab-0123456789ab' },
+              },
+              ready: { ...ready, restoreSessionId: 'owned-session' },
+            }
+          : {}),
+        async emit(frame, send) {
+          if (frame.method !== method) return false
+          await f.frameSend(send, {
+            jsonrpc: '2.0',
+            id: frame.id!,
+            error: {
+              code: -32603,
+              message: '/private/native-state secret-token rejected private-model',
+              data: { credential: 'secret-token', cause: 'untrusted native detail' },
+            },
+          })
+          return true
+        },
+      })
+      const failure = await agentAcpFlow(f.run).catch((error) => error)
+      expect(failure).toBeInstanceOf(OperationError)
+      expect(failure).toMatchObject({
+        code: 'EXECUTION_FAILED',
+        message: `Native ACP request failed during ${method}; private client details were withheld.`,
+      })
+      expect(f.frames.at(-1)?.method).toBe(method)
+      expect(f.stats()).toEqual({ calls: 1, cancelled: true, settled: true })
+    },
+  )
+})
+
 describe('ordinary session retention and restoration', () => {
   test.each(['active', 'settled'])(
     'notice display during %s does not enter answers or selected public events',