@selesai/code 0.5.29 → 0.6.1

package/dist/extensions/pi-subagents/src/shared/types.ts

@@ -5,7 +5,7 @@
 import * as os from "node:os";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
-import type { AgentConfig } from "../agents/agents.ts";
+import type { AgentConfig, AgentSource } from "../agents/agents.ts";
 import type { FSWatcher } from "node:fs";
 import type { ExtensionContext } from "@selesai/code";
 import type { ModelScopeConfig } from "../runs/shared/model-scope.ts";
@@ -912,12 +912,51 @@ export interface SpawnBudgetSnapshot {
 	grantHistory: SpawnBudgetGrant[];
 }
 
+// ============================================================================
+// Runtime catalog (action:list machine metadata)
+// ============================================================================
+
+/** Machine-readable catalog entry for one visible runtime agent. */
+export interface CatalogAgentMetadata {
+	name: string;
+	source: AgentSource;
+	description: string;
+	/** false for capability-ceiling-restricted agents (still visible, not launchable). */
+	executable: boolean;
+	/** Present only when the agent is capability-ceiling-restricted. */
+	restrictionSources?: string[];
+	aliases?: string[];
+	/** Normalized to explicit "fresh" when the agent has no defaultContext. */
+	defaultContext: "fresh" | "fork";
+	acceptanceRole?: AcceptanceRole;
+	/** Effective declared tools: normal tools plus mcp:-prefixed direct MCP tools. */
+	tools?: string[];
+}
+
+/** Machine-readable catalog entry for one visible chain. */
+export interface CatalogChainMetadata {
+	name: string;
+	source: AgentSource;
+	description: string;
+}
+
+/** Versioned action:list catalog mirroring the human list output. */
+export interface CatalogMetadataV1 {
+	version: 1;
+	agents: CatalogAgentMetadata[];
+	chains: CatalogChainMetadata[];
+	/** Present only when a capability ceiling restricted visible agents. */
+	capabilityCeilingSources?: string[];
+}
+
 export interface Details {
 	mode: SubagentRunMode | "management";
 	runId?: string;
 	/** Run-level context summary. "mixed" when children resolved to different modes. */
 	context?: "fresh" | "fork" | "mixed";
 	results: SingleResult[];
+	/** Runtime-resolved human+machine catalog for { action: "list" } results. */
+	catalog?: CatalogMetadataV1;
 	controlEvents?: ControlEvent[];
 	steering?: SteerActionResult;
 	asyncId?: string;
@@ -1645,7 +1684,7 @@ export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
 };
 
 export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
-	enabled: true,
+	enabled: false,
 	dir: "project",
 	includeInput: true,
 	includeOutput: true,

package/dist/extensions/pi-subagents/src/shared/utils.ts

@@ -7,7 +7,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import { formatToolCall } from "./formatters.ts";
-import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, NestedRunSummary, SingleResult, ToolCallSummary, Usage } from "./types.ts";
+import type { AgentProgress, AsyncStatus, ChainOutputMap, Details, DisplayItem, ErrorInfo, NestedRunSummary, SingleResult, ToolCallSummary, Usage } from "./types.ts";
 
 // ============================================================================
 // File System Utilities
@@ -414,12 +414,40 @@ export function compactForegroundResult(result: SingleResult): SingleResult {
 		messages: undefined,
 		progress: undefined,
 		toolCalls: toolCalls.length ? toolCalls : undefined,
+		// Reference-first terminal details: once an authoritative saved output path
+		// exists, drop the raw final output and truncation marker from the model-
+		// visible projection; consumers recover the file from `savedOutputPath`.
+		// Explicit `outputMode: "inline"` is the sole legacy full-text opt-out and
+		// keeps its final output in the terminal projection (e.g. delegation v1
+		// `response.output` stays populated).
+		finalOutput: result.savedOutputPath && result.outputMode !== "inline" ? undefined : result.finalOutput,
+		truncation: result.savedOutputPath && result.outputMode !== "inline" ? undefined : result.truncation,
 	};
 }
 
