portable-agent-layer 0.88.1 → 0.89.1

package/src/hooks/lib/agent-registry.ts

@@ -0,0 +1,88 @@
+/**
+ * The one list of agents PAL installs into. Every per-agent union, roster and
+ * priority order elsewhere is derived from or checked against this table, so a
+ * new agent starts here.
+ */
+
+import { resolve } from "node:path";
+import { platform } from "./paths";
+
+type SkillDiscovery = "own-skills-dir" | "shared-agents-skills";
+
+interface AgentEntry {
+  label: string;
+  binary: string;
+  home: () => string;
+  skills: SkillDiscovery;
+}
+
+export const AGENT_REGISTRY = {
+  claude: {
+    label: "Claude Code",
+    binary: "claude",
+    home: platform.claudeDir,
+    skills: "own-skills-dir",
+  },
+  opencode: {
+    label: "opencode",
+    binary: "opencode",
+    home: platform.opencodeDir,
+    skills: "shared-agents-skills",
+  },
+  cursor: {
+    label: "Cursor",
+    binary: "cursor-agent",
+    home: platform.cursorDir,
+    skills: "own-skills-dir",
+  },
+  copilot: {
+    label: "Copilot",
+    binary: "copilot",
+    home: platform.copilotDir,
+    skills: "own-skills-dir",
+  },
+  codex: {
+    label: "Codex",
+    binary: "codex",
+    home: platform.codexDir,
+    skills: "own-skills-dir",
+  },
+  antigravity: {
+    label: "Antigravity CLI",
+    binary: "agy",
+    home: platform.antigravityPluginDir,
+    skills: "own-skills-dir",
+  },
+} as const satisfies Record<string, AgentEntry>;
+
+export type AgentName = keyof typeof AGENT_REGISTRY;
+
+export const AGENT_NAMES = Object.keys(AGENT_REGISTRY) as AgentName[];
+
+export const INFERENCE_PRIORITY = [
+  "claude",
+  "codex",
+  "opencode",
+  "copilot",
+  "cursor",
+  "antigravity",
+] as const satisfies readonly AgentName[];
+
+export const LAUNCH_PRIORITY = [
+  "claude",
+  "codex",
+  "cursor",
+  "copilot",
+  "opencode",
+  "antigravity",
+] as const satisfies readonly AgentName[];
+
+export function skillsDirOf(agent: AgentName): string {
+  const entry: AgentEntry = AGENT_REGISTRY[agent];
+  const root = entry.skills === "own-skills-dir" ? entry.home() : platform.agentsDir();
+  return resolve(root, "skills");
+}
+
+export function isAgentName(value: string): value is AgentName {
+  return Object.hasOwn(AGENT_REGISTRY, value);
+}

package/src/hooks/lib/agent.ts

@@ -14,24 +14,23 @@
  * on PATH rather than assuming claude.
  */
 
+import {
+  AGENT_REGISTRY,
+  type AgentName,
+  INFERENCE_PRIORITY,
+  isAgentName,
+} from "./agent-registry";
 import { findBinaryOnPath } from "./which";
 
-export type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode" | "vscode";
+export type AgentType = AgentName | "vscode";
 
-const KNOWN_AGENTS: ReadonlySet<AgentType> = new Set([
-  "claude",
-  "cursor",
-  "codex",
-  "copilot",
-  "opencode",
-  "vscode",
-]);
+function asAgentType(value: string | undefined): AgentType | undefined {
+  if (!value) return undefined;
+  return value === "vscode" || isAgentName(value) ? value : undefined;
+}
 
 function agentFromEnv(): AgentType | undefined {
-  const explicit = process.env.PAL_AGENT;
-  return explicit && KNOWN_AGENTS.has(explicit as AgentType)
-    ? (explicit as AgentType)
-    : undefined;
+  return asAgentType(process.env.PAL_AGENT);
 }
 
 /**
@@ -43,8 +42,7 @@ function agentFromEnv(): AgentType | undefined {
  */
 export function agentFromArgv(): AgentType | undefined {
   const flag = process.argv.find((a) => a.startsWith("--agent="));
-  const value = flag?.slice("--agent=".length);
-  return value && KNOWN_AGENTS.has(value as AgentType) ? (value as AgentType) : undefined;
+  return asAgentType(flag?.slice("--agent=".length));
 }
 
 /**
@@ -73,17 +71,24 @@ function inClaudeCode(): boolean {
   return Boolean(process.env.CLAUDE_CODE_ENTRYPOINT);
 }
 
+/** Exported into every hook and tool process agy spawns. */
+function inAntigravity(): boolean {
+  return Boolean(process.env.ANTIGRAVITY_CONVERSATION_ID);
+}
+
 /**
  * Which host is running this process, read from what the host itself exported.
  *
  * cursor-agent is tested first on purpose: it emulates Claude Code closely
  * enough to inject CLAUDE_PROJECT_DIR and CLAUDE_CODE_AUTO_COMPACT_WINDOW, so
  * a CLAUDE_* variable is evidence of Claude Code only once Cursor is ruled out.
+ * Antigravity comes last because its variable leaks into any agent it runs.
  */
 function agentFromRuntimeEnv(): AgentType | undefined {
   if (inCursorAgent()) return "cursor";
   if (inCodex()) return "codex";
   if (inClaudeCode()) return "claude";
+  if (inAntigravity()) return "antigravity";
   return undefined;
 }
 
