@edgehero/pi-dispatch 2.1.0 → 3.0.0

package/.env.example

@@ -35,6 +35,13 @@ ANTHROPIC_API_KEY=
 PI_PROVIDER=anthropic
 # A DATED model id is deterministic; a floating alias (e.g. claude-sonnet-4-5) can change cost.
 PI_MODEL=claude-sonnet-4-5-20250929
+# optional: the only models a job may call, comma-separated provider/model (at most 16). A trigger's own
+# run.models replaces this list for its jobs. The default model must be on it, or every job that uses the
+# default is refused before it spends. Env only: the settings overlay cannot set or widen it.
+# Unset = any model. Needs a job image that declares the modelPolicy capability.
+# No spaces, not even after a comma: a shell that sources this file cuts the value at the first space
+# and leaves it unset, so jobs would run with no list (the worker refuses a spaced value at boot).
+# PI_ALLOWED_MODELS=anthropic/claude-sonnet-4-5-20250929,anthropic/claude-haiku-4-5-20251001
 
 # --- Spend + concurrency guards (money bounds; all have conservative defaults) ---
 # per-job turn cap -- pi has none of its own, so the harness imposes one
@@ -55,6 +62,21 @@ PI_DAILY_CAP=25
 # optional daily token cap: once a day's recorded spend reaches it, the NEXT job is refused pre-container.
 # Check-AFTER by nature (token cost is only known post-run), unlike PI_DAILY_CAP; unset = disabled
 # PI_DAILY_TOKEN_CAP=
+# optional per-job DOLLAR cap (issue #501): the runner stops a job before any model call that could take its
+# spend past it. A plain decimal, at most 6 decimals, above 0, at most 1000000 (e.g. 2.50). A trigger's run.maxCostUsd
+# can only lower it for that trigger's jobs. Needs a job image that declares the `costCap` capability: an older image
+# is refused for every capped job before anything is spent. Unset = no dollar cap (the token and job caps still apply)
+# PI_MAX_COST_USD=
+# optional dollar WINDOWS (issue #501): what all jobs may spend per UTC day, Monday week and month. Before a job
+# starts, its per-job cap is reserved in every window set here; a job that does not fit is refused (dollar-cap) and
+# spends nothing. After the run the reservation is replaced by the metered cost; when the cost is not fully known
+# the window is charged at least the reservation, and the metered cost when that is higher. Each needs
+# PI_MAX_COST_USD, the amount reserved per job. Same format as PI_MAX_COST_USD. Unset = off
+# With an allocation envelope (PI_ENVELOPE_FILE below), its total caps its window too: the smaller number wins, and a
+# job refused by the envelope's number or by its project's share is refused as allocation-cap, not dollar-cap
+# PI_DAILY_COST_USD=
+# PI_WEEKLY_COST_USD=
+# PI_MONTHLY_COST_USD=
 # how many jobs run in parallel
 PI_CONCURRENCY=3
 
@@ -159,23 +181,33 @@ PI_JOB_IMAGE=pi-job:latest
 # Unset = cron disabled for the worker; the receiver falls back to ./triggers.json in the folder it starts from (what `pi-dispatch init` scaffolds)
 # and refuses to start when neither exists (it holds the label/comment/pull_request trigger config)
 # PI_TRIGGERS_FILE=
-# The two keys below are the only ones where uncommenting WITHOUT filling in a path is worse than leaving
-# them alone: the worker keeps an empty value and refuses to start, rather than treating it as unset.
-# `pi-dispatch up` fills them in for you; by hand, write the path or leave the line commented.
+# The keys below are the ones where uncommenting WITHOUT filling in a path is worse than leaving them alone:
+# the worker keeps an empty value and refuses to start, rather than treating it as unset.
+# `pi-dispatch up` fills in the first three for you; by hand, write the path or leave the line commented.
 # ABSOLUTE path to pause-windows.json — "quiet hours" per folder/repo (pause runs between certain times/days/dates, auto-resume). Unset = feature off. See docs/pause-windows.md
 # `pi-dispatch up` sets this to the pause-windows.json in the folder it runs in, which is the one `init` scaffolds and the one the panel defaults to, so all three agree
 # PI_PAUSE_WINDOWS_FILE=
