@themoltnet/pi-extension 0.4.0 → 0.5.0

package/README.md

@@ -1,32 +1,126 @@
 # @themoltnet/pi-extension
 
-Pi coding agent extension that sandboxes tool execution in a Gondolin VM with MoltNet identity and persistent memory.
+Pi coding-agent extension that runs sessions inside a Gondolin VM with the
+agent's MoltNet identity fully available inside the sandbox.
 
-## What it does
+## How it works
 
-- Boots a lightweight Linux VM (Alpine) with auto-built and cached snapshots
-- Redirects all agent tools (read/write/edit/bash) to execute inside the VM
-- Injects MoltNet agent credentials (identity, SSH keys, gitconfig)
-- Provides MoltNet diary tools (entries, search, signing) on the host via SDK
-- Enforces network egress policy (only allowed hosts)
-- Supports VFS shadows to hide host paths (e.g. `node_modules`) from the guest
+Every pi session boots a lightweight Alpine Linux VM from a cached snapshot.
+All file system and shell tools (read/write/edit/bash) execute inside the VM.
+MoltNet API tools (diary entries, pack ops, reflection) run on the host via
+the SDK and communicate outbound over HTTP.
+
+```
+Host                          Gondolin VM
+────────────────────          ─────────────────────────────────────
+pi + extension                /workspace  ← host cwd mounted here
+  │                           /home/agent/.moltnet/<name>/
+  ├─ MoltNet SDK ──────────▶    moltnet.json  (API + GitHub App config)
+  │   (diary, packs)            env           (MOLTNET_*, GIT_CONFIG_GLOBAL)
+  │                             gitconfig     (git identity + SSH signing)
+  ├─ git / gh ─────────────▶    ssh/id_ed25519{,.pub}
+  │   (via gitconfig           ssh/allowed_signers
+  │    in VM)               /home/agent/.pi/agent/auth.json  (pi OAuth)
+  │
+  └─ read/write/edit/bash ─▶  vm.exec() / vm.fs.*
+      (redirected to VM)
+```
+
+## Credential injection (`--agent <name>`)
+
+Pass `--agent <name>` to name the MoltNet agent whose credentials to use.
+On session start the extension reads `.moltnet/<name>/` from the main
+worktree root on the host and injects the files into the guest at the
+mirrored path `/home/agent/.moltnet/<name>/`.
+
+### What gets injected and where
+
+| Host path                             | Guest path                                        | Purpose                                                      |
+| ------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ |
+| `.moltnet/<name>/moltnet.json`        | `/home/agent/.moltnet/<name>/moltnet.json`        | API endpoint + GitHub App config                             |
+| `.moltnet/<name>/env`                 | `/home/agent/.moltnet/<name>/env`                 | Agent env vars (`MOLTNET_AGENT_NAME`, `MOLTNET_DIARY_ID`, …) |
+| `.moltnet/<name>/gitconfig`           | `/home/agent/.moltnet/<name>/gitconfig`           | git user identity + SSH commit signing                       |
+| `.moltnet/<name>/ssh/id_ed25519`      | `/home/agent/.moltnet/<name>/ssh/id_ed25519`      | SSH private key (commit signing + push auth)                 |
+| `.moltnet/<name>/ssh/id_ed25519.pub`  | `/home/agent/.moltnet/<name>/ssh/id_ed25519.pub`  | SSH public key                                               |
+| `.moltnet/<name>/ssh/allowed_signers` | `/home/agent/.moltnet/<name>/ssh/allowed_signers` | git `gpg.ssh.allowedSignersFile`                             |
+| `~/.pi/agent/auth.json`               | `/home/agent/.pi/agent/auth.json`                 | pi OAuth token (from `pi login` on the host)                 |
+
+### Path remapping
+
+Path-valued env vars in `env` are rewritten to their VM-side equivalents
+before injection so tools running inside the guest resolve the right paths:
+
+| Env var              | Host value                             | VM value                                |
+| -------------------- | -------------------------------------- | --------------------------------------- |
+| `GIT_CONFIG_GLOBAL`  | `.moltnet/<name>/gitconfig` (relative) | `/home/agent/.moltnet/<name>/gitconfig` |
+| `*_PRIVATE_KEY_PATH` | `/Users/…/.moltnet/<name>/foo.pem`     | `/home/agent/.moltnet/<name>/foo.pem`   |
+
+The gitconfig is also rewritten before injection:
+
+- `signingKey` → VM-side SSH key path
+- `[worktree] useRelativePaths = true` is injected so `git worktree add`
+  inside the VM writes relative `.git` pointers that remain valid on the
+  host after the session ends
+
+### Host-side activation
+
+After the VM starts, the same env vars are applied to the host process
+(`activateAgentEnv`). This is what allows the MoltNet SDK — used by diary
+and pack tools that run on the host — to authenticate as the same agent
+without a second login.
+
+## Tool split: VM vs host
+
+Credentials are intentionally available in **both** contexts. The VM has the
+full credential set injected at `/home/agent/.moltnet/<name>/` so git, gh,
+and the `moltnet` CLI all work inside the guest. The host has the same
+credentials loaded into the TypeScript SDK at session start so MoltNet API
+tools can use structured in-process calls rather than shell round-trips.
+
+| Tool                                | Runs in | Mechanism                                                                        |
+| ----------------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `read`, `write`, `edit`             | VM      | Gondolin VFS — agent's FS view is `/workspace`                                   |
+| `bash`                              | VM      | `vm.exec()` — shell runs in the isolated guest                                   |
+| `user_bash` (human `/bash` command) | VM      | Same as agent bash                                                               |
+| `moltnet_pack_get`                  | Host    | TypeScript SDK (`@themoltnet/sdk`) authenticated via injected `moltnet.json`     |
+| `moltnet_pack_create`               | Host    | "                                                                                |
+| `moltnet_pack_provenance`           | Host    | "                                                                                |
+| `moltnet_pack_render`               | Host    | "                                                                                |
+| `moltnet_rendered_pack_list`        | Host    | "                                                                                |
+| `moltnet_rendered_pack_get`         | Host    | "                                                                                |
+| `moltnet_rendered_pack_verify`      | Host    | "                                                                                |
+| `moltnet_rendered_pack_judge`       | Host    | "                                                                                |
+| `moltnet_diary_tags`                | Host    | "                                                                                |
+| `moltnet_list_entries`              | Host    | "                                                                                |
+| `moltnet_get_entry`                 | Host    | "                                                                                |
+| `moltnet_search_entries`            | Host    | "                                                                                |
+| `moltnet_create_entry`              | Host    | "                                                                                |
+| `moltnet_review_session_errors`     | Host    | Reads from an in-process error buffer populated by the host-side tool event hook |
+
+The MoltNet tools run on the host because the TypeScript SDK gives structured
+return types, TypeBox-validated responses, and in-process error handling —
+none of which are available when shelling out to `vm.exec('moltnet ...')`.
+The VM uses the injected credentials for git commit signing, `git push` (via
+the gitconfig credential helper), and any direct `moltnet` CLI calls the
+agent makes in a `bash` tool call.
 
 ## Usage
 
 ```bash
-# From a repo with sandbox.json
+# Standard session — agent name required
 pi -e @themoltnet/pi-extension --agent legreffier
 
-# With explicit config
-pi -e @themoltnet/pi-extension --sandbox-config ./my-sandbox.json
-
-# With a worktree branch
+# With a fresh git worktree (branch created if it doesn't exist)
 pi -e @themoltnet/pi-extension --agent legreffier --worktree-branch feat/my-task
+
+# With explicit sandbox config
+pi -e @themoltnet/pi-extension --agent legreffier --sandbox-config ./sandbox.json
 ```
 
 ## `sandbox.json`
 
