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 — Extension config types.
 *
 * A2A protocol types are imported directly from @a2a-js/sdk where needed.
 */

import type { LocalAuthOverride, PeerAuthMetadata, StaticAuthOverride } from "./auth-types.ts";

// ── Extension Config ────────────────────────────────────────────

export interface LocalConfig {
	/** HTTP port for the A2A server. Defaults to 3100. */
	port?: number;
	/** Port range for dynamic port discovery (inclusive). When set, pi-a2a
	 *  finds the first free port in this range instead of using a fixed port.
	 *  E.g. [3100, 3199]. Takes precedence over `port`. */
	portRange?: [number, number];
	/** Bind address for the HTTP server. Defaults to "127.0.0.1" (localhost only).
	 *  Set to "0.0.0.0" for external access (requires apiKey). */
	bind?: string;
	/** Network interface name or IP to use for publicUrl auto-detection.
	 *  When set, publicUrl uses this interface's IP instead of the primary IP.
	 *  Examples: "en0", "eth0", "192.168.1.100". Requires `bind` to be set if not localhost. */
	bindInterface?: string;
	/** Public-facing base URL. Defaults to http://localhost:{port}. */
	publicUrl?: string;
	/** Require an API key for inbound requests. When true and apiKey is unset, one is auto-generated.
	 *  Useful for external binds that are not using hub configuration. */
	requireApiKey?: boolean;
	/** API key for authenticating RPC requests. Required when bind is not localhost.
	 *  Optional when requireApiKey is true, or when hub.url is configured for an external bind,
	 *  as loadConfig() will auto-generate one if not provided. */
	apiKey?: string;
	/** Peer-auth policy and local transport capabilities. */
	auth?: LocalAuthOverride;
}

export interface A2AConfig {
	/** Local server settings (port, bind, apiKey, etc.). */
	local?: LocalConfig;
	/** Agent display name. Defaults to "Pi Agent". */
	name?: string;
	/** Agent description. */
	description?: string;
	/** Agent version. Defaults to "1.0.0". */
	version?: string;
	/** Provider organization name. */
	organization?: string;
	/** Provider URL. */
	providerUrl?: string;
	/** Agent owner name or email (displayed in agent discovery and hub UIs). */
	owner?: string;
	/** Skills to advertise in the Agent Card. */
	skills?: Array<{ id: string; name: string; description: string; tags?: string[] }>;
	/** A2A Hub settings for optional registration. */
	hub?: HubConfig;
	/** Timeout in milliseconds for outbound a2a_send requests. No timeout by default. */
	sendTimeoutMs?: number;
	/** Default maximum hop count for loop control. Defaults to 10.
	 *  Messages exceeding this many agent-to-agent hops are rejected. */
	maxHops?: number;
	/** URL to an icon for the agent (displayed in hub UIs and agent discovery). */
	iconUrl?: string;
	/** URL to the agent's documentation page. */
	documentationUrl?: string;
	/** Manually configured remote agents (no hub required). */
	staticAgents?: StaticAgentConfig[];
	/** Task time-to-live in milliseconds. Tasks older than this are pruned periodically.
	 *  Defaults to 86400000 (24 hours). Set to 0 to disable expiry. */
	taskTtlMs?: number;
	/** Timeout in milliseconds for processing a single inbound A2A task.
	 *  If the main agent doesn't respond within this time, the task is marked failed
	 *  and the queue is unblocked. Defaults to 600000 (10 minutes). Set to 0 to disable. */
	taskTimeoutMs?: number;
	/** Timeout in milliseconds for waiting for follow-up input when a task is in
	 *  input-required state. If the caller doesn't respond within this time, the
	 *  a2a_request_input tool returns an error and the task fails.
	 *  Defaults to 600000 (10 minutes). */
	inputRequiredTimeoutMs?: number;
	/** Maximum number of input-required rounds allowed per task.
	 *  Prevents infinite input loops. Defaults to 5. */
	maxInputRounds?: number;
	/** Clarification response poller settings.
	 *  When enabled, periodically checks the hub for answered owner clarifications
	 *  and spawns a fresh pi subprocess to handle each response. */
	poller?: PollerConfig;
	/** Long-running task support.
	 *  When enabled, tasks can run for hours/days without timeouts.
	 *  State is persisted to disk and survives Pi restarts.
	 *  Uses a smart resume queue that waits for agent to be idle. */
	longRunningTasks?: LongRunningTasksConfig;
}

