portable-agent-layer 0.64.0 → 0.65.0

package/src/hooks/lib/export.ts

@@ -6,6 +6,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import AdmZip from "adm-zip";
+import { ensureRegistered } from "./machine";
 import { palHome } from "./paths";
 
 /**
@@ -59,9 +60,41 @@ export function collectExportFiles(): string[] {
   return files;
 }
 
-/** Zip the given files and write to outputPath. Returns file count. */
+/** Archive metadata naming the machine that produced it. */
+export const MANIFEST_NAME = "export-manifest.json";
+
+export interface ExportManifest {
+  machineId: string;
+  label: string;
+  os: string;
+  exportedAt: string;
+  fileCount: number;
+}
+
+export function buildManifest(
+  identity: { id: string; label: string; os: string },
+  fileCount: number
+): ExportManifest {
+  return {
+    machineId: identity.id,
+    label: identity.label,
+    os: identity.os,
+    exportedAt: new Date().toISOString(),
+    fileCount,
+  };
+}
+
+/**
+ * Zip the given files and write to outputPath. Returns file count.
+ *
+ * The archive declares its source machine in a manifest. Registry entries under
+ * memory/machines/ travel with the corpus, so the manifest exists to say which
+ * machine produced THIS archive — after a merge an archive can carry entries
+ * for several machines.
+ */
 export function exportZip(outputPath: string): number {
   const root = palHome();
+  const identity = ensureRegistered(root);
   const files = collectExportFiles();
   if (files.length === 0) return 0;
 
@@ -71,6 +104,10 @@ export function exportZip(outputPath: string): number {
     const dir = file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : "";
     zip.addLocalFile(fullPath, dir);
   }
+  zip.addFile(
+    MANIFEST_NAME,
+    Buffer.from(`${JSON.stringify(buildManifest(identity, files.length), null, 2)}\n`)
+  );
 
   zip.writeZip(outputPath);
   return files.length;

package/src/hooks/lib/import-merge.ts

@@ -0,0 +1,220 @@
+/**
+ * Import merge — fold an export archive into an existing PAL home without
+ * destroying local records.
+ *
+ * `extractAllTo(home, true)` overwrites every colliding path, so importing
+ * machine A onto machine B silently discards B's side of every append-only log.
+ * This module replaces that with a per-type policy:
+ *
+ *   *.jsonl      union of both sides, deduplicated by exact line
+ *   new files    written as-is
+ *   identical    no-op
+ *   diverged     local kept in place, incoming quarantined under backups/
+ *   denylisted   never written (machine identity, rebuildable indexes)
+ *
+ * Every policy is idempotent: re-importing the same archive is a no-op on the
+ * corpus.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { type ExportManifest, MANIFEST_NAME } from "./export";
+
+/** One file inside an export archive, decoupled from the zip library. */
+export interface ArchiveEntry {
+  path: string;
+  data(): Buffer;
+}
+
+export interface MergeResult {
+  created: string[];
+  merged: string[];
+  identical: string[];
+  conflicts: string[];
+  skipped: string[];
+  linesAdded: number;
+  quarantineDir: string | null;
+}
+
+/**
+ * Paths that must never cross machines. `machine.json` carries this install's
+ * identity — importing it would give two machines one id and silently break
+ * every origin-scoped read. The retrieval index is rebuilt from its sources.
+ */
+const NEVER_IMPORT = [
+  "machine.json",
+  "export-manifest.json",
+  "memory/learning/.retrieval-index.json",
+];
+
+function normalize(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+export function isNeverImport(path: string): boolean {
+  const rel = normalize(path);
+  return NEVER_IMPORT.some((deny) => rel === deny || rel.endsWith(`/${deny}`));
+}
+
+function isJsonl(path: string): boolean {
+  return normalize(path).endsWith(".jsonl");
+}
+
+function splitLines(raw: string): string[] {
+  return raw.split("\n").filter((l) => l.trim().length > 0);
+}
+
+/**
+ * Union of two JSONL bodies, local order preserved, incoming lines appended
+ * only when not already present. Exact-line identity is the dedupe key — no
+ * schema is shared across PAL's jsonl files, and every writer serializes a
+ * record the same way, so byte equality is the only key that holds for all of
+ * them.
+ */
+export function mergeJsonlLines(
+  localRaw: string,
+  incomingRaw: string
+): { text: string; added: number } {
+  const local = splitLines(localRaw);
+  const seen = new Set(local);
+  const added: string[] = [];
+  for (const line of splitLines(incomingRaw)) {
+    if (seen.has(line)) continue;
+    seen.add(line);
+    added.push(line);
+  }
+  const all = [...local, ...added];
+  return { text: all.length > 0 ? `${all.join("\n")}\n` : "", added: added.length };
+}
+
+function writeFileEnsuringDir(target: string, data: Buffer | string): void {
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, data);
+}
+
+function quarantine(quarantineDir: string, rel: string, data: Buffer): void {
+  writeFileEnsuringDir(resolve(quarantineDir, rel), data);
+}
+
+/**
+ * Merge every archive entry into `home`. `quarantineDir` receives the incoming
+ * copy of any file that diverged from its local counterpart, so a conflict
+ * loses neither side.
+ */
+export function mergeArchive(
+  entries: ArchiveEntry[],
+  home: string,
+  quarantineDir: string
+): MergeResult {
+  const result: MergeResult = {
+    created: [],
+    merged: [],
+    identical: [],
+    conflicts: [],
+    skipped: [],
+    linesAdded: 0,
+    quarantineDir: null,
+  };
+
+  for (const entry of entries) {
+    const rel = normalize(entry.path);
+    if (rel.length === 0 || rel.endsWith("/")) continue;
+
+    if (isNeverImport(rel)) {
+      result.skipped.push(rel);
+      continue;
+    }
+
+    const target = resolve(home, rel);
+    const incoming = entry.data();
+
+    if (!existsSync(target)) {
+      writeFileEnsuringDir(target, incoming);
+      result.created.push(rel);
+      continue;
+    }
+
+    const localRaw = readFileSync(target);
+    if (localRaw.equals(incoming)) {
+      result.identical.push(rel);
+      continue;
+    }
+
+    if (isJsonl(rel)) {
+      const { text, added } = mergeJsonlLines(
+        localRaw.toString("utf-8"),
+        incoming.toString("utf-8")
+      );
+      writeFileSync(target, text);
+      result.merged.push(rel);
+      result.linesAdded += added;
+      continue;
+    }
+
+    quarantine(quarantineDir, rel, incoming);
+    result.conflicts.push(rel);
+    result.quarantineDir = quarantineDir;
+  }
+
+  return result;
+}
+
+/**
+ * The source machine declared by an archive's manifest, or null when the
+ * archive predates manifests.
+ */
+export function readManifest(entries: ArchiveEntry[]): ExportManifest | null {
+  const hit = entries.find((e) => normalize(e.path) === MANIFEST_NAME);
+  if (!hit) return null;
+  try {
+    const parsed = JSON.parse(hit.data().toString("utf-8")) as Partial<ExportManifest>;
+    if (typeof parsed.machineId !== "string" || parsed.machineId.length === 0)
+      return null;
+    return {
+      machineId: parsed.machineId,
+      label: parsed.label ?? parsed.machineId,
+      os: parsed.os ?? "",
+      exportedAt: parsed.exportedAt ?? "",
+      fileCount: parsed.fileCount ?? 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export interface ImportLogEntry {
+  ts: string;
+  archive: string;
+  mode: "merge" | "overwrite";
+  created: number;
+  merged: number;
+  identical: number;
+  conflicts: number;
+  skipped: number;
+  linesAdded: number;
+  quarantineDir: string | null;
+  sourceMachineId?: string | null;
+}
+
+/** Append one record per import so a merged corpus stays attributable. */
+export function appendImportLog(home: string, entry: ImportLogEntry): void {
+  const logPath = resolve(home, "memory", "state", "import-log.jsonl");
+  mkdirSync(dirname(logPath), { recursive: true });
+  const line = `${JSON.stringify(entry)}\n`;
+  if (existsSync(logPath)) {
+    writeFileSync(logPath, readFileSync(logPath, "utf-8") + line);
+    return;
+  }
+  writeFileSync(logPath, line);
+}
+
+export function summarize(result: MergeResult): string {
+  const parts = [
+    `${result.created.length} new`,
+    `${result.merged.length} merged (+${result.linesAdded} records)`,
+    `${result.identical.length} unchanged`,
+  ];
+  if (result.conflicts.length > 0) parts.push(`${result.conflicts.length} conflicts`);
+  if (result.skipped.length > 0) parts.push(`${result.skipped.length} skipped`);
+  return parts.join(", ");
+}

package/src/hooks/lib/inference.ts

@@ -20,7 +20,9 @@
  * yet wired and currently fall through to the API path.
  */
 
-import { basename } from "node:path";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
 import {
   getActiveAgent,
   isClaude,
@@ -151,14 +153,14 @@ export async function inference(opts: InferenceOptions): Promise<InferenceResult
         "inference",
         `${tag} route=claude-spawn agent=${agent} model=${opts.model ?? HAIKU_MODEL}`
       );
-      return inferenceViaCliSpawn(bin, buildClaudeArgs(opts), opts.user, opts);
+      return inferenceViaClaudeSpawn(bin, opts);
     }
   }
   if (isCodex()) {
     const bin = getCodexBinary();
     if (bin) {
       logDebug("inference", `${tag} route=codex-spawn agent=${agent}`);
-      return inferenceViaCliSpawn(bin, buildCodexArgs(opts), "", opts);
+      return inferenceViaCliSpawn(bin, buildCodexArgs(opts), buildCliPrompt(opts), opts);
     }
   }
   if (isCodex() && hasOpenAiKey()) {
@@ -172,7 +174,7 @@ export async function inference(opts: InferenceOptions): Promise<InferenceResult
       return inferenceViaCliSpawn(
         bin,
         buildOpencodeArgs(opts),
-        "",
+        buildCliPrompt(opts),
         opts,
         extractOpencodeText
       );
@@ -182,14 +184,19 @@ export async function inference(opts: InferenceOptions): Promise<InferenceResult
     const bin = getCopilotBinary();
     if (bin) {
       logDebug("inference", `${tag} route=copilot-spawn agent=${agent}`);
-      return inferenceViaCliSpawn(bin, buildCopilotArgs(opts), "", opts);
+      return inferenceViaCliSpawn(
+        bin,
+        buildCopilotArgs(opts),
+        buildCliPrompt(opts),
+        opts
+      );
     }
   }
   if (isCursor()) {
     const bin = getCursorBinary();
     if (bin) {
       logDebug("inference", `${tag} route=cursor-spawn agent=${agent}`);
-      return inferenceViaCliSpawn(bin, buildCursorArgs(opts), "", opts);
+      return inferenceViaCliSpawn(bin, buildCursorArgs(opts), buildCliPrompt(opts), opts);
     }
   }
   if (hasApiKey()) {
@@ -284,16 +291,23 @@ export function _resetCursorBinaryCache(): void {
   cursorBinaryCache = undefined;
 }
 
-/** Build the argv for `claude --print …` from inference options. Pure. */
-export function buildClaudeArgs(opts: InferenceOptions): string[] {
-  const model = opts.model ?? HAIKU_MODEL;
-  const system = opts.jsonSchema
-    ? injectJsonSchemaInstruction(opts.system ?? "", opts.jsonSchema)
-    : opts.system;
+/**
+ * Build the argv for `claude --print …`. Pure.
+ *
+ * `--system-prompt` is deliberately absent: PAL's system prompts run to several
+ * paragraphs, and an argv element cannot carry a newline on Windows once
+ * Bun.spawn resolves claude to its .cmd shim and cmd.exe re-parses the command
+ * line. System, user and any JSON-schema instruction all travel together on
+ * stdin instead, the same way every other agent receives them.
+ */
+export function buildClaudeArgs(
+  opts: InferenceOptions,
+  systemPromptFile?: string
+): string[] {
   const args = [
     "--print",
     "--model",
-    model,
+    opts.model ?? HAIKU_MODEL,
     "--tools",
     "",
     "--output-format",
@@ -301,12 +315,38 @@ export function buildClaudeArgs(opts: InferenceOptions): string[] {
     "--setting-sources",
     "",
   ];
-  if (system) {
-    args.push("--system-prompt", system);
-  }
+  if (systemPromptFile) args.push("--system-prompt-file", systemPromptFile);
   return args;
 }
 
+/**
+ * Claude keeps a real system prompt, unlike the other agents, so the system text
+ * reaches it through --system-prompt-file rather than --system-prompt. Only the
+ * path travels in argv, which is what makes this work on Windows: an argv
+ * element cannot carry a newline once Bun.spawn resolves claude to its .cmd
+ * shim, and PAL's system prompts run to several paragraphs. Folding the system
+ * text into the user message instead is not an option — Claude treats
+ * instructions embedded in message content as an injection attempt and refuses.
+ */
+async function inferenceViaClaudeSpawn(
+  bin: string,
+  opts: InferenceOptions
+): Promise<InferenceResult> {
+  const system = opts.jsonSchema
+    ? injectJsonSchemaInstruction(opts.system ?? "", opts.jsonSchema)
+    : opts.system;
+  if (!system) return inferenceViaCliSpawn(bin, buildClaudeArgs(opts), opts.user, opts);
+
+  const dir = await mkdtemp(join(tmpdir(), "pal-system-"));
+  try {
+    const file = join(dir, "system-prompt.md");
+    await writeFile(file, system, "utf-8");
+    return await inferenceViaCliSpawn(bin, buildClaudeArgs(opts, file), opts.user, opts);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
 /**
  * Build the argv for `codex exec …` from inference options. Pure.
  *
@@ -316,20 +356,16 @@ export function buildClaudeArgs(opts: InferenceOptions): string[] {
  *   --sandbox read-only   → child cannot execute shell commands even if it tries
  *   --ephemeral           → no session persistence; one-shot only
  *
- * Codex has no --system-prompt equivalent — the full prompt is a single positional
- * argv string. We concatenate system + user + JSON-schema instruction into one
- * prompt. ARG_MAX is ~256KB on macOS; typical PAL prompts are 1-2KB.
+ * Codex has no --system-prompt equivalent, so system + user + JSON-schema become
+ * one prompt. That prompt goes in on stdin, not as a positional argument, because
+ * a PAL prompt spans several paragraphs and an argv element cannot carry a
+ * newline on Windows: Bun.spawn resolves the CLI to its .cmd shim, cmd.exe
+ * re-parses the command line, and the child exits non-zero having written
+ * nothing. Codex reads its instructions from stdin when no positional prompt is
+ * given, so this costs nothing on POSIX and is the only thing that works on
+ * Windows. Do not move the prompt back into argv.
  */
-export function buildCodexArgs(opts: InferenceOptions): string[] {
-  const parts: string[] = [];
-  if (opts.system) parts.push(opts.system);
-  parts.push(opts.user);
-  if (opts.jsonSchema) {
-    parts.push(
-      `Respond with ONLY a JSON value matching this schema (no prose, no markdown): ${JSON.stringify(opts.jsonSchema)}`
-    );
-  }
-  const prompt = parts.join("\n\n");
+export function buildCodexArgs(_opts: InferenceOptions): string[] {
   return [
     "exec",
     "--color",
@@ -340,7 +376,6 @@ export function buildCodexArgs(opts: InferenceOptions): string[] {
     "--sandbox",
     "read-only",
     "--ephemeral",
-    prompt,
   ];
 }
 
@@ -354,21 +389,14 @@ export function buildCodexArgs(opts: InferenceOptions): string[] {
  *                    text via extractOpencodeText() rather than wading through
  *                    decoration ("> build · provider/model" banner etc).
  *
- * opencode (like codex) has no --system-prompt equivalent — the full prompt is
- * the positional message argv. System + user + JSON-schema are concatenated.
- * Provider/model is left unset so opencode uses the user's configured default.
+ * opencode (like codex) has no --system-prompt equivalent, so system + user +
+ * JSON-schema are concatenated and delivered on stdin rather than as the
+ * positional message, for the same reason as codex: a multi-paragraph argv
+ * element does not survive cmd.exe on Windows. Provider/model is left unset so
+ * opencode uses the user's configured default.
  */
-export function buildOpencodeArgs(opts: InferenceOptions): string[] {
-  const parts: string[] = [];
-  if (opts.system) parts.push(opts.system);
-  parts.push(opts.user);
-  if (opts.jsonSchema) {
-    parts.push(
-      `Respond with ONLY a JSON value matching this schema (no prose, no markdown): ${JSON.stringify(opts.jsonSchema)}`
-    );
-  }
-  const prompt = parts.join("\n\n");
-  return ["run", "--pure", "--format", "json", prompt];
+export function buildOpencodeArgs(_opts: InferenceOptions): string[] {
+  return ["run", "--pure", "--format", "json"];
 }
 
 /**
@@ -385,23 +413,16 @@ export function buildOpencodeArgs(opts: InferenceOptions): string[] {
  *                          of running inference. Safe to pair with --mode ask
  *                          because that mode disallows tool calls anyway.
  *
- * cursor-agent has no --system-prompt flag — system + user + JSON-schema are
- * concatenated into a single positional prompt argument.
+ * cursor-agent has no --system-prompt flag, so system + user + JSON-schema are
+ * concatenated into one prompt delivered on stdin rather than as the trailing
+ * positional argument: a multi-paragraph argv element cannot survive cmd.exe on
+ * Windows. `-p` stays because for cursor-agent it means --print, not --prompt.
  *
  * Auth note: cursor-agent picks up either `cursor-agent login` credentials or
  * `CURSOR_API_KEY` env var. PAL doesn't manage these — that's the user's setup.
  */
-export function buildCursorArgs(opts: InferenceOptions): string[] {
-  const parts: string[] = [];
-  if (opts.system) parts.push(opts.system);
-  parts.push(opts.user);
-  if (opts.jsonSchema) {
-    parts.push(
-      `Respond with ONLY a JSON value matching this schema (no prose, no markdown): ${JSON.stringify(opts.jsonSchema)}`
-    );
-  }
-  const prompt = parts.join("\n\n");
-  return ["-p", "--mode", "ask", "--output-format", "text", "--trust", prompt];
+export function buildCursorArgs(_opts: InferenceOptions): string[] {
+  return ["-p", "--mode", "ask", "--output-format", "text", "--trust"];
 }
 
 /**
@@ -417,22 +438,14 @@ export function buildCursorArgs(opts: InferenceOptions): string[] {
  *   --allow-all-tools         → REQUIRED for non-interactive mode (without it,
  *                                copilot prompts for tool-use confirmation)
  *
- * Copilot has no --system-prompt flag — system + user + JSON-schema are
- * concatenated into a single prompt passed via -p.
+ * Copilot has no --system-prompt flag, so system + user + JSON-schema are
+ * concatenated into one prompt delivered on stdin. `-p/--prompt` is deliberately
+ * absent: it takes the prompt inline, and a multi-paragraph argv element cannot
+ * survive cmd.exe when Bun.spawn resolves copilot to its Windows .cmd shim.
+ * Piping stdin keeps copilot non-interactive, so dropping -p costs nothing.
  */
-export function buildCopilotArgs(opts: InferenceOptions): string[] {
-  const parts: string[] = [];
-  if (opts.system) parts.push(opts.system);
-  parts.push(opts.user);
-  if (opts.jsonSchema) {
-    parts.push(
-      `Respond with ONLY a JSON value matching this schema (no prose, no markdown): ${JSON.stringify(opts.jsonSchema)}`
-    );
-  }
-  const prompt = parts.join("\n\n");
+export function buildCopilotArgs(_opts: InferenceOptions): string[] {
   return [
-    "-p",
-    prompt,
     "--no-custom-instructions",
     "--disable-builtin-mcps",
     "--no-auto-update",
@@ -465,12 +478,40 @@ export function extractOpencodeText(rawStdout: string): string {
   return texts.join("").trim();
 }
 
+/**
+ * Render a JSON schema for a prompt without double quotes.
+ *
+ * Bun.spawn resolves an agent CLI on Windows to its `.cmd` shim, which npm
+ * installs it as, and cmd.exe re-parses the command line it is handed. A double
+ * quote inside an argv element does not survive that round trip: the child exits
+ * non-zero having written nothing, so the dispatcher sees an empty abort and
+ * gives up. Single quotes carry the same shape to a model and are inert to
+ * cmd.exe, so the schema travels intact on every platform.
+ */
+function schemaForPrompt(schema: Record<string, unknown>): string {
+  return JSON.stringify(schema).replaceAll('"', "'");
+}
+
+/** The one instruction line that asks a CLI agent for schema-shaped JSON. */
+export function schemaInstruction(schema: Record<string, unknown>): string {
+  return `Respond with ONLY a JSON value matching this schema (no prose, no markdown): ${schemaForPrompt(schema)}`;
+}
+
+/** system + user + schema instruction, the single prompt a CLI agent receives. */
+export function buildCliPrompt(opts: InferenceOptions): string {
+  const parts: string[] = [];
+  if (opts.system) parts.push(opts.system);
+  parts.push(opts.user);
+  if (opts.jsonSchema) parts.push(schemaInstruction(opts.jsonSchema));
+  return parts.join("\n\n");
+}
+
 /** Append a JSON-schema instruction to the system prompt (PAI pattern). */
 export function injectJsonSchemaInstruction(
   systemPrompt: string,
   schema: Record<string, unknown>
 ): string {
-  const schemaLine = `Respond with ONLY a JSON value matching this schema (no prose, no markdown): ${JSON.stringify(schema)}`;
+  const schemaLine = schemaInstruction(schema);
   return systemPrompt ? `${systemPrompt}\n\n${schemaLine}` : schemaLine;
 }