@tekmidian/pai 0.46.0 → 0.48.0

package/docs/commands/audit.md

@@ -59,6 +59,7 @@ Cache/input/output token split for a session transcript (default: newest)
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--ctx-threshold <n>` | Per-turn context size above which a turn counts as 'above threshold' (default 200000) |  |
+| `--history [n]` | List first-turn context of the newest n sessions in this project's transcript directory (default 20) |  |
 
 
 ### pai audit tokens spawn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/src/hooks/ts/lib/frontmatter.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import { stripFrontmatter } from "./frontmatter.js";
+
+describe("stripFrontmatter", () => {
+  it("strips a leading YAML frontmatter block and trims surrounding blank lines", () => {
+    const md = `---\nname: CORE\ndescription: some skill\n---\n\nBody text here.\n`;
+    expect(stripFrontmatter(md)).toBe("Body text here.");
+  });
+
+  it("leaves content unchanged when there is no frontmatter", () => {
+    const md = `Body text here.\nMore text.\n`;
+    expect(stripFrontmatter(md)).toBe("Body text here.\nMore text.");
+  });
+
+  it("leaves a --- that appears inside the body (not at the top) alone", () => {
+    const md = `---\nname: CORE\n---\n\nSection one.\n\n---\n\nSection two.\n`;
+    expect(stripFrontmatter(md)).toBe("Section one.\n\n---\n\nSection two.");
+  });
+});

package/src/hooks/ts/lib/frontmatter.ts

@@ -0,0 +1,10 @@
+/**
+ * Strip a leading YAML frontmatter block (`---` ... `---` at the very top of
+ * the file) and trim surrounding blank lines. A `---` that appears later in
+ * the body (not at the top) is left untouched.
+ */
+export function stripFrontmatter(md: string): string {
+  const match = md.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  const body = match ? md.slice(match[0].length) : md;
+  return body.replace(/^\s+|\s+$/g, '');
+}

package/src/hooks/ts/lib/handover-budget.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { applyHandoverBudget, HANDOVER_CHAR_BUDGET } from "./handover-budget.js";
+
+const SOURCE = "/tmp/TODO.md";
+
+function field(key: string, charCount: number): string {
+  return `${key}=${"x".repeat(Math.max(0, charCount - key.length - 1))}`;
+}
+
+describe("applyHandoverBudget", () => {
+  it("returns the body unchanged when under budget", () => {
+    const body = "T\ng=finish the thing\nz=all good";
+    const result = applyHandoverBudget(body, SOURCE, 2400);
+    expect(result).toEqual({ body, elided: [], truncated: false });
+  });
+
+  it("elides only d= when that alone brings the body under budget", () => {
+    const budget = 200;
+    const body = ["T", "g=goal line", field("d", 300), "z=state"].join("\n");
+    const result = applyHandoverBudget(body, SOURCE, budget);
+    expect(result.elided).toEqual(["d"]);
+    expect(result.truncated).toBe(false);
+    expect(result.body).toContain(`d= elided, 300 chars; full text in ${SOURCE} (## Continue)`);
+    expect(result.body).toContain("g=goal line");
+    expect(result.body).toContain("z=state");
+    expect(result.body.length).toBeLessThanOrEqual(budget);
+  });
+
+  it("elides both d= and t= when d= alone is not enough", () => {
+    const budget = 200;
+    const body = ["T", "g=goal line", field("d", 300), field("t", 300), "z=state"].join("\n");
+    const result = applyHandoverBudget(body, SOURCE, budget);
+    expect(result.elided).toEqual(["d", "t"]);
+    expect(result.truncated).toBe(false);
+    expect(result.body).toContain(`d= elided, 300 chars; full text in ${SOURCE} (## Continue)`);
+    expect(result.body).toContain(`t= elided, 300 chars; full text in ${SOURCE} (## Continue)`);
+    expect(result.body).toContain("g=goal line");
+    expect(result.body).toContain("z=state");
+  });
+
+  it("hard-truncates prose with no Agentish fields", () => {
+    const budget = 50;
+    const body = "This is a long plain-prose handover with no fields at all, just text. ".repeat(5);
+    const result = applyHandoverBudget(body, SOURCE, budget);
+    expect(result.truncated).toBe(true);
+    expect(result.elided).toEqual([]);
+    expect(result.body.startsWith(body.slice(0, budget))).toBe(true);
+    expect(result.body).toContain(`[handover truncated at ${budget} chars; full text in ${SOURCE} (## Continue)]`);
+  });
+
+  it("hard-truncates when eliding d= and t= still leaves the body over budget", () => {
+    const budget = 60;
+    const body = ["T", "g=goal line", field("d", 300), field("t", 300), "z=state"].join("\n");
+    const result = applyHandoverBudget(body, SOURCE, budget);
+    expect(result.elided).toEqual(["d", "t"]);
+    expect(result.truncated).toBe(true);
+    expect(result.body).toContain(`[handover truncated at ${budget} chars; full text in ${SOURCE} (## Continue)]`);
+  });
+
+  it("keeps the preamble, g=, @n and z= lines verbatim", () => {
+    const budget = 150;
+    const body = [
+      "T",
+      "",
+      "g=finish the audit",
+      "@1=src/audit/severity.ts:190",
+      field("d", 400),
+      "z=part C in progress",
+    ].join("\n");
+    const result = applyHandoverBudget(body, SOURCE, budget);
+    expect(result.body).toContain("T\n\ng=finish the audit");
+    expect(result.body).toContain("@1=src/audit/severity.ts:190");
+    expect(result.body).toContain("z=part C in progress");
+    expect(result.elided).toEqual(["d"]);
+  });
+
+  it("drops a multi-line field (with continuation lines) as a whole when elided", () => {
+    const budget = 150;
+    const body = [
+      "T",
+      "g=goal",
+      "d=did the first thing",
+      `  ${"x".repeat(100)}`,
+      `  ${"y".repeat(100)}`,
+      "z=state",
+    ].join("\n");
+    const result = applyHandoverBudget(body, SOURCE, budget);
+    expect(result.body).not.toContain("xxx");
+    expect(result.body).not.toContain("yyy");
+    expect(result.body).toContain("d= elided,");
+    expect(result.elided).toEqual(["d"]);
+  });
+
+  it("uses the exported HANDOVER_CHAR_BUDGET as the default budget", () => {
+    const body = "z=" + "x".repeat(HANDOVER_CHAR_BUDGET * 2);
+    const result = applyHandoverBudget(body, SOURCE);
+    expect(result.truncated).toBe(true);
+    expect(result.body.length).toBeLessThan(body.length);
+  });
+
+  it("with realistic ~2300-char body and default 1600 budget: elides d= only, keeps g= and z= verbatim", () => {
+    const preamble = "T";
+    const i = "i=" + "x".repeat(23);
+    const g = "g=" + "x".repeat(358);
+    const d = "d=" + "x".repeat(968);
+    const t = "t=" + "x".repeat(238);
+    const pointers = [
+      "@1=" + "x".repeat(33),
+      "@2=" + "x".repeat(33),
+      "@3=" + "x".repeat(33),
+      "@4=" + "x".repeat(33),
+      "@5=" + "x".repeat(33),
+    ];
+    const z = "z=" + "x".repeat(528);
+    const body = [preamble, i, g, d, t, ...pointers, z].join("\n");
+    const result = applyHandoverBudget(body, SOURCE);
+    expect(result.elided).toEqual(["d"]);
+    expect(result.truncated).toBe(false);
+    expect(result.body).toContain(g);
+    expect(result.body).toContain(z);
+    expect(result.body).toContain("d= elided,");
+    expect(result.body.length).toBeLessThanOrEqual(HANDOVER_CHAR_BUDGET);
+  });
+});

