@aexhq/agentloop-pi 0.0.0 → 1.2.0

package/index.d.ts

@@ -0,0 +1,14 @@
+import type { Agentloop } from "@aexhq/brain";
+
+export interface PiOptions {
+  /** 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. */
+  readonly reserveTokens?: number;
+  /** Approximate tokens of recent conversation kept verbatim through a compaction. pi default 20000. */
+  readonly keepRecentTokens?: number;
+  /** Disable automatic compaction entirely. Default true (enabled). */
+  readonly compaction?: boolean;
+}
+
+export declare const pi: (options?: PiOptions) => Agentloop;

package/package.json

@@ -1,19 +1,41 @@
 {
   "name": "@aexhq/agentloop-pi",
-  "version": "0.0.0",
-  "description": "Reserved package name; no stable release is available.",
-  "license": "Apache-2.0",
+  "version": "1.2.0",
+  "description": "Pi-style parallel-Tool Brain extension",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aexhq/extensions.git",
+    "directory": "packages/loop-pi"
+  },
   "type": "module",
-  "exports": "./index.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./dist/index.mjs" },
+    "./package.json": "./package.json"
+  },
   "files": [
-    "index.js"
+    "dist",
+    "src",
+    "index.d.ts",
+    "README.md"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aexhq/extensions.git"
+  "scripts": {
+    "build": "brain build src/index.mjs --out dist",
+    "test": "npm run build && node --test",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@aexhq/brain": "0.11.0",
+    "zod": "4.4.3"
   },
-  "aexHoldPlaceholder": {
-    "stagedVersion": "1.1.0",
-    "source": "720d4ff2ae98f7df85fcd54a53a36ccbd6f03230"
-  }
+  "devDependencies": {}
 }

package/src/compat.mjs