@@ -117,13 +122,8 @@ export function declaredAgent(): AgentType | undefined {
  * The CLI each agent spawns for inference, in the order inference.ts routes
  * them. vscode is absent because it has no CLI of its own — it runs Claude's.
  */
-const AGENT_BINARIES: ReadonlyArray<readonly [AgentType, string]> = [
-  ["claude", "claude"],
-  ["codex", "codex"],
-  ["opencode", "opencode"],
-  ["copilot", "copilot"],
-  ["cursor", "cursor-agent"],
-];
+const AGENT_BINARIES: ReadonlyArray<readonly [AgentType, string]> =
+  INFERENCE_PRIORITY.map((agent) => [agent, AGENT_REGISTRY[agent].binary] as const);
 
 /**
  * Which agent this machine actually has, for the case where nothing declared
@@ -150,6 +150,7 @@ export const isCursor = () => getActiveAgent() === "cursor";
 export const isCodex = () => getActiveAgent() === "codex";
 export const isCopilot = () => getActiveAgent() === "copilot";
 export const isOpencode = () => getActiveAgent() === "opencode";
+export const isAntigravity = () => getActiveAgent() === "antigravity";
 const isVscode = () => getActiveAgent() === "vscode";
 
 /** Normalized preToolUse request — one shape for every agent's payload. */
@@ -159,6 +160,16 @@ export interface ToolUseRequest {
   hookEventName?: string;
 }
 
+/** Every spelling agents use for the file a write tool changes. */
+export const FILE_TARGET_KEYS = ["file_path", "filePath", "path", "TargetFile"];
+
+/** Antigravity's file-writing tools, all of which name their file `TargetFile`. */
+export const ANTIGRAVITY_WRITE_TOOLS = [
+  "write_to_file",
+  "replace_file_content",
+  "multi_replace_file_content",
+];
+
 function firstString(...values: unknown[]): string | undefined {
   return values.find((v): v is string => typeof v === "string" && v.length > 0);
 }
@@ -186,6 +197,14 @@ function toolInputOf(payload: Record<string, unknown>): Record<string, unknown>
   return firstObject(...candidates) ?? candidates.map(parsedObject).find(Boolean) ?? {};
 }
 
