pi-openappa 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aemonge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# pi-openappa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A thin [OpenAPPA](https://openappa.com) guard extension for
+[Pi](https://pi.dev): every tool call in a protected session is checked by the
+APPA runtime before it runs, and every tool result before the model sees it.
+No policy logic lives here — the APPA runtime owns every decision; this
+extension only translates events and enforces the answer.
+
+```text
+pi event ──▶ adapter ──▶ `appa hook` ──▶ APPA runtime
+                                          allow / deny / replace
+pi event ◀── enforce  ◀── decision  ◀────────────┘
+```
+
+## Requirements
+
+- 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
+
+## Install
+
+```sh
+pi install npm:pi-openappa        # once published
+pi install ./pi-openappa          # from a checkout
+```
+
+## Protect sessions
+
+Protection is opt-in, in one of three ways:
+
+- **Project-scoped (recommended):** create `<project>/.pi/openappa` — sessions
+  started in that directory are protected, sessions elsewhere are not. The
+  marker's optional content names that project's policy (absolute or
+  cwd-relative); empty content falls back to `APPA_CONFIG` or APPA's default:
+
+  ```sh
+  cd your-project && mkdir -p .pi && echo "appa.toml" > .pi/openappa
+  ```
+
+- **Built-in:** run `/appa on` once — every Pi session everywhere is
+  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
+`APPA_RUNTIME_URL` names a runtime that is *yours* to start — the hook
+refuses with exactly that reason instead of guessing.
+
+While gated, a runtime that cannot answer blocks the call and the reason is
+returned to the model — **silence never means yes**. If no policy exists the
+startup warning names the exact outs; `/appa off` always works, even with
+every tool call blocked. Ungated sessions never invoke the hook.
+
+## Configuration
+
+| Variable | 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 |
+| `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 |
+
+`/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
+current session.
+
+## Event mapping
+
+| Pi event | APPA event | Effect |
+|---|---|---|
+| `session_start` | `SessionStart` | opens the trajectory; warns when the runtime is down |
+| `before_agent_start` | `UserPromptSubmit` | turn boundary (never gates) |
+| `tool_call` | `PreToolUse` | deny blocks the call; the reason reaches the model |
+| `tool_result` | `PostToolUse` | replace swaps the result the model sees |
+| `turn_end` | `Stop` | reported (`--turn-end`), never gates |
+
+Pi built-in tool names map to Claude Code policy names (`bash`→`Bash`,
+`find`→`Glob`, …); custom and MCP tools pass through under their own names and
+policies declare them verbatim.
+
+## Limitations
+
+- **Load order matters in theory**: the runtime digests tool arguments at
+  `PreToolUse`. If another extension rewrites `event.input` after this
+  handler runs, the executed arguments differ from the checked ones and the
+  runtime withholds the result (`byte_mismatch`). Load pi-openappa last if
+  you combine it with argument-rewriting extensions.
+- **Policy edits reach new sessions only**: trajectories keep the policy they
+  opened with, by runtime design. When iterating on a policy, restart the
+  runtime (and start fresh sessions) — a stale runtime or an old trajectory
+  will keep serving the old policy.
+- **Subagents**: spawning is mediated as a plain tool call (deny blocks the
+  spawn). Child trajectories are not linked into the parent's label chain
+  yet; a gated child Pi process opens its own root trajectory.
+- The adapter never starts a runtime for ungated sessions; auto-start needs
+  either `APPA_CONFIG` or an installed APPA deployment.
+- OpenAPPA is Preview & RFC: wire surfaces may break without shims. The
+  entire wire contract lives in `src/hook-client.ts` and `src/adapter.ts`
+  (verified facts in `docs/wire-notes.md`), and the adapter core is
+  runtime-agnostic so a pi-durable wiring can reuse it unchanged.
+
+## Development
+
+```sh
+npm test        # node --test, mock-driven, no runtime needed
+npm run typecheck
+```
+
+The adapter core (`src/adapter.ts`) has no Pi imports by design; the Pi
+wiring is `extensions/index.ts` only.
+
+## License
+
+MIT

package/docs/wire-notes.md

@@ -0,0 +1,80 @@
+# Wire notes: `appa hook` contract (verified 2026-10-06, appa 0.31.1)
+
+All facts below were probed live against `appa runtime` on 127.0.0.1:8791 with a
+minimal one-tool policy. Probes: SessionStart, UserPromptSubmit, PreToolUse (allow,
+undeclared-refuse), PostToolUse (byte-mismatch withhold), Stop --turn-end, plus
+ungated and runtime-down probes.
+
+## Transport
+
+- Subprocess: `appa hook` (env inherited; gate and URL read from env)
+- Gate: inert unless `APPA_GATE=1` — ungated always exits 0, no side effects
+- URL: `APPA_RUNTIME_URL` (default `127.0.0.1:8787`, loopback only)
+- Turn-end: pass `--turn-end` (non-blocking report; exit 0 even when down)
+- Payload: Claude Code hook JSON on stdin
+
+## Payload fields (accepted and observed)
+
+- `session_id` — becomes trajectory `cc:<session_id>` in the runtime
+- `hook_event_name` — `SessionStart` | `UserPromptSubmit` | `PreToolUse` |
+  `PostToolUse` | `Stop`
+- `source` (SessionStart): `startup` | `resume`
+- `prompt` (UserPromptSubmit)
+- `tool_name`, `tool_input` (PreToolUse / PostToolUse)
+- `tool_response` (PostToolUse)
+- `cwd`
+
+## Decision protocol (observed)
+
+- Exit 0, no stdout (or `{}`) → proceed. SessionStart/UserPromptSubmit behave so.
+- Exit 0 + `{"hookSpecificOutput":{"hookEventName":"PreToolUse",
+  "permissionDecision":"allow","permissionDecisionReason":"..."}}` → proceed.
+- Exit 2 + stderr `OpenAPPA hook blocked: <reason>` → block; reason goes to the
+  model. Observed for an undeclared tool (HTTP 409 upstream, stdout carries
+  `{"error": "<reason>"}`).
+- Exit 0 + `{"decision":"block","reason":"...",
+  "hookSpecificOutput":{"hookEventName":"PostToolUse","updatedToolOutput":{...}}}`
+  → PostToolUse replacement: `updatedToolOutput` is what the model must see
+  (observed: withheld-result notice replacing a mismatched result).
+- Runtime down: PreToolUse exit 2 (fail-closed, stderr names 127.0.0.1:8787);
+  Stop --turn-end exit 0 + stderr warning.
+
+## Hard constraints
+
+1. **Byte-exact echo**: PostToolUse `tool_input` must be byte-identical to the
+   PreToolUse `tool_input` (runtime digests it canonically; mismatch → result
+   withheld with `byte_mismatch`). The extension must remember the exact object
+   it sent per tool call id.
+2. **Tool naming**: the runtime sees `host/claude-code/<Name>`; policies are
+   written in Claude-Code naming. Map pi built-ins: bash→Bash,
+   powershell→PowerShell, read→Read, edit→Edit, write→Write, grep→Grep,
+   find→Glob, ls→LS. Unknown/custom tools pass through verbatim; policy authors
+   declare them under the pi name.
+3. **tool_response shape**: Claude-Code-shaped for tools where pi provides the
+   data (bash: `stdout`/`stderr`/`exitcode`/`interrupted` from details when
+   present); otherwise generic `{ "output": <joined text>, "isError": <bool> }`.
+
+## Session mapping
+
+pi `session_start.reason`: `startup|new` → `startup`; `resume|fork|reload` →
+`resume`.
+
+## Not yet observed (client parses defensively)
+
+- `permissionDecision: "deny"` exact shape (a declared-but-denied call)
+- `deliver_value` / remedy offers on PreToolUse
+- Subagent (`SubagentStop`, child trajectories) — out of v1 scope
+
+## Auto-start (verified 2026-10-06)
+
+- `appa hook --ensure-runtime --config <path>` with nothing on the default
+  port boots a runtime on `127.0.0.1:8787`; the hook exits 0.
+- `--ensure-runtime` with a custom `APPA_RUNTIME_URL` exits 2:
+  `the runtime could not be started: nothing answers <url>, and a runtime at
+  a URL the session named is the user's own to start` — custom URLs are
+  user-managed by design; nothing binds 8787 in that case.
+
+## Test seam
+
+`appa replay <dir>` checks `.appa` trace files against a policy; mock-driven unit
+tests remain our primary seam (no runtime needed).

package/extensions/index.ts

@@ -0,0 +1,183 @@
+/**
+ * pi-openappa — Pi extension wiring for OpenAPPA.
+ *
+ * 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.
+ *
+ * Wire facts and constraints: docs/wire-notes.md
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  parseCallDecision,
+  parseResultDecision,
+  postToolUsePayload,
+  preToolUsePayload,
+  promptPayload,
+  sessionStartPayload,
+  stopPayload,
+  toolResponseFrom,
+} from "../src/adapter.ts";
+import { invokeAppaHook } from "../src/hook-client.ts";
+import { captureGate, checkHealth, setAlwaysOn, type GateState } from "../src/gate.ts";
+
+interface TextPart {
+  type: "text";
+  text: string;
+}
+
+export default function (pi: ExtensionAPI): void {
+  /** Launch-fixed protection state; null until the session starts. */
+  let gate: GateState | null = null;
+  let sessionId = "";
+  /**
+   * toolCallId → the exact `input` object sent in the PreToolUse payload.
+   * PostToolUse must echo it byte-identically or the runtime withholds the
+   * result (byte_mismatch, see wire notes).
+   */
+  const pendingInputs = new Map<string, Record<string, unknown>>();
+
+  const gated = (): boolean => gate?.gated === true;
+
+  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",
+      );
+    }
+  });
+
+  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));
+  });
+
+  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 decision = parseCallDecision(outcome.exitCode, outcome.stdout, outcome.stderr);
+    if (decision.type === "deny") {
+      return { block: true, reason: `appa: ${decision.reason}` };
+    }
+    pendingInputs.set(event.toolCallId, event.input);
+    return undefined;
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (!gated()) return;
+    const sentInput = pendingInputs.get(event.toolCallId);
+    pendingInputs.delete(event.toolCallId);
+    const response = toolResponseFrom({
+      text: joinContent(event.content),
+      isError: event.isError,
+      details: event.details,
+    });
+    const payload = postToolUsePayload(
+      sessionId,
+      event.toolName,
+      sentInput ?? event.input,
+      response,
+      ctx.cwd,
+    );
+    const outcome = await invokeAppaHook(payload);
+    const decision = parseResultDecision(outcome.exitCode, outcome.stdout, outcome.stderr);
+    if (decision.type === "pass") {
+      return undefined;
+    }
+    return {
+      content: [{ type: "text", text: decision.text } satisfies TextPart],
+      isError: decision.isError,
+    };
+  });
+
+  pi.on("turn_end", async () => {
+    if (!gated()) return;
+    // Turn completion is reported, never gated (matching --turn-end).
+    await invokeAppaHook(stopPayload(sessionId), { turnEnd: true });
+  });
+
+  pi.on("session_shutdown", () => {
+    pendingInputs.clear();
+  });
+
+  pi.registerCommand("appa", {
+    description: "Show OpenAPPA status; `appa on|off` toggles always-on protection",
+    handler: async (args, ctx) => {
+      const arg = args.trim();
+      if (arg === "on" || arg === "off") {
+        setAlwaysOn(process.env, arg === "on");
+        gate = captureGate(process.env, ctx.cwd);
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            arg === "on"
+              ? "OpenAPPA always-on enabled: every future Pi session is protected."
+              : "OpenAPPA always-on disabled.",
+            "info",
+          );
+        }
+        return;
+      }
+      const state = gate ?? captureGate(process.env, ctx.cwd);
+      const mode =
+        state.source === "project"
+          ? "project (.pi/openappa)"
+          : state.source === "env"
+            ? "launch (APPA_GATE=1)"
+            : state.source === "always-on"
+              ? "always-on (/appa off to disable)"
+              : "off — /appa on enables it for every session";
+      const lines: string[] = [];
+      lines.push(state.gated ? `Protection: ON (session ${sessionId || "not started"})` : `Protection: off — ${mode}`);
+      if (state.gated) lines.push(`Mode: ${mode}`);
+      if (state.config !== undefined) lines.push(`Policy: ${state.config}`);
+      lines.push(`Runtime: ${state.runtimeUrl}`);
+      const health = await checkHealth(state.runtimeUrl);
+      lines.push(`Health: ${health.ok ? "ok" : `unreachable (${health.detail})`}`);
+      if (state.gated && !health.ok) {
+        lines.push("While the runtime is down, gated tool calls are blocked (fail-closed).");
+      }
+      const message = lines.join("\n");
+      if (ctx.hasUI) {
+        ctx.ui.notify(message, health.ok || !state.gated ? "info" : "warning");
+      }
+    },
+  });
+}
+
+function joinContent(content: ReadonlyArray<unknown>): string {
+  const parts: string[] = [];
+  for (const item of content) {
+    if (
+      typeof item === "object" &&
+      item !== null &&
+      (item as { type?: unknown }).type === "text"
+    ) {
+      parts.push(String((item as { text?: unknown }).text ?? ""));
+    } else {
+      parts.push("[non-text content omitted]");
+    }
+  }
+  return parts.join("\n");
+}

