anon-pi 0.1.1 → 0.3.0

package/Dockerfile.pi

@@ -1,12 +1,19 @@
 # A minimal image with `pi` (the Earendil Works coding agent) on PATH, for use as
-# anon-pi's ANON_PI_IMAGE. It follows the official upstream containerization
-# pattern (earendil-works/pi, packages/coding-agent/docs/containerization.md):
-# node:24-bookworm-slim + the official `@earendil-works/pi-coding-agent` npm
-# package, plus the handful of tools pi's built-in bash/grep/find expect.
+# anon-pi's ANON_PI_IMAGE. node:24-bookworm-slim + the official
+# `@earendil-works/pi-coding-agent` npm package + the tools pi's built-in
+# bash/grep/find expect.
 #
-# Note: unlike the upstream `Dockerfile.pi`, this image sets NO ENTRYPOINT and
-# NO config volume. anon-pi passes `pi` as the run command and mounts pi's config
-# itself (PI_CODING_AGENT_DIR), so the image just needs `pi` reachable on PATH.
+# HOW anon-pi USES THIS IMAGE (stateful model):
+#   anon-pi mounts a PERSISTENT per-workdir host dir at the container's
+#   ~/.pi/agent, so pi's sessions/history/settings and any extensions you
+#   `pi install` persist across launches. On a FRESH home, anon-pi seeds it once
+#   from this image's STAGING dir (/opt/anon-pi-seed/agent) + your imported
+#   models.json, then stamps a marker and never overwrites again.
+#
+#   So image defaults (extensions, trust.json) go in the STAGING dir, NOT in
+#   ~/.pi/agent (which is the mount and would be shadowed). Set
+#   PI_CODING_AGENT_DIR to the staging dir while running `pi install` so the
+#   extension is recorded there.
 #
 # Build (pin a digest for reproducibility once pushed to a registry):
 #   podman build -t localhost/anon-pi-pi:latest -f Dockerfile.pi .
@@ -20,4 +27,25 @@ RUN apt-get update \
 # The official pi coding agent CLI (puts `pi` on PATH).
 RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
 
+# The staging dir anon-pi promotes into a fresh home on first launch.
+ENV ANON_PI_STAGE=/opt/anon-pi-seed/agent
+RUN mkdir -p "$ANON_PI_STAGE"
+
+# Trust /work so pi does not prompt on the mounted project (staged, so it lands
+# in the persistent home on first launch; anon-pi never writes this for you).
+RUN printf '{"/work": true}\n' > "$ANON_PI_STAGE/trust.json"
+
+# --- Optional: extensions + skills (the capability layer) -------------------
+# Install into the STAGING dir (PI_CODING_AGENT_DIR), so `pi install` records the
+# extension there and anon-pi promotes it into the persistent home on first
+# launch. After that you can `pi install` more from inside the session and it
+# persists. Uncomment what you want in the anon persona:
+#
+#   RUN PI_CODING_AGENT_DIR="$ANON_PI_STAGE" pi install npm:pi-subagents
+#   RUN PI_CODING_AGENT_DIR="$ANON_PI_STAGE" pi install npm:pi-plan-mode
+#
+# An extension that needs a running SERVICE (e.g. pi-webveil + a local SearXNG)
+# installs and configures that service in the image too. See the worked example
+# examples/Dockerfile.pi-webveil.
+
 WORKDIR /work

package/README.md

@@ -33,7 +33,8 @@ export ANON_PI_IMAGE=your/pi-image:tag
 export ANON_PI_LLM=192.168.1.150:8080     # your local model, reached directly
 export ANON_PI_PROXY=socks5h://127.0.0.1:9050
 
-anon-pi ./recon
+anon-pi import       # one-time: generate the seed models.json from your model
+anon-pi ./recon      # launch
 ```
 
 You land in pi, inside the jail, cwd `/work` = `./recon`. pi's web/tool egress is anonymized through the proxy; the local model at `ANON_PI_LLM` is reachable directly; everything else is dropped if the proxy is down (fail-closed).
@@ -42,24 +43,39 @@ You land in pi, inside the jail, cwd `/work` = `./recon`. pi's web/tool egress i
 
 | Var | Required | Default | Meaning |
 | --- | --- | --- | --- |
-| `ANON_PI_IMAGE` | yes | | container image with `pi` on `PATH` |
+| `ANON_PI_IMAGE` | for run | | container image with `pi` on `PATH` |
 | `ANON_PI_LLM` | yes | | RFC1918/link-local `IP[:port]` of the local model (the one direct hole) |
-| `ANON_PI_PROXY` | no | `socks5h://127.0.0.1:9050` | the socks5h proxy |
+| `ANON_PI_PROXY` | yes | | the socks5h proxy (Tor/wireproxy/ssh -D). No default: it is what anonymizes |
+| `ANON_PI_EPHEMERAL` | no | (off) | set to `1` for a throwaway, non-persistent session |
 | `ANON_PI_HOME` | no | `$XDG_CONFIG_HOME/anon-pi` or `~/.config/anon-pi` | anon-pi home |
