portable-agent-layer 0.91.8 → 0.93.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/assets/schema/pal-settings.schema.json

@@ -98,6 +98,14 @@
           "type": "boolean",
           "description": "Let the rules you approved from your past corrections steer the agent: a rule triggered by your prompt is injected before the agent answers, and a reply that matches a rule's trigger is sent back to the agent once at stop. Each firing is logged to memory/adaptation/rule-events.jsonl. Set false to switch every rule off. Reply-side rules do not run on Cursor, whose stop payload carries no reply text, or on opencode, whose plugin does not run the stop check."
         },
+        "entityCards": {
+          "type": "boolean",
+          "description": "When a prompt names a person or company from the knowledge store, inject a short card about them before the agent answers. Reads files only; no model call."
+        },
+        "entityExtraction": {
+          "type": "boolean",
+          "description": "After a session stops, ask a background model which people and companies your own messages mentioned, and write clear matches and new full names to the knowledge store with the message as source. A name that could be more than one entry, or a first name alone, waits for `pal cli knowledge review` instead."
+        },
         "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
       }
     },

package/assets/templates/pal-settings.json

@@ -33,6 +33,8 @@
     "claimCheck": true,
     "claimCheckBlocks": false,
     "adaptationRules": true,
+    "entityCards": true,
+    "entityExtraction": true,
     "steeringTestReport": false
   },
   "steering": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.91.8",
+  "version": "0.93.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/knowledge.ts

@@ -6,6 +6,13 @@
  */
 
 import { readFileSync } from "node:fs";
+import type { ReviewItem } from "../hooks/lib/entity-extraction";
+import {
+  type AcceptChoice,
+  acceptReview,
+  pendingReviews,
+  rejectReview,
+} from "../hooks/lib/entity-review";
 import { toPath } from "../hooks/lib/paths";
 import { buildGraph, resolveSlug, stats, traverse } from "../tools/knowledge/graph";
 import {
@@ -113,6 +120,36 @@ export const knowledgeCommand = group({
       },
       run: ({ values }) => cmdIngest(values.source ?? "manual", values.file),
     }),
+    review: group({
+      summary: "People and companies the background extractor would not guess",
+      fallback: "list",
+      commands: {
+        list: leaf({ summary: "Show what waits for an answer", run: cmdReviewList }),
+        accept: leaf({
+          summary: "Write an item, to an existing entry (--as) or a new one",
+          args: "<id>",
+          options: {
+            as: {
+              type: "string",
+              value: "<slug>",
+              description: "Existing entry to update",
+            },
+            name: {
+              type: "string",
+              value: "<name>",
+              description: "Name for a new entry (default: as extracted)",
+            },
+          },
+          run: ({ positionals, values }) =>
+            cmdReviewAccept(positionals[0], { as: values.as, name: values.name }),
+        }),
+        reject: leaf({
+          summary: "Drop an item without writing it",
+          args: "<id>",
+          run: ({ positionals }) => cmdReviewReject(positionals[0]),
+        }),
+      },
+    }),
   },
   details: VOCABULARY,
 });
@@ -578,3 +615,63 @@ async function cmdIngest(sourceId: string, file: string | undefined): Promise<nu
   console.log(JSON.stringify(summary, null, 2));
   return 0;
 }
