pi-openappa 0.1.0 → 0.3.0

package/README.md

@@ -17,7 +17,8 @@ pi event ◀── enforce  ◀── decision  ◀─────────
 - The `appa` binary on `PATH` ([install](https://openappa.com)) — version
   0.31.x verified; see `docs/wire-notes.md` for the recorded contract
 - An APPA runtime listening on loopback (default `127.0.0.1:8787`)
-- A policy (`appa.toml`) that declares the tools your sessions may use
+- A policy (`appa.toml`) that declares the tools your sessions may use —
+  `/appa init` writes a starter one, or copy `templates/appa.toml`
 
 ## Install
 
@@ -43,10 +44,13 @@ Protection is opt-in, in one of three ways:
   protected. `/appa off` disables.
 - **Per launch:** `APPA_GATE=1 pi` (the `clappa`-style launcher route).
 
-A gated session brings the runtime up on its own: `session_start` invokes
-`appa hook --ensure-runtime`, passing `--config "$APPA_CONFIG"` when set and
-otherwise letting APPA use its own default policy (`~/.config/appa/appa.toml`).
-Protected sessions therefore need zero manual server management. A custom
+A gated session brings the runtime up on its own: `session_start` sends
+`appa hook --ensure-runtime` (passing `--config` when a policy is resolved),
+but **does not wait for it** — the boot runs on a serialized background lane,
+so a cold runtime, a first-run install, or a slow start never sits in Pi's
+session-start path. Ordering is preserved: the SessionStart payload always
+lands before the first `PreToolUse`, and a runtime that cannot answer fails
+that first call closed with the reason (silence never means yes). A custom
 `APPA_RUNTIME_URL` names a runtime that is *yours* to start — the hook
 refuses with exactly that reason instead of guessing.
 
@@ -57,15 +61,68 @@ every tool call blocked. Ungated sessions never invoke the hook.
 
 ## Configuration
 
-| Variable | Default | Meaning |
+| Source | Default | Meaning |
 |---|---|---|
 | `APPA_GATE` | unset | `1` protects this session (read once at launch) |
 | `.pi/openappa` | absent | Project marker: gates sessions started in that directory; optional content = policy path |
+| `~/.config/pi-openappa/settings.json` | absent | File settings: `config`, `runtimeUrl`, `hookBin`, `hookTimeoutMs`; env always wins, project markers beat `config` |
 | `APPA_RUNTIME_URL` | `http://127.0.0.1:8787` | Runtime endpoint (loopback only) |
 | `APPA_CONFIG` | unset | `appa.toml` the session auto-starts the runtime with |
 | `APPA_HOOK_BIN` | `appa` | Hook binary to invoke |
 | `APPA_HOOK_TIMEOUT_MS` | `15000` | Kill the hook after this long; the call is then blocked |
 
+Policy resolution order: `APPA_CONFIG`, then the project marker's content,
+then `settings.json`'s `config`, then APPA's own default
+(`~/.config/appa/appa.toml`).
+
+## Starter policy: `/appa init`
+
+`templates/appa.toml` is a complete, self-contained policy written for Pi.
+It gates **flows, not tools**: sources mark data, sinks check it.
+
+| When a session carries… | it is refused at… |
+|---|---|
+| web text (`curl`/`wget`, `web_explore`, context7) | editing any existing file except docs/openspec/`*.md` (research lands in docs, it doesn't rewrite code); writing tests, devops (Makefile, justfile, scripts, CI, Dockerfile), infra (terraform, k8s, helm…), or credential-shaped paths; `git push` / `gh …`; `mem_save`/`mem_update` (poisoned memory must not persist) |
+| `.env`/credentials (read or commanded) | web tools (a secret-narrowed session cannot prove a query shareable) — trusted docs domains carved out for `curl`; bash output returns masked via `redact-secrets` |
+| anything | editing appa's own policy files |
+| nothing (clean session) | nowhere — reads, edits, tests, commits, pushes all flow |
+
+An undeclared tool is refused before it runs (deny-by-default; a `*`
+wildcard requires an annotator, so refusing is the only annotator-free
+stance — the commented `builtin = "llm"` block shows the classifier
+upgrade). Selectors use **Pi argument names** (`Read(path:…)`, not Claude
+Code's `file_path` — the stock battery's never match a Pi call), and the
+policy is **static rules only**: nothing host-coupled, nothing that can be
+unreachable. Taint lives in the trajectory label and only narrows — the
+manual reset is a **new session** (resume/fork inherit it; there is no
+`/untaint` by design).
+
+Install it one of three ways:
+
+```sh
+/appa init               # inside Pi: writes ~/.config/appa/appa.toml (+ settings.json)
+/appa init project       # writes ./appa.toml and the .pi/openappa marker
+cp templates/appa.toml ~/.config/appa/appa.toml   # from a checkout
+```
+
+`init` never clobbers: rerun with `--force` to overwrite. Subcommands
+autocomplete (`on`, `off`, `init`, `init project`, `status`).
+
+### Policy-as-code
+
+The policy is tested like code — no runtime needed, only the `appa` CLI:
+
+```sh
+just policy-check      # templates/appa.toml loads
+just policy-coverage   # every known Pi tool declared (Day E: refusals fail)
+just policy-test       # replay the usage-day traces (Days A–D, F)
+```
+
+`traces/*.appa` are line-based replays (`<canonical-tool> {` / one `arg:`
+JSON value per line / `}` / `expect allow|withhold|deny`); calls in one
+file share a trajectory, so taint accumulates exactly as live. All three
+gates run in `just check`.
+
 `/appa` reports protection, always-on state, and runtime health; `/appa on`
 and `/appa off` toggle always-on protection (marker:
 `~/.config/pi-openappa/always-on`), taking effect immediately including the

package/extensions/index.ts

@@ -3,12 +3,16 @@
  *
  * Thin by design: translate Pi events to `appa hook` invocations and enforce
  * the answer. No policy logic lives here; the APPA runtime owns every
- * decision. Protection is opt-in per session (APPA_GATE=1 at launch) and
- * fail-closed while gated: if the runtime cannot answer, the call is blocked.
+ * decision. Protection is opt-in per session (APPA_GATE=1 at launch, a
+ * project marker, or always-on) and fail-closed while gated: if the runtime
+ * cannot answer, the call is blocked.
  *
  * Wire facts and constraints: docs/wire-notes.md
  */
 
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   parseCallDecision,
@@ -20,14 +24,30 @@ import {
   stopPayload,
   toolResponseFrom,
 } from "../src/adapter.ts";
+import type { InvokeOptions } from "../src/hook-client.ts";
 import { invokeAppaHook } from "../src/hook-client.ts";
-import { captureGate, checkHealth, setAlwaysOn, type GateState } from "../src/gate.ts";
+import {
+  appaDefaultConfigPath,
+  captureGate,
+  checkHealth,
+  setAlwaysOn,
+  settingsPath,
+  type GateState,
+} from "../src/gate.ts";
 
 interface TextPart {
   type: "text";
   text: string;
 }
 
+/** The starter policy `/appa init` writes (templates/appa.toml in this package). */
+function templateToml(): string {
+  return readFileSync(
+    fileURLToPath(new URL("../templates/appa.toml", import.meta.url)),
+    "utf8",
+  );
+}
+
 export default function (pi: ExtensionAPI): void {
   /** Launch-fixed protection state; null until the session starts. */
   let gate: GateState | null = null;
@@ -39,44 +59,78 @@ export default function (pi: ExtensionAPI): void {
    */
   const pendingInputs = new Map<string, Record<string, unknown>>();
 
+  /**
+   * Serialized hook lane. Every `appa hook` invocation for this session runs
+   * through here in order, so the SessionStart payload (with
+   * `--ensure-runtime`) always lands before the first PreToolUse even though
+   * session_start does not wait for it. Startup stays off the fast-start
+   * lane: the runtime boot cost is paid by whichever tool call needs the
+   * runtime first, and a runtime that cannot answer fails that call closed
+   * with the reason — never a slower session start.
+   */
+  let lane: Promise<unknown> = Promise.resolve();
+  const enqueue = <T>(run: () => Promise<T>): Promise<T> => {
+    const outcome = lane.then(run, run);
+    lane = outcome.then(
+      () => undefined,
+      () => undefined,
+    );
+    return outcome;
+  };
+
   const gated = (): boolean => gate?.gated === true;
 
+  const hookOptions = (state: GateState, extra: InvokeOptions = {}): InvokeOptions => {
+    const options: InvokeOptions = { ...extra };
+    if (state.hookTimeoutMs !== undefined) options.timeoutMs = state.hookTimeoutMs;
+    return options;
+  };
+
   pi.on("session_start", async (event, ctx) => {
     gate = captureGate(process.env, ctx.cwd);
     sessionId = ctx.sessionManager.getSessionId();
     if (!gated()) return;
-
-    const outcome = await invokeAppaHook(
-      sessionStartPayload(sessionId, event.reason, ctx.cwd),
-      {
-        ensureRuntime: true,
-        ...(gate.config !== undefined ? { config: gate.config } : {}),
-      },
-    );
-    if (outcome.exitCode !== 0 && ctx.hasUI) {
-      const remedy =
-        gate.config === undefined
-          ? " Provide a policy (this project's .pi/openappa, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
-          : "";
-      ctx.ui.notify(
-        `OpenAPPA gated but the runtime did not answer (${gate.runtimeUrl}): ` +
-          `${outcome.stderr.trim() || `exit ${outcome.exitCode}`}.${remedy} ` +
-          "Tool calls will be blocked until it answers.",
-        "warning",
+    const state = gate;
+    const options: InvokeOptions = { ensureRuntime: true };
+    if (state.config !== undefined) options.config = state.config;
+    if (state.hookTimeoutMs !== undefined) options.timeoutMs = state.hookTimeoutMs;
+    // Backgrounded on purpose (see `lane`): a cold runtime boot — or a first
+    // run that still has to install or update the runtime — must not sit in
+    // Pi's session-start path. Failure surfaces as a warning when it settles.
+    void enqueue(async () => {
+      const outcome = await invokeAppaHook(
+        sessionStartPayload(sessionId, event.reason, ctx.cwd),
+        options,
       );
-    }
+      if (outcome.exitCode !== 0 && ctx.hasUI) {
+        const remedy =
+          options.config === undefined
+            ? " Provide a policy (this project's .pi/openappa, /appa init, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
+            : "";
+        ctx.ui.notify(
+          `OpenAPPA gated but the runtime did not answer (${state.runtimeUrl}): ` +
+            `${outcome.stderr.trim() || `exit ${outcome.exitCode}`}.${remedy} ` +
+          "Tool calls will be blocked until it answers.",
+          "warning",
+        );
+      }
+    });
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
     if (!gated()) return;
     // The prompt event establishes the turn boundary; it does not gate.
-    await invokeAppaHook(promptPayload(sessionId, event.prompt, ctx.cwd));
+    await enqueue(() =>
+      invokeAppaHook(promptPayload(sessionId, event.prompt, ctx.cwd), hookOptions(gate!)),
+    );
   });
 
   pi.on("tool_call", async (event, ctx) => {
     if (!gated()) return;
     const payload = preToolUsePayload(sessionId, event.toolName, event.input, ctx.cwd);
-    const outcome = await invokeAppaHook(payload);
+    const outcome = await enqueue(() =>
+      invokeAppaHook(payload, hookOptions(gate!)),
+    );
     const decision = parseCallDecision(outcome.exitCode, outcome.stdout, outcome.stderr);
     if (decision.type === "deny") {
       return { block: true, reason: `appa: ${decision.reason}` };
@@ -101,7 +155,9 @@ export default function (pi: ExtensionAPI): void {
       response,
       ctx.cwd,
     );
-    const outcome = await invokeAppaHook(payload);
+    const outcome = await enqueue(() =>
+      invokeAppaHook(payload, hookOptions(gate!)),
+    );
     const decision = parseResultDecision(outcome.exitCode, outcome.stdout, outcome.stderr);
     if (decision.type === "pass") {
       return undefined;
@@ -115,7 +171,9 @@ export default function (pi: ExtensionAPI): void {
   pi.on("turn_end", async () => {
     if (!gated()) return;
     // Turn completion is reported, never gated (matching --turn-end).
-    await invokeAppaHook(stopPayload(sessionId), { turnEnd: true });
+    await enqueue(() =>
+      invokeAppaHook(stopPayload(sessionId), hookOptions(gate!, { turnEnd: true })),
+    );
   });
 
   pi.on("session_shutdown", () => {
@@ -123,9 +181,36 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("appa", {
-    description: "Show OpenAPPA status; `appa on|off` toggles always-on protection",
+    description:
+      "OpenAPPA guard: status, `appa on|off` always-on, `appa init [project]` writes a starter policy",
+    getArgumentCompletions: (argumentPrefix) => {
+      const items = [
+        {
+          value: "on",
+          label: "on",
+          description: "Protect every future Pi session (always-on marker)",
+        },
+        { value: "off", label: "off", description: "Disable always-on protection" },
+        {
+          value: "init",
+          label: "init",
+          description: "Write the starter policy to ~/.config/appa/appa.toml",
+        },
+        {
+          value: "init project",
+          label: "init project",
+          description: "Write ./appa.toml plus the .pi/openappa project marker",
+        },
+        { value: "status", label: "status", description: "Show protection and runtime health" },
+      ];
+      const prefix = argumentPrefix.trim();
+      const hits = prefix === "" ? items : items.filter((item) => item.value.startsWith(prefix));
+      return hits.length > 0 ? hits : null;
+    },
     handler: async (args, ctx) => {
-      const arg = args.trim();
+      const tokens = args.trim().split(/\s+/).filter((token) => token !== "");
+      const arg = tokens[0] ?? "";
+
       if (arg === "on" || arg === "off") {
         setAlwaysOn(process.env, arg === "on");
         gate = captureGate(process.env, ctx.cwd);
@@ -139,6 +224,14 @@ export default function (pi: ExtensionAPI): void {
         }
         return;
       }
+
+      if (arg === "init") {
+        const scope = tokens[1] === "project" ? "project" : "user";
+        const force = tokens.includes("--force");
+        await runInit(scope, force, ctx);
+        return;
+      }
+
       const state = gate ?? captureGate(process.env, ctx.cwd);
       const mode =
         state.source === "project"
@@ -164,6 +257,59 @@ export default function (pi: ExtensionAPI): void {
       }
     },
   });
+
+  /** `/appa init` — write the starter policy (and settings) without clobbering. */
+  async function runInit(
+    scope: "user" | "project",
+    force: boolean,
+    ctx: { cwd: string; hasUI: boolean; ui: { notify: (message: string, type?: "info" | "warning" | "error") => void } },
+  ): Promise<void> {
+    const notify = (message: string, type: "info" | "warning" | "error" = "info") => {
+      if (ctx.hasUI) ctx.ui.notify(message, type);
+    };
+    try {
+      if (scope === "project") {
+        const policy = join(ctx.cwd, "appa.toml");
+        const marker = join(ctx.cwd, ".pi", "openappa");
+        if (existsSync(policy) && !force) {
+          notify(`${policy} already exists; rerun with --force to overwrite it.`, "warning");
+          return;
+        }
+        mkdirSync(dirname(policy), { recursive: true });
+        writeFileSync(policy, templateToml());
+        if (!existsSync(marker)) {
+          mkdirSync(dirname(marker), { recursive: true });
+          writeFileSync(marker, "appa.toml\n");
+        }
+        notify(
+          `Wrote ${policy} and the .pi/openappa marker. Sessions started in this directory are protected; new sessions pick the policy up (trajectories keep the policy they opened with).`,
+        );
+        return;
+      }
+      const policy = appaDefaultConfigPath(process.env);
+      if (existsSync(policy) && !force) {
+        notify(
+          `${policy} already exists; rerun with --force to overwrite it, or /appa init project for one project.`,
+          "warning",
+        );
+        return;
+      }
+      mkdirSync(dirname(policy), { recursive: true });
+      writeFileSync(policy, templateToml());
+      const settings = settingsPath(process.env);
+      const lines: string[] = [`Wrote the starter policy to ${policy}.`];
+      if (!existsSync(settings)) {
+        mkdirSync(dirname(settings), { recursive: true });
+        writeFileSync(settings, `${JSON.stringify({ config: policy }, null, 2)}\n`);
+        lines.push(`Wrote ${settings} pointing at it.`);
+      }
+      lines.push("Protect sessions with /appa on, APPA_GATE=1, or /appa init project.");
+      notify(lines.join(" "));
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      notify(`/appa init failed: ${detail}`, "error");
+    }
+  }
 }
 
 function joinContent(content: ReadonlyArray<unknown>): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openappa",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Thin OpenAPPA guard extension for Pi: gates tool calls through the APPA runtime. No policy logic lives here.",
   "keywords": [
     "pi-package",
@@ -11,7 +11,21 @@
     "policy"
   ],
   "license": "MIT",
+  "author": "aemonge",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aemonge-dev/pi-openappa.git"
+  },
+  "homepage": "https://github.com/aemonge-dev/pi-openappa#readme",
+  "bugs": "https://github.com/aemonge-dev/pi-openappa/issues",
   "type": "module",
+  "files": [
+    "extensions/",
+    "src/",
+    "templates/",
+    "traces/",
+    "docs/"
+  ],
   "pi": {
     "extensions": ["./extensions/index.ts"]
   },

package/src/gate.ts

@@ -8,7 +8,8 @@
  * - 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
+ * project marker's content is used; otherwise the settings file's `config`;
+ * 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.
  */
@@ -29,6 +30,55 @@ export function alwaysOnMarkerPath(env: NodeJS.ProcessEnv): string {
   return join(baseConfigDir(env), "pi-openappa", "always-on");
 }
 
+/** The policy a gated session auto-starts the runtime with, by APPA default. */
+export function appaDefaultConfigPath(env: NodeJS.ProcessEnv): string {
+  return join(baseConfigDir(env), "appa", "appa.toml");
+}
+
+/** File-backed settings for this extension (see `ExtensionSettings`). */
+export function settingsPath(env: NodeJS.ProcessEnv): string {
+  return join(baseConfigDir(env), "pi-openappa", "settings.json");
+}
+
+/**
+ * Keys read from `settings.json`. Every key is optional; environment
+ * variables of the same meaning always win over the file, and the file
+ * always wins over the built-in defaults. Written by `/appa init`.
+ */
+export interface ExtensionSettings {
+  /** Policy path passed as `--config` (the APPA_CONFIG fallback). */
+  config?: string;
+  /** Runtime endpoint (the APPA_RUNTIME_URL fallback). */
+  runtimeUrl?: string;
+  /** Hook binary (the APPA_HOOK_BIN fallback). */
+  hookBin?: string;
+  /** Hook timeout in ms (the APPA_HOOK_TIMEOUT_MS fallback). */
+  hookTimeoutMs?: number;
+}
+
+/** Read settings.json; a missing or malformed file resolves to `{}`. */
+export function readSettings(env: NodeJS.ProcessEnv): ExtensionSettings {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(settingsPath(env), "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return {};
+    }
+    const out: ExtensionSettings = {};
+    const record = parsed as Record<string, unknown>;
+    for (const key of ["config", "runtimeUrl", "hookBin"] as const) {
+      const value = record[key];
+      if (typeof value === "string" && value !== "") out[key] = value;
+    }
+    const timeout = record["hookTimeoutMs"];
+    if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) {
+      out.hookTimeoutMs = timeout;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
 export function projectMarkerPath(cwd: string): string {
   return join(cwd, ".pi", "openappa");
 }
@@ -54,12 +104,14 @@ export interface GateState {
   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. */
+  /** Policy for auto-start: env, then project marker, then settings file. */
   config?: string;
   /** Runtime URL for health reporting (the hook binary reads it from env). */
   runtimeUrl: string;
   /** Hook binary used for reporting. */
   hookBin: string;
+  /** Hook timeout in ms when settings pin one; otherwise the default applies. */
+  hookTimeoutMs?: number;
 }
 
 /** Read a project marker's optional policy path; empty content resolves to none. */
@@ -74,9 +126,11 @@ function projectConfig(cwd: string): string | undefined {
 }
 
 export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
+  const settings = readSettings(env);
   const base = {
-    runtimeUrl: env.APPA_RUNTIME_URL ?? DEFAULT_RUNTIME_URL,
-    hookBin: env.APPA_HOOK_BIN ?? "appa",
+    runtimeUrl: env.APPA_RUNTIME_URL ?? settings.runtimeUrl ?? DEFAULT_RUNTIME_URL,
+    hookBin: env.APPA_HOOK_BIN ?? settings.hookBin ?? "appa",
+    ...(settings.hookTimeoutMs !== undefined ? { hookTimeoutMs: settings.hookTimeoutMs } : {}),
   };
   const explicitConfig =
     env.APPA_CONFIG !== undefined && env.APPA_CONFIG !== ""
@@ -85,7 +139,9 @@ export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
   const projectGated = cwd !== undefined && existsSync(projectMarkerPath(cwd));
   const projectCfg =
     projectGated && cwd !== undefined ? projectConfig(cwd) : undefined;
-  const config = explicitConfig ?? projectCfg;
+  // Precedence: launch env, then the project marker (per-project intent),
+  // then the global settings file (see readSettings).
+  const config = explicitConfig ?? projectCfg ?? settings.config;
 
   if (env.APPA_GATE === "1" || projectGated) {
     return {
@@ -100,7 +156,7 @@ export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
       gated: true,
       source: "always-on",
       ...base,
-      ...(explicitConfig !== undefined ? { config: explicitConfig } : {}),
+      ...(config !== undefined ? { config } : {}),
     };
   }
   return { gated: false, source: "off", ...base };