portable-agent-layer 0.70.0 → 0.72.0

package/src/hooks/lib/security-gate.ts

@@ -0,0 +1,159 @@
+/**
+ * The gate's decision, separated from the process that carries it out.
+ *
+ * SecurityValidator is spawned, so nothing can import it and nothing measures
+ * it — every rule about which tool names run a shell, which argument spells the
+ * path, and what the agent is told was unreachable from a test. The decision
+ * lives here instead; the entrypoint is left with stdin, stdout and the ledger.
+ */
+
+import { normalizeToolUse } from "./agent";
+import { logDebug } from "./log";
+import { checkBashCommand, checkFilePath } from "./security";
+
+/** beforeShellExecution (Cursor only) — flat, no tool-name wrapper. */
+interface ShellExecInput {
+  command: string;
+  sandbox?: boolean;
+}
+
+export type SecurityInput = Record<string, unknown> | ShellExecInput;
+
+export interface GateRefusal {
+  tool: string;
+  /** The file, or the directory a refused command would have run in. */
+  target: string;
+  /** Set only when a shell was refused: it has no file to name. */
+  command?: string;
+  /** Why, for the ledger. */
+  reason: string;
+  /** Why, in the words the agent is given — the two differ only by framing. */
+  message: string;
+  hookEventName?: string;
+}
+
+// A name this list misses is a command this hook waves through, so both sets mirror
+// the tool names VS Code's own Copilot build ships in its shell and edit tool sets.
+const SHELL_TOOLS = [
+  "bash",
+  "shell",
+  "powershell",
+  "local_shell",
+  "runinterminal",
+  "run_in_terminal",
+  "terminal",
+  "execute_command",
+];
+
+const FILE_WRITE_TOOLS = [
+  "write",
+  "edit",
+  "multiedit",
+  "write_file",
+  "apply_patch",
+  "applypatch",
+  "create",
+  "create_file",
+  "createfile",
+  "str_replace",
+  "str_replace_editor",
+  "insert",
+  "insert_edit_into_file",
+  "replace_string_in_file",
+  "multi_replace_string_in_file",
+  "replacestring",
+  "edit_notebook_file",
+  "notebookedit",
+];
+
+function isShellExec(input: SecurityInput): input is ShellExecInput {
+  return !("tool_name" in input) && !("toolName" in input) && "command" in input;
+}
+
+/** First of `keys` present as a non-empty string — agents disagree on argument spelling. */
+function firstStringArg(
+  args: Record<string, unknown>,
+  keys: string[]
+): string | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/** Tool names that run a shell command, across every agent's naming. */
+function runsShellCommand(toolName: string): boolean {
+  return SHELL_TOOLS.includes(toolName.toLowerCase());
+}
+
+/** Tool names that write to a file, across every agent's naming. */
+function writesFile(toolName: string): boolean {
+  return FILE_WRITE_TOOLS.includes(toolName.toLowerCase());
+}
+
+/**
+ * What the gate would do with this call, or null to let it through.
+ *
+ * `cwd` is passed rather than read so a test can pin the target of a refused
+ * command, which has no file of its own to name.
+ */
+export function decideRefusal(input: SecurityInput, cwd: string): GateRefusal | null {
+  if (isShellExec(input)) {
+    const reason = checkBashCommand(input.command);
+    if (!reason) return null;
+    return {
+      tool: "shell",
+      target: cwd,
+      command: input.command,
+      reason,
+      message: `Blocked: ${reason}`,
+    };
+  }
+
+  const toolUse = normalizeToolUse(input);
+  if (!toolUse) return null;
+
+  // Each agent names its shell/write tools differently; log the real name so an
+  // unrecognized one shows up here instead of silently skipping the check.
+  logDebug(
+    "SecurityValidator",
+    `toolName=${toolUse.toolName} args=${Object.keys(toolUse.toolInput).join(",")}`
+  );
+
+  const command = firstStringArg(toolUse.toolInput, ["command", "commandLine", "script"]);
+  if (runsShellCommand(toolUse.toolName) && command) {
+    const reason = checkBashCommand(command);
+    // "No output" from a downstream tool is indistinguishable between "denied,
+    // never ran" and "ran, produced nothing" — logging the verdict here, next
+    // to the literal command, is what actually tells the two apart.
+    const verdict = reason ? `BLOCK(${reason})` : "ALLOW";
+    logDebug("SecurityValidator", `bashVerdict=${verdict} command=${command}`);
+    if (reason) {
+      return {
+        tool: toolUse.toolName,
+        target: cwd,
+        command,
+        reason,
+        message: `Blocked: ${reason}`,
+        hookEventName: toolUse.hookEventName,
+      };
+    }
+  }
+
+  const filePath = firstStringArg(toolUse.toolInput, ["file_path", "filePath", "path"]);
+  if (writesFile(toolUse.toolName) && filePath) {
+    const reason = checkFilePath(filePath);
+    if (reason) {
+      return {
+        tool: toolUse.toolName,
+        target: filePath,
+        reason,
+        message: reason,
+        hookEventName: toolUse.hookEventName,
+      };
+    }
+  }
+
+  return null;
+}

