@tduyng/pi-subagent 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+Use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 tduyng

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @tduyng/pi-subagent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Delegates work to child pi sessions running in-process. The parent stays lean because the child reads the files, returns one message plus a file list and usage stats, and then its context is discarded. Each finished child also appends its usage to `<agentDir>/overhead.jsonl` under the parent's session, so `/cost` can show what the delegation spent alongside the conversation.
+
+## How delegation works
+
+The `subagent` tool sends one task, or up to `MAX_TASKS` tasks, to a child
+session. At most `MAX_CONCURRENT` children run at once. Each child runs on the
+current model unless a task, profile, or `subagent.json` override changes it.
+The child sees the task prompt, does the work, and returns one message. The
+parent never carries the child's exploration.
+
+Use `scout` for read-only file and document search, code tracing, analysis, and
+short sourced summaries. Omitting `agent` selects `scout`. It is the cheap
+default for I/O-heavy work. `subagent.json` supplies its low-cost model.
+
+Use `verifier` only
+after an artifact exists and the task explicitly asks for verification or
+review. Keep ordinary implementation, debugging, design, builds, tests, and lint
+in the parent session.
+
+### Resume ids
+
+A child that reaches its turn budget is told to wrap up and gets a fresh budget in the same session, so a cap never turns work into a failure. If the child still stops early, its last text comes back as a `[partial answer]`. Salvage walks the whole transcript for that text, not just the last message, so a child stopped mid-tool-burst still returns what it wrote. Every failed task prints a `resume:` id. Pass `resume: "<id>"` (or `"all"`) to continue where it stopped instead of paying for the investigation again. An optional `task` alongside `resume` steers the continuation. Failed sessions are kept 30 minutes, completed ones 5.
+
+A deadline is reported as a timeout, not a cancellation. Pi keeps any final text produced before the deadline, marks it partial, and retains the session for resume.
+
+Every run also writes `run.json` under `<agent-dir>/subagents/<session-id>/<run-id>/` with the task prompt, model, tools, and the path to each child session. The file is rewritten after each task transition, so it survives the process. Reopening the same Pi session reads it back: children interrupted less than ten minutes ago are resumed from their saved sessions and their result arrives as a `subagent-durable` message, while older interruptions are listed with their resume ids. `resume` therefore works after a restart, not only inside the process that started the child.
+
+### Worktree isolation
+
+With `isolation: "worktree"`, each child runs in its own git worktree on a branch named `pi-task-<id>`, so concurrent children never edit the same checkout and a commit a child makes outlives the checkout. The task result names the branch.
+
+### Structured output
+
+Pass `schema` to ask the child to call a `structured_output` tool exactly once. The parsed payload comes back in the task result. If the child finishes without calling the tool, the extension re-prompts the same session up to three times, so the investigation is not paid for twice. If it still refuses, the text answer stands and the task completes marked partial. If a provider rejects the schema tool, the extension removes it and retries once in plain-text mode.
+
+### Fork context
+
+With `context: "fork"`, the parent's conversation history is replayed into the child as context entries.
+
+## Agent profiles
+
+The `/agents` command lists agent profiles, which are markdown files with YAML frontmatter in `<agent-dir>/agents` or `.pi/agents`. Project agents shadow user agents of the same name. Each profile specifies a tool list, model, thinking level, limits, and optional color for the widget. Profiles can also set `inheritProjectContext` and `inheritSkills` to control whether the child picks up the parent project's context files and skills, and `systemPromptMode: replace` to swap the default system prompt instead of appending to it. The `subagent` widget in the TUI shows up to 8 running and recently finished children, with a summary line of counts by status. Navigate with Down/Up, Enter opens a live transcript viewer, d/x dismisses.
+
+## Bulk-read guard
+
+The guard blocks reads of files above `BULK_READ_MIN_LINES` lines (default 350). It also blocks `cat`, `less`, and `more` commands that would dump large files. The second call for the same path passes through, so the file stays reachable. A read passes when it returns fewer lines than the threshold, whether that comes from a `limit`, an `offset`, a small file, or `head`/`tail` on their 10-line default, and so does a piped command.
+
+## Log reducer
+
+Build or test logs above 4,096 bytes, matched by diagnostic command patterns, get replaced with a short receipt of quoted lines. Every quote is verified byte-for-byte against the archived original. If validation fails, the full log reaches the model untouched. The reducer runs on `tool_result`, so the swap happens before the result enters history. The raw log is archived next to the session for full access.
+
+## Design
+
+- The default safe delegation is read-only I/O: `scout` searches, traces, analyses, and summarizes without editing or running commands.
+- `verifier` is reserved for explicit verification of an existing artifact. It may write only its verification report, never implementation files.
+- Ordinary implementation, debugging, design, builds, tests, and lint stay in the parent session.
+- The tool rejects concurrent write-capable tasks. Read-only scouts may still run in parallel. A call whose task texts normalize to the same request is rejected, so one question does not get paid for twice.
+- Children see one prompt and return one message. No sequential pipelines.
+- Children cannot spawn their own subagents. No grandchildren.
+- The `subagent` tool schema is present on every turn, and it lists only the fields a model sets: `task`, `agent`, `cwd`, `isolation`, `schema`, `context`, and `resume`. `label`, `thinking`, `model`, `timeoutMs`, and `maxTurns` are profile policy. They still work when a scripted caller passes them, and three of them already resolved to the profile before the split.
+- The `subagent` tool schema is present on every turn. The `bulk-read` and `log-reducer` extensions add no tool schemas. They run as event handlers. The registry holds at most 50 tasks. The widget shows at most 8 rows. The `touched` file list per task is capped at 12 entries. Progress updates emit at most once every 250ms.
+- Child deadlines default to 30 minutes. A shorter `timeoutMs` or profile `maxExecutionTimeMs` is raised to 30 minutes, while longer values pass through. A profile deadline beyond the 32-bit setTimeout ceiling (2,147,483,647 ms) clamps to the ceiling. Node would round a larger delay down to 1 ms and kill the child instantly, so the clamp degrades a bad value to a very long deadline.
+- Children inherit the parent's model by default. Thinking does not inherit: it resolves from the task's `thinking`, then the profile, then `subagent.json`, then `medium`.
+
+## Install
+
+```bash
+pi install npm:@tduyng/pi-subagent
+```
+
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-subagent`
+
+## Configure
+
+- `subagent.json` in the agent dir (`~/.pi/agent/`) sets the default child model and thinking level. A project's `.pi/subagent.json` overrides either field. Shape: `{ "model": "provider/model-id", "thinking": "medium" }`, both optional. `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Unset, it is `medium`. No file means children inherit the parent's model.
+- `BULK_READ=0` disables the bulk-read guard. `BULK_READ_MIN_LINES` sets the line threshold (default 350).
+- `PI_LOG_REDUCER=0` disables the log reducer.
+- `PI_LOG_REDUCER_TIMEOUT_MS` sets the reducer deadline. The default is 15 seconds and the maximum is 60 seconds.
+- Agent profiles are markdown files with YAML frontmatter in `~/.pi/agent/agents/` or `.pi/agents/` (project shadowing user on name collision).

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@tduyng/pi-subagent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Delegation to in-process child sessions: a subagent tool with agent profiles and worktree isolation, a side chat, a guard that redirects bulk reads, and a verified log reducer.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "subagent",
+    "delegation",
+    "parallel",
+    "tokens"
+  ],
+  "homepage": "https://gitlab.com/tduyng/pi-agent/-/tree/main/extensions/pi-subagent#readme",
+  "bugs": "https://gitlab.com/tduyng/pi-agent/-/issues",
+  "license": "Apache-2.0",
+  "author": "tduyng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tduyng/pi-agent.git",
+    "directory": "extensions/pi-subagent"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/subagent/index.ts",
+      "./src/bulk-read.ts",
+      "./src/log-reducer.ts"
+    ]
+  },
+  "exports": {
+    ".": "./src/subagent/index.ts",
+    "./agent": "./src/subagent/agent.ts"
+  },
+  "dependencies": {
+    "ata-validator": "^1.62.1"
+  }
+}

