claude
f0173440e4
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>
257 lines
15 KiB
Markdown
257 lines
15 KiB
Markdown
# Build plan
|
||
|
||
Where PIG stands, audited against the tree rather than against the last version
|
||
of this document.
|
||
|
||
The original plan was 24 tasks in three waves with real dependency edges, so
|
||
that work could be handed to several people (or several agents) at once without
|
||
them colliding. **Every one of those tasks has shipped.** What follows is the
|
||
audit, then the work that is actually left — which is a different and shorter
|
||
list, and mostly not new code.
|
||
|
||
---
|
||
|
||
## Where PIG stands
|
||
|
||
Live at primeintellectgrowth.com. Around 45k lines of TypeScript including
|
||
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
|
||
- Write paths for accounts, contacts, both deal sides, commitments,
|
||
allocations, holds, contracts, calendar entries and activities
|
||
- RBAC: eleven capabilities resolved from team and role, enforced on every
|
||
write and shared with the browser — see the caveat under **Left to do**
|
||
- Auth: Supabase or any OIDC provider behind one interface; invite-gated
|
||
registration, profile creation, sign-out
|
||
- 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 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
|
||
- Docker, Compose, Caddy, `deploy.sh` with rollback, and tag-to-ship CD —
|
||
including Piggy, which ships and rolls back with the app when `PIGGY_ENABLED`
|
||
is on rather than being started by hand
|
||
|
||
---
|
||
|
||
## Audit of the original plan
|
||
|
||
Verified by reading the tree on 2026-08-13. Every row was checked; none was
|
||
believed on the strength of the previous version of this file.
|
||
|
||
### Wave 0 — Foundation
|
||
|
||
| | Task | Status |
|
||
|---|---|---|
|
||
| **F1** | shadcn primitive set | **Done.** 22 primitives in `apps/web/src/components/ui`, including everything the plan listed |
|
||
| **F2** | Shared API write-path convention | **Done.** `apps/api/src/lib/mutation.ts` — ontology-derived zod schemas, one transaction per write, automatic activity logging, consistent error shape |
|
||
| **F3** | RBAC | **Done.** `packages/core/src/permissions.ts` — eleven capabilities, ranked roles, shared by API and browser. Reads were added later and are *not yet enforced*; see below |
|
||
|
||
### Wave 1
|
||
|
||
| | Task | Status |
|
||
|---|---|---|
|
||
| **A1** | Allocation + commitment write API | **Done.** `routes/capacity-writes.ts`, availability invariant enforced server-side |
|
||
| **A2** | API keys | **Done.** `routes/api-keys.ts` — mint, list, revoke; plaintext shown once |
|
||
| **A3** | Auth-provider seam | **Done.** `lib/auth-provider.ts`; OIDC is a full second implementation, not a stub |
|
||
| **A4** | Piggy | **Done.** `apps/piggy` — worker, queue, provider, tools. See the gap on task kinds below |
|
||
| **A5** | Slack adapter | **Done.** `routes/slack.ts` + `services/slack.ts`; signed-request verification, channel links, capacity slash command |
|
||
| **A6** | Buzz adapter | **Done.** `routes/buzz.ts`, same notifier interface, mounted only when `BUZZ_RELAY_URL` is set |
|
||
| **A7** | `pig` CLI | **Done.** `apps/cli` — `me`, `accounts`, `deals`, `commitments`, `allocations`, `capacity`, with `--json` |
|
||
| **A8** | Data table + ⌘K palette | **Done.** `components/DataTable.tsx`, `components/CommandPalette.tsx` |
|
||
| **A9** | `SourcedValue` + fact review | **Done.** `components/SourcedValue.tsx`, `pages/FactReview.tsx`, `routes/facts.ts` |
|
||
| **A10** | Contracts UI | **Done.** `pages/Contracts.tsx` over `contracts`, `sla_terms`, `sla_metric_targets`, `contract_obligations` |
|
||
| **A11** | Record create/edit sheets | **Done.** `components/RecordSheets.tsx` |
|
||
| **A12** | Capacity tiers | **Done.** `SECURITY_TIERS = ['government', 'secure_cloud', 'community_cloud']` with a rank comparison, so a requirement is satisfied only from at or above its tier |
|
||
| **A13** | Admin settings | **Done.** `routes/admin-settings.ts`, `components/AdminSettings.tsx` |
|
||
| **A14** | Import framework | **Done.** `routes/imports.ts`, `services/tabular-import.ts` — CSV and .xlsx, mapping, preview, idempotent commit, gated on `data:import` |
|
||
| **A15** | Notion import | **Done.** `routes/notion-import.ts` |
|
||
| **A16** | Google Sheets import | **Done.** `routes/google-sheets.ts` |
|
||
|
||
### Wave 2
|
||
|
||
| | Task | Status |
|
||
|---|---|---|
|
||
| **B1** | Allocation UI | **Done.** `components/AllocationSheet.tsx`, reachable from the matcher |
|
||
| **B2** | Piggy chat UI | **Done.** `components/PiggyChat.tsx` + `PiggyDock.tsx`, streaming with separate reasoning and tool-call events |
|
||
| **B3** | Slack/Buzz connection settings | **Done.** `components/IntegrationSettings.tsx`, `routes/integration-settings.ts` |
|
||
| **B4** | Critical-path E2E | **Done.** `apps/api/e2e/critical-path.test.ts`, run by CI against a real Postgres |
|
||
|
||
### Built since, and not in the original plan
|
||
|
||
| Feature | Where |
|
||
|---|---|
|
||
| Read-authorisation policy table and governance test | `routes/read-guards.ts`, `lib/read-guard.ts` — **written, tested, not mounted** |
|
||
| GTM calendar: thirteen event kinds across nine tables, three-month timeline | `routes/calendar.ts`, `services/calendar.ts`, `pages/Calendar.tsx`. This is what finally surfaced `export_authorizations` and `compliance_artifacts`, which had indexed `expires_at` columns and no UI at all |
|
||
| Growth / customer lifecycle projection | `services/customer-lifecycle.ts`, `pages/Growth.tsx` |
|
||
| Learn: member curriculum plus a code-gated public track | `routes/learn.ts` (**not mounted**), `pages/Learn.tsx` |
|
||
| HubSpot: OAuth, connections, sync jobs, webhooks, seven tables | `routes/hubspot.ts`, `routes/hubspot-webhook.ts` (**neither mounted**) |
|
||
| 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` |
|
||
|
||
---
|
||
|
||
## Left to do
|
||
|
||
In rough order of value. The first four are all "wire up something that already
|
||
exists", which is a strange shape for a backlog and worth taking seriously
|
||
because that is exactly the kind of work that stays undone.
|
||
|
||
**1. Mount `createReadGuardRoutes`.** The read half of the permission model —
|
||
`book:read`, `economics:read`, `team:read` — has a policy table, middleware, and
|
||
a governance test that fails when a GET appears with no rule covering it. None
|
||
of it runs, because `app.ts` never mounts it. Until it does, any authenticated
|
||
member reads supplier cost, break-even price and every margin total regardless
|
||
of team or role. Registration order is load-bearing: Hono runs matched handlers
|
||
in the order they were registered, so the guard must be mounted before the
|
||
handlers it guards.
|
||
|
||
**2. Mount `learn.ts`.** `/learn` is in the navigation and every one of its API
|
||
paths answers 404.
|
||
|
||
**3. Enqueue the other six agent task kinds.** `AGENT_TASK_KINDS` declares
|
||
eight. Only `enrich_account` and `enrich_contact` are ever written to
|
||
`agent_tasks`, both from record creation in `routes/records.ts`. `write_brief`,
|
||
`match_capacity`, `detect_idle_capacity`, `summarise_pipeline`, `watch_renewal`
|
||
and `research_supplier` have no producer anywhere. The worker is generic and
|
||
complete; the gap is entirely on the enqueue side, and each one is a few lines
|
||
in the service that already computes the underlying answer.
|
||
|
||
**4. Mount the HubSpot routes, or delete them.** Seven `hubspot_*` tables, an
|
||
OAuth flow, sync cursors, jobs and a verified webhook endpoint, all written,
|
||
all tested, all unreachable. Whichever way this goes it should not stay in this
|
||
state — dead-but-tested code reads as shipped to anyone grepping the repo.
|
||
|
||
**5. Row-level or team-scoped reads.** Every read returns the whole book. This
|
||
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. 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
|
||
`PIG_SETTINGS_ENCRYPTION_KEY` were missing from `.env.example`, which made the
|
||
documented `cp .env.example .env` fail at the first compose command. Both are
|
||
in it now, along with every Piggy key.)
|
||
|
||
**8. A remote MCP transport.** The server is stdio only; there is no
|
||
Streamable HTTP transport and no `/mcp` endpoint on the API, so every user runs
|
||
the server locally. The package is also unpublished, so `npx @pig/mcp` does not
|
||
work and the documented install command has to be a path into a clone.
|
||
|
||
Not started at all, and deliberately: email or calendar ingestion, forecasting,
|
||
quota and attainment, invoicing or billing reconciliation, multi-tenancy, and
|
||
any native mobile application.
|
||
|
||
---
|
||
|
||
## On the component library
|
||
|
||
Three gaps were identified in an early review of the front end. All three have
|
||
since been acted on.
|
||
|
||
**The primitive set was too thin — 9 at the time.** PIG now has 22, including
|
||
the ones that mattered: `data-table`, `command`, `sheet`, `drawer`, `sidebar`,
|
||
`form`. The agent-chat compositions (`message`, `reasoning`,
|
||
`thinking-indicator`) are ours, written inside `PiggyChat.tsx`.
|
||
|
||
**`SourcedValue` / `Provenance` had to exist** — a dotted underline on any
|
||
agent-derived value, with a tooltip carrying the claim, the reasons, when it was
|
||
observed and the source URL. PIG already held that data in `facts` and surfaced
|
||
none of it. It does now.
|
||
|
||
**Mobile is a lead, and the ratio has held:** PIG is 63 `.tsx` files with
|
||
safe-area handling, a bottom tab bar, a sidebar Sheet and a hard rule that no
|
||
route may scroll sideways at 393px. Most tools in this category are effectively
|
||
desktop-only.
|
||
|
||
**Where a primitive is a shadcn/ui original, install it from upstream**, where
|
||
it is canonical and current — not lifted out of somebody else's repository.
|
||
Compositions we write ourselves.
|
||
|
||
---
|
||
|
||
## Prime Intellect API — verified facts
|
||
|
||
Confirmed against the live API, not assumed.
|
||
|
||
**Two different hosts.** `api.primeintellect.ai` is the compute/pods API
|
||
(availability, pods, billing). Inference is `api.pinference.ai/api/v1`, which
|
||
is OpenAI-compatible (`/chat/completions`, `/models`, and an Anthropic-style
|
||
`/messages`). PIG's config carries both separately — `PRIME_API_BASE` and
|
||
`PIGGY_INFERENCE_BASE`.
|
||
|
||
**`prices.onDemand` is the TOTAL FOR THE NODE, not per-GPU.** Verified:
|
||
datacrunch lists 1× A100 at 1.79 and 2× A100 at 3.58. `gpuMemory` is likewise a
|
||
node total (640 for 8× 80GB). This was a real bug — an 8-GPU node read eight
|
||
times too expensive — and is **fixed**: `packages/prime/src/map.ts` divides both
|
||
by `gpuCount` at the boundary and keeps the node totals in `raw` for
|
||
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`. 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`.
|
||
|
||
**The user-agent concern did not reproduce** — both a browser UA and PIG's own
|
||
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, 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.
|
||
- **Which key does PIG get?** The existing Prime Intellect key is broad and
|
||
never expires. PIG's sync should hold a separate one scoped to
|
||
`Availability → Read`.
|