package/src/hooks/lib/serves.ts

@@ -0,0 +1,60 @@
+/**
+ * What a project is for, and what that makes it worth.
+ *
+ * Importance cannot be read off a repository: two projects with identical
+ * activity can be a client's livelihood and a weekend toy. So the record carries
+ * one fact PAL guesses and the user can overrule — never a name or a rank
+ * written into source, because next month the same code serves something else.
+ */
+
+import {
+  readProject,
+  type ServesAuthority,
+  type ServesKind,
+  writeProject,
+} from "./projects";
+
+export const SERVES_KINDS: ServesKind[] = ["goal", "revenue", "fun"];
+
+export const SERVES_MEANING: Record<ServesKind, string> = {
+  goal: "serves a stated goal",
+  revenue: "a way this could pay",
+  fun: "kept for its own sake",
+};
+
+/** A goal and a revenue bet are worth protecting time for; fun is not. */
+export function isImportant(kind: ServesKind | undefined): boolean {
+  return kind === "goal" || kind === "revenue";
+}
+
+export function isServesKind(value: unknown): value is ServesKind {
+  return typeof value === "string" && SERVES_KINDS.includes(value as ServesKind);
+}
+
+export interface ServesUpdate {
+  name: string;
+  kind: ServesKind;
+  note?: string;
+  by: ServesAuthority;
+}
+
+/**
+ * A guess never overwrites an answer. This is the whole reason the record
+ * stores who decided: re-inference runs freely and the user is only asked once.
+ *
+ * Writing does bump `updated`, like every other write to the record — a hobby
+ * project that becomes the thing people depend on should rank as touched the
+ * moment that is written down, not fourteen days later.
+ */
+export function setServes(update: ServesUpdate): "written" | "kept" | "missing" {
+  const project = readProject(update.name);
+  if (!project) return "missing";
+  if (update.by === "inferred" && project.serves_by === "user") return "kept";
+
+  project.serves = update.kind;
+  project.serves_by = update.by;
+  if (update.note) project.serves_note = update.note;
+  project.updated = new Date().toISOString();
+  writeProject(project);
+  return "written";
+}

package/src/hooks/lib/session-context.ts