-| `ANON_PI_CONFIG` | no | `<ANON_PI_HOME>/agent` | the canonical seed dir |
-| `ANON_PI_AGENT_MOUNT` | no | `/opt/pi-agent` | absolute container path pi's config is mounted at (see below) |
+| `ANON_PI_CONFIG` | no | `<ANON_PI_HOME>/agent` | canonical seed dir (holds the imported `models.json`) |
+| `ANON_PI_SOURCE_MODELS` | no | `~/.pi/agent/models.json` | (`import`) the host `models.json` to read from |
 
 ## How it works
 
-1. **Seed (once per workdir).** The first time you use a workdir, anon-pi copies your canonical config (`~/.config/anon-pi/agent`) into a per-session dir `~/.config/anon-pi/sessions/<hash-of-workdir>/agent`. The canonical config is only ever READ; it is never mounted into the container, so pi in the jail cannot mutate it.
-2. **Mount.** The session config dir is mounted as pi's global config (`PI_CODING_AGENT_DIR=<mount>`, default `/opt/pi-agent`), and the workdir is mounted at `/work`.
-3. **Run.** anon-pi execs `netcage run --proxy <proxy> --allow-direct <ANON_PI_LLM> -it -v <workdir> -v <session>:<mount> -e PI_CODING_AGENT_DIR=<mount> <image> pi`.
+**Stateful by default.** anon-pi mounts a persistent per-workdir host dir at the container's `~/.pi/agent`, so pi's **sessions, history, settings (your model choice), and any extensions you `pi install`** all persist across launches. Re-running in the same folder resumes it. The state dir is `<ANON_PI_HOME>/state/<workdir>/agent`, named with pi's own readable path convention (e.g. `--home-me-proj--`), not a hash, so you can see which folder it belongs to and delete it to reset.
 
-### Where pi's config is mounted (`ANON_PI_AGENT_MOUNT`)
+1. **Mount the persistent home.** `-v <ANON_PI_HOME>/state/<workdir>/agent:/root/.pi/agent`. Everything pi writes there survives.
+2. **First-launch seed (only when the home is fresh).** anon-pi mounts the image's staged defaults and your imported `models.json`, and the container promotes them into the fresh home, then stamps a `.anon-pi-seed` marker. On later launches the marker is present, so nothing is re-copied and **your changes (added models, installed extensions) are never clobbered**.
+3. **Run.** `netcage run --proxy <proxy> --allow-direct <ANON_PI_LLM> -it -v <workdir> -v <state>:/root/.pi/agent [-v <models.json>:...:ro] <image> sh -c '<seed-if-fresh> && exec pi'`.
 
-By default anon-pi mounts the seeded config at `/opt/pi-agent` and points pi there with `PI_CODING_AGENT_DIR`. This absolute, image-independent path is chosen so the podman mount target and pi's config dir agree without anon-pi having to guess your image's home directory.
+pi auto-selects the first available model (your local one; it needs no real API key), so no default needs to be set. Services and default extensions live in the **image**; your state lives in the persistent home.
 
-If you would rather pi's config live at its **standard** `~/.pi/agent` inside the container, set `ANON_PI_AGENT_MOUNT` to that home's **absolute** path, e.g. `ANON_PI_AGENT_MOUNT=/root/.pi/agent` for an image that runs as `root` (or `/home/<user>/.pi/agent` otherwise). The value must be absolute: podman does not expand `~`, and anon-pi rejects a `~`-relative or relative value rather than mounting it at a literal `~` directory. Both the mount target and `PI_CODING_AGENT_DIR` always stay in lockstep.
+### Ephemeral (throwaway) sessions
+
+For a clean, no-local-trace session, pass `--ephemeral` (or `ANON_PI_EPHEMERAL=1`): anon-pi mounts **no writable state** at all. pi writes to the container's own filesystem, which netcage runs with `--rm`, so it is destroyed when the container exits. Nothing writable ever touches a host path (only the read-only `models.json` seed is mounted), there is no cleanup step, and nothing is left behind even if anon-pi is killed.
+
+```sh
+anon-pi --ephemeral ./scratch
+```
+
+### Reset a session
+
+Delete its state home; the next launch re-seeds:
+
+```sh
+rm -rf ~/.config/anon-pi/state/<workdir-slug>/agent
+```
 
 ## Providing a pi image
 
