@sns-myagent/cli 0.2.0

package/src/internal-urls/agent-protocol.ts

@@ -0,0 +1,146 @@
+/**
+ * Protocol handler for agent:// URLs.
+ *
+ * Resolves agent output IDs against the artifacts directories of every active
+ * session. Parents and subagents share outputs via this registry: a subagent
+ * can read its parent's output IDs because both sessions are registered in
+ * the shared context.
+ *
+ * URL forms:
+ * - agent://<id> - Full output content
+ * - agent://<id>/<path> - JSON extraction via path form
+ * - agent://<id>?q=<query> - JSON extraction via query form
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { applyQuery, pathToQuery } from "./json-query";
+import { artifactsDirsFromRegistry } from "./registry-helpers";
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+
+/**
+ * Handler for agent:// URLs.
+ *
+ * Resolves output IDs like "reviewer_0" to their artifact files,
+ * with optional JSON extraction.
+ */
+export class AgentProtocolHandler implements ProtocolHandler {
+	readonly scheme = "agent";
+	readonly immutable = true;
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const outputId = url.rawHost || url.hostname;
+		if (!outputId) {
+			throw new Error("agent:// URL requires an output ID: agent://<id>");
+		}
+
+		const urlPath = url.pathname;
+		const queryParam = url.searchParams.get("q");
+		const hasPathExtraction = urlPath && urlPath !== "/" && urlPath !== "";
+		const hasQueryExtraction = queryParam !== null && queryParam !== "";
+
+		if (hasPathExtraction && hasQueryExtraction) {
+			throw new Error("agent:// URL cannot combine path extraction with ?q=");
+		}
+
+		const dirs = artifactsDirsFromRegistry();
+
+		if (dirs.length === 0) {
+			throw new Error("No session - agent outputs unavailable");
+		}
+
+		let foundPath: string | undefined;
+		let anyDirExists = false;
+		const availableIds = new Set<string>();
+
+		for (const dir of dirs) {
+			try {
+				await fs.stat(dir);
+				anyDirExists = true;
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			const candidate = path.join(dir, `${outputId}.md`);
+			try {
+				await fs.stat(candidate);
+				foundPath = candidate;
+				break;
+			} catch (err) {
+				if (!isEnoent(err)) throw err;
+				try {
+					const files = await fs.readdir(dir);
+					for (const f of files) {
+						if (f.endsWith(".md")) availableIds.add(f.replace(/\.md$/, ""));
+					}
+				} catch {
+					// Listing failures are non-fatal; continue searching.
+				}
+			}
+		}
+
+		if (!anyDirExists) {
+			throw new Error("No artifacts directory found");
+		}
+
+		if (!foundPath) {
+			const availableStr = availableIds.size > 0 ? [...availableIds].join(", ") : "none";
+			throw new Error(`Not found: ${outputId}\nAvailable: ${availableStr}`);
+		}
+
+		const rawContent = await Bun.file(foundPath).text();
+		const notes: string[] = [];
+		let content = rawContent;
+		let contentType: InternalResource["contentType"] = "text/markdown";
+
+		if (hasPathExtraction || hasQueryExtraction) {
+			let jsonValue: unknown;
+			try {
+				jsonValue = JSON.parse(rawContent);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new Error(`Output ${outputId} is not valid JSON: ${message}`);
+			}
+
+			const query = hasPathExtraction ? pathToQuery(urlPath) : queryParam!;
+			if (query) {
+				const extracted = applyQuery(jsonValue, query);
+				try {
+					content = JSON.stringify(extracted, null, 2) ?? "null";
+				} catch {
+					content = String(extracted);
+				}
+				notes.push(`Extracted: ${query}`);
+			} else {
+				content = JSON.stringify(jsonValue, null, 2);
+			}
+			contentType = "application/json";
+		}
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: foundPath,
+			notes,
+		};
+	}
+
+	async complete(): Promise<UrlCompletion[]> {
+		const ids = new Set<string>();
+		for (const dir of artifactsDirsFromRegistry()) {
+			let files: string[];
+			try {
+				files = await fs.readdir(dir);
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			for (const f of files) {
+				if (f.endsWith(".md")) ids.add(f.slice(0, -3));
+			}
+		}
+		return [...ids].sort().map(value => ({ value }));
+	}
+}

package/src/internal-urls/artifact-protocol.ts

