pi-openappa 0.0.0-stage → 0.1.0

package/src/adapter.ts

@@ -0,0 +1,284 @@
+/**
+ * Pure translation between host events and the OpenAPPA `appa hook` wire.
+ *
+ * This module must stay runtime-agnostic: no Pi imports, no I/O. Everything
+ * that knows about `appa hook` subprocess semantics lives in hook-client.ts;
+ * everything that knows about Pi lives in extensions/index.ts.
+ *
+ * Wire facts are documented and verified in docs/wire-notes.md (appa 0.31.1).
+ */
+
+export type HookEventName =
+  | "SessionStart"
+  | "UserPromptSubmit"
+  | "PreToolUse"
+  | "PostToolUse"
+  | "Stop";
+
+export interface AppaHookPayload {
+  session_id: string;
+  hook_event_name: HookEventName;
+  source?: "startup" | "resume";
+  prompt?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_response?: Record<string, unknown>;
+  cwd?: string;
+}
+
+/** Decision for a tool call (PreToolUse). */
+export type AppaCallDecision =
+  | { type: "allow" }
+  | { type: "deny"; reason: string };
+
+/** Decision for a tool result (PostToolUse). */
+export type AppaResultDecision =
+  | { type: "pass" }
+  | { type: "replace"; text: string; isError: boolean };
+
+/**
+ * Pi built-in tool names → Claude Code policy names. The claude-code codec
+ * and battery argument selectors are written against these; custom tools pass
+ * through verbatim and policies declare them under the host name.
+ */
+const TOOL_NAME_MAP: Readonly<Record<string, string>> = {
+  bash: "Bash",
+  powershell: "PowerShell",
+  read: "Read",
+  edit: "Edit",
+  write: "Write",
+  grep: "Grep",
+  find: "Glob",
+  ls: "LS",
+};
+
+export function mapToolName(piName: string): string {
+  return TOOL_NAME_MAP[piName] ?? piName;
+}
+
+/** pi session_start reason → Claude Code SessionStart source. */
+export function mapSessionSource(
+  reason: "startup" | "reload" | "new" | "resume" | "fork",
+): "startup" | "resume" {
+  return reason === "resume" || reason === "fork" || reason === "reload"
+    ? "resume"
+    : "startup";
+}
+
+export function sessionStartPayload(
+  sessionId: string,
+  reason: "startup" | "reload" | "new" | "resume" | "fork",
+  cwd: string,
+): AppaHookPayload {
+  return {
+    session_id: sessionId,
+    hook_event_name: "SessionStart",
+    source: mapSessionSource(reason),
+    cwd,
+  };
+}
+
+export function promptPayload(
+  sessionId: string,
+  prompt: string,
+  cwd: string,
+): AppaHookPayload {
+  return {
+    session_id: sessionId,
+    hook_event_name: "UserPromptSubmit",
+    prompt,
+    cwd,
+  };
+}
+
+/**
+ * Build the PreToolUse payload. The returned payload's `tool_input` reference
+ * must be echoed byte-identically at PostToolUse time: the runtime digests it
+ * canonically and withholds results that mismatch (byte_mismatch). Callers
+ * must keep the exact `input` object they passed here until the call settles.
+ */
+export function preToolUsePayload(
+  sessionId: string,
+  piToolName: string,
+  input: Record<string, unknown>,
+  cwd: string,
+): AppaHookPayload {
+  return {
+    session_id: sessionId,
+    hook_event_name: "PreToolUse",
+    tool_name: mapToolName(piToolName),
+    tool_input: input,
+    cwd,
+  };
+}
+
+/**
+ * Build the PostToolUse payload. `input` MUST be the exact object previously
+ * passed to preToolUsePayload for this call (see its doc comment).
+ */
+export function postToolUsePayload(
+  sessionId: string,
+  piToolName: string,
+  input: Record<string, unknown>,
+  response: Record<string, unknown>,
+  cwd: string,
+): AppaHookPayload {
+  return {
+    session_id: sessionId,
+    hook_event_name: "PostToolUse",
+    tool_name: mapToolName(piToolName),
+    tool_input: input,
+    tool_response: response,
+    cwd,
+  };
+}
+
+export function stopPayload(sessionId: string): AppaHookPayload {
+  return { session_id: sessionId, hook_event_name: "Stop" };
+}
+
+/**
+ * Host tool result → Claude-Code-shaped `tool_response`. Structured fields are
+ * copied when the host provides them; every result also carries the joined
+ * text and error flag so unknown tools stay observable.
+ */
+export function toolResponseFrom(parts: {
+  text?: string;
+  isError?: boolean;
+  details?: unknown;
+}): Record<string, unknown> {
+  const response: Record<string, unknown> = {
+    output: parts.text ?? "",
+    isError: parts.isError === true,
+  };
+  if (isRecord(parts.details)) {
+    for (const key of ["stdout", "stderr", "exitcode", "interrupted"] as const) {
+      const value = parts.details[key];
+      if (value !== undefined) response[key] = value;
+    }
+  }
+  return response;
+}
+
+/** Render a runtime-supplied `updatedToolOutput` as model-facing text. */
+export function renderToolOutput(output: Record<string, unknown>): string {
+  const stdout = typeof output.stdout === "string" ? output.stdout : undefined;
+  const stderr = typeof output.stderr === "string" ? output.stderr : undefined;
+  if (stdout !== undefined || stderr !== undefined) {
+    const parts: string[] = [];
+    if (stdout !== undefined && stdout !== "") parts.push(stdout);
+    if (stderr !== undefined && stderr !== "") parts.push(stderr);
+    if (parts.length > 0) return parts.join("\n");
+  }
+  return JSON.stringify(output, null, 2);
+}
+
+const BLOCKED_PREFIX = "OpenAPPA hook blocked: ";
+
+function reasonFromStderr(stderr: string): string {
+  const trimmed = stderr.trim();
+  if (trimmed.startsWith(BLOCKED_PREFIX)) {
+    return trimmed.slice(BLOCKED_PREFIX.length);
+  }
+  return trimmed;
+}
+
+interface StdoutDecision {
+  permissionDecision?: string;
+  permissionDecisionReason?: string;
+  decision?: string;
+  reason?: string;
+  error?: string;
+  hookSpecificOutput?: {
+    hookEventName?: string;
+    permissionDecision?: string;
+    permissionDecisionReason?: string;
+    updatedToolOutput?: Record<string, unknown>;
+  };
+}
+
+function parseStdout(stdout: string): StdoutDecision | undefined {
+  const text = stdout.trim();
+  if (text === "" || text === "{}") return undefined;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return isRecord(parsed) ? (parsed as StdoutDecision) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Map a finished `appa hook` invocation for a PreToolUse event to a call
+ * decision. Fail-closed: every unrecognized outcome denies.
+ */
+export function parseCallDecision(
+  exitCode: number,
+  stdout: string,
+  stderr: string,
+): AppaCallDecision {
+  const out = parseStdout(stdout);
+  if (exitCode === 0 && out === undefined) return { type: "allow" };
+  if (out?.error !== undefined && exitCode !== 0) {
+    return { type: "deny", reason: String(out.error) };
+  }
+  const permission = out?.hookSpecificOutput?.permissionDecision ?? out?.permissionDecision;
+  if (permission === "deny") {
+    return {
+      type: "deny",
+      reason:
+        out?.hookSpecificOutput?.permissionDecisionReason ??
+        out?.permissionDecisionReason ??
+        out?.reason ??
+        "denied by APPA policy",
+    };
+  }
+  if (out?.decision === "block" || out?.decision === "deny_call") {
+    return { type: "deny", reason: out?.reason ?? "blocked by APPA policy" };
+  }
+  if (exitCode === 0 && (permission === "allow" || permission === undefined)) {
+    if (out?.decision !== undefined && out.decision !== "allow") {
+      // A decision we do not understand is treated as a denial, not a pass.
+      return {
+        type: "deny",
+        reason: out?.reason ?? `unrecognized APPA decision: ${out.decision}`,
+      };
+    }
+    return { type: "allow" };
+  }
+  return {
+    type: "deny",
+    reason: reasonFromStderr(stderr) || `appa hook exited ${exitCode}`,
+  };
+}
+
+/**
+ * Map a finished `appa hook` invocation for a PostToolUse event to a result
+ * decision. The runtime replaces results through `updatedToolOutput`; exit 2
+ * or an unreadable outcome withholds the result (isError) rather than passing
+ * possibly-unauthorized content through.
+ */
+export function parseResultDecision(
+  exitCode: number,
+  stdout: string,
+  stderr: string,
+): AppaResultDecision {
+  const out = parseStdout(stdout);
+  const updated = out?.hookSpecificOutput?.updatedToolOutput;
+  if (exitCode === 0 && isRecord(updated)) {
+    return { type: "replace", text: renderToolOutput(updated), isError: false };
+  }
+  if (exitCode === 0 && (out === undefined || out.decision === undefined || out.decision === "allow")) {
+    return { type: "pass" };
+  }
+  const reason =
+    out?.reason ??
+    (out?.error !== undefined ? String(out.error) : undefined) ??
+    reasonFromStderr(stderr) ??
+    (exitCode === 0 ? "tool result withheld by APPA policy" : `appa hook exited ${exitCode}`);
+  return { type: "replace", text: reason, isError: true };
+}

package/src/gate.ts

@@ -0,0 +1,135 @@
+/**
+ * Session gate: protection is opt-in, fixed at session start.
+ *
+ * Three ways a session becomes protected, most specific first for reporting:
+ * - a project marker `<cwd>/.pi/openappa` (project-scoped; optional content
+ *   names that project's policy, absolute or cwd-relative),
+ * - launched with APPA_GATE=1 (the launcher route, mirroring `clappa`), or
+ * - always-on mode, persisted by `/appa on` (marker file below).
+ *
+ * An explicit APPA_CONFIG always wins as the policy source; otherwise a
+ * project marker's content is used; otherwise APPA's own default. The gate is
+ * captured once per session so a session cannot disable its own protection
+ * mid-run; `/appa on|off` are deliberate user commands and do re-resolve.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+export const DEFAULT_RUNTIME_URL = "http://127.0.0.1:8787";
+
+/** Base config directory honoring XDG_CONFIG_HOME, falling back to ~/.config. */
+function baseConfigDir(env: NodeJS.ProcessEnv): string {
+  const xdg = env.XDG_CONFIG_HOME;
+  if (xdg !== undefined && xdg !== "") return xdg;
+  return join(env.HOME ?? "", ".config");
+}
+
+export function alwaysOnMarkerPath(env: NodeJS.ProcessEnv): string {
+  return join(baseConfigDir(env), "pi-openappa", "always-on");
+}
+
+export function projectMarkerPath(cwd: string): string {
+  return join(cwd, ".pi", "openappa");
+}
+
+export function isAlwaysOn(env: NodeJS.ProcessEnv): boolean {
+  return existsSync(alwaysOnMarkerPath(env));
+}
+
+export function setAlwaysOn(env: NodeJS.ProcessEnv, on: boolean): void {
+  const marker = alwaysOnMarkerPath(env);
+  if (on) {
+    mkdirSync(dirname(marker), { recursive: true });
+    writeFileSync(marker, "");
+  } else {
+    rmSync(marker, { force: true });
+  }
+}
+
+export type GateSource = "project" | "env" | "always-on" | "off";
+
+export interface GateState {
+  /** Protection active for this session. */
+  gated: boolean;
+  /** Most specific reason this session is (or is not) protected. */
+  source: GateSource;
+  /** Policy for auto-start: explicit env wins, then project marker content. */
+  config?: string;
+  /** Runtime URL for health reporting (the hook binary reads it from env). */
+  runtimeUrl: string;
+  /** Hook binary used for reporting. */
+  hookBin: string;
+}
+
+/** Read a project marker's optional policy path; empty content resolves to none. */
+function projectConfig(cwd: string): string | undefined {
+  try {
+    const content = readFileSync(projectMarkerPath(cwd), "utf8").trim();
+    if (content === "") return undefined;
+    return isAbsolute(content) ? content : resolve(cwd, content);
+  } catch {
+    return undefined;
+  }
+}
+
+export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
+  const base = {
+    runtimeUrl: env.APPA_RUNTIME_URL ?? DEFAULT_RUNTIME_URL,
+    hookBin: env.APPA_HOOK_BIN ?? "appa",
+  };
+  const explicitConfig =
+    env.APPA_CONFIG !== undefined && env.APPA_CONFIG !== ""
+      ? env.APPA_CONFIG
+      : undefined;
+  const projectGated = cwd !== undefined && existsSync(projectMarkerPath(cwd));
+  const projectCfg =
+    projectGated && cwd !== undefined ? projectConfig(cwd) : undefined;
+  const config = explicitConfig ?? projectCfg;
+
+  if (env.APPA_GATE === "1" || projectGated) {
+    return {
+      gated: true,
+      source: projectGated ? "project" : "env",
+      ...base,
+      ...(config !== undefined ? { config } : {}),
+    };
+  }
+  if (isAlwaysOn(env)) {
+    return {
+      gated: true,
+      source: "always-on",
+      ...base,
+      ...(explicitConfig !== undefined ? { config: explicitConfig } : {}),
+    };
+  }
+  return { gated: false, source: "off", ...base };
+}
+
+export interface HealthResult {
+  ok: boolean;
+  detail: string;
+}
+
+export async function checkHealth(
+  runtimeUrl: string,
+  timeoutMs = 2000,
+): Promise<HealthResult> {
+  try {
+    const response = await fetch(new URL("health", withSlash(runtimeUrl)), {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const body = (await response.text()).trim();
+    if (response.ok && body === "ok") {
+      return { ok: true, detail: "ok" };
+    }
+    return { ok: false, detail: body !== "" ? body : `HTTP ${response.status}` };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return { ok: false, detail };
+  }
+}
+
+function withSlash(url: string): string {
+  return url.endsWith("/") ? url : `${url}/`;
+}

package/src/hook-client.ts

@@ -0,0 +1,133 @@
+/**
+ * The only module that talks to OpenAPPA: it runs `appa hook` and returns the
+ * raw outcome. It never decides — adapter.ts interprets, extensions wire.
+ *
+ * Design rules:
+ * - Never throw for policy or transport outcomes; every failure becomes a
+ *   HookOutcome the decision parsers treat as fail-closed.
+ * - Gate and URL come from the inherited environment (APPA_GATE is checked by
+ *   the gate module before any invocation happens; APPA_RUNTIME_URL and other
+ *   APPA_* conventions flow straight through to the binary).
+ */
+
+import { spawn } from "node:child_process";
+import type { AppaHookPayload } from "./adapter.ts";
+
+export interface HookOutcome {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+export interface InvokeOptions {
+  /** Report a finished turn (non-blocking `--turn-end`). */
+  turnEnd?: boolean;
+  /** Bring the runtime up before posting (SessionStart semantics). */
+  ensureRuntime?: boolean;
+  /** Config the started runtime serves; requires ensureRuntime. */
+  config?: string;
+  /** Override for the `appa` binary; defaults to APPA_HOOK_BIN or "appa". */
+  bin?: string;
+  /** Kill the hook after this many ms; defaults to APPA_HOOK_TIMEOUT_MS or 15000. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export function resolveHookBin(env: NodeJS.ProcessEnv): string {
+  return env.APPA_HOOK_BIN ?? "appa";
+}
+
+export function resolveTimeoutMs(env: NodeJS.ProcessEnv): number {
+  const raw = Number(env.APPA_HOOK_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+
+export async function invokeAppaHook(
+  payload: AppaHookPayload,
+  options: InvokeOptions = {},
+): Promise<HookOutcome> {
+  const bin = options.bin ?? resolveHookBin(process.env);
+  const timeoutMs = options.timeoutMs ?? resolveTimeoutMs(process.env);
+  const args = ["hook"];
+  if (options.turnEnd === true) args.push("--turn-end");
+  if (options.ensureRuntime === true) args.push("--ensure-runtime");
+  if (options.config !== undefined) args.push("--config", options.config);
+
+  return await new Promise<HookOutcome>((resolve) => {
+    let child;
+    try {
+      child = spawn(bin, args, {
+        env: { ...process.env, APPA_GATE: "1" },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch (error) {
+      resolve(spawnFailure(error));
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+
+    const finish = (exitCode: number) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (timedOut) {
+        resolve({
+          exitCode: -1,
+          stdout,
+          stderr: `${stderr}appa hook timed out after ${timeoutMs}ms`.trim(),
+          timedOut: true,
+        });
+        return;
+      }
+      resolve({ exitCode, stdout, stderr, timedOut: false });
+    };
+
+    child.on("error", (error) => {
+      resolve(mergeOutcome(spawnFailure(error), stderr));
+      settled = true;
+      clearTimeout(timer);
+    });
+    child.on("close", (code) => finish(code ?? -1));
+
+    try {
+      child.stdin?.end(JSON.stringify(payload));
+    } catch (error) {
+      child.kill("SIGKILL");
+      resolve(mergeOutcome(spawnFailure(error), stderr));
+      settled = true;
+      clearTimeout(timer);
+    }
+  });
+}
+
+function spawnFailure(error: unknown): HookOutcome {
+  const detail = error instanceof Error ? error.message : String(error);
+  return {
+    exitCode: -1,
+    stdout: "",
+    stderr: `appa hook failed to start: ${detail}`,
+    timedOut: false,
+  };
+}
+
+function mergeOutcome(base: HookOutcome, stderrSoFar: string): HookOutcome {
+  return { ...base, stderr: `${stderrSoFar}${base.stderr}`.trim() };
+}