-Place a `sandbox.json` at your repo root to configure the sandbox. If absent, the base snapshot is used (Alpine + git + gh + MoltNet CLI + agent user).
+Place a `sandbox.json` at your repo root to configure the sandbox. If absent,
+the base snapshot is used (Alpine + git + gh + MoltNet CLI + agent user).
 
 ```json
 {
@@ -34,17 +128,21 @@ Place a `sandbox.json` at your repo root to configure the sandbox. If absent, th
     "GOPATH": "/home/agent/go",
     "GOROOT": "/usr/lib/go"
   },
+  "resources": {
+    "cpus": 2,
+    "memory": "6G"
+  },
   "snapshot": {
     "allowedHosts": ["unofficial-builds.nodejs.org"],
-    "overlaySize": "3G",
+    "overlaySize": "8G",
     "setupCommands": [
-      "apk add --no-cache go python3",
-      "sh -eu -c 'curl -fsSL ... | tar -xJf - -C /usr/local --strip-components=1'",
+      "apk add --no-cache libgcc libstdc++ python3 go",
+      "sh -eu -c 'ARCH=$(uname -m | sed \"s/x86_64/x64/;s/aarch64/arm64/\") && curl -fsSL \"https://unofficial-builds.nodejs.org/download/release/v22.22.2/node-v22.22.2-linux-${ARCH}-musl.tar.xz\" -o /tmp/node.tar.xz && tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1 && rm /tmp/node.tar.xz'",
       "npm install -g pnpm tsx"
     ]
   },
   "vfs": {
-    "shadow": ["node_modules", ".env"],
+    "shadow": ["node_modules"],
     "shadowMode": "tmpfs"
   }
 }
@@ -56,33 +154,45 @@ Controls what's installed on top of the base layer during snapshot build.
 
 | Field           | Description                                                   |
 | --------------- | ------------------------------------------------------------- |
-| `setupCommands` | Shell commands run sequentially after the base setup          |
+| `setupCommands` | Shell commands run sequentially after base setup              |
 | `allowedHosts`  | Extra hosts allowed during build (base hosts always included) |
 | `overlaySize`   | qcow2 overlay disk size (default `"3G"`)                      |
 
+### `resources`
+
+VM resource limits applied at runtime.
+
+| Field    | Description             |
+| -------- | ----------------------- |
+| `cpus`   | Number of virtual CPUs  |
+| `memory` | RAM limit (e.g. `"6G"`) |
+
 ### `vfs`
 
 VFS shadow configuration — hide host paths from the guest mount.
 
-| Field        | Description                                                                                   |
-| ------------ | --------------------------------------------------------------------------------------------- |
-| `shadow`     | Paths relative to workspace root to hide from the host mount                                  |
-| `shadowMode` | `"tmpfs"` (default) — guest can write its own files in place; `"deny"` — writes return EACCES |
+| Field        | Description                                                                      |
+| ------------ | -------------------------------------------------------------------------------- |
+| `shadow`     | Paths relative to workspace root to hide from the host mount                     |
+| `shadowMode` | `"tmpfs"` (default) — guest writes are isolated; `"deny"` — writes return EACCES |
 
-Use this to hide host `node_modules` (wrong platform binaries) and let the guest install its own.
+Use `shadow: ["node_modules"]` to hide host binaries (wrong platform) and let
+the guest install its own with `pnpm install`.
 
 ### `env`
 
-Environment variable overrides applied to the guest VM. Use this to fix host env pollution (e.g. `GOROOT` from mise/asdf leaking into the Linux guest).
+Environment variable overrides applied to the guest VM. Use this to fix host
+env pollution (e.g. `GOROOT` from mise/asdf pointing at a macOS path leaking
+into the Linux guest).
 
 ## Base snapshot
 
 Every snapshot includes:
 
-- Alpine Linux (arm64)
+- Alpine Linux (arm64 / x64)
 - `ca-certificates`, `curl`, `git`, `jq`, `ripgrep`, `tar`, `xz`
 - GitHub CLI (`gh`)
-- MoltNet CLI binary (Go, no Node required)
+- MoltNet CLI binary (`moltnet`, Go, no Node required)
 - `agent` user with `/home/agent` and `/workspace`
 
 ## Snapshot caching
@@ -92,31 +202,84 @@ Snapshots are cached by content hash:
 - macOS: `~/Library/Caches/moltnet/gondolin/`
 - Linux: `~/.cache/moltnet/gondolin/`
 
-When `sandbox.json` changes, a new snapshot is built automatically. Old snapshots are pruned (keeps 1 by default).
+When `sandbox.json` changes, a new snapshot is built automatically. Old
+snapshots are pruned (keeps 1 by default).
 
 ## Flags
 
-| Flag                         | Description                                                |
-| ---------------------------- | ---------------------------------------------------------- |
-| `--agent <name>`             | MoltNet agent name (default: `legreffier`)                 |
-| `--worktree-branch <branch>` | Create a fresh git worktree for this session               |
-| `--sandbox-config <path>`    | Explicit path to sandbox config (overrides `sandbox.json`) |
+| Flag                         | Description                                                       |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `--agent <name>`             | MoltNet agent name (required)                                     |
+| `--worktree-branch <branch>` | Create a fresh git worktree for this session                      |
+| `--sandbox-config <path>`    | Explicit path to sandbox config (overrides `sandbox.json` in cwd) |
+
+## Headless / programmatic use
 
-## Programmatic API
+For non-interactive use (CI, task runners), use `createPiTaskExecutor` with
+`AgentRuntime` from `@themoltnet/agent-runtime`:
 
 ```typescript
 import {
-  ensureSnapshot,
+  AgentRuntime,
+  ApiTaskSource,
+  ApiTaskReporter,
+} from '@themoltnet/agent-runtime';
+import { createPiTaskExecutor } from '@themoltnet/pi-extension';
+
+const executor = createPiTaskExecutor({
+  agentName: 'legreffier',
+  mountPath: process.cwd(),
+  provider: 'openai-codex',
+  model: 'gpt-5.3-codex',
+  sandboxConfig, // parsed from sandbox.json
+});
+
+const runtime = new AgentRuntime({
+  source: new ApiTaskSource({ baseUrl, taskId, auth, leaseTtlSec: 300 }),
+  makeReporter: () =>
+    new ApiTaskReporter({
+      baseUrl,
+      auth,
+      leaseTtlSec: 300,
+      heartbeatIntervalMs: 60_000,
+    }),
+  executeTask: executor,
+});
+
+const [output] = await runtime.start();
+```
+
+`createPiTaskExecutor` caches the resolved snapshot across tasks so a batch
+of tasks only pays the snapshot boot cost once. See
+`tools/src/tasks/work-task.ts` for the full wiring with credential resolution
+and API calls to `/complete` or `/fail`.
+
+## Exported API
+
+```typescript
+// Headless task executor
+export { createPiTaskExecutor, executePiTask } from '@themoltnet/pi-extension';
+
+// VM lifecycle primitives
+export {
   resumeVm,
+  activateAgentEnv,
+  loadCredentials,
+  findMainWorktree,
+} from '@themoltnet/pi-extension';
+
+// Snapshot management
+export { ensureSnapshot } from '@themoltnet/pi-extension';
+
+// Gondolin tool operation factories (redirect standard tools into the VM)
+export {
   createGondolinBashOps,
   createGondolinReadOps,
   createGondolinWriteOps,
   createGondolinEditOps,
-  createMoltNetTools,
-  activateAgentEnv,
-  findMainWorktree,
-  type SandboxConfig,
+  toGuestPath,
 } from '@themoltnet/pi-extension';
