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>
109 lines
4.5 KiB
Markdown
109 lines
4.5 KiB
Markdown
# Connecting an agent
|
|
|
|
PIG is a first-class application for agents. The same MCP server serves every
|
|
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: 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
|
|
|
|
The MCP server speaks **stdio only**. There is no Streamable HTTP transport and
|
|
no `/mcp` endpoint on the API, so each person runs their own copy locally
|
|
against their own API key rather than pointing a client at a shared URL. That is
|
|
a real limitation, not a security posture — see the build plan.
|
|
|
|
`@pig/mcp` is a workspace package and is **not published to npm**, so `npx
|
|
@pig/mcp` does not work. Run it out of a clone.
|
|
|
|
## Setup
|
|
|
|
Create an API key in PIG under **Settings → API keys** — the plaintext is shown
|
|
once — then:
|
|
|
|
```bash
|
|
export PIG_URL=https://primeintellectgrowth.com
|
|
export PIG_API_KEY=pig_...
|
|
```
|
|
|
|
Scope the key to `read` unless the agent genuinely needs to write. An agent
|
|
acting for you is a **separate principal** from you: it has its own audit trail
|
|
and can be revoked without disturbing your session, and it can never reach
|
|
further than you can — on a write, the key's `write` scope is checked first and
|
|
then your own capability for that team.
|
|
|
|
⚠️ **Reads are not yet gated.** The read policy exists and is tested but is not
|
|
mounted in `app.ts`, so a `read`-scoped key currently reaches every GET in the
|
|
product, including supplier cost and margin. Treat any key you mint as
|
|
cost-visible until that lands.
|
|
|
|
## What connects
|
|
|
|
| Client | How |
|
|
|---|---|
|
|
| **Claude Code** | `claude mcp add pig -- pnpm --dir /path/to/pig exec tsx apps/mcp/src/stdio.ts` |
|
|
| **Codex** | Add the same command as an MCP server in its config, with the same two environment variables |
|
|
| **prime-agent** | It is an MCP *client*; register the same stdio command |
|
|
| **Buzz** | Agents reach PIG through the ACP bridge's MCP support |
|
|
|
|
## CLI
|
|
|
|
The `pig` CLI is the HTTP API surface for scripts and Prime Agent kernels. It
|
|
never receives database credentials and has no arbitrary-request, shell, or
|
|
filesystem command. Configure it separately from the MCP process:
|
|
|
|
```bash
|
|
export PIG_API_URL=https://primeintellectgrowth.com
|
|
export PIG_API_KEY=pig_...
|
|
|
|
pnpm run pig -- me
|
|
pnpm run pig -- --json capacity idle --threshold 0.2
|
|
pnpm run pig -- --json capacity search --gpu-type H100_80GB --min-gpu-count 8
|
|
```
|
|
|
|
`--api-url` and `--api-key` override the environment for one invocation. In
|
|
`--json` mode success writes one JSON value to stdout, while failures write one
|
|
JSON error to stderr and exit non-zero. The key is sent only as a bearer token
|
|
and is redacted if an upstream error happens to echo it.
|
|
|
|
## The tools
|
|
|
|
| Tool | What it answers |
|
|
|---|---|
|
|
| `pig_whoami` | Who am I acting for, and which teams am I on? |
|
|
| `pig_my_pipeline` | Where are we? What needs attention? |
|
|
| `pig_capacity_match` | What have we bought that would serve this customer? |
|
|
| `pig_margin_report` | What is each block earning against what it cost? |
|
|
| `pig_idle_capacity` | What are we paying for and not selling? |
|
|
| `pig_inventory_search` | What could we buy to cover demand we cannot serve? |
|
|
| `pig_search` | Find an account |
|
|
| `pig_get_account` | Everything about one account |
|
|
| `pig_log_activity` | Record a call, meeting or note |
|
|
|
|
`pig_capacity_match` is the one worth learning. Ask it in plain language:
|
|
|
|
> "A customer wants 128 H100s with InfiniBand for three months, ceiling $2.80
|
|
> per GPU-hour. What have we got?"
|
|
|
|
It returns ranked matches, preferring blocks that are sitting idle — those
|
|
hours are already paid for — and warns explicitly when a match would sell below
|
|
break-even.
|
|
|
|
## Why the surface is small
|
|
|
|
Nine tools, each doing one thing. A sprawling tool list measurably degrades
|
|
model performance, and anything genuinely niche is reachable through
|
|
`pig_search` or the HTTP API. If you need something that is not here, it is
|
|
probably better added as a service method than as a tenth tool.
|
|
|
|
## What it cannot do
|
|
|
|
The MCP server holds an API key and calls the same HTTP API a browser does. It
|
|
has no database credentials and no privileged path. There is deliberately no
|
|
tool that provisions infrastructure, spends money, or emails a customer.
|