@@ -73,33 +89,59 @@ podman build -t localhost/anon-pi-pi:latest -f Dockerfile.pi .
 export ANON_PI_IMAGE=localhost/anon-pi-pi:latest
 ```
 
-The image only needs `pi` reachable on `PATH`. anon-pi passes `pi` as the run command and mounts pi's config itself, so the image needs **no `ENTRYPOINT` and no config volume** (unlike pi's upstream `Dockerfile.pi`, which is written for running pi directly).
+The image only needs `pi` reachable on `PATH`. anon-pi passes `pi` as the run command (via a small copy-then-exec step) and never mounts over pi's config dir, so the image needs **no `ENTRYPOINT` and no config volume** (unlike pi's upstream `Dockerfile.pi`, which is written for running pi directly).
 
 A community image also exists ([`gni/pi-coding-agent-container`](https://github.com/gni/pi-coding-agent-container)); it is third-party and unvetted, so review it yourself before trusting it with your (anonymized) credentials.
 
-## Populating the seed
+### Extensions, skills, and their services go in the image
 
-anon-pi **never** populates the canonical config for you (it will not silently copy your real identity into the anon config). Create it yourself:
+anon-pi deliberately imports **only your local model** (see below), never your extensions or skills. That is on purpose: your extension set is an identity fingerprint, extensions run code and can leak, and many need a runtime that a copied folder cannot carry (for example `pi-webveil` needs a running searxng). The right home for capabilities is the **image**, where they are installed once, reviewably, with clean config:
 
-```sh
-mkdir -p ~/.config/anon-pi/agent
-cp -a ~/.pi/agent/. ~/.config/anon-pi/agent/
-# then remove anything you do NOT want in the anonymized identity
+```dockerfile
+FROM node:24-bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      bash ca-certificates git ripgrep && rm -rf /var/lib/apt/lists/*
+RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+
+# Extensions are installed with `pi install` (which records them in settings),
+# NOT a global npm install:
+# RUN pi install npm:pi-webveil
+# ...and an extension that needs a service (pi-webveil -> searxng) also installs
+# and configures that service in the image. Its egress is forced through the
+# socks proxy by netcage at runtime, so it must be happy with proxy-only,
+# DNS-through-proxy networking.
+
+WORKDIR /work
 ```
 
-Put the pi config you want anon sessions to use here: anonymously-created accounts / API keys, the models and skills you want, and a **`trust.json` that trusts `/work`** so pi does not prompt about the (mounted) project on every run. anon-pi does not synthesize pi's `trust.json`; getting a valid one into the seed is your responsibility (copy it from a pi setup where `/work` is trusted, or approve once inside a session and it persists in the session dir).
+Install image defaults into the **staging dir** (`PI_CODING_AGENT_DIR=/opt/anon-pi-seed/agent pi install ...`), NOT `~/.pi/agent`: anon-pi mounts a persistent home over `~/.pi/agent`, and promotes the staging dir into it on a fresh launch. Anything you then `pi install` *inside* a session also persists (it is written to the mounted home). See the `Dockerfile.pi` comments for the exact `pi install` form.
 