+/**
+ * Strip chain `details.outputs` text/structured payloads from the terminal
+ * projection while retaining the output names and step metadata. Chain output
+ * bindings themselves remain reference-first in the completion content and
+ * `{outputs.name}` interpolation (see outputEntryFromResult).
+ */
+function compactChainOutputs(outputs: ChainOutputMap | undefined): ChainOutputMap | undefined {
+	if (!outputs) return undefined;
+	const compact: ChainOutputMap = {};
+	for (const [name, entry] of Object.entries(outputs)) {
+		compact[name] = {
+			agent: entry.agent,
+			stepIndex: entry.stepIndex,
+			text: "",
+		};
+	}
+	return compact;
+}
+
 export function compactForegroundDetails(details: Details): Details {
 	return {
 		...details,
+		outputs: compactChainOutputs(details.outputs),
 		results: details.results.map(compactForegroundResult),
 		progress: details.progress
 			? details.progress.map(compactCompletedProgress)

package/dist/extensions/pi-subagents/src/slash/delegation-adapters.ts

@@ -375,7 +375,11 @@ export function toSubagentDelegationExecutionParams(request: SubagentDelegationR
 		toolBudget: request.toolBudget,
 		skill: request.skill,
 		output: request.output,
-		outputMode: request.outputMode,
+		// v1 has no default for outputMode: preserve the legacy full-text contract by
+		// resolving an omitted outputMode to explicit inline (response.output stays
+		// populated). The model-facing tool's mode-dependent reference-first default
+		// (omitted outputMode -> file-only) is intentionally NOT applied here.
+		outputMode: request.outputMode ?? "inline",
 		outputSchema: request.outputSchema,
 		agentContract: request.agentContract,
 		acceptance: request.acceptance,

package/dist/extensions/pi-subagents/src/tui/render.ts

@@ -2,6 +2,7 @@
  * Rendering functions for subagent results
  */
 
+import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { getMarkdownTheme, keyText, type ExtensionContext } from "@selesai/code";
@@ -27,6 +28,27 @@ import { contextModeBadge, contextModePrefix } from "../runs/shared/context-mode
 
 type Theme = ExtensionContext["ui"]["theme"];
 
+/**
+ * UI-side output projection: completed terminal results strip `finalOutput`/
+ * `truncation` when an authoritative saved output path exists (see
+ * compactForegroundResult). The UI recovers the full text from that path so
+ * widgets keep showing output without reintroducing it into model-facing
+ * details.
+ */
+function resultOutputForUi(r: Details["results"][number]): string {
+	const output = r.truncation?.text || getSingleResultOutput(r);
+	if (output) return output;
+	if (r.savedOutputPath) {
+		try {
+			const content = fs.readFileSync(r.savedOutputPath, "utf-8").trim();
+			return content || output;
+		} catch {
+			return output;
+		}
+	}
+	return output;
+}
+
 function liveDetailKeyText(): string {
 	return keyText("app.tools.expand");
 }
@@ -1308,7 +1330,7 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 }
 
 function renderSingleCompact(d: Details, r: Details["results"][number], theme: Theme, frame?: number): Component {
-	const output = r.truncation?.text || getSingleResultOutput(r);
+	const output = resultOutputForUi(r);
 	const progress = r.progress || r.progressSummary;
 	const isRunning = r.progress?.status === "running";
 	const contextBadge = contextModeBadge(theme, r.context ?? d.context);
@@ -1418,7 +1440,7 @@ function renderMultiCompact(d: Details, theme: Theme, frame?: number): Component
 			c.addChild(new Text(truncLine(theme.fg("dim", `  ◦ ${pendingLabel}: ${agentName} · pending`), width), 0, 0));
 			continue;
 		}
-		const output = getSingleResultOutput(r);
+		const output = resultOutputForUi(r);
 		const progressFromArray = d.progress?.find((p) => p.index === i) || d.progress?.find((p) => p.agent === r.agent && p.status === "running");
 		const rProg = r.progress || progressFromArray || r.progressSummary;
 		const rRunning = rProg && "status" in rProg && rProg.status === "running";
@@ -1500,7 +1522,7 @@ export function renderSubagentResult(
 					? theme.fg("success", "ok")
 					: theme.fg("error", "failed");
 		const contextBadge = contextModeBadge(theme, r.context ?? d.context);
-		const output = r.truncation?.text || getSingleResultOutput(r);
+		const output = resultOutputForUi(r);
 
 		const progressInfo = isRunning && r.progress
 			? ` | ${r.progress.toolCount} tools, ${formatTokens(r.progress.tokens)} tok, ${formatDuration(r.progress.durationMs)}`
@@ -1600,7 +1622,7 @@ export function renderSubagentResult(
 	const hasEmptyWithoutTarget = d.results.some((r) =>
 		r.exitCode === 0
 		&& r.progress?.status !== "running"
-		&& hasEmptyTextOutputWithoutOutputTarget(r.task, getSingleResultOutput(r)),
+		&& hasEmptyTextOutputWithoutOutputTarget(r.task, resultOutputForUi(r)),
 	);
 	const hasWorkflowFailure = workflowGraphHasStatus(d, ["failed"]);
 	const hasWorkflowStop = d.results.some((r) => r.stopped && r.progress?.status !== "running") || workflowGraphHasStatus(d, ["stopped"]);
@@ -1658,7 +1680,7 @@ export function renderSubagentResult(
 					const isComplete = result && result.exitCode === 0 && result.progress?.status !== "running";
 					const isEmptyWithoutTarget = Boolean(result)
 						&& Boolean(isComplete)
-						&& hasEmptyTextOutputWithoutOutputTarget(result.task, getSingleResultOutput(result));
+						&& hasEmptyTextOutputWithoutOutputTarget(result.task, resultOutputForUi(result));
 					const isCurrent = i === (d.currentStepIndex ?? d.results.length);
 					const stepIcon = isFailed
 						? theme.fg("error", "failed")
@@ -1729,7 +1751,7 @@ export function renderSubagentResult(
 		const rRunning = rProg?.status === "running";
 		const stepNumber = typeof rProg?.index === "number" ? rProg.index + 1 : i + 1;
 
-		const resultOutput = getSingleResultOutput(r);
+		const resultOutput = resultOutputForUi(r);
 		const statusIcon = rRunning
 			? theme.fg("warning", "running")
 			: r.exitCode !== 0

package/dist/extensions/pi-subagents/test/e2e/real-session-subagent.test.ts

@@ -13,6 +13,7 @@
 
 import { afterEach, describe, it } from "node:test";
 import assert from "node:assert/strict";
+import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { tryImport } from "../support/helpers.ts";
@@ -23,6 +24,17 @@ const piAi = await tryImport<unknown>("@earendil-works/pi-ai");
 const available = Boolean(piCodingAgent && piAi);
 
 const CHILD_MARKER = "CHILD_REAL_SESSION_OK";
+
+/**
+ * Reference-first tool results: completion content carries "Output saved to:
+ * <path> (…)". Read the durable file to inspect the full child output.
+ */
+function readSavedOutput(text: string): string {
+	const rest = text.split("Output saved to: ")[1];
+	assert.ok(rest, `expected a saved-output reference in: ${text.slice(0, 160)}`);
+	const outputPath = rest.split(" (")[0]!;
+	return fs.readFileSync(outputPath, "utf-8");
+}
 // Env vars the runner must clear so a parent that was itself spawned as a
 // subagent child can still launch fresh children. The values are deliberately
 // bogus sentinels (nonexistent paths) so a leaked value would break spawning.
@@ -122,10 +134,14 @@ Use the available tools.`;
 		const chainDetails = JSON.stringify((toolMessages[1] as { details?: unknown } | undefined)?.details);
 		const structuredDetails = JSON.stringify((toolMessages[2] as { details?: unknown } | undefined)?.details);
 		assert.equal(results.length, 4);
-		assert.match(results[0] ?? "", /ACTIVE_TOOLS:[^\n]*fixture_search/);
-		assert.match(results[0] ?? "", /ACTIVE_TOOLS:[^\n]*read/);
-		assert.match(chainDetails, /ACTIVE_TOOLS:[^\n]*fixture_search/);
-		assert.match(chainDetails, /ACTIVE_TOOLS:[^\n]*read/);
+		const directOutput = readSavedOutput(results[0] ?? "");
+		assert.match(directOutput, /ACTIVE_TOOLS:[^\n]*fixture_search/);
+		assert.match(directOutput, /ACTIVE_TOOLS:[^\n]*read/);
+		const chainFirstChild = (toolMessages[1] as { details?: { results?: Array<{ savedOutputPath?: string }> } } | undefined)?.details?.results?.[0];
+		assert.ok(chainFirstChild?.savedOutputPath, "chain details should carry the saved output path");
+		const chainOutput = fs.readFileSync(chainFirstChild.savedOutputPath, "utf-8");
+		assert.match(chainOutput, /ACTIVE_TOOLS:[^\n]*fixture_search/);
+		assert.match(chainOutput, /ACTIVE_TOOLS:[^\n]*read/);
 		assert.match(structuredDetails, /STRUCTURED_OUTPUT_OK/);
 		assert.match(results[3] ?? "", /requested unavailable child tools: missing_search/);
 		assert.match(results[3] ?? "", /subagentOnlyExtensions/);
@@ -172,7 +188,8 @@ Report active tools.`;
 
 		const results = subagentToolResults(run.parentSession);
 		assert.equal(results.length, 1);
-		assert.match(results[0] ?? "", /ACTIVE_TOOLS:[^\n]*fixture_async_search/);
+		const asyncOutput = readSavedOutput(results[0] ?? "");
+		assert.match(asyncOutput, /ACTIVE_TOOLS:[^\n]*fixture_async_search/);
 		assert.doesNotMatch(results[0] ?? "", /requested unavailable child tools/);
 	});
 
@@ -206,7 +223,7 @@ Report active tools.`;
 
 			const toolResults = subagentToolResults(run.parentSession);
 			assert.equal(toolResults.length, 1);
-			assert.match(toolResults[0]!, new RegExp(CHILD_MARKER));
+			assert.match(readSavedOutput(toolResults[0]!), new RegExp(CHILD_MARKER));
 			assert.match(run.responseText, new RegExp(CHILD_MARKER));
 			assert.doesNotMatch(run.responseText, /CHILD_MISSING/);
 			assert.ok(run.modelCalls >= 2, `expected parent tool-call and final turns, got ${run.modelCalls}`);
@@ -219,4 +236,92 @@ Report active tools.`;
 			}
 		}
 	});
