pi-petrroll 0.1.1 → 0.2.0

package/README.md

@@ -5,12 +5,13 @@ Small, focused extensions for [Pi](https://pi.dev). MIT licensed.
 | Extension | Command | Agent tool |
 | --- | --- | --- |
 | [Change directory](#change-directory) | `/cd <path>` | `change_directory` |
+| [External costs](#external-costs) | — | `add_cost` |
 
-One extension, one command, one tool. No skills, shell wrappers, or replacement built-in tools.
+Independent, focused extensions. No skills, shell wrappers, or replacement built-in tools.
 
 ## Install
 
-Requires **interactive Pi 0.85.1 or newer** (`@earendil-works/pi-coding-agent`); tested against 0.85.1. Earlier Pi versions may not rebuild cwd-bound services when switching sessions.
+Requires **Pi 0.85.1 or newer** (`@earendil-works/pi-coding-agent`); tested against 0.85.1. Change directory requires interactive mode; external cost recording works in all modes. Earlier Pi versions may not rebuild cwd-bound services when switching sessions.
 
 ```sh
 pi install npm:pi-petrroll
@@ -46,7 +47,7 @@ All extensions load by default. To load only `cd`, including after future update
 }
 ```
 
-Disabling `cd` disables both `/cd` and its `change_directory` tool.
+Disabling `cd` disables both `/cd` and its `change_directory` tool. Disabling `cost` disables `add_cost`. To load only cost recording, use `"extensions": ["extensions/cost/index.ts"]` in the package entry above.
 
 ## Change directory
 
@@ -100,6 +101,27 @@ Manual `/cd` switches without starting another model response; the agent tool re
 - The copied history can contain references to the old project. A visible context message records the change, and the new system prompt contains the destination's instructions.
 - Switching reloads project extensions according to Pi's trust policy. Install only code you trust.
 
+## External costs
+
+After launching a subagent with the ordinary `bash` tool, Pi can call `add_cost` to include the subagent's reported cost in the **current session's native cost total**:
+
+```json
+{
+  "amount": 0.0375,
+  "reason": "Bash-launched review subagent, run review-123"
+}
+```
+
+- `amount` is an additional, finite, non-negative cost in **USD**, not cents. Zero is allowed.
+- `reason` is a required, non-blank description (up to 1000 characters), saved with the tool result for an audit trail.
+- Costs appear in Pi's footer, `/session`, and RPC session statistics. Pi stores them as tool-result usage, so they survive reload/resume and compaction without inventing token counts or changing the parent model's usage.
+- Works in interactive, print, JSON, and RPC modes, including in-memory sessions. `--no-session` costs exist only for that process.
+- This is accounting only: the tool does not launch anything, inspect subagent output, estimate pricing, or charge money. The agent must obtain the cost from the external run first.
+
+**Every successful call is additive; there is no deduplication.** Report each external cost once. For a continued subagent, report only the new, unrecorded cost—not its cumulative lifetime total. Do not report parent-session model costs or nested usage already returned by another tool. If the external cost is unknown, do not guess.
+
+Pi's totals include all entries in the session file, including abandoned branches. Forked or copied sessions inherit costs present in their copied history; a new empty session starts at zero. No session files or Pi internals are patched.
+
 ## Development
 
 ```sh
@@ -108,15 +130,17 @@ npm run check
 npm test
 ```
 
-Tests cover path handling, copy/branch preservation, cancellation, aborts, concurrency, and a real Pi runtime handoff with a fake model stream. The runtime test verifies that tool results are copied, `read` and `bash` use the new cwd, destination `AGENTS.md` replaces source context, and the agent continues. Tests do not call a model API or use your credentials.
+Tests cover cost validation, native cost accumulation, persistence/resume, compaction, path handling, copy/branch preservation, cancellation, aborts, concurrency, and a real Pi runtime handoff with a fake model stream. The runtime test verifies that tool results are copied, `read` and `bash` use the new cwd, destination `AGENTS.md` replaces source context, and the agent continues. Tests do not call a model API or use your credentials.
 
 ```text
 extensions/
   cd/
     index.ts
-  # Add another-extension/index.ts here.
+  cost/
+    index.ts
 tests/
   cd.test.ts
+  cost.test.ts
   runtime.test.ts
 ```
 

package/extensions/cost/index.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+
+export const addCostParameters = Type.Object({
+  amount: Type.Number({ minimum: 0, description: "Additional cost in USD (not cents or a cumulative session total)." }),
+  reason: Type.String({ minLength: 1, maxLength: 1000, description: "What incurred this cost, e.g. the bash-launched subagent task or run ID." }),
+});
+
+export type AddCostInput = Static<typeof addCostParameters>;
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "add_cost",
+    label: "Add Cost",
+    description:
+      "Add an external cost in USD to the current Pi session's native cost total. " +
+      "Use after external work such as a subagent launched via bash reports its cost. " +
+      "Every successful call adds the amount again; report only the unrecorded cost, never a cumulative total or costs Pi already accounts for. " +
+      "This records accounting only: it does not run a subagent or charge money.",
+    promptSnippet: "Record external costs in the current session total",
+    promptGuidelines: [
+      "Use add_cost after bash-launched subagents or other external work report a cost in USD. Do not guess costs or double-count costs already recorded by Pi or a previous add_cost call.",
+    ],
+    parameters: addCostParameters,
+    async execute(_toolCallId, { amount, reason }, signal) {
+      signal?.throwIfAborted();
+      // Validate here too: tool_call hooks can mutate arguments after schema validation.
+      if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) {
+        throw new Error("amount must be a finite, non-negative cost in USD.");
+      }
+      if (typeof reason !== "string" || !reason.trim() || reason.length > 1000) {
+        throw new Error("reason must be non-blank and at most 1000 characters.");
+      }
+      const description = reason.trim();
+      return {
+        content: [{ type: "text", text: `Added $${amount} USD to this session's cost: ${description}` }],
+        details: { amount, currency: "USD", reason: description },
+        // Pi persists tool-result usage and includes it in footer, /session, and
+        // RPC totals, including after compaction. No fabricated token counts or
+        // attribution to the parent model's input/output pricing categories.
+        usage: {
+          input: 0,
+          output: 0,
+          cacheRead: 0,
+          cacheWrite: 0,
+          totalTokens: 0,
+          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: amount },
+        },
+      };
+    },
+  });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-petrroll",
-  "version": "0.1.1",
-  "description": "Small, focused Pi extensions by petrroll: change projects without leaving your session.",
+  "version": "0.2.0",
+  "description": "Small, focused Pi extensions by petrroll: switch projects and track external costs in your session.",
   "type": "module",
   "license": "MIT",
   "author": "Petr Houška (petrroll)",