-# ABSOLUTE path to scoped-limits.json — per repo/folder job-count caps (day/week/month, refused pre-spend as scope-cap) and max concurrent jobs per scope (excess deferred, never dropped).
+# ABSOLUTE path to scoped-limits.json: per repo/folder job-count caps (day/week/month, refused pre-spend as scope-cap) and max concurrent jobs per scope (excess deferred, never dropped); project:<id> rows cap a whole project (projects.json), refused as project-cap.
 # Unset = no scoped caps or concurrency; the one-job-per-folder mutex for local jobs is always on and needs no file. See docs/scoped-limits.md
+# Version 2 of the file adds dollar windows (dayUsd/weekUsd/monthUsd) per repo or folder, and model:<provider>/<model> rows; each needs a per-job cap (PI_MAX_COST_USD or run.maxCostUsd)
 # `pi-dispatch up` sets this to the scoped-limits.json in the folder it runs in, the same way and for the same reason as PI_PAUSE_WINDOWS_FILE above
 # PI_SCOPED_LIMITS_FILE=
+# ABSOLUTE path to projects.json: named groups of repos and folders (members like github:owner/name or an absolute folder). Each run records its project's id.
+# Unset = no projects, and every run records no project. See docs/projects.md
+# `pi-dispatch up` sets this to the projects.json in the folder it runs in, the same way and for the same reason as PI_PAUSE_WINDOWS_FILE above
+# PI_PROJECTS_FILE=
+# ABSOLUTE path to envelope.json: the allocation envelope. A dollar total for one window (day, week or month), a floor per project of projects.json, default weights and the delegation rules.
+# Inside it a priorities plan splits the dollar budget between projects with no keypress; jobs over their project's share are refused pre-spend as allocation-cap. Unset = no envelope and no delegation; once a split has been applied, also run `valkey-cli DEL alloc:plan alloc:envelope:expected`.
+# Needs PI_MAX_COST_USD. Like the keys above, an EMPTY value refuses the start; unlike them, `pi-dispatch up` and `init` never set it, so delegation stays off until you turn it on.
+# The path must be canonical (no symlink, "." or "..") and outside every job path (cron run.folder, PI_DISPATCH_RUN_ROOTS, run.skillsDir, PI_GLOBAL_PI_DIR). Every host needs the same file, or hosts refuse with envelope-mismatch (a host without it too, while the fleet has a split). See docs/allocation.md
+# PI_ENVELOPE_FILE=
 # path to subscriptions.json — operator-declared subscription plan prices (the admin defaults to ./subscriptions.json in its working directory). Read by the ADMIN EXTENSION only, never at job time.
 # Subscription-backed providers bill 0 per run (their rate tables are all zeros), so this file is where the real price lives — cost analytics only; it changes no routing, auth, or job behavior
 # PI_SUBSCRIPTIONS_FILE=
 # ABSOLUTE path to the runtime settings overlay (default: ~/.pi-dispatch/settings.json); edited by the admin extension, read by the worker per job
 # DURABLE by default, beside the run history. Losing it does not stop jobs, it WIDENS them: a missing file reads as an empty overlay and every panel-set cap falls back to this file's values
 # Same per-user caveat as PI_LOGS_DIR, and the same fix: `pi-dispatch up` writes the resolved account default here explicitly, so the worker and the panel cannot drift apart silently
-# The setup wizard's deployment pointer does NOT carry this key (it carries the triggers, pause-windows, scoped-limits and subscriptions paths), so an explicit line here is what keeps the two in step
+# The setup wizard's deployment pointer does NOT carry this key (it carries the triggers, pause-windows, scoped-limits, projects and subscriptions paths), so an explicit line here is what keeps the two in step
 # PI_SETTINGS_FILE=
 # ABSOLUTE path to the deployment pointer the /dispatch panel reads to find a deployment built elsewhere
 # (default: <your pi agent dir>/pi-dispatch-deployment.json). Read by the ADMIN EXTENSION only; the worker and receiver never look at it.
@@ -291,6 +323,10 @@ PI_SCHEDULER_STALL_MAX=2
 # the proxy container the per-job network is built around (default: pi-dispatch-egress-proxy)
 # While the policy is armed, PI_FORWARD_ENV must not carry HTTPS_PROXY/HTTP_PROXY/NO_PROXY/NODE_USE_ENV_PROXY: the policy sets them itself, and a forwarded value would redirect every job while looking like the control working.
 # PI_EGRESS_PROXY=