@@ -0,0 +1,74 @@
+/**
+ * What each agent is handed at session start, and in which envelope.
+ *
+ * The four runtimes disagree on all of it: whether AGENTS.md is already loaded,
+ * which JSON key carries injected context, and whether it is read from stdout at
+ * all. This has been wrong in production before — Copilot silently received no
+ * context for weeks — and none of it was reachable from a test.
+ */
+
+export interface ContextEnvelope {
+  /** Whether the agent parses stdout as JSON or reads it as raw text. */
+  kind: "json" | "text";
+  payload: string;
+  /** Copilot only: the same context, also written where its extension reads. */
+  file?: string;
+}
+
+/**
+ * A subagent gets none of this. Its parent already carries the context, and
+ * paying for it again on every spawn is the whole cost of a cheap subagent.
+ */
+export function isSubagentSession(env: NodeJS.ProcessEnv): boolean {
+  if (env.CLAUDE_AGENT_TYPE !== undefined) return true;
+  return env.CLAUDE_PROJECT_DIR?.includes("/.claude/Agents/") ?? false;
+}
+
+/**
+ * Copilot and Cursor read AGENTS.md natively from nothing, so it is prepended
+ * here; Codex reaches it through a symlink and Claude Code loads it itself.
+ */
+export function needsAgentsMd(agent: string): boolean {
+  return agent === "copilot" || agent === "cursor";
+}
+
+/**
+ * Copilot also writes the same text to a file, because its CLI reads stdout
+ * while the VS Code extension reads only ~/.copilot/instructions/.
+ */
+export function contextEnvelope(
+  agent: string,
+  reminder: string,
+  agentsMd: string
+): ContextEnvelope | null {
+  const merged = needsAgentsMd(agent)
+    ? [agentsMd, reminder].filter(Boolean).join("\n\n")
+    : reminder;
+  if (!merged) return null;
+
+  if (agent === "copilot") {
+    return {
+      kind: "json",
+      payload: JSON.stringify({ additionalContext: merged }),
+      file: merged,
+    };
+  }
+  if (agent === "cursor") {
+    return { kind: "json", payload: JSON.stringify({ additional_context: merged }) };
+  }
+  if (agent === "codex") {
+    return {
+      kind: "json",
+      payload: JSON.stringify({
+        hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: merged },
+      }),
+    };
+  }
+  // Claude Code, and opencode which uses the plugin path rather than this hook.
+  return { kind: "text", payload: merged };
+}
+
+/** The file Copilot's VS Code extension reads, with the applyTo header it needs. */
+export function copilotInstructions(context: string): string {
+  return `---\napplyTo: "**"\n---\n\n${context}`;
+}

package/src/hooks/lib/stop.ts

