@cydm/pie 2.7.0 → 2.7.2

package/README.md

@@ -83,7 +83,7 @@ Required model fields:
 
 - `id`
 - `input`
-- `cost`
+- `cost` (`input`, `output`, `cacheRead`, `cacheWrite`; optional `cacheWriteLong`)
 - `contextWindow`
 - `maxTokens`
 
@@ -104,6 +104,22 @@ pie models init --stdout
 
 For editor auto-complete and validation, you can also point the optional `"$schema"` field in your local `models.json` at your installed `@cydm/pie/models.schema.json` file.
 
+`cost` may additionally carry `cacheWriteLong` — the per-million-token rate for 1h-TTL cache writes on providers that report a TTL breakdown (Anthropic-style routes). It is optional; legacy configs without it keep working. When it is absent, long writes are priced at the Anthropic 2x-input estimate and the calculated cost is marked `cacheWriteLongEstimated` so it is not presented as a precise provider bill.
+
+### Settings
+
+`~/.pie/settings.json` (or `./.pie/settings.json` for project scope) holds CLI defaults. Relevant prompt-cache keys:
+
+```jsonc
+{
+  // Explicit Anthropic prompt-cache TTL: "none" | "short" | "long".
+  // Absent keeps the provider default (Anthropic: short/5m).
+  "promptCacheRetention": "short"
+}
+```
+
+Priority is **per-request option > CLI setting > provider default**. The setting is forwarded only on Anthropic prompt-cache routes; it never forces OpenAI-compatible `store` or another provider's cache mode. Pie does not auto-switch TTL from observed hit rates — choose `long` explicitly when the 1h write premium is worth it.
+
 ### Remote model catalogs
 
 Pie can add centrally managed models without replacing local profiles or defaults. Add a catalog to `~/.pie/models.json` and keep the virtual key in an environment variable:

package/dist/builtin/extensions/ask-user/index.js

@@ -1,9 +1,9 @@
 import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
 import {
   createAskUserCapability
-} from "../../../chunks/chunk-6RBSTII7.js";
-import "../../../chunks/chunk-TWILEFLD.js";
-import "../../../chunks/chunk-R5I2QLF2.js";
+} from "../../../chunks/chunk-65B6P5J5.js";
+import "../../../chunks/chunk-GZDAIW6F.js";
+import "../../../chunks/chunk-BRFP5WZ6.js";
 import "../../../chunks/chunk-XXGYUYXI.js";
 import "../../../chunks/chunk-LZQXQOPJ.js";
 

package/dist/builtin/extensions/plan-mode/index.js

@@ -7,9 +7,9 @@ import {
   isPlanModeSafeCommand,
   markCompletedPlanSteps,
   restoreExecutionState
-} from "../../../chunks/chunk-6RBSTII7.js";
-import "../../../chunks/chunk-TWILEFLD.js";
-import "../../../chunks/chunk-R5I2QLF2.js";
+} from "../../../chunks/chunk-65B6P5J5.js";
+import "../../../chunks/chunk-GZDAIW6F.js";
+import "../../../chunks/chunk-BRFP5WZ6.js";
 import {
   Type
 } from "../../../chunks/chunk-XXGYUYXI.js";

package/dist/builtin/extensions/subagent/index.js

@@ -1,14 +1,16 @@
 import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
 import {
-  createCliHostCapabilities
-} from "../../../chunks/chunk-IPNAFMOJ.js";
+  createCliHostCapabilities,
+  formatTransportLifecycle,
+  logTransportLifecycle
+} from "../../../chunks/chunk-GECAIKZL.js";
 import {
   SUBAGENT_SESSION_RECORD_VERSION,
   createSharedFileSystemTools,
   createSubagentCapability
-} from "../../../chunks/chunk-6RBSTII7.js";
-import "../../../chunks/chunk-TWILEFLD.js";
-import "../../../chunks/chunk-R5I2QLF2.js";
+} from "../../../chunks/chunk-65B6P5J5.js";
+import "../../../chunks/chunk-GZDAIW6F.js";
+import "../../../chunks/chunk-BRFP5WZ6.js";
 import "../../../chunks/chunk-XXGYUYXI.js";
 import "../../../chunks/chunk-LZQXQOPJ.js";
 