+
+// ── review ─────────────────────────────────────────────────────────
+
+function reviewReason(reason: ReviewItem["reason"]): string {
+  const reasons: Record<ReviewItem["reason"], string> = {
+    ambiguous: "could be more than one known entry",
+    "unknown-existing": "named an entry the store does not have",
+    "first-name-only": "first name only",
+  };
+  return reasons[reason];
+}
+
+function reviewLines(item: ReviewItem): string[] {
+  const { kind, name, fact } = item.entity;
+  const candidates =
+    item.candidates.length > 0 ? `could be: ${item.candidates.join(", ")}` : "";
+  return [
+    `  ${item.id}  ${kind} "${name}" — ${reviewReason(item.reason)}`,
+    ...[fact, candidates, `from ${item.source}`]
+      .filter(Boolean)
+      .map((line) => `            ${line}`),
+  ];
+}
+
+function cmdReviewList(): number {
+  const items = pendingReviews();
+  if (items.length === 0) {
+    console.log("Nothing waits for review.");
+    return 0;
+  }
+  console.log(`\n${items.length} waiting for review\n`);
+  for (const item of items) console.log(reviewLines(item).join("\n"));
+  console.log(
+    "\nAccept: pal cli knowledge review accept <id> [--as <slug>] [--name <name>]\nReject: pal cli knowledge review reject <id>\n"
+  );
+  return 0;
+}
+
+function acceptOrExplain(id: string, choice: AcceptChoice) {
+  try {
+    return acceptReview(id, choice);
+  } catch (err) {
+    throw new UsageError(err instanceof Error ? err.message : String(err));
+  }
+}
+
+function cmdReviewAccept(id: string, choice: AcceptChoice): number {
+  const accepted = acceptOrExplain(id, choice);
+  if (!accepted) throw new UsageError(`no review item "${id}"`);
+  const verb = accepted.created ? "Created" : "Updated";
+  console.log(`${verb} ${accepted.slug} from "${accepted.item.entity.name}".`);
+  return 0;
+}
+
+function cmdReviewReject(id: string): number {
+  const rejected = rejectReview(id);
+  if (!rejected) throw new UsageError(`no review item "${id}"`);
+  console.log(`Dropped "${rejected.entity.name}".`);
+  return 0;
+}

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/handlers/entity-extraction.ts

@@ -0,0 +1,85 @@
+/**
+ * Stop handler: learn the people and companies the user mentioned since the last
+ * stop, so the prompt-time cards know them next time. Runs detached; one model
+ * call at most, and only when the new text names someone.
+ */
+
+import { ingestEntities } from "../../tools/knowledge/ingest";
+import { excludedNames, loadKnownEntities, loadNameIndex } from "../lib/entity-cards";
+import {
+  extractionSchema,
+  extractionSystem,
+  extractionUser,
+  markSeen,
+  parseExtraction,
+  planExtraction,
+  queueForReview,
+  seenCount,
+  unseenUserText,
+  worthExtracting,
+} from "../lib/entity-extraction";
+import { canInfer, inference } from "../lib/inference";
+import { logDebug, logError } from "../lib/log";
+import { identity, isEnabled } from "../lib/settings";
+import { logTokenUsage } from "../lib/token-usage";
+import { parseMessages } from "../lib/transcript";
+
+function sourceId(sessionId: string, count: number): string {
+  return `chat ${new Date().toISOString().slice(0, 10)} ${sessionId.slice(0, 8)} #${count}`;
+}
+
+/** @lintignore exercised directly by test/entity-extraction.test.ts */
+export async function extractSessionEntities(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  if (!sessionId || !isEnabled("entityExtraction")) return;
+  const seen = seenCount(sessionId);
+  const { text, count } = unseenUserText(parseMessages(transcript), seen);
+  if (count <= seen) return;
+
+  const index = loadNameIndex(loadKnownEntities());
+  const excluded = excludedNames();
+  markSeen(sessionId, count);
+  if (!worthExtracting(text, index, excluded) || !canInfer()) return;
+
+  const id = identity();
+  const result = await inference({
+    system: extractionSystem(id.principal.name, id.ai.name),
+    user: extractionUser(text, index),
+    tier: "medium",
+    maxTokens: 900,
+    timeout: 90000,
+    jsonSchema: extractionSchema(),
+    caller: "entity-extraction",
+    sessionId,
+  });
+  if (result.usage) logTokenUsage("entity-extraction", result.usage);
+  if (!result.success || !result.output) return;
+
+  const source = sourceId(sessionId, count);
+  const plan = planExtraction(parseExtraction(result.output), index, excluded, source);
+  const written = ingestEntities(plan.ingest, source);
+  queueForReview(plan.review);
+  logDebug(
+    "entity-extraction",
+    `${written.people.length} people, ${written.companies.length} companies, ${plan.review.length} for review`
+  );
+}
+
+if (process.argv[2] === "--run") {
+  const sid = process.argv[3];
+  const transcriptPath = process.argv[4];
+  if (transcriptPath) {
+    const { readFile, unlink } = await import("node:fs/promises");
+    try {
+      const transcript = await readFile(transcriptPath, "utf-8");
+      await extractSessionEntities(transcript, sid === "" ? undefined : sid);
+    } catch (err) {
+      logError("entity-extraction:run", err);
+    } finally {
+      await unlink(transcriptPath).catch(() => {});
+    }
+  }
+  process.exit(0);
+}

