Skip to content

espennilsen/pi / extensions/pi-a2a

pi-a2a

Flagged

FileKindSize
AGENTS.mdmarkdown12.0 KB
CHANGELOG.mdmarkdown1.3 KB
README.mdmarkdown11.0 KB
SKILL.mdskill md9.7 KB
agent-card-auth.test.tsscript1.7 KB
agent-card.tsscript6.1 KB
agent-executor.tsscript38.7 KB
auth-integration.test.tsscript4.6 KB
auth-selector.test.tsscript4.0 KB
auth-selector.tsscript2.6 KB
auth-types.tsscript3.7 KB
client.test.tsscript3.1 KB
client.tsscript14.9 KB
config-auth.test.tsscript4.0 KB
config.tsscript9.1 KB
cost.test.tsscript1.8 KB
hub.test.tsscript6.2 KB
hub.tsscript39.5 KB
inbound-auth.test.tsscript2.6 KB
inbound-auth.tsscript4.4 KB
index.tsscript136.5 KB
logger.tsscript1.5 KB
long-running-task-store.tsscript6.3 KB
outbound-auth.test.tsscript1.5 KB
outbound-auth.tsscript1.6 KB
package-lock.jsonmanifest149.9 KB
package.jsonmanifest1.5 KB
peer-metadata.test.tsscript3.7 KB
peer-metadata.tsscript4.6 KB
port-finder.tsscript742 B
server.tsscript12.6 KB
static-agents.tsscript5.8 KB
supervisor.test.tsscript6.1 KB
supervisor.tsscript8.4 KB
task-store.tsscript12.5 KB
token-provider.test.tsscript5.3 KB
token-provider.tsscript7.7 KB
tool-telemetry.test.tsscript2.8 KB
tool-telemetry.tsscript1.7 KB
tsconfig.jsonconfig274 B
types.tsscript11.3 KB
/**
 * pi-a2a — Standalone HTTP server.
 *
 * Self-contained A2A protocol server using @a2a-js/sdk for protocol handling.
 * The SDK's JsonRpcTransportHandler handles JSON-RPC routing and validation;
 * this module handles the HTTP layer, auth, and CORS.
 *
 * Routes:
 *   GET  /.well-known/agent-card.json   — A2A Agent Card (canonical SDK path)
 *   GET  /.well-known/agent.json        — A2A Agent Card (alternate path)
 *   POST /                              — A2A JSON-RPC 2.0 endpoint (streaming returns SSE)
 *   GET  /health                        — Health check
 */

import * as http from "node:http";
import { Extensions, HTTP_EXTENSION_HEADER, type AgentCard } from "@a2a-js/sdk";
import { ServerCallContext, type JsonRpcTransportHandler, type User } from "@a2a-js/sdk/server";
import type { LogFn } from "./logger.ts";
import { authenticateInboundRequest, getInboundSupportedModes, type MtlsEvidence, type OAuthVerifier } from "./inbound-auth.ts";
import type { AuthMode, LocalAuthOverride } from "./auth-types.ts";

/** Authenticated user — created when API key auth succeeds. */
class AuthenticatedUser implements User {
	private _userName: string;

	constructor(userName: string) {
		this._userName = userName;
	}

	get isAuthenticated(): boolean { return true; }
	get userName(): string { return this._userName; }
}

const MAX_BODY = 1_048_576; // 1 MB

export interface ServerOptions {
	port: number;
	/** Bind address. Defaults to "127.0.0.1" (localhost only). */
	bind?: string;
	/** API key for authenticating RPC requests. */
	apiKey?: string;
	/** Additive inbound auth policy. Omitted preserves legacy API-key behavior. */
	auth?: LocalAuthOverride;
	/** Runtime-enforceable modes (mTLS is omitted for this HTTP server). */
	supportedAuthModes?: AuthMode[];
	/** Injected verifier; without one OAuth requests fail closed. */
	verifyOAuth?: OAuthVerifier;
	/** TLS peer evidence, for an HTTPS server integration. Forwarded headers are never trusted. */
	getMtlsEvidence?: (req: http.IncomingMessage) => MtlsEvidence | undefined;
	agentCard: AgentCard;
	/** SDK JSON-RPC transport handler for A2A protocol dispatch. */
	rpcHandler: JsonRpcTransportHandler;
	log: LogFn;
}

let server: http.Server | null = null;
let currentAgentCard: AgentCard | null = null;