+/** Antigravity nests the call as `toolCall: { name, args }`. */
+function nestedToolCall(payload: Record<string, unknown>): ToolUseRequest | null {
+  const call = firstObject(payload.toolCall);
+  const toolName = firstString(call?.name);
+  if (!call || !toolName) return null;
+  return { toolName, toolInput: firstObject(call.args) ?? {} };
+}
+
 /**
  * Normalize a preToolUse payload across agents.
  *
@@ -198,7 +217,7 @@ export function normalizeToolUse(raw: unknown): ToolUseRequest | null {
   const payload = firstObject(raw);
   if (!payload) return null;
   const toolName = firstString(payload.tool_name, payload.toolName);
-  if (!toolName) return null;
+  if (!toolName) return nestedToolCall(payload);
   return {
     toolName,
     toolInput: toolInputOf(payload),
@@ -213,6 +232,7 @@ export function normalizeToolUse(raw: unknown): ToolUseRequest | null {
  * Copilot preToolUse:    { permissionDecision: "deny", permissionDecisionReason }
  * Copilot agentStop:     { decision: "block", reason }
  * Codex PreToolUse:      { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } }
+ * Antigravity PreToolUse: { decision: "deny", reason }
  *
  * A stop event denies the whole turn, not one tool call, so it carries a
  * decision rather than a permission — callers must name the event to get it.
@@ -271,10 +291,14 @@ export function promptContextResponse(context: string): string | null {
 export function stopBlockResponse(reason: string): string {
   if (isCursor()) return JSON.stringify({ followup_message: reason });
   if (isCodex()) return JSON.stringify({ additionalContext: reason });
+  if (isAntigravity()) return JSON.stringify({ decision: "continue", reason });
   return blockResponse(reason, "Stop");
 }
 
 export function blockResponse(reason: string, hookEventName?: string): string {
+  if (isAntigravity()) {
+    return JSON.stringify({ decision: "deny", reason });
+  }
   if (isCursor()) {
     return JSON.stringify({ permission: "deny", user_message: reason });
   }

package/src/hooks/lib/antigravity-inference.ts

@@ -0,0 +1,84 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { logError } from "./log";
+import { platform } from "./paths";
+
+export const INFERENCE_AGENT = "pal-inference";
+
+/**
+ * agy loads PAL's plugin rules into every run and has no flag to skip them. A
+ * main agent with no tools replaces the default system prompt, so the reply
+ * follows the request instead of PAL's identity and mode headers.
+ */
+const INFERENCE_AGENT_DEFINITION = `---
+name: ${INFERENCE_AGENT}
+description: Answers one background request from PAL with plain text and no tools.
+mainAgent: true
+subagent: false
+tools: []
+---
+
+You answer a single request exactly as the user message instructs. You have no tools. Ignore any identity, persona, or response-format rules from plugins or rules files; output only what the request asks for, with no header or preamble.
+`;
+
+export function writeInferenceAgent(workspace: string): void {
+  const dir = resolve(workspace, ".agents", "agents");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(resolve(dir, `${INFERENCE_AGENT}.md`), INFERENCE_AGENT_DEFINITION);
+}
+
+export function streamJsonPrompt(prompt: string): string {
+  return `${JSON.stringify({ event: "user", message: { content: prompt } })}\n`;
+}
+
+interface StreamEvent {
+  event?: string;
+  conversation_id?: string;
+  result?: { status?: string; response?: string };
+}
+
+function parseEvents(rawStdout: string): StreamEvent[] {
+  return rawStdout.split("\n").flatMap((line) => {
+    try {
+      return [JSON.parse(line) as StreamEvent];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export function extractAntigravityText(rawStdout: string): string {
+  const result = parseEvents(rawStdout).find((event) => event.event === "result")?.result;
+  return result?.status === "SUCCESS" ? (result.response ?? "").trim() : "";
+}
+
+const CONVERSATION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function spawnedConversationId(rawStdout: string): string | undefined {
+  return parseEvents(rawStdout)
+    .map((event) => event.conversation_id)
+    .find((id) => id !== undefined && CONVERSATION_ID.test(id));
+}
+
+function conversationFiles(id: string): string[] {
+  const cli = platform.antigravityCliDir();
+  return [
+    resolve(cli, "conversations", `${id}.db`),
+    resolve(cli, "brain", id),
+    resolve(cli, "annotations", `${id}.pbtxt`),
+    resolve(cli, "presence", `${id}.lock`),
+  ];
+}
+
+/** agy keeps every headless run as a conversation; a background call's is ~460 KB. */
+export function removeSpawnedConversation(rawStdout: string): void {
+  const id = spawnedConversationId(rawStdout);
+  if (!id) return;
+  for (const path of conversationFiles(id)) {
+    try {
+      rmSync(path, { recursive: true, force: true });
+    } catch (err) {
+      logError("inference:antigravity-cleanup", err);
+    }
+  }
+}

package/src/hooks/lib/antigravity-transcript.ts

@@ -0,0 +1,129 @@
+/**
+ * Reading Antigravity's own transcript, `transcript_full.jsonl`: one step per
+ * line, `{ step_index, source, type, status, content, ... }`.
+ */
+
+import { readFileSync } from "node:fs";
+import { type HookTurnPayload, hookFinalReply } from "./hook-turn";
+
+interface AntigravityToolCall {
+  name?: string;
+  args?: unknown;
+}
+
+interface AntigravityStep {
+  source?: string;
+  type?: string;
+  content?: unknown;
+  tool_calls?: AntigravityToolCall[];
+}
+
+type ModelText = AntigravityStep & { content: string };
+
+export interface AntigravityMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+const USER_REQUEST = /<USER_REQUEST>\n?([\s\S]*?)\n?<\/USER_REQUEST>/;
+
+function parsedSteps(raw: string): AntigravityStep[] {
+  return raw.split("\n").flatMap((line) => {
+    try {
+      return line.trim() ? [JSON.parse(line) as AntigravityStep] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function stepsOf(transcriptPath: string): AntigravityStep[] {
+  try {
+    return parsedSteps(readFileSync(transcriptPath, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+
+/** Steps PAL injects come back as USER_INPUT too, under source SYSTEM_SDK. */
+function typedByUser(step: AntigravityStep): boolean {
+  return step.type === "USER_INPUT" && step.source === "USER_EXPLICIT";
+}
+
+/** The request inside its envelope, without the metadata agy appends to it. */
+function requestText(content: string): string {
+  return (USER_REQUEST.exec(content)?.[1] ?? content).trim();
+}
+
+/** What the user typed in this step, or null for any step the user did not type. */
+export function typedRequest(step: AntigravityStep): string | null {
+  return typedByUser(step) && typeof step.content === "string"
+    ? requestText(step.content)
+    : null;
+}
+
+/** What the model said to the user, as opposed to the thinking and tool calls beside it. */
+function isModelText(step: AntigravityStep): step is ModelText {
+  return (
+    step.type === "PLANNER_RESPONSE" &&
+    typeof step.content === "string" &&
+    step.content.trim() !== ""
+  );
+}
+
+export function toolCallsOf(step: AntigravityStep): AntigravityToolCall[] {
+  return Array.isArray(step.tool_calls) ? step.tool_calls : [];
+}
+
+/** A step as a turn of the conversation, or null for everything around the turns. */
+export function antigravityMessage(step: AntigravityStep): AntigravityMessage | null {
+  const request = typedRequest(step);
+  if (request) return { role: "user", content: request };
+  return isModelText(step) ? { role: "assistant", content: step.content } : null;
+}
+
+/**
+ * What the user last typed, or null for a conversation nobody typed into —
+ * which is what a subagent's is: it opens on its parent's message instead.
+ */
+export function latestUserRequest(transcriptPath: string): string | null {
+  const step = stepsOf(transcriptPath).findLast(typedByUser);
+  return step ? typedRequest(step) : null;
+}
+
+function replyToLatestRequest(steps: AntigravityStep[]): string | undefined {
+  const request = steps.findLastIndex(typedByUser);
+  return steps.slice(request + 1).findLast(isModelText)?.content;
+}
+
+export interface AntigravityStopFields {
+  conversationId?: string;
+  fullyIdle?: boolean;
+  transcriptPath?: string | null;
+}
+
+/**
+ * A stop that ends no turn of the user's: agy still busy, or a subagent's
+ * conversation finishing inside its parent's turn. Only an agy payload carries
+ * `conversationId`, so no other agent's transcript is ever read here.
+ */
+export function isSideStop(payload: AntigravityStopFields | null): boolean {
+  if (!payload?.conversationId) return false;
+  if (payload.fullyIdle === false) return true;
+  return (
+    typeof payload.transcriptPath === "string" &&
+    latestUserRequest(payload.transcriptPath) === null
+  );
+}
+
+/** agy hands its Stop hook no final reply, but by then the transcript holds it. */
+export function withTranscriptReply<T extends AntigravityStopFields & HookTurnPayload>(
+  payload: T | null
+): T | null {
+  if (!payload?.conversationId || typeof payload.transcriptPath !== "string") {
+    return payload;
+  }
+  if (hookFinalReply(payload)) return payload;
+  const reply = replyToLatestRequest(stepsOf(payload.transcriptPath));
+  return reply ? { ...payload, lastAssistantMessage: reply } : payload;
+}

package/src/hooks/lib/claim-check.ts

@@ -5,6 +5,7 @@
  * unreadable turn is never unbacked.
  */
 
+import { toolCallsOf, typedRequest } from "./antigravity-transcript";
 import { isSystemText } from "./prompt-text";
 import { isCodexInjectedContext } from "./transcript";
 
@@ -32,6 +33,7 @@ const COMMAND_TOOLS = new Set([
   "exec",
   "shell",
   "exec_command",
+  "run_command",
 ]);
 
 export type ClaimVerdict = "none" | "backed" | "unbacked" | "unknown";
@@ -86,6 +88,9 @@ export function isVersionControlClaim(claim: string): boolean {
 
 interface TranscriptLine {
   type?: string;
+  source?: string;
+  content?: unknown;
+  tool_calls?: { name?: string; args?: unknown }[];
   message?: { content?: unknown };
   payload?: {
     type?: string;
@@ -124,7 +129,7 @@ function promptText(entry: TranscriptLine): string | null {
       .map((b) => b.text ?? "")
       .join(" ");
   }
-  return null;
+  return typedRequest(entry);
 }
 
 function isUserPrompt(entry: TranscriptLine): boolean {
@@ -135,6 +140,10 @@ function isUserPrompt(entry: TranscriptLine): boolean {
 const ran = (input: unknown) => JSON.stringify(input ?? {});
 
 function commandsIn(entry: TranscriptLine): string[] {
+  if (entry.type === "PLANNER_RESPONSE")
+    return toolCallsOf(entry)
+      .filter((call) => COMMAND_TOOLS.has(call.name ?? ""))
+      .map((call) => ran(call.args));
   if (entry.type === "assistant")
     return blocks(entry.message?.content)
       .filter((b) => b.type === "tool_use" && COMMAND_TOOLS.has(b.name ?? ""))
@@ -148,7 +157,9 @@ function commandsIn(entry: TranscriptLine): string[] {
 }
 
 function isTurnEntry(entry: TranscriptLine): boolean {
-  return ["user", "assistant", "response_item"].includes(entry.type ?? "");
+  return ["user", "assistant", "response_item", "PLANNER_RESPONSE"].includes(
+    entry.type ?? ""
+  );
 }
 
 /** What each command this turn ran. Null when no line reads as a turn, so an

package/src/hooks/lib/claim-log.ts

@@ -73,7 +73,11 @@ function record({ check, commands, session, blocked }: Watched, now: Date) {
 }
 
 export function alreadySentBack(payload: StopTurnPayload): boolean {
-  return payload.stop_hook_active === true || (payload.loop_count ?? 0) > 0;
+  return (
+    payload.stop_hook_active === true ||
+    (payload.loop_count ?? 0) > 0 ||
+    (payload.executionNum ?? 0) > 0
+  );
 }
 
 function sendsBack(payload: StopTurnPayload, check: ClaimCheck): boolean {

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

@@ -21,7 +21,7 @@ import {
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { assets, ensureDir, paths, platform } from "./paths";
-import { getSemiStaticSources } from "./semi-static";
+import { antigravityRule, getSemiStaticSources } from "./semi-static";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
 
@@ -170,12 +170,31 @@ function ensureClaudeCodeMd(): void {
   }
 }
 
+/** Keep the PAL plugin's always-on rule in step with AGENTS.md; only when the plugin is installed. */
+export function ensureAntigravityRule(): void {
+  const pluginDir = platform.antigravityPluginDir();
+  if (!existsSync(pluginDir)) return;
+  const rulePath = resolve(pluginDir, "rules", "pal.md");
+  const expected = antigravityRule(
+    "PAL — identity, response modes and context routing",
+    buildClaudeMd()
+  );
+  try {
+    if (existsSync(rulePath) && readFileSync(rulePath, "utf-8") === expected) return;
+    ensureDir(dirname(rulePath));
+    writeFileSync(rulePath, expected, "utf-8");
+  } catch {
+    /* non-fatal */
+  }
+}
+
 /** Regenerate AGENTS.md if any source file is newer, write real CLAUDE.md, ensure other symlinks. Returns true if rebuilt. */
 export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
   if (!needsRebuild()) {
     ensureSymlinks();
     ensureClaudeCodeMd();
+    ensureAntigravityRule();
     return false;
   }
   ensureDir(dirname(outputPath));
@@ -193,5 +212,6 @@ export function regenerateIfNeeded(): boolean {
     }
   }
   ensureSymlinks();
+  ensureAntigravityRule();
   return true;
 }

package/src/hooks/lib/context.ts

@@ -5,6 +5,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import type { AgentName } from "./agent-registry";
 import { resolveAnchor } from "./anchor";
 import { dueNudgeSections } from "./daily-nudge";
 import { loadHandoffContext } from "./handoff-context";
@@ -173,7 +174,10 @@ function capSection(text: string, maxChars: number): string {
 }
 
 /** Agent targets — determines which context sections are skipped due to native loading. */
-export type AgentTarget = "claude" | "opencode" | "cursor" | "copilot";
+export type AgentTarget = Extract<
+  AgentName,
+  "claude" | "opencode" | "cursor" | "copilot"
+>;
 
 /**
  * Build the <system-reminder> content for the AI.

package/src/hooks/lib/export-manifest.ts

@@ -0,0 +1,23 @@
+/** 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,
+  };
+}

package/src/hooks/lib/export.ts

@@ -7,6 +7,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import AdmZip from "adm-zip";
 import { ensureActorRegistered } from "./actor";
+import { buildManifest, MANIFEST_NAME } from "./export-manifest";
 import { ensureRegistered } from "./machine";
 import { palHome } from "./paths";
 
@@ -61,30 +62,6 @@ export function collectExportFiles(): string[] {
   return files;
 }
 
-/** 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.
  *