@@ -392,6 +394,14 @@ function subagentExtension(ctx) {
     log: (message) => ctx.log(message),
     notify: ctx.hasUI ? (message, type) => ctx.ui.notify(message, type === "success" ? "info" : type) : void 0,
     debugLog: (module, message, data) => ctx.log(`[subagent:${module}] ${message}${data !== void 0 ? ` ${JSON.stringify(data)}` : ""}`),
+    // Body-free Responses transport timeline for CHILD agents: 5 of the 7
+    // incident failures happened inside subagents with no transport record.
+    onTransportLifecycle: (event) => {
+      logTransportLifecycle(event);
+      if (event.phase === "timeout" || event.cleanupOutcome === "request_abandoned") {
+        ctx.log(formatTransportLifecycle(event));
+      }
+    },
     resolveModelClass: (modelClass) => ctx.resolveModelClass?.(modelClass),
     resolveModelRef: (modelRef) => ctx.resolveModelRef?.(modelRef),
     createRuntimeTools: (mode) => {

package/dist/builtin/extensions/todo/index.js

@@ -8,9 +8,9 @@ import {
   executeManageTodoList,
   executionStateToTodos,
   restoreExecutionState
-} from "../../../chunks/chunk-6RBSTII7.js";
-import "../../../chunks/chunk-TWILEFLD.js";
-import "../../../chunks/chunk-R5I2QLF2.js";
+} from "../../../chunks/chunk-65B6P5J5.js";
+import "../../../chunks/chunk-GZDAIW6F.js";
+import "../../../chunks/chunk-BRFP5WZ6.js";
 import "../../../chunks/chunk-XXGYUYXI.js";
 import "../../../chunks/chunk-LZQXQOPJ.js";
 

package/dist/builtin/skills/computer-use-axi/SKILL.md

@@ -15,7 +15,47 @@ node <baseDir>/computer-use-axi-cli.js <command> [options]
 
 Desktop control is a last resort — prefer API/CLI/web tools when they suffice.
 First use on macOS installs the `pie-computer-use.app` helper; the CLI then
-asks you to grant it Accessibility and Screen Recording permissions.
+reports missing Accessibility and Screen Recording permissions. Use the real
+non-TUI setup flow (the user grants toggles in macOS Settings):
+
+```bash
+node <baseDir>/computer-use-axi-cli.js permissions setup
+# User enables pie-computer-use.app in both Settings panes.
+node <baseDir>/computer-use-axi-cli.js permissions recheck
+```
+
+Setup registers the helper and opens missing panes; recheck restarts the helper
+and probes permissions. Missing grants exit 1. Both require an idle broker;
+recheck expires old observations, so run `roots`/`observe` again afterward.
+Starting Pie in interactive mode is not a substitute for this flow.
+
+## How it runs
+
+The CLI is a short-lived client. A local **broker** owns the execution engine,
+native helper handles, observation state, resource scheduling, `@o` output
+refs, and image artifacts. The broker starts on demand, is shared by every Pie
+session on this desktop, and exits after 30 minutes with no in-flight or
+unconfirmed work. It is not a system service and opens no network listener
+(Unix socket on macOS/Linux, per-user named pipe on Windows).
+
+```bash
+node <baseDir>/computer-use-axi-cli.js status   # broker pid/generation/queues
+node <baseDir>/computer-use-axi-cli.js stop     # safe shutdown, owns only its processes
+```
+
+A broker restart creates a new generation. State ids from the old generation
+are reported as expired; they are never restored or replayed — run `roots` and
+`observe` again. Request-ID deduplication is generation-scoped: retrieve a
+result with `--request-id ID --generation G` using its original generation.
+`request_id_expired` refuses replay after result eviction; `request_ledger_full`
+refuses fresh work until a safe stop/new generation. Never replay old actions
+to recover from either error.
+
+`stop` is a safe drain, not a hard kill. While a native action is still
+settling, the stopping broker keeps its endpoint bound and rejects new
+connections with `broker_draining`; a bootstrapping broker waits for that
+drain instead of starting a second execution authority. Retry shortly after a
+`broker_draining` rejection rather than racing another broker.
 
 ## Current guidance lives in the CLI
 
@@ -50,10 +90,35 @@ node <baseDir>/computer-use-axi-cli.js act --state S1 --actions '[{"action":"pre
 - States are stale-checked by epoch: acting twice from one stateId fails the
   second time by design — consume the successor stateId the act output names.
 - `@oN` refs continue long truncated output: `read --ref @o1 --offset N`
-  (byte offsets; no `--state` needed for `@o`).
+  (byte offsets; no `--state` needed for `@o`). The broker allocates these.
 - `pictureOnly` nodes have no semantic element: coordinate actions only, and
   only from an image-bearing (visual) state.
 
+## Image evidence
+
+Visual observations do not print base64. The broker writes the original
+screenshot to a private file (`0700` directory, `0600` file under the Pie
+config directory) and the text result names its absolute path, dimensions,
+sha256, broker generation, and owning `stateId`.
+
+When the result includes an `Image evidence:` line, call the normal
+`read_file` tool on that absolute path before using coordinates. The image
+belongs only to the returned `stateId`: after acting, use the successor
+image/state, not the old one. Artifacts are evicted with their state; if the
+file is gone, observe again instead of guessing coordinates. The broker never
+scales or transforms the bytes it stores.
+
+## Owners and concurrency
+
+The Pie host passes an opaque owner identity into the shell; separate sessions
+have separate observations, `@o` refs, and artifact directories. Manual CLI
+use without that environment resolves to a stable `standalone` namespace.
+Owners are **not** an OS security boundary — every client is the same local
+user. Two owners acting on the same app/page share one resource lane and one
+epoch counter, so the second write is rejected as stale rather than
+overlapping. `status` reports only an owner **count** and non-reversible
+fingerprints; it never prints another session's owner id.
+
 ## Acting and batching
 
 ```bash
@@ -82,6 +147,15 @@ node <baseDir>/computer-use-axi-cli.js act --state S1 --actions '[
   `node <baseDir>/scripts/setup-helper.mjs` once, grant the permissions, and
   retry.
 
+## Uncertain outcomes
+
+If a command returns `Outcome unknown` (the client timed out or lost the
+broker connection after dispatch), the native action may already have run.
+Do **not** replay it. The broker keeps that resource lane occupied until the
+native helper confirms completion; run `observe` to establish a successor
+state and decide from there. Reusing the same `--request-id` retrieves the
+original result (or `in-flight`/`outcome-unknown`); it never dispatches again.
+
 ## Browser pages
 
 ```bash
@@ -95,9 +169,20 @@ states. Native browser windows are ordinary desktop UI — use `roots`/
 `observe`/`act` on them. Browser control may need enabling via the
 computer-use config (`browser_use`).
 
+## Test-only backend
+
+The deterministic fake desktop backend used by the broker test suite is not
+shipped in release bundles. In a source checkout it activates only when both
+`PIE_COMPUTER_USE_FAKE_BACKEND=1` and
+`PIE_COMPUTER_USE_ENABLE_TEST_COMMANDS=1` are set; otherwise the setting is
+ignored with a warning and the real platform backend is used. Never rely on it
+for real UI work.
+
 ## Output bounds and exit codes
 
 Model-facing output is capped (~48 KiB / 2 000 lines); oversized results
 return a preview plus an `@o` continuation ref. Exit codes: `0` ok, `1` tool
-error (message on stderr), `2` usage error. `--json` wraps
-`{ content, details, isError }` for programmatic use.
+or broker error (message on stderr), `2` usage error, `3` broker
+version/generation mismatch (run `stop`, then retry). `--json` wraps
+`{ content, details, isError }` for programmatic use; `--request-id` makes a
+retry idempotent.