-## Reseed
+A worked example ships in this package: [`examples/Dockerfile.pi-webveil`](examples/Dockerfile.pi-webveil) builds pi + the `pi-webveil` extension (staged) + a local SearXNG (over a Unix socket, `http-socket` so webveil's `unix:` baseUrl can speak HTTP to it, JSON API on, limiter off), started by an entrypoint that then execs anon-pi's seed-then-pi command. Note the anonymity subtlety it documents: SearXNG's own crawl is anonymized here **because netcage forces every process's egress through the proxy**, so webveil's plain `egress: direct` is correct in-jail (the usual "local SearXNG leaks your IP" caveat does not apply).
 
-Reseed is a manual step: delete the session dir and the next run re-seeds it.
+## Generating the seed (`anon-pi import`)
+
+anon-pi **never** copies your real pi config. Instead, `anon-pi import` synthesizes a minimal `models.json` from your local model:
 
 ```sh
-rm -rf ~/.config/anon-pi/sessions/<hash>/agent
+export ANON_PI_LLM=192.168.1.150:8080
+anon-pi import
 ```
 
+It reads your host `~/.pi/agent/models.json` (override with `ANON_PI_SOURCE_MODELS`), finds the provider whose `baseUrl` serves `ANON_PI_LLM` (matched on host:port, so `192.168.1.150:8080` matches `http://192.168.1.150:8080/v1`), and writes **just that provider** to `<ANON_PI_CONFIG>/models.json`. Everything else, your paid providers and their API keys, your sessions, your trust list, is left behind on the host.
+
+That file **seeds a fresh session home** (it is copied in on first launch). Models you later add *inside* pi persist in the session home and are never clobbered by import. To change what a fresh home seeds, re-run `anon-pi import --force`; to apply it to an existing session, reset that session (delete its state home).
+
+- If no provider matches `ANON_PI_LLM`, it errors and lists the providers it did find.
+- If the matched provider carries a real-looking `apiKey` (not `none`/`ollama`/empty), it warns but proceeds (for a local model this is usually fine).
+- It refuses to overwrite the canonical seed unless you pass `--force`.
+
+## Trusting `/work`
+
+pi treats a mounted project as untrusted until approved. The shipped Dockerfiles stage a `trust.json` trusting `/work` (in `/opt/anon-pi-seed/agent`), which is promoted into the session home on first launch, so you are not prompted. You can also approve once inside a session; it persists.
+
 ## Overriding the config per workdir
 
-The seeded config is pi's **global** in the container. pi also supports a **project-local** config at `<cwd>/.pi/`, which layers on top of the global. Since your workdir is pi's cwd (`/work`), you can drop a `/work/.pi/` (i.e. `<workdir>/.pi/`) into the folder to override the global for that folder only. anon-pi does nothing special for this; it is pi's normal project-over-global layering. (Make sure your seed's `trust.json` trusts `/work` so the override is honored without a prompt.)
+pi also supports a **project-local** config at `<cwd>/.pi/`, which layers on top of the image's global config. Since your workdir is pi's cwd (`/work`), you can drop a `/work/.pi/` (i.e. `<workdir>/.pi/`) into the folder to override settings for that folder only. anon-pi does nothing special for this; it is pi's normal project-over-global layering.
 
 ## Platform
 

package/dist/anon-pi.d.ts

@@ -1,20 +1,48 @@
 /** The container path the workdir is mounted at (pi's cwd). */
 export declare const CONTAINER_WORKDIR = "/work";
 /**
- * The DEFAULT container path the seeded pi config is mounted at (the pi global).
- * Absolute and image-independent: both podman (the -v target) and pi (the
- * PI_CODING_AGENT_DIR env) agree on it with no home-resolution guessing. A user
- * who knows their image's home can override it (ANON_PI_AGENT_MOUNT) to the
- * standard `~/.pi/agent` location, e.g. /root/.pi/agent for a root image.
+ * The container path pi uses as its config+state home. anon-pi mounts a
+ * PERSISTENT host dir here (Model B), so everything pi writes, sessions,
+ * history, settings (your model choice), `pi install`ed extensions, downloaded
+ * bin/fd, survives across launches. Statefulness is the default; --ephemeral
+ * mounts a throwaway dir here instead.
  */
