agent-relay-sdk 0.1.0

package/src/types.ts

@@ -0,0 +1,740 @@
+export type AgentKind = "provider" | "channel" | "orchestrator" | "system" | "user";
+
+export interface AgentCard {
+  id: string;
+  name: string;
+  kind: AgentKind;
+  label?: string; // human-friendly alias; acts as a fan-out target ("label:foo")
+  tags: string[];
+  machine?: string;
+  rig?: string;
+  capabilities: string[];
+  ready: boolean;
+  status: AgentStatus;
+  instanceId?: string;
+  epoch: number;
+  meta?: Record<string, unknown>;
+  lastSeen: number;
+  createdAt: number;
+}
+
+export type AgentStatus = "online" | "idle" | "busy" | "stale" | "offline";
+
+export type MessageKind =
+  | "chat"
+  | "channel.event"
+  | "task"
+  | "pair"
+  | "control"
+  | "system";
+
+export interface Message {
+  id: number;
+  from: string;
+  to: string; // agent-id | "tag:<name>" | "broadcast" | "cap:<name>"
+  kind: MessageKind;
+  channel?: string;
+  subject?: string;
+  body: string;
+  threadId?: number;
+  replyTo?: number;
+  claimable?: boolean;
+  claimedBy?: string;
+  claimedAt?: number;
+  claimExpiresAt?: number;
+  idempotencyKey?: string;
+  payload: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+  readBy: string[];
+  createdAt: number;
+}
+
+export interface SendMessageInput {
+  from: string;
+  to: string;
+  kind?: MessageKind;
+  channel?: string;
+  subject?: string;
+  body: string;
+  replyTo?: number;
+  claimable?: boolean;
+  idempotencyKey?: string;
+  payload?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export type ConnectorKind = "channel" | "event" | "provider" | "orchestrator";
+export type ConnectorAction = "install" | "uninstall" | "enable" | "disable" | "start" | "stop" | "restart" | "status" | "doctor";
+
+export interface ConnectorManifest {
+  schema: "agent-relay.connector.v1";
+  id: string;
+  kind: ConnectorKind;
+  packageName?: string;
+  binary: string;
+  displayName: string;
+  description?: string;
+  version: string;
+  capabilities: string[];
+  commands: Partial<Record<ConnectorAction, string[]>>;
+  configSchema?: Record<string, unknown>;
+}
+
+interface ConnectorRuntime {
+  installed: boolean;
+  enabled?: boolean;
+  running?: boolean;
+  status?: "ok" | "warn" | "error" | "unknown";
+  detail?: string;
+  updatedAt?: string;
+  raw?: unknown;
+}
+
+export interface ConnectorSummary {
+  id: string;
+  kind: ConnectorKind;
+  displayName: string;
+  description?: string;
+  version: string;
+  packageName?: string;
+  binary: string;
+  capabilities: string[];
+  registryPath: string;
+  manifest: ConnectorManifest;
+  config?: Record<string, unknown>;
+  state?: Record<string, unknown>;
+  runtime: ConnectorRuntime;
+}
+
+export interface ConnectorActionResult {
+  connectorId: string;
+  action: ConnectorAction;
+  command?: string[];
+  ok: boolean;
+  exitCode?: number | null;
+  stdout?: string;
+  stderr?: string;
+  parsed?: unknown;
+}
+
+export type PairStatus = "pending" | "active" | "ended" | "rejected" | "expired";
+
+export interface PairSession {
+  id: string;
+  requesterId: string;
+  targetId: string;
+  status: PairStatus;
+  objective?: string;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number;
+  acceptedAt?: number;
+  endedAt?: number;
+  endedBy?: string;
+  lastMessageAt?: number;
+  meta: Record<string, unknown>;
+}
+
+export interface CreatePairInput {
+  from: string;
+  target: string;
+  objective?: string;
+  ttlMs?: number;
+  meta?: Record<string, unknown>;
+}
+
+export interface PairActionInput {
+  agentId: string;
+  reason?: string;
+}
+
+export interface PairMessageInput {
+  from: string;
+  body: string;
+  subject?: string;
+}
+
+export interface PollQuery {
+  for: string; // agent-id
+  since?: number; // unix ms (createdAt cursor)
+  sinceId?: number; // monotonic message id cursor (preferred — avoids same-ms collisions)
+  unread?: boolean;
+  channel?: string;
+  limit?: number;
+}
+
+export interface RegisterAgentInput {
+  id: string;
+  name: string;
+  kind?: AgentKind;
+  label?: string | null;
+  tags?: string[];
+  machine?: string;
+  rig?: string;
+  capabilities?: string[];
+  ready?: boolean;
+  status?: AgentCard["status"];
+  instanceId?: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface AgentSessionGuard {
+  instanceId?: string;
+  epoch?: number;
+}
+
+export type TaskSeverity = "info" | "warning" | "critical";
+export type TaskStatus =
+  | "open"
+  | "claimed"
+  | "in_progress"
+  | "blocked"
+  | "orphaned"
+  | "done"
+  | "failed"
+  | "canceled";
+
+export type CommandStatus =
+  | "pending"
+  | "accepted"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "timed_out"
+  | "rejected"
+  | "canceled";
+
+export interface Command {
+  id: string;
+  type: string;
+  source: string;
+  target: string;
+  params: Record<string, unknown>;
+  status: CommandStatus;
+  result?: Record<string, unknown>;
+  error?: string;
+  correlationId?: string;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt?: number;
+}
+
+export interface CreateCommandInput {
+  type: string;
+  source: string;
+  target: string;
+  params?: Record<string, unknown>;
+  correlationId?: string;
+  ttlMs?: number;
+}
+
+export interface UpdateCommandInput {
+  status?: CommandStatus;
+  result?: Record<string, unknown>;
+  error?: string;
+}
+
+export interface Task {
+  id: number;
+  source: string;
+  title: string;
+  body: string;
+  severity: TaskSeverity;
+  status: TaskStatus;
+  target: string;
+  channel?: string;
+  dedupeKey?: string;
+  externalUrl?: string;
+  occurrenceCount: number;
+  claimedBy?: string;
+  claimedAt?: number;
+  claimExpiresAt?: number;
+  messageId?: number;
+  result?: string;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+  lastSeenAt: number;
+}
+
+export interface TaskEvent {
+  id: number;
+  taskId: number;
+  source: string;
+  type: string;
+  severity: TaskSeverity;
+  title: string;
+  body: string;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+}
+
+export interface IntegrationEventInput {
+  source?: string;
+  type?: string;
+  severity?: TaskSeverity;
+  status?: TaskStatus | "resolved";
+  title: string;
+  body: string;
+  target: string;
+  channel?: string;
+  dedupeKey?: string;
+  externalUrl?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IntegrationTaskStats {
+  source: string;
+  tasks: number;
+  openTasks: number;
+  waitingTasks: number;
+  failedTasks: number;
+  lastSeenAt?: number;
+  lastUpdatedAt?: number;
+}
+
+export interface IntegrationSummary {
+  name: string;
+  configured: boolean;
+  observed: boolean;
+  scopes: string[];
+  targets: string[];
+  channels: string[];
+  callbackHost?: string;
+  callbackConfigured: boolean;
+  rateLimit: {
+    limitPerMinute: number;
+    currentWindowCount: number;
+    windowStartedAt?: number;
+  };
+  taskStats: IntegrationTaskStats;
+}
+
+export type AutomationKind = "scheduled_task";
+export type AutomationCatchUpPolicy = "skip" | "run_once" | "run_all";
+export type AutomationConcurrencyPolicy = "skip" | "queue" | "replace";
+export type AutomationRunStatus =
+  | "scheduled"
+  | "dispatching"
+  | "waiting_agent"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "canceled"
+  | "timed_out";
+
+export interface AutomationExistingAgentPolicy {
+  mode: "existing_agent";
+  selector: {
+    provider?: SpawnProvider;
+    label?: string;
+    tags?: string[];
+    capabilities?: string[];
+  };
+  ifNoMatch?: "fail" | "spawn";
+}
+
+export interface AutomationOnDemandAgentPolicy {
+  mode: "on_demand_agent";
+  provider: SpawnProvider;
+  cwd?: string;
+  profile?: string;
+  approvalMode?: SpawnApprovalMode;
+  keepAlive?: boolean;
+  shutdownAfterMs?: number;
+}
+
+export type AutomationTargetPolicy = AutomationExistingAgentPolicy | AutomationOnDemandAgentPolicy;
+
+export interface AutomationTaskTemplate {
+  title: string;
+  body: string;
+  severity?: TaskSeverity;
+  dedupeKey?: string;
+  externalUrl?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Automation {
+  id: string;
+  kind: AutomationKind;
+  name: string;
+  description?: string;
+  enabled: boolean;
+  schedule: string;
+  timezone: string;
+  nextRunAt?: number;
+  catchUpPolicy: AutomationCatchUpPolicy;
+  concurrencyPolicy: AutomationConcurrencyPolicy;
+  orchestratorId: string;
+  targetPolicy: AutomationTargetPolicy;
+  taskTemplate: AutomationTaskTemplate;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface AutomationRun {
+  id: string;
+  automationId: string;
+  status: AutomationRunStatus;
+  scheduledFor: number;
+  startedAt?: number;
+  finishedAt?: number;
+  orchestratorId: string;
+  targetAgentId?: string;
+  spawnedAgentId?: string;
+  taskId?: number;
+  messageId?: number;
+  controlMessageId?: number;
+  error?: string;
+  result?: Record<string, unknown>;
+  meta: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+  shutdownRequestedAt?: number;
+}
+
+export interface CreateAutomationInput {
+  kind?: AutomationKind;
+  name: string;
+  description?: string;
+  enabled?: boolean;
+  schedule: string;
+  timezone?: string;
+  catchUpPolicy?: AutomationCatchUpPolicy;
+  concurrencyPolicy?: AutomationConcurrencyPolicy;
+  orchestratorId: string;
+  targetPolicy: AutomationTargetPolicy;
+  taskTemplate: AutomationTaskTemplate;
+}
+
+export interface UpdateAutomationInput {
+  name?: string;
+  description?: string | null;
+  enabled?: boolean;
+  schedule?: string;
+  timezone?: string;
+  catchUpPolicy?: AutomationCatchUpPolicy;
+  concurrencyPolicy?: AutomationConcurrencyPolicy;
+  orchestratorId?: string;
+  targetPolicy?: AutomationTargetPolicy;
+  taskTemplate?: AutomationTaskTemplate;
+}
+
+export type ChannelDirection = "inbound" | "outbound" | "bidirectional";
+
+export type ChannelRouteTarget =
+  | { type: "agent"; id: string }
+  | { type: "label"; id: string }
+  | { type: "tag"; id: string }
+  | { type: "capability"; id: string }
+  | { type: "broadcast" }
+  | { type: "orchestrator"; id: string }
+  | { type: "pool"; id: string };
+
+export type ChannelBindingMode = "exclusive" | "broadcast";
+
+export interface ChannelBinding {
+  id: string;
+  channelId: string;
+  conversationId?: string;
+  target: ChannelRouteTarget;
+  mode: ChannelBindingMode;
+  priority: number;
+  createdAt: number;
+  updatedAt: number;
+  poolSelector?: string;
+  poolAgentId?: string;
+  poolAgentEpoch?: number;
+  poolClaimExpiresAt?: number;
+}
+
+export interface ChannelTargetHealth {
+  status: "ok" | "warning" | "error";
+  detail: string;
+  target: ChannelRouteTarget;
+  matches: Array<{
+    id: string;
+    name: string;
+    status: AgentCard["status"];
+    ready: boolean;
+    lastSeen: number;
+    label?: string;
+    tags: string[];
+    capabilities: string[];
+  }>;
+}
+
+export interface ChannelSummary {
+  id: string;
+  name: string;
+  type: string;
+  transport: string;
+  agentId: string;
+  accountId: string;
+  status: AgentCard["status"];
+  ready: boolean;
+  direction: ChannelDirection;
+  target?: string;
+  binding?: ChannelBinding;
+  targetHealth?: ChannelTargetHealth;
+  topicChannels: string[];
+  capabilities: string[];
+  tags: string[];
+  lastSeen: number;
+  meta?: Record<string, unknown>;
+}
+
+export interface TaskStatusInput {
+  status: TaskStatus;
+  agentId?: string;
+  instanceId?: string;
+  epoch?: number;
+  result?: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface InboxThreadState {
+  operatorId: string;
+  peerId: string;
+  readCursorMessageId?: number;
+  archivedAtMessageId?: number;
+  updatedAt: number;
+}
+
+export interface InboxDraft {
+  operatorId: string;
+  peerId: string;
+  body: string;
+  subject?: string;
+  channel?: string;
+  updatedAt: number;
+}
+
+export interface InboxState {
+  operatorId: string;
+  threads: InboxThreadState[];
+  drafts: InboxDraft[];
+}
+
+export type ActivityKind = "message" | "reply" | "question" | "operator" | "pair" | "task" | "state";
+
+export interface ActivityEvent {
+  id: number;
+  operatorId?: string;
+  clientId?: string;
+  kind: ActivityKind;
+  title: string;
+  body?: string;
+  meta?: string;
+  icon?: string;
+  view?: string;
+  peer?: string;
+  messageId?: number;
+  pairId?: string;
+  taskId?: number;
+  agentId?: string;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+}
+
+export interface ActivityEventInput {
+  operatorId?: string;
+  clientId?: string;
+  kind: ActivityKind;
+  title: string;
+  body?: string;
+  meta?: string;
+  icon?: string;
+  view?: string;
+  peer?: string;
+  messageId?: number;
+  pairId?: string;
+  taskId?: number;
+  agentId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+// --- Orchestrators ---
+
+export type OrchestratorStatus = "online" | "offline";
+export type SpawnProvider = "claude" | "codex";
+export type SpawnApprovalMode = "open" | "guarded" | "read-only";
+
+export interface Orchestrator {
+  id: string;
+  hostname: string;
+  status: OrchestratorStatus;
+  agentId: string; // relay agent id for messaging
+  providers: SpawnProvider[];
+  baseDir: string;
+  apiUrl?: string;
+  envKeys: string[]; // names only, never values
+  version?: string;
+  protocolVersion?: number;
+  gitSha?: string;
+  health?: OrchestratorHealth;
+  meta: Record<string, unknown>;
+  managedAgents: ManagedAgent[];
+  lastSeen: number;
+  createdAt: number;
+}
+
+export interface OrchestratorHealth {
+  status: "ok" | "warn" | "error";
+  restartRequired: boolean;
+  issues: Array<{
+    code: "missing-version" | "outdated" | "protocol-mismatch" | "restart-required";
+    detail: string;
+  }>;
+}
+
+export interface ManagedAgent {
+  agentId: string;
+  provider: SpawnProvider;
+  tmuxSession: string;
+  cwd: string;
+  label?: string;
+  approvalMode: SpawnApprovalMode;
+  pid?: number;
+  startedAt: number;
+}
+
+export interface RegisterOrchestratorInput {
+  id: string;
+  hostname: string;
+  providers: SpawnProvider[];
+  baseDir: string;
+  apiUrl?: string;
+  envKeys?: string[];
+  version?: string;
+  protocolVersion?: number;
+  gitSha?: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface OrchestratorRuntimeInput {
+  version?: string;
+  protocolVersion?: number;
+  gitSha?: string;
+}
+
+export interface OrchestratorSpawnInput {
+  provider: SpawnProvider;
+  cwd?: string;
+  label?: string;
+  approvalMode?: SpawnApprovalMode;
+  prompt?: string;
+  env?: Record<string, string>;
+}
+
+export interface OrchestratorSpawnResult {
+  orchestratorId: string;
+  provider: SpawnProvider;
+  tmuxSession: string;
+  cwd: string;
+  label?: string;
+  approvalMode: SpawnApprovalMode;
+  pid?: number;
+  startedAt: number;
+}
+
+export interface Recipe {
+  name: string;
+  description: string;
+  version?: string;
+  author?: string;
+  agents: RecipeAgent[];
+  workflow?: RecipeWorkflow;
+  lifecycle?: RecipeLifecycle;
+}
+
+export interface RecipeAgent {
+  role: string;
+  provider: "claude" | "codex";
+  count?: number;
+  capabilities: string[];
+  label?: string;
+  tags?: string[];
+  approvalMode?: "open" | "guarded" | "read-only";
+  prompt?: string;
+  model?: string;
+  env?: Record<string, string>;
+}
+
+export interface RecipeWorkflow {
+  trigger?: string;
+  fanOut?: "all" | "first";
+  collect?: string;
+  routing?: RecipeRoute[];
+}
+
+export interface RecipeRoute {
+  pattern: string;
+  pipeline: string[];
+}
+
+export interface RecipeLifecycle {
+  mode?: "persistent" | "ephemeral";
+  idleTimeoutMs?: number;
+}
+
+export interface RecipeInstance {
+  id: string;
+  recipeName: string;
+  recipeSource: "builtin" | "user";
+  cwd: string;
+  orchestratorId: string;
+  status: "starting" | "running" | "stopping" | "stopped" | "failed";
+  agents: RecipeAgentInstance[];
+  startedAt: number;
+  stoppedAt?: number;
+  startedBy: string;
+  error?: string;
+}
+
+export interface RecipeAgentInstance {
+  role: string;
+  agentId: string;
+  provider: string;
+  status: "spawning" | "running" | "stopping" | "stopped" | "failed";
+  index?: number;
+}
+
+export interface ComponentToken {
+  sub: string;
+  role: "provider" | "channel" | "orchestrator" | "admin" | "dashboard" | string;
+  scope: string[];
+  iat: number;
+  exp?: number;
+  jti?: string;
+}
+
+export type TokenScope =
+  | "agent:read"
+  | "agent:write"
+  | "message:send"
+  | "message:read"
+  | "command:spawn"
+  | "command:shutdown"
+  | "command:*"
+  | "task:read"
+  | "task:write"
+  | "recipe:start"
+  | "recipe:stop"
+  | "admin:*";
+
+export interface HealthCheck {
+  name: string;
+  status: "ok" | "warn" | "error";
+  detail?: string;
+  count?: number;
+}
+
+export interface HealthReport {
+  status: "ok" | "degraded" | "error";
+  version: string;
+  generatedAt: number;
+  checks: HealthCheck[];
+}