@@ -50,6 +50,7 @@ export async function runStopHandlers(
   // inference and write results to disk; they don't block this hook.
   await detachSessionIntelligence(transcript, options.sessionId);
   await detachFailurePrinciple(transcript);
+  detachAgenda(options.sessionId);
   // Failure auto-graduation is intentionally NOT wired here: every pattern it
   // ever promoted was a frustration log, not a principle. Wisdom frames are
   // populated by Claude in-conversation (see wisdom.ts header). The handler
@@ -161,6 +162,19 @@ async function writeTranscriptTmp(transcript: string): Promise<string> {
   return file;
 }
 
+/**
+ * The agenda reads files, not the transcript, so it needs no tmp copy — but it
+ * calls a model, so it detaches like the others. It no-ops on a fresh agenda.
+ */
+function detachAgenda(sessionId?: string): void {
+  try {
+    const scriptPath = resolve(assets.hooks(), "handlers", "agenda.ts");
+    spawnDetachedInference(scriptPath, ["--run", sessionId ?? ""], "agenda");
+  } catch (err) {
+    logError("detachAgenda", err);
+  }
+}
+
 /** Spawn a detached child to run session-intelligence on a tmp copy of the transcript. */
 async function detachSessionIntelligence(
   transcript: string,

package/src/hooks/lib/telos-goals.ts

@@ -0,0 +1,144 @@
+/**
+ * The user's stated goals, read as ranked items rather than prose.
+ *
+ * A goal belongs on the morning screen next to the projects — "find clients"
+ * outranks every repository and is not one. Parsing is deliberately deterministic:
+ * the page must render without a model call, so a date is found by reading, not
+ * by asking.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { palHome } from "./paths";
+
+export interface TelosGoal {
+  id: string;
+  title: string;
+  text: string;
+  /** Horizon heading the entry sat under, when GOALS.md uses them. */
+  horizon: string | null;
+  /** First date the entry names, as an ISO day. */
+  due: string | null;
+}
+
+const MONTHS = [
+  "january",
+  "february",
+  "march",
+  "april",
+  "may",
+  "june",
+  "july",
+  "august",
+  "september",
+  "october",
+  "november",
+  "december",
+];
+
+const ISO_DAY = /\b(\d{4})-(\d{2})-(\d{2})\b/;
+const MONTH_YEAR = new RegExp(String.raw`\b(${MONTHS.join("|")})\s+(\d{4})\b`, "i");
+const QUARTER = /\bQ([1-4])\s*,?\s*(\d{4})\b/i;
+
+function endOfMonth(year: number, monthIndex: number): string {
+  return new Date(Date.UTC(year, monthIndex + 1, 0)).toISOString().slice(0, 10);
+}
+
+/** The last day the entry could still be met, which is what urgency measures against. */
+export function dueFrom(text: string): string | null {
+  const iso = ISO_DAY.exec(text);
+  if (iso) return iso[0];
+
+  const monthYear = MONTH_YEAR.exec(text);
+  if (monthYear) {
+    return endOfMonth(Number(monthYear[2]), MONTHS.indexOf(monthYear[1].toLowerCase()));
+  }
+
+  const quarter = QUARTER.exec(text);
+  if (quarter) return endOfMonth(Number(quarter[2]), Number(quarter[1]) * 3 - 1);
+
+  return null;
+}
+
+function firstSentenceOf(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  const match = new RegExp(/^.*?[.!?](?=\s|$)/).exec(flat);
+  return match ? match[0] : flat;
+}
+
+function slug(title: string, index: number): string {
+  const base = title
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, "")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 5)
+    .join("-");
+  return base || `goal-${index + 1}`;
+}
+
+function isScaffolding(line: string): boolean {
+  const l = line.trim();
+  return !l || l.startsWith("<!--") || l.startsWith("-->") || /^(-{3,}|_{3,})$/.test(l);
+}
+
+/**
+ * Bullets are entries when a block has them; otherwise the paragraph is the
+ * entry. Both shapes ship — the scaffold offers horizon headings with bullets,
+ * and people write prose anyway.
+ */
+function entriesIn(lines: string[]): string[] {
+  const bullets = lines
+    .filter((l) => /^\s*[-*+]\s+\S/.test(l))
+    .map((l) => l.replace(/^\s*[-*+]\s+/, "").trim());
+  if (bullets.length > 0) return bullets;
+  const paragraph = lines.join(" ").trim();
+  return paragraph ? [paragraph] : [];
+}
+
+function goalsFrom(content: string): TelosGoal[] {
+  const goals: TelosGoal[] = [];
+  let horizon: string | null = null;
+  let block: string[] = [];
+
+  const flush = () => {
+    for (const text of entriesIn(block)) {
+      const title = firstSentenceOf(text);
+      goals.push({
+        id: slug(title, goals.length),
+        title,
+        text: text.replace(/\s+/g, " ").trim(),
+        horizon,
+        due: dueFrom(text),
+      });
+    }
+    block = [];
+  };
+
+  for (const line of content.split("\n")) {
+    if (line.trim().startsWith("#")) {
+      flush();
+      const heading = line.replace(/^#+\s*/, "").trim();
+      horizon = /^goals$/i.test(heading) ? null : heading;
+      continue;
+    }
+    if (isScaffolding(line)) {
+      flush();
+      continue;
+    }
+    block.push(line);
+  }
+  flush();
+
+  return goals;
+}
+
+export function readTelosGoals(home: string = palHome()): TelosGoal[] {
+  const path = resolve(home, "telos", "GOALS.md");
+  if (!existsSync(path)) return [];
+  try {
+    return goalsFrom(readFileSync(path, "utf-8"));
+  } catch {
+    return [];
+  }
+}

package/src/hooks/lib/telos-topics.ts

@@ -0,0 +1,68 @@
+/**
+ * The TELOS topics, and the one rule for whether a topic has been answered.
+ *
+ * Install does not ask these questions any more — the onboarding skill does,
+ * whenever the user is ready to answer them. Both that skill and the doctor
+ * read the answer from here through `pal cli telos`, so the prose in the skill
+ * cannot drift away from the code that decides.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { palHome } from "./paths";
+
+interface TelosTopic {
+  key: string;
+  file: string;
+  /** Interviewed first, and the only ones the doctor reports on. */
+  priority: boolean;
+}
+
+const TELOS_TOPICS: TelosTopic[] = [
+  { key: "mission", file: "telos/MISSION.md", priority: true },
+  { key: "goals", file: "telos/GOALS.md", priority: true },
+  { key: "challenges", file: "telos/CHALLENGES.md", priority: true },
+  { key: "strategies", file: "telos/STRATEGIES.md", priority: true },
+  { key: "beliefs", file: "telos/BELIEFS.md", priority: true },
+  { key: "models", file: "telos/MODELS.md", priority: false },
+  { key: "narratives", file: "telos/NARRATIVES.md", priority: false },
+  { key: "learned", file: "telos/LEARNED.md", priority: false },
+  { key: "ideas", file: "telos/IDEAS.md", priority: false },
+];
+
+/** A shipped scaffold is headings, comments, rules and empty bullets — nothing said. */
+function isScaffolding(line: string): boolean {
+  const l = line.trim();
+  if (!l) return true;
+  if (l.startsWith("#")) return true;
+  if (l.startsWith("<!--") || l.startsWith("-->")) return true;
+  if (/^(-{3,}|\*{3,}|_{3,})$/.test(l)) return true;
+  return /^[-*+]$/.test(l);
+}
+
+/**
+ * Anything the scaffold did not put there counts, table rows included.
+ * @lintignore exercised directly by test/telos-topics.test.ts
+ */
+export function hasRealContent(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    return readFileSync(filePath, "utf-8")
+      .split("\n")
+      .some((line) => !isScaffolding(line));
+  } catch {
+    return false;
+  }
+}
+
+export interface TopicStatus extends TelosTopic {
+  path: string;
+  answered: boolean;
+}
+
+export function telosStatus(home: string = palHome()): TopicStatus[] {
+  return TELOS_TOPICS.map((topic) => {
+    const path = resolve(home, topic.file);
+    return { ...topic, path, answered: hasRealContent(path) };
+  });
+}

