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/agents.md

@@ -5,9 +5,11 @@ client, so nobody is asked to use a different tool than the one they already
 work in.
 
 This page is about connecting *your* agent to PIG. **Piggy**, the agent that
-lives inside PIG, is a different thing and is documented in the README — it
-drains a database queue and, in chat, reads and cites records for whoever is
-looking at the page.
+lives inside PIG, is a different thing: it drains a database queue, and in chat
+it runs a Prime Agent session over PIG's own tools for whoever is looking at the
+page — reading and citing records, and proposing changes the user approves. It
+is described in the README under *The agent surface*, and the engineering
+account, including the traps, is AGENTS.md §6.
 
 ## Transport, and what that means for you
 

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.

docs/learn-scripts.md

@@ -39,7 +39,8 @@ the agent sitting next to all of it.
    the first ten minutes of every deployment.
 5. **Piggy** — a GTM team will be asked "can it do X". The useful video is the
    one that draws the line, because the answer to "can it write to the CRM" is
-   no and being wrong about that in front of a customer is expensive.
+   now *yes, with your approval*, and being vague about which half applies in
+   front of a customer is expensive.
 
 Deliberately not filmed: `/growth`, `/demand`, `/supply`, `/contracts`,
 `/facts`. They are good pages, but each is either a conventional pipeline board
@@ -145,27 +146,31 @@ Hi team, check out this feature we worked on: Import gets you off the spreadshee
 
 ---
 
-## 5. Piggy, and what it will not do
+## 5. Piggy, and where the line is
 
 - **Slug:** `piggy-and-its-boundary`
-- **Title:** Piggy, and what it will not do
-- **Summary:** The docked agent reads through scoped, page-specific PIG tools — and has no shell, no filesystem, and no ability to write CRM records.
-- **Word count:** 101
+- **Title:** Piggy, and where the line is
+- **Summary:** The agent reads through scoped PIG tools, has no shell, filesystem or browser, and writes only what you approve — as you, under your own permissions.
+- **Word count:** 108
 
 ```narration
-Hi team, check out this feature we worked on: Piggy is docked on every page. Ask it about the book and it answers through scoped PIG tools, one per page: margin on Margin, idle capacity on Capacity, the same calendar projection the Calendar page renders. It gets aggregates, not the raw ledger, so it quotes rather than recomputes. What it cannot do matters as much: no shell, no filesystem, no browser, and this chat cannot write CRM records. On a record it reads only that record and cannot pivot to another. Check the source record before you act. thanks for watching!
+Hi team, check out this feature we worked on: Piggy is docked on every page. Ask it about the book and it answers through scoped PIG tools, one per page: margin on Margin, idle capacity on Capacity. It gets aggregates, not the raw ledger, so it quotes rather than recomputes. It can also change records now — but on Ask first, every change arrives as a card showing the old value and the new one, and nothing is saved until you press Apply. It writes as you, under your permissions, so it can never reach further than you can. No shell, no filesystem, no browser. thanks for watching!
 ```
 
 **Shot list**
 
 | ~sec | Route | On screen |
 |---|---|---|
-| 0–4 | `/piggy` | The workspace. The "Read-only workspace" pill and the "Inspection boundary" note. |
+| 0–4 | `/piggy` | The workspace, on the "Ask first" segment of the mode control. The line under the hero: "Piggy reads your PIG records through scoped tools, with no shell, filesystem or browser." |
 | 4–8 | `/margin` | Open the dock from the header while standing on Margin, so the dock is visibly attached to the page. |
 | 8–15 | `/margin` | Ask "how is the book doing". Show the tool step appearing in the transcript, then the answer quoting the same figures the page shows. |
 | 15–20 | `/capacity` | Move to Capacity, ask "what is idle and what does it cost". Show the different tool name in the transcript. |
-| 20–25 | `/piggy` | Hold on the line under the composer: "Piggy reads only through scoped PIG tools. It has no shell, filesystem or browser access, and this chat cannot write CRM records." |
-| 25–30 | `/accounts` | Open an account, press "Ask Piggy", and show the answer citing that record — then the footer line "Read-only session · Check source records before acting on material terms." |
+| 20–26 | `/demand` | Ask Piggy to log a call on a deal. Hold on the approval card — the field rows with the previous value beside the new one — then press **Apply** and show the badge settle to "Applied". |
+| 26–30 | `/piggy` | The mode control open, showing all three sentences: "Piggy answers from your CRM and is offered no tool that could change it" / "Piggy proposes each change and nothing is saved until you press Apply" / "Piggy makes changes to your CRM itself, without asking first." |
+
+**Do not film Auto mode making a change.** The point of the video is the
+approval step; a clip of an agent writing unattended is the clip that gets
+quoted back.
 
 ---
 
@@ -189,13 +194,21 @@ Kept so the next person does not re-derive them.
   `apps/web/src/pages/Imports.tsx`. Accepted file types are `.csv` and
   `.xlsx`. Google Sheets is read-only with server-side encrypted tokens and a
   bounded A1 range: `apps/web/src/components/GoogleSheetsSource.tsx`.
-- Piggy's tools are one per route — `pig_get_margin_summary`,
+- Piggy's page tools are one per route — `pig_get_margin_summary`,
   `pig_get_idle_capacity`, `pig_get_pipeline`, `pig_get_calendar_ahead`,
   `pig_get_workspace_summary` — mapped in `apps/piggy/src/page-routes.ts` and
-  implemented in `apps/piggy/src/page-tools.ts`. The record tool
-  `pig_get_record` takes no id and cannot inspect another record
-  (`apps/piggy/src/chat-tools.ts`). Results are aggregated because interactive
-  chat runs at `max_tokens` 1024 over at most four turns.
+  implemented in `apps/piggy/src/page-tools.ts`. The focused record tool
+  `pig_get_record` takes no id and reads only the record in context; a record
+  that is *not* in context is reachable by name through `pig_search_records`
+  and `pig_get_record_by_id` (`apps/piggy/src/chat-tools.ts`), so "it cannot
+  look at another record" is no longer true and must not be said on camera.
+  Results are aggregated because a chat turn has a bounded output budget
+  (`PIGGY_AGENT_MAX_TOKENS`, 4096 by default, reasoning included).
+- The five write tools are `pig_log_activity`, `pig_create_contact`,
+  `pig_create_task`, `pig_update_deal_stage` and `pig_update_record_fields`
+  (`apps/piggy/src/write-tools.ts`). None of them can change money, ownership
+  or a contract; the always-confirm kinds are in
+  `packages/core/src/piggy-protocol.ts`.
 - **Caveat for whoever schedules these:** `learn.ts` is not mounted in
   `apps/api/src/app.ts`, so `/api/learn/*` currently answers 404 and these rows
-  cannot be created yet. See AGENTS.md §7.
+  cannot be created yet. See AGENTS.md §8.