package/justfile

@@ -0,0 +1,32 @@
+# pi-openappa — a Pi extension for OpenAPPA
+# Just runs from the repo root; recipes are boring on purpose.
+
+# Run everything a change should pass (default)
+default: check
+
+# Tests + typecheck together
+check: test typecheck
+
+# Mock-driven test suite (no APPA runtime needed)
+test:
+    npm test
+
+# TypeScript check, no emit
+typecheck:
+    npm run typecheck
+
+# Install this checkout as a local Pi package (loads live from this path)
+install:
+    pi install {{justfile_directory()}}
+
+# Reconcile Pi package installations after dependency changes
+update:
+    pi update --extensions
+
+# Remove this checkout from Pi's packages
+remove:
+    pi remove {{justfile_directory()}}
+
+# Publish to npm (requires `npm login`; the Pi gallery indexes the pi-package keyword)
+publish: check
+    npm publish

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "pi-openappa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Thin OpenAPPA guard extension for Pi: gates tool calls through the APPA runtime. No policy logic lives here.",
+  "keywords": [
+    "pi-package",
+    "openappa",
+    "appa",
+    "security",
+    "guardrails",
+    "policy"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "main": "./extensions/index.ts",
+  "scripts": {
+    "test": "node --test 'test/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.0.4",
+    "typescript": "^5.9.3"
+  }
+}