pi-open-agents 0.1.31 → 0.1.33

package/README.md

@@ -334,9 +334,11 @@ Use `replace-all` for fully isolated agents that should not be influenced by
 workspace context — e.g., a subagent that must run identically regardless of
 the project it's invoked from.
 
-For **subagents** (child process), the agent body **is** the system prompt —
-pi's default prompt is not included. Skills are injected as an XML block after
-the body.
+For **subagents** (child process), the same modes apply: with the default
+`append`, the agent body is appended to pi's default prompt (`--append-system-prompt`);
+`replace`/`replace-all` pass the body as the whole system prompt (`--system-prompt`).
+Skills are injected as an XML block after the body, followed by the result-closing
+contract (`## Outcome` block, file + summary).
 
 ---
 
@@ -415,7 +417,8 @@ six sessions, zero chaos: that's the exact workstation setup documented in
 - ~~**Per-call model override** in `subagent()`~~ — ✅ shipped in [0.1.19](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.19) (#10)
 - ~~**Primary tool filters incl. extension tools**~~ — ✅ shipped in [0.1.30](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.30) (#18)
 - ~~**Subagent output: file + summary**~~ — ✅ shipped in [0.1.31](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.31) (#32)
-- **Parallel subagent limit** — #11
+- ~~**Parallel subagent limit**~~ — ✅ closed, see #11 for the outcome
+- **Zero open issues** — the tracker is empty; new work starts from new issues.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-open-agents",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
   "keywords": [
     "pi-package",

package/src/discovery/loader.ts

@@ -115,6 +115,12 @@ export async function loadAgents(options: LoadAgentsOptions = {}): Promise<Agent
           // Skip disabled agents entirely
           if (agent.disable) continue;
 
+          // Resolve body-level include directives (fail-soft, never throws)
+          agent.prompt = await resolveIncludes(agent.prompt, path.dirname(filePath), {
+            fs: fileSystem,
+            reportedMissing: new Set(),
+          }, new Set([path.resolve(filePath)]), 0);
+
           // Add to the appropriate map
           if (discPath.source === "project") {
             projectAgents.set(agent.name, agent);
@@ -153,6 +159,119 @@ function defaultAgentDir(): string {
   return path.join(process.env.HOME ?? "", ".pi", "agent");
 }
 
+// ─── Include Directive Resolution ───────────────────────────────────────────
+
+/** Max recursion depth for include directives. */
+const INCLUDE_MAX_DEPTH = 8;
+
+/**
+ * A full-line include directive: `include: "path"`, `include: 'path'`,
+ * or `include: path`. Case-sensitive, must start at column 0 and occupy
+ * the whole line (trailing whitespace allowed). Occurrences inside
+ * sentences, indented lines, or fenced code blocks never match.
+ */
+const INCLUDE_LINE_RE = /^include:[ \t]+(?:"([^"]*)"|'([^']*)'|([^\s"']+))[ \t]*$/;
+
+/** Opening/closing fenced code block markers (``` or ~~~, optionally indented). */
+const FENCE_RE = /^[ \t]*(```|~~~)/;
+
+/** Shared state for one loadAgents run. */
+interface IncludeContext {
+  /** Filesystem abstraction (honors the custom fs used for tests). */
+  fs: AgentFs;
+  /** Resolved paths already warned about (one warning per missing path). */
+  reportedMissing: Set<string>;
+}
+
+function warnInclude(message: string): void {
+  console.error(`[pi-open-agents] include: ${message}`);
+}
+
+/**
+ * Resolve body-level include directives in agent markdown.
+ *
+ * Each directive line is replaced by the content of the referenced file,
+ * resolved relative to the directory of the file containing the directive.
+ * Includes are recursive under the same rule. Cycles are detected via the
+ * set of absolute paths on the current expansion path, and nesting is
+ * capped at INCLUDE_MAX_DEPTH.
+ *
+ * Fail-soft: missing files, cycles, and over-deep nesting keep the directive
+ * line literal and warn on stderr, but never throw. Keeping the line (instead
+ * of dropping it) preserves visibility for debugging and for any downstream
+ * loader that might resolve it later.
+ *
+ * @param content  Markdown body to process
+ * @param baseDir  Directory of the file containing the directives
+ * @param ctx      Shared per-load state
+ * @param visited  Absolute paths on the current expansion path (cycle guard)
+ * @param depth    Current inclusion depth (0 = the agent file itself)
+ */
+async function resolveIncludes(
+  content: string,
+  baseDir: string,
+  ctx: IncludeContext,
+  visited: Set<string>,
+  depth: number,
+): Promise<string> {
+  const lines = content.split("\n");
+  const out: string[] = [];
+  let inFence = false;
+
+  for (const line of lines) {
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      out.push(line);
+      continue;
+    }
+
+    if (inFence) {
+      out.push(line);
+      continue;
+    }
+
+    const match = INCLUDE_LINE_RE.exec(line);
+    const includePath = match ? (match[1] ?? match[2] ?? match[3]) : undefined;
+    if (!includePath) {
+      out.push(line);
+      continue;
+    }
+
+    const resolved = path.resolve(baseDir, includePath);
+
+    if (visited.has(resolved)) {
+      warnInclude(`cycle detected for "${includePath}" (${resolved}); keeping directive literal`);
+      out.push(line);
+      continue;
+    }
+
+    if (depth >= INCLUDE_MAX_DEPTH) {
+      warnInclude(`max depth ${INCLUDE_MAX_DEPTH} exceeded for "${includePath}"; keeping directive literal`);
+      out.push(line);
+      continue;
+    }
+
+    let raw: string;
+    try {
+      raw = await ctx.fs.readFile(resolved);
+    } catch {
+      if (!ctx.reportedMissing.has(resolved)) {
+        ctx.reportedMissing.add(resolved);
+        warnInclude(`file not found: "${includePath}" (${resolved}); keeping directive literal`);
+      }
+      out.push(line);
+      continue;
+    }
+
+    visited.add(resolved);
+    const expanded = await resolveIncludes(raw, path.dirname(resolved), ctx, visited, depth + 1);
+    visited.delete(resolved);
+    out.push(expanded);
+  }
+
+  return out.join("\n");
+}
+
 // ─── Filtering Utilities ────────────────────────────────────────────────────
 
 /**

package/src/subagent/prompt.ts

@@ -78,8 +78,8 @@ export function buildClosingContract(outputPath?: string): string {
     "",
     "If you produced files the caller asked for, list each on its own line as",
     "`<path>` — <one line describing the content>.",
-    "Keep the outcome block to 2-3 lines. Never paste the full output after the",
-    "marker when a file reference suffices; never hide an error behind a file reference.",
+    "Keep the outcome block to 2-3 lines. Keep the rest of your answer concise — the",
+    "outcome block is what the caller reads first; never hide an error behind brevity.",
   ];
   if (outputPath) {
     lines.push(

package/src/subagent/tool.ts

@@ -45,7 +45,7 @@ import {
   parentInheritedRules,
   type RecursionEnv,
 } from "./env.ts";
-import { preview, shortenPath, stringArg } from "../utils/format.ts";
+import { byteLength, preview, shortenPath, stringArg } from "../utils/format.ts";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -161,11 +161,41 @@ function toToolResult(result: AgentResult) {
 
 function toProgressResult(progress: AgentProgress) {
   return {
-    content: [{ type: "text" as const, text: progress.output || "(running...)" }],
+    content: [{ type: "text" as const, text: liveProgressText(progress.output) }],
     details: progress,
   };
 }
 
+/**
+ * Cap for live progress text (issue #32 follow-up).
+ *
+ * Every progress emit used to re-send the child's ENTIRE accumulated output:
+ * over a long run the same bytes go out N times (once per event, growing).
+ * Partial updates are transient (never persisted to the transcript — verified
+ * against live session JSONL), so the cap only trims live display/RPC traffic:
+ * the tail stays (what the child is doing *now*), the head is already in the
+ * temp archive. Final results are untouched (see toToolResult).
+ */
+export const LIVE_PROGRESS_MAX_BYTES = 2048;
+
+/** Tail a string to a byte budget (halving converge, multibyte-safe). */
+export function tailTextByBytes(text: string, maxBytes: number): string {
+  if (byteLength(text) <= maxBytes) return text;
+  let take = Math.min(text.length, maxBytes);
+  let cut = text.slice(text.length - take);
+  while (byteLength(cut) > maxBytes && take > 0) {
+    take = Math.floor(take / 2);
+    cut = text.slice(text.length - take);
+  }
+  return cut;
+}
+
+function liveProgressText(output: string | undefined): string {
+  const text = output || "(running...)";
+  const tailed = tailTextByBytes(text, LIVE_PROGRESS_MAX_BYTES);
+  return tailed.length < text.length ? `[…earlier live output omitted…]\n${tailed}` : text;
+}
+
 // ─── Styled Rendering ────────────────────────────────────────────────────────
 
 function styledPathArg(args: Record<string, unknown>, theme: ThemeLike, fallback?: string): string {