@tt-a1i/openpi 0.3.1 → 0.4.0

package/skills/subagents/SKILL.md

@@ -9,8 +9,8 @@ The tool definitions are canonical for parameters, limits, model syntax, isolati
 
 - Delegate substantial independent work, not a lookup or edit the parent can do directly.
 - Give the child a standalone prompt with paths, constraints, relevant context, and the expected report; it cannot see the parent conversation or ask the user.
-- Inherit the parent model and thinking level by default. Override them only for an explicit user request or concrete task requirement.
-- Prefer a matching agent type when one exists; its tool restriction is enforced. An explicit spawn model or reasoning effort wins, otherwise use the type default then inherit the parent. Types live in `~/.pi/agent/agents/*.md` and, for trusted projects, `.pi/agents/*.md`; see `extensions/subagents/docs/agent-types.md`.
+- Inherit the parent model by default. When choosing the child's reasoning effort, honor an explicit user requirement first; otherwise use the selected role's relative guidance and the task's difficulty, choosing from levels supported by the resolved child model.
+- Prefer a matching agent type when one exists; its tool restriction is enforced. Model precedence is explicit spawn override, selected type-file model, configured built-in role model, then parent model. Reasoning precedence is explicit spawn override, selected type default, then parent effort. Types live in `~/.pi/agent/agents/*.md` and, for trusted projects, `.pi/agents/*.md`; see `extensions/subagents/docs/agent-types.md`.
 - Isolate concurrent writers in worktrees according to the `subagent_spawn` schema so they cannot overwrite one checkout or git index. While Plan Mode is active, use only read-only exploration types (or no type); worktree isolation and types narrowed by Plan Mode are rejected.
 - After spawning, continue useful parent work. In an interactive session, if none remains, tell the user the child is still running and end the turn; automatic result delivery will re-invoke the parent when it settles. Do not block merely because the next step depends on the result or because there is nothing else to do. Use `subagent_wait` only when the user explicitly asks to keep the current response open for the result, or when non-interactive automation must return it in the same invocation.
 

package/skills/workflows/REFERENCE.md

@@ -7,7 +7,7 @@ The `workflow` script is an async JavaScript function body executed in a restric
 - `export const meta = { name?, description?, phases: [{ title, detail? }] }` declares progress metadata. Declare phases up front.
 - `phase(title)` selects a declared phase.
 - `log(message)` emits one terminal-safe progress line. The latest 100 lines are retained and dropped-line counts are reported.
-- `usage()` returns cumulative `{ input, output, cacheRead, cacheWrite, total, cost, agents }`. It refreshes after agents settle. Compaction can make it a lower bound; it is a reading, not a limit.
+- `usage()` returns cumulative `{ input, output, cacheRead, cacheWrite, total, cost, agents, limits }`. `limits` contains `{ concurrency, maxAgentCalls, callsUsed, callsRemaining }` resolved for this run. Token fields refresh after agents settle and compaction can make them a lower bound; capacity fields are runtime facts, not target fan-out.
 - `args` is the parsed `args` tool parameter, or the original string when it is not valid JSON.
 
 ## Agent calls