+# path to model-endpoints.json: the local or LAN model servers (Ollama, vLLM, llama.cpp, LM Studio) a job may reach through the proxy,
+# each by one host and one port, with its number of parallel slots. Default: model-endpoints.json in the folder the worker starts from,
+# which `pi-dispatch init` writes empty. A missing default file declares no endpoints; a path set here that does not exist, or an empty value, is refused
+# PI_MODEL_ENDPOINTS_FILE=
 
 # OS-path-delimited allowlist (; on Windows, : elsewhere) of folders the model-callable dispatch_run may target; default empty = fail-closed (dispatch_run refuses every folder until you opt in)
 # PI_DISPATCH_RUN_ROOTS=

package/README.md

@@ -4,10 +4,13 @@ The worker and the `pi-dispatch` command line tool of
 **[pi-dispatch](https://github.com/edgehero/pi-dispatch)**, which runs the
 [pi](https://github.com/earendil-works/pi) coding agent as a self hosted background service.
 
-The worker takes jobs from a durable queue (Valkey with BullMQ). It checks the spend caps before
-anything is spent, starts one locked down container per job (Docker or Podman), gives the agent the
-job, records what it did and what it cost, and removes the container. Jobs come from the command line,
-from cron triggers, or from forge events that the
+The worker takes jobs from a durable queue (Valkey with BullMQ). Before anything is spent it checks every
+cap that applies: job counts and a daily token count for the whole deployment, job counts per repo, folder
+or project, and dollars per day, week or month for the deployment and per repo, folder, project or model,
+plus each project's share of the budget split. It then starts one locked down container per job (Docker or
+Podman), holds the job to its own dollar cap when one is set, gives the agent the job, records what it did
+and what it cost, and removes the container. Jobs come from the command line, from cron triggers, or from
+forge events that the
 [receiver](https://www.npmjs.com/package/@edgehero/pi-dispatch-receiver) queues.
 
 ## Start
@@ -25,7 +28,8 @@ npx @edgehero/pi-dispatch run ./my-project --task "add type hints" --flow tidy
 ```
 
 A local job edits your folder **in place**, and there is no undo, so commit first. The worker refuses a
-folder with uncommitted changes unless you pass `--force`.
+folder with uncommitted changes unless you pass `--force`. The folder must be the root of a git repository
+with at least one commit, and `run` refuses any other folder before it queues anything.
 
 ## Commands
 
@@ -36,11 +40,13 @@ folder with uncommitted changes unless you pass `--force`.
 | `doctor [--fix] [--live]` | check the whole setup; `--live` reads the isolation guarantees back from real containers |
 | `worker` | run jobs from the queue |
 | `run <folder> --task "..."` | queue one job against a local folder |
+| `run --trigger <id>` | fire one cron trigger from the triggers file now, once, as its schedule would |
 | `status`, `pause`, `resume`, `cancel <jobId>` | steer the running worker from any terminal |
 | `service render\|install\|status\|restart` | run the worker (or `--receiver`) as a service (user level on macOS and Linux, nssm on Windows) |
 | `setup github` | create a GitHub App in one browser click |
 | `import-pi` | stage your own pi setup (models, skills, persona) for every job, without credentials |
 | `sandbox <jobId>` | reopen a finished run's workspace in a fresh container with no credentials |
+| `egress render` | write `model-endpoints.conf` from `model-endpoints.json`, then print the command that reloads the egress proxy |
 
 Before you rely on it, read [`SECURITY.md`](https://github.com/edgehero/pi-dispatch/blob/main/SECURITY.md).
 In short: the agent can read the provider key and the forge token inside its container, and the

package/deploy/docker-compose.yml

@@ -134,6 +134,18 @@ services:
       # never clobbers an edited allowlist. Mounting a path that does not exist makes Docker create it as a
       # DIRECTORY and squid then fails confusingly, which is why init writes it first.
       - ../egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro,z
+      # The declared model endpoints' rules (issue #503), rendered from model-endpoints.json by
+      # `pi-dispatch egress render` and read by the rules' `include`. `init` scaffolds it empty. It must exist:
+      # squid refuses to start when an included file is missing. After a render, reload with
+      # `docker exec pi-dispatch-egress-proxy squid -k reconfigure`, not a restart.
+      - ../model-endpoints.conf:/etc/pi-dispatch/model-endpoints.conf:ro,z
+    # How the proxy reaches a model server on this host (issue #503). On Docker Engine (Linux) this name does
+    # not exist without the line, and host-gateway is the bridge gateway (docker0, 172.17.0.1). Docker
+    # Desktop already resolves the name, and host-gateway there is the same host address, so the line is kept
+    # for both. It is on the PROXY only: a job never gets it, and reaches the host only through a declared
+    # endpoint's CONNECT rule.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     networks:
       - egress-out
     restart: unless-stopped

package/deploy/egress-proxy.conf

@@ -6,9 +6,12 @@
 # misordered one silently allows everything, so the file an operator edits contains no ordering at all.
 #
 # What this policy is, and is not:
-#   - Hostname filtering on CONNECT, to port 443 only. The provider, the forge and the registry are
-#     ordinary entries in the allowlist, and nothing is special. The one address-based rule is a DENY:
-#     a listed name that resolves to a fixed loopback or link-local address of this host is refused.
+#   - Hostname filtering, and exactly two shapes pass (issue #508): a CONNECT tunnel to a listed host
+#     on port 443, or a plain (untunnelled) request to a listed host on port 80. Nothing else. The
+#     provider, the forge and the registry are ordinary entries in the allowlist, and nothing is
+#     special. The one address-based rule is a DENY: a listed name that resolves to a fixed loopback
+#     or link-local address of this host is refused. Beside those, a model server you declare (issue
+#     #503) is a CONNECT tunnel to its one host and port, from the include below, and nothing else.
 #   - TLS is NEVER terminated. This proxy sees the name a client asks for and no byte inside the tunnel,
 #     so it cannot read a credential and cannot account for a token. A proxy that decrypts provider
 #     traffic is OQ-011's mechanism, a materially larger change, and it is not this.
@@ -29,6 +32,15 @@ http_port 3128
 acl allowed dstdomain -n "/etc/pi-dispatch/allowlist.conf"
 
 acl SSL_ports port 443
+# Stock squid's name, narrowed to one port (issue #508). Without it `allow allowed` below let any
+# tool that forwards plain HTTP (npm undici's EnvHttpProxyAgent from 8.7 on without proxyTunnel, a
+# package manager, a curl -x a job brings) reach ANY port of a listed host, in clear text. What every
+# job has never takes this path: pi and the runner tunnel every origin, Node 22's built-in fetch sends a
+# CONNECT even for http://, and the job image's git ignores HTTP_PROXY for an http:// remote. A side
+# effect: a plain forward `GET https://host/`, where this proxy would open the TLS itself, is refused
+# too, since it names port 443 without a CONNECT. Measured on Docker and rootless Podman 4.9.3 and 5.8.1
+# (docs/egress.md): port 8080 went from 200 to 403, port 80 stayed 200.
+acl Safe_ports port 80
 acl CONNECT method CONNECT
 
 # The host's own services, by address (issue #428). On rootless Podman an account's containers.conf
@@ -55,9 +67,22 @@ acl to_host_local dst 127.0.0.0/8 0.0.0.0/32 169.254.0.0/16 10.0.2.2/32 ::1 ::/1
 # debug_options 78,3: a CONNECT to an unlisted name sent a DNS query, where without the rule it sent
 # none), which is a DNS channel out of an egress-armed job. With `allowed` first, only a listed name
 # is ever resolved here, and it is the only kind the allows below could let through anyway.
+# The port rule for plain requests (issue #508) sits right before the allow it narrows: first match
+# wins, so after it it would never apply. It names only port and method ACLs, which resolve nothing,
+# so no unlisted name is resolved by it. It never matches a CONNECT, so the tunnel rules (including a
+# CONNECT allow later placed between the first two rules, see #503) are untouched by it.
 http_access deny allowed to_host_local
+# The declared model endpoints (issue #503): `model-endpoints.conf` in your deployment folder, rendered
+# from model-endpoints.json by `pi-dispatch egress render`, empty by default. It only adds a CONNECT
+# allow for each declared host and port pair, and a deny for such a host that resolves to loopback.
+# It sits BEFORE the next line on purpose: pi tunnels every provider call, plain http:// included, so a
+# call to a model server arrives as a CONNECT to its port, and first match wins, so the port-443 deny
+# below would refuse it before any later allow was read. The file must exist (squid will not start
+# without it). After a render, reload with `squid -k reconfigure` in this container, not a restart.
+include /etc/pi-dispatch/model-endpoints.conf
 http_access deny CONNECT !SSL_ports
 http_access allow CONNECT allowed
+http_access deny !Safe_ports !CONNECT
 http_access allow allowed
 http_access deny all
 

package/deploy/pi-dispatch-egress-proxy.container

@@ -3,10 +3,10 @@
 # this account's own rootless Podman.
 #
 # Installed by `pi-dispatch service install` (user scope, with podman in PI_BACKENDS and PI_EGRESS armed) and by
-# `pi-dispatch up`. Unlike the Valkey unit this one is RENDERED: the two /opt/pi-dispatch paths below are
+# `pi-dispatch up`. Unlike the Valkey unit this one is RENDERED: the three /opt/pi-dispatch paths below are
 # placeholders, replaced with an account-owned copy of the package's egress-proxy.conf (written beside this account's
 # config, because `z` cannot relabel a root-owned package file: measured, exit 126) and with the deployment folder's
-# egress-allowlist.conf. Never `systemctl --user enable` it (a generated unit refuses that); the [Install] section is
+# egress-allowlist.conf and model-endpoints.conf. Never `systemctl --user enable` it (a generated unit refuses that); the [Install] section is
 # read by the generator itself.
 #
 # A RESTART DROPS EVERY PER-JOB NETWORK (measured on Podman 5.8.1). The generated unit runs `podman run --replace
@@ -34,6 +34,12 @@ Network=pi-dispatch-egress-out.network
 # on a host that also runs the compose proxy the same allowlist file is mounted by both.
 Volume=/opt/pi-dispatch/deploy/egress-proxy.conf:/etc/squid/squid.conf:ro,z
 Volume=/opt/pi-dispatch/egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro,z
+# The declared model endpoints' rules (issue #503), the deployment folder's own file like the list, never a copy:
+# `pi-dispatch egress render` rewrites it in place, and a copy would not be the file the render wrote. `init`
+# scaffolds it empty. It must exist, since squid will not start when an included file is missing. After a render,
+# `podman exec pi-dispatch-egress-proxy squid -k reconfigure` reloads it; a restart is not needed and drops every job
+# network (above). No host-gateway line: rootless Podman resolves host.containers.internal with no flag.
+Volume=/opt/pi-dispatch/model-endpoints.conf:/etc/pi-dispatch/model-endpoints.conf:ro,z
 # The exec form, a JSON array, for the reason the compose file gives: a plain string runs under /bin/sh, which on
 # this image is dash, where /dev/tcp does not exist and the check would fail forever while squid serves.
 HealthCmd=["bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/3128"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "type": "module",
   "description": "The pi-dispatch worker and CLI: runs the pi coding agent as a self-hosted service, one locked down Docker or Podman container per job, with spend caps checked before anything is spent, plus init, up, doctor and service install.",
   "keywords": [
@@ -70,6 +70,10 @@
     "./packages": "./src/packages.mjs",
     "./pause-windows": "./src/pause-windows.mjs",
     "./scoped-limits": "./src/scoped-limits.mjs",
+    "./projects": "./src/projects.mjs",
+    "./priorities": "./src/priorities.mjs",
+    "./envelope": "./src/envelope.mjs",
+    "./allocation": "./src/allocation.mjs",
     "./wait-for": "./src/wait-for.mjs",
     "./wait-state": "./src/wait-state.mjs",
     "./cancel-state": "./src/cancel-state.mjs",
@@ -79,6 +83,7 @@
     "./forgejo-identity": "./src/forgejo-identity.mjs",
     "./azure-identity": "./src/azure-identity.mjs",
     "./get-token": "./src/get-token.mjs",
+    "./octokit-log": "./src/octokit-log.mjs",
     "./runtime-settings": "./src/runtime-settings.mjs",
     "./run-history": "./src/run-history.mjs",
     "./run-mirror": "./src/run-mirror.mjs",
@@ -87,6 +92,8 @@
     "./subscriptions": "./src/subscriptions.mjs",
     "./budget": "./src/budget.mjs",
     "./pricing": "./src/pricing.mjs",
+    "./money": "./src/money.mjs",
+    "./dollar-budget": "./src/dollar-budget.mjs",
     "./scheduler-stall-guard": "./src/scheduler-stall-guard.mjs",
     "./watch-closer": "./src/watch-closer.mjs"
   },