/** Configuration for the background clarification poller. */
export interface PollerConfig {
	/** Enable the poller. Defaults to false. */
	enabled?: boolean;
	/** Poll interval in seconds. Defaults to 60. Min 15, max 600. */
	intervalSeconds?: number;
	/** Extension paths to load in spawned pi subprocesses. */
	extensions?: string[];
	/** Skill paths to load in spawned pi subprocesses. */
	skills?: string[];
	/** Model to use for spawned pi subprocesses. */
	model?: string;
}

/** Configuration for long-running task support. */
export interface LongRunningTasksConfig {
	/** Enable long-running task support. Defaults to false. */
	enabled?: boolean;
	/** Maximum task age in hours. Tasks older than this are pruned.
	 *  Defaults to 168 hours (7 days). */
	maxTaskAgeHours?: number;
	/** Maximum retry attempts for resume requests. Defaults to 3. */
	resumeRetryAttempts?: number;
	/** Delay between resume retry attempts in milliseconds. Defaults to 5000. */
	resumeRetryDelayMs?: number;
	/** Polling interval for checking completed tasks in milliseconds.
	 *  Defaults to 300000 (5 minutes). */
	pollingIntervalMs?: number;
}

/** Configuration for a manually defined remote agent. */
export interface StaticAgentConfig {
	/** Agent display name (used for resolution in a2a_send). */
	name: string;
	/** Agent's A2A base URL (e.g. "http://192.168.1.50:3100"). */
	url: string;
	/** API key for authenticating with this agent (sent as Bearer token). */
	apiKey?: string;
	/** Optional peer-auth metadata override for this static directory entry. */
	auth?: StaticAuthOverride;
	/** Optional description override (defaults to agent card description). */
	description?: string;
}

export interface HubConfig {
	/** Hub API base URL (e.g. "http://localhost:3001/api"). */
	url: string;
	/** API key for hub authentication. */
	apiKey: string;
	/** Categories to register under. */
	categories?: string[];
	/** Freeform tags. */
	tags?: string[];
	/** Visibility: public, unlisted, or private. Defaults to "public". */
	visibility?: "public" | "unlisted" | "private";
	/** Auto-register on session start. Defaults to true when hub config is present. */
	autoRegister?: boolean;
}

// ── Remote Agent Types (from hub API responses) ─────────────────

export interface RemoteAgentSummary {
	id: string;
	name: string;
	description: string;
	url: string;
	category: string[];
	tags: string[];
	iconUrl: string | null;
	healthStatus: "healthy" | "degraded" | "down" | "unknown";
	popularity: number;
	featured: boolean;
	queueDepth: number;
	activeTasks: number;
	maxConcurrent: number;
	avgResponseMs: number | null;
	availability: "idle" | "busy" | "saturated" | "unknown";
	telemetryUpdatedAt: string | null;
	lastSeenAt: string | null;
}

