API reference

All types, interfaces, and constants are exported from types.ts. This page covers the key exports for anyone integrating with pi-mesh.

Interfaces

MeshConfig

The configuration object. See Configuration for full details.

interface MeshConfig {
  autoRegister: boolean;
  autoRegisterPaths: string[];
  contextMode: "full" | "minimal" | "none";
  feedRetention: number;
  stuckThreshold: number;
  autoStatus: boolean;
  hooksModule?: string;
}

AgentRegistration

Represents a registered agent in the mesh. Written to .pi/mesh/registry/{name}.json.

interface AgentRegistration {
  name: string;              // Display name (e.g. "zero-1")
  agentType: string;         // From PI_AGENT env var
  pid: number;               // OS process ID, used for stale cleanup
  sessionId: string;         // Unique session identifier
  cwd: string;               // Working directory
  model: string;             // LLM model name
  startedAt: string;         // ISO timestamp
  reservations?: FileReservation[];
  gitBranch?: string;
  isHuman: boolean;          // True for human-driven sessions
  session: AgentSession;     // Cumulative session stats
  activity: AgentActivity;   // Recent activity info
  statusMessage?: string;    // Custom or auto-generated status
}

MeshMessage

A message between agents. Written as a JSON file in the recipient's inbox.

interface MeshMessage {
  id: string;                // Unique message ID
  from: string;              // Sender agent name
  to: string;                // Recipient agent name
  text: string;              // Message body
  timestamp: string;         // ISO timestamp
  urgent: boolean;           // If true, interrupts the recipient
  replyTo: string | null;    // ID of the message being replied to
}

FileReservation

A file or directory reservation held by an agent.

interface FileReservation {
  pattern: string;           // Path or glob pattern (e.g. "src/auth/")
  reason?: string;           // Why the reservation was made
  since: string;             // ISO timestamp
}

FeedEvent

A single entry in the activity feed (feed.jsonl).

interface FeedEvent {
  ts: string;                // ISO timestamp
  agent: string;             // Agent that caused the event
  type: FeedEventType;       // "join" | "leave" | "reserve" | "release" |
                             // "message" | "commit" | "test" | "edit" | "stuck"
  target?: string;           // File path, agent name, or other context
  preview?: string;          // Short preview text
}

MeshLifecycleHooks

Hooks for reacting to mesh events. See Lifecycle Hooks for usage.

interface MeshLifecycleHooks {
  onRegistered?(state: MeshState, ctx: ExtensionContext, actions: HookActions): void | Promise<void>;
  onRenamed?(state: MeshState, ctx: ExtensionContext, result: RenameResult): void | Promise<void>;
  onPollTick?(state: MeshState, ctx: ExtensionContext, actions: HookActions): void | Promise<void>;
  onShutdown?(state: MeshState): void;
}

HookActions

Actions available to hooks for triggering mesh operations.

interface HookActions {
  rename(newName: string): Promise<RenameResult>;
}

RenameResult

Result of a rename operation (from registry.ts).

interface RenameResult {
  success: boolean;
  oldName?: string;
  newName?: string;
  error?: string;  // "not_registered" | "invalid_name" | "same_name" | "name_taken" | "write_failed" | "race_lost" | "verify_failed"
}

Types

AgentStatus

type AgentStatus = "active" | "idle" | "away" | "stuck";

Derived from agent activity. "active" means recent tool calls, "idle" means quiet but alive, "away" means no activity for a while, and "stuck" means idle beyond stuckThreshold.

FeedEventType

type FeedEventType =
  | "join" | "leave" | "reserve" | "release"
  | "message" | "commit" | "test" | "edit" | "stuck";

Constants

Tuning constants exported from types.ts:

STATUS_INDICATORS

Unicode indicators used in the overlay and context output:

const STATUS_INDICATORS: Record<AgentStatus, string> = {
  active: "●",
  idle:   "○",
  away:   "◌",
  stuck:  "✕",
};