@victor-software-house/pi-acp 0.12.0 → 0.13.1

package/README.md

@@ -7,7 +7,7 @@ ACP ([Agent Client Protocol](https://agentclientprotocol.com/get-started/introdu
 ## Specs and decisions
 
 - [`docs/prd/PRD-001-acp-v013-zed-alignment.md`](docs/prd/PRD-001-acp-v013-zed-alignment.md) — v0.5 release PRD (Shipped).
-- [`docs/prd/PRD-002-portable-runtime.md`](docs/prd/PRD-002-portable-runtime.md) — v0.6 portable runtime + multi-host resource composition (Draft).
+- [`docs/prd/PRD-002-portable-runtime.md`](docs/prd/PRD-002-portable-runtime.md) — v0.6 portable runtime + multi-host resource composition (Substrate Shipped; Phases 8b/9 deferred).
 - [`docs/prd/PRD-003-runtime-daemon.md`](docs/prd/PRD-003-runtime-daemon.md) — v0.6 long-running daemon + thin-client binary (Draft).
 - [`docs/architecture/plan-acp-v013-zed-alignment.md`](docs/architecture/plan-acp-v013-zed-alignment.md) — v0.5 phased implementation plan.
 - [`docs/architecture/plan-portable-runtime.md`](docs/architecture/plan-portable-runtime.md) — v0.6 portable-runtime plan.
@@ -53,6 +53,63 @@ Active development. ACP compliance is improving steadily. Development is centere
   - Built-in adapter commands (see below)
 - Authentication via Terminal Auth (ACP Registry support)
 - Startup info block with pi version and context (configurable via `quietStartup` setting)
+- **Resource composition manifest** (`.pi-acp.yaml`) — PRD-002 §FR-3
+  - Cascade: ACP session params > project `<cwd>/.pi-acp.yaml` > user-global `~/.pi-acp/config.yaml` > synthesized default
+  - Backends: `local`, `ssh` (Bun Shell `$` + ssh self-terminate options), `http` (HTTPS-only fetch + per-URL TTL cache, default 300s)
+  - Merge strategies: `append` (default) or `override-by-name` for skills and prompts
+  - Opt-in diagnostics surface (`diagnostics: true`) — one-line resource summary on first prompt of each session
+- **Cwd-independence modes** (PRD-002 §FR-5)
+  - `local` (default) / `overlay` — ACP `params.cwd` used as session cwd; manifest roots compose
+  - `none` — pi-acp mints an ephemeral tmpdir under `os.tmpdir()/pi-acp-session-*`, cleaned up at session dispose. For one-shot Q&A sessions that shouldn't pollute any project directory.
+- **ACP-FS `read` delegation** (PRD-002 §FR-6) — When the client advertises `clientCapabilities.fs.readTextFile`, pi-acp routes pi's built-in `read` tool through `connection.fs.readTextFile` instead of local disk. Lets Zed Remote read the actual remote workspace files (the ones the user is editing) while pi runs locally.
+
+## Resource composition (`.pi-acp.yaml`)
+
+Drop a `.pi-acp.yaml` at the project root (or `~/.pi-acp/config.yaml` for user-global defaults). Schema version `1`:
+
+```yaml
+version: 1
+mode: local      # local (default) | overlay | none
+mergeStrategy: append   # append | override-by-name
+diagnostics: false      # true: emit a one-line resource summary on first prompt
+
+roots:
+  # Local roots (cwd + optional alt agentDir)
+  - id: project
+    kind: local
+    paths:
+      cwd: .
+      agentDir: ~/.pi/agent
+
+  # Remote files over SSH (operator's ~/.ssh/config honored end-to-end)
+  - id: cvm
+    kind: ssh
+    host: cvm
+    user: varaujo
+    paths:
+      agentsFiles:
+        - /home/varaujo/.pi/agent/AGENTS.md
+        - /workspace/team/SECURITY.md
+      # skills/prompts/extensions over SSH not yet implemented;
+      # declaring paths.skills here emits a diagnostic at session start.
+
+  # Public HTTPS fetch (e.g. team's shared AGENTS file on a public repo)
+  - id: team
+    kind: http
+    baseUrl: https://raw.githubusercontent.com/team/dotfiles/main
+    cache:
+      ttl: 600   # per-URL TTL in seconds; default 300, 0 disables
+    paths:
+      agentsFiles:
+        - AGENTS.md
+```
+
+Cascade precedence (highest first):
+
+1. ACP session params: `params._meta.piAcp.manifest` (inline manifest object OR string path to a YAML file)
+2. Project: `<cwd>/.pi-acp.yaml`
+3. User-global: `~/.pi-acp/config.yaml`
+4. Synthesized default (single implicit local root)
 
 ## Prerequisites
 
@@ -151,7 +208,7 @@ bun run dev          # run from src
 bun run build        # tsdown -> dist/index.mjs
 bun run typecheck    # tsc --noEmit
 bun run lint         # biome + oxlint
-bun test             # 26 tests
+bun test             # 277 tests
 ```
 
 Project layout:
@@ -191,7 +248,7 @@ test/
 ### Not implemented (MAY / client capabilities)
 
 - **`agent_plan`** -- plan updates not emitted before tool execution. pi has no equivalent planning surface.
-- **ACP filesystem delegation** (`fs/read_text_file`, `fs/write_text_file`) -- pi reads/writes locally. Not advertised.
+- **ACP filesystem `write` delegation** (`fs/write_text_file`) -- pi writes locally. Not advertised. `fs/read_text_file` IS routed through ACP when the client advertises the capability (see Features → ACP-FS `read` delegation).
 - **ACP terminal delegation** (`terminal/*`) -- pi executes commands locally. Not advertised.
 
 ### Design decisions

package/dist/{daemon-D6QKWz5C.mjs → daemon-BErbUhcE.mjs}

@@ -877,6 +877,7 @@ var PiAcpSession = class {
 	lastEmit = Promise.resolve();
 	unsubscribe;
 	cleanups;
+	pendingDiagnosticsReport;
 	constructor(opts) {
 		this.sessionId = opts.sessionId;
 		this.cwd = opts.cwd;
@@ -885,6 +886,7 @@ var PiAcpSession = class {
 		this.conn = opts.conn;
 		this.supportsTerminalOutput = opts.supportsTerminalOutput ?? false;
 		this.cleanups = opts.cleanups ?? [];
+		this.pendingDiagnosticsReport = opts.diagnosticsReport !== void 0 && opts.diagnosticsReport !== "" ? opts.diagnosticsReport : null;
 		this.unsubscribe = this.piSession.subscribe((ev) => this.handlePiEvent(ev));
 	}
 	dispose() {
@@ -930,6 +932,20 @@ var PiAcpSession = class {
 			};
 		});
 		const imageContents = Array.isArray(images) ? images.filter((img) => typeof img === "object" && img !== null && "type" in img && img.type === "image") : [];
+		if (this.pendingDiagnosticsReport !== null) {
+			const report = this.pendingDiagnosticsReport;
+			this.pendingDiagnosticsReport = null;
+			this.conn.sessionUpdate({
+				sessionId: this.sessionId,
+				update: {
+					sessionUpdate: "agent_message_chunk",
+					content: {
+						type: "text",
+						text: `${report}\n`
+					}
+				}
+			}).catch(() => {});
+		}
 		this.piSession.prompt(message, { images: imageContents }).catch(() => {
 			this.flushEmits().finally(() => {
 				const reason = this.cancelRequested ? "cancelled" : "error";
@@ -1345,6 +1361,43 @@ function acpPromptToPiMessage(blocks) {
 	};
 }
 //#endregion
+//#region src/resources/diagnostics.ts
+function buildDiagnosticsReport(input) {
+	const sourceStats = input.sources.map((source) => {
+		const skills = source.getSkills();
+		const prompts = source.getPrompts();
+		const failures = skills.diagnostics.filter((d) => d.type === "warning" || d.type === "error").map((d) => d.message);
+		return {
+			id: source.id,
+			kind: source.kind,
+			agentsFiles: source.getAgentsFiles().length,
+			skills: skills.skills.length,
+			prompts: prompts.prompts.length,
+			failures
+		};
+	});
+	const lines = [];
+	if (sourceStats.length > 0) {
+		lines.push("[pi-acp] resources active:");
+		for (const s of sourceStats) lines.push(`  ${s.id.padEnd(20)} kind=${s.kind} (${s.agentsFiles} AGENTS files, ${s.skills} skills, ${s.prompts} prompts)`);
+	}
+	const allFailures = [];
+	for (const s of sourceStats) for (const f of s.failures) allFailures.push(`  ${s.id.padEnd(20)} ${f}`);
+	for (const d of input.manifestDiagnostics) {
+		const where = d.path !== void 0 ? ` ${d.path}` : "";
+		allFailures.push(`  manifest[${d.source}${where}] ${d.message}`);
+	}
+	if (allFailures.length > 0) {
+		if (lines.length > 0) lines.push("");
+		lines.push("[pi-acp] resource failures:");
+		lines.push(...allFailures);
+	}
+	return {
+		text: lines.join("\n"),
+		sourceStats
+	};
+}
+//#endregion
 //#region src/resources/sources/local.ts
 /**
 * LocalBackend: wraps pi's DefaultResourceLoader for one (cwd, agentDir) root.
@@ -1954,7 +2007,7 @@ var SshBackend = class {
 //#endregion
 //#region package.json
 var name = "@victor-software-house/pi-acp";
-var version = "0.12.0";
+var version = "0.13.1";
 //#endregion
 //#region src/acp/agent.ts
 /** Builtin ACP slash commands handled directly by the adapter. */
@@ -2086,15 +2139,20 @@ var PiAcpAgent = class {
 	* Phase 7 adds `kind: "http"`. `acp-fs` still parses fine but surfaces as
 	* a diagnostic until its backend lands in a subsequent phase.
 	*/
-	async buildResourceLoader(cwd, sessionParams) {
+	async buildResourceLoader(cwd, sessionParams, opts) {
 		const loaded = await loadManifest({
 			cwd,
 			sessionParams
 		});
-		const modeResult = resolveMode({
+		const modeResult = opts?.resolveCwdMode !== false ? resolveMode({
 			manifest: loaded.manifest,
 			requestedCwd: cwd
-		});
+		}) : {
+			mode: loaded.manifest.mode,
+			cwd,
+			cleanup: () => {},
+			ephemeral: false
+		};
 		const effectiveCwd = modeResult.cwd;
 		const diagnostics = [...loaded.diagnostics];
 		const sources = [];
@@ -2149,7 +2207,9 @@ var PiAcpAgent = class {
 		}
 		return {
 			loader,
-			modeResult
+			modeResult,
+			diagnosticsEnabled: loaded.manifest.diagnostics === true,
+			manifestDiagnostics: diagnostics
 		};
 	}
 	/**
@@ -2223,7 +2283,7 @@ var PiAcpAgent = class {
 		};
 	}
 	async newSession(params) {
-		const { loader: resourceLoader, modeResult } = await this.buildResourceLoader(params.cwd, params).catch((e) => {
+		const { loader: resourceLoader, modeResult, diagnosticsEnabled, manifestDiagnostics } = await this.buildResourceLoader(params.cwd, params).catch((e) => {
 			const authErr = detectAuthError(e);
 			if (authErr !== null) throw authErr;
 			const msg = e instanceof Error ? e.message : String(e);
@@ -2234,6 +2294,10 @@ var PiAcpAgent = class {
 			modeResult.cleanup();
 			throw RequestError.invalidParams(`cwd must be an absolute path: ${params.cwd}`);
 		}
+		const diagnosticsReport = diagnosticsEnabled ? buildDiagnosticsReport({
+			sources: resourceLoader.listSources(),
+			manifestDiagnostics
+		}).text : "";
 		const acpReadOverlay = this.buildAcpReadOverlay(effectiveCwd);
 		let result;
 		try {
@@ -2269,7 +2333,8 @@ var PiAcpAgent = class {
 			piSession,
 			conn: this.conn,
 			supportsTerminalOutput: this.clientCapabilities.terminalOutput,
-			cleanups: modeResult.ephemeral ? [modeResult.cleanup] : []
+			cleanups: modeResult.ephemeral ? [modeResult.cleanup] : [],
+			...diagnosticsReport !== "" ? { diagnosticsReport } : {}
 		});
 		this.sessions.register(session);
 		this.registerWithDaemon({
@@ -2519,7 +2584,7 @@ var PiAcpAgent = class {
 		let result;
 		try {
 			const sm = SessionManager.open(sessionFile);
-			const { loader: resourceLoader } = await this.buildResourceLoader(params.cwd, params);
+			const { loader: resourceLoader } = await this.buildResourceLoader(params.cwd, params, { resolveCwdMode: false });
 			result = await createAgentSession({
 				cwd: params.cwd,
 				sessionManager: sm,
@@ -2625,7 +2690,7 @@ var PiAcpAgent = class {
 		let result;
 		try {
 			const sm = SessionManager.open(sessionFile);
-			const { loader: resourceLoader } = await this.buildResourceLoader(params.cwd, params);
+			const { loader: resourceLoader } = await this.buildResourceLoader(params.cwd, params, { resolveCwdMode: false });
 			result = await createAgentSession({
 				cwd: params.cwd,
 				sessionManager: sm,
@@ -2690,7 +2755,7 @@ var PiAcpAgent = class {
 		let result;
 		try {
 			const sm = SessionManager.forkFrom(sourceFile, params.cwd);
-			const { loader: resourceLoader } = await this.buildResourceLoader(params.cwd, params);
+			const { loader: resourceLoader } = await this.buildResourceLoader(params.cwd, params, { resolveCwdMode: false });
 			result = await createAgentSession({
 				cwd: params.cwd,
 				sessionManager: sm,
@@ -3327,4 +3392,4 @@ async function runDaemon() {
 //#endregion
 export { runDaemon };
 
-//# sourceMappingURL=daemon-D6QKWz5C.mjs.map
+//# sourceMappingURL=daemon-BErbUhcE.mjs.map