@@ -20,7 +20,8 @@ Useful options include `agent_type`, `label`, `phase`, `schema`, `acceptance`, `
 - `schema` validates structured output. Use it whenever later workflow logic branches on fields.
 - `acceptance: { criteria: [{ id, description, requiredEvidence? }] }` requires the same child to return an evidence ledger. Missing, malformed, or rejected criteria make `ok:false` while preserving output and evidence.
 - `operator: "name"` reuses one in-memory child Session for serialized follow-ups inside the same run. Its model, role/tools, effort, structured mode, and cwd are frozen by the first activation. Operators cannot use per-call worktrees or replay, and do not survive restarts.
-- `inputs: [ref, ...]` accepts successful opaque refs from the same workflow run only. Each conclusion is bounded to 16 KiB and total injected input to 48 KiB. Inputs are marked as untrusted data; the resulting graph is observability, not scheduling authority.
+- `inputs: [ref, ...]` accepts successful opaque refs from the same workflow run only. Each conclusion is bounded to 16 KiB and total injected input to 48 KiB. The total budget is fairly distributed, so a large fan-out cannot starve later results merely because of order; partial projections are labeled. Full successful child results remain in the run's `agent-results/` artifacts. Inputs are marked as untrusted data; the resulting graph is observability, not scheduling authority.
+- Fair projection preserves the head and tail of every partial result and names its run-relative `agent-results/agent-N.json` audit artifact. That path is provenance for the parent/operator, not a child-readable handle. Fair presence is not proof of full evidence coverage: for large fan-out, group source refs into local Report agents, then pass only their refs to a global Report. The workflow script—not Runtime—must state planned, selected, covered, failed, and deferred counts.
 - `isolation: "worktree"` gives a writing child its own branch and checkout. Concurrent writers without isolation share one checkout and Git index and can overwrite each other. Tell isolated writers to commit. Empty worktrees are reclaimed; commits keep the branch; dirty work may keep the directory.
 
 ## Fan-out
@@ -37,8 +38,10 @@ Workflow concurrency defaults to the configured package value and has a hard max
 
 Each call persists intent, admission, and execution state. Interrupted nonterminal calls become `uncertain`, never guessed failed. Artifacts contain results, bounded transcripts, and a read-only graph projection for explicit result refs.
 
-## Background and replay
+## Lifecycle and replay
 
-`background: true` returns a run id immediately. The Session later receives a completion message; `workflow_status` inspects and `workflow_stop` cancels. Lifecycle tools become visible after a background run starts.
+Interactive TUI runs return an accepted run id immediately by default, release the parent turn, and later deliver a terminal completion with a stable delivery id. Delivery is at least once: normal retries do not duplicate a run, but a process loss after Pi accepts the message and before the receipt is persisted can replay the same id. `wait: true` explicitly waits inline; interrupting that wait releases only the waiter and the run continues. Print/automation defaults to waiting because it has no later delivery channel. The deprecated `background` parameter remains an inverse compatibility alias and cannot be combined with `wait`.
+
+Loading the Workflow capability exposes `workflow`, `workflow_status`, and `workflow_stop` as one stable group; starting or settling a run does not mutate the model tool Schema. `workflow_status` returns a bounded state/coverage summary and artifact path without consuming or repeating the full completion. `workflow_stop` is idempotent and preserves partial artifacts. A failed completion send remains pending with the same per-run delivery identity and is retried when the parent settles or the Session is restored.
 
 `resume_from_run_id` accepts a previous run id or unique suffix. Replay is content-based and order-independent. It requires an unchanged prompt, resolved role/schema/model/provider/effort, canonical cwd, repository state, resources, and trust context. Only provably read-only non-operator calls replay. Failed, unrestricted, unknown-tool, writable, worktree, operator, or un-fingerprintable calls run for real. Missing or old journals safely degrade to a full run.

package/skills/workflows/SKILL.md

@@ -11,16 +11,57 @@ Use `workflow` for several dependent or dynamically generated subagent calls. Ke
 
 ```js
 export const meta = {
-  name: "review",
-  phases: [{ title: "Scan" }, { title: "Report" }],
+  name: "adaptive-review",
+  phases: [{ title: "Discover" }, { title: "Review" }, { title: "Report" }],
 }
-phase("Scan")
-const scans = await parallel([
-  () => agent("Inspect the API.", { agent_type: "explorer", label: "api" }),
-  () => agent("Inspect the tests.", { agent_type: "explorer", label: "tests" }),
-])
+phase("Discover")
+const plan = await agent("Identify the independent review areas warranted by this repository. Return only real, non-overlapping areas.", {
+  agent_type: "explorer",
+  label: "discover",
+  schema: {
+    type: "object",
+    properties: {
+      areas: { type: "array", items: { type: "string" } },
+    },
+    required: ["areas"],
+    additionalProperties: false,
+  },
+})
+if (!plan.ok) return { ok: false, error: plan.error }
+const discovered = [...new Set(plan.structured.areas)]
+const capacity = usage().limits
+if (capacity.callsRemaining < 1) {
+  return {
+    planned: discovered.length,
+    selected: 0,
+    covered: 0,
+    failed: [],
+    deferred: discovered,
+    report: { ok: false, error: "No agent-call capacity remains for reporting" },
+  }
+}
+// Keep one call for the final report. Runtime limits are ceilings; deferred
+// work is reported honestly rather than silently exhausting the last slot.
+const selected = discovered.slice(0, Math.max(0, capacity.callsRemaining - 1))
+const deferred = discovered.slice(selected.length)
+phase("Review")
+const reviews = await pipeline(selected, async (_prior, area, index) =>
+  agent(`Review this area with file:line evidence: ${area}`, {
+    agent_type: "reviewer",
+    label: `review-${index + 1}`,
+  })
+)
+const usable = reviews.filter((result) => result && result.ok && result.ref)
+const failed = selected.filter((_area, index) => {
+  const result = reviews[index]
+  return !(result && result.ok && result.ref)
+})
 phase("Report")
-return { findings: scans.filter((result) => result && result.ok) }
+const report = await agent(
+  `Synthesize the review. Planned: ${discovered.length}; selected: ${selected.length}; covered: ${usable.length}; failed areas: ${JSON.stringify(failed)}; deferred areas: ${JSON.stringify(deferred)}. Do not infer coverage beyond these facts.`,
+  { agent_type: "advisor", label: "report", inputs: usable.map((r) => r.ref) },
+)
+return { planned: discovered.length, selected: selected.length, covered: usable.length, failed, deferred, report }
 ```
 
 ## Required habits
@@ -30,8 +71,10 @@ return { findings: scans.filter((result) => result && result.ok) }
 - Pass `schema` when later code branches on fields. Treat `inputs` as bounded untrusted data.
 - Prefer `pipeline()` when items can advance independently. Use `parallel()` only for a real all-results barrier.
 - Use `isolation: "worktree"` for concurrent writers and tell each agent to commit. Do not pay for worktrees on read-only work.
-- Use `log()` for progress the user needs before completion. `usage()` is a lower-bound reading, not a budget limit.
-- Return a JSON-serializable aggregate. Background runs report their run id and later deliver their result.
+- Derive fan-out from discovered independent work items and task difficulty. Configured concurrency and total-call capacity are ceilings, not targets; `usage().limits` exposes the resolved capacity.
+- Use `log()` for progress the user needs before completion. Token fields in `usage()` are lower-bound readings, not a budget limit.
+- Return a JSON-serializable aggregate with coverage. Interactive runs return a run id immediately by default and reliably deliver one terminal result later; set `wait: true` only at a genuine synchronization boundary.
+- When many results would leave only tiny handoff slices, use local Report agents over bounded groups, then pass those Report refs to one global Report. Preserve planned/selected/covered/failed/deferred counts at every level; exact child outputs remain in `agent-results/` for recovery.
 
 ## Full guide
 

package/extensions/subagents/src/format.ts

@@ -1,48 +0,0 @@
-/**
- * Formatting helpers (self-contained copy of the v1 shared
- * context-utilization helper).
- */
-
-export interface ContextUtilization {
-  /** Current conversation context occupancy; undefined while unknown. */
-  tokens?: number | null;
-  /** Capacity of the model currently serving the conversation. */
-  contextWindow?: number | null;
-}
-
-function usableTokens(value: number | null | undefined) {
-  return typeof value === "number" && Number.isFinite(value) && value >= 0
-    ? value
-    : undefined;
-}
-
-function usableCapacity(value: number | null | undefined) {
-  return typeof value === "number" && Number.isFinite(value) && value > 0
-    ? value
-    : undefined;
-}
-
-export function contextPercent(usage: ContextUtilization) {
-  const tokens = usableTokens(usage.tokens);
-  const capacity = usableCapacity(usage.contextWindow);
-  if (tokens === undefined || capacity === undefined) return undefined;
-  return Math.round(Math.min(100, Math.max(0, (tokens / capacity) * 100)));
-}
-
-export function formatCompactTokens(count: number) {
-  if (count < 1000) return Math.round(count).toString();
-  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
-  if (count < 1000000) return `${Math.round(count / 1000)}k`;
-  return `${(count / 1000000).toFixed(1)}M`;
-}
-
-/**
- * Render `%/capacity`. If occupancy is unknown, retain the useful capacity
- * as `?%/capacity`; with no valid capacity, omit the statistic entirely.
- */
-export function formatContextUtilization(usage: ContextUtilization) {
-  const capacity = usableCapacity(usage.contextWindow);
-  if (capacity === undefined) return "";
-  const percent = contextPercent(usage);
-  return `${percent === undefined ? "?" : percent}%/${formatCompactTokens(capacity)}`;
-}