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

agent-card.ts

View on GitHub
/**
 * pi-a2a — Agent Card builder.
 *
 * Produces agent cards in the @a2a-js/sdk format, which is the de facto standard
 * used by all A2A SDK consumers. The SDK's AgentCard type follows the draft/0.2.x
 * spec shape (top-level `url`, `protocolVersion`, `additionalInterfaces` with
 * `transport`, OpenAPI 3.0 security schemes).
 *
 * The official A2A spec v1.0 introduced breaking changes (renamed fields, per-interface
 * protocol versions, discriminated union security schemes) but no SDK has adopted them.
 * Since other agents use the same SDK, we serve the SDK-native format for interoperability.
 */

import type { AgentCard, AgentSkill } from "@a2a-js/sdk";
import type { A2AConfig } from "./types.ts";
import type { AuthMode } from "./auth-types.ts";
import { getInboundSupportedModes } from "./inbound-auth.ts";

/** Minimal tool info matching pi's ToolInfo type. */
export interface ToolInfo {
	name: string;
	description: string;
}

/** Built-in tools that are always present — no need to advertise individually. */
const BUILTIN_TOOL_NAMES = new Set([
	"bash",
	"read",
	"edit",
	"write",
	"grep",
	"find",
	"ls",
]);

const DEFAULT_SKILLS: AgentSkill[] = [
	{
		id: "general_coding",
		name: "General Coding",
		description: "Read, write, edit, and debug code across languages and frameworks",
		tags: ["coding", "development"],
		examples: ["Fix the bug in auth.ts", "Add input validation to the signup form"],
	},
	{
		id: "file_operations",
		name: "File Operations",
		description: "Read, create, and modify files in the project",
		tags: ["files", "editing"],
		examples: ["Create a new config file", "Read the contents of package.json"],
	},
	{
		id: "shell_commands",
		name: "Shell Commands",
		description: "Execute bash commands for builds, tests, and system operations",
		tags: ["bash", "shell", "cli"],
		examples: ["Run the test suite", "Install the missing dependency"],
	},
];

const PROTOCOL_VERSION = "0.3.0";

/**
 * Build an A2A Agent Card (SDK format).
 *
 * Used internally by the SDK's DefaultRequestHandler for JSON-RPC protocol handling.
 * The SDK has its own field names (e.g. `additionalInterfaces`, `transport`) that
 * differ from the spec — the SDK maps these internally when processing requests.
 */
export function buildAgentCard(config: A2AConfig, baseUrl: string, runtimeSupportedModes?: AuthMode[]): AgentCard {
	const configSkills: AgentSkill[] | undefined = config.skills?.map((s) => ({
		...s,
		tags: s.tags ?? [],
	}));

	const card: AgentCard = {
		name: config.name ?? "Pi Agent",
		description: config.description ?? "Personal AI coding agent powered by Pi",
		url: baseUrl,
		version: config.version ?? "1.0.0",
		protocolVersion: PROTOCOL_VERSION,
		provider: {
			organization: config.organization ?? "Pi",
			url: config.providerUrl ?? baseUrl,
		},
		capabilities: {
			streaming: true,
			pushNotifications: true,
		},
		skills: configSkills ?? DEFAULT_SKILLS,
		defaultInputModes: ["text/plain", "application/json"],
		defaultOutputModes: ["text/plain", "application/json"],
		additionalInterfaces: [
			{ url: baseUrl, transport: "JSONRPC" },
		],
	};

	if (config.owner) {
		(card as any).owner = config.owner;
	}

	if (config.iconUrl) {
		card.iconUrl = config.iconUrl;
	}
	if (config.documentationUrl) {
		card.documentationUrl = config.documentationUrl;
	}

	// Advertise only mechanisms the started server can enforce, never credential material.
	const modes = runtimeSupportedModes ?? getInboundSupportedModes(config.local);
	const schemes: Record<string, unknown> = {};
	const requirements: Array<Record<string, string[]>> = [];
	if (modes.includes("legacy-api-key")) {
		schemes.bearerAuth = { type: "http", scheme: "bearer", description: "API key passed as Bearer token in the Authorization header" };
		requirements.push({ bearerAuth: [] });
	}
	const tokenUrl = trustedOAuthTokenEndpoint(config);
	const canAdvertiseOAuth = !!tokenUrl;
	if (canAdvertiseOAuth) {
		schemes.oauth2 = { type: "oauth2", flows: { clientCredentials: { tokenUrl, scopes: {} } }, description: "OAuth 2.0 bearer access token" };
	}
	if (canAdvertiseOAuth && modes.includes("oauth2")) requirements.push({ oauth2: [] });
	if (canAdvertiseOAuth && modes.includes("oauth2+mtls")) {
		schemes.mutualTLS = { type: "mutualTLS", description: "TLS client certificate bound to the OAuth access token" };
		requirements.push({ oauth2: [], mutualTLS: [] });
	}
	if (requirements.length) {
		// SDK's current AgentCard types only model a subset of OpenAPI schemes.
		(card as any).securitySchemes = schemes;
		(card as any).security = requirements;
	}

	return card;
}

/** Return a token endpoint only when local configuration explicitly pins it. */
function trustedOAuthTokenEndpoint(config: A2AConfig): string | undefined {
	const oauth = config.local?.auth?.oauth2;
	if (!oauth?.authorizationServer) return undefined;
	try {
		const endpoint = new URL(oauth.authorizationServer);
		if (endpoint.protocol !== "https:" || endpoint.username || endpoint.password) return undefined;
		const trustedOrigins = new Set((oauth.trustedTokenEndpointOrigins ?? []).flatMap((origin) => {
			try { return [new URL(origin).origin]; } catch { return []; }
		}));
		return trustedOrigins.has(endpoint.origin) ? endpoint.toString() : undefined;
	} catch {
		return undefined;
	}
}

/**
 * Enrich an existing agent card with dynamically discovered tools.
 *
 * Extension tools (non-built-in) are converted to A2A skills and merged
 * with the card's existing skills. Config-defined skills take precedence.
 */
export function enrichAgentCard(card: AgentCard, tools: ToolInfo[]): AgentCard {
	const existingIds = new Set(card.skills.map((s) => s.id));

	const toolSkills: AgentSkill[] = tools
		.filter((t) => !BUILTIN_TOOL_NAMES.has(t.name) && !existingIds.has(t.name))
		.map((t) => ({
			id: t.name,
			name: formatToolName(t.name),
			description: t.description,
			tags: ["tool", "extension"],
		}));

	return {
		...card,
		skills: [...card.skills, ...toolSkills],
	};
}

/**
 * Convert tool_name to Title Case display name.
 */
function formatToolName(name: string): string {
	return name
		.split(/[_-]/)
		.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
		.join(" ");
}
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