@@ -0,0 +1,107 @@
+/**
+ * Protocol handler for artifact:// URLs.
+ *
+ * Resolves artifact IDs against the artifacts directories of every active
+ * session. Unlike agent://, artifacts are raw text with no JSON extraction.
+ *
+ * URL form:
+ * - artifact://<id> - Full artifact content
+ *
+ * Pagination is handled by the read tool via offset/limit parameters.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { artifactsDirsFromRegistry } from "./registry-helpers";
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
+
+export class ArtifactProtocolHandler implements ProtocolHandler {
+	readonly scheme = "artifact";
+	readonly immutable = true;
+
+	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
+		const id = url.rawHost || url.hostname;
+		if (!id) {
+			throw new Error("artifact:// URL requires a numeric ID: artifact://0");
+		}
+		if (!/^\d+$/.test(id)) {
+			throw new Error(`artifact:// ID must be numeric, got: ${id}`);
+		}
+
+		// Artifact ids are per-session counters; in multi-session hosts the same
+		// id exists in several dirs. Pin resolution to the calling session's
+		// artifacts dir first so `artifact://3` means *this* session's #3.
+		const dirs = artifactsDirsFromRegistry();
+		const pinnedDir = context?.localProtocolOptions?.getArtifactsDir?.() ?? null;
+		if (pinnedDir) {
+			const pinnedIndex = dirs.indexOf(pinnedDir);
+			if (pinnedIndex >= 0) dirs.splice(pinnedIndex, 1);
+			dirs.unshift(pinnedDir);
+		}
+
+		if (dirs.length === 0) {
+			throw new Error("No session - artifacts unavailable");
+		}
+
+		let foundPath: string | undefined;
+		let anyDirExists = false;
+		const availableIds = new Set<string>();
+
+		for (const dir of dirs) {
+			let files: string[];
+			try {
+				files = await fs.readdir(dir);
+				anyDirExists = true;
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			const match = files.find(f => f.startsWith(`${id}.`));
+			if (match) {
+				foundPath = path.join(dir, match);
+				break;
+			}
+			for (const f of files) {
+				const m = f.match(/^(\d+)\./);
+				if (m) availableIds.add(m[1]);
+			}
+		}
+
+		if (!anyDirExists) {
+			throw new Error("No artifacts directory found");
+		}
+
+		if (!foundPath) {
+			const sorted = [...availableIds].sort((a, b) => Number(a) - Number(b));
+			const availableStr = sorted.length > 0 ? sorted.join(", ") : "none";
+			throw new Error(`Artifact ${id} not found. Available: ${availableStr}`);
+		}
+
+		const content = await Bun.file(foundPath).text();
+		return {
+			url: url.href,
+			content,
+			contentType: "text/plain",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: foundPath,
+		};
+	}
+
+	async complete(): Promise<UrlCompletion[]> {
+		const ids = new Set<string>();
+		for (const dir of artifactsDirsFromRegistry()) {
+			let files: string[];
+			try {
+				files = await fs.readdir(dir);
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			for (const f of files) {
+				const m = f.match(/^(\d+)\./);
+				if (m) ids.add(m[1]!);
+			}
+		}
+		return [...ids].sort((a, b) => Number(a) - Number(b)).map(value => ({ value }));
+	}
+}

package/src/internal-urls/docs-index.generated.txt

@@ -0,0 +1,2 @@
+["configuration.md","faq.md","installation.md","memory.md","tbm.md","terminal-ui.md","troubleshooting.md"]
+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

package/src/internal-urls/docs-index.ts

@@ -0,0 +1,102 @@
+/**
+ * Harness documentation index for the `omp://` protocol.
+ *
+ * Compiled binaries and the prepacked npm bundle inline a compressed index from
+ * `docs-index.generated.txt` (populated by `scripts/generate-docs-index.ts
+ * --generate` at build time). The format is two lines:
+ *   1. a plain JSON array of the sorted doc file names, and
+ *   2. a base64 gzip blob of the index-aligned doc bodies (`string[]`).
+ * Listing/completion (`getDocFilenames`) parses only the small first line and
+ * never inflates the blob; the bodies are gunzipped off the event loop (via the
+ * async `node:zlib` threadpool) lazily, once, on the first actual read. When the
+ * placeholder is empty (dev tree, source checkout), the index is read from the
+ * repo `docs/` directory on disk instead.
+ */
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { gunzip } from "node:zlib";
+import { Glob } from "bun";
+import docsEmbed from "./docs-index.generated.txt";
+
+const gunzipAsync = promisify(gunzip);
+
+export interface DocsIndex {
+	/** Sorted documentation file names, relative to `docs/`. */
+	readonly filenames: readonly string[];
+	/** Resolve a doc body by path; inflates the embedded bodies off-thread, lazily, on first call. */
+	getBody(relativePath: string): Promise<string | undefined>;
+}
+
+/**
+ * Decode a populated two-line embed (`<filenames JSON>\n<base64 gzip of bodies>`)
+ * into a lazily-inflating index, or `null` when there is no newline separator
+ * (the empty placeholder, or a malformed payload — the caller decides which).
+ * Reading `filenames` never touches the blob; the bodies are gunzipped off the
+ * event loop into a path→content table on the first `getBody` call, and that
+ * work is shared across concurrent reads.
+ */
+export function decodeDocsIndex(embed: string): DocsIndex | null {
+	const newline = embed.indexOf("\n");
+	if (newline === -1) return null;
+	const filenames = JSON.parse(embed.slice(0, newline)) as string[];
+	let bodies: Promise<Record<string, string>> | undefined;
+	return {
+		filenames,
+		getBody(relativePath: string): Promise<string | undefined> {
+			bodies ??= (async () => {
+				const inflated = await gunzipAsync(Buffer.from(embed.slice(newline + 1), "base64"));
+				const decoded = JSON.parse(inflated.toString("utf8")) as string[];
+				const map: Record<string, string> = {};
+				for (let i = 0; i < filenames.length; i++) map[filenames[i]] = decoded[i];
+				return map;
+			})();
+			return bodies.then(map => map[relativePath]);
+		},
+	};
+}
+
+/** Dev tree / source checkout: build the index from the repo `docs/` directory. */
+function readDocsFromDisk(): DocsIndex {
+	const docsDir = path.resolve(import.meta.dir, "../../../../docs");
+	const filenames: string[] = [];
+	const bodies: Record<string, string> = {};
+	for (const relativePath of new Glob("**/*.md").scanSync(docsDir)) {
+		const normalized = relativePath.split(path.sep).join("/");
+		filenames.push(normalized);
+		bodies[normalized] = readFileSync(path.join(docsDir, relativePath), "utf8");
+	}
+	filenames.sort();
+	return { filenames, getBody: relativePath => Promise.resolve(bodies[relativePath]) };
+}
+
+let index: DocsIndex | undefined;
+function getIndex(): DocsIndex {
+	if (index !== undefined) return index;
+	// Empty placeholder → dev tree / source checkout: read docs from disk.
+	if (docsEmbed.length === 0) {
+		index = readDocsFromDisk();
+		return index;
+	}
+	// Populated embed in compiled binaries / npm bundle. A non-empty payload with
+	// no newline is a broken build (truncated/corrupt embed), not a placeholder.
+	const decoded = decodeDocsIndex(docsEmbed);
+	if (decoded === null) {
+		throw new Error(
+			"Malformed embedded docs index (docs-index.generated.txt): non-empty payload without a newline separator. " +
+				"Rebuild with `bun --cwd=packages/coding-agent scripts/generate-docs-index.ts --generate`.",
+		);
+	}
+	index = decoded;
+	return index;
+}
+
+/** Sorted list of available documentation file names (relative to `docs/`). */
+export function getDocFilenames(): readonly string[] {
+	return getIndex().filenames;
+}
+
+/** Resolve a documentation file's content, or `undefined` when not found. */
+export function getEmbeddedDoc(relativePath: string): Promise<string | undefined> {
+	return getIndex().getBody(relativePath);
+}

