Put Piggy on Prime Agent, and let it write to the book

Piggy was a hand-rolled OpenAI tool loop. It is now a Prime Agent session —
Prime Intellect's own harness, embedded as a Node library — answering from
PIG's tools and, for the first time, able to put information into the CRM
rather than only read it out.

The harness is a coding agent, so the first job was taking the coding agent
away from it. `noTools: 'all'` plus an explicit allowlist leaves the model
with PIG's ten `pig_*` tools and no bash, no filesystem, no IPython. That
holds under attack: a hostile extension, a skill and a settings file planted
in the agent's own directory, then `setActiveToolsByName` called with every
built-in, still leaves ten tools, all ours. Both lines are load-bearing —
`noTools` alone registers nothing, and the allowlist is what admits our own.

Writing is gated rather than assumed. A change is proposed, not made: the
tool returns a description, the transcript renders a diff card, and nothing
reaches the database until someone presses Apply. Contracts, commitments,
allocations and compliance always stop for a human whatever the mode. Every
write runs through `executeMutation` as the calling user, so their
capabilities and the audit trail apply exactly as they would to a human's.

Four things about the SDK are wrong in its own documentation and cost a
debugging cycle each: models.json does not resolve an env var name for
`apiKey`, it sends the literal string; there is no built-in prime-inference
provider in 0.84.1; a ResourceLoader you pass in is never reloaded for you;
and the stock system prompt is a coding-assistant prompt that must be
replaced — but replacing it also silently removes the tool list, because the
harness only renders that section when it owns the prompt. AGENTS.md records
all four.

The expensive one was thinking level. The harness defaults to `medium`, and
nemotron spent an entire 4,096-token budget reasoning and returned an empty
answer. `low` was worse; `off` omits the parameter so the endpoint's default
wins. An explicit `reasoning_effort: none` via `thinkingLevelMap` took a turn
from 6,195 output tokens to 149.

And a turn is now bounded. The harness loop is `while (true)` with no
iteration cap; a runaway on a frontier model would have eaten the credit it
is supposed to report on. Ceilings on model calls and tokens, enforced both
through the harness hook and independently from the event stream, plus a
per-user daily spend limit — and the ledger now records spend on turns that
fail, which it previously discarded.

Signing in lands on /piggy, which is a workspace: conversations down one
side, the agent in the middle, what it did and what it cost beside it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/build-plan.md

@@ -14,8 +14,8 @@ list, and mostly not new code.
 ## Where PIG stands
 
 Live at primeintellectgrowth.com. Around 45k lines of TypeScript including
-tests, 261 unit tests across five packages plus a critical-path E2E suite,
-green CI, 47 tables, 13 migrations.
+tests, 403 unit tests across five packages plus critical-path E2E suites
+(`apps/api/e2e`, `apps/piggy/e2e`), green CI, 47 tables, 15 migrations.
 
 - The ontology and margin engine, with the `allocations` join at the centre
 - Both pipelines; capacity availability, matching, holds and idle alerts
@@ -28,8 +28,10 @@ green CI, 47 tables, 13 migrations.
 - Import: CSV and .xlsx with mapping, dry-run preview and idempotent commit;
   Notion and Google Sheets as OAuth sources onto the same mapping step
 - Piggy: lease-based queue worker with `SKIP LOCKED` claims, renewable leases,
-  capped exponential backoff and `agent_runs`; plus a private read-only chat
-  server behind the API
+  capped exponential backoff and `agent_runs`; plus a private chat server behind
+  the API, running Prime Agent (`@earendil-works/pi-coding-agent`) over the CRM
+  tools with no shell, filesystem or Python, and a write surface that proposes
+  before it writes — see AGENTS.md §6
 - MCP server (9 tools, stdio), `pig` CLI, Prime Intellect client, demo dataset
 - Slack and Buzz notification adapters behind one notifier interface
 - Growth (customer lifecycle projection) and the GTM calendar
@@ -94,6 +96,9 @@ believed on the strength of the previous version of this file.
 | Notification outbox | `services/notification-outbox.ts` |
 | Tag-to-ship CD with a host-side release poller and rollback | `.gitea/workflows/ci.yml`, `scripts/autodeploy.sh`, `deploy/pig-autodeploy.*` |
 | Three-pane application shell with a docked agent | `components/Shell.tsx`, `AppHeader.tsx`, `AppSidebar.tsx` |
+| Piggy re-platformed onto Prime Agent, embedded as a Node library with `noTools: 'all'` and an allowlist | `apps/piggy/src/agent/*` — session, models.json, prompt, tool bridge |
+| Piggy writes, behind an approval rendezvous, as the calling user's own principal | `apps/piggy/src/write-tools.ts`, `chat-server.ts`, `packages/core/src/piggy-protocol.ts` |
+| Persisted conversations and the `/piggy` workspace | `piggy_conversations` + `piggy_messages` (migration 0014), `routes/piggy-conversations.ts`, `pages/Piggy.tsx` |
 
 ---
 