package/src/hooks/handlers/inject-retrieval.ts

@@ -10,6 +10,7 @@
 import { promptRulesReminder } from "../lib/adaptation-steering";
 import { promptContextResponse } from "../lib/agent";
 import { dueNudgeReminder } from "../lib/daily-nudge";
+import { getEntityReminder } from "../lib/entity-cards";
 import { observeTurn } from "../lib/interaction";
 import { logDebug, logError } from "../lib/log";
 import { parkPromptContext } from "../lib/parked-context";
@@ -91,6 +92,9 @@ export async function getPromptContext(
     withinBudget(() => dueNudgeReminder(), BUDGET_MS),
     userText && getSteeringReminder(userText),
     userText && getSkillReminder(userText),
+    userText &&
+      isEnabled("entityCards") &&
+      withinBudget(() => getEntityReminder(userText), BUDGET_MS),
     userText && (await getRetrievalReminder(userText)),
   ].filter((p): p is string => Boolean(p));
 

package/src/hooks/lib/daily-nudge.ts

@@ -3,9 +3,10 @@ import { resolve } from "node:path";
 import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { loadAnalyzeNudge } from "./analyze-nudge";
+import { loadEntityReviewNudge } from "./entity-review";
 import { ensureDir, paths } from "./paths";
 import { loadReactionAuditNudge } from "./reaction-audit";
-import { isOptedIn } from "./settings";
+import { isEnabled, isOptedIn } from "./settings";
 import { localDay } from "./wall-clock";
 
 type ShownOn = Record<string, string>;