+
+	function latestSubagentToolResultText(messages: Array<{ role?: string; toolName?: string; content?: unknown }>): string | undefined {
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const message = messages[i]!;
+			if (message.role === "toolResult" && message.toolName === "subagent") {
+				return Array.isArray(message.content)
+					? message.content
+						.map((part) => part && typeof part === "object" && (part as { type?: unknown }).type === "text"
+							? String((part as { text?: unknown }).text ?? "")
+							: "")
+						.join("")
+					: "";
+			}
+		}
+		return undefined;
+	}
+
+	it("lists then delegates to a non-bundled discovered writer in a broad-mutation request", async () => {
+		const { runRealSubagentSession, subagentCall, subagentToolResults } = await import("../support/real-session-runner.ts");
+		const writerAgent = `---
+name: fixture-writer
+description: Scoped mutation-capable fixture writer
+aliases: fw
+tools: read, grep, find, ls, bash, edit, write
+acceptanceRole: writer
+defaultContext: fork
+completionGuard: false
+---
+Implement the scoped fixture change and return the marker.`;
+
+		run = await runRealSubagentSession({
+			prompt: "Implement the fixture change across the codebase.",
+			childText: CHILD_MARKER,
+			projectFiles: {
+				".selesai/agents/fixture-writer.md": writerAgent,
+			},
+			respond(context) {
+				const messages = context.messages as Array<{ role?: string; toolName?: string; content?: unknown; details?: unknown }>;
+				const subagentResults = messages.filter((message) => message.role === "toolResult" && message.toolName === "subagent");
+				if (subagentResults.length === 0) {
+					return subagentCall({ action: "list", agentScope: "project" }, "call-list-writer");
+				}
+				if (subagentResults.length === 1) {
+					const listText = latestSubagentToolResultText(messages) ?? "";
+					assert.match(
+						listText,
+						/- fixture-writer \(project, context: fork, role: writer, aliases: fw, tools: read, grep, find, ls, bash, edit, write\)/,
+						"catalog must expose the custom writer with its runtime metadata",
+					);
+					const listedDetails = JSON.stringify(subagentResults.at(-1)?.details ?? {});
+					assert.match(listedDetails, /"catalog"/);
+					assert.match(listedDetails, /"fixture-writer"/);
+					assert.match(listedDetails, /"acceptanceRole":"writer"/);
+					return subagentCall(
+						{ agent: "fixture-writer", task: "Implement the change and return the marker.", context: "fresh", agentScope: "project" },
+						"call-fixture-writer",
+					);
+				}
+				return "Broad mutation work complete.";
+			},
+			timeoutMs: 60_000,
+		});
+
+		const results = subagentToolResults(run.parentSession);
+		assert.equal(results.length, 2);
+		assert.match(results[0] ?? "", /fixture-writer \(project, context: fork, role: writer/);
+		assert.match(readSavedOutput(results[1] ?? ""), new RegExp(CHILD_MARKER));
+	});
+
+	it("keeps tiny targeted reads local without a subagent call", async () => {
+		const { runRealSubagentSession, subagentToolResults } = await import("../support/real-session-runner.ts");
+		run = await runRealSubagentSession({
+			prompt: "What does the README say about subagents?",
+			childText: CHILD_MARKER,
+			projectFiles: {
+				"README.md": "Subagents are delegated workers.",
+			},
+			respond() {
+				return "The README says: Subagents are delegated workers.";
+			},
+			timeoutMs: 60_000,
+		});
+
+		const results = subagentToolResults(run.parentSession);
+		assert.equal(results.length, 0);
+		assert.match(run.responseText, /Subagents are delegated workers/);
+		assert.ok(run.modelCalls >= 1, `expected at least one parent turn, got ${run.modelCalls}`);
+	});
 });