package/src/internal-urls/filesystem-resource.ts

@@ -0,0 +1,34 @@
+import * as fs from "node:fs/promises";
+import type { InternalResource } from "./types";
+
+/**
+ * Builds a text resource for a filesystem directory resolved by an internal URL handler.
+ *
+ * The resource is flagged immutable so the read tool never mints hashline edit
+ * anchors against a directory listing — only file resources from the same
+ * handler stay editable.
+ */
+export async function buildDirectoryResource(
+	url: string,
+	directoryPath: string,
+	notes?: string[],
+): Promise<InternalResource> {
+	const entries = await fs.readdir(directoryPath, { withFileTypes: true });
+	entries.sort((a, b) => {
+		const directoryOrder = Number(b.isDirectory()) - Number(a.isDirectory());
+		return directoryOrder || a.name.localeCompare(b.name);
+	});
+	const content =
+		entries.length === 0
+			? "(empty directory)"
+			: entries.map(e => `${e.name}${e.isDirectory() ? "/" : ""}`).join("\n");
+	return {
+		url,
+		content,
+		contentType: "text/plain",
+		size: Buffer.byteLength(content, "utf-8"),
+		sourcePath: directoryPath,
+		immutable: true,
+		...(notes ? { notes } : {}),
+	};
+}

package/src/internal-urls/history-protocol.ts

