portable-agent-layer 0.91.8 → 0.92.0

package/README.md

@@ -85,6 +85,7 @@ pal cli status        # check your setup
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
 | `pal cli analyze [--actionable]` | Learning analysis: rating trends, failure patterns, graduation candidates |
 | `pal cli usage` | Summarize token usage and estimated cost |
+| `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium`, `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |
 | `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
 | `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
 | `pal cli telos` | Which TELOS topics are answered, in interview order, and which one comes next |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.91.8",
+  "version": "0.92.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   },
   "scripts": {
     "type-check": "tsc --noEmit",
-    "test": "bun test --randomize",
+    "test": "bun test --randomize --isolate",
     "test:mutate": "stryker run",
     "test:mutate:diff": "bun .agents/scripts/mutate-diff.ts",
     "format": "biome format",
@@ -107,6 +107,7 @@
     "marked": "18.0.4",
     "pdf-lib": "1.17.1",
     "playwright": "^1.60.0",
-    "unpdf": "^0.12.0"
+    "unpdf": "^0.12.0",
+    "zod": "^4.4.3"
   }
 }

package/src/cli/infer.ts

@@ -0,0 +1,142 @@
+/**
+ * pal cli infer — one inference call through PAL's own route, for programs
+ * outside an agent session. The route, its model for each tier, and the
+ * isolation from PAL's hooks are the same ones PAL's background calls use.
+ */
+
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { inference } from "../hooks/lib/inference";
+import { INFERENCE_TIERS, type InferenceTier } from "../hooks/lib/models";
+import { leaf } from "../tools/lib/command";
+
+const DEFAULT_TIMEOUT_SECONDS = 60;
+
+interface InferValues {
+  tier?: string;
+  system?: string;
+  schema?: string;
+  timeout?: string;
+  caller?: string;
+}
+
+type Infer = typeof inference;
+
+class InferInputError extends Error {}
+
+function tierOf(name = "small"): InferenceTier {
+  const tier = INFERENCE_TIERS.find((known) => known === name);
+  if (!tier) {
+    throw new InferInputError(
+      `Unknown tier "${name}". Use ${INFERENCE_TIERS.join(", ")}.`
+    );
+  }
+  return tier;
+}
+
+function timeoutMs(seconds = String(DEFAULT_TIMEOUT_SECONDS)): number {
+  const value = Number(seconds);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new InferInputError(`--timeout takes a number of seconds, not "${seconds}".`);
+  }
+  return value * 1000;
+}
+
+function promptOf(stdin: string): string {
+  const prompt = stdin.trim();
+  if (!prompt) throw new InferInputError("No prompt: pipe it in on stdin.");
+  return prompt;
+}
+
+function readSchema(path: string): Record<string, unknown> {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    throw new InferInputError(`--schema ${path} is not a readable JSON file.`);
+  }
+}
+
+function assertCheckable(path: string, schema: Record<string, unknown>): void {
+  try {
+    z.fromJSONSchema(schema);
+  } catch (err) {
+    throw new InferInputError(
+      `--schema ${path} cannot be checked: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+function schemaFrom(path: string | undefined): Record<string, unknown> | undefined {
+  if (!path) return undefined;
+  const schema = readSchema(path);
+  assertCheckable(path, schema);
+  return schema;
+}
+
+function requestFrom(values: InferValues, stdin: string): Parameters<Infer>[0] {
+  return {
+    user: promptOf(stdin),
+    system: values.system ? readFileSync(values.system, "utf-8") : undefined,
+    jsonSchema: schemaFrom(values.schema),
+    tier: tierOf(values.tier),
+    timeout: timeoutMs(values.timeout),
+    caller: values.caller ?? "cli-infer",
+  };
+}
+
+function failureReason(result: Awaited<ReturnType<Infer>>, wantedJson: boolean): string {
+  if (result.error) return result.error;
+  if (wantedJson && result.output) return "the reply was not JSON";
+  return "no inference route answered (run `pal cli doctor`)";
+}
+
+export async function inferFromCli(
+  values: InferValues,
+  stdin: string,
+  infer: Infer = inference
+): Promise<number> {
+  let request: Parameters<Infer>[0];
+  try {
+    request = requestFrom(values, stdin);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+  const result = await infer(request);
+  if (!result.success || !result.output) {
+    console.error(
+      `Inference failed: ${failureReason(result, Boolean(request.jsonSchema))}`
+    );
+    return 1;
+  }
+  console.log(result.output);
+  return 0;
+}
+
+export const inferCommand = leaf({
+  summary: "Run one inference call on the active agent's model; prompt on stdin",
+  options: {
+    tier: {
+      type: "string",
+      value: "<tier>",
+      description: `Model size: ${INFERENCE_TIERS.join(" or ")} (default small)`,
+    },
+    system: { type: "string", value: "<file>", description: "System prompt file" },
+    schema: {
+      type: "string",
+      value: "<file>",
+      description: "JSON schema file; a reply that doesn't match it fails",
+    },
+    timeout: {
+      type: "string",
+      value: "<seconds>",
+      description: `Give up after this long (default ${DEFAULT_TIMEOUT_SECONDS})`,
+    },
+    caller: {
+      type: "string",
+      value: "<label>",
+      description: "Label for PAL's debug log",
+    },
+  },
+  run: async ({ values }) => inferFromCli(values, await Bun.stdin.text()),
+});

package/src/cli/tree.ts

@@ -15,6 +15,7 @@ import {
 } from "../tools/lib/command";
 import { builtinTools, builtinToolVerbs } from "./builtin-tools";
 import { identityCommand } from "./identity";
+import { inferCommand } from "./infer";
 import { knowledgeCommand } from "./knowledge";
 import { ledgerCommand } from "./ledger-command";
 import { runMigrate } from "./migrate";
@@ -150,6 +151,7 @@ export function cliTree(admin: AdminHandlers): Group {
     commands: {
       ...adminCommands(admin),
       usage: usageCommand,
+      infer: inferCommand,
       actor: identityCommand("actor"),
       machine: identityCommand("machine"),
       telos: telosCommand,

package/src/hooks/lib/inference.ts

@@ -23,6 +23,7 @@
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
+import { z } from "zod";
 import {
   getActiveAgent,
   isAntigravity,
@@ -151,7 +152,7 @@ interface InferenceOptions {
   tier?: InferenceTier;
   maxTokens?: number;
   timeout?: number;
-  /** JSON schema for structured output — guarantees valid JSON matching the schema */
+  /** JSON schema the reply must match; a reply that doesn't fails with the reason */
   jsonSchema?: Record<string, unknown>;
   /** Opaque label identifying the calling handler — appears in debug logs as caller=X */
   caller?: string;
@@ -167,7 +168,34 @@ interface InferenceResult {
   usage?: { inputTokens: number; outputTokens: number };
 }
 
+function schemaProblem(
+  output: string,
+  schema: Record<string, unknown>
+): string | undefined {
+  const checked = z.fromJSONSchema(schema).safeParse(parseJsonFromOutput(output));
+  if (checked.success) return undefined;
+  return checked.error.issues
+    .map((issue) => `${issue.path.join(".") || "reply"}: ${issue.message}`)
+    .join("; ");
+}
+
 export async function inference(opts: InferenceOptions): Promise<InferenceResult> {
+  const result = await routeInference(opts);
+  if (!opts.jsonSchema || !result.success || !result.output) return result;
+  const problem = schemaProblem(result.output, opts.jsonSchema);
+  if (!problem) return result;
+  logError(
+    "inference",
+    `caller=${opts.caller ?? "anonymous"} schema mismatch: ${problem}`
+  );
+  return {
+    ...result,
+    success: false,
+    error: `the reply does not match the schema: ${problem}`,
+  };
+}
+
+async function routeInference(opts: InferenceOptions): Promise<InferenceResult> {
   // Hard kill-switch — set by the test suite to guarantee no real inference
   // ever fires from tests (no spawn, no API call). Production code never sets it.
   if (process.env.PAL_INFERENCE_DISABLED === "1") {

package/src/hooks/lib/models.ts

@@ -9,7 +9,8 @@ export const HAIKU_5_5_MODEL = "claude-haiku-5-5";
 export const SONNET_MODEL = "claude-sonnet-5";
 export const FABLE_MODEL = "claude-fable-5";
 
-export type InferenceTier = "small" | "medium";
+export const INFERENCE_TIERS = ["small", "medium"] as const;
+export type InferenceTier = (typeof INFERENCE_TIERS)[number];
 
 export type FixedModelRoute =
   | "claude-spawn"

package/src/hooks/lib/paths.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import { isAbsolute, relative, resolve } from "node:path";
 
 /**
@@ -62,8 +62,12 @@ export function palPkg(): string {
  * Always resolves to ~/.pal/ regardless of where the package lives.
  * Power users who want memory/telos versioned in a repo can override via PAL_HOME.
  */
+function sandboxPalHome(): string {
+  return resolve(import.meta.dir, "..", "..", "..", ".test", "pal-home");
+}
+
 function defaultPalHome(): string {
-  if (process.env.PAL_TEST_SANDBOX) return resolve(tmpdir(), "pal-test-home");
+  if (process.env.PAL_TEST_SANDBOX) return sandboxPalHome();
   return resolve(homedir(), ".pal");
 }