@aexhq/agentloop-pi 6.0.0 → 6.1.1

package/README.md

@@ -13,8 +13,10 @@ pi's per-turn contract:
   `contextWindow - reserveTokens` (default 16384), history older than ~`keepRecentTokens`
   (default 20000) is summarized into pi's structured context checkpoint.
 
-pi's steering and follow-up queues and per-tool `executionMode` are host-app seams with no Brain
-equivalent and are not ported.
+Tools and their Environments coordinate access to shared resources with their own transactions,
+locks or queues. A lock prevents overlap; dependency-sensitive work still needs ordered dispatch
+or a Tool that owns the whole operation. Pi has no per-tool scheduling flag or batch Tool protocol.
+Its steering and follow-up queues are host application concerns and are not ported.
 
 ```ts
 import { brainEnv } from "@aexhq/brain";
@@ -32,7 +34,10 @@ The component is built by this package's publisher. Brain consumes the resulting
 does not compile its JavaScript source.
 
 The loop reads paginated session Events before each turn and saves its observation cursor in
-kv. Interrupted turns and environment failures enter the transcript as runtime observations.
+kv after saving those observations in the transcript. For unanswered calls in the last saved
+assistant message, it inserts error Tool results explaining that the turn was interrupted and
+the operation may have run. Saved results, media and native provider state are preserved.
+Interrupted turns and environment failures also enter the transcript as runtime observations.
 A failed tool result goes back to the model with `is_error`; the loop does not retry it automatically.
 Brain can release execution between turns without losing this transcript or cursor. The caller
 controls Environment lifetime; a browser closure or provider resource loss can still destroy its
@@ -48,16 +53,31 @@ Transcript changes and `ctx.kv.read/put/delete` use Brain's state services. KV m
 committed inline; missing keys remain distinct from stored JSON null. A later model or
 Tool failure preserves acknowledged writes; turn output contains only the result. Retained
 native model blocks pass through unchanged, and user images enter model context as media.
-Version 5.1 also presents successful Tool outputs shaped as
+Successful Tool outputs shaped as
 `{ type: "aex_tool_output", version: 1, content, media: [{ type: "image", url }] }`
-as Tool-result content and image media. Browser and MCP extensions use this presentation
-convention; ordinary JSON results keep their existing behavior.
+become Tool-result content and native media. Images and PDFs require HTTPS URLs. Browser and MCP
+extensions use this presentation convention; ordinary JSON/base64 remains business data.
+Results keep call IDs and assistant source order, including mixed image/text batches and failed
+siblings. For hosted applications, publish bytes with Aex's attachment API and return its media URL.
 Compaction explicitly resets the response format and installs a summary only after `end_turn`;
 a truncated, refused, or unknown summary leaves the original saved context intact.
 
-Version 5.1 targets Brain 0.22 and preserves the existing WIT. Existing sessions keep their
+Version 6.1 targets Brain SDK 0.24 and preserves the 0.23 WIT and URL-media contract. Existing sessions keep their
 immutable loop implementation; create new sessions to adopt the updated loop. Keep matching
 server/artifacts for recovery. An upgrade does not migrate or delete session data.
 
 Image and PDF blocks remain native media in compaction requests. The JSON-length estimate used
 for new context does not measure image/PDF tokens; provider context-limit failures remain explicit.
+
+Use `session.send(prompt, { output: { type: AnswerSchema } })` for validated application output.
+Pi finishes when the assistant returns no Tool calls; no special terminal Tool is required.
+Ordinary `send()` returns session state, so `idle` alone does not establish turn success.
+
+## Develop the loop
+
+From a checkout of this repository, run `npm run test:logic -w packages/loop-pi` or
+`npm run test:logic:watch -w packages/loop-pi`. These execute the existing JavaScript logic tests
+without rebuilding Wasm. Run `npm test -w packages/loop-pi` for the Component build and package
+tests, then the compiled journeys described in the repository README. All release gates remain
+required. A rebuilt Component needs a new admission and session. Package source is not a public
+logic-library entry point, and existing sessions keep their admitted implementation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/agentloop-pi",
-  "version": "6.0.0",
+  "version": "6.1.1",
   "description": "Pi-style parallel-Tool Brain extension",
   "license": "MIT",
   "repository": {
@@ -31,11 +31,13 @@
   "scripts": {
     "build": "node ../../tools/build-agentloop.mjs src/component.mjs src/index.mjs dist",
     "test": "npm run build && node --test *.test.mjs",
+    "test:logic": "node --test loop.test.mjs state.test.mjs",
+    "test:logic:watch": "node --test --watch loop.test.mjs state.test.mjs",
     "test:journeys": "node --test test/journeys.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@aexhq/brain": "0.23.0",
+    "@aexhq/brain": "0.24.2",
     "zod": "4.4.3"
   },
   "devDependencies": {}

package/src/logic.mjs

@@ -67,7 +67,6 @@ export async function runPi(input, context) {
   const transcript = cloneJson(input.transcript);
   const observed_sequence = await observeEvents(context, transcript, (await context.kv.read("observed_sequence")) ?? 0);
   const saved = await context.kv.read("checkpoint");
-  await context.kv.put("observed_sequence", observed_sequence);
   const checkpoint = saved === undefined ? { summary: null } : cloneJson(saved);
   const body = () => checkpoint.summary === null ? transcript : transcript.slice(1);
   const shouldCompact = () =>
@@ -104,8 +103,9 @@ export async function runPi(input, context) {
   };
 
   transcript.push({ role: "user", content: [{ type: "text", text: input.input.message }, ...(input.input.media ?? [])] });
+  await context.setTranscript(transcript);
+  await context.kv.put("observed_sequence", observed_sequence);
   for (;;) {
-    await context.setTranscript(transcript);
     if (shouldCompact()) {
       await compact();
       await context.setTranscript(transcript);
@@ -127,6 +127,7 @@ export async function runPi(input, context) {
         role: "user",
         content: calls.map((call) => ({ type: "tool_result", tool_use_id: call.call_id, content: TRUNCATED_CALL_MESSAGE, is_error: true })),
       });
+      await context.setTranscript(transcript);
       continue;
     }
     const results = await context.dispatch(calls.map(placement.invocation));
@@ -135,6 +136,7 @@ export async function runPi(input, context) {
       role: "user",
       content: calls.map(({ call_id }) => toolResult(call_id, byCall.get(call_id))),
     });
+    await context.setTranscript(transcript);
   }
 }