export function startServer(opts: ServerOptions): Promise<void> {
	return new Promise((resolve, reject) => {
		if (server) {
			opts.log("server_already_running", { port: opts.port }, "WARN");
			resolve();
			return;
		}

		currentAgentCard = opts.agentCard;

		const isLocalhost = !opts.bind || opts.bind === "127.0.0.1" || opts.bind === "::1";
		// Only allow CORS on localhost; external bindings should use a reverse proxy for cross-origin access
		const corsOrigin = isLocalhost ? "*" : "";
		const corsHeaders = (opts.apiKey || opts.auth?.supportedAuthModes?.some((mode) => mode !== "legacy-api-key")) ? "Content-Type, Authorization" : "Content-Type";
		const supportedAuthModes = opts.supportedAuthModes ?? getInboundSupportedModes({ apiKey: opts.apiKey, auth: opts.auth });
		const authenticationRequired = opts.apiKey !== undefined || (opts.auth?.supportedAuthModes?.length ?? 0) > 0;

		server = http.createServer(async (req, res) => {
			const method = req.method ?? "GET";
			const url = new URL(req.url ?? "/", `http://localhost:${opts.port}`);
			const pathname = url.pathname;

			// CORS headers
			if (corsOrigin) {
				res.setHeader("Access-Control-Allow-Origin", corsOrigin);
				res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
				res.setHeader("Access-Control-Allow-Headers", corsHeaders);
			}

			if (method === "OPTIONS") {
				res.writeHead(204);
				res.end();
				return;
			}

			try {
				// GET /.well-known/agent.json or /.well-known/agent-card.json — Agent Card
				if ((pathname === "/.well-known/agent.json" || pathname === "/.well-known/agent-card.json") && method === "GET") {
					if (!currentAgentCard) {
						res.writeHead(503, { "Content-Type": "application/json" });
						res.end(JSON.stringify({ error: "Agent card not yet available" }));
						return;
					}
					res.writeHead(200, { "Content-Type": "application/json" });
					res.end(JSON.stringify(currentAgentCard, null, 2));
					return;
				}

				// GET /health — Health check
				if (pathname === "/health" && method === "GET") {
					res.writeHead(200, { "Content-Type": "application/json" });
					res.end(JSON.stringify({ status: "healthy", agent: currentAgentCard?.name }));
					return;
				}

				// POST / — A2A JSON-RPC 2.0 (via SDK handler)
				if (pathname === "/" && method === "POST") {
					// A2A-Version header validation (§3.6.2, §9.2)
					const clientVersion = req.headers["a2a-version"] as string | undefined;
					if (clientVersion && !clientVersion.startsWith("0.")) {
						res.writeHead(400, { "Content-Type": "application/json" });
						res.end(JSON.stringify({
							jsonrpc: "2.0",
							error: { code: -32600, message: `Unsupported A2A version: ${clientVersion}. This agent supports 0.x.` },
							id: null,
						}));
						return;
					}
					if (clientVersion && !(clientVersion === "0.3" || clientVersion.startsWith("0.3."))) {
						opts.log("a2a_version_mismatch", { clientVersion, supported: "0.3.x" }, "WARN");
					}

					const authHeader = typeof req.headers.authorization === "string" ? req.headers.authorization : undefined;
					const body = await readBody(req);

					let parsed: unknown;
					try {
						parsed = JSON.parse(body);
					} catch {
						res.writeHead(400, { "Content-Type": "application/json" });
						res.end(JSON.stringify({
							jsonrpc: "2.0",
							error: { code: -32700, message: "Parse error" },
							id: null,
						}));
						return;
					}

					// Authenticate once after extracting the operation, still before dispatch.
					// This avoids verifying an OAuth bearer token twice per request.
					const operation = operationFromRpc(parsed);
					const authentication = authenticationRequired ? await authenticateInboundRequest({
						authorization: authHeader, local: { apiKey: opts.apiKey, auth: opts.auth },
						supportedModes: supportedAuthModes, verifyOAuth: opts.verifyOAuth,
						mtlsEvidence: opts.getMtlsEvidence?.(req), operation,
					}) : {};
					if (authenticationRequired && !authentication.principal) {
						opts.log("a2a_auth_policy_denied", { peerId: "unknown", taskId: rpcTaskId(parsed), operation: operation ?? "unknown", metadataSource: "inbound", mode: "unknown", reason: authentication.reason }, "WARN");
						res.writeHead(authentication.status ?? 403, { "Content-Type": "application/json" });
						res.end(JSON.stringify({ error: "Forbidden" }));
						return;
					}
					if (authenticationRequired && authentication.principal) {
						opts.log("a2a_auth_inbound_allowed", { peerId: authentication.principal.identity, taskId: rpcTaskId(parsed), operation: operation ?? "unknown", metadataSource: "inbound", mode: authentication.principal.mode });
					}

					// Build ServerCallContext with extensions and auth info.
					// The SDK threads this through to RequestContext.context
					// so the executor can inspect caller identity and extensions.
					const extensionsHeader = req.headers[HTTP_EXTENSION_HEADER.toLowerCase()] as string | undefined;
					let requestedExtensions: string[] = [];
					try {
						requestedExtensions = Extensions.parseServiceParameter(extensionsHeader);
					} catch (err) {
						opts.log("extensions_parse_error", { header: extensionsHeader, error: err instanceof Error ? err.message : String(err) }, "WARN");
					}
					const user: User | undefined = authentication.principal ? new AuthenticatedUser(authentication.principal.identity) : undefined;
					const callContext = new ServerCallContext(
						requestedExtensions.length > 0 ? requestedExtensions : undefined,
						user,
					);

					const result = await opts.rpcHandler.handle(parsed, callContext);

					// Check if result is an async generator (streaming)
					if (result && typeof result === "object" && Symbol.asyncIterator in result) {
						// SSE streaming response
						res.writeHead(200, {
							"Content-Type": "text/event-stream",
							"Cache-Control": "no-cache",
							"Connection": "keep-alive",
						});
						const generator = result as AsyncGenerator<unknown>;
						// Abort generator early if client disconnects to free subprocess slot
						req.on("close", () => {
							generator.return(undefined);
						});
						for await (const event of generator) {
							if (res.writableEnded) break;
							res.write(`data: ${JSON.stringify(event)}\n\n`);
						}
						res.end();
					} else {
						// Single JSON-RPC response
						res.writeHead(200, { "Content-Type": "application/json" });
						res.end(JSON.stringify(result));
					}
					return;
				}

				// 404
				res.writeHead(404, { "Content-Type": "application/json" });
				res.end(JSON.stringify({ error: "Not found" }));
			} catch (err: unknown) {
				// Guard against writing headers twice (e.g. error during SSE streaming)
				if (res.headersSent) {
					if (!res.writableEnded) res.end();
					const msg = err instanceof Error ? err.message : String(err);
					opts.log("server_error_after_headers", { path: pathname, error: msg }, "ERROR");
					return;
				}
				if (err instanceof PayloadTooLargeError) {
					opts.log("payload_too_large", { path: pathname }, "WARN");
					res.writeHead(413, { "Content-Type": "application/json" });
					res.end(JSON.stringify({ error: "Payload too large" }));
					return;
				}
				const msg = err instanceof Error ? err.message : String(err);
				opts.log("server_error", { path: pathname, error: msg }, "ERROR");
				res.writeHead(500, { "Content-Type": "application/json" });
				res.end(JSON.stringify({ error: "Internal server error" }));
			}
		});

		server.on("error", (err) => {
			opts.log("server_bind_error", { error: err.message }, "ERROR");
			server = null;
			reject(err);
		});

		const bind = opts.bind ?? "127.0.0.1";
		const logHost = bind === "::1" ? "[::1]" : (!bind || bind === "0.0.0.0") ? "localhost" : bind;
		server.listen(opts.port, bind, () => {
			opts.log("server_started", { port: opts.port, bind, agentCard: `http://${logHost}:${opts.port}/.well-known/agent.json` });
			resolve();
		});
	});
}