@@ -0,0 +1,118 @@
+/**
+ * Protocol handler for history:// URLs.
+ *
+ * Exposes agent transcripts as concise markdown. Live refs render from the
+ * in-memory message array; parked refs (session disposed, sessionFile
+ * retained) load read-only from the JSONL session file — no writer, no lock.
+ *
+ * URL forms:
+ * - history:// - Index of all registry agents (id, status, kind, last activity)
+ * - history://<agentId> - Concise markdown transcript of that agent
+ */
+import type { AgentRef } from "../registry/agent-registry";
+import { AgentRegistry } from "../registry/agent-registry";
+import { formatSessionHistoryMarkdown } from "../session/session-history-format";
+import { loadSessionMessagesReadOnly } from "../session/session-loader";
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+
+/** Humanize a last-activity timestamp as `Ns/Nm/Nh/Nd ago`. */
+function formatAgo(timestamp: number): string {
+	const diffMs = Math.max(0, Date.now() - timestamp);
+	const secs = Math.floor(diffMs / 1000);
+	if (secs < 60) return `${secs}s ago`;
+	const mins = Math.floor(secs / 60);
+	if (mins < 60) return `${mins}m ago`;
+	const hours = Math.floor(mins / 60);
+	if (hours < 24) return `${hours}h ago`;
+	return `${Math.floor(hours / 24)}d ago`;
+}
+
+/**
+ * Handler for history:// URLs.
+ *
+ * Resolves agent ids against the global AgentRegistry, serving transcripts
+ * for both live and parked agents.
+ */
+export class HistoryProtocolHandler implements ProtocolHandler {
+	readonly scheme = "history";
+	readonly immutable = false;
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const agentId = url.rawHost || url.hostname;
+		const registry = AgentRegistry.global();
+		// Advisor transcripts are observability-only — surfaced in the Agent Hub, never
+		// in the agent-facing roster. Hide them from the index, lookup, and completions.
+		const visible = registry.list().filter(ref => ref.kind !== "advisor");
+
+		if (!agentId) {
+			const content = this.#renderIndex(visible);
+			return {
+				url: url.href,
+				content,
+				contentType: "text/markdown",
+				size: Buffer.byteLength(content, "utf-8"),
+			};
+		}
+
+		let ref = registry.get(agentId);
+		if (ref?.kind === "advisor") ref = undefined;
+		if (!ref) {
+			// Case-insensitive fallback: agent ids are human-typed (e.g. AuthLoader).
+			const lower = agentId.toLowerCase();
+			ref = visible.find(candidate => candidate.id.toLowerCase() === lower);
+		}
+		if (!ref) {
+			const known = visible.map(candidate => candidate.id);
+			const knownStr = known.length > 0 ? known.join(", ") : "none";
+			throw new Error(`Unknown agent: ${agentId}\nKnown agents: ${knownStr}\nList all with history://`);
+		}
+
+		const notes: string[] = [];
+		let messages: unknown[];
+		if (ref.session) {
+			messages = ref.session.messages;
+			notes.push("Source: live session");
+		} else if (ref.sessionFile) {
+			messages = await loadSessionMessagesReadOnly(ref.sessionFile);
+			notes.push(`Source: session file (read-only, ${ref.status})`);
+		} else {
+			throw new Error(`Agent ${ref.id} has no transcript: session is gone and no session file was retained`);
+		}
+
+		const content = formatSessionHistoryMarkdown(messages, { title: `${ref.id} (${ref.status})` });
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: ref.sessionFile ?? undefined,
+			notes,
+		};
+	}
+
+	#renderIndex(refs: AgentRef[]): string {
+		const lines: string[] = ["# Agents", ""];
+		if (refs.length === 0) {
+			lines.push("No agents registered.");
+			return `${lines.join("\n")}\n`;
+		}
+		lines.push("| id | status | kind | parent | last activity |", "|---|---|---|---|---|");
+		for (const ref of refs) {
+			lines.push(
+				`| ${ref.id} | ${ref.status} | ${ref.kind} | ${ref.parentId ?? "—"} | ${formatAgo(ref.lastActivity)} |`,
+			);
+		}
+		lines.push("", "Read a transcript with `read history://<id>`.");
+		return `${lines.join("\n")}\n`;
+	}
+
+	async complete(): Promise<UrlCompletion[]> {
+		return AgentRegistry.global()
+			.list()
+			.filter(ref => ref.kind !== "advisor")
+			.map(ref => ({
+				value: ref.id,
+				description: `${ref.status} · ${ref.kind}${ref.parentId ? ` · parent ${ref.parentId}` : ""}`,
+			}));
+	}
+}

package/src/internal-urls/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Internal URL routing system for internal protocols like agent://, memory://,
+ * skill://, mcp://, and local://.
+ *
+ * One process-global `InternalUrlRouter` is shared across sessions. Handlers
+ * are stateless; they pull whatever they need (active skills/rules, active
+ * MCP/async managers, AgentRegistry-listed sessions) from the owning module
+ * on each resolve call.
+ */
+
+export * from "./agent-protocol";
+export * from "./artifact-protocol";
+export * from "./history-protocol";
+export * from "./issue-pr-protocol";
+export * from "./json-query";
+export * from "./local-protocol";
+export * from "./mcp-protocol";
+export * from "./memory-protocol";
+export * from "./omp-protocol";
+export * from "./parse";
+export * from "./router";
+export * from "./rule-protocol";
+export * from "./skill-protocol";
+export type * from "./types";
+export * from "./vault-protocol";