portable-agent-layer 0.25.0 → 0.26.1

package/assets/skills/telos/tools/update-projects.ts

@@ -38,64 +38,69 @@ function isoDate(): string {
   return new Date().toISOString().replace("T", " ").slice(0, 19);
 }
 
-const args = process.argv.slice(2);
-const id = args[0];
-const row = args[1];
-const description = args[2];
-
-if (!id || !row || !description) {
-  console.error('Usage: bun update-projects.ts <id> "<row>" "<description>"');
-  console.error(
-    '\nExample: bun update-projects.ts my-proj "| my-proj | My Project | In progress | High | Notes |" "Added My Project"'
-  );
-  process.exit(1);
+export interface UpsertProjectResult {
+  file: string;
+  id: string;
+  mode: "replaced" | "appended";
+  backed_up: boolean;
+  logged: boolean;
+  description: string;
 }
 
-// Backup
-mkdirSync(BACKUPS_DIR, { recursive: true });
-if (existsSync(PROJECTS_FILE)) {
-  const backupName = `PROJECTS-${timestamp()}.md`;
-  copyFileSync(PROJECTS_FILE, resolve(BACKUPS_DIR, backupName));
-}
+export function upsertProject(
+  id: string,
+  row: string,
+  description: string
+): UpsertProjectResult {
+  mkdirSync(BACKUPS_DIR, { recursive: true });
+  if (existsSync(PROJECTS_FILE)) {
+    const backupName = `PROJECTS-${timestamp()}.md`;
+    copyFileSync(PROJECTS_FILE, resolve(BACKUPS_DIR, backupName));
+  }
+
+  const existing = existsSync(PROJECTS_FILE) ? readFileSync(PROJECTS_FILE, "utf-8") : "";
+
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const idPattern = new RegExp(`^\\|\\s*${escapedId}\\s*\\|.*$`, "m");
+  let mode: "replaced" | "appended";
 
-const existing = existsSync(PROJECTS_FILE) ? readFileSync(PROJECTS_FILE, "utf-8") : "";
+  if (idPattern.test(existing)) {
+    writeFileSync(PROJECTS_FILE, existing.replace(idPattern, row.trim()), "utf-8");
+    mode = "replaced";
+  } else {
+    const separator = existing.trim() ? "\n" : "";
+    writeFileSync(
+      PROJECTS_FILE,
+      `${existing.trimEnd()}${separator}${row.trim()}\n`,
+      "utf-8"
+    );
+    mode = "appended";
+  }
 
-const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-const idPattern = new RegExp(`^\\|\\s*${escapedId}\\s*\\|.*$`, "m");
-let mode: "replaced" | "appended";
+  const logEntry = `- **${isoDate()}** — \`PROJECTS.md\` [${id}]: ${description}`;
+  const existingLog = existsSync(UPDATES_LOG)
+    ? readFileSync(UPDATES_LOG, "utf-8")
+    : "# TELOS Updates\n";
+  writeFileSync(UPDATES_LOG, `${existingLog.trimEnd()}\n${logEntry}\n`, "utf-8");
 
-if (idPattern.test(existing)) {
-  const updated = existing.replace(idPattern, row.trim());
-  writeFileSync(PROJECTS_FILE, updated, "utf-8");
-  mode = "replaced";
-} else {
-  const separator = existing.trim() ? "\n" : "";
-  writeFileSync(
-    PROJECTS_FILE,
-    `${existing.trimEnd()}${separator}${row.trim()}\n`,
-    "utf-8"
-  );
-  mode = "appended";
+  return { file: "PROJECTS.md", id, mode, backed_up: true, logged: true, description };
 }
 
-// Log change
-const logEntry = `- **${isoDate()}** — \`PROJECTS.md\` [${id}]: ${description}`;
-const existingLog = existsSync(UPDATES_LOG)
-  ? readFileSync(UPDATES_LOG, "utf-8")
-  : "# TELOS Updates\n";
-writeFileSync(UPDATES_LOG, `${existingLog.trimEnd()}\n${logEntry}\n`, "utf-8");
+function run() {
+  const args = process.argv.slice(2);
+  const id = args[0];
+  const row = args[1];
+  const description = args[2];
+
+  if (!id || !row || !description) {
+    console.error('Usage: bun update-projects.ts <id> "<row>" "<description>"');
+    console.error(
+      '\nExample: bun update-projects.ts my-proj "| my-proj | My Project | In progress | High | Notes |" "Added My Project"'
+    );
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify(upsertProject(id, row, description), null, 2));
+}
 
-console.log(
-  JSON.stringify(
-    {
-      file: "PROJECTS.md",
-      id,
-      mode,
-      backed_up: true,
-      logged: true,
-      description,
-    },
-    null,
-    2
-  )
-);
+if (import.meta.main) run();

package/assets/templates/AGENTS.md.template

@@ -58,7 +58,6 @@ Start your response with the following header in this mode:
 
 ---
 
-{{SETUP_PROMPT}}
 ## Context Routing
 
 When you need context about any of these topics, read `~/.pal/docs/CONTEXT_ROUTING.md` for the file path:

package/package.json

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

package/src/cli/index.ts

@@ -22,6 +22,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { palHome, palPkg, platform } from "../hooks/lib/paths";
+import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 import { log } from "../targets/lib";
 
 const allArgs = process.argv.slice(2);
@@ -460,19 +461,16 @@ function doctor(silent = false): DoctorResult {
         : fail("CLAUDE.md — missing (run 'pal cli install --claude')");
     }
 
-    // Setup state
-    const setupPath = resolve(home, "memory", "state", "setup.json");
-    if (existsSync(setupPath)) {
-      try {
-        const setup = JSON.parse(readFileSync(setupPath, "utf-8"));
-        setup?.completed
-          ? ok("TELOS setup complete")
-          : warn("TELOS setup incomplete — run 'pal cli install' or start a session");
-      } catch {
-        warn("TELOS setup — could not read setup.json");
-      }
-    } else {
-      warn("TELOS setup — setup.json missing (run 'pal cli install')");
+    // Setup state — check file content directly (no setup.json dependency)
+    {
+      const missing = STEP_ORDER.filter(
+        (key) => !hasRealContent(resolve(home, SETUP_STEPS[key].file))
+      );
+      missing.length === 0
+        ? ok("TELOS setup complete")
+        : warn(
+            `TELOS setup incomplete — ${missing.join(", ")} missing (run 'pal cli install')`
+          );
     }
 
     // Skills (per installed agent)
@@ -574,7 +572,6 @@ function doctor(silent = false): DoctorResult {
 // ── Commands ──
 
 async function init(args: string[]) {
-  const { ensureSetupState, isSetupComplete } = await import("../hooks/lib/setup");
   const { scaffoldTelos } = await import("../targets/lib");
 
   banner();
@@ -591,17 +588,10 @@ async function init(args: string[]) {
   mkdirSync(resolve(home, "memory"), { recursive: true });
 
   scaffoldTelos();
-  ensureSetupState();
 
   // Auto-detect available targets
   const targets = resolveTargets(args, health);
   await install(targets);
-
-  console.log("");
-  const state = ensureSetupState();
-  if (!isSetupComplete(state)) {
-    log.info("Start a session — PAL will guide you through first-run setup");
-  }
 }
 
 async function install(targets: Targets) {
@@ -620,9 +610,11 @@ async function install(targets: Targets) {
   // Scaffold TELOS + PAL settings, then prompt for missing identity
   const { scaffoldTelos, scaffoldPalSettings } = await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");
+  const { promptTelos } = await import("./setup-telos");
   scaffoldTelos();
   scaffoldPalSettings();
   await promptIdentity();
+  await promptTelos();
 
   if (targets.claude) {
     console.log("━━━ Claude Code ━━━");

package/src/cli/setup-telos.ts

@@ -0,0 +1,120 @@
+/**
+ * Interactive TELOS setup — prompts for personal context during `pal install`.
+ * Skips any step whose TELOS file already has real content.
+ * Projects use the upsertProject tool directly with a structured add-another loop.
+ */
+
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import * as clack from "@clack/prompts";
+import { upsertProject } from "../../assets/skills/telos/tools/update-projects";
+import { palHome } from "../hooks/lib/paths";
+import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
+
+function toKebabCase(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+async function promptProjectsLoop(): Promise<void> {
+  const addFirst = await clack.confirm({
+    message: "Do you want to add any projects now?",
+    initialValue: true,
+  });
+  if (clack.isCancel(addFirst) || !addFirst) return;
+
+  let addMore = true;
+  while (addMore) {
+    const name = await clack.text({
+      message: "Project name?",
+      placeholder: "e.g. PAL, My SaaS, Work Dashboard",
+    });
+    if (clack.isCancel(name)) return;
+
+    const status = await clack.select({
+      message: "Status?",
+      options: [
+        { value: "Active", label: "Active" },
+        { value: "Planning", label: "Planning" },
+        { value: "Paused", label: "Paused" },
+        { value: "Complete", label: "Complete" },
+      ],
+    });
+    if (clack.isCancel(status)) return;
+
+    const priority = await clack.select({
+      message: "Priority?",
+      options: [
+        { value: "High", label: "High" },
+        { value: "Medium", label: "Medium" },
+        { value: "Low", label: "Low" },
+      ],
+    });
+    if (clack.isCancel(priority)) return;
+
+    const notes = await clack.text({
+      message: "Notes? (optional — leave blank to skip)",
+      placeholder: "e.g. Building the v2 API, blocked on design review",
+    });
+    if (clack.isCancel(notes)) return;
+
+    const id = toKebabCase(name as string);
+    const row = `| ${id} | ${name} | ${status} | ${priority} | ${notes || ""} |`;
+    upsertProject(id, row, `Added ${name} during PAL setup`);
+    clack.log.success(`Added: ${name}`);
+
+    const again = await clack.confirm({
+      message: "Add another project?",
+      initialValue: false,
+    });
+    if (clack.isCancel(again) || !again) addMore = false;
+  }
+}
+
+/** Prompt for missing TELOS context. Skips any step whose file already has real content. */
+export async function promptTelos(): Promise<void> {
+  // Skip interactive prompts in non-TTY environments (tests, CI)
+  if (!process.stdin.isTTY) return;
+
+  const home = palHome();
+  const pending = STEP_ORDER.filter(
+    (key) => !hasRealContent(resolve(home, SETUP_STEPS[key].file))
+  );
+
+  if (pending.length === 0) {
+    clack.log.info("TELOS already configured");
+    return;
+  }
+
+  clack.intro("Personal Context Setup");
+  clack.note(
+    "Answer in a sentence or two — you can edit the files in ~/.pal/telos/ for more detail later.",
+    "Quick setup"
+  );
+
+  for (const key of pending) {
+    if (key === "projects") {
+      await promptProjectsLoop();
+    } else {
+      const step = SETUP_STEPS[key];
+      const title = key.charAt(0).toUpperCase() + key.slice(1);
+
+      const answer = await clack.text({
+        message: step.question,
+        placeholder: step.hint,
+      });
+
+      if (clack.isCancel(answer)) {
+        clack.cancel("Setup cancelled");
+        return;
+      }
+
+      const filePath = resolve(home, step.file);
+      writeFileSync(filePath, `# ${title}\n\n${answer}\n`, "utf-8");
+    }
+  }
+
+  clack.outro("Personal context saved ✓");
+}

package/src/hooks/lib/claude-md.ts

@@ -19,7 +19,6 @@ import {
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { assets, ensureDir, paths, platform } from "./paths";
-import { buildSetupPrompt, readSetupState } from "./setup";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
 
@@ -114,14 +113,11 @@ import { identity } from "./settings";
 export function buildClaudeMd(): string {
   const template = existsSync(TEMPLATE_PATH)
     ? readFileSync(TEMPLATE_PATH, "utf-8")
-    : "# PAL Context\n\n{{SETUP_PROMPT}}\n";
+    : "# PAL Context\n";
 
-  const state = readSetupState();
-  const setupPrompt = state ? buildSetupPrompt(state) : null;
   const id = identity();
 
   return template
-    .replace("{{SETUP_PROMPT}}", setupPrompt ? `${setupPrompt}\n` : "")
     .replaceAll("{{IDENTITY_NAME}}", id.ai.name)
     .replaceAll("{{IDENTITY_DISPLAY}}", id.ai.displayName)
     .replaceAll("{{IDENTITY_CATCHPHRASE}}", id.ai.catchphrase)

package/src/hooks/lib/context.ts

@@ -13,7 +13,7 @@ import { paths } from "./paths";
 import { loadRecentNotes } from "./relationship";
 import { readSessionNames } from "./session-names";
 import * as settings from "./settings";
-import { buildSetupPrompt, readSetupState, remainingSteps, STEP_ORDER } from "./setup";
+import { isSetupComplete, readSetupState, remainingSteps, STEP_ORDER } from "./setup";
 import { computeSignalTrends, formatTrends } from "./signal-trends";
 import { readFramePrinciples } from "./wisdom";
 import { readProjectHistory, readSessions, recentSessions } from "./work-tracking";
@@ -141,12 +141,12 @@ export function buildGreeting(): string[] {
   const counts = loadCachedCounts();
   const work = loadActiveWork();
   const setupState = readSetupState();
-  const setupPrompt = setupState ? buildSetupPrompt(setupState) : null;
+  const setupIncomplete = setupState && !isSetupComplete(setupState);
 
   const greeting: string[] = [];
 
-  if (setupPrompt) {
-    const done = STEP_ORDER.length - (setupState ? remainingSteps(setupState).length : 0);
+  if (setupIncomplete) {
+    const done = STEP_ORDER.length - remainingSteps(setupState).length;
     greeting.push(
       `🔧 PAL setup ${done}/${STEP_ORDER.length} | ${counts.signals} signals`
     );

package/src/hooks/lib/setup.ts

@@ -23,31 +23,33 @@ export interface SetupState {
 }
 
 /** Ordered setup steps — defines the wizard flow */
-const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
+export const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
   mission: {
     file: "telos/MISSION.md",
-    question: "What do you do? What's your role and core purpose?",
-    hint: "Write their role and core purpose to telos/MISSION.md",
+    question:
+      "What do you do? What's your role and core purpose? (~/.pal/telos/MISSION.md)",
+    hint: "e.g. Senior software engineer building developer tooling at Acme Corp",
   },
   goals: {
     file: "telos/GOALS.md",
-    question: "What are your current goals? (short-term, medium-term, long-term)",
-    hint: "Write goals organized by timeframe to telos/GOALS.md",
+    question:
+      "What are your current goals? (short-term, medium-term, long-term) (~/.pal/telos/GOALS.md)",
+    hint: "e.g. Ship v2 by Q3, learn Rust, get promoted to staff engineer",
   },
   projects: {
     file: "telos/PROJECTS.md",
-    question: "What projects are you currently working on?",
-    hint: "Write to telos/PROJECTS.md using table format: | Project | Status | Priority | Notes |",
+    question: "What projects are you currently working on? (~/.pal/telos/PROJECTS.md)",
+    hint: "e.g. PAL (active, high priority), personal blog (paused), side SaaS (early stage)",
   },
   beliefs: {
     file: "telos/BELIEFS.md",
-    question: "What principles or values guide your work?",
-    hint: "Write their values and principles to telos/BELIEFS.md",
+    question: "What principles or values guide your work? (~/.pal/telos/BELIEFS.md)",
+    hint: "e.g. Simple code > clever code, ship early and iterate, always write tests",
   },
   challenges: {
     file: "telos/CHALLENGES.md",
-    question: "What are your biggest current challenges?",
-    hint: "Write their challenges and obstacles to telos/CHALLENGES.md",
+    question: "What are your biggest current challenges? (~/.pal/telos/CHALLENGES.md)",
+    hint: "e.g. Context switching between projects, unclear requirements, work-life balance",
   },
 };
 
@@ -58,21 +60,17 @@ function setupPath(): string {
 }
 
 /** Check if a TELOS file has real content (not just template scaffolding) */
-function hasRealContent(filePath: string): boolean {
+export function hasRealContent(filePath: string): boolean {
   if (!existsSync(filePath)) return false;
   try {
     const content = readFileSync(filePath, "utf-8").trim();
-    return content
-      .split("\n")
-      .some(
-        (l) =>
-          !l.startsWith("#") &&
-          !l.startsWith("<!--") &&
-          !l.startsWith("-->") &&
-          l.trim() &&
-          !/^\s*-\s*$/.test(l) &&
-          !/^\s*\|/.test(l)
-      );
+    return content.split("\n").some((l) => {
+      if (!l.trim()) return false;
+      if (l.startsWith("#")) return false;
+      if (l.startsWith("<!--") || l.startsWith("-->")) return false;
+      if (/^\s*-\s*$/.test(l)) return false;
+      return true; // includes table rows (| ... |) — counts as real content
+    });
   } catch {
     return false;
   }
@@ -123,55 +121,3 @@ export function remainingSteps(state: SetupState): string[] {
 export function isSetupComplete(state: SetupState): boolean {
   return state.completed;
 }
-
-/**
- * Build the system-prompt instructions for the current setup state.
- * Returns null if setup is already complete.
- */
-export function buildSetupPrompt(state: SetupState): string | null {
-  if (state.completed) return null;
-
-  const remaining = remainingSteps(state);
-  if (remaining.length === 0) return null;
-
-  const completedSteps = STEP_ORDER.filter((k) => state.steps[k]?.done);
-  const totalSteps = STEP_ORDER.length;
-
-  const lines: string[] = [
-    "## IMPORTANT: PAL First-Run Setup Required",
-    "",
-    "TELOS files are empty — the user's identity is already configured (via the installer),",
-    "but personal context is still needed. You MUST start the setup process immediately.",
-    "Greet them, explain that PAL needs to learn about them to personalize future sessions,",
-    "and ask the first remaining question below. Do NOT wait for the user to ask about setup.",
-    "",
-  ];
-
-  if (completedSteps.length > 0) {
-    lines.push(
-      `Setup in progress — ${completedSteps.length}/${totalSteps} steps complete. Continue from the next remaining step.`,
-      ""
-    );
-  }
-
-  lines.push("### Steps to complete (ask one at a time):", "");
-
-  for (const key of remaining) {
-    const step = state.steps[key];
-    lines.push(`- **${key}** — Ask: "${step.question}" → ${step.hint}`);
-  }
-
-  lines.push(
-    "",
-    "### After each answer:",
-    "1. Write the user's answer to the corresponding TELOS file.",
-    `2. Read \`memory/state/setup.json\`, set \`steps.<key>.done = true\`, and write it back.`,
-    "3. Ask the next remaining question.",
-    "",
-    `When all steps are done (or the user wants to skip), set \`completed: true\` in setup.json.`,
-    "",
-    "Keep it conversational and natural. If the user wants to skip a step, mark it done and move on."
-  );
-
-  return lines.join("\n");
-}

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

@@ -14,7 +14,8 @@ export type TokenCaller =
   | "work-learning"
   | "session-name"
   | "session-intelligence"
-  | "relationship";
+  | "relationship"
+  | "self-model";
 
 interface TokenUsageEntry {
   ts: string;

package/src/tools/self-model.ts

@@ -21,6 +21,7 @@ import { parseArgs } from "node:util";
 import { inference } from "../hooks/lib/inference";
 import { SONNET_MODEL } from "../hooks/lib/models";
 import { ensureDir, paths } from "../hooks/lib/paths";
+import { logTokenUsage } from "../hooks/lib/token-usage";
 
 // ── Config ──
 
@@ -537,6 +538,8 @@ export async function composeSelfModel(days: number): Promise<string> {
     timeout: 30000,
   });
 
+  if (result.usage) logTokenUsage("self-model", result.usage, SONNET_MODEL);
+
   if (result.success && result.output) {
     // Append meta line if inference didn't include it
     const output = result.output;

package/src/tools/token-cost.ts

@@ -258,10 +258,11 @@ export function readClaudeCode(projectFilter?: string): {
   return { buckets, byModel, byProject };
 }
 
-// ── PAL Haiku inference ──
+// ── PAL inference ──
 
 export function readPalInference(): {
   buckets: TimeBuckets;
+  byModel: Record<string, TimeBuckets>;
   byCaller: Record<string, Bucket>;
 } {
   const now = new Date();
@@ -270,13 +271,14 @@ export function readPalInference(): {
   const monthAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString();
 
   const buckets = emptyTimeBuckets();
+  const byModel: Record<string, TimeBuckets> = {};
   const byCaller: Record<string, Bucket> = {};
 
   const filepath = resolve(palHome(), "memory", "signals", "token-usage.jsonl");
-  if (!existsSync(filepath)) return { buckets, byCaller };
+  if (!existsSync(filepath)) return { buckets, byModel, byCaller };
 
   const content = readFileSync(filepath, "utf-8").trim();
-  if (!content) return { buckets, byCaller };
+  if (!content) return { buckets, byModel, byCaller };
 
   for (const line of content.split("\n")) {
     try {
@@ -299,6 +301,19 @@ export function readPalInference(): {
         weekAgo,
         monthAgo
       );
+      if (!byModel[e.model]) byModel[e.model] = emptyTimeBuckets();
+      addToTimeBuckets(
+        byModel[e.model],
+        e.ts,
+        e.model,
+        e.inputTokens,
+        e.outputTokens,
+        0,
+        0,
+        todayPrefix,
+        weekAgo,
+        monthAgo
+      );
       if (!byCaller[e.caller]) byCaller[e.caller] = emptyBucket();
       addToBucket(byCaller[e.caller], e.model, e.inputTokens, e.outputTokens, 0, 0);
     } catch {
@@ -306,7 +321,7 @@ export function readPalInference(): {
     }
   }
 
-  return { buckets, byCaller };
+  return { buckets, byModel, byCaller };
 }
 
 // ── CLI ──
@@ -352,12 +367,18 @@ function run() {
     }
   }
 
-  if (pal.buckets.total.calls > 0) {
-    console.log("\n  PAL Inference (Haiku)\n");
-    printRow("Today", pal.buckets.today);
-    printRow("7d", pal.buckets.week);
-    printRow("30d", pal.buckets.month);
-    printRow("Total", pal.buckets.total);
+  for (const [model, tb] of Object.entries(pal.byModel)) {
+    if (tb.total.calls === 0) continue;
+    const label = model.includes("haiku")
+      ? "Haiku"
+      : model.includes("sonnet")
+        ? "Sonnet"
+        : model.replace("claude-", "");
+    console.log(`\n  PAL Inference (${label})\n`);
+    printRow("Today", tb.today);
+    printRow("7d", tb.week);
+    printRow("30d", tb.month);
+    printRow("Total", tb.total);
   }
 
   const grand = emptyBucket();