@danypops/pi-packed 0.5.1 → 0.5.3

package/README.md

@@ -3,7 +3,7 @@
 Package service for the [Pi](https://github.com/earendil-works/pi) agent —
 DNF-style package management that both **you** and the **agent** can use.
 
-The agent gets native tools (`pkg_search`, `pkg_info`, `pkg_install`); you get
+The agent gets native tools (`pkg_search`, `pkg_info`, `pkg_install`, `pkg_update`, and `pkg_remove`); you get
 the `packed` CLI and an interactive `/packages` TUI. The extension is a thin,
 Node-compatible client. Registry access, SQLite, and package execution remain
 inside the supervised Bun daemon.
@@ -66,6 +66,16 @@ Guarded CLI mutations require `--approve` under the secure default. This is pi-p
 Failures use exit code 1 and `{ "ok": false, ... , "error": "..." }` with
 credential-safe diagnostics. Usage errors use exit code 2.
 
+## Native tool presentation
+
+Native tools keep three output contracts independent:
+
+- model-facing `content` is concise, credential-safe, and capped at 2,000 characters;
+- renderer-facing `details` uses a versioned bounded package DTO and never retains raw npm metadata or manifest values;
+- CLI human output and `--json` remain presenters over daemon DTOs and do not parse either native-tool channel.
+
+Calls and results have themed collapsed and expanded renderers. Missing or legacy details fall back to model content, while daemon and execution failures are thrown through Pi's native error channel. Package approval refusal remains a normal `cancelled` or `denied` outcome.
+
 ## Service API
 
 Every route requires the bearer token stored in the private state directory.

package/extension/src/packed.ts

@@ -3,14 +3,18 @@
  *
  * Pi's extension runtime is Node-compatible and does not guarantee a global
  * `Bun`. All registry reads, SQLite access, and package mutations therefore
- * stay inside the supervised Bun daemon. The seam reconnects for every call so
- * a restarted daemon cannot leave a stale port/token client cached in Pi.
+ * stay inside the supervised Bun daemon. A restarted daemon binds a new
+ * port/token, which would otherwise leave a stale cached client behind for
+ * the rest of the Pi session -- daemon-kit's createRetryingClient detects
+ * that on the failing call itself and reconnects, so the happy path reuses
+ * one connected client instead of reconnecting on every single operation.
  */
+import { createRetryingClient } from "@danypops/daemon-kit/pi-client";
 import type { PackageDaemonPort as ClientPackageDaemonPort } from "../../src/client.ts";
-import type { InstalledPkg, Pkg, PkgInfo, UpdateEntry } from "../../src/ports.ts";
+import type { InstalledPkg, Pkg, PkgInfo, UpdateEntry, UpdateOutcome } from "../../src/ports.ts";
 import type { MutationApproval, SecuritySettings } from "../../src/security.ts";
 
-export type { InstalledPkg, UpdateEntry };
+export type { InstalledPkg, UpdateEntry, UpdateOutcome };
 export type PackageInfo = PkgInfo;
 export type PackageDaemonPort = ClientPackageDaemonPort;
 
@@ -30,7 +34,7 @@ export interface Natives {
 	setMutationApproval(value: MutationApproval, approved?: boolean): Promise<SecuritySettings>;
 	install(source: string, approved?: boolean): Promise<string>;
 	remove(name: string, approved?: boolean): Promise<string>;
-	update(source: string, approved?: boolean): Promise<string>;
+	update(source: string, approved?: boolean): Promise<UpdateOutcome>;
 }
 
 export type PackageDaemonConnector = () => Promise<PackageDaemonPort>;
@@ -44,28 +48,18 @@ async function connectDefaultDaemon(): Promise<PackageDaemonPort> {
 }
 
 export async function createNatives(connect: PackageDaemonConnector = connectDefaultDaemon): Promise<Natives> {
-	async function call<T>(operation: (daemon: PackageDaemonPort) => Promise<T>): Promise<T> {
-		let lastError: unknown;
-		for (let attempt = 0; attempt < 2; attempt += 1) {
-			try {
-				return await operation(await connect());
-			} catch (error) {
-				lastError = error;
-			}
-		}
-		throw lastError instanceof Error ? lastError : new Error(String(lastError));
-	}
+	const client = createRetryingClient(connect, { label: "pi-packed" });
 
 	return {
-		search: (query, limit) => call((daemon) => daemon.search(query, limit)),
-		searchOffline: (query, limit) => call((daemon) => daemon.search(query, limit, true)),
-		info: (name) => call((daemon) => daemon.info(name)),
-		installed: () => call((daemon) => daemon.installed()),
-		updates: () => call((daemon) => daemon.updates()),
-		security: () => call((daemon) => daemon.security()),
-		setMutationApproval: (value, approved) => call((daemon) => daemon.setMutationApproval(value, approved)),
-		install: (source, approved) => call((daemon) => daemon.install(source, approved)),
-		remove: (name, approved) => call((daemon) => daemon.remove(name, approved)),
-		update: (source, approved) => call((daemon) => daemon.update(source, approved)),
+		search: (query, limit) => client.call((daemon) => daemon.search(query, limit)),
+		searchOffline: (query, limit) => client.call((daemon) => daemon.search(query, limit, true)),
+		info: (name) => client.call((daemon) => daemon.info(name)),
+		installed: () => client.call((daemon) => daemon.installed()),
+		updates: () => client.call((daemon) => daemon.updates()),
+		security: () => client.call((daemon) => daemon.security()),
+		setMutationApproval: (value, approved) => client.call((daemon) => daemon.setMutationApproval(value, approved)),
+		install: (source, approved) => client.call((daemon) => daemon.install(source, approved)),
+		remove: (name, approved) => client.call((daemon) => daemon.remove(name, approved)),
+		update: (source, approved) => client.call((daemon) => daemon.update(source, approved)),
 	};
 }

package/extension/src/tool-output.ts

@@ -0,0 +1,269 @@
+import type { AgentToolResult, Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	TOOL_COLLAPSED_PACKAGE_PREVIEW,
+	TOOL_DETAILS_MAX_CAPABILITIES,
+	TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS,
+	TOOL_DETAILS_MAX_KEYWORDS,
+	TOOL_DETAILS_MAX_OUTPUT_CHARACTERS,
+	TOOL_DETAILS_MAX_PACKAGES,
+	TOOL_DETAILS_MAX_SERIALIZED_CHARACTERS,
+	TOOL_MODEL_CONTENT_MAX_CHARACTERS,
+} from "../../src/constants.ts";
+import type { Pkg, PkgInfo } from "../../src/ports.ts";
+
+const DETAILS_VERSION = 1 as const;
+const MUTATION_OPERATIONS = new Set(["install", "update", "remove"]);
+const MUTATION_STATUSES = new Set(["succeeded", "cancelled", "denied"]);
+
+export interface PackageSummaryDetails {
+	name: string;
+	version: string;
+	description: string;
+}
+
+export interface SearchToolDetails {
+	version: typeof DETAILS_VERSION;
+	kind: "search";
+	operation: "search";
+	query: string;
+	total: number;
+	items: PackageSummaryDetails[];
+	truncated: boolean;
+}
+
+export interface InfoToolDetails {
+	version: typeof DETAILS_VERSION;
+	kind: "info";
+	operation: "info";
+	package: PackageSummaryDetails & {
+		homepage?: string;
+		repository?: string;
+		license?: string;
+		keywords: string[];
+		capabilities: string[];
+	};
+}
+
+export interface MutationToolDetails {
+	version: typeof DETAILS_VERSION;
+	kind: "mutation";
+	operation: "install" | "update" | "remove";
+	target: string;
+	status: "succeeded" | "cancelled" | "denied";
+	output: string;
+	reloadRequired: boolean;
+}
+
+export type PackageToolDetails = SearchToolDetails | InfoToolDetails | MutationToolDetails;
+
+export interface BoundedModelContent {
+	text: string;
+	truncated: boolean;
+	omitted: number;
+}
+
+function bounded(value: unknown, maximum: number): string {
+	const text = typeof value === "string" ? value : "";
+	return text.length <= maximum ? text : text.slice(0, maximum);
+}
+
+export function safePackageTarget(value: unknown): string {
+	const target = bounded(value, TOOL_DETAILS_MAX_OUTPUT_CHARACTERS);
+	const gitPrefix = target.startsWith("git+http://") || target.startsWith("git+https://") ? "git+" : "";
+	const candidate = gitPrefix ? target.slice(gitPrefix.length) : target;
+	if (!candidate.startsWith("http://") && !candidate.startsWith("https://")) return target;
+	try {
+		const url = new URL(candidate);
+		url.username = "";
+		url.password = "";
+		url.search = "";
+		url.hash = "";
+		const safe = url.toString().replace(/\/$/, candidate.endsWith("/") ? "/" : "");
+		return `${gitPrefix}${safe}`;
+	} catch {
+		return `${gitPrefix}https://[invalid-package-source]`;
+	}
+}
+
+function safeDisplayText(value: unknown, maximum: number): string {
+	const text = bounded(value, maximum);
+	return text.replace(/(?:git\+)?https?:\/\/[^\s]+/gu, (url) => safePackageTarget(url));
+}
+
+export function createModelContent(value: string): BoundedModelContent {
+	const safe = safeDisplayText(value, value.length);
+	if (safe.length <= TOOL_MODEL_CONTENT_MAX_CHARACTERS) {
+		return { text: safe, truncated: false, omitted: 0 };
+	}
+	let omitted = safe.length - TOOL_MODEL_CONTENT_MAX_CHARACTERS;
+	let marker = "";
+	let kept = 0;
+	for (let iteration = 0; iteration < 5; iteration += 1) {
+		const nextMarker = `\n[truncated ${omitted} characters]`;
+		const nextKept = Math.max(0, TOOL_MODEL_CONTENT_MAX_CHARACTERS - nextMarker.length);
+		const nextOmitted = safe.length - nextKept;
+		marker = nextMarker;
+		kept = nextKept;
+		if (nextOmitted === omitted) break;
+		omitted = nextOmitted;
+	}
+	return { text: `${safe.slice(0, kept)}${marker}`, truncated: true, omitted: safe.length - kept };
+}
+
+function packageSummary(pkg: Pkg): PackageSummaryDetails {
+	return {
+		name: bounded(pkg.name, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS),
+		version: bounded(pkg.version, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS),
+		description: bounded(pkg.description, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS),
+	};
+}
+
+export function createSearchDetails(query: string, total: number, packages: Pkg[]): SearchToolDetails {
+	return {
+		version: DETAILS_VERSION,
+		kind: "search",
+		operation: "search",
+		query: bounded(query, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS),
+		total: Number.isFinite(total) ? Math.max(0, Math.floor(total)) : packages.length,
+		items: packages.slice(0, TOOL_DETAILS_MAX_PACKAGES).map(packageSummary),
+		truncated: packages.length > TOOL_DETAILS_MAX_PACKAGES || total > packages.length,
+	};
+}
+
+export function createInfoDetails(info: PkgInfo): InfoToolDetails {
+	return {
+		version: DETAILS_VERSION,
+		kind: "info",
+		operation: "info",
+		package: {
+			...packageSummary(info),
+			...(info.homepage ? { homepage: safePackageTarget(info.homepage) } : {}),
+			...(info.repository ? { repository: safePackageTarget(info.repository) } : {}),
+			...(info.license ? { license: bounded(info.license, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS) } : {}),
+			keywords: (info.keywords ?? []).slice(0, TOOL_DETAILS_MAX_KEYWORDS).map((keyword) => bounded(keyword, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS)),
+			capabilities: Object.keys(info.pi ?? {}).slice(0, TOOL_DETAILS_MAX_CAPABILITIES).map((name) => bounded(name, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS)),
+		},
+	};
+}
+
+export function createMutationDetails(
+	operation: MutationToolDetails["operation"],
+	target: string,
+	status: MutationToolDetails["status"],
+	output: string,
+	// update's reloadRequired is not always "succeeded implies true" -- pi
+	// update exits 0 whether or not a pinned/already-latest package actually
+	// changed. Callers that know the real outcome (updatePackageWithPolicy)
+	// pass it explicitly; install/remove keep the old succeeded-implies-true
+	// default, which is accurate for them.
+	reloadRequired: boolean = operation === "update" && status === "succeeded",
+): MutationToolDetails {
+	return {
+		version: DETAILS_VERSION,
+		kind: "mutation",
+		operation,
+		target: safePackageTarget(target),
+		status,
+		output: safeDisplayText(output, TOOL_DETAILS_MAX_OUTPUT_CHARACTERS),
+		reloadRequired,
+	};
+}
+
+function isShortString(value: unknown, maximum = TOOL_DETAILS_MAX_OUTPUT_CHARACTERS): value is string {
+	return typeof value === "string" && value.length <= maximum;
+}
+
+export function parsePackageToolDetails(value: unknown): PackageToolDetails | undefined {
+	try {
+		if (!value || typeof value !== "object") return undefined;
+		if (JSON.stringify(value).length > TOOL_DETAILS_MAX_SERIALIZED_CHARACTERS) return undefined;
+		const candidate = value as Record<string, unknown>;
+		if (candidate.version !== DETAILS_VERSION || typeof candidate.kind !== "string") return undefined;
+		if (candidate.kind === "search") {
+			if (candidate.operation !== "search" || !isShortString(candidate.query, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS) || typeof candidate.total !== "number" || !Number.isSafeInteger(candidate.total) || candidate.total < 0 || typeof candidate.truncated !== "boolean") return undefined;
+			if (!Array.isArray(candidate.items) || candidate.items.length > TOOL_DETAILS_MAX_PACKAGES) return undefined;
+			if (!candidate.items.every((item) => isPackageSummary(item))) return undefined;
+			return value as SearchToolDetails;
+		}
+		if (candidate.kind === "info") {
+			if (candidate.operation !== "info" || !candidate.package || typeof candidate.package !== "object") return undefined;
+			const pkg = candidate.package as Record<string, unknown>;
+			if (!isPackageSummary(pkg) || !Array.isArray(pkg.keywords) || pkg.keywords.length > TOOL_DETAILS_MAX_KEYWORDS || !pkg.keywords.every((item) => isShortString(item, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS))) return undefined;
+			if (!Array.isArray(pkg.capabilities) || pkg.capabilities.length > TOOL_DETAILS_MAX_CAPABILITIES || !pkg.capabilities.every((item) => isShortString(item, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS))) return undefined;
+			for (const field of ["homepage", "repository", "license"] as const) {
+				if (pkg[field] !== undefined && !isShortString(pkg[field])) return undefined;
+			}
+			return value as InfoToolDetails;
+		}
+		if (candidate.kind === "mutation") {
+			if (typeof candidate.operation !== "string" || !MUTATION_OPERATIONS.has(candidate.operation)) return undefined;
+			if (typeof candidate.status !== "string" || !MUTATION_STATUSES.has(candidate.status)) return undefined;
+			if (!isShortString(candidate.target) || !isShortString(candidate.output) || typeof candidate.reloadRequired !== "boolean") return undefined;
+			return value as MutationToolDetails;
+		}
+	} catch {
+		return undefined;
+	}
+	return undefined;
+}
+
+function isPackageSummary(value: unknown): boolean {
+	if (!value || typeof value !== "object") return false;
+	const item = value as Record<string, unknown>;
+	return isShortString(item.name, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS)
+		&& isShortString(item.version, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS)
+		&& isShortString(item.description, TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS);
+}
+
+function contentFallback(result: AgentToolResult<unknown>): string {
+	return result.content.filter((item) => item.type === "text").map((item) => item.text).join("\n");
+}
+
+export function renderPackageToolCall(label: string, args: Record<string, unknown>, theme: Theme) {
+	const target = safePackageTarget(args.query ?? args.name ?? args.source ?? "");
+	return new Text(`${theme.fg("accent", label)}${target ? theme.fg("muted", ` · ${target}`) : ""}`, 0, 0);
+}
+
+export function renderPackageToolResult(
+	result: AgentToolResult<unknown>,
+	options: { expanded: boolean; isPartial: boolean },
+	theme: Theme,
+	context: { isPartial: boolean },
+) {
+	if (options.isPartial || context.isPartial) return new Text(theme.fg("muted", "Working…"), 0, 0);
+	const details = parsePackageToolDetails(result.details);
+	if (!details) return new Text(contentFallback(result), 0, 0);
+	return {
+		render(width: number): string[] {
+			const safeWidth = Math.max(1, width);
+			if (details.kind === "search") {
+				const shown = options.expanded ? details.items : details.items.slice(0, TOOL_COLLAPSED_PACKAGE_PREVIEW);
+				const heading = `${theme.bold(String(details.total))} packages · showing ${details.items.length}${details.truncated ? " · bounded" : ""}`;
+				const rows = shown.map((pkg) => truncateToWidth(`${theme.fg("accent", `${pkg.name}@${pkg.version}`)}${options.expanded && pkg.description ? ` — ${pkg.description}` : ""}`, safeWidth));
+				if (!options.expanded && details.items.length > shown.length) rows.push(theme.fg("muted", `… ${details.items.length - shown.length} more`));
+				return [truncateToWidth(heading, safeWidth), ...rows];
+			}
+			if (details.kind === "info") {
+				const pkg = details.package;
+				const lines = [theme.bold(`${pkg.name}@${pkg.version}`), pkg.description];
+				if (options.expanded) {
+					if (pkg.license) lines.push(`license: ${pkg.license}`);
+					if (pkg.repository) lines.push(`repository: ${pkg.repository}`);
+					if (pkg.homepage) lines.push(`homepage: ${pkg.homepage}`);
+					if (pkg.capabilities.length) lines.push(`provides: ${pkg.capabilities.join(", ")}`);
+					if (pkg.keywords.length) lines.push(`keywords: ${pkg.keywords.join(", ")}`);
+				}
+				return lines.filter(Boolean).map((line) => truncateToWidth(line, safeWidth));
+			}
+			const statusColor = details.status === "succeeded" ? "success" : "warning";
+			const lines = [
+				`${theme.fg(statusColor, details.status === "succeeded" ? "✓" : "○")} ${details.operation} ${details.target}`,
+			];
+			if (options.expanded && details.output) lines.push(details.output);
+			if (details.reloadRequired) lines.push(theme.fg("warning", "Reload Pi with /reload to activate the update."));
+			return lines.map((line) => truncateToWidth(line, safeWidth));
+		},
+		invalidate() {},
+	};
+}

package/extension/src/tools.ts

@@ -3,9 +3,18 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { packagePermissionDecision, type PackageOperation } from "../../src/security.ts";
 import type { Natives } from "./packed.js";
+import {
+	createInfoDetails,
+	createModelContent,
+	createMutationDetails,
+	createSearchDetails,
+	renderPackageToolCall,
+	renderPackageToolResult,
+	type PackageToolDetails,
+} from "./tool-output.js";
 
-function text(t: string, details: Record<string, unknown> = {}) {
-	return { content: [{ type: "text" as const, text: t }], details };
+function text(value: string, details: PackageToolDetails) {
+	return { content: [{ type: "text" as const, text: createModelContent(value).text }], details };
 }
 
 type ApprovalContext = {
@@ -18,7 +27,7 @@ export async function approvePackageOperation(
 	command: string,
 	natives: Pick<Natives, "security">,
 	ctx: ApprovalContext,
-): Promise<{ allowed: boolean; approved: boolean; message?: string }> {
+): Promise<{ allowed: boolean; approved: boolean; reason?: "cancelled" | "denied"; message?: string }> {
 	const settings = await natives.security();
 	const decision = packagePermissionDecision(settings, operation);
 	if (!decision.approvalRequired) return { allowed: true, approved: false };
@@ -26,6 +35,7 @@ export async function approvePackageOperation(
 		return {
 			allowed: false,
 			approved: false,
+			reason: "denied",
 			message: `${operation} requires interactive approval; change mutationApproval in /packed only to deliberately opt out.`,
 		};
 	}
@@ -33,7 +43,7 @@ export async function approvePackageOperation(
 		`${operation[0]!.toUpperCase()}${operation.slice(1)} Pi package`,
 		`Run: ${command}\n\nThis operation can execute package code or mutate Pi settings/install roots. Continue?`,
 	);
-	return approved ? { allowed: true, approved: true } : { allowed: false, approved: false, message: `${operation} cancelled by user.` };
+	return approved ? { allowed: true, approved: true } : { allowed: false, approved: false, reason: "cancelled", message: `${operation} cancelled by user.` };
 }
 
 export async function installPackageWithPolicy(
@@ -41,14 +51,13 @@ export async function installPackageWithPolicy(
 	natives: Pick<Natives, "security" | "install">,
 	ctx: ApprovalContext,
 ) {
-	try {
-		const approval = await approvePackageOperation("install", `pi install ${source}`, natives, ctx);
-		if (!approval.allowed) return text(approval.message ?? "install denied");
-		const out = await natives.install(source, approval.approved);
-		return text(out || `Installed ${source}. Reload with /reload to activate.`);
-	} catch (error) {
-		return text(`install failed: ${error instanceof Error ? error.message : error}`);
+	const approval = await approvePackageOperation("install", `pi install ${source}`, natives, ctx);
+	if (!approval.allowed) {
+		const output = approval.message ?? "install denied";
+		return text(output, createMutationDetails("install", source, approval.reason ?? "denied", output));
 	}
+	const output = await natives.install(source, approval.approved) || `Installed ${source}. Reload with /reload to activate.`;
+	return text(output, createMutationDetails("install", source, "succeeded", output));
 }
 
 export async function updatePackageWithPolicy(
@@ -56,14 +65,23 @@ export async function updatePackageWithPolicy(
 	natives: Pick<Natives, "security" | "update">,
 	ctx: ApprovalContext,
 ) {
-	try {
-		const approval = await approvePackageOperation("update", `pi update --extension ${source}`, natives, ctx);
-		if (!approval.allowed) return text(approval.message ?? "update denied");
-		const out = await natives.update(source, approval.approved);
-		return text(`${out || `Updated ${source}.`} Reload with /reload to activate.`);
-	} catch (error) {
-		return text(`update failed: ${error instanceof Error ? error.message : error}`);
+	const approval = await approvePackageOperation("update", `pi update --extension ${source}`, natives, ctx);
+	if (!approval.allowed) {
+		const output = approval.message ?? "update denied";
+		return text(output, createMutationDetails("update", source, approval.reason ?? "denied", output));
 	}
+	const outcome = await natives.update(source, approval.approved);
+	if (outcome.alreadyUpToDate) {
+		const version = outcome.currentVersion ?? outcome.previousVersion;
+		const reason = outcome.pinned
+			? `pinned to ${version ?? "an exact version"} -- pi update intentionally leaves pinned packages unchanged; reinstall with a different (or no) version to move off the pin`
+			: `already up to date${version ? ` at ${version}` : ""}`;
+		const message = `${source} is ${reason}.`;
+		return text(message, createMutationDetails("update", source, "succeeded", outcome.output || message, false));
+	}
+	const transition = outcome.previousVersion && outcome.currentVersion ? ` (${outcome.previousVersion} → ${outcome.currentVersion})` : "";
+	const message = `${outcome.output || `Updated ${source}.`}${transition} Reload with /reload to activate.`;
+	return text(message, createMutationDetails("update", source, "succeeded", outcome.output || message, true));
 }
 
 export async function removePackageWithPolicy(
@@ -71,14 +89,13 @@ export async function removePackageWithPolicy(
 	natives: Pick<Natives, "security" | "remove">,
 	ctx: ApprovalContext,
 ) {
-	try {
-		const approval = await approvePackageOperation("remove", `pi remove npm:${name}`, natives, ctx);
-		if (!approval.allowed) return text(approval.message ?? "remove denied");
-		const out = await natives.remove(name, approval.approved);
-		return text(out || `Removed ${name}. Reload with /reload to deactivate.`);
-	} catch (error) {
-		return text(`remove failed: ${error instanceof Error ? error.message : error}`);
+	const approval = await approvePackageOperation("remove", `pi remove npm:${name}`, natives, ctx);
+	if (!approval.allowed) {
+		const output = approval.message ?? "remove denied";
+		return text(output, createMutationDetails("remove", name, approval.reason ?? "denied", output));
 	}
+	const output = await natives.remove(name, approval.approved) || `Removed ${name}. Reload with /reload to deactivate.`;
+	return text(output, createMutationDetails("remove", name, "succeeded", output));
 }
 
 export function registerTools(pi: ExtensionAPI, natives: Natives): void {
@@ -90,14 +107,17 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 			query: Type.String({ description: "Search terms, e.g. 'lsp' or 'telegram'" }),
 			limit: Type.Optional(Type.Number({ description: "Max results (default 10, max 50)" })),
 		}),
+		renderCall(args, theme) { return renderPackageToolCall("Search packages", args, theme); },
+		renderResult(result, options, theme, context) { return renderPackageToolResult(result, options, theme, context); },
 		async execute(_id, params) {
 			try {
-				const r = await natives.search(params.query, params.limit ?? 10);
-				if (r.results.length === 0) return text(`No Pi packages found for "${params.query}".`);
-				const lines = r.results.map((p, i) => `${i + 1}. ${p.name}@${p.version}\n   ${p.description ?? ""}`);
-				return text(`Found ${r.total} pi package(s) (showing ${r.results.length}):\n\n${lines.join("\n")}`, { results: r.results, total: r.total });
+				const response = await natives.search(params.query, params.limit ?? 10);
+				const details = createSearchDetails(params.query, response.total, response.results);
+				if (response.results.length === 0) return text(`No Pi packages found for "${params.query}".`, details);
+				const lines = response.results.map((pkg, index) => `${index + 1}. ${pkg.name}@${pkg.version}\n   ${pkg.description ?? ""}`);
+				return text(`Found ${response.total} pi package(s) (showing ${response.results.length}):\n\n${lines.join("\n")}`, details);
 			} catch (error) {
-				return text(`pkg_search failed: ${error instanceof Error ? error.message : error}`);
+				throw new Error(`pkg_search failed: ${error instanceof Error ? error.message : error}`);
 			}
 		},
 	});
@@ -107,6 +127,8 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 		label: "Pi Package Info",
 		description: "Show bounded metadata and declared Pi resources for one package.",
 		parameters: Type.Object({ name: Type.String({ description: "npm package name" }) }),
+		renderCall(args, theme) { return renderPackageToolCall("Package info", args, theme); },
+		renderResult(result, options, theme, context) { return renderPackageToolResult(result, options, theme, context); },
 		async execute(_id, params) {
 			try {
 				const info = await natives.info(params.name);
@@ -119,9 +141,9 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 					info.unpackedSize ? `size: ${(info.unpackedSize / 1024).toFixed(0)} KB` : "",
 					info.modified ? `modified: ${info.modified}` : "",
 				].filter(Boolean);
-				return text(lines.join("\n"), { info });
+				return text(lines.join("\n"), createInfoDetails(info));
 			} catch (error) {
-				return text(`pkg_info failed: ${error instanceof Error ? error.message : error}`);
+				throw new Error(`pkg_info failed: ${error instanceof Error ? error.message : error}`);
 			}
 		},
 	});
@@ -131,6 +153,8 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 		label: "Pi Package Install",
 		description: "Install a Pi package through the authenticated daemon. Operation-aware approval is secure by default.",
 		parameters: Type.Object({ source: Type.String({ description: "npm:, git:, or https source" }) }),
+		renderCall(args, theme) { return renderPackageToolCall("Install package", args, theme); },
+		renderResult(result, options, theme, context) { return renderPackageToolResult(result, options, theme, context); },
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			return installPackageWithPolicy(params.source, natives, ctx);
 		},
@@ -141,6 +165,8 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 		label: "Pi Package Update",
 		description: "Update one configured Pi package through Pi's documented update command. Operation-aware approval is secure by default.",
 		parameters: Type.Object({ source: Type.String({ description: "configured npm:, git:, or https source" }) }),
+		renderCall(args, theme) { return renderPackageToolCall("Update package", args, theme); },
+		renderResult(result, options, theme, context) { return renderPackageToolResult(result, options, theme, context); },
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			return updatePackageWithPolicy(params.source, natives, ctx);
 		},
@@ -151,6 +177,8 @@ export function registerTools(pi: ExtensionAPI, natives: Natives): void {
 		label: "Pi Package Remove",
 		description: "Remove an installed npm Pi package through the authenticated daemon. Operation-aware approval is secure by default.",
 		parameters: Type.Object({ name: Type.String({ description: "bare npm name, e.g. pi-lsp or @scope/pkg" }) }),
+		renderCall(args, theme) { return renderPackageToolCall("Remove package", args, theme); },
+		renderResult(result, options, theme, context) { return renderPackageToolResult(result, options, theme, context); },
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			return removePackageWithPolicy(params.name, natives, ctx);
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-packed",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Package service for the Pi agent: search/info/install/updates + /packages TUI, backed by a long-running Bun service",
   "type": "module",
   "bin": {
@@ -20,6 +20,9 @@
       "extension/src/index.ts"
     ]
   },
+  "dependencies": {
+    "@danypops/daemon-kit": "^0.4.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",

package/src/cli.ts

@@ -7,7 +7,7 @@
  */
 import { buildSearchQuery, clampLimit } from "./ports.ts";
 import type { Installer, Registry } from "./ports.ts";
-import { readInstalledPackages } from "./installed.ts";
+import { npmPackageName, readInstalledPackages } from "./installed.ts";
 import { checkUpdates } from "./watcher.ts";
 import { syncCatalog } from "./catalog.ts";
 import { openDb, searchLocal, catalogList, getSyncMeta, latestVersion, dbPath } from "./db.ts";
@@ -246,10 +246,18 @@ const commands: Record<string, { usage: string; run: Command }> = {
 			const source = pos[0] ?? "";
 			if (!SOURCE_RE.test(source)) return usageErr(`usage: ${commands["update"]!.usage}\n`);
 			try {
-				const output = await d.inst.update(source, { approved: flags.approved });
-				return flags.json
-					? ok(`${JSON.stringify({ ok: true, source, output, reloadRequired: true })}\n`)
-					: ok(`${output}\nReload Pi with /reload to activate the updated package.\n`);
+				const outcome = await d.inst.update(source, { approved: flags.approved });
+				if (flags.json) return ok(`${JSON.stringify({ ok: true, source, ...outcome })}\n`);
+				if (outcome.alreadyUpToDate) {
+					const version = outcome.currentVersion ?? outcome.previousVersion;
+					const reason = outcome.pinned
+						? `is pinned to ${version ?? "an exact version"} — pi update intentionally leaves pinned packages unchanged; run \`packed install npm:${npmPackageName(source) ?? source}\` to move off the pin`
+						: `is already up to date${version ? ` at ${version}` : ""}`;
+					return ok(`${source} ${reason}\n`);
+				}
+				const transition =
+					outcome.previousVersion && outcome.currentVersion ? ` (${outcome.previousVersion} → ${outcome.currentVersion})` : "";
+				return ok(`${outcome.output}${transition}\nReload Pi with /reload to activate the updated package.\n`);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
 				return flags.json

package/src/client.ts

@@ -5,7 +5,7 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { InstalledPkg, Installer, PkgInfo, Registry, SearchPage, UpdateEntry, UpdatesSnapshot } from "./ports.ts";
+import type { InstalledPkg, Installer, PkgInfo, Registry, SearchPage, UpdateEntry, UpdateOutcome, UpdatesSnapshot } from "./ports.ts";
 import { HttpRegistry } from "./registry.ts";
 import { DAEMON_HOST, PROBE_TIMEOUT_MS, REGISTRY_FETCH_TIMEOUT_MS, PORT_FILE, TOKEN_FILE } from "./constants.ts";
 import type { MutationApproval, SecuritySettings } from "./security.ts";
@@ -21,7 +21,7 @@ export interface PackageDaemonPort {
 	setMutationApproval(value: MutationApproval, approved?: boolean): Promise<SecuritySettings>;
 	install(source: string, approved?: boolean): Promise<string>;
 	remove(name: string, approved?: boolean): Promise<string>;
-	update(source: string, approved?: boolean): Promise<string>;
+	update(source: string, approved?: boolean): Promise<UpdateOutcome>;
 }
 
 interface MutationResponse {
@@ -29,6 +29,8 @@ interface MutationResponse {
 	output: string;
 }
 
+interface UpdateMutationResponse extends MutationResponse, Partial<Omit<UpdateOutcome, "output">> {}
+
 export class PackageDaemonError extends Error {
 	constructor(
 		message: string,
@@ -115,13 +117,23 @@ export class PackageDaemonClient implements PackageDaemonPort {
 		return result.output;
 	}
 
-	async update(source: string, approved = false): Promise<string> {
-		const result = await this.request<MutationResponse>("/update", {
+	async update(source: string, approved = false): Promise<UpdateOutcome> {
+		const result = await this.request<UpdateMutationResponse>("/update", {
 			method: "POST",
 			body: JSON.stringify({ source, approved }),
 		});
 		if (!result.ok) throw new PackageDaemonError(result.output || `failed to update ${source}`, "update");
-		return result.output;
+		// Older daemons (pre-honest-update) only ever sent {ok, output}; default
+		// to the historical "assume it changed" signal rather than claiming
+		// certainty the response doesn't actually contain.
+		return {
+			output: result.output,
+			reloadRequired: result.reloadRequired ?? true,
+			alreadyUpToDate: result.alreadyUpToDate ?? false,
+			pinned: result.pinned ?? false,
+			previousVersion: result.previousVersion,
+			currentVersion: result.currentVersion,
+		};
 	}
 }
 
@@ -139,7 +151,7 @@ export class PackageDaemonInstaller implements Installer {
 		return this.client.remove(source.slice(4), options?.approved);
 	}
 
-	update(source: string, options?: { approved?: boolean }): Promise<string> {
+	update(source: string, options?: { approved?: boolean }): Promise<UpdateOutcome> {
 		return this.client.update(source, options?.approved);
 	}
 }
@@ -165,7 +177,7 @@ export class DaemonBackedInstaller implements Installer {
 		return new PackageDaemonInstaller(await connectPackageDaemon(this.stateDirectory)).remove(source, options);
 	}
 
-	async update(source: string, options?: { approved?: boolean }): Promise<string> {
+	async update(source: string, options?: { approved?: boolean }): Promise<UpdateOutcome> {
 		return (await connectPackageDaemon(this.stateDirectory)).update(source, options?.approved);
 	}
 }

package/src/constants.ts

@@ -12,6 +12,16 @@ export const SEARCH_MAX_LIMIT = 50;
 export const SEARCH_PAGE_SIZE = 250; // npm registry max page size
 export const PI_PACKAGE_KEYWORD = "keywords:pi-package";
 
+// --- Native tool presentation bounds ---
+export const TOOL_MODEL_CONTENT_MAX_CHARACTERS = 2_000;
+export const TOOL_DETAILS_MAX_SERIALIZED_CHARACTERS = 32_000;
+export const TOOL_DETAILS_MAX_PACKAGES = 50;
+export const TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS = 240;
+export const TOOL_DETAILS_MAX_OUTPUT_CHARACTERS = 1_000;
+export const TOOL_DETAILS_MAX_KEYWORDS = 20;
+export const TOOL_DETAILS_MAX_CAPABILITIES = 12;
+export const TOOL_COLLAPSED_PACKAGE_PREVIEW = 3;
+
 // --- Upstream etiquette (429s) ---
 export const RETRY_MAX_ATTEMPTS = 6;
 export const RETRY_BASE_DELAY_MS = 2_000; // 2+4+8+16+32s spans npm's ~60s search window

package/src/install.ts

@@ -1,5 +1,6 @@
 /** install.ts — driven adapter: pi CLI mutations via Bun.spawn. */
-import type { Installer } from "./ports.ts";
+import { defaultPiHome, isPinnedNpmSource, readResolvedVersion } from "./installed.ts";
+import type { Installer, UpdateOutcome } from "./ports.ts";
 
 /** Bare npm package name (for `packed remove`). */
 export const NAME_RE = /^(@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+$/;
@@ -9,7 +10,10 @@ export function defaultPiBin(): string {
 }
 
 export class ExecInstaller implements Installer {
-	constructor(private bin = defaultPiBin()) {}
+	constructor(
+		private bin = defaultPiBin(),
+		private piHome = defaultPiHome(),
+	) {}
 
 	private async run(args: string[]): Promise<string> {
 		const proc = Bun.spawn([this.bin, ...args], { stdout: "pipe", stderr: "pipe" });
@@ -31,7 +35,18 @@ export class ExecInstaller implements Installer {
 		return this.run(["remove", source]);
 	}
 
-	update(source: string, _options?: { approved?: boolean }): Promise<string> {
-		return this.run(["update", "--extension", source]);
+	async update(source: string, _options?: { approved?: boolean }): Promise<UpdateOutcome> {
+		const pinned = isPinnedNpmSource(source);
+		const previousVersion = readResolvedVersion(this.piHome, source);
+		const output = await this.run(["update", "--extension", source]);
+		const currentVersion = readResolvedVersion(this.piHome, source);
+		// Only trust a "nothing changed" conclusion when we actually read a
+		// real version both before and after (npm source, resolvable in
+		// node_modules). Otherwise (git:/https: sources, or an unreadable
+		// node_modules entry) fall back to the traditional "assume it may
+		// have changed" signal instead of falsely claiming it didn't.
+		const knowsBoth = previousVersion !== undefined && currentVersion !== undefined;
+		const changed = !knowsBoth || previousVersion !== currentVersion;
+		return { output, reloadRequired: changed, alreadyUpToDate: !changed, pinned, previousVersion, currentVersion };
 	}
 }

package/src/installed.ts

@@ -30,6 +30,36 @@ function nodeModulesVersion(piHome: string, name: string): string | undefined {
 	}
 }
 
+/**
+ * True when a configured npm: source pins an exact version, e.g.
+ * "npm:@scope/pkg@1.2.3" vs. the floating "npm:@scope/pkg". `pi update`
+ * intentionally leaves pinned sources unchanged (see readInstalledPackages)
+ * but still exits 0 and prints "Updated <source>" either way -- callers
+ * must not treat that text as proof anything changed.
+ */
+export function isPinnedNpmSource(source: string): boolean {
+	if (!source.startsWith("npm:")) return false;
+	const [, pinned] = splitNpmSource(source.slice(4));
+	return pinned !== "";
+}
+
+/** The bare npm package name for a configured npm: source, pinned or not.
+ * undefined for git:/https: sources -- there is no npm-registry name to read. */
+export function npmPackageName(source: string): string | undefined {
+	if (!source.startsWith("npm:")) return undefined;
+	const [name] = splitNpmSource(source.slice(4));
+	return name;
+}
+
+/** Reads a single npm package's real on-disk resolved version, regardless of
+ * whether its configured source is pinned -- ground truth for detecting
+ * whether an update actually changed anything. undefined for non-npm
+ * sources or when node_modules has no matching package.json to read. */
+export function readResolvedVersion(piHome: string, source: string): string | undefined {
+	const name = npmPackageName(source);
+	return name ? nodeModulesVersion(piHome, name) : undefined;
+}
+
 export function readInstalledPackages(piHome: string): InstalledPkg[] {
 	let settings: { packages?: unknown[] };
 	try {

package/src/ports.ts

@@ -37,11 +37,30 @@ export interface Registry {
 	info(name: string): Promise<PkgInfo>;
 }
 
+/**
+ * `pi update --extension <source>` exits 0 and prints "Updated <source>"
+ * whether or not anything actually changed -- verified empirically against
+ * both a pinned, already-current source and an unpinned, already-latest
+ * one. reloadRequired/alreadyUpToDate are ground truth (on-disk resolved
+ * version, before vs. after), not that text. previousVersion/currentVersion
+ * are omitted when unknown (git:/https: sources, or no node_modules entry
+ * to read) -- reloadRequired then conservatively stays true rather than
+ * guessing.
+ */
+export interface UpdateOutcome {
+	output: string;
+	reloadRequired: boolean;
+	alreadyUpToDate: boolean;
+	pinned: boolean;
+	previousVersion?: string;
+	currentVersion?: string;
+}
+
 /** Driven port: pi CLI mutations. */
 export interface Installer {
 	install(source: string, options?: { approved?: boolean }): Promise<string>;
 	remove(source: string, options?: { approved?: boolean }): Promise<string>;
-	update(source: string, options?: { approved?: boolean }): Promise<string>;
+	update(source: string, options?: { approved?: boolean }): Promise<UpdateOutcome>;
 }
 
 export interface InstalledPkg {

package/src/service.ts

@@ -182,8 +182,8 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 			const denied = authorize("update", approved);
 			if (denied) return denied;
 			try {
-				const output = await deps.inst.update(source, { approved });
-				return json({ ok: true, source, output, reloadRequired: true });
+				const outcome = await deps.inst.update(source, { approved });
+				return json({ ok: true, source, ...outcome });
 			} catch (error) {
 				return json({ ok: false, source, output: error instanceof Error ? error.message : String(error), reloadRequired: false });
 			}