@@ -133,10 +138,25 @@ is why read capabilities are platform-wide, and it is the honest reason the
 permission model says so out loud. It is also the thing to build before PIG
 serves a company where that is not acceptable.
 
-**6. Piggy writes.** Interactive chat is read-only by design for now. The
-queue-side agent writes only to `facts`. A write path for the chat agent needs
-the same evidence discipline plus a confirmation step, and should not be added
-casually.
+**6. What is left on Piggy, now that it writes.** The chat agent has five write
+tools, each running through `executeMutation` as the calling user, and a
+proposal-and-approval step in `confirm` mode. Four things remain:
+
+- **A stage change Piggy makes raises no Slack notification.** The API route
+  passes a `NotificationOutbox` into `updateDemandDealMutationDefinition`;
+  `apps/piggy/src/write-tools.ts` does not, because the outbox is wired in the
+  API server and Piggy runs in its own process. A move made in chat is
+  therefore silent in Slack. Known gap, not a decision.
+- **No tool creates a guarded kind yet.** `requiresApproval` stops contracts,
+  commitments, allocations and compliance in every mode, and nothing currently
+  proposes one, so that rule is enforced and unexercised. Whoever adds the first
+  such tool should read `packages/core/src/piggy-protocol.ts` before writing a
+  line of it.
+- **The queue worker is still on the hand-rolled provider.** `apps/piggy/src/provider.ts`
+  speaks OpenAI-completions directly; only the chat path runs on Prime Agent.
+  Two model paths, two budgets, two sets of environment variables.
+- **`PIGGY_ENABLED` is `false` in production.** Everything above is shipped and
+  switched off; turning it on is `.env` plus a deploy.
 
 **7. `ANTHROPIC_API_KEY` is declared in `apps/api/src/lib/config.ts` and read by
 nothing** — remove it or use it. (`POSTGRES_PASSWORD` and
@@ -200,10 +220,15 @@ reconciliation. Anything new that reads an upstream price must do the same.
 
 **Piggy's default model:** `nvidia/nemotron-3-nano-30b-a3b` ($0.05/$0.20 per
 Mtok). It is a *hybrid reasoning* model that thinks aloud by default and will
-ramble or truncate under a tight `max_tokens`. Pass **`reasoning_effort:
-"none"`** for tool use, routing, extraction and classification — roughly one
-second, terse output. Leave reasoning on only for genuine maths or logic, where
-it arrives in a separate `reasoning_content` field while `content` stays clean.
+ramble or truncate under a tight `max_tokens`. It needs
+**`reasoning_effort: "none"`** for tool use, routing, extraction and
+classification — roughly one second, terse output. Measured on the agent path:
+with the harness's default thinking level the same question cost 6,195 output
+tokens and returned an empty answer; with the effort pinned to `none` it cost
+149. On the agent path that parameter is not passed by hand — it comes from the
+`thinkingLevelMap` on the model entry in `apps/piggy/src/agent/models.json`, and
+a model without one sends no reasoning parameter at all. Read
+**AGENTS.md §6.5** before changing `PIGGY_AGENT_MODEL` or `PIGGY_AGENT_THINKING`.
 
 **Billing** is pay-as-you-go against a shared balance, not a per-model
 whitelist. Check with `GET /api/v1/billing/wallet`.
@@ -213,12 +238,16 @@ returned 200. Worth remembering it was once an issue if a 403 ever appears.
 
 ## Open questions
 
-- **Which inference host for on-prem?** Settled in shape: both the model and
-  the host are environment values — `PIGGY_MODEL` and `PIGGY_INFERENCE_BASE`,
-  read once at Piggy's boot. Nothing about the agent is selectable at runtime;
-  `apps/piggy` never reads `platform_settings`, so a change means editing `.env`
-  and restarting the container. What is untested is a customer pointing the base
-  at their own OpenAI-compatible endpoint.
+- **Which inference host for on-prem?** Settled in shape, but no longer one
+  answer. The **queue worker** reads `PIGGY_MODEL` and `PIGGY_INFERENCE_BASE`
+  from the environment at boot. The **chat agent** reads its base URL and its
+  five models from `apps/piggy/src/agent/models.json`, which is compiled into
+  the image, so pointing it at another OpenAI-compatible endpoint means editing
+  that file rather than setting a variable. Nothing is read from
+  `platform_settings` on either path. What the user *can* choose at runtime is
+  which of the five models answers, and the mode — both ride on the request
+  rather than on configuration. A customer pointing either at their own endpoint
+  is still untested.
 - **Who may import?** Currently team admins and platform admins
   (`data:import`, minimum role `admin`, all teams). Easy to loosen, unpleasant
   to tighten after the fact.