export function stopServer(log: LogFn): Promise<void> {
	return new Promise((resolve) => {
		if (!server) {
			resolve();
			return;
		}
		// Destroy active connections (including SSE) so .close() callback fires promptly
		server.closeAllConnections();
		server.close(() => {
			log("server_stopped");
			server = null;
			currentAgentCard = null;
			resolve();
		});
	});
}

export function isRunning(): boolean {
	return server !== null;
}

/**
 * Update the agent card served by the running server.
 */
export function updateAgentCard(card: AgentCard): void {
	currentAgentCard = card;
}

/**
 * Get the current agent card, or null if server hasn't started.
 */
export function getAgentCard(): AgentCard | null {
	return currentAgentCard;
}

// ── Helpers ─────────────────────────────────────────────────────


class PayloadTooLargeError extends Error {
	constructor() {
		super("Payload too large");
		this.name = "PayloadTooLargeError";
	}
}

/** Prefer an explicit A2A skill identifier when supplied; otherwise policy applies to the RPC method. */
function operationFromRpc(value: unknown): string | undefined {
	if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
	const rpc = value as { method?: unknown; params?: { skillId?: unknown; skill?: unknown } };
	if (typeof rpc.params?.skillId === "string") return rpc.params.skillId;
	if (typeof rpc.params?.skill === "string") return rpc.params.skill;
	return typeof rpc.method === "string" ? rpc.method : undefined;
}

function rpcTaskId(value: unknown): string | undefined {
	if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
	const params = (value as { params?: unknown }).params;
	if (params === null || typeof params !== "object" || Array.isArray(params)) return undefined;
	const taskId = (params as { taskId?: unknown }).taskId;
	return typeof taskId === "string" ? taskId : undefined;
}

function readBody(req: http.IncomingMessage): Promise<string> {
	return new Promise((resolve, reject) => {
		const chunks: Buffer[] = [];
		let byteLength = 0;
		let rejected = false;

		req.on("data", (chunk: Buffer) => {
			byteLength += chunk.byteLength;
			if (byteLength > MAX_BODY) {
				rejected = true;
				req.destroy();
				reject(new PayloadTooLargeError());
				return;
			}
			chunks.push(chunk);
		});

		req.on("end", () => {
			if (!rejected) resolve(Buffer.concat(chunks).toString("utf-8"));
		});

		req.on("error", reject);
	});
}
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall