killeros 1.4.1 → 1.4.3

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to KillerOS are documented here.
 
+## [1.4.3] - 2026-08-01
+
+### Fixed
+
+- Added child-runtime tool budgets for read-only roles, with a soft finalization nudge and hard blocking for read and web tools after 32 calls.
+- Added bounded child report instructions and kept read-tool budgets cumulative across steering restarts.
+- Lowered the default child quota to 250,000 tokens and $5, and exposed child tool-call counts in results.
+
+## [1.4.2] - 2026-08-01
+
+### Added
+
+- Added named child threads with inspectable lifecycle state, Active/Done views, steering, interruption, collection, and closure controls.
+- Added isolated child-process resource guards for wall time, JSONL lines, retained trace, stderr, output, token quota, cost quota, task count, and concurrency.
+
+### Changed
+
+- Replaced routine child turn limits with natural completion plus named resource guards.
+- Preserved partial traces and handoffs when a child fails, stops, or reaches a limit.
+
 ## [1.4.1] - 2026-08-01
 
 ### Added

package/README.md

@@ -33,7 +33,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.1
+  pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.3
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -47,7 +47,7 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 - Responsive footer with polished model/provider identity, plain-language context, and active goal state remaining; reasoning, Git branch, elapsed time, cost, and path cut down by available width
 - `/variants` selector and direct reasoning-level arguments
 - Codex-style `/goal` for durable long-running objectives with pause, resume, edit, clear, automatic continuation, and explicit completion
-- Pi-native `subagent` tool with isolated child processes, Markdown roles, explicit read/write boundaries, parallel readers, one serialized writer, bounded output, and cancellation propagation
+- Pi-native `subagent` tool with named, inspectable child threads, Markdown roles, explicit read/write boundaries, parent controls, bounded resources, and cancellation propagation
 - Claude Code-style `/init` that scans the repository and generates a concise root `AGENTS.md` without setup questions
 - `question` tool with filtering, proposal previews, keyboard selection, custom answers, history, cancellation, and resize-safe rendering
 - Mid-prompt slash completion with current Pi `0.82.1` commands, extensions, prompts, and skills
@@ -95,7 +95,7 @@ KillerOS ships `planner`, `reviewer`, `scout`, and `security` as read-only roles
 2. Personal: `~/.pi/agent/agents/*.md`
 3. Trusted project: `<repo>/.pi/agents/*.md`
 
-The default `agentScope: "user"` uses bundled and personal roles. Use `"project"` or `"both"` to opt into trusted project roles; a selected project override requires interactive confirmation. Role frontmatter requires `name`, `description`, `access`, and an explicit `tools` list. Optional fields are `model`, `thinking`, `maxTurns`, and `timeoutMs`. Every bundled role shows `model: inherit` and `thinking: inherit` as editable placeholders. Replace them with an available `provider/model` and a separate thinking level when you want to pin a role; `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` are checked against that model’s supported capabilities.
+The default `agentScope: "user"` uses bundled and personal roles. Use `"project"` or `"both"` to opt into trusted project roles; a selected project override requires interactive confirmation. Role frontmatter requires `name`, `description`, `access`, and an explicit `tools` list. Optional fields are `model`, `thinking`, and `timeoutMs`. Every bundled role shows `model: inherit` and `thinking: inherit` as editable placeholders. Replace them with an available `provider/model` and a separate thinking level when you want to pin a role; `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` are checked against that model’s supported capabilities.
 
 The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model. For example:
 
@@ -103,7 +103,29 @@ The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `
 {"agent":"reviewer","task":"Review the change","model":"provider/model","thinking":"high"}
 ```
 
-Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as ephemeral `pi --mode json -p --no-session` processes with explicit local tools plus `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` before work and to use web research when external evidence is needed. KillerOS allows at most eight tasks, four parallel readers, one serialized writer, 12 turns, ten minutes, a 32 MiB JSONL line, 2 MiB retained trace, 64 KiB stderr, and 50 KiB returned output per task. Esc cancellation terminates active children and escalates after five seconds.
+Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as ephemeral `pi --mode json -p --no-session` processes with explicit local tools plus `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Each child explicitly loads `npm:pi-web-access` and the KillerOS child-budget hook, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md`, work in bounded passes, and report after its first useful evidence. KillerOS allows at most eight tasks, four parallel readers, ten minutes, a 32 MiB JSONL line, 2 MiB retained trace, 64 KiB stderr, 50 KiB returned output, 250,000 tokens, and $5 per child. Read-only children receive a 24-call soft and 32-call hard tool budget that blocks read and web tools after the hard limit; final reports remain allowed. Esc cancellation terminates active children and escalates after five seconds.
+
+### Thread lifecycle
+
+Each delegated task creates a named child thread. Its contract records the parent ID, child ID, role, prompt, model, requested capability boundary, trace, usage, and result state. Roles define the child’s access and tools; they do not own lifecycle controls or grant new filesystem powers. The parent owns scope, waits, inspection, steering, collection, and closure.
+
+Threads move through `queued`, `active`, `done`, `failed`, `stopped`, and `closed`. The parent renders separate **Active** and **Done** lists. Active threads show their name, task, model, usage, and direct controls. Done threads keep their handoff and trace available until the parent closes them.
+
+The parent can inspect a thread’s prompt, role, model, tools, trace, usage, and handoff; steer an active thread with one bounded follow-up; interrupt one child or all active children; collect a concise handoff into parent context; and close a finished or stopped thread. An interrupt preserves the partial trace, states the reason, and reports the handoff as partial rather than successful.
+
+A child completes naturally when it returns a final answer. Routine turn caps do not end useful work. Named resource guards still stop unsafe growth: wall time, output bytes, retained trace, stderr, quota, read-tool calls, task count, and concurrency. Read-tool budgets are enforced inside the child process, so the model receives a finalization nudge and a blocked-tool result instead of being killed while it is still researching. A guard reports its cause and returns any partial work clearly. Esc cancellation terminates active children and escalates after five seconds.
+
+The replacement lifecycle has nine phases:
+
+1. **Dispatch:** create a named thread and store its contract before launch.
+2. **Track:** maintain lifecycle states and Active/Done visibility.
+3. **Inspect:** keep the trace in the child thread, not the parent context.
+4. **Steer:** append a bounded parent follow-up to an active thread.
+5. **Interrupt:** stop one or all active children while preserving partial work.
+6. **Collect:** return a concise handoff while retaining the expanded trace.
+7. **Bound:** apply named resource guards instead of a routine turn stop.
+8. **Close:** remove a finished or stopped thread from the workspace without deleting its result record.
+9. **Prove:** test identity, visibility, controls, natural completion, guards, partial handoffs, and closure.
 
 ## Configuration
 
@@ -141,7 +163,7 @@ The package manifest lists Pi’s built-in modules as peer dependencies, so npm
 
 The [`pi-package`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) keyword makes a published npm release visible in Pi’s package catalog.
 
-For the current unreleased `1.4.1`, keep the version unchanged and publish after the validation checks pass:
+For the current unreleased `1.4.3`, publish after the validation checks pass:
 
 ```bash
 npm login

package/agents/debugger.md

@@ -6,7 +6,6 @@ tools: read, grep, find, ls, edit, write, bash, web_search, source_check, fetch_
 # Replace inherit with provider/model to pin this role; set thinking separately when needed.
 model: inherit
 thinking: inherit
-maxTurns: 8
 timeoutMs: 300000
 ---
 

package/agents/documenter.md

@@ -6,7 +6,6 @@ tools: read, grep, find, ls, edit, write, bash, web_search, source_check, fetch_
 # Replace inherit with provider/model to pin this role; set thinking separately when needed.
 model: inherit
 thinking: inherit
-maxTurns: 8
 timeoutMs: 300000
 ---
 

package/agents/planner.md

@@ -6,7 +6,6 @@ tools: read, grep, find, ls, web_search, source_check, fetch_content, get_search
 # Replace inherit with provider/model to pin this role; set thinking separately when needed.
 model: inherit
 thinking: inherit
-maxTurns: 8
 timeoutMs: 300000
 ---
 

package/agents/reviewer.md

@@ -6,7 +6,6 @@ tools: read, grep, find, ls, web_search, source_check, fetch_content, get_search
 # Replace inherit with provider/model to pin this role; set thinking separately when needed.
 model: inherit
 thinking: inherit
-maxTurns: 8
 timeoutMs: 300000
 ---
 

package/agents/scout.md

@@ -6,7 +6,6 @@ tools: read, grep, find, ls, web_search, source_check, fetch_content, get_search
 # Replace inherit with provider/model to pin this role; set thinking separately when needed.
 model: inherit
 thinking: inherit
-maxTurns: 8
 timeoutMs: 300000
 ---
 

package/agents/security.md

@@ -6,7 +6,6 @@ tools: read, grep, find, ls, web_search, source_check, fetch_content, get_search
 # Replace inherit with provider/model to pin this role; set thinking separately when needed.
 model: inherit
 thinking: inherit
-maxTurns: 8
 timeoutMs: 300000
 ---
 

package/agents/tester.md

@@ -6,7 +6,6 @@ tools: read, grep, find, ls, edit, write, bash, web_search, source_check, fetch_
 # Replace inherit with provider/model to pin this role; set thinking separately when needed.
 model: inherit
 thinking: inherit
-maxTurns: 8
 timeoutMs: 300000
 ---
 

package/agents/worker.md

@@ -6,7 +6,6 @@ tools: read, grep, find, ls, edit, write, bash, web_search, source_check, fetch_
 # Replace inherit with provider/model to pin this role; set thinking separately when needed.
 model: inherit
 thinking: inherit
-maxTurns: 8
 timeoutMs: 300000
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "A production-hardened TUI and workflow extension for the Pi coding agent.",
   "type": "module",
   "keywords": [
@@ -22,6 +22,10 @@
   "files": [
     "Killeros.ts",
     "subagents.ts",
+    "subagent-lifecycle.ts",
+    "subagent-process.ts",
+    "subagent-budget.ts",
+    "subagent-ui.ts",
     "agents/*.md",
     "themes/killeros.json",
     "README.md",

package/subagent-budget.ts

@@ -0,0 +1,65 @@
+import type { ExtensionAPI, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+
+export const CHILD_TOOL_BUDGET_ENV = "PI_KILLEROS_TOOL_BUDGET";
+
+export interface ChildToolBudget {
+	soft?: number;
+	hard: number;
+	block: "*" | string[];
+}
+
+export function parseChildToolBudget(value: string | undefined): ChildToolBudget | undefined {
+	if (!value?.trim()) return undefined;
+	try {
+		const parsed = JSON.parse(value) as Record<string, unknown>;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+		const hard = parsed.hard;
+		const soft = parsed.soft;
+		const block = parsed.block;
+		if (typeof hard !== "number" || !Number.isSafeInteger(hard) || hard < 1) return undefined;
+		if (soft !== undefined && (typeof soft !== "number" || !Number.isSafeInteger(soft) || soft < 1 || soft > hard)) return undefined;
+		if (block !== "*" && (!Array.isArray(block) || block.length === 0 || block.some((tool) => typeof tool !== "string" || !tool.trim()))) return undefined;
+		return {
+			hard,
+			...(soft === undefined ? {} : { soft }),
+			block: block === "*" ? "*" : [...new Set((block as string[]).map((tool) => tool.trim()))],
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function softNudge(budget: ChildToolBudget, calls: number): string {
+	return `Tool budget soft limit reached after ${calls} tool call${calls === 1 ? "" : "s"} (soft ${budget.soft}, hard ${budget.hard}). Stop starting new browsing/search work and finalize from the context you already have.`;
+}
+
+function shouldBlock(budget: ChildToolBudget, toolName: string, calls: number): boolean {
+	return calls > budget.hard && (budget.block === "*" || budget.block.includes(toolName));
+}
+
+export default function registerSubagentBudget(pi: ExtensionAPI): void {
+	const budget = parseChildToolBudget(process.env[CHILD_TOOL_BUDGET_ENV]);
+	if (!budget) return;
+	let calls = 0;
+	let nudged = false;
+	const sendUserMessage = (pi as unknown as {
+		sendUserMessage?: (content: string, options: { deliverAs: "steer" }) => unknown;
+	}).sendUserMessage;
+
+	pi.on("tool_call", (event): ToolCallEventResult | void => {
+		calls += 1;
+		if (!nudged && budget.soft !== undefined && calls >= budget.soft) {
+			nudged = true;
+			try {
+				sendUserMessage?.(softNudge(budget, calls), { deliverAs: "steer" });
+			} catch {
+				// The hard block below remains authoritative if steering is unavailable.
+			}
+		}
+		if (!shouldBlock(budget, event.toolName, calls)) return undefined;
+		return {
+			block: true,
+			reason: `Tool budget hard limit reached after ${calls} tool calls (hard ${budget.hard}). Finalize from the context you already have.`,
+		};
+	});
+}