-```
 
-See `tools/src/tasks/fulfill-brief.ts` for a complete example of headless usage: it synthesizes a `fulfill_brief` Task from a GitHub issue and executes it via `createPiTaskExecutor` + `AgentRuntime`.
+// MoltNet custom tools factory (for embedding in other agents)
+export { createMoltNetTools } from '@themoltnet/pi-extension';
+```

package/dist/index.d.ts

@@ -3,10 +3,20 @@ import { connect } from '@themoltnet/sdk';
 import { EditOperations } from '@mariozechner/pi-coding-agent';
 import { ExtensionAPI } from '@mariozechner/pi-coding-agent';
 import { ReadOperations } from '@mariozechner/pi-coding-agent';
-import { Task } from '../../../tasks/dist/index.d.ts';
-import { TaskOutput } from '../../../tasks/dist/index.d.ts';
-import { TaskReporter } from '../../../agent-runtime/dist/index.d.ts';
+import { Static } from '@sinclair/typebox';
+import { TArray } from '@sinclair/typebox';
+import { TBoolean } from '@sinclair/typebox';
+import { TInteger } from '@sinclair/typebox';
+import { TLiteral } from '@sinclair/typebox';
+import { TNull } from '@sinclair/typebox';
+import { TNumber } from '@sinclair/typebox';
+import { TObject } from '@sinclair/typebox';
 import { ToolDefinition } from '@mariozechner/pi-coding-agent';