@@ -14,6 +15,7 @@ interface DueNudge {
   key: string;
   command: string;
   load: () => string;
+  enabled?: () => boolean;
 }
 
 const DUE_NUDGES: DueNudge[] = [
@@ -27,6 +29,27 @@ const DUE_NUDGES: DueNudge[] = [
   { key: "analyze", command: "/pal-analyze", load: loadAnalyzeNudge },
 ];
 
+function entityReviewNudge(): DueNudge {
+  return {
+    key: "entity-review",
+    command: "pal cli knowledge review",
+    load: loadEntityReviewNudge,
+    enabled: () => isEnabled("entityExtraction"),
+  };
+}
+
+function dueNudges(): DueNudge[] {
+  return [...DUE_NUDGES, entityReviewNudge()];
+}
+
+function dueRemindersOn(): boolean {
+  return isOptedIn("dueReminders");
+}
+
+function isSwitchedOn(nudge: DueNudge): boolean {
+  return (nudge.enabled ?? dueRemindersOn)();
+}
+
 function shownPath(): string {
   return resolve(ensureDir(paths.state()), "nudges-shown.json");
 }
@@ -53,7 +76,7 @@ export function pendingToday(
 }
 
 export function acknowledgeMentioned(reply: string, now: Date = new Date()): void {
-  const mentioned = DUE_NUDGES.filter((nudge) => reply.includes(nudge.command));
+  const mentioned = dueNudges().filter((nudge) => reply.includes(nudge.command));
   if (!mentioned.length) return;
   const today = localDay(now);
   const shownOn = readShownOn();
@@ -62,10 +85,10 @@ export function acknowledgeMentioned(reply: string, now: Date = new Date()): voi
 }
 
 export function dueNudgeSections(now: Date = new Date()): string[] {
-  if (!isOptedIn("dueReminders")) return [];
-  return DUE_NUDGES.map((nudge) => pendingToday(nudge.key, nudge.load(), now)).filter(
-    Boolean
-  );
+  return dueNudges()
+    .filter(isSwitchedOn)
+    .map((nudge) => pendingToday(nudge.key, nudge.load(), now))
+    .filter(Boolean);
 }
 
 export function dueNudgeReminder(now: Date = new Date()): string | null {

package/src/hooks/lib/entity-cards.ts

@@ -0,0 +1,112 @@
+/**
+ * Prompt-time cards for the people and companies a prompt names, so the user
+ * never has to re-explain who someone is. Reads files only; no model call.
+ */
+
+import { type Entity, list } from "../../tools/knowledge/lib";
+import {
+  buildNameIndex,
+  entityKey,
+  findMentions,
+  type Mention,
+  type NamedEntity,
+  type NameIndex,
+} from "./entity-names";
+import { identity } from "./settings";
+
+const MAX_CARDS = 3;
+const MAX_LATEST = 160;
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === "string")
+    : [];
+}
+
+function textField(entity: Entity, key: string): string {
+  const value = entity.frontmatter[key];
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function namedEntity(entity: Entity): NamedEntity {
+  return {
+    slug: entity.slug,
+    domain: entity.domain === "Companies" ? "Companies" : "People",
+    title: entity.frontmatter.title,
+    aliases: stringList(entity.frontmatter.aliases),
+    domainName: textField(entity, "domain_name") || undefined,
+  };
+}
+
+export function loadKnownEntities(rootDir?: string): Entity[] {
+  return [...list("People", rootDir), ...list("Companies", rootDir)];
+}
+
+export function excludedNames(): string[] {
+  const id = identity();
+  return [id.principal.name, id.ai.name];
+}
+
+export function loadNameIndex(entities: Entity[]): NameIndex {
+  return buildNameIndex(entities.map(namedEntity), excludedNames());
+}
+
+function isSourceLine(line: string): boolean {
+  return (
+    line.startsWith("### ") ||
+    line.startsWith("<!--") ||
+    /^(?:role|importance|mentioned_as|sentiment): /.test(line)
+  );
+}
+
+/** The newest thing the store learned about this entity, in a sentence or two. */
+export function latestNote(body: string): string {
+  const sections = body.split(/\n(?=### )/);
+  const text = (sections.at(-1) ?? "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l && !isSourceLine(l))
+    .join(" ")
+    .replace(/\*\*/g, "");
+  return text.length > MAX_LATEST ? `${text.slice(0, MAX_LATEST - 1)}…` : text;
+}
+
+function describe(entity: Entity): string {
+  const fields =
+    entity.domain === "People"
+      ? [
+          textField(entity, "position") || textField(entity, "role"),
+          textField(entity, "company"),
+        ]
+      : [textField(entity, "industry")];
+  const facts = [...fields, textField(entity, "relation")].filter(
+    (f) => f && f !== "subject"
+  );
+  const latest = latestNote(entity.body);
+  return [facts.join(", "), latest].filter(Boolean).join(". ");
+}
+
+function card(mention: Mention, bySlug: Map<string, Entity>): string {
+  if (mention.entities.length > 1) {
+    const names = mention.entities.map((e) => e.title).join(", ");
+    return `- "${mention.said}" could be: ${names}. Ask which one if it matters.`;
+  }
+  const entity = bySlug.get(entityKey(mention.entities[0]));
+  const summary = entity ? describe(entity) : "";
+  const name = `- **${mention.entities[0].title}**`;
+  return summary ? `${name}: ${summary}` : name;
+}
+
+export function entityReminder(prompt: string, entities: Entity[]): string | null {
+  const mentions = findMentions(prompt, loadNameIndex(entities)).slice(0, MAX_CARDS);
+  if (mentions.length === 0) return null;
+  const bySlug = new Map(entities.map((e) => [entityKey(e), e]));
+  return [
+    "**Known people and companies in this message** (PAL knowledge store):",
+    ...mentions.map((m) => card(m, bySlug)),
+  ].join("\n");
+}
+
+export function getEntityReminder(prompt: string): string | null {
+  return entityReminder(prompt, loadKnownEntities());
+}