@chankov/agent-skills 0.3.0 → 0.3.2

package/.versions/0.3.2/.pi/extensions/compact-and-continue/index.ts

@@ -0,0 +1,120 @@
+import type { CompactionResult, ExtensionAPI, ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { Type } from 'typebox';
+
+const DEFAULT_COMPACTION_INSTRUCTIONS = 'Preserve task goal, completed work, changed/read files, decisions, blockers, and next steps.';
+
+const RequestCompactionParams = Type.Object({
+	customInstructions: Type.Optional(Type.String({
+		description: 'Instructions for the compaction summary. Include what must be preserved for continuing safely.',
+	})),
+	reason: Type.Optional(Type.String({
+		description: 'Short explanation recorded in tool details for why immediate compaction was requested.',
+	})),
+	continuationPrompt: Type.Optional(Type.String({
+		description: 'Self-contained summary of the remaining plan to execute after compaction. Do not copy the original prompt verbatim. Include the next concrete actions. If the original plan explicitly requires later compaction checkpoints, include them; otherwise do not repeat the same compaction request.',
+	})),
+});
+
+function compact(ctx: ExtensionContext, customInstructions: string): Promise<CompactionResult> {
+	return new Promise((resolve, reject) => {
+		ctx.compact({
+			customInstructions,
+			onComplete: resolve,
+			onError: reject,
+		});
+	});
+}
+
+export default function compactAndContinueExtension(pi: ExtensionAPI) {
+	type PendingCompaction = {
+		customInstructions: string;
+		reason: string;
+		continuationPrompt?: string;
+	};
+
+	const pendingCompactions: PendingCompaction[] = [];
+	let compactionRunning = false;
+
+	async function runQueuedCompactions(ctx: ExtensionContext): Promise<void> {
+		if (compactionRunning || pendingCompactions.length === 0) {
+			return;
+		}
+
+		compactionRunning = true;
+		const pending = pendingCompactions.splice(0);
+		const customInstructions = pending
+			.map((item, index) => [
+				`Queued compaction request ${index + 1}/${pending.length}.`,
+				`Reason: ${item.reason}`,
+				item.customInstructions,
+			].join(' '))
+			.join('\n\n');
+		const continuationRequest = [...pending].reverse().find(item => item.continuationPrompt !== undefined);
+
+		try {
+			ctx.ui.notify('Compacting queued context request.', 'info');
+			await compact(ctx, customInstructions);
+			ctx.ui.notify('Queued compaction finished.', 'info');
+
+			if (continuationRequest?.continuationPrompt) {
+				ctx.ui.notify('Continuing summarized plan after compaction.', 'info');
+				setTimeout(() => pi.sendUserMessage(continuationRequest.continuationPrompt!), 0);
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Queued compaction failed: ${message}`, 'error');
+		} finally {
+			compactionRunning = false;
+			if (pendingCompactions.length > 0) {
+				setTimeout(() => void runQueuedCompactions(ctx), 0);
+			}
+		}
+	}
+
+	pi.on('agent_end', async (_event, ctx) => {
+		if (pendingCompactions.length > 0 && !compactionRunning) {
+			setTimeout(() => void runQueuedCompactions(ctx), 0);
+		}
+	});
+
+	pi.registerTool({
+		name: 'request_compaction',
+		label: 'Request Compaction',
+		description: 'Queue pi context compaction to run as soon as the current agent turn finishes. Use only when the user, a skill, or a prompt explicitly asks for compaction. If more work should continue after compaction, provide continuationPrompt as a concise summary of the remaining plan rather than the original prompt verbatim. This tool does not ask for confirmation; workflows that need confirmation must ask the user before calling it.',
+		promptSnippet: 'request_compaction(customInstructions?, reason?, continuationPrompt?) - queue context compaction after the current turn, then optionally continue from a summarized remaining plan.',
+		promptGuidelines: [
+			'Use request_compaction only when compaction was explicitly requested by the user, skill, or prompt.',
+			'If user confirmation is required, ask the user before calling request_compaction; this tool does not ask for confirmation.',
+			'Use request_compaction when the user asks to compact now or before continuing to later steps in the same task.',
+			'Provide customInstructions that preserve goals, decisions, files read/modified, blockers, and next steps.',
+			'When work should continue after compaction, provide continuationPrompt as a concise, self-contained summary of the remaining plan; do not copy the original prompt verbatim.',
+			'If the original plan explicitly requires later compaction checkpoints, include those checkpoints in continuationPrompt so request_compaction can be called again later; otherwise do not repeat the same compaction request.',
+		],
+		parameters: RequestCompactionParams,
+		executionMode: 'sequential',
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const customInstructions = params.customInstructions?.trim() || DEFAULT_COMPACTION_INSTRUCTIONS;
+			const reason = params.reason?.trim() || 'The current instructions requested immediate context compaction.';
+			const continuationPrompt = params.continuationPrompt?.trim() || undefined;
+
+			pendingCompactions.push({ customInstructions, reason, continuationPrompt });
+			ctx.ui.notify(
+				continuationPrompt
+					? 'Compaction queued after the current turn. The summarized remaining plan will continue after compaction.'
+					: 'Compaction queued after the current turn.',
+				'info',
+			);
+
+			return {
+				content: [{
+					type: 'text',
+					text: continuationPrompt
+						? 'Compaction queued. It will run after this agent turn finishes, then the summarized remaining plan will continue.'
+						: 'Compaction queued. It will run after this agent turn finishes.',
+				}],
+				details: { queued: true, continueAfterCompaction: continuationPrompt !== undefined, customInstructions, reason, continuationPrompt },
+				terminate: true,
+			};
+		},
+	});
+}

package/.versions/0.3.2/.pi/extensions/compact-and-continue/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-skills-pi-compact-and-continue",
+  "private": true,
+  "type": "module",
+  "main": "index.ts"
+}

package/.versions/0.3.2/.pi/extensions/mcp-bridge/README.md

@@ -0,0 +1,46 @@
+# mcp-bridge
+
+A reusable factory for turning any stdio MCP server into a pi extension.
+
+This is a **library**, not a standalone pi extension. It is consumed by other extensions in `.pi/extensions/` (for example, `chrome-devtools-mcp/`). pi will not load it directly.
+
+## What it does
+
+Given a config describing how to spawn an MCP server, the factory returns a pi extension that:
+
+1. Spawns the MCP server over stdio (`StdioClientTransport`).
+2. Lists the server's tools via `listTools`.
+3. Registers each tool with pi under a configurable prefix.
+4. Forwards calls and normalizes MCP content (`text`, `image`, `resource`) back to pi.
+5. Registers a status command and cleans up on `session_shutdown`.
+
+## Usage
+
+```ts
+import { createMcpBridgeExtension } from "../mcp-bridge/index.js";
+
+export default createMcpBridgeExtension({
+  prefix: "my_server__",
+  command: "npx",
+  args: ["-y", "some-mcp-server@latest"],
+});
+```
+
+## Config
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `prefix` | yes | — | Prefix prepended to every registered pi tool name (e.g. `chrome_devtools__`). |
+| `command` | yes | — | Executable used to spawn the MCP server (e.g. `npx`, `node`, an absolute path). |
+| `args` | yes | — | Arguments passed to `command`. |
+| `clientName` | no | `pi-<prefix>` | Identifier sent to the MCP server during connection. |
+| `labelPrefix` | no | humanized `prefix` | Shown in pi tool labels and status messages. |
+| `statusCommandName` | no | `<prefix>-status` | Slash command that reports bridge status. |
+
+## Why this exists
+
+pi does not yet have first-class MCP support. This bridge is a **stopgap**: it lets pi consume MCP servers today. When pi gains native MCP support, individual wrapper extensions can be retired or replaced; this library will then be deprecated.
+
+## Dependencies
+
+Runtime dependencies (`@modelcontextprotocol/sdk`, `typebox`) are declared once at `.pi/extensions/package.json` and installed via `npm ci` in the cloned `agent-skills` repo. Wrapper extensions resolve them from the hoisted `node_modules/` — no per-wrapper install required. `@mariozechner/pi-coding-agent` is supplied by the pi runtime that loads the extension.

package/.versions/0.3.2/.pi/extensions/mcp-bridge/index.ts

@@ -0,0 +1,206 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+
+export interface McpBridgeConfig {
+	prefix: string;
+	command: string;
+	args: string[];
+	env?: Record<string, string>;
+	stderr?: "inherit" | "pipe" | "overlapped";
+	clientName?: string;
+	labelPrefix?: string;
+	statusCommandName?: string;
+}
+
+type JsonObject = Record<string, unknown>;
+
+type McpTool = {
+	name: string;
+	description?: string;
+	inputSchema?: JsonObject;
+};
+
+type McpClient = {
+	listTools(): Promise<{ tools?: McpTool[] }>;
+	callTool(input: { name: string; arguments: JsonObject }): Promise<{ isError?: boolean; content?: unknown }>;
+	close(): Promise<void>;
+};
+
+type McpTransport = {
+	close?: () => Promise<void> | void;
+};
+
+function humanizePrefix(prefix: string): string {
+	return prefix
+		.replace(/__+$/, "")
+		.replace(/[_-]+/g, " ")
+		.replace(/\b\w/g, (c) => c.toUpperCase())
+		.trim();
+}
+
+function toPiToolName(prefix: string, mcpToolName: string): string {
+	const safeName = mcpToolName.replace(/[^A-Za-z0-9_-]/g, "_");
+	return `${prefix}${safeName}`;
+}
+
+function normalizeInputSchema(tool: McpTool) {
+	const schema = tool.inputSchema as JsonObject | undefined;
+	if (!schema || typeof schema !== "object") {
+		return Type.Object({});
+	}
+
+	return {
+		type: "object",
+		properties: {},
+		additionalProperties: true,
+		...schema,
+	} as ReturnType<typeof Type.Object>;
+}
+
+function stringifyMcpContent(content: unknown): string {
+	if (!Array.isArray(content)) {
+		return JSON.stringify(content, null, 2);
+	}
+
+	return content
+		.map((part) => {
+			if (!part || typeof part !== "object") return String(part);
+			const item = part as JsonObject;
+
+			if (item.type === "text" && typeof item.text === "string") {
+				return item.text;
+			}
+
+			if (item.type === "image") {
+				const mimeType = typeof item.mimeType === "string" ? item.mimeType : "image/*";
+				return `[Image returned by MCP bridge: ${mimeType}]`;
+			}
+
+			if (item.type === "resource") {
+				return `[Resource returned by MCP bridge]\n${JSON.stringify(item.resource ?? item, null, 2)}`;
+			}
+
+			return JSON.stringify(item, null, 2);
+		})
+		.join("\n\n");
+}
+
+function errorWithStderr(error: unknown, stderr: string): Error {
+	const message = error instanceof Error ? error.message : String(error);
+	const stderrExcerpt = stderr.trim().slice(-2_000);
+	return new Error(stderrExcerpt ? `${message}\n${stderrExcerpt}` : message);
+}
+
+// pi auto-discovers `.pi/extensions/*/index.ts` files. This module is primarily
+// a library consumed by wrapper extensions (for example, `chrome-devtools-mcp`),
+// but when the directory itself is symlinked as recommended it is also loaded as
+// a project extension. Export a harmless default factory so that direct loading
+// succeeds without registering tools; wrappers should import `createMcpBridgeExtension`.
+export default function mcpBridgeLibraryExtension(_pi: ExtensionAPI) {
+	// Intentionally empty.
+}
+
+export function createMcpBridgeExtension(config: McpBridgeConfig) {
+	const {
+		prefix,
+		command,
+		args,
+		env,
+		stderr = "inherit",
+		clientName = `pi-${prefix.replace(/__+$/, "")}`,
+		labelPrefix = humanizePrefix(prefix),
+		statusCommandName = `${prefix.replace(/__+$/, "")}-status`,
+	} = config;
+
+	async function connect(): Promise<{ client: McpClient; transport: McpTransport }> {
+		const [{ Client }, { StdioClientTransport }] = await Promise.all([
+			import("@modelcontextprotocol/sdk/client/index.js"),
+			import("@modelcontextprotocol/sdk/client/stdio.js"),
+		]);
+		const client = new Client({ name: clientName, version: "1.0.0" });
+		const transport = new StdioClientTransport({ command, args, env, stderr });
+		let stderrOutput = "";
+		transport.stderr?.on("data", (chunk: Buffer) => {
+			stderrOutput += chunk.toString();
+		});
+
+		try {
+			await client.connect(transport);
+			return { client, transport };
+		} catch (error) {
+			await transport.close().catch(() => undefined);
+			throw errorWithStderr(error, stderrOutput);
+		}
+	}
+
+	return async function mcpBridgeExtension(pi: ExtensionAPI) {
+		let client: McpClient | undefined;
+		let transport: McpTransport | undefined;
+		let tools: McpTool[] = [];
+
+		try {
+			const connection = await connect();
+			client = connection.client;
+			transport = connection.transport;
+			tools = (await client.listTools()).tools ?? [];
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			pi.registerCommand(statusCommandName, {
+				description: `Show ${labelPrefix} MCP bridge status`,
+				handler: async (_args, ctx) => {
+					ctx.ui.notify(`${labelPrefix} MCP failed to start: ${message}`, "error");
+				},
+			});
+			return;
+		}
+
+		for (const tool of tools) {
+			const piToolName = toPiToolName(prefix, tool.name);
+
+			pi.registerTool({
+				name: piToolName,
+				label: `${labelPrefix}: ${tool.name}`,
+				description: `${tool.description ?? `${labelPrefix} MCP tool`}\n\nWrapped MCP tool: ${tool.name}`,
+				promptSnippet: `${piToolName}: use ${labelPrefix} MCP tool '${tool.name}'.`,
+				parameters: normalizeInputSchema(tool),
+				executionMode: "sequential",
+				execute: async (_toolCallId, params, signal) => {
+					if (!client) {
+						throw new Error(`${labelPrefix} MCP client is not connected`);
+					}
+					if (signal?.aborted) {
+						throw new Error(`${labelPrefix} MCP tool call was aborted before it started`);
+					}
+
+					const result = await client.callTool({
+						name: tool.name,
+						arguments: params as JsonObject,
+					});
+
+					if (result.isError) {
+						throw new Error(stringifyMcpContent(result.content));
+					}
+
+					return {
+						content: [{ type: "text", text: stringifyMcpContent(result.content) }],
+						details: { mcpToolName: tool.name, rawResult: result },
+					};
+				},
+			});
+		}
+
+		pi.registerCommand(statusCommandName, {
+			description: `Show ${labelPrefix} MCP bridge status`,
+			handler: async (_args, ctx) => {
+				ctx.ui.notify(`${labelPrefix} MCP connected. Registered ${tools.length} tool(s).`, "success");
+			},
+		});
+
+		pi.on("session_shutdown", async () => {
+			await client?.close().catch(() => undefined);
+			await transport?.close?.().catch(() => undefined);
+			client = undefined;
+			transport = undefined;
+		});
+	};
+}

package/.versions/0.3.2/.pi/extensions/mcp-bridge/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-skills-pi-mcp-bridge",
+  "private": true,
+  "type": "module",
+  "main": "index.ts"
+}