export interface RemoteAgentDetail {
	id: string;
	agentCard: Record<string, unknown>;
	/** Optional peer-auth metadata supplied by the Hub's `agents.get` response. */
	auth?: PeerAuthMetadata;
	status: "pending" | "active" | "suspended" | "archived";
	visibility: "public" | "private" | "unlisted";
	category: string[];
	tags: string[];
	featured: boolean;
	popularity: number;
	healthStatus: "healthy" | "degraded" | "down" | "unknown";
	uptimePercentage: number;
	validationStatus: "valid" | "invalid" | "warning" | "unknown";
	hasCredential: boolean;
	credentialUpdatedAt: string | null;
	createdAt: string;
	updatedAt: string;
	queueDepth: number;
	activeTasks: number;
	maxConcurrent: number;
	avgResponseMs: number | null;
	totalTasks: number;
	totalFailures: number;
	availability: "idle" | "busy" | "saturated" | "unknown";
	telemetryUpdatedAt: string | null;
	lastSeenAt: string | null;
}

// ── Telemetry Snapshot ──────────────────────────────────────────

export interface ToolCallRecord {
	toolName: string;
	durationMs: number;
	isError: boolean;
	/** When isError is true, a truncated error message from the tool result. */
	errorText: string | null;
	/** Model ID used during this tool call. */
	modelId?: string;
	/** Model provider name. */
	modelProvider?: string;
	/** Model context window size. */
	modelContextWindow?: number;
	/** Correlates multiple telemetry snapshots to a single agent session. */
	sessionId?: string;
	/** Estimated context tokens at the time of the tool call. */
	contextTokens?: number | null;
	/** Context usage as percentage of context window. */
	contextPercent?: number | null;
	/** Unix timestamp (ms). */
	timestamp: number;
}

/** Cost attribution data for a completed A2A task. */
export interface TaskCostInfo {
	/** Input tokens consumed. */
	inputTokens: number;
	/** Output tokens consumed. */
	outputTokens: number;
	/** Estimated cost in USD, derived from model pricing metadata. */
	estimatedCostUsd: number;
	/** Number of tool calls made during the task. */
	toolCallCount: number;
	/** Total task duration in milliseconds. */
	durationMs: number;
}

export interface TelemetrySnapshot {
	queueDepth: number;
	activeTasks: number;
	maxConcurrent: number;
	lastTaskDurationMs?: number;
	lastTaskStatus?: "completed" | "failed";
	/** Recent tool calls since the last telemetry report. */
	recentToolCalls?: ToolCallRecord[];
	/** Cost attribution for the last completed/failed task. */
	costInfo?: TaskCostInfo;
}

// ── Orchestrator Types ──────────────────────────────────────────

export interface AgentSelectionResult {
	agentId: string;
}

export interface AgentStrategy {
	name: string;
	description: string;
	weights?: Record<string, number>;
}

export interface ProjectSettings {
	project: string;
	displayName?: string;
	maxConcurrent?: number;
	stallTimeoutMs?: number;
	turnTimeoutMs?: number;
	maxRetryBackoffMs?: number;
	pollIntervalMs?: number;
	autoApprove?: boolean;
	inputRequiredPolicy?: "block" | "ask";
	eligibleAgents?: string[];
	createdAt: string;
	updatedAt: string;
}

// ── SSE Stream Types ──────────────────────────────────────────

export interface PipelineStreamEvent {
	type: "task.stateChanged";
	data: {
		taskId: string;
		fromState: string | null;
		toState: string;
		project: string;
		assignedAgentId: string | null;
		externalTaskId: string | null;
		branch: string | null;
		prUrl: string | null;
		prNumber: number | null;
		title: string;
		priority: string;
	};
	timestamp: string;
}

// ── Push Notification Types ──────────────────────────────────────────

export type PushEventType =
	| "task.stateChanged"
	| "task.progress"
	| "task.error"
	| "heartbeat";

export interface PushEventPayload {
	taskId?: string;
	fromState?: string | null;
	toState?: string;
	progress?: number;
	message?: string;
	error?: string;
	artifact?: unknown;
	queueDepth?: number;
	activeTasks?: number;
	maxConcurrent?: number;
	timestamp: string;
}

export interface AgentPushCapabilities {
	enabled: boolean;
	url: string;
	events: PushEventType[];
}
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