package/src/bulk-read.ts

@@ -0,0 +1,147 @@
+import { closeSync, openSync, readSync, statSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+import { isToolCallEventType, type ExtensionAPI, type ToolCallEvent } from '@earendil-works/pi-coding-agent'
+
+const DEFAULT_MIN_LINES = 350
+const HUGE_BYTES = 2_000_000
+const CHUNK_BYTES = 64 * 1024
+
+function minLines(): number {
+    const raw = Number(process.env['BULK_READ_MIN_LINES'])
+    return Number.isInteger(raw) && raw > 0 ? raw : DEFAULT_MIN_LINES
+}
+
+/**
+ * Lines in a file, reading in chunks and stopping once `cap` is passed. A caller that only
+ * needs to know a file is over the threshold never reads the whole of a large file, and a
+ * caller that needs the exact count passes no cap.
+ */
+export function lineCount(absolutePath: string, cap = Number.MAX_SAFE_INTEGER): number | null {
+    try {
+        if (statSync(absolutePath).size > HUGE_BYTES) return Number.MAX_SAFE_INTEGER
+        const fd = openSync(absolutePath, 'r')
+        try {
+            const buffer = Buffer.allocUnsafe(CHUNK_BYTES)
+            let lines = 0
+            let last = 0
+            let position = 0
+            while (true) {
+                const bytes = readSync(fd, buffer, 0, CHUNK_BYTES, position)
+                if (bytes === 0) break
+                for (let index = 0; index < bytes; index += 1) {
+                    if (buffer[index] === 10) lines += 1
+                }
+                last = buffer[bytes - 1] ?? 0
+                position += bytes
+                if (lines > cap) return lines
+            }
+            return last === 10 ? lines : lines + 1
+        } finally {
+            closeSync(fd)
+        }
+    } catch {
+        return null
+    }
+}
+
+const DUMP_DEFAULT_LINES = {
+    cat: Number.POSITIVE_INFINITY,
+    less: Number.POSITIVE_INFINITY,
+    more: Number.POSITIVE_INFINITY,
+    head: 10,
+    tail: 10
+} as const
+
+function isDumpTool(name: string): name is keyof typeof DUMP_DEFAULT_LINES {
+    return name in DUMP_DEFAULT_LINES
+}
+
+export function dumpTarget(command: string, threshold: number): string | null {
+    if (/[|><;&]/.test(command)) return null
+
+    const parts = command.trim().split(/\s+/)
+    const tool = parts.shift()
+    if (tool === undefined || !isDumpTool(tool)) return null
+
+    let bound: number = DUMP_DEFAULT_LINES[tool]
+    const counted = tool === 'head' || tool === 'tail'
+    const files: string[] = []
+    for (let i = 0; i < parts.length; i += 1) {
+        const part = parts[i] ?? ''
+        if (counted && (part === '-n' || part === '-c')) {
+            i += 1
+            bound = Number(parts[i]) || bound
+            continue
+        }
+        const short = /^-(\d+)$/.exec(part)
+        if (counted && short?.[1] !== undefined) {
+            bound = Number(short[1])
+            continue
+        }
+        if (part.startsWith('-')) continue
+        files.push(part)
+    }
+    if (files.length !== 1 || bound < threshold) return null
+    return files[0] ?? null
+}
+
+export function redirect(path: string, lines: number, threshold: number): string {
+    return (
+        `bulk-read blocked this read: ${path} is at least ${lines} lines (threshold ${threshold}), ` +
+        `and its contents would stay in context and be re-billed every later turn.\n` +
+        `Pick one:\n` +
+        `  - Outline it, cheapest and usually enough. Call outline on ${path} for its declarations ` +
+        `and line spans, then read the span you need with offset and limit. Use grep when you know a name.\n` +
+        `  - Filter it in codemode when you need the whole file and only a slice of it. ` +
+        `Await tools.read in a script and text() just the lines you keep.\n` +
+        `  - Delegate it when you need the whole file's meaning rather than a few lines. Call ` +
+        `subagent with a task naming this file and the exact question, e.g. "Read ${path} and ` +
+        `list the functions that touch the database, with line numbers." The child reads it on ` +
+        `a cheap model and you get back only the answer.\n` +
+        `Read the whole file only if you truly need all of it; repeating this exact call will go through.`
+    )
+}
+
+export default function bulkReadExtension(pi: ExtensionAPI): void {
+    if (/^(0|false|no|off)$/i.test(process.env['BULK_READ'] ?? '')) return
+
+    const refused = new Set<string>()
+
+    pi.on('session_start', (event) => {
+        if (event.reason === 'new') refused.clear()
+    })
+
+    pi.on('tool_call', (event: ToolCallEvent, ctx) => {
+        // A nested call is codemode, where the script decides what reaches context.
+        if (event.parentToolCallId !== undefined) return undefined
+
+        const threshold = minLines()
+        let path: string
+        let skipLines = 0
+        let limit: number | undefined
+        if (isToolCallEventType('read', event)) {
+            limit = event.input.limit
+            if (limit !== undefined && limit < threshold) return undefined
+            skipLines = Math.max(0, (event.input.offset ?? 1) - 1)
+            path = event.input.path
+        } else if (isToolCallEventType('bash', event)) {
+            const target = dumpTarget(event.input.command, threshold)
+            if (target === null) return undefined
+            path = target
+        } else {
+            return undefined
+        }
+
+        const absolute = isAbsolute(path) ? path : resolve(ctx.cwd, path)
+        if (refused.has(absolute)) return undefined
+
+        const total = lineCount(absolute, skipLines + threshold)
+        if (total === null) return undefined
+        const lines = Math.max(0, total - skipLines)
+        const returned = limit === undefined ? lines : Math.min(lines, limit)
+        if (returned < threshold) return undefined
+
+        refused.add(absolute)
+        return { block: true, reason: redirect(path, returned, threshold) }
+    })
+}

package/src/lib/child-runtime.ts

@@ -0,0 +1,18 @@
+import { type ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { ModelRuntime } from '@earendil-works/pi-coding-agent'
+
+export async function createChildModelRuntime(ctx: Pick<ExtensionContext, 'modelRegistry'>): Promise<ModelRuntime> {
+    const runtime = await ModelRuntime.create()
+    for (const providerId of ctx.modelRegistry.getRegisteredProviderIds()) {
+        const config = ctx.modelRegistry.getRegisteredProviderConfig(providerId)
+        if (config) {
+            runtime.registerProvider(providerId, config)
+            continue
+        }
+        const native = ctx.modelRegistry.getRegisteredNativeProvider(providerId)
+        if (native) {
+            runtime.registerNativeProvider(native)
+        }
+    }
+    return runtime
+}