-export declare const DEFAULT_CONTAINER_AGENT_DIR = "/opt/pi-agent";
-/** The pi env var that overrides its config dir (see pi config.ts getAgentDir). */
-export declare const PI_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+export declare const CONTAINER_AGENT_DIR = "/root/.pi/agent";
+/**
+ * Where the image STAGES its first-launch defaults (extensions + trust.json).
+ * NOT the agent dir, so it never conflicts with the persistent mount. The
+ * entrypoint promotes these into the mounted agent dir only when the home is
+ * FRESH (Model C seed-if-fresh).
+ */
+export declare const CONTAINER_STAGE_DIR = "/opt/anon-pi-seed/agent";
+/**
+ * Where anon-pi mounts the canonical models.json (from `import`) read-only, so
+ * the first-launch seed can copy it into the fresh home alongside the image's
+ * staged defaults. Read-only: the container never writes back to the host seed.
+ */
+export declare const CONTAINER_MODELS_SEED = "/anon-pi-seed/models.json";
+/** Marker file written into the agent dir after seeding; holds the seed version. */
+export declare const SEED_MARKER = ".anon-pi-seed";
+/** The single file the host-side seed carries: pi's model/provider registry. */
+export declare const MODELS_FILE = "models.json";
+/**
+ * containerRunCmd builds the container command: on a FRESH home (no seed
+ * marker), promote the image's staged defaults + the mounted models.json into
+ * the persistent agent dir and stamp the marker; then exec pi. On a seeded home
+ * it does nothing but exec pi, so pi's persisted state (incl. anything you
+ * `pi install`ed or models pi added) is used as-is and NEVER clobbered.
+ *
+ * seedVersion is written into the marker so a future image can re-seed changed
+ * defaults on a version bump; v1 only seeds when the marker is absent.
+ */
+export declare function containerRunCmd(seedVersion: string): string;
+/** The seed version anon-pi stamps when it seeds a fresh home (bump to re-seed). */
+export declare const SEED_VERSION = "1";
 /** Inputs resolved from the environment + argv, injected so this stays pure. */
 export interface AnonPiEnv {
     /** $HOME (or an override) used to derive default paths. */
     home: string;
-    /** socks5h proxy URL. Default socks5h://127.0.0.1:9050. */
+    /** socks5h proxy URL. REQUIRED (no default: the proxy is what anonymizes). */
     proxy?: string;
     /** The anon-pi home dir. Default $XDG_CONFIG_HOME/anon-pi or ~/.config/anon-pi. */
     anonPiHome?: string;
@@ -27,63 +55,148 @@ export interface AnonPiEnv {
     /** XDG_CONFIG_HOME, if set (used to derive the default anon-pi home). */
     xdgConfigHome?: string;
     /**
-     * The ABSOLUTE container path to mount the seeded config at (and point pi's
-     * PI_CODING_AGENT_DIR at). Default /opt/pi-agent. Set it to your image's real
-     * `~/.pi/agent` (e.g. /root/.pi/agent) if you want the standard location.
-     * MUST be absolute: podman does not expand `~`, so a `~`-relative value would
-     * be mounted literally. Rejected if it starts with `~` or is not absolute.
+     * Absolute path to the Dockerfile.pi that ships with anon-pi, used only to
+     * make the missing-image error's build command concrete. cli.ts resolves it
+     * from import.meta.url; when absent the message falls back to a bare
+     * `Dockerfile.pi`.
+     */
+    dockerfilePath?: string;
+    /**
+     * Absolute path to the shipped examples/Dockerfile.pi-webveil (pi + pi-webveil
+     * + SearXNG), used to make the missing-image error mention the fuller build.
      */
-    agentMount?: string;
+    webveilDockerfilePath?: string;
+    /** `import` source models.json override (ANON_PI_SOURCE_MODELS). */
+    sourceModels?: string;
+    /** The host pi agent dir override (PI_CODING_AGENT_DIR), used to find models.json. */
+    piAgentDir?: string;
+    /** When true, use a throwaway state home (no persistence). Default false. */
+    ephemeral?: boolean;
+    /** The seed version anon-pi stamps into a fresh home. Default SEED_VERSION. */
+    seedVersion?: string;
 }
 /** The fully-resolved run plan cli.ts executes. */
 export interface RunPlan {
     /** Absolute workdir on the host (mounted at /work). */
     workdir: string;
-    /** The per-session seeded config dir on the host (mounted as the pi global). */
-    sessionAgentDir: string;
-    /** The canonical seed dir to copy FROM (read-only by convention). */
+    /**
+     * The PERSISTENT per-workdir state dir on the host, mounted at the container's
+     * ~/.pi/agent. Everything pi writes here survives. For --ephemeral this is a
+     * throwaway path cli.ts creates + discards.
+     */
+    stateDir: string;
+    /** The canonical host models.json (from `import`) mounted read-only for the seed, or '' if absent. */
     configSeed: string;
-    /** The absolute container path the session config is mounted at (== pi's config dir). */
-    agentMount: string;
-    /** True iff the session dir does not exist yet and must be seeded from configSeed. */
-    needsSeed: boolean;
+    /** True when this workdir has no state yet (fresh home; the seed will run). */
+    fresh: boolean;
     /** The argv passed to `netcage` (after the `netcage` program name). */
     netcageArgs: string[];
 }
 /** A user-facing error whose message is meant to be printed verbatim (no stack). */
 export declare class AnonPiError extends Error {
 }
+/** Resolve the anon-pi home dir (holds the seed). */
+export declare function resolveAnonPiHome(env: AnonPiEnv): string;
 /**
- * Resolve the container agent-mount path: ANON_PI_AGENT_MOUNT or the default.
- * It MUST be an absolute container path, because it is BOTH the podman `-v`
- * target AND pi's PI_CODING_AGENT_DIR, and podman (unlike pi) does not expand
- * `~`. A `~`-relative or relative value is rejected loudly rather than silently
- * mounted at a literal `~` directory or a cwd-relative path.
+ * The CANONICAL host seed dir holding models.json (written by `anon-pi import`).
+ * Mounted read-only so the first-launch seed can copy models.json into a fresh
+ * persistent home. Workdir-independent (import does not need a workdir).
  */
-export declare function resolveAgentMount(env: AnonPiEnv): string;
-/** Resolve the anon-pi home dir (holds the canonical seed + per-session state). */
-export declare function resolveAnonPiHome(env: AnonPiEnv): string;
-/** The canonical seed dir (copied FROM, never mounted). */
 export declare function resolveConfigSeed(env: AnonPiEnv): string;
 /**
- * Session id = a stable short hash of the ABSOLUTE workdir path, so re-running
- * anon-pi on the same folder resumes the same session config+state, and moving
- * the folder starts a new session (documented, accepted).
+ * Encode an absolute path into a directory name using pi's OWN convention (see
+ * pi coding-agent session-manager: `--${cwd without leading slash, / \ : -> -}--`),
+ * so an anon-pi state dir is readable and matches pi's mental model (no opaque
+ * hash). e.g. /home/u/dev/x -> --home-u-dev-x--
  */
-export declare function sessionId(absWorkdir: string): string;
-/** The per-session seeded config dir on the host for a given workdir. */
-export declare function sessionAgentDir(env: AnonPiEnv, absWorkdir: string): string;
+export declare function pathSlug(absPath: string): string;
+/**
+ * The persistent per-workdir state dir on the host (mounted at the container's
+ * ~/.pi/agent). Keyed by the workdir via pi's path-slug convention:
+ *   <anonPiHome>/state/<slug>/agent
+ */
+export declare function stateAgentDir(env: AnonPiEnv, absWorkdir: string): string;
+/**
+ * Normalise a proxy-less host:port key from an ANON_PI_LLM value or a provider
+ * baseUrl, so `192.168.1.150:8080` matches `http://192.168.1.150:8080/v1`.
+ * Returns `host` (no port) or `host:port`, lowercased, scheme/path stripped.
+ */
+export declare function hostPortKey(value: string): string;
+/**
+ * A pi provider entry (as it appears under models.json `providers[name]`). Only
+ * the fields anon-pi reads are typed; the rest is preserved verbatim.
+ */
+export interface PiProvider {
+    baseUrl?: string;
+    apiKey?: string;
+    api?: string;
+    models?: unknown[];
+    [k: string]: unknown;
+}
+/** Parsed shape of a pi models.json (only `providers` is required). */
+export interface PiModelsFile {
+    providers?: Record<string, PiProvider>;
+    [k: string]: unknown;
+}
+/** The result of picking the ANON_PI_LLM provider out of a host models.json. */
+export interface ImportResult {
+    /** The provider key (e.g. "llamacpp-router"). */
+    name: string;
+    /** The barebones models.json to write (just the matched provider). */
+    models: PiModelsFile;
+    /** True if the matched provider's apiKey looks like a REAL secret (warn). */
+    apiKeyLooksReal: boolean;
+}
+/**
+ * PURE: given a parsed host models.json and the ANON_PI_LLM value, select the
+ * provider whose baseUrl points at that host:port and return a barebones
+ * models.json carrying ONLY that provider (verbatim, with its models). Throws
+ * AnonPiError if nothing matches. Carries no other provider (so etherplay /
+ * google / paid API keys never enter the seed).
+ */
+export declare function pickProviderForLlm(hostModels: PiModelsFile, llmDirect: string): ImportResult;
+/**
+ * The default host models.json path `import` reads FROM. Overridable via
+ * ANON_PI_SOURCE_MODELS; defaults to the real pi config (~/.pi/agent/models.json
+ * under the container-less host HOME, or PI_CODING_AGENT_DIR if the user set it).
+ */
+export declare function resolveSourceModelsPath(env: AnonPiEnv): string;
 /**
  * Build the run plan from the environment + the (optional) workdir arg. PURE: it
- * resolves paths and composes the netcage argv, and reports whether a seed copy
- * is needed, but performs NO filesystem writes or spawns. It THROWS AnonPiError
- * for the two hard preconditions (missing image, missing llm) so the required
- * inputs fail loud; the missing-SEED check is left to cli.ts (it needs a real
- * `existsSync`), but `needsSeed` is derived from the injected `seedExists`.
+ * resolves paths and composes the netcage argv, performing NO filesystem writes
+ * or spawns. It THROWS AnonPiError for the required inputs (image, llm, proxy).
+ *
+ * Statefulness (Model B): a persistent per-workdir host dir is mounted at the
+ * container's ~/.pi/agent, so pi's sessions/history/settings/extensions persist.
+ * First-launch seed (Model C): when that home is FRESH, the container run
+ * command promotes the image's staged defaults + the imported models.json into
+ * it and stamps a marker; thereafter pi OWNS the home and nothing is clobbered.
+ *
+ * `modelsSeedExists` reports whether the canonical import models.json exists (so
+ * it is mounted for the seed); `stateExists` reports whether this workdir's
+ * state home already exists (so `fresh` is known).
+ *
+ * --ephemeral mounts NO writable state: pi writes to the container's own
+ * filesystem, which netcage runs with `--rm`, so it is destroyed when the
+ * container exits. Nothing writable ever touches a host path; there is no
+ * cleanup and no leftover-on-crash. (The read-only models.json seed is still
+ * mounted; it is a single file anon-pi never writes to.)
+ */
+export declare function buildRunPlan(env: AnonPiEnv, workdirArg: string | undefined, modelsSeedExists: (modelsJsonPath: string) => boolean, stateExists: (stateDir: string) => boolean): RunPlan;
+/**
+ * Absolute path to the Dockerfile.pi that ships with anon-pi, resolved from this
+ * module's location (package root, one level up from dist/anon-pi.js), or
+ * undefined if it cannot be found. Used only to make the missing-image error's
+ * build command concrete.
+ */
+export declare function shippedDockerfilePath(): string | undefined;
+/**
+ * Absolute path to the fuller pi-webveil + SearXNG example that ships with
+ * anon-pi (examples/Dockerfile.pi-webveil), or undefined if not found.
  */
-export declare function buildRunPlan(env: AnonPiEnv, workdirArg: string | undefined, seedExists: (dir: string) => boolean, sessionExists: (dir: string) => boolean): RunPlan;
+export declare function shippedWebveilDockerfilePath(): string | undefined;
 /** Read the AnonPiEnv from a process env map (kept separate so tests inject one). */
 export declare function envFromProcess(penv: Record<string, string | undefined>): AnonPiEnv;
 /** The --help text (kept here so it is covered by the same module). */
-export declare const HELP = "anon-pi - launch pi inside a netcage (anonymized egress + one direct local model)\n\nUSAGE\n  anon-pi [WORKDIR]\n\n  WORKDIR   the host folder pi works in (mounted at /work). Defaults to the\n            current directory. The session config+state is keyed to this folder.\n\nWHAT IT DOES\n  Seeds a per-workdir writable copy of your canonical anon-pi config into\n  ~/.config/anon-pi/sessions/<hash>/agent, mounts it as pi's global config\n  (PI_CODING_AGENT_DIR=<mount>, default /opt/pi-agent), mounts WORKDIR at\n  /work, opens ONE direct hole to your local model, and runs pi with all other\n  egress forced through the socks5h proxy, fail-closed. Requires `netcage`.\n\nENVIRONMENT\n  ANON_PI_IMAGE   (required) image with `pi` on PATH. No image yet? Running\n                  anon-pi without it prints a ready-to-build Dockerfile.pi\n                  recipe; see the README (Providing a pi image).\n  ANON_PI_LLM     (required) RFC1918/link-local IP[:port] of the local model\n  ANON_PI_PROXY   socks5h URL (default socks5h://127.0.0.1:9050)\n  ANON_PI_HOME    anon-pi home (default $XDG_CONFIG_HOME/anon-pi or ~/.config/anon-pi)\n  ANON_PI_CONFIG  canonical seed dir (default <ANON_PI_HOME>/agent)\n  ANON_PI_AGENT_MOUNT  absolute container path for pi's config (default\n                  /opt/pi-agent; set to your image's ~/.pi/agent, e.g. /root/.pi/agent)\n\nRESEED\n  Reseed is manual: delete the session dir, e.g.\n    rm -rf ~/.config/anon-pi/sessions/<hash>/agent\n  and the next run re-seeds it from the canonical config.\n\nPLATFORM\n  Linux only (via netcage's netns/nft jail). On macOS/Windows it works only\n  inside a Linux VM, where --allow-direct to a LAN model is VM-boundary-sensitive.\n";
+export declare const HELP = "anon-pi - launch pi inside a netcage (anonymized egress + one direct local model)\n\nUSAGE\n  anon-pi [WORKDIR]     launch pi jailed, working in WORKDIR (default: cwd)\n  anon-pi import        seed models.json from your local model\n\n  WORKDIR   the host folder pi works in (mounted at /work; pi's cwd). Files pi\n            writes there land on the host.\n\nWHAT IT DOES\n  Runs pi inside netcage with all web/DNS egress forced through the socks5h\n  proxy (fail-closed) and ONE direct hole to your local model (ANON_PI_LLM).\n\n  STATEFUL by default: a persistent per-workdir home\n  (<ANON_PI_HOME>/state/<workdir>/agent) is mounted at the container's\n  ~/.pi/agent, so your conversations, history, settings (model choice), and any\n  extensions you `pi install` persist across launches. Re-running in the same\n  folder resumes it. On a FRESH home, the image's staged defaults (extensions,\n  trust) and your imported models.json are seeded in once; after that pi owns the\n  home and nothing is overwritten. Requires `netcage`.\n\n  --ephemeral (or ANON_PI_EPHEMERAL=1): mount NO writable state; pi writes to the\n  container's own --rm layer, gone on exit. Nothing writable touches the host,\n  no cleanup, no leftover-on-crash.\n\nimport\n  Reads your host ~/.pi/agent/models.json, picks the provider whose baseUrl\n  serves ANON_PI_LLM, and writes JUST that provider to the canonical seed\n  (<ANON_PI_CONFIG>/models.json). No other provider's API keys, no sessions, no\n  identity. It SEEDS a fresh home; models you later add inside pi persist and are\n  never clobbered. Re-run with --force to overwrite the canonical seed.\n\nENVIRONMENT\n  ANON_PI_IMAGE   (required for run) image with `pi` on PATH. No image yet?\n                  Running anon-pi without it prints a ready-to-build\n                  Dockerfile.pi recipe; see the README (Providing a pi image).\n  ANON_PI_LLM     (required) RFC1918/link-local IP[:port] of the local model\n  ANON_PI_PROXY   (required) socks5h URL of your proxy (Tor/wireproxy/ssh -D).\n                  No default: the proxy is what anonymizes, so it is never guessed.\n  ANON_PI_EPHEMERAL  set to 1 for a throwaway (non-persistent) session\n  ANON_PI_HOME    anon-pi home (default $XDG_CONFIG_HOME/anon-pi or ~/.config/anon-pi)\n  ANON_PI_CONFIG  canonical seed dir holding models.json (default <ANON_PI_HOME>/agent)\n  ANON_PI_SOURCE_MODELS  (import) host models.json to read (default ~/.pi/agent/models.json)\n\nRESET A SESSION\n  Delete its state home to start fresh (re-seeds next launch):\n    rm -rf <ANON_PI_HOME>/state/<workdir-slug>/agent\n\nPLATFORM\n  Linux only (via netcage's netns/nft jail). On macOS/Windows it works only\n  inside a Linux VM, where --allow-direct to a LAN model is VM-boundary-sensitive.\n";
 //# sourceMappingURL=anon-pi.d.ts.map

package/dist/anon-pi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anon-pi.d.ts","sourceRoot":"","sources":["../src/anon-pi.ts"],"names":[],"mappings":"AAwBA,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,kBAAkB,CAAC;AAE3D,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACzB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,OAAO;IACvB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,SAAS,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAID,oFAAoF;AACpF,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAiBxD;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAOxD;AAED,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAO1E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,SAAS,EACd,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,EACpC,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GACrC,OAAO,CAiFT;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,SAAS,CAWX;AAED,uEAAuE;AACvE,eAAO,MAAM,IAAI,urDAkChB,CAAC"}
+{"version":3,"file":"anon-pi.d.ts","sourceRoot":"","sources":["../src/anon-pi.ts"],"names":[],"mappings":"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"}