package/src/hooks/lib/token-usage.ts

@@ -14,7 +14,9 @@ type TokenCaller =
   | "session-name"
   | "session-intelligence"
   | "relationship"
-  | "self-model";
+  | "self-model"
+  | "agenda-serves"
+  | "agenda-moves";
 
 interface TokenUsageEntry {
   ts: string;

package/src/hooks/lib/wall-clock.ts

@@ -0,0 +1,58 @@
+/**
+ * The one fact that goes stale inside a session: the time.
+ *
+ * The session-start reminder stamps the clock once, so a conversation picked up
+ * the next morning still believes it is yesterday. This line rides along with
+ * every prompt instead, in the principal's own timezone, because "is it morning"
+ * is the question the agent keeps getting wrong.
+ */
+
+import { identity, isEnabled } from "./settings";
+
+const FIELDS = {
+  weekday: "short",
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+  hour: "2-digit",
+  minute: "2-digit",
+  hourCycle: "h23",
+} as const;
+
+function fieldsIn(now: Date, timeZone: string): Record<string, string> {
+  const parts = new Intl.DateTimeFormat("en-US", { ...FIELDS, timeZone }).formatToParts(
+    now
+  );
+  return Object.fromEntries(parts.map((p) => [p.type, p.value]));
+}
+
+/** The IANA name Intl settles on, or null when it does not recognise the input. */
+export function canonicalTimeZone(timeZone: string): string | null {
+  try {
+    return new Intl.DateTimeFormat("en-US", { timeZone }).resolvedOptions().timeZone;
+  } catch {
+    return null;
+  }
+}
+
+export function isValidTimeZone(timeZone: string): boolean {
+  return canonicalTimeZone(timeZone) !== null;
+}
+
+/** A configured timezone is user input, and Intl throws on a bad one. UTC is always true. */
+function zoneOrUtc(timeZone: string): string {
+  return timeZone && isValidTimeZone(timeZone) ? timeZone : "UTC";
+}
+
+/** @lintignore exercised directly by test/wall-clock.test.ts */
+export function wallClockLine(now: Date, configuredZone: string): string {
+  const zone = zoneOrUtc(configuredZone);
+  const f = fieldsIn(now, zone);
+  return `Now: ${f.weekday} ${f.year}-${f.month}-${f.day} ${f.hour}:${f.minute} ${zone}`;
+}
+
+export function getWallClockReminder(now: Date = new Date()): string | null {
+  if (!isEnabled("wallClock")) return null;
+  const line = wallClockLine(now, identity().principal.timezone);
+  return `<system-reminder>${line}</system-reminder>`;
+}