portable-agent-layer 0.85.22 → 0.85.24

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -425,6 +425,17 @@ LoadContext.ts
       8. Other recent learnings (other projects, titles only)
 ```
 
+### Injection Budget
+
+Claude Code caps each string a hook injects at **10,000 characters**: plain stdout as a whole, or each JSON field (`additionalContext`, `systemMessage`) on its own. Over the cap, the text is saved to a file and replaced with the file path plus a preview of the first 2,000 characters, and the model is never told to read the file. No setting raises the cap.
+
+Design rules for anything injected by a hook (Tier 3 and per-prompt reminders):
+- Stay under 10,000 characters per hook output.
+- Put what matters most in the first 2,000 characters, in case a future change crosses the cap.
+- Measure before adding a section: pipe a SessionStart payload into `LoadContext.ts` and count the bytes.
+
+Tier 1 and Tier 2 load as memory files, not hook output, so this cap does not apply to them. Other agents' limits are not documented here; check them before relying on the same budget.
+
 ### On-Demand Context
 
 Everything else loads via the routing table in CLAUDE.md. The AI reads files only when the current task requires that context — no upfront loading of the full system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.85.22",
+  "version": "0.85.24",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/doctor/inference.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import { previewInferenceRoute } from "../../hooks/lib/inference";
 import { opencodeBackgroundModel } from "../../hooks/lib/opencode-config";
@@ -51,8 +52,13 @@ export function apiKeyFindings(env: Env): Finding[] {
   );
 }
 
-function routeFinding(): Finding | null {
-  const preview = previewInferenceRoute();
+type Preview = ReturnType<typeof previewInferenceRoute>;
+
+function modelSuffix(preview: Preview): string {
+  return preview.model ? ` on ${preview.model}` : "";
+}
+
+export function routeFinding(preview: Preview = previewInferenceRoute()): Finding | null {
   if (preview.route === "disabled") return null;
   if (preview.route === "none")
     return failing(
@@ -63,10 +69,13 @@ function routeFinding(): Finding | null {
   if (preview.route.endsWith("-api"))
     return warning(
       "inference.api",
-      `Background inference goes through ${preview.route} (${preview.reason}) — it bills the API key`,
+      `Background inference goes through ${preview.route}${modelSuffix(preview)} (${preview.reason}) — it bills the API key`,
       { say: "Put the agent's CLI on PATH to use your subscription instead" }
     );
-  return passed("inference", `Inference: ${preview.route} (${preview.reason})`);
+  return passed(
+    "inference",
+    `Inference: ${preview.route}${modelSuffix(preview)} (${preview.reason})`
+  );
 }
 
 function opencodeModelFinding(): Finding {
@@ -81,11 +90,45 @@ function opencodeModelFinding(): Finding {
       );
 }
 
+function aboutField(about: string, field: string): string | null {
+  const line = about.split("\n").find((l) => l.startsWith(`${field} `));
+  return line ? line.slice(field.length).trim() || null : null;
+}
+
+/** Cursor's free plan refuses every named model, so a pinned one fails all background inference. */
+export function cursorPlanFinding(about: string): Finding | null {
+  const model = aboutField(about, "Model");
+  const tier = aboutField(about, "Subscription Tier");
+  if (!model || !tier) return null;
+  if (tier === "Free" && model !== "Auto")
+    return warning(
+      "cursor.model",
+      `Cursor is set to ${model}, but its free plan only runs Auto — background inference fails`,
+      { say: "Switch Cursor's model to Auto, or upgrade the plan" }
+    );
+  return passed("cursor.model", `Cursor model ${model} runs on the ${tier} plan`);
+}
+
+function cursorAbout(): string {
+  const result = spawnSync("cursor-agent", ["about"], {
+    encoding: "utf-8",
+    shell: true,
+    timeout: 15_000,
+  });
+  return result.status === 0 ? result.stdout : "";
+}
+
+function cursorFindings(): Finding[] {
+  const finding = cursorPlanFinding(cursorAbout());
+  return finding ? [finding] : [];
+}
+
 export function inferenceFindings(agents: AgentName[]): Finding[] {
   const route = routeFinding();
   return [
     ...(route ? [route] : []),
     ...(agents.includes("opencode") ? [opencodeModelFinding()] : []),
+    ...(agents.includes("cursor") ? cursorFindings() : []),
     ...leakedEnvFindings(process.env, process.platform),
     ...apiKeyFindings(process.env),
   ];

package/src/cli/index.ts

@@ -457,7 +457,7 @@ async function probeInference(): Promise<void> {
         );
       } else {
         console.log(
-          `  ${red}✗${reset} ${tag} ${String(elapsedMs).padStart(6)}ms  ${dim}failed — see ~/.pal/debug/debug.log${reset}`
+          `  ${red}✗${reset} ${tag} ${String(elapsedMs).padStart(6)}ms  ${dim}${r.error ?? "failed — see ~/.pal/debug/debug.log"}${reset}`
         );
       }
     }

package/src/hooks/handlers/agenda.ts

@@ -178,7 +178,7 @@ async function guessMissingServes(sessionId?: string): Promise<number> {
     maxTokens: 700,
     timeout: 90000,
     jsonSchema: SERVES_SCHEMA,
-    model: SONNET_MODEL,
+    tier: "medium",
     caller: "agenda-serves",
     sessionId,
   });
@@ -252,7 +252,7 @@ async function refreshGoalLinks(
     maxTokens: 600,
     timeout: 90000,
     jsonSchema: LINKS_SCHEMA,
-    model: SONNET_MODEL,
+    tier: "medium",
     caller: "agenda-goal-links",
     sessionId,
   });
@@ -306,7 +306,7 @@ async function extractWaitingOn(sessionId?: string): Promise<number> {
       maxTokens: 120,
       timeout: 60000,
       jsonSchema: WAITING_SCHEMA,
-      model: SONNET_MODEL,
+      tier: "medium",
       caller: "agenda-waiting-on",
       sessionId,
     });
@@ -352,7 +352,7 @@ async function writeMoves(sessionId?: string): Promise<boolean> {
     maxTokens: 400,
     timeout: 90000,
     jsonSchema: MOVES_SCHEMA,
-    model: SONNET_MODEL,
+    tier: "medium",
     caller: "agenda-moves",
     sessionId,
   });

package/src/hooks/lib/inference.ts

@@ -32,8 +32,13 @@ import {
   isOpencode,
 } from "./agent";
 import { logDebug, logError } from "./log";
-import { HAIKU_MODEL } from "./models";
-import { writeInstructionFreeConfig } from "./opencode-config";
+import {
+  type FixedModelRoute,
+  type InferenceTier,
+  inferenceModel,
+  isFixedModelRoute,
+} from "./models";
+import { opencodeTierModel, writeInstructionFreeConfig } from "./opencode-config";
 import { buildSpawnGuardEnv, getInferenceDepth, SPAWN_GUARD_ENV } from "./spawn-guard";
 import { findBinaryOnPath } from "./which";
 
@@ -45,24 +50,39 @@ export function hasOpenAiKey(): boolean {
   return !!process.env.PAL_OPENAI_API_KEY;
 }
 
+type InferenceRoute =
+  | FixedModelRoute
+  | "opencode-spawn"
+  | "copilot-spawn"
+  | "cursor-spawn"
+  | "disabled"
+  | "none";
+
+interface RoutePreview {
+  agent: string;
+  route: InferenceRoute;
+  reason: string;
+}
+
+function modelFor(route: FixedModelRoute, opts: InferenceOptions): string {
+  return inferenceModel(route, opts.tier);
+}
+
+function smallModelOf(route: InferenceRoute): string | undefined {
+  if (route === "opencode-spawn") return opencodeTierModel("small") ?? undefined;
+  return isFixedModelRoute(route) ? inferenceModel(route, "small") : undefined;
+}
+
 /**
  * Preview what `inference()` would do RIGHT NOW given current env + binaries.
  * Pure diagnostic — never spawns or fetches. Used by `pal cli doctor`.
  */
-export function previewInferenceRoute(): {
-  agent: string;
-  route:
-    | "claude-spawn"
-    | "codex-spawn"
-    | "openai-api"
-    | "opencode-spawn"
-    | "copilot-spawn"
-    | "cursor-spawn"
-    | "anthropic-api"
-    | "disabled"
-    | "none";
-  reason: string;
-} {
+export function previewInferenceRoute(): RoutePreview & { model?: string } {
+  const preview = previewRoute();
+  return { ...preview, model: smallModelOf(preview.route) };
+}
+
+function previewRoute(): RoutePreview {
   const agent = getActiveAgent();
   if (process.env.PAL_INFERENCE_DISABLED === "1") {
     return {
@@ -115,7 +135,8 @@ export function canInfer(): boolean {
 interface InferenceOptions {
   system?: string;
   user: string;
-  model?: string;
+  /** Model size; the active route maps it to that provider's model. Default "small". */
+  tier?: InferenceTier;
   maxTokens?: number;
   timeout?: number;
   /** JSON schema for structured output — guarantees valid JSON matching the schema */
@@ -129,6 +150,8 @@ interface InferenceOptions {
 interface InferenceResult {
   success: boolean;
   output?: string;
+  /** First line of a failed CLI's error output. */
+  error?: string;
   usage?: { inputTokens: number; outputTokens: number };
 }
 
@@ -152,7 +175,7 @@ export async function inference(opts: InferenceOptions): Promise<InferenceResult
     if (bin) {
       logDebug(
         "inference",
-        `${tag} route=claude-spawn agent=${agent} model=${opts.model ?? HAIKU_MODEL}`
+        `${tag} route=claude-spawn agent=${agent} model=${modelFor("claude-spawn", opts)}`
       );
       return inferenceViaClaudeSpawn(bin, opts);
     }
@@ -269,7 +292,7 @@ export function buildClaudeArgs(
   const args = [
     "--print",
     "--model",
-    opts.model ?? HAIKU_MODEL,
+    modelFor("claude-spawn", opts),
     "--tools",
     "",
     "--output-format",
@@ -327,9 +350,11 @@ async function inferenceViaClaudeSpawn(
  * given, so this costs nothing on POSIX and is the only thing that works on
  * Windows. Do not move the prompt back into argv.
  */
-export function buildCodexArgs(_opts: InferenceOptions): string[] {
+export function buildCodexArgs(opts: InferenceOptions): string[] {
   return [
     "exec",
+    "-m",
+    modelFor("codex-spawn", opts),
     "--color",
     "never",
     "--skip-git-repo-check",
@@ -357,8 +382,9 @@ export function buildCodexArgs(_opts: InferenceOptions): string[] {
  * element does not survive cmd.exe on Windows. Provider/model is left unset so
  * opencode uses the user's configured default.
  */
-export function buildOpencodeArgs(_opts: InferenceOptions): string[] {
-  return ["run", "--pure", "--format", "json"];
+export function buildOpencodeArgs(opts: InferenceOptions): string[] {
+  const model = opencodeTierModel(opts.tier ?? "small");
+  return ["run", "--pure", "--format", "json", ...(model ? ["-m", model] : [])];
 }
 
 // Without its own AGENTS.md, opencode falls back to ~/.claude/CLAUDE.md, and it
@@ -520,6 +546,13 @@ export function parseJsonFromOutput(output: string): unknown | null {
   return null;
 }
 
+function firstLine(text: string): string | undefined {
+  return text
+    .split("\n")
+    .find((line) => line.trim())
+    ?.trim();
+}
+
 interface RawSpawnResult {
   code: number | null;
   stdout: string;
@@ -685,7 +718,7 @@ async function inferenceViaCliSpawn(
       "inference:spawn",
       `${tag} exited=${attempt.code} binary=${binaryName} argv=${JSON.stringify(args)} stderr(${attempt.stderr.length})=${attempt.stderr.slice(0, 300)} stdout(${attempt.stdout.length})=${attempt.stdout.slice(0, 300)}`
     );
-    return finish({ success: false });
+    return finish({ success: false, error: firstLine(attempt.stderr || attempt.stdout) });
   }
   const rawText = attempt.stdout.trim();
   if (!rawText) return finish({ success: false });
@@ -716,21 +749,14 @@ async function inferenceViaApi(opts: InferenceOptions): Promise<InferenceResult>
   const apiKey = process.env.PAL_ANTHROPIC_API_KEY;
   if (!apiKey) return { success: false };
 
-  const {
-    system,
-    user,
-    model = HAIKU_MODEL,
-    maxTokens = 200,
-    timeout = 5000,
-    jsonSchema,
-  } = opts;
+  const { system, user, maxTokens = 200, timeout = 5000, jsonSchema } = opts;
 
   try {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
 
     const body: Record<string, unknown> = {
-      model,
+      model: modelFor("anthropic-api", opts),
       max_tokens: maxTokens,
       messages: [{ role: "user", content: user }],
     };
@@ -787,20 +813,11 @@ async function inferenceViaApi(opts: InferenceOptions): Promise<InferenceResult>
 // structured-output schema for JSON-mode callers.
 // ─────────────────────────────────────────────────────────────────────────────
 
-const OPENAI_DEFAULT_MODEL = "gpt-5.4-mini";
-
 async function inferenceViaOpenAiApi(opts: InferenceOptions): Promise<InferenceResult> {
   const apiKey = process.env.PAL_OPENAI_API_KEY;
   if (!apiKey) return { success: false };
 
-  const {
-    system,
-    user,
-    model = OPENAI_DEFAULT_MODEL,
-    maxTokens = 500,
-    timeout = 15000,
-    jsonSchema,
-  } = opts;
+  const { system, user, maxTokens = 500, timeout = 15000, jsonSchema } = opts;
 
   try {
     const controller = new AbortController();
@@ -811,7 +828,7 @@ async function inferenceViaOpenAiApi(opts: InferenceOptions): Promise<InferenceR
     messages.push({ role: "user", content: user });
 
     const body: Record<string, unknown> = {
-      model,
+      model: modelFor("openai-api", opts),
       max_tokens: maxTokens,
       messages,
     };

package/src/hooks/lib/models.ts

@@ -8,6 +8,40 @@ export const HAIKU_MODEL = "claude-haiku-4-5-20251001";
 export const SONNET_MODEL = "claude-sonnet-5";
 export const FABLE_MODEL = "claude-fable-5";
 
+export type InferenceTier = "small" | "medium";
+
+export type FixedModelRoute =
+  | "claude-spawn"
+  | "anthropic-api"
+  | "codex-spawn"
+  | "openai-api";
+
+const ANTHROPIC_MODELS = { small: HAIKU_MODEL, medium: SONNET_MODEL };
+const OPENAI_MODELS = { small: "gpt-6-luna", medium: "gpt-6-sol" };
+
+/**
+ * opencode's models come from the user's own config (opencodeTierModel). Copilot and
+ * Cursor are absent on purpose: which named models they accept depends on the user's
+ * plan, and a free plan refuses every one but Auto.
+ */
+const INFERENCE_MODELS: Record<FixedModelRoute, Record<InferenceTier, string>> = {
+  "claude-spawn": ANTHROPIC_MODELS,
+  "anthropic-api": ANTHROPIC_MODELS,
+  "codex-spawn": OPENAI_MODELS,
+  "openai-api": OPENAI_MODELS,
+};
+
+export function isFixedModelRoute(route: string): route is FixedModelRoute {
+  return Object.hasOwn(INFERENCE_MODELS, route);
+}
+
+export function inferenceModel(
+  route: FixedModelRoute,
+  tier: InferenceTier = "small"
+): string {
+  return INFERENCE_MODELS[route][tier];
+}
+
 /**
  * Per-agent flagship model used to AUTHOR new skills (via `create-skill`).
  *

package/src/hooks/lib/opencode-config.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import type { InferenceTier } from "./models";
 import { platform } from "./paths";
 
 const GLOBAL_CONFIG_FILES = ["config.json", "opencode.json", "opencode.jsonc"];
@@ -17,19 +18,29 @@ function readConfig(name: string): OpencodeConfig | null {
   }
 }
 
-function pinnedModel(config: OpencodeConfig | null): string | null {
-  return typeof config?.model === "string" && config.model ? config.model : null;
+function pinnedModel(config: OpencodeConfig | null, key = "model"): string | null {
+  const value = config?.[key];
+  return typeof value === "string" && value ? value : null;
 }
 
-/** Without a pinned model, `opencode run` falls back to whatever was last picked in the TUI. */
-export function opencodeBackgroundModel(): string | null {
+function firstPinned(key: string): string | null {
   for (const name of GLOBAL_CONFIG_FILES) {
-    const model = pinnedModel(readConfig(name));
+    const model = pinnedModel(readConfig(name), key);
     if (model) return model;
   }
   return null;
 }
 
+/** Without a pinned model, `opencode run` falls back to whatever was last picked in the TUI. */
+export function opencodeBackgroundModel(): string | null {
+  return firstPinned("model");
+}
+
+export function opencodeTierModel(tier: InferenceTier): string | null {
+  const small = tier === "small" ? firstPinned("small_model") : null;
+  return small ?? opencodeBackgroundModel();
+}
+
 function withoutInstructions(config: OpencodeConfig): OpencodeConfig {
   const { instructions: _, ...rest } = config;
   return rest;

package/src/tools/self-model.ts

@@ -84,7 +84,7 @@ async function composeSelfModel(days: number): Promise<string> {
   const result = await inference({
     system: buildPrompt(ai.name, principal.name),
     user: inferenceUserContent(rawData, readFileOrEmpty(selfModelPath())),
-    model: SONNET_MODEL,
+    tier: "medium",
     maxTokens: 1500,
     timeout: 90000,
     caller: "self-model",