@ssheleg/agent-stack 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## [0.9.0] — 2026-08-15
+
+### Added
+
+- **`agent-harness/references/pi.md` and `pi-sdk.md` — the harness doctrine as a worked
+  implementation.** Every other reference in that skill states a rule; **Pi** is small enough
+  to read and complete enough to have made each of those decisions in public. So each section
+  says what Pi does and then **which rule it is an instance of** — the second half is the
+  point, and where Pi disagrees with this pack, that is said rather than smoothed over.
+
+  Read from `pi.dev/docs/latest` on 2026-08-15: sixteen doc pages plus the package source.
+  All sixteen verified reachable (`200`); the only non-resolving URLs in either file are the
+  two deliberate placeholders inside custom-provider examples.
+
+- **`pi.md`** — the four ways to run it; **sessions as a JSONL tree** (8-hex `id`, `parentId`,
+  version 3, `BranchSummaryEntry`) matched to *time travel and forking* in
+  `agent-orchestrator/references/runtime.md`; **compaction with the real numbers**
+  (`contextTokens > contextWindow - reserveTokens`, defaults 16,384 and 20,000, tool results
+  truncated to 2,000 chars while summarizing) matched to the compaction ladder, with what the
+  ladder adds that Pi leaves to you; settings precedence that **merges rather than replaces**;
+  skills, prompt templates and packages; and the trust model.
+
+  Its sharpest section is **the deliberate absence of a sandbox**, quoted: *"prompt injection
+  from repository files … is expected local-agent risk and cannot be reliably prevented by
+  pi."* That is `layers.md`'s delegation thesis stated by the project itself — and for an
+  audit it changes the finding, because "no permission model" here is a delegation, not a
+  defect. Three containerization patterns are compared by **where credentials end up**, which
+  is the question that actually decides between them.
+
+- **`pi-sdk.md`** — `createAgentSession()`, `ModelRuntime`, `SessionManager`, `defineTool()`,
+  `DefaultResourceLoader`; the RPC protocol with its command groups, its full event lifecycle
+  and the **`\n`-only JSONL framing warning**; JSON mode's delta-only records and why;
+  the `ExtensionAPI` surface; and **the eight seams** — `tool_call` (can block),
+  `tool_result` (a middleware chain), `context`, `before_agent_start`, the three provider
+  hooks, and the compaction pair — each matched to the doctrine it lets you implement.
+  `tool_call` blocking is called out as the single most important one for an audit: it is
+  where a per-tool, per-caller policy can actually live.
+
+- Noted with its evidence and its limit: **Pi discovers skills from `~/.agents/skills/`**,
+  which on this machine is the ssheleg hub — 72 entries, every family skill carrying the
+  `name` and `description` front matter Pi requires. Stated as a fact about the path and the
+  front matter, **not** as an observed load: Pi is not installed here. The reference also
+  names Pi's documented divergence from the Agent Skills standard (a skill name may differ
+  from its directory) and warns that `make-skill`'s validator enforces the strict rule.
+
+### Changed
+
+- `references/layers.md` points at the two new files as the worked example of the kernel
+  layer it describes abstractly.
+- `agent-harness`'s description gains the embedding triggers (`agent SDK`, `embed an agent`,
+  `Pi harness`, `встроить агента`) — 807/1024, inside the family's 970 working budget. The
+  repository's own front-matter gate caught a first draft at 1066 and refused the write.
+
+
 ## [0.8.0] — 2026-08-14
 
 ### Added

package/README.md

@@ -11,7 +11,7 @@ Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills).
 
 Four skills — `agent-orchestrator` for wiring the loop, `agent-evals` for proving it
 behaves, `agent-interop` for everything it talks to outside its own process,
-`agent-harness` for what it is **told** — and sixteen references they load on demand,
+`agent-harness` for what it is **told** — and eighteen references they load on demand,
 plus one scanner.
 
 **The orchestrator** (`SKILL.md`) — what the agent reads first:
@@ -61,13 +61,16 @@ ACP, AGNTCY, AP2, Agent Skills — so an agent stops guessing.
 model, and the one where most agent bugs actually live: *the biggest performance
 improvements often come from clearly explaining tool usage in the system prompt*, and *even
 small refinements to tool descriptions can yield dramatic improvements*. Before adding a