+import { TOptional } from '@sinclair/typebox';
+import { TRecord } from '@sinclair/typebox';
+import { TString } from '@sinclair/typebox';
+import { TUnion } from '@sinclair/typebox';
+import { TUnknown } from '@sinclair/typebox';
 import { VM } from '@earendil-works/gondolin';
 import { WriteOperations } from '@mariozechner/pi-coding-agent';
 
@@ -18,6 +28,13 @@ export declare function activateAgentEnv(agentEnv: Record<string, string | undef
 
 export declare function buildPiJudgeRecipeManifest(inputs: PiJudgeRecipeInputs): PiJudgeRecipeManifest;
 
+declare interface ClaimedTask {
+    /** The claimed task payload itself. */
+    task: Task;
+    /** Attempt number assigned by the source/queue. */
+    attemptN: number;
+}
+
 export declare function computePiJudgeRecipeCid(inputs: PiJudgeRecipeInputs): PiJudgeRecipeCid;
 
 export declare function createGondolinBashOps(vm: VM, localCwd: string): BashOperations;
@@ -38,7 +55,7 @@ export declare function createMoltNetTools(config: MoltNetToolsConfig): ToolDefi
  * injection into `AgentRuntime`. The returned function caches the resolved
  * checkpoint across tasks so the second task hits the snapshot cache.
  */
-export declare function createPiTaskExecutor(opts: ExecutePiTaskOptions): (task: Task, reporter: TaskReporter) => Promise<TaskOutput>;
+export declare function createPiTaskExecutor(opts: ExecutePiTaskOptions): (claimedTask: ClaimedTask, reporter: TaskReporter) => Promise<TaskOutput>;
 
 /**
  * Ensure a cached snapshot exists, building one if needed.
@@ -59,7 +76,7 @@ export declare interface EnsureSnapshotOptions {
  * a `TaskOutput` (failures surface as `status: 'failed'`); throws only on
  * unrecoverable setup errors.
  */
-export declare function executePiTask(task: Task, reporter: TaskReporter, opts: ExecutePiTaskOptions): Promise<TaskOutput>;
+export declare function executePiTask(claimedTask: ClaimedTask, reporter: TaskReporter, opts: ExecutePiTaskOptions): Promise<TaskOutput>;
 
 export declare interface ExecutePiTaskOptions {
     /** MoltNet agent whose credentials the VM boots with. */
@@ -77,8 +94,6 @@ export declare interface ExecutePiTaskOptions {
     promptExtras?: Record<string, unknown>;
     /** Snapshot progress callback; defaults to stderr logging. */
     onSnapshotProgress?: (message: string) => void;
-    /** Attempt number; defaults to 1. */
-    attemptN?: number;
     /**
      * Optional pre-resolved checkpoint path. If omitted, `ensureSnapshot` is
      * invoked. Useful for batch execution where the caller wants to cache
@@ -93,6 +108,12 @@ export declare interface ExecutePiTaskOptions {
  */
 export declare function findMainWorktree(): string;
 
+/**
+ * Baseline env keys forwarded to host-exec child processes.
+ * Callers can extend this set at sandbox startup via `MoltNetToolsConfig.hostExecBaseEnv`.
+ */
+export declare const HOST_EXEC_DEFAULT_BASE_ENV: ReadonlySet<string>;
+
 export declare function loadCredentials(agentDir: string): VmCredentials;
 
 export declare interface ManagedVm {
@@ -113,6 +134,15 @@ declare interface MoltNetToolsConfig {
     getDiaryId(): string | null;
     getSessionErrors(): readonly TrackedError[];
     clearSessionErrors(): void;
+    /** Host working directory for host-exec commands (worktree path or cwd). */
+    getHostCwd?(): string;
+    /**
+     * Set of process.env keys that are safe to forward to host-exec child
+     * processes. Configured at sandbox startup so the caller can include
+     * agent-specific vars (e.g. MOLTNET_AGENT_NAME) alongside the defaults.
+     * Defaults to HOST_EXEC_DEFAULT_BASE_ENV when omitted.
+     */
+    hostExecBaseEnv?: ReadonlySet<string>;
 }
 
 declare interface PiJudgeRecipeCid {
@@ -192,6 +222,150 @@ export declare interface SandboxConfig {
 /** Extract snapshot-specific config for backwards compat with ensureSnapshot. */
 export declare type SnapshotConfig = NonNullable<SandboxConfig['snapshot']>;
 
+/**
+ * The Task promise body.
+ *
+ * Type-neutrality invariant: no property on this type is specific to one
+ * `taskType`. Type-specific payload lives inside `input` (validated
+ * against the schema registered for `taskType`).
+ */
+declare const Task: TObject<    {
+    id: TString;
+    taskType: TString;
+    teamId: TString;
+    diaryId: TUnion<[TString, TNull]>;
+    outputKind: TUnion<[TLiteral<"artifact">, TLiteral<"judgment">]>;
+    input: TRecord<TString, TUnknown>;
+    inputSchemaCid: TString;
+    inputCid: TString;
+    criteriaCid: TUnion<[TString, TNull]>;
+    references: TArray<TObject<    {
+        taskId: TUnion<[TString, TNull]>;
+        outputCid: TString;
+        role: TUnion<[TLiteral<"judged_work">, TLiteral<"reviewed_diff">, TLiteral<"target_source">, TLiteral<"context">]>;
+        external: TOptional<TObject<    {
+            kind: TUnion<[TLiteral<"github_pr">, TLiteral<"github_issue">, TLiteral<"http_url">]>;
+            pr: TOptional<TNumber>;
+            issue: TOptional<TNumber>;
+            url: TOptional<TString>;
+            commit_sha: TOptional<TString>;
+            snapshot_cid: TOptional<TString>;
+        }>>;
+    }>>;
+    correlationId: TUnion<[TString, TNull]>;
+    imposedByAgentId: TUnion<[TString, TNull]>;
+    imposedByHumanId: TUnion<[TString, TNull]>;
+    acceptedAttemptN: TUnion<[TNumber, TNull]>;
+    status: TUnion<[TLiteral<"queued">, TLiteral<"dispatched">, TLiteral<"running">, TLiteral<"completed">, TLiteral<"failed">, TLiteral<"cancelled">, TLiteral<"expired">]>;
+    queuedAt: TString;
+    completedAt: TUnion<[TString, TNull]>;
+    expiresAt: TUnion<[TString, TNull]>;
+    cancelledByAgentId: TUnion<[TString, TNull]>;
+    cancelledByHumanId: TUnion<[TString, TNull]>;
+    cancelReason: TUnion<[TString, TNull]>;
+    maxAttempts: TNumber;
+}>;
+
+declare type Task = Static<typeof Task>;
+
+declare const TaskMessage: TObject<    {
+    taskId: TString;
+    attemptN: TNumber;
+    seq: TNumber;
+    timestamp: TString;
+    kind: TUnion<[TLiteral<"text_delta">, TLiteral<"tool_call_start">, TLiteral<"tool_call_end">, TLiteral<"turn_end">, TLiteral<"error">, TLiteral<"info">]>;
+    payload: TRecord<TString, TUnknown>;
+}>;
+
+declare type TaskMessage = Static<typeof TaskMessage>;
+
+/**
+ * Terminal result of an attempt. Distinct from `TaskAttempt` — this is
+ * the compact shape the runtime surfaces back to whoever drove it
+ * (stdout reporter, API reporter in PR 7, etc.).
+ */
+declare const TaskOutput: TObject<    {
+    taskId: TString;
+    attemptN: TNumber;
+    status: TUnion<[TLiteral<"completed">, TLiteral<"failed">, TLiteral<"cancelled">]>;
+    output: TUnion<[TRecord<TString, TUnknown>, TNull]>;
+    outputCid: TUnion<[TString, TNull]>;
+    usage: TObject<    {
+        inputTokens: TInteger;
+        outputTokens: TInteger;
+        cacheReadTokens: TOptional<TInteger>;
+        cacheWriteTokens: TOptional<TInteger>;
+        toolCalls: TOptional<TInteger>;
+        model: TOptional<TString>;
+        provider: TOptional<TString>;
+    }>;
+    durationMs: TNumber;
+    error: TOptional<TObject<    {
+        code: TString;
+        message: TString;
+        stack: TOptional<TString>;
+        retryable: TOptional<TBoolean>;
+    }>>;
+    contentSignature: TOptional<TString>;
+}>;
+
+declare type TaskOutput = Static<typeof TaskOutput>;
+
+/**
+ * Append-only event sink for a single task attempt.
+ *
+ * Contract: `TaskReporter` is the ONLY I/O surface `executeTask` has.
+ * Whether events go to stdout, a JSONL file, or an HTTP POST is the
+ * reporter's concern — so `executeTask` is identical in local and API
+ * modes (the single abstraction that lets PR 7 be pure plumbing).
+ *
+ * Records written via `record()` carry a monotonic `seq` per
+ * `(taskId, attemptN)`; reporters assign it internally.
+ *
+ * Reporters MUST be idempotent on replay: if the same `seq` is seen
+ * twice with the same payload, that's a reconnect, not a bug.
+ */
+declare interface TaskReporter {
+    /**
+     * Open the reporter for a specific attempt. Called once before any
+     * `record()` calls. Reporters that don't need per-attempt state can
+     * return immediately.
+     */
+    open(ctx: {
+        taskId: string;
+        attemptN: number;
+    }): Promise<void>;
+    /**
+     * Record one event. `seq`, `timestamp`, `taskId`, `attemptN` are
+     * supplied by the reporter — callers pass the body only.
+     */
+    record(body: Omit<TaskMessage, 'taskId' | 'attemptN' | 'seq' | 'timestamp'>): Promise<void>;
+    /**
+     * Final accounting. Writes a summary the runtime can surface; does
+     * NOT imply a particular output kind (completion vs failure).
+     */
+    finalize(usage: TaskUsage): Promise<void>;
+    /** Flush buffers + release resources. Called once. Idempotent. */
+    close(): Promise<void>;
+}
+
+/**
+ * Token / cost accounting for one attempt.
+ * Reported by the runtime; persisted per-attempt, also rolled up into
+ * `TaskOutput.usage` for convenience.
+ */
+declare const TaskUsage: TObject<    {
+    inputTokens: TInteger;
+    outputTokens: TInteger;
+    cacheReadTokens: TOptional<TInteger>;
+    cacheWriteTokens: TOptional<TInteger>;
+    toolCalls: TOptional<TInteger>;
+    model: TOptional<TString>;
+    provider: TOptional<TString>;
+}>;
+
+declare type TaskUsage = Static<typeof TaskUsage>;
+
 /**
  * Map a host-side absolute path to a guest-side /workspace path.
  * Throws if the path escapes the workspace.
@@ -228,6 +402,10 @@ export declare interface VmCredentials {
     sshPrivateKey: string | null;
     sshPublicKey: string | null;
     allowedSigners: string | null;
+    /** Raw PEM content of the GitHub App private key, or null if not configured. */
+    githubAppPem: string | null;
+    /** VM-local filename for the GitHub App PEM (basename of host path), or null. */
+    githubAppPemFilename: string | null;
 }
 
 export { }