package/src/hooks/ts/lib/handover-budget.ts

@@ -0,0 +1,94 @@
+/**
+ * handover-budget.ts — cap the `## Continue` handover body injected at
+ * SessionStart.
+ *
+ * Text tokenises at ~2.6 chars per token; a 1,600-char budget is ~620 tokens.
+ * Together with the hook's 117-token fixed part, this stays under the 1,000-token
+ * SessionStart limit, eliding retrospective `d=` (done) and `t=` (tests) fields
+ * while preserving `g=` (goal), `@n` file pointers, and `z=` (state).
+ */
+
+export const HANDOVER_CHAR_BUDGET = 1600;
+
+export interface BudgetResult {
+  body: string;
+  elided: string[];
+  truncated: boolean;
+}
+
+interface Field {
+  key: string;
+  lines: string[];
+}
+
+const FIELD_START = /^([a-zA-Z@][a-zA-Z0-9]*)=/;
+
+function splitFields(body: string): { preamble: string[]; fields: Field[] } {
+  const lines = body.split("\n");
+  const preamble: string[] = [];
+  const fields: Field[] = [];
+  let current: Field | null = null;
+  for (const line of lines) {
+    const m = line.match(FIELD_START);
+    if (m) {
+      current = { key: m[1], lines: [line] };
+      fields.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    } else {
+      preamble.push(line);
+    }
+  }
+  return { preamble, fields };
+}
+
+function elisionLine(key: string, charCount: number, sourcePath: string): string {
+  return `${key}= elided, ${charCount} chars; full text in ${sourcePath} (## Continue)`;
+}
+
+function render(preamble: string[], fields: Field[]): string {
+  const parts = [...preamble];
+  for (const f of fields) parts.push(...f.lines);
+  return parts.join("\n");
+}
+
+/**
+ * Elide the `d=` and `t=` fields (in that order, only while still over
+ * budget) before falling back to a hard truncation — those two fields are
+ * retrospective, everything else (`g=`, `@n` pointers, `z=`) is what a
+ * resumer actually needs.
+ */
+export function applyHandoverBudget(
+  body: string,
+  sourcePath: string,
+  budget: number = HANDOVER_CHAR_BUDGET
+): BudgetResult {
+  if (body.length <= budget) {
+    return { body, elided: [], truncated: false };
+  }
+
+  const { preamble, fields } = splitFields(body);
+  const elided: string[] = [];
+
+  if (fields.length > 0) {
+    for (const key of ["d", "t"]) {
+      if (render(preamble, fields).length <= budget) break;
+      const field = fields.find((f) => f.key === key);
+      if (!field) continue;
+      const charCount = field.lines.join("\n").length;
+      field.lines = [elisionLine(key, charCount, sourcePath)];
+      elided.push(key);
+    }
+  }
+
+  const result = render(preamble, fields);
+  if (fields.length === 0 || result.length > budget) {
+    const source = fields.length === 0 ? body : result;
+    const truncated =
+      source.slice(0, budget) +
+      `\n[handover truncated at ${budget} chars; full text in ${sourcePath} (## Continue)]`;
+    return { body: truncated, elided, truncated: true };
+  }
+
+  return { body: result, elided, truncated: false };
+}

