@aexhq/agentloop-pi 2.1.0 → 4.0.0

package/README.md

@@ -17,10 +17,10 @@ pi's steering and follow-up queues and per-tool `executionMode` are host-app sea
 equivalent and are not ported.
 
 ```ts
-import { brainWasm } from "@aexhq/brain";
+import { brainEnv } from "@aexhq/brain";
 import { pi } from "@aexhq/agentloop-pi";
 
-const loopRuntime = brainWasm();
+const loopRuntime = brainEnv({ name: "brain" });
 const session = await brain.sessions.create({
   agentloop: pi({ env: loopRuntime, contextWindow: 200_000 }),
   model,
@@ -32,8 +32,23 @@ 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
-slots. Interrupted turns and environment failures enter the transcript as runtime observations.
+kv. Interrupted turns and environment failures 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. Physical
-browser and sandbox state follows the Environment provider's TTL and may be lost. The official
-`tool-env` inspection and lifecycle tool is planned after the MVP.
+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
+physical state.
+
+By default the model sees canonical Tool schemas. A Tool with multiple placements requires an
+explicit `placements: { toolName: "environmentName" }` option. Set
+`environmentSelection: "model"` to expose each Tool's authorized Environment names in its input
+schema. The loop unwraps that choice before dispatch; Brain validates the selected pair and the
+canonical input. Both modes use the same session Tool placements.
+
+Transcript and kv changes are saved inline through Brain's state services. 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.
+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.
+
+Rebuild Components against the matching Brain WIT when upgrading. Existing sessions keep their
+immutable loop implementation and must be recreated for this interface change.

package/dist/index.mjs

@@ -2,6 +2,8 @@
 import { agentloop, component } from "@aexhq/brain";
 import { z } from "zod";
 var options = z.object({
+  environmentSelection: z.enum(["hidden", "model"]).default("hidden"),
+  placements: z.record(z.string(), z.string()).default({}),
   contextWindow: z.number().int().positive().default(2e5),
   // pi defaults (compaction.ts): compact when context exceeds
   // contextWindow - reserveTokens, keep ~keepRecentTokens of recent messages.

package/index.d.ts

@@ -1,7 +1,9 @@
-import type { AgentloopBinding, Environment } from "@aexhq/brain";
+import type { PlacedAgentloop, Environment } from "@aexhq/brain";
 
 export interface PiOptions {
   readonly env: Environment;
+  readonly environmentSelection?: "hidden" | "model";
+  readonly placements?: Readonly<Record<string, string>>;
   /** Model context window in tokens the compaction budget is measured against. Default 200000. */
   readonly contextWindow?: number;
   /** Compact when the estimated context exceeds contextWindow - reserveTokens. pi default 16384. */
@@ -12,4 +14,4 @@ export interface PiOptions {
   readonly compaction?: boolean;
 }
 
-export declare const pi: (options: PiOptions) => AgentloopBinding;
+export declare const pi: (options: PiOptions) => PlacedAgentloop;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/agentloop-pi",
-  "version": "2.1.0",
+  "version": "4.0.0",
   "description": "Pi-style parallel-Tool Brain extension",
   "license": "MIT",
   "repository": {
@@ -15,7 +15,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "provenance": false,
+    "provenance": true,
     "tag": "next"
   },
   "exports": {
@@ -34,7 +34,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@aexhq/brain": "0.17.0",
+    "@aexhq/brain": "0.19.0",
     "zod": "4.4.3"
   },
   "devDependencies": {}

package/src/component.mjs

@@ -19,12 +19,14 @@ export async function turn(input) {
     const output = await runPi({
       input: JSON.parse(input.inputJson),
       transcript: JSON.parse(input.transcriptJson),
-      slots: JSON.parse(input.slotsJson),
+      kv: JSON.parse(input.kvJson),
       events: JSON.parse(input.eventsJson),
       configuration: JSON.parse(input.configurationJson),
       system: input.system,
       tools: JSON.parse(input.toolsJson),
     }, {
+      setTranscript: (messages) => hosted(() => host.setTranscript(JSON.stringify(messages))),
+      setKv: (key, value) => hosted(() => host.setKv(key, JSON.stringify(value))),
       events: (after) => JSON.parse(hosted(() => host.events(BigInt(after)))),
       model: (request) => JSON.parse(hosted(() => host.model(JSON.stringify(request)))),
       dispatch: (calls) => JSON.parse(hosted(() => host.dispatch(JSON.stringify(calls)))),
@@ -32,8 +34,6 @@ export async function turn(input) {
       telemetry: (record) => host.telemetry(JSON.stringify(record ?? null)),
     });
     return {
-      transcriptJson: JSON.stringify(output.transcript),
-      slotsJson: JSON.stringify(output.slots),
       resultJson: output.result === undefined ? undefined : JSON.stringify(output.result),
     };
   } catch (error) {

package/src/index.mjs

@@ -1,6 +1,8 @@
 import { agentloop, component } from "@aexhq/brain";
 import { z } from "zod";
 const options = z.object({
+  environmentSelection: z.enum(["hidden", "model"]).default("hidden"),
+  placements: z.record(z.string(), z.string()).default({}),
   contextWindow: z.number().int().positive().default(200_000),
   // pi defaults (compaction.ts): compact when context exceeds
   // contextWindow - reserveTokens, keep ~keepRecentTokens of recent messages.

package/src/logic.mjs

@@ -1,3 +1,4 @@
+import { toolPlacement } from "../../../shared/tool-placement.mjs";
 import { observeEvents } from "../../../shared/loop-events.mjs";
 
 const CHECKPOINT_PREFIX = "Context checkpoint from earlier in this conversation:\n\n";
@@ -44,6 +45,8 @@ const text = (message) => message.content.filter((block) => block.type === "text
 const blockText = (block) => {
   if (block.type === "text") return block.text;
   if (block.type === "tool_use") return `[tool_use ${block.name}] ${JSON.stringify(block.input)}`;
+  if (block.type === "native") return `[provider continuation state: ${block.format}]`;
+  if (block.type === "image") return block.url.startsWith("https://") ? `[image ${block.url}]` : "[embedded image]";
   const output = typeof block.content === "string" ? block.content : JSON.stringify(block.content);
   return `[tool_result${block.is_error ? " (error)" : ""}] ${output.length > 2000 ? `${output.slice(0, 2000)}…` : output}`;
 };
@@ -59,9 +62,11 @@ export async function runPi(input, context) {
     compaction: true,
     ...input.configuration,
   };
+  const placement = toolPlacement(input.tools, options);
   const transcript = cloneJson(input.transcript);
-  const observed_sequence = await observeEvents(context, transcript, input.slots.observed_sequence ?? 0);
-  const saved = input.slots.checkpoint;
+  const observed_sequence = await observeEvents(context, transcript, input.kv.observed_sequence ?? 0);
+  const saved = input.kv.checkpoint;
+  await context.setKv("observed_sequence", observed_sequence);
   const checkpoint = saved === undefined ? { summary: null } : cloneJson(saved);
   const body = () => checkpoint.summary === null ? transcript : transcript.slice(1);
   const shouldCompact = () =>
@@ -85,26 +90,36 @@ export async function runPi(input, context) {
     if (cut === 0) return;
     const previous = checkpoint.summary === null ? "" : `Previous summary:\n\n${checkpoint.summary}\n\n`;
     const prompt = checkpoint.summary === null ? SUMMARIZATION_PROMPT : `${UPDATE_RULES}${SUMMARIZATION_PROMPT}`;
-    const { message } = await context.model({
+    const { message, stop_reason } = await context.model({
+      response_format: null,
+      tools: [],
       messages: [{ role: "user", content: [{ type: "text", text: `${previous}${serializeConversation(messages.slice(0, cut))}\n\n${prompt}` }] }],
     });
+    if (stop_reason !== "end_turn") throw new Error(`Compaction did not complete: ${stop_reason}`);
     checkpoint.summary = text(message);
     transcript.splice(0, transcript.length,
       { role: "user", content: [{ type: "text", text: `${CHECKPOINT_PREFIX}${checkpoint.summary}` }] },
       ...messages.slice(cut));
   };
 
-  transcript.push({ role: "user", content: [{ type: "text", text: input.input.message }] });
+  transcript.push({ role: "user", content: [{ type: "text", text: input.input.message }, ...(input.input.media ?? [])] });
   for (;;) {
-    if (shouldCompact()) await compact();
-    const { message, stop_reason } = await context.model({ messages: transcript });
+    await context.setTranscript(transcript);
+    if (shouldCompact()) {
+      await compact();
+      await context.setTranscript(transcript);
+      await context.setKv("checkpoint", checkpoint);
+    }
+    const { message, stop_reason } = await context.model({ messages: transcript, tools: placement.definitions });
     transcript.push(message);
+    await context.setTranscript(transcript);
+    await context.setKv("checkpoint", checkpoint);
     const calls = message.content
       .filter((block) => block.type === "tool_use")
       .map((block) => ({ call_id: block.id, name: block.name, input: block.input }));
     if (calls.length === 0) {
       await context.emit("output_emitted", { type: "assistant_message", message: text(message) });
-      return { transcript, slots: { checkpoint, observed_sequence } };
+      return {};
     }
     if (stop_reason === "max_tokens") {
       transcript.push({
@@ -113,7 +128,7 @@ export async function runPi(input, context) {
       });
       continue;
     }
-    const results = await context.dispatch(calls);
+    const results = await context.dispatch(calls.map(placement.invocation));
     const byCall = new Map(results.map((result) => [result.call_id, result]));
     transcript.push({
       role: "user",