@@ -0,0 +1,33 @@
+// StarlingMonkey compatibility rewrites for pi's dependency tree, applied while bundling.
+// COMPAT (recorded in the H0 report): the pinned guest engine rejects Unicode property
+// escapes in regex literals at parse time. typebox (a pi dependency) emits `\p{ID_Start}` in
+// its identifier guard and builds IDN validators from `\p{…}` classes; the guard rewrites to
+// an ASCII-equivalent class and the unused IDN modules stub out.
+import { readFile } from "node:fs/promises";
+
+const UNICODE_ID_REGEX_PATTERN = /\/\^\[\\p\{ID_Start\}[^/]*\*\$\/u/g;
+const ASCII_ID_REGEX = String.raw`/^[A-Za-z_$][A-Za-z0-9_$]*$/`;
+
+/** esbuild plugin for `buildLoopBundle({ plugins: [compatRewrite] })`. */
+export const compatRewrite = {
+  name: "starlingmonkey-compat",
+  setup(b) {
+    b.onLoad({ filter: /typebox[\\/].*\.mjs$/ }, async (args) => {
+      if (/[\\/]format[\\/]idn_email\.mjs$/.test(args.path)) {
+        return { contents: "export function IsIdnEmail(){return false;}", loader: "js" };
+      }
+      if (/[\\/]format[\\/]_idna\.mjs$/.test(args.path)) {
+        return {
+          contents:
+            "export function IsIdnLabel(){return false;}\nexport function IsLabel(){return false;}",
+          loader: "js",
+        };
+      }
+      let contents = await readFile(args.path, "utf8");
+      if (UNICODE_ID_REGEX_PATTERN.test(contents)) {
+        contents = contents.replace(UNICODE_ID_REGEX_PATTERN, ASCII_ID_REGEX);
+      }
+      return { contents, loader: "js" };
+    });
+  },
+};

package/src/index.mjs

@@ -0,0 +1,219 @@
+import { agentloop } from "@aexhq/brain";
+import { z } from "zod";
+
+// Semantic port of the pi coding agent's loop, pinned against
+// earendil-works/pi tag v0.84.4 (@earendil-works/pi-agent-core@0.84.4,
+// packages/agent/src/agent-loop.ts + packages/coding-agent/src/core/compaction/compaction.ts).
+//
+// The published loop is an async driver: one invocation awaits the LLM stream
+// and every tool execution internally, so it cannot run inside Brain's
+// deterministic synchronous sandbox. This port reproduces its per-turn
+// contract instead:
+// - tool calls are issued as one parallel batch, results return as one
+//   user message of tool_result blocks in assistant source order
+// - a length-stop that carries tool calls fails the whole batch without
+//   executing it, and the loop re-asks the model
+// - automatic compaction: when the estimated context exceeds
+//   contextWindow - reserveTokens, everything older than ~keepRecentTokens
+//   is summarized into a structured context checkpoint that replaces it
+//   (cut points never split a tool_result away from its tool_use)
+// Host-app seams of pi (steering and follow-up queues, per-tool
+// executionMode) have no Brain equivalent and are not ported.
+
+const optionsSchema = z.object({
+  contextWindow: z.number().int().positive().default(200_000),
+  // pi defaults (compaction.ts): compact when context exceeds
+  // contextWindow - reserveTokens, keep ~keepRecentTokens of recent messages.
+  reserveTokens: z.number().int().positive().default(16_384),
+  keepRecentTokens: z.number().int().positive().default(20_000),
+  compaction: z.boolean().default(true),
+}).default({});
+
+const stateSchema = z.object({
+  messages: z.array(z.unknown()),
+  summary: z.union([z.string(), z.null()]),
+  compacting: z.boolean(),
+  keepFrom: z.number().int().nonnegative(),
+  pending: z.array(z.object({ callId: z.string(), name: z.string() })),
+});
+
+const SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
+
+Use this EXACT format:
+
+## Goal
+
+## Constraints & Preferences
+
+## Progress
+
+### Done
+
+### In Progress
+
+### Blocked
+
+## Key Decisions
+
+## Next Steps
+
+## Critical Context
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`;
+
+const UPDATE_RULES = `Update the existing structured summary with new information.
+
+RULES:
+- PRESERVE all existing information from the previous summary
+- ADD new progress, decisions, and context from the new messages
+- Move items from In Progress to Done as they complete
+
+`;
+
+const TRUNCATED_CALL_MESSAGE =
+  "Tool call was not executed: the model response was cut off by the output token limit, so the arguments may be truncated. Re-issue the tool call.";
+
+const blockText = (block) => {
+  if (block.type === "text") return block.text;
+  if (block.type === "tool_use") return `[tool_use ${block.name}] ${JSON.stringify(block.input)}`;
+  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}`;
+};
+
+const serializeConversation = (messages) =>
+  messages.map((message) => `${message.role}:\n${message.content.map(blockText).join("\n")}`).join("\n\n");
+
+export const pi = agentloop({ options: optionsSchema }, (author) => {
+  const options = author.options;
+  const state = author.state(stateSchema, () => ({
+    messages: [],
+    summary: null,
+    compacting: false,
+    keepFrom: 0,
+    pending: [],
+  }));
+
+  const context = () =>
+    state.summary === null
+      ? state.messages
+      : [
+          {
+            role: "user",
+            content: [{ type: "text", text: `Context checkpoint from earlier in this conversation:\n\n${state.summary}` }],
+          },
+          ...state.messages,
+        ];
+
+  const shouldCompact = () =>
+    options.compaction && author.context.estimateTokens(context()) > options.contextWindow - options.reserveTokens;
+
+  // Earliest index the recent-token budget allows, then forward to the next
+  // boundary that does not split a tool_result away from its tool_use.
+  const cutPoint = () => {
+    let kept = 0;
+    let cut = 0;
+    for (let index = state.messages.length - 1; index >= 0; index -= 1) {
+      kept += author.context.estimateTokens([state.messages[index]]);
+      if (kept > options.keepRecentTokens) {
+        cut = index + 1;
+        break;
+      }
+    }
+    while (
+      cut < state.messages.length &&
+      state.messages[cut].role === "user" &&
+      state.messages[cut].content.some((block) => block.type === "tool_result")
+    ) {
+      cut += 1;
+    }
+    return cut;
+  };
+
+  const compact = (turn) => {
+    state.keepFrom = cutPoint();
+    if (state.keepFrom === 0) return turn.model({ messages: context() });
+    state.compacting = true;
+    const previous = state.summary === null ? "" : `Previous summary:\n\n${state.summary}\n\n`;
+    const prompt = state.summary === null ? SUMMARIZATION_PROMPT : `${UPDATE_RULES}${SUMMARIZATION_PROMPT}`;
+    return turn.model({
+      messages: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "text",
+              text: `${previous}${serializeConversation(state.messages.slice(0, state.keepFrom))}\n\n${prompt}`,
+            },
+          ],
+        },
+      ],
+    });
+  };
+
+  const advance = (turn) => (shouldCompact() ? compact(turn) : turn.model({ messages: context() }));
+
+  author.on.message(({ input }, turn) => {
+    state.messages.push({ role: "user", content: [{ type: "text", text: input.message }] });
+    return advance(turn);
+  });
+
+  author.on.model((completed, turn) => {
+    const { message, stop_reason } = completed.response;
+    if (state.compacting) {
+      state.summary = message.content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("");
+      state.messages = state.messages.slice(state.keepFrom);
+      state.compacting = false;
+      state.keepFrom = 0;
+      return turn.model({ messages: context() });
+    }
+    const calls = message.content
+      .filter((block) => block.type === "tool_use")
+      .map((block) => ({ callId: block.id, name: block.name, input: block.input }));
+    state.messages.push(message);
+    if (calls.length > 0 && stop_reason === "max_tokens") {
+      // pi fails the whole batch without executing it when the response was
+      // cut off: the arguments cannot be trusted.
+      state.messages.push({
+        role: "user",
+        content: calls.map((call) => ({
+          type: "tool_result",
+          tool_use_id: call.callId,
+          content: TRUNCATED_CALL_MESSAGE,
+          is_error: true,
+        })),
+      });
+      return advance(turn);
+    }
+    if (calls.length > 0) {
+      state.pending = calls.map(({ callId, name }) => ({ callId, name }));
+      return turn.tools(calls);
+    }
+    const text = message.content
+      .filter((block) => block.type === "text")
+      .map((block) => block.text)
+      .join("");
+    return turn.reply(text);
+  });
+
+  author.on.tools((completed, turn) => {
+    const byCall = new Map(completed.results.map((result) => [result.call_id, result]));
+    state.messages.push({
+      role: "user",
+      // Assistant source order, the order pi appends result messages in.
+      content: state.pending.map(({ callId }) => {
+        const result = byCall.get(callId);
+        return {
+          type: "tool_result",
+          tool_use_id: callId,
+          content: result === undefined ? "Tool produced no result." : result.output,
+          is_error: result === undefined ? true : result.is_error,
+        };
+      }),
+    });
+    state.pending = [];
+    return advance(turn);
+  });
+});

package/src/polyfill.mjs

@@ -0,0 +1,14 @@
+// Runs before the workload bundle's top-level code (ESM evaluation order).
+if (typeof globalThis.TextEncoder === "undefined") {
+  globalThis.TextEncoder = class TextEncoder {
+    encode(s) {
+      const bytes = unescape(encodeURIComponent(String(s)));
+      const out = new Uint8Array(bytes.length);
+      for (let i = 0; i < bytes.length; i++) out[i] = bytes.charCodeAt(i);
+      return out;
+    }
+  };
+}
+if (typeof globalThis.structuredClone === "undefined") {
+  globalThis.structuredClone = (v) => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+}

package/index.js

@@ -1 +0,0 @@
-throw new Error("@aexhq/agentloop-pi has no stable release; install @aexhq/agentloop-pi@next or an exact version");