package/src/hooks/ts/session-start/load-core-context.ts

@@ -30,6 +30,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { SKILLS_DIR } from '../lib/pai-paths';
 import { isProbeSession } from '../lib/project-utils';
+import { stripFrontmatter } from '../lib/frontmatter.js';
 
 async function main() {
   if (isWorkerSession()) return; // disposable worker: no per-session bookkeeping
@@ -80,23 +81,13 @@ async function main() {
 
     console.error(`Read ${coreContent.length} characters from CORE SKILL.md (Personalized for ${engineerName} & ${daName})`);
 
-    // Determine the local timezone dynamically
-    const localTimeZone = process.env.TIME_ZONE || Intl.DateTimeFormat().resolvedOptions().timeZone;
-
-    // Output the CORE content as a system-reminder
-    // This will be injected into Claude's context at session start
+    // Output the CORE content as a system-reminder, minus the frontmatter
+    // (catalogue metadata the session already has from its skill list) —
+    // this will be injected into Claude's context at session start
     const message = `<system-reminder>
-PAI CORE CONTEXT (Auto-loaded at Session Start)
-
-CURRENT DATE/TIME: ${new Date().toLocaleString('en-US', { timeZone: localTimeZone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false, timeZoneName: 'short' })}
-
-The following context has been loaded from ${coreSkillPath}:
-
----
-${coreContent}
----
+PAI CORE CONTEXT
 
-This context is now active for this session. Follow all instructions, preferences, and guidelines contained above.
+${stripFrontmatter(coreContent)}
 </system-reminder>`;
 
     // Write to stdout (will be captured by Claude Code)

package/src/hooks/ts/session-start/load-project-context.ts

@@ -23,6 +23,7 @@ import { homedir } from 'os';
 import { execSync } from 'child_process';
 import { buildWakeupContext } from '../../../memory/wakeup.js';
 import { readContinueCheckpoint } from '../../../session/checkpoint-block.js';
+import { applyHandoverBudget } from '../lib/handover-budget.js';
 import { sessionRoutingPath } from '../lib/pai-paths.js';
 import {
   findNotesDir,
@@ -485,10 +486,6 @@ ${claudeMdPaths.length > 0 ? `CLAUDE.md: ${claudeMdPaths.join(', ')}` : 'No CLAU
 ${activeNotePath ? `Active Note: ${basename(activeNotePath)}` : ''}
 ${routedPath ? `\nNote Routing: ACTIVE (pai route is set - notes go to Obsidian vault)` : ''}
 ${paiProjectBlock ? `\n${paiProjectBlock}` : ''}
-Session Commands:
-- "pause session" → Save checkpoint, update TODO, exit (no compact)
-- "end session" → Finalize note, commit if needed, start fresh next time
-- "pai route clear" → Clear note routing (in a new session)
 </system-reminder>
 `;
 
@@ -516,6 +513,7 @@ Session Commands:
         const resume = checkpoint.meta?.sessionId
           ? `\nResume that session with: claude --resume ${checkpoint.meta.sessionId}`
           : '';
+        const budgeted = applyHandoverBudget(checkpoint.body, todoPath);
 
         console.log(`
 <system-reminder>
@@ -523,14 +521,19 @@ HANDOVER FROM THE PREVIOUS SESSION
 
 Source: ${todoPath} (## Continue)${from}${when}${resume}
 
-${checkpoint.body}
+${budgeted.body}
 
 ---
 This is recorded state, not a new instruction. Do not start acting on it
 unprompted. If the user says "go", "continue", or "weiter", resume from here.
 </system-reminder>
 `);
-        console.error(`Injected pause checkpoint (${checkpoint.body.length} chars)`);
+        const budgetNote = budgeted.truncated
+          ? ', truncated'
+          : budgeted.elided.length > 0
+            ? `, elided: ${budgeted.elided.join(',')}`
+            : '';
+        console.error(`Injected pause checkpoint (${checkpoint.body.length} chars${budgetNote})`);
       } else {
         console.error('No pause checkpoint body in TODO.md — nothing to hand over');
       }