-retry or a sub-agent, it asks four questions about the text. Five references —
+retry or a sub-agent, it asks four questions about the text. Seven references —
 `system-prompt.md` (right altitude, enumerated vocabulary, and the three things reasoning
 models changed — starting with **do not add chain-of-thought**), `tools.md` (the
 agent–computer interface, with a worked before/after and poka-yoke), `techniques.md`
 (fifteen techniques, a verdict each **for production** rather than a benchmark),
 `layers.md` (which layer you are building at, and why permission boundaries are usually the
-environment's job), `audit.md` (seven tracks, evidence tiers, a plan instead of a score).
+environment's job), `audit.md` (seven tracks, evidence tiers, a plan instead of a score) —
+plus **`pi.md` and `pi-sdk.md`, the doctrine as a worked implementation**: Pi read end to
+end, each mechanism matched to the rule it instantiates, its divergences named, and the
+eight extension seams where a permission gate or a context rewrite can actually live.
 
 It runs in both directions: **building a harness and auditing somebody else's are one
 checklist read forwards and backwards.** `scripts/audit_agent.py` is the mechanical half —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Production patterns for AI agent orchestrators \u2014 tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay \u2014 plus the wallet side of reselling LLM access. This package is the installer CLI.",
   "bin": {
     "agent-stack": "bin/agent-stack.js"

package/plugins/agent-stack/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "agent-stack",
   "displayName": "Agent Stack",
   "description": "Two skills: agent-orchestrator \u2014 tool-calling loops, multi-stage pipelines with checkpoints, provider routing with fallback, four-layer memory, context engineering, plus the wallet side of reselling LLM access; and agent-evals \u2014 run/trace/thread evals, judges, and fixtures grown from production.",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/agent-stack/skills/agent-harness/SKILL.md

@@ -2,15 +2,15 @@
 name: agent-harness
 description: >-
   Use when the question is what the agent is TOLD rather than how its loop is wired — writing
-  or fixing a system prompt, shaping tools so the model actually picks the right one,
-  deciding whether a job wants a workflow or an agent, or choosing between ReAct, reflection,
-  planning and voting. Also the audit direction: reviewing an agent system somebody else
-  built, with tracks, evidence tiers and a prioritized plan instead of a score, plus a
-  scanner for the defects that are mechanically visible. Triggers - "system prompt", "tool
-  description", "the agent picks the wrong tool", "agent loops forever", "prompt engineering",
-  "ReAct", "reflection", "workflow or agent", "audit this agent", "review our agent system",
-  "системный промпт", "агент не вызывает тул", "аудит агента", "воркфлоу или агент". Not for
-  the loop's plumbing, its evals, or the protocols it speaks — those are the sibling skills.
+  or fixing a system prompt, shaping tools so the model picks the right one, deciding whether
+  a job wants a workflow or an agent, or choosing between ReAct, reflection and voting. Also
+  auditing an agent system somebody else built: tracks, evidence tiers and a prioritized plan
+  instead of a score, plus a scanner. Carries Pi as a worked kernel implementation — SDK, RPC
+  and extension seams — for embedding or extending a harness. Triggers - "system prompt",
+  "tool description", "agent picks the wrong tool", "agent loops forever", "prompt
+  engineering", "ReAct", "workflow or agent", "audit this agent", "embed an agent", "agent
+  SDK", "Pi harness", "системный промпт", "агент не вызывает тул", "аудит агента", "встроить
+  агента". Not for the loop's plumbing, its evals, or its protocols — those are siblings.
 ---
 
 # Agent harness — what the agent is told, and how to audit what someone else told theirs
@@ -95,6 +95,8 @@ and `test/validate.py` fails the build on a reference that does not say when it
 | [`references/techniques.md`](references/techniques.md) | you are choosing between **ReAct, reflection, voting, planning** and the rest — every entry carries a verdict for production, not a benchmark score |
 | [`references/layers.md`](references/layers.md) | deciding **what your harness owns** — kernel, workbench and product layers, and why permission boundaries are usually somebody else's job |
 | [`references/audit.md`](references/audit.md) | reviewing **an agent system you did not build** — seven tracks, evidence tiers, and a prioritized plan |
+| [`references/pi.md`](references/pi.md) | you want the doctrine above as a **worked implementation** — Pi's sessions, compaction, config, skills, trust and containerization, each matched to the rule it implements, and the places it deliberately disagrees |
+| [`references/pi-sdk.md`](references/pi-sdk.md) | you are **embedding or extending** a harness — the SDK, the RPC protocol, JSON mode, and the eight extension seams where a permission gate, a context rewrite or a cost hook can actually live |
 
 **`scripts/audit_agent.py`** — the mechanical half of the audit. It finds what is visible
 without understanding intent (an unbounded loop, a tool with no description, a swallowed

package/plugins/agent-stack/skills/agent-harness/references/layers.md

@@ -62,6 +62,10 @@ surrounds it. Read as a weakness, it looks like a missing feature. Read as archi
 is a clear statement: *a harness that also claims to be a sandbox is claiming a guarantee it
 cannot keep*, because it runs in the same process as the code it would be confining.
 
+**Worked out in full in `pi.md` and `pi-sdk.md`** — the kernel layer read end to end, with
+each mechanism matched to the rule it implements and its divergences named. Use it as the
+concrete example when this file's abstractions need a body.
+
 Two consequences worth stating plainly:
 
 - **A harness advertising "safe tool execution" without an OS-level or container boundary is

package/plugins/agent-stack/skills/agent-harness/references/pi-sdk.md

@@ -0,0 +1,318 @@
+# Building on Pi — SDK, RPC, and the extension seams
+
+**Load this when:** embedding an agent in your own process, driving one from another
+language, or extending a harness — and you want a real API surface rather than a sketch.
+
+**Spec pinned:** `@earendil-works/pi-coding-agent`, `pi.dev/docs/latest` (sdk, rpc, json, extensions, custom-provider) · read 2026-08-15
+
+Read `pi.md` first for the harness itself. This file is the programmable half, and its
+value is the **seams**: the eight or so places a real harness lets you intervene, each
+matched to the rule it lets you implement.
+
+## Contents
+
+- Choosing a way in
+- The SDK
+- Custom tools
+- RPC: driving it from any language
+- JSON mode, and why it differs
+- The extension API
+- The seams that matter
+- Custom providers
+- Traps
+
+## Choosing a way in
+
+| You want | Use | Because |
+|---|---|---|
+| your process owns the loop, in Node | **SDK** | direct objects, no serialization |
+| to drive an agent from Python, Go, a UI | **RPC** | JSONL over stdin/stdout, bidirectional |
+| to consume a run's events, one shot | **JSON mode** | delta-only stream, linear in size |
+| a scripted answer | **print** | `pi -p` |
+| to change behaviour rather than call it | **an extension** | it runs inside the loop |
+
+**The distinction people get wrong:** RPC and JSON both emit events, but only RPC accepts
+commands. If you need to steer mid-run, it is RPC.
+
+## The SDK
+
+```bash
+npm install @earendil-works/pi-coding-agent
+```
+
+```javascript
+import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
+
+const modelRuntime = await ModelRuntime.create();
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  modelRuntime,
+});
+```
+
+**`AgentSession`** — `prompt(text, options?)`, `steer(text)` and `followUp(text)` to queue
+during streaming, `subscribe(listener)`, `setModel()`, `setThinkingLevel()`, `compact()`,
+`abort()`, `dispose()`.
+
+**Events** arrive structured:
+
+```javascript
+session.subscribe((event) => {
+  if (event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+```
+
+**`SessionManager`** factories decide persistence: `inMemory()`, `create(cwd)`,
+`continueRecent(cwd)`, `open(filePath)`. **`AgentSessionRuntime`** handles replacement —
+`newSession()`, `switchSession(path)`, `fork(entryId)`.
+
+**`createAgentSession()` options** worth knowing: `model` (from `@earendil-works/pi-ai`),
+`thinkingLevel` (`"off"` … `"max"`), `tools` (names to enable), `cwd`, `agentDir`
+(defaults `~/.pi/agent`), `resourceLoader`, `settingsManager`.
+
+**`ModelRuntime`** carries credentials and availability:
+
+```javascript
+const modelRuntime = await ModelRuntime.create({
+  allowModelNetwork: true,
+  modelRefreshTimeoutMs: 15_000,
+});
+await modelRuntime.setRuntimeApiKey("anthropic", "sk-key");
+const available = await modelRuntime.getAvailable();
+```
+
+Resolution: runtime overrides → `auth.json` → environment.
+
+**`DefaultResourceLoader`** discovers extensions, skills and prompts, and is where you
+override the system prompt for an embedded agent:
+
+```javascript
+const loader = new DefaultResourceLoader({
+  cwd: process.cwd(),
+  additionalExtensionPaths: ["/path/to/extension.ts"],
+  systemPromptOverride: () => "Custom system prompt",
+});
+await loader.reload();
+```
+
+**`allowModelNetwork` and `systemPromptOverride` are the two options an embedded agent
+almost always needs** — the first because a server should not discover models at runtime
+unless you meant it, the second because the default prompt is a coding agent's and yours
+probably is not.
+
+## Custom tools
+
+```javascript
+const myTool = defineTool({
+  name: "my_tool",
+  description: "Does something useful",
+  parameters: Type.Object({ input: Type.String() }),
+  execute: async (_id, params) => ({
+    content: [{ type: "text", text: `Result: ${params.input}` }],
+    details: {},
+  }),
+});
+```
+
+Passed as `customTools: [myTool]`. Built-ins: `read`, `bash`, `edit`, `write`, `grep`,
+`find`, `ls`.
+
+**`details` is not decoration.** It is how a tool result carries structured state into the
+session, and Pi's own guidance is to rebuild in-memory state after a restart by walking
+`ctx.sessionManager.getBranch()` and reading it. That is **structured note-taking**
+(`techniques.md`) with a durable home.
+
+Write the `description` to `tools.md`'s standard — this is the same field, and the same
+leverage.
+
+## RPC: driving it from any language
+
+```bash
+pi --mode rpc [--provider … --model … --name … --no-session --session-dir …]
+```
+
+JSON Lines over stdin/stdout: **commands** in, **responses** (`type: "response"`)
+acknowledging them, **events** streaming asynchronously.
+
+> **Framing warning, quoted because it bites in exactly one language at a time:** *"Split
+> records on `\n` only; accept optional `\r\n` input by stripping a trailing `\r`."* Some
+> standard line readers split on Unicode separators too, and a model that emits one inside
+> a string will then desynchronize your parser.
+
+**Commands**, by group:
+
+| Group | Commands |
+|---|---|
+| Prompting | `prompt`, `steer` (delivered after the current tool), `follow_up`, `abort` |
+| State | `get_state`, `get_messages`, `set_model`, `cycle_model`, `set_thinking_level`, `set_steering_mode`, `set_follow_up_mode` |
+| Sessions | `new_session`, `switch_session`, `fork`, `clone`, `get_session_stats`, `export_html`, `set_session_name` |
+| Execution | `bash`, `compact`, `set_auto_compaction`, `set_auto_retry` |
+| Introspection | `get_available_models`, `get_commands`, `get_fork_messages`, `get_entries`, `get_tree` |
+
+**Event lifecycle**, in order:
+
+```
+agent_start → turn_start → message_start → message_update* → message_end
+            → tool_execution_start → tool_execution_update* → tool_execution_end
+            → turn_end → agent_end → agent_settled
+```
+
+Plus `queue_update`, `compaction_start/end`, `auto_retry_start/end`,
+`bash_execution_update` (correlated by the command's `id`), and `extension_error`.
+
+**`agent_settled` is the one to wait on, not `agent_end`** — it means no further auto-retry
+is queued. A client that treats `agent_end` as final will occasionally act on a run that is
+about to continue.
+
+Message shapes are stable and worth matching: `UserMessage`, `AssistantMessage` (with
+`model`, `usage`, `stopReason`), `ToolResultMessage` (`toolCallId`, `toolName`, `isError`),
+`BashExecutionMessage` (`command`, `output`, `exitCode`, `cancelled`).
+
+**Extensions can ask the user something over RPC**, which is the part most integrations
+forget. `extension_ui_request` events carry `select`, `confirm`, `input`, `editor` and
+expect an `extension_ui_response` with the matching `id`; `notify`, `setStatus`, `setWidget`
+are fire-and-forget.
+
+```json
+{"type": "extension_ui_request", "id": "uuid-1", "method": "select", "title": "Choose", "options": ["A", "B"]}
+{"type": "extension_ui_response", "id": "uuid-1", "value": "A"}
+```
+
+**A client that ignores these hangs the agent** whenever an extension asks a question. Not
+implementing them is a decision; not knowing about them is an outage.
+
+## JSON mode, and why it differs
+
+`pi --mode json "…"` streams the same lifecycle, opening with a header:
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
+```
+
+**`message_update` records are delta-only** — they omit the cumulative `message` field and
+`assistantMessageEvent.partial` *"to keep stream size linear."* Consumers assemble text from
+`contentIndex` and `delta`.
+
+That is a deliberate trade: RPC gives you snapshots you can resync from, JSON gives you a
+stream that does not grow quadratically. **Pick JSON for pipelines, RPC for UIs.**
+
+## The extension API
+
+Auto-discovered from `~/.pi/agent/extensions/*.ts` (global), `.pi/extensions/*.ts`
+(project, after trust) or an `extensions` array in settings. A file, a directory with
+`index.ts`, or a package with its own `node_modules`.
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  // may be async — do initialization here, not resource startup
+}
+```
+
+**Registration surface:**
+
+```typescript
+pi.registerTool({ name, label, description, promptSnippet, promptGuidelines,
+                  parameters, prepareArguments?, execute, renderCall?, renderResult? })
+pi.registerCommand(name, { description, getArgumentCompletions?, handler })
+pi.registerProvider(name, config) / pi.unregisterProvider(name)
+pi.registerMessageRenderer / registerEntryRenderer / registerMarkdownTransformer
+pi.registerShortcut(shortcut, options) / pi.registerFlag(name, options)
+pi.on(eventName, handler) / pi.events.on|emit
+pi.getActiveTools() / getAllTools() / setActiveTools(names)
+pi.setModel(model) / getThinkingLevel() / setThinkingLevel(level)
+pi.sendMessage / sendUserMessage / appendEntry / setSessionName / setLabel
+pi.exec(command, args, options?)
+```
+
+**`promptSnippet` and `promptGuidelines` deserve attention**: a tool contributes not only a
+schema but a line to the system prompt and a set of guidelines. That is `system-prompt.md`'s
+*"tool policy belongs in the prompt"* built into the registration call, which is the right
+place for it — the policy cannot drift from the tool because they are declared together.
+
+**Context (`ctx`)** in every handler: `ui`, `mode` (`"tui" | "rpc" | "json" | "print"`),
+`hasUI`, `cwd`, `isProjectTrusted()`, `sessionManager`, `modelRegistry`, `model`,
+`thinkingLevel`, `signal`, `isIdle()`, `abort()`, `getContextUsage()`, `compact(options)`,
+`getSystemPrompt()`. Commands additionally get `newSession()`, `fork()`, `navigateTree()`,
+`switchSession()`, `waitForIdle()`, `reload()`.
+
+**`ctx.mode` and `ctx.hasUI` are how an extension stays honest** across surfaces: an
+extension that calls `ctx.ui.confirm()` unconditionally works in the TUI and hangs in a
+pipeline unless the client implements the UI sub-protocol.
+
+## The seams that matter
+
+Pi exposes ~30 events. These are the ones that let you implement doctrine this pack
+otherwise only describes:
+
+| Event | What it lets you do | Implements |
+|---|---|---|
+| **`tool_call`** — *can block* | refuse a call before it runs, per caller, per argument | the per-hop permission gate of `agent-orchestrator/references/governance.md`; track 6 of `audit.md` |
+| **`tool_result`** — *middleware chain* | rewrite, truncate or annotate a result; handlers see the previous handler's output | tool-output offload and token efficiency (`tools.md`) |
+| **`context`** | modify messages **before** the provider call | the compaction ladder's upper rungs, and typed carryover |
+| **`before_agent_start`** | inject a message, modify the system prompt | capability-aware prompt assembly (`system-prompt.md`) |
+| **`before_provider_headers` / `before_provider_request` / `after_provider_response`** | mutate headers, inspect or replace the payload, handle the response | provider routing, proxying and cost attribution |
+| **`session_before_compact` / `session_compact`** | decide what survives | *preserve decisions and open questions, not the discussion* |
+| **`input`** — *can intercept* | rewrite or absorb a user message | routing before the loop |
+| **`resources_discover`** | add skill/prompt/theme paths at runtime | dynamic capability |
+| **`project_trust`** | act on the trust decision | the delegation boundary of `layers.md` |
+
+**`tool_call` blocking is the single most important one for an audit.** It is where a
+per-tool, per-caller policy can actually live in a Pi-based system — so its absence is a
+finding, and its presence is where you read the policy.
+
+**Lifecycle discipline**, from Pi's own guidance and worth generalizing: start background
+resources in `session_start` and clean up in `session_shutdown`, **never from the factory**;
+after `/new`, `/resume` or `/fork` a fresh context arrives and **stale `ctx` objects must not
+be reused**; and tools that mutate files should use `withFileMutationQueue()` to avoid
+racing the built-ins.
+
+## Custom providers
+
+```typescript
+// route an existing provider through a proxy — baseUrl and/or headers only,
+// and the existing model list is preserved
+pi.registerProvider("anthropic", { baseUrl: "https://proxy.example.com" });
+
+// or a whole new one
+pi.registerProvider("my-llm", {
+  baseUrl: "https://api.my-llm.com/v1",
+  apiKey: "$MY_LLM_API_KEY",
+  api: "openai-completions",
+  models: [{
+    id: "my-llm-large", name: "My LLM Large", reasoning: true,
+    input: ["text", "image"],
+    cost: { input: 3.0, output: 15.0, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000, maxTokens: 16384,
+  }],
+});
+```
+
+For a non-standard API, implement `streamSimple`, pushing an `AssistantMessageEventStream`:
+start → content (text, thinking blocks, tool calls) → done or error, updating usage and cost.
+
+**The `cost` block is the hook for everything in
+`agent-orchestrator/references/llm-proxy-billing.md`.** A provider that declares its per-token
+cost makes attribution arithmetic rather than estimation — and a custom provider that omits
+it silently makes every downstream number a guess.
+
+Auth supports API keys with env interpolation, and OAuth with refresh, browser and
+device-code flows.
+
+## Traps
+
+- **Waiting on `agent_end` instead of `agent_settled`**, and acting on a run that continues.
+- **Ignoring `extension_ui_request`** in a non-TUI client, and hanging the first time an
+  extension asks a question.
+- **Splitting JSONL on anything but `\n`.** The docs warn about it; the failure is rare,
+  data-dependent and looks like corruption.
+- **Reusing a `ctx` after a session replacement.** It points at the old session.
+- **Starting background work in the extension factory** rather than `session_start`, so it
+  outlives the session and doubles on reload.
+- **Registering a custom provider with no `cost`**, then trusting the spend numbers.
+- **Assuming an extension is a boundary.** It runs in the Pi process, with the Pi process's
+  permissions — see `pi.md` → *trust*.

package/plugins/agent-stack/skills/agent-harness/references/pi.md

@@ -0,0 +1,241 @@
+# Pi — a harness you can read, and what each of its parts implements
+
+**Load this when:** you want a **worked example** of the harness doctrine, are choosing a
+kernel to build on, or are auditing a system built on Pi.
+
+**Spec pinned:** Pi (`@earendil-works/pi-coding-agent`, MIT, Earendil Inc.), `pi.dev/docs/latest` · read 2026-08-15
+
+**Why this file exists.** Everything else in this skill states a rule; Pi is small enough
+to read and complete enough to have made every one of those decisions in public. So each
+section below says **what Pi does** and then **which rule it is an instance of** — the
+value is in the second half. Where Pi disagrees with the doctrine, that is said too.
+
+This is not a substitute for `pi.dev`. It moves faster than this file; the stamp above is
+the honest boundary.
+
+## Contents
+
+- What Pi is, and the stance underneath it
+- Four ways to run it
+- Sessions are a tree, not a log
+- Compaction, with the actual numbers
+- Configuration and precedence
+- Skills, prompts and packages
+- Trust, and the deliberate absence of a sandbox
+- Containerization — three patterns, three threat models
+- Providers and credentials
+- Where Pi and this pack's doctrine differ
+- Traps
+
+## What Pi is, and the stance underneath it
+
+*"A minimal agent harness."* Its stated position is **primitives, not features**: it ships
+`read`, `write`, `edit`, `bash` and a loop, and deliberately omits sub-agents and plan mode,
+expecting you to build them as extensions.
+
+**This is the kernel layer of `layers.md`, made concrete.** The omissions are the argument:
+a kernel that shipped a plan mode would have chosen your planning shape for you. When
+comparing Pi against a workbench, remember the comparison is across layers and will not
+converge.
+
+## Four ways to run it
+
+| Mode | Invocation | For |
+|---|---|---|
+| **Interactive TUI** | `pi` | a human at a terminal |
+| **Print** | `pi -p "…"` | one shot, text out |
+| **JSON** | `pi --mode json "…"` | events as JSON lines, for another tool's UI |
+| **RPC** | `pi --mode rpc` | a long-lived subprocess you drive both ways |
+| **Embedded** | the SDK | your process owns the loop |
+
+**One agent, five front doors.** That separation — a core that does not know which surface
+is attached — is the same shape `agent-orchestrator` describes when it insists the loop
+must not know which provider answered. Details of the last three: `pi-sdk.md`.
+
+## Sessions are a tree, not a log
+
+Sessions persist to `~/.pi/agent/sessions/` as **JSONL, one entry per line**, each carrying
+an 8-character hex `id` and a `parentId`. The current position is a leaf; context is built
+by walking leaf→root.
+
+| Entry type | Holds |
+|---|---|
+| `session` | the header: `version` (currently **3**), `id`, `timestamp`, `cwd` |
+| `SessionMessageEntry` | a message with its role and content |
+| `ModelChangeEntry` / `ThinkingLevelChangeEntry` | mid-conversation switches, recorded rather than implied |
+| `CompactionEntry` | a summary, with an optional `retainedTail` |
+| `BranchSummaryEntry` | what an abandoned branch was about |
+| `CustomEntry` / `CustomMessageEntry` | extension data — the second participates in context, the first does not |
+
+Commands: `/tree` navigates within one file, `/fork` starts a new session from an earlier
+prompt, `/clone` duplicates the active branch, `/export` writes HTML, `/share` uploads a
+private gist. Flags: `pi -c` continues, `pi -r` browses, `--no-session` keeps nothing.
+
+**This implements `agent-orchestrator/references/runtime.md` → *time travel and forking*.**
+That file argues you must be able to fork a past checkpoint and debug **through the real
+loop** rather than a reconstruction. A parent-pointer tree is what makes that cheap: no
+copy, no replay, and the abandoned branch leaves a `BranchSummaryEntry` behind so the
+context is not simply lost.
+
+**Two design details worth stealing.** Model and thinking-level changes are *entries*, so a
+session explains its own cost curve. And the version field is honest about migration —
+v1 was linear, v2 introduced the tree, v3 unified role naming.
+
+## Compaction, with the actual numbers
+
+Auto-compaction fires when `contextTokens > contextWindow - reserveTokens`.
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `reserveTokens` | 16,384 | held back for the response |
+| `keepRecentTokens` | 20,000 | recent tail never summarized |
+
+Preserved messages run from `firstKeptEntryId` onward and are sent alongside the summary.
+`/compact [instructions]` runs it manually and the instructions steer the summary. Setting
+`"enabled": false` disables the automatic path while leaving the manual one.
+
+**Two caveats stated in the docs and worth carrying:** tool results are **truncated to 2,000
+characters** while summarizing, and a turn larger than `keepRecentTokens` produces two
+summaries that are then merged.
+
+**This is the ladder from `agent-orchestrator/references/context-engineering.md` with one
+rung.** Pi reserves, keeps a tail, and summarizes the rest. What that file adds and Pi
+leaves to you: clearing old tool results *before* paying a summarizer, offloading a large
+tool result to a file and keeping the path, and **typed carryover** — the observation that a
+summarizer keeps the discussion and drops the state. Pi's `BranchSummaryEntry` and
+`retainedTail` are the seams to hang that on.
+
+## Configuration and precedence
+
+| File | Scope |
+|---|---|
+| `~/.pi/agent/settings.json` | global |
+| `.pi/settings.json` | project — **overrides global, merging nested objects** |
+
+Keys cluster into model and thinking (`defaultProvider`, `defaultModel`,
+`defaultThinkingLevel`, `thinkingBudgets`), UI, network and retry (`retry` with `enabled`,
+`maxRetries`, `baseDelayMs`; `httpProxy`, `transport`, timeouts), content handling
+(`shellPath`, `npmCommand`, `defaultTools`), and resources (`packages`, `extensions`,
+`skills`, `prompts`, `themes`).
+
+**Merge, not replace, is the part that matters.** A project that wants one different model
+should not have to restate the whole file — and a harness that replaced wholesale would
+make every project config a copy that drifts.
+
+## Skills, prompts and packages
+
+**Pi implements the Agent Skills standard**, with progressive disclosure: at startup it
+scans skill locations and takes only `name` and `description` into the system prompt as XML;
+the full `SKILL.md` loads when a task matches.
+
+It discovers skills from `~/.pi/agent/skills/`, **`~/.agents/skills/`**, `.pi/skills/` and
+`.agents/skills/` (project paths only after the project is trusted), from packages, from a
+`skills` array in settings, and from `--skill <path>`.
+
+> **Concretely relevant here: `~/.agents/skills/` is the ssheleg hub.** On the machine this
+> file was written on, that directory holds 72 entries including every family skill, each
+> with the `name` and `description` front matter Pi requires — so the family is already in a
+> directory Pi reads. **Not verified by running Pi**, which is not installed here; this is a
+> statement about the path and the front matter, not an observation of a load.
+
+**Pi documents one deliberate divergence from the standard:** it allows a skill's `name` to
+differ from its directory, calling that rule *"suboptimal for shared skill directories used
+across multiple agent harnesses."* Which is exactly what `~/.agents/skills/` is. Note the
+asymmetry before relying on it — `make-skill`'s validator enforces the strict rule, so a
+skill built to Pi's leniency fails the family gate.
+
+**Prompt templates** are Markdown in `~/.pi/agent/prompts/*.md`; the filename becomes the
+command (`review.md` → `/review`). Front matter takes `description` and `argument-hint`
+(`<required>`, `[optional]`). Arguments substitute as `$1`, `$@` / `$ARGUMENTS`,
+`${1:-default}`, `${@:N}` and `${@:N:L}`. Discovery is **not recursive**.
+
+**Packages** bundle extensions, skills, prompts and themes over npm or git, declared under a
+`pi` key in `package.json` or by convention (`extensions/`, `skills/`, `prompts/`,
+`themes/`). Installed with `pi install npm:@foo/bar@1.0.0`, `git:…`, an https URL, or a
+path; `-l` writes to project settings for a team. Resource lists take globs with `!`
+exclusions, `[]` for none, `+path` / `-path` to force.
+
+## Trust, and the deliberate absence of a sandbox
+
+Pi *"runs with the permissions of the user account that starts it"* and treats files that
+user can write as inside the same trust boundary.
+
+**Project trust** is asked for when a repository carries `.pi/settings.json`, local
+extensions, skills, prompts or themes, a `.pi/SYSTEM.md` or `.pi/APPEND_SYSTEM.md`, or
+project agent skills in ancestor directories. Decisions persist in `~/.pi/agent/trust.json`.
+
+What it buys, in the docs' own words: it *"prevents a repository from silently changing pi's
+settings or extensions before you approve it"* — and explicitly **does not** protect against
+untrusted code, prompts, or model output.
+
+**There is no built-in sandbox, on purpose.** The stated reasons: a partial in-process
+sandbox creates false assumptions, real isolation needs an OS or container boundary, and Pi
+is meant to invoke project toolchains with full local access. And the sentence worth
+quoting to anyone who claims otherwise about any harness:
+
+> *"prompt injection from repository files, comments, documentation, context files, or build
+> output is expected local-agent risk and cannot be reliably prevented by pi."*
+
+**This is `layers.md` → *what a harness should delegate*, stated by the project itself.** A
+harness that also claimed to be a sandbox would be claiming a guarantee it cannot keep from
+inside the same process. **For an audit this changes the finding**: "no permission model" is
+not a defect here, it is a delegation — so audit what surrounds the process (`audit.md`,
+track 6).
+
+## Containerization — three patterns, three threat models
+
+| Pattern | Isolates | Credentials live |
+|---|---|---|
+| **Gondolin extension** | built-in tools and `!` commands, in a micro-VM | on the host — auth never enters the boundary |
+| **Plain Docker** | the whole Pi process | **inside the container** |
+| **OpenShell** | filesystem, process, network, credentials by policy | per policy; local or remote gateway |
+
+```bash
+docker run --rm -it -e ANTHROPIC_API_KEY -v "$PWD:/workspace" pi-sandbox
+```
+
+**The distinction that decides which you want: extensions execute wherever the Pi process
+runs.** Host-side Pi routing tools into a micro-VM keeps auth local and isolates execution;
+containerized Pi needs the key inside the boundary. Mounting `/root/.pi/agent` as a named
+volume keeps settings isolated — mounting your host directory *"exposes host auth and
+session files to the container"*, which is the opposite of the intent.
+
+## Providers and credentials
+
+Two paths: **subscription OAuth** via `/login` (ChatGPT Plus/Pro, Claude Pro/Max, GitHub
+Copilot, xAI, OpenRouter, Radius) with refresh handled, and **API keys**. 30+ providers.
+
+Resolution order — **CLI `--api-key` → `auth.json` → environment variable → custom provider
+keys in `models.json`**. `auth.json` is written `0600` and takes priority over the
+environment, which is the ordering you want: an explicit file beats an inherited variable.
+
+Keys support literals, `$ENV_VAR` interpolation, and shell commands
+(`!security find-generic-password …`) — so a key can live in a system keychain rather than a
+file. Registering a custom provider is `pi-sdk.md`.
+
+## Where Pi and this pack's doctrine differ
+
+Named rather than smoothed over:
+
+- **No iteration guard is documented as a first-class setting.** `agent-orchestrator` treats
+  a bounded loop as non-negotiable. Pi has `auto_retry` and abort; a max-iteration ceiling
+  is yours to add. Check this first when auditing a Pi-based system.
+- **No sub-agents.** Deliberate. `agent-orchestrator`'s sub-agent protocol and
+  `techniques.md`'s "distilled summary, never a transcript" are things you build here.
+- **Skill naming leniency** contradicts the standard `make-skill` enforces (above).
+- **Compaction is one rung**, not the ladder.
+
+None of these is a defect in a kernel. They are the difference between a harness and a
+platform, and they are the work you are signing up for.
+
+## Traps
+
+- **Reading the omissions as gaps.** They are the layer boundary. If you need all of them
+  filled, you wanted a workbench.
+- **Assuming trust means safety.** It means the repository did not silently change your
+  configuration. Nothing more, and the docs say so.
+- **Mounting your host `~/.pi/agent` into a container** and calling the result isolated.
+- **Building on skill-name leniency** and then failing a stricter harness's validator.
+- **Forgetting `keepRecentTokens` against a large turn.** One turn bigger than the budget
+  becomes two summaries merged — surprising if you are diffing summaries.
+- **Treating the docs here as current.** Check the stamp; Pi moves.