agent-relay-sdk 0.2.0 → 0.2.2

package/src/types.ts

@@ -13,6 +13,8 @@ export interface AgentCard {
   status: AgentStatus;
   instanceId?: string;
   epoch: number;
+  providerCapabilities?: ProviderCapabilities;
+  context?: ContextState;
   meta?: Record<string, unknown>;
   lastSeen: number;
   createdAt: number;
@@ -20,6 +22,291 @@ export interface AgentCard {
 
 export type AgentStatus = "online" | "idle" | "busy" | "stale" | "offline";
 
+export type CapabilitySource = "catalog" | "provider" | "runtime" | "override" | "estimate";
+export type CapabilityConfidence = "declared" | "reported" | "verified" | "estimated" | "unknown";
+
+export interface ProviderCapabilities {
+  lifecycle: {
+    managed: boolean;
+    shutdownHard: boolean;
+    restartHard: boolean;
+    semanticStatus?: boolean;
+    reconnect?: boolean;
+    hibernate?: boolean;
+    resume?: boolean;
+  };
+  model?: {
+    provider?: SpawnProvider | string;
+    id?: string;
+    alias?: string;
+    providerModel?: string;
+    effort?: SpawnEffort | string;
+    source: CapabilitySource;
+    confidence: CapabilityConfidence;
+    lastUpdatedAt?: number;
+  };
+  session?: {
+    approvalMode?: SpawnApprovalMode | string;
+    fileRead?: boolean;
+    fileWrite?: boolean;
+    shell?: boolean;
+    source: CapabilitySource;
+    confidence: CapabilityConfidence;
+    lastUpdatedAt?: number;
+  };
+  context?: {
+    stats?: {
+      source: "api" | "statusline" | "hook" | "estimate";
+      confidence: "exact" | "reported" | "estimated";
+    };
+    compact?: boolean;
+    clear?: boolean;
+    inject?: boolean;
+    fork?: boolean;
+    rollback?: boolean;
+    archive?: boolean;
+  };
+  terminal?: {
+    live?: {
+      read?: boolean;
+      write?: boolean;
+    };
+    attach?: {
+      create?: boolean;
+      read?: boolean;
+      write?: boolean;
+      detach?: boolean;
+    };
+  };
+  source: CapabilitySource;
+  confidence: CapabilityConfidence;
+  lastUpdatedAt: number;
+}
+
+export type ContextLifecycleState =
+  | "fresh"
+  | "primed"
+  | "working"
+  | "cooling"
+  | "compacting"
+  | "hibernating";
+
+export interface ContextProbeMetrics {
+  agentId: string;
+  contextPercent: number;
+  tokensUsed?: number;
+  tokensMax?: number;
+  quotaUsed?: number;
+  quotaLimit?: number;
+  quotaResetIn?: number;
+  model?: string;
+  effort?: string;
+  source: "statusline" | "hook" | "api" | "estimate";
+  confidence: "exact" | "reported" | "estimated";
+  timestamp: number;
+}
+
+export interface ContextState {
+  utilization: number;
+  tokensUsed?: number;
+  tokensMax?: number;
+  lifecycleState: ContextLifecycleState;
+  warmTopics: string[];
+  activeMemories: string[];
+  tasksSinceCompact: number;
+  lastCompactedAt?: number;
+  lastUpdatedAt: number;
+  source: "statusline" | "hook" | "api" | "estimate";
+  confidence: "exact" | "reported" | "estimated";
+}
+
+export interface ContextSnapshot {
+  id: number;
+  agentId: string;
+  context: ContextState;
+  utilization: number;
+  lifecycleState: ContextLifecycleState;
+  tokensUsed?: number;
+  tokensMax?: number;
+  source: ContextState["source"];
+  confidence: ContextState["confidence"];
+  capturedAt: number;
+}
+
+export type MemoryType = "organization" | "role" | "project" | "task" | "interaction" | "agent";
+export type MemoryVisibility = "private" | "project" | "org" | "public";
+export type MemorySensitivity = "public" | "normal" | "sensitive" | "secret";
+export type MemoryConfidence = "reported" | "inferred" | "verified";
+export type MemoryRedactionState = "raw" | "redacted" | "rejected";
+
+export interface Memory {
+  id: string;
+  type: MemoryType;
+  scope: string;
+  title: string;
+  content: string;
+  tags: string[];
+  visibility: MemoryVisibility;
+  sensitivity: MemorySensitivity;
+  confidence: MemoryConfidence;
+  redactionState: MemoryRedactionState;
+  relevanceScore: number;
+  sourceAgent?: string;
+  sourceTask?: number;
+  createdBy?: string;
+  contentHash?: string;
+  metadata: Record<string, unknown>;
+  accessCount: number;
+  lastAccessedAt?: number;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt?: number;
+}
+
+export interface CreateMemoryInput {
+  type: MemoryType;
+  scope: string;
+  title: string;
+  content: string;
+  tags?: string[];
+  visibility?: MemoryVisibility;
+  sensitivity?: MemorySensitivity;
+  confidence?: MemoryConfidence;
+  redactionState?: MemoryRedactionState;
+  relevanceScore?: number;
+  sourceAgent?: string;
+  sourceTask?: number;
+  createdBy?: string;
+  metadata?: Record<string, unknown>;
+  ttlMs?: number;
+}
+
+export interface UpdateMemoryInput {
+  title?: string;
+  content?: string;
+  tags?: string[];
+  visibility?: MemoryVisibility;
+  sensitivity?: MemorySensitivity;
+  confidence?: MemoryConfidence;
+  redactionState?: MemoryRedactionState;
+  relevanceScore?: number;
+  metadata?: Record<string, unknown>;
+  expiresAt?: number | null;
+}
+
+export interface MemoryQuery {
+  type?: MemoryType;
+  scope?: string;
+  tags?: string[];
+  minRelevance?: number;
+  limit?: number;
+  includeExpired?: boolean;
+  visibility?: MemoryVisibility;
+  includeSensitive?: boolean;
+}
+
+export interface MemorySearchResult {
+  memories: Memory[];
+  total: number;
+}
+
+export interface PackagedMemory {
+  memory: Memory;
+  reason: string;
+  priority: 1 | 2 | 3;
+  score?: number;
+}
+
+export interface TaskRoutingHints {
+  id?: number;
+  title?: string;
+  text?: string;
+  scope?: string;
+  tags?: string[];
+  capabilities?: string[];
+  target?: string;
+}
+
+export interface ContextBudget {
+  maxTokens: number;
+  maxMemories: number;
+  priorityCutoff: 1 | 2 | 3;
+}
+
+export interface TaskHistorySummary {
+  taskId: number;
+  agentId: string;
+  status: string;
+  summary?: string;
+  completedAt?: number;
+}
+
+export interface ContextPackage {
+  memories: PackagedMemory[];
+  rolePrompt?: string;
+  recentContext?: string;
+  taskHistory?: TaskHistorySummary[];
+  estimatedTokens: number;
+}
+
+export interface ContextPackageRequest {
+  task: TaskRoutingHints;
+  agent: AgentCard;
+  budget: ContextBudget;
+  memories?: Memory[];
+}
+
+export interface MemoryStats {
+  total: number;
+  byType: Partial<Record<MemoryType, number>>;
+  byScope: Record<string, number>;
+  bySensitivity: Partial<Record<MemorySensitivity, number>>;
+}
+
+export type ActiveMemoryClearReason = "compact" | "clearContext" | "restart" | "shutdown" | "manual";
+
+export interface MemoryBrokerCapabilities {
+  search: true;
+  create: boolean;
+  update: boolean;
+  delete: boolean;
+  stats: boolean;
+  assemble: boolean;
+  activeTracking: boolean;
+  activeList: boolean;
+  external: boolean;
+}
+
+export interface MemoryBrokerContext {
+  now: number;
+  actor: string;
+  scopes: string[];
+  relayUrl?: string;
+  requestId?: string;
+}
+
+export type MemoryBrokerKind = "sqlite" | "http" | "command";
+
+export interface SqliteMemoryBrokerConfig {
+  type: "sqlite";
+}
+
+export interface HttpMemoryBrokerConfig {
+  type: "http";
+  url: string;
+  tokenEnv?: string;
+  timeoutMs?: number;
+}
+
+export interface CommandMemoryBrokerConfig {
+  type: "command";
+  command: string;
+  args?: string[];
+  timeoutMs?: number;
+}
+
+export type MemoryBrokerConfig = SqliteMemoryBrokerConfig | HttpMemoryBrokerConfig | CommandMemoryBrokerConfig;
+
 export type MessageKind =
   | "chat"
   | "channel.event"
@@ -28,6 +315,71 @@ export type MessageKind =
   | "control"
   | "system";
 
+export type ArtifactKind = "image" | "audio" | "video" | "document" | "archive" | "other";
+export type ArtifactSensitivity = "public" | "normal" | "sensitive" | "secret";
+export type ArtifactVisibility = "private" | "project" | "org";
+export type ArtifactRole = "media" | "patch" | "report" | "log" | "output" | "input";
+
+export interface ArtifactBlob {
+  digest: string;
+  storageUri: string;
+  mediaType: string;
+  size: number;
+  createdAt: number;
+}
+
+export interface ArtifactLink {
+  id: string;
+  artifactId: string;
+  entityType: "message" | "task" | "recipeRun" | "recipeStep" | "channelEvent";
+  entityId: string;
+  role?: ArtifactRole;
+  title?: string;
+  createdBy: string;
+  createdAt: number;
+}
+
+export interface Artifact {
+  id: string;
+  blobDigest: string;
+  mediaType: string;
+  kind: ArtifactKind;
+  filename?: string;
+  size: number;
+  digest: string;
+  visibility: ArtifactVisibility;
+  sensitivity: ArtifactSensitivity;
+  createdBy: string;
+  createdAt: number;
+  expiresAt?: number;
+  metadata: Record<string, unknown>;
+  links?: ArtifactLink[];
+  url?: string;
+}
+
+export interface AttachmentRef {
+  artifactId: string;
+  kind?: ArtifactKind;
+  role?: ArtifactRole;
+  title?: string;
+  ref?: AttachmentSourceRef;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ChannelAttachmentRef {
+  artifactId?: string;
+  kind?: ArtifactKind;
+  role?: ArtifactRole;
+  title?: string;
+  ref?: AttachmentSourceRef;
+  metadata?: Record<string, unknown>;
+}
+
+export type AttachmentSourceRef =
+  | { type: "relay-blob"; id: string; [key: string]: unknown }
+  | { type: "external-url"; url: string; [key: string]: unknown }
+  | { type: "channel-file"; id: string; provider?: string; uniqueId?: string; [key: string]: unknown };
+
 export interface Message {
   id: number;
   from: string;
@@ -43,12 +395,93 @@ export interface Message {
   claimedAt?: number;
   claimExpiresAt?: number;
   idempotencyKey?: string;
+  deliveryStatus?: MessageDeliveryStatus;
+  deliveryAttempts?: number;
+  deliveryLastError?: string;
+  deliveryNextRetryAt?: number;
+  deliveryPoisonReason?: string;
+  deliveryUpdatedAt?: number;
+  queuedAt?: number;
+  maxAgeSeconds?: number;
+  resolvedToAgent?: string;
   payload: Record<string, unknown>;
   meta?: Record<string, unknown>;
+  reactions?: MessageReaction[];
   readBy: string[];
   createdAt: number;
 }
 
+export interface ReplyObligation {
+  messageId: number;
+  agentId: string;
+  from: string;
+  kind: MessageKind;
+  subject?: string;
+  channel?: string;
+  bodyPreview: string;
+  createdAt: number;
+  replyCommand: string;
+}
+
+export interface MessageReaction {
+  messageId: number;
+  actorId: string;
+  emoji: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export type RelayNotificationKind =
+  | "message"
+  | "reply"
+  | "error"
+  | "agent.blocked";
+
+export type RelayNotificationSeverity = "info" | "warning" | "error";
+
+export interface RelayNotification {
+  id: string;
+  kind: RelayNotificationKind;
+  severity: RelayNotificationSeverity;
+  title: string;
+  body: string;
+  messageId?: number;
+  agentId?: string;
+  threadPeer?: string;
+  view?: "chat" | "messages" | "agents" | "work" | "tasks" | "channels" | "overview";
+  createdAt: number;
+}
+
+export type MessageDeliveryStatus = "pending" | "delivered" | "queued" | "failed" | "dead";
+
+export interface MessageDeliveryAttempt {
+  id: number;
+  messageId: number;
+  agentId?: string;
+  action: "attempt" | "retry-now" | "mark-dead" | "clear";
+  status: MessageDeliveryStatus;
+  error?: string;
+  nextRetryAt?: number;
+  poisonReason?: string;
+  createdAt: number;
+}
+
+export interface MessageDeliveryState extends Pick<Message,
+  | "id"
+  | "to"
+  | "deliveryStatus"
+  | "deliveryAttempts"
+  | "deliveryLastError"
+  | "deliveryNextRetryAt"
+  | "deliveryPoisonReason"
+  | "deliveryUpdatedAt"
+  | "queuedAt"
+  | "maxAgeSeconds"
+  | "resolvedToAgent"
+> {
+  attempts: MessageDeliveryAttempt[];
+}
+
 export interface SendMessageInput {
   from: string;
   to: string;
@@ -59,6 +492,8 @@ export interface SendMessageInput {
   replyTo?: number;
   claimable?: boolean;
   idempotencyKey?: string;
+  maxAgeSeconds?: number;
+  attachments?: AttachmentRef[];
   payload?: Record<string, unknown>;
   meta?: Record<string, unknown>;
 }
@@ -175,6 +610,8 @@ export interface RegisterAgentInput {
   ready?: boolean;
   status?: AgentCard["status"];
   instanceId?: string;
+  providerCapabilities?: ProviderCapabilities;
+  context?: ContextState;
   meta?: Record<string, unknown>;
 }
 
@@ -280,6 +717,7 @@ export interface IntegrationEventInput {
   channel?: string;
   dedupeKey?: string;
   externalUrl?: string;
+  attachments?: AttachmentRef[];
   metadata?: Record<string, unknown>;
 }
 
@@ -295,8 +733,19 @@ export interface IntegrationTaskStats {
 
 export interface IntegrationSummary {
   name: string;
+  displayName?: string;
+  description?: string;
+  enabled: boolean;
   configured: boolean;
   observed: boolean;
+  type?: string;
+  icon?: string;
+  accentColor?: string;
+  tags: string[];
+  homepageUrl?: string;
+  repositoryUrl?: string;
+  docsUrl?: string;
+  manifest?: Record<string, unknown>;
   scopes: string[];
   targets: string[];
   channels: string[];
@@ -310,6 +759,32 @@ export interface IntegrationSummary {
   taskStats: IntegrationTaskStats;
 }
 
+export type RuntimeContractName =
+  | "relayApi"
+  | "orchestratorProtocol"
+  | "runnerProtocol"
+  | "providerPluginProtocol";
+
+export type RuntimeContracts = Partial<Record<RuntimeContractName, number>>;
+export type RuntimeCapabilities = Record<string, boolean>;
+
+export interface RuntimePackageMetadata {
+  name: string;
+  version: string;
+}
+
+export interface ContractCompatibilityIssue {
+  contract: string;
+  expected: string;
+  actual?: number;
+}
+
+export interface ContractCompatibility {
+  status: "compatible" | "incompatible" | "unknown";
+  compatible: boolean;
+  issues: ContractCompatibilityIssue[];
+}
+
 export type AutomationKind = "scheduled_task";
 export type AutomationCatchUpPolicy = "skip" | "run_once" | "run_all";
 export type AutomationConcurrencyPolicy = "skip" | "queue" | "replace";
@@ -337,15 +812,25 @@ export interface AutomationExistingAgentPolicy {
 export interface AutomationOnDemandAgentPolicy {
   mode: "on_demand_agent";
   provider: SpawnProvider;
+  model?: string;
+  effort?: SpawnEffort;
   cwd?: string;
+  workspaceMode?: WorkspaceMode;
   profile?: string;
   approvalMode?: SpawnApprovalMode;
   keepAlive?: boolean;
+  runtimeBudget?: AutomationRuntimeBudget;
   shutdownAfterMs?: number;
 }
 
 export type AutomationTargetPolicy = AutomationExistingAgentPolicy | AutomationOnDemandAgentPolicy;
 
+export interface AutomationRuntimeBudget {
+  maxRuntimeMs: number;
+  warnAtMs?: number;
+  warningMessage?: string;
+}
+
 export interface AutomationTaskTemplate {
   title: string;
   body: string;
@@ -429,7 +914,8 @@ export type ChannelRouteTarget =
   | { type: "capability"; id: string }
   | { type: "broadcast" }
   | { type: "orchestrator"; id: string }
-  | { type: "pool"; id: string };
+  | { type: "pool"; id: string }
+  | { type: "policy"; id: string };
 
 export type ChannelBindingMode = "exclusive" | "broadcast";
 
@@ -484,6 +970,22 @@ export interface ChannelSummary {
   meta?: Record<string, unknown>;
 }
 
+export interface ChannelEventInput {
+  body?: string;
+  payload: Record<string, unknown>;
+  attachments?: ChannelAttachmentRef[];
+  conversationId?: string;
+  idempotencyKey?: string;
+  instanceId?: string;
+  epoch?: number;
+}
+
+export interface ChannelEventResult {
+  messages: Message[];
+  bindings: ChannelBinding[];
+  created: boolean;
+}
+
 export interface TaskStatusInput {
   status: TaskStatus;
   agentId?: string;
@@ -517,6 +1019,28 @@ export interface InboxState {
   drafts: InboxDraft[];
 }
 
+export interface ChatHistoryImportEntry {
+  position: number;
+  originalMessageId: number;
+  originalFrom: string;
+  originalTo: string;
+  originalCreatedAt: number;
+  message: Message;
+}
+
+export interface ChatHistoryImport {
+  id: string;
+  targetAgentId?: string;
+  targetSpawnRequestId?: string;
+  sourcePeerId: string;
+  sourceAgentId?: string;
+  sourceThreadId?: string;
+  sourceAgentLabel?: string;
+  importedBy: string;
+  importedAt: number;
+  entries: ChatHistoryImportEntry[];
+}
+
 export type ActivityKind = "message" | "reply" | "question" | "operator" | "pair" | "task" | "state";
 
 export interface ActivityEvent {
@@ -560,6 +1084,342 @@ export interface ActivityEventInput {
 export type OrchestratorStatus = "online" | "offline";
 export type SpawnProvider = "claude" | "codex";
 export type SpawnApprovalMode = "open" | "guarded" | "read-only";
+export type SpawnEffort = "low" | "medium" | "high" | "xhigh" | "max";
+export type WorkspaceMode = "isolated" | "shared" | "inherit";
+export type WorkspaceStatus = "active" | "ready" | "conflict" | "review_requested" | "merge_planned" | "merged" | "abandoned" | "cleanup_requested" | "cleaned";
+
+/** How a workspace's work is integrated back into its base branch. */
+export type WorkspaceMergeStrategy = "pr" | "rebase-ff" | "auto";
+
+export interface WorkspaceProbeWorktree {
+  path: string;
+  branch?: string;
+  headSha?: string;
+  bare?: boolean;
+  detached?: boolean;
+  prunable?: boolean;
+  locked?: boolean;
+  reason?: string;
+}
+
+export interface WorkspaceProbe {
+  path: string;
+  isGitRepo: boolean;
+  repoRoot?: string;
+  branch?: string;
+  headSha?: string;
+  dirty?: boolean;
+  detached?: boolean;
+  worktrees?: WorkspaceProbeWorktree[];
+  error?: string;
+}
+
+export interface WorkspaceGitCommit {
+  sha: string;
+  message: string;
+  at?: number;
+}
+
+/**
+ * Live git state of a workspace worktree, computed on the host by the
+ * orchestrator. Used to surface whether a worktree contains actual work
+ * (commits ahead of base, dirty files) so the dashboard isn't a black box and
+ * so exit-time reconcile can decide cleanup-vs-flag.
+ */
+export interface WorkspaceGitState {
+  /** Commits on the agent branch not yet in base (work the agent produced). */
+  ahead?: number;
+  /** Commits in base not in the agent branch (how far base moved on). */
+  behind?: number;
+  /** True if the worktree has uncommitted/untracked changes. */
+  dirty?: boolean;
+  /** Number of dirty (porcelain) entries. */
+  dirtyCount?: number;
+  /** Most recent commit in the worktree. */
+  lastCommit?: WorkspaceGitCommit;
+  /** Ref/sha the ahead/behind counts were computed against. */
+  baseRef?: string;
+  /** Set when the worktree path no longer exists on disk. */
+  missing?: boolean;
+  /** Populated when git interrogation failed. */
+  error?: string;
+}
+
+/**
+ * Pre-flight check for integrating a workspace's work, computed on the host.
+ * Reports whether the merge would be clean, conflict, or is a no-op, and which
+ * strategy `auto` would pick — so the dashboard can warn before the user acts.
+ */
+export interface WorkspaceMergePreview {
+  /** Strategy `auto` would resolve to given the repo's remote/gh state. */
+  strategy: "pr" | "rebase-ff";
+  /** Commits on the agent branch not yet in base. */
+  ahead?: number;
+  /** Commits in base not in the agent branch. */
+  behind?: number;
+  /** Uncommitted/untracked entries in the worktree. */
+  dirtyCount?: number;
+  /** True if the three-way merge of base and the branch would conflict. */
+  conflict?: boolean;
+  /** True if base can fast-forward to the branch with no rebase needed. */
+  cleanFastForward?: boolean;
+  /** Whether an `origin` remote is configured. */
+  hasRemote?: boolean;
+  /** Whether the `gh` CLI is available on the host. */
+  ghAvailable?: boolean;
+  /** Resolved base branch name the work would land on. */
+  baseRef?: string;
+  /** Human-readable reason a merge can't proceed (no work, dirty, missing). */
+  reason?: string;
+  /** Set when the worktree path no longer exists. */
+  missing?: boolean;
+  /** Populated when git interrogation failed. */
+  error?: string;
+}
+
+/** Outcome of a `workspace.merge` command executed on the host. */
+export interface WorkspaceMergeResult {
+  workspaceId?: string;
+  /** Strategy actually used. */
+  strategy: "pr" | "rebase-ff";
+  /** True when work was landed locally (rebase-ff into base). */
+  merged: boolean;
+  /** True when a merge was prevented by conflicts. */
+  conflict?: boolean;
+  /** PR URL when the pr strategy opened one. */
+  prUrl?: string;
+  branch?: string;
+  baseRef?: string;
+  /** SHA base now points at after a successful rebase-ff. */
+  mergedSha?: string;
+  branchDeleted?: boolean;
+  worktreeRemoved?: boolean;
+  /** Resulting workspace status the relay should record. */
+  status: WorkspaceStatus;
+  /** Populated when the merge could not complete. */
+  error?: string;
+}
+
+/** One changed file in a workspace diff against its base. */
+export interface WorkspaceDiffFile {
+  path: string;
+  /** Lines added (undefined for binary files). */
+  additions?: number;
+  /** Lines removed (undefined for binary files). */
+  deletions?: number;
+  binary?: boolean;
+}
+
+/** Diff of a workspace's committed work against its base, computed on the host. */
+export interface WorkspaceDiff {
+  baseRef?: string;
+  ahead?: number;
+  files: WorkspaceDiffFile[];
+  /** Unified patch text (may be truncated). */
+  patch?: string;
+  /** True when the patch was capped at the size limit. */
+  truncated?: boolean;
+  /** Uncommitted entries in the worktree, not part of the committed diff. */
+  dirtyCount?: number;
+  missing?: boolean;
+  error?: string;
+}
+
+/** A worktree found on disk with no matching active workspace row. */
+export interface WorkspaceOrphan {
+  worktreePath: string;
+  repoRoot: string;
+  branch?: string;
+  headSha?: string;
+  /** True if a DB row exists for this path but is already terminal (cleaned/merged). */
+  hadTerminalRow?: boolean;
+}
+
+export interface WorkspaceMetadata {
+  id?: string;
+  mode: WorkspaceMode;
+  requestedMode?: WorkspaceMode;
+  repoRoot?: string;
+  sourceCwd?: string;
+  worktreePath?: string;
+  branch?: string;
+  baseRef?: string;
+  baseSha?: string;
+  status?: WorkspaceStatus;
+  stewardAgentId?: string;
+  probe?: WorkspaceProbe;
+}
+
+export interface WorkspaceRecord {
+  id: string;
+  repoRoot: string;
+  sourceCwd: string;
+  worktreePath: string;
+  branch?: string;
+  baseRef?: string;
+  baseSha?: string;
+  mode: WorkspaceMode;
+  requestedMode?: WorkspaceMode;
+  status: WorkspaceStatus;
+  ownerAgentId?: string;
+  ownerPolicyName?: string;
+  ownerAutomationRunId?: string;
+  stewardAgentId?: string;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+  readyAt?: number;
+  cleanedAt?: number;
+}
+
+export interface ConfigEntry<T = unknown> {
+  namespace: string;
+  key: string;
+  value: T;
+  version: number;
+  updatedAt: string;
+  updatedBy?: string;
+}
+
+export interface ConfigHistoryEntry<T = unknown> {
+  id: number;
+  namespace: string;
+  key: string;
+  value: T;
+  version: number;
+  changedAt: string;
+  changedBy?: string;
+}
+
+export type ManagedAgentStatus = "stopped" | "starting" | "running" | "stopping" | "backoff";
+
+export interface ManagedAgentState {
+  policyName: string;
+  status: ManagedAgentStatus;
+  agentId?: string;
+  orchestratorId: string;
+  provider: SpawnProvider;
+  tmuxSession?: string;
+  spawnRequestId?: string;
+  workspaceId?: string;
+  workspacePath?: string;
+  workspaceBranch?: string;
+  lastSpawnAt?: number;
+  lastStopAt?: number;
+  healthySince?: number;
+  restartCount: number;
+  consecutiveFailures: number;
+  backoffUntil?: number;
+  lastError?: string;
+  updatedAt: number;
+}
+
+export type SpawnPolicyMode = "always-on" | "on-demand";
+
+export type AgentProfileProvider = SpawnProvider | "any";
+export type AgentProfileBase = "host" | "minimal" | "isolated";
+export type AgentProfileInstructionPolicy = "allow" | "ignore";
+export type AgentProfileCategoryMode = "host" | "profile" | "repo" | "none";
+export type AgentProfileFilesystemScope = "repo" | "workspace" | "host";
+
+export interface AgentProfileAssetRef {
+  source: "relay" | "repo" | "inline" | "provider";
+  ref: string;
+  enabled: boolean;
+  provider?: AgentProfileProvider;
+  meta?: Record<string, unknown>;
+}
+
+export interface AgentProfile {
+  name: string;
+  description?: string;
+  provider?: AgentProfileProvider;
+  base: AgentProfileBase;
+  builtIn?: boolean;
+  instructions: {
+    system?: string;
+    append: string[];
+    repoInstructions: AgentProfileInstructionPolicy;
+    globalInstructions: AgentProfileInstructionPolicy;
+  };
+  relay: {
+    context: boolean;
+    skills: boolean;
+    plugins: boolean;
+    statusLine: boolean;
+  };
+  skills: AgentProfileAssetRef[];
+  plugins: AgentProfileAssetRef[];
+  mcp: {
+    mode: AgentProfileCategoryMode;
+    servers?: Record<string, unknown>;
+  };
+  hooks: {
+    mode: AgentProfileCategoryMode;
+  };
+  permissions: {
+    mode?: SpawnApprovalMode;
+    filesystem: AgentProfileFilesystemScope;
+  };
+  env: Record<string, string>;
+  providerOptions: Record<string, unknown>;
+}
+
+export type AgentProfileProjectionResult = "applied" | "partial" | "unsupported" | "not-applicable";
+
+export interface AgentProfileProjectionEntry {
+  capability: string;
+  requested: string;
+  result: AgentProfileProjectionResult;
+  detail: string;
+}
+
+export interface AgentProfileProjectionReport {
+  profileName: string;
+  provider: SpawnProvider;
+  base: AgentProfileBase;
+  generatedAt: number;
+  entries: AgentProfileProjectionEntry[];
+  warnings: string[];
+  unsupported: string[];
+}
+
+export interface SpawnPolicy {
+  name: string;
+  description?: string;
+  // Desired on/off switch. `false` keeps the policy from (re)spawning even for
+  // always-on mode, so a manual stop survives reconcile ticks. Defaults to true.
+  enabled?: boolean;
+  orchestratorId: string;
+  cwd: string;
+  provider: SpawnProvider;
+  workspaceMode?: WorkspaceMode;
+  rig?: string;
+  model?: string;
+  effort?: SpawnEffort;
+  profile?: string;
+  providerArgs: string[];
+  prompt?: string;
+  tags: string[];
+  capabilities: string[];
+  label?: string;
+  mode: SpawnPolicyMode;
+  permissionMode: SpawnApprovalMode;
+  restartOnUpdate: boolean;
+  scheduledDailyRestart: boolean;
+  onDemand?: {
+    keepaliveSeconds: number;
+    idleDefinition: "no-activity";
+  };
+  backoff: {
+    schedule: number[];
+    resetAfterSeconds: number;
+  };
+  binding?: {
+    type: "channel";
+    channelId: string;
+  };
+}
 
 export interface Orchestrator {
   id: string;
@@ -567,24 +1427,51 @@ export interface Orchestrator {
   status: OrchestratorStatus;
   agentId: string; // relay agent id for messaging
   providers: SpawnProvider[];
+  providerStatus?: ProviderStatusReport[];
+  providerCatalog?: ProviderCatalogSummary[];
   baseDir: string;
   apiUrl?: string;
   envKeys: string[]; // names only, never values
+  package?: RuntimePackageMetadata;
+  contracts?: RuntimeContracts;
+  capabilities?: RuntimeCapabilities;
+  contractCompatibility?: ContractCompatibility;
   version?: string;
   protocolVersion?: number;
   gitSha?: string;
   health?: OrchestratorHealth;
+  // Self-reported host supervision (how the orchestrator's own process is run),
+  // used to target a remote self-upgrade at the right unit.
+  supervisor?: "process" | "systemd" | "unknown";
+  selfUnit?: string;
+  runtimePrefix?: string;
+  // In-flight / last remote upgrade state, reconciled by the relay against the
+  // version the orchestrator reports after it restarts.
+  upgrade?: OrchestratorUpgradeState;
   meta: Record<string, unknown>;
   managedAgents: ManagedAgent[];
   lastSeen: number;
   createdAt: number;
 }
 
+export interface OrchestratorUpgradeState {
+  desiredVersion: string;
+  status: "pending" | "succeeded" | "failed";
+  commandId?: string;
+  providers?: string[];
+  fromVersion?: string;
+  requestedBy?: string;
+  requestedAt: number;
+  settledAt?: number;
+  error?: string;
+}
+
 export interface OrchestratorHealth {
-  status: "ok" | "warn" | "error";
+  status: "ok" | "warn" | "restart-required" | "upgrade-required" | "unknown";
   restartRequired: boolean;
+  upgradeRequired?: boolean;
   issues: Array<{
-    code: "missing-version" | "outdated" | "protocol-mismatch" | "restart-required";
+    code: "missing-version" | "package-drift" | "missing-contract" | "protocol-mismatch" | "restart-required" | "upgrade-required";
     detail: string;
   }>;
 }
@@ -592,21 +1479,80 @@ export interface OrchestratorHealth {
 export interface ManagedAgent {
   agentId: string;
   provider: SpawnProvider;
+  model?: string;
+  effort?: SpawnEffort;
+  profile?: string;
+  workspaceMode?: WorkspaceMode;
+  workspace?: WorkspaceMetadata;
+  sessionName?: string;
+  supervisor?: "process" | "systemd" | "unknown";
+  systemdUnit?: string;
+  terminalSession?: string;
+  terminalAvailable?: boolean;
   tmuxSession: string;
   cwd: string;
   label?: string;
   approvalMode: SpawnApprovalMode;
+  policyName?: string;
+  spawnRequestId?: string;
+  automationRunId?: string;
   pid?: number;
   startedAt: number;
 }
 
+export interface ManagedSessionExitDiagnostics {
+  agentId: string;
+  provider: SpawnProvider;
+  workspaceMode?: WorkspaceMode;
+  workspace?: WorkspaceMetadata;
+  sessionName?: string;
+  tmuxSession: string;
+  cwd: string;
+  label?: string;
+  policyName?: string;
+  spawnRequestId?: string;
+  automationRunId?: string;
+  supervisor: "process" | "systemd" | "unknown";
+  systemdUnit?: string;
+  terminalSession?: string;
+  terminalAvailable?: boolean;
+  pid?: number;
+  currentPid?: number;
+  startedAt: number;
+  detectedAt: number;
+  runtimeMs: number;
+  logFile?: string;
+  logBytes?: number;
+  logEmpty?: boolean;
+  logTail?: string[];
+  runnerInfoFile?: string;
+  runnerInfoPresent?: boolean;
+  systemd?: {
+    unit: string;
+    activeState?: string;
+    subState?: string;
+    result?: string;
+    execMainCode?: string;
+    execMainStatus?: string;
+    mainPid?: number;
+    unavailable?: string;
+  };
+  unavailable?: string[];
+  lastError: string;
+}
+
 export interface RegisterOrchestratorInput {
   id: string;
   hostname: string;
   providers: SpawnProvider[];
+  providerStatus?: ProviderStatusReport[];
+  providerCatalog?: ProviderCatalogSummary[];
   baseDir: string;
   apiUrl?: string;
   envKeys?: string[];
+  package?: RuntimePackageMetadata;
+  contracts?: RuntimeContracts;
+  capabilities?: RuntimeCapabilities;
   version?: string;
   protocolVersion?: number;
   gitSha?: string;
@@ -614,23 +1560,120 @@ export interface RegisterOrchestratorInput {
 }
 
 export interface OrchestratorRuntimeInput {
+  package?: RuntimePackageMetadata;
+  contracts?: RuntimeContracts;
+  capabilities?: RuntimeCapabilities;
   version?: string;
   protocolVersion?: number;
   gitSha?: string;
+  providers?: SpawnProvider[];
+  providerStatus?: ProviderStatusReport[];
+  providerCatalog?: ProviderCatalogSummary[];
 }
 
 export interface OrchestratorSpawnInput {
   provider: SpawnProvider;
+  model?: string;
+  effort?: SpawnEffort;
   cwd?: string;
+  workspaceMode?: WorkspaceMode;
   label?: string;
   approvalMode?: SpawnApprovalMode;
   prompt?: string;
+  systemPromptAppend?: string;
   env?: Record<string, string>;
 }
 
+export interface ProviderStatusReport {
+  name: SpawnProvider;
+  available: boolean;
+  checkedAt: number;
+  reason?: string;
+  version?: string;
+  features?: Record<string, boolean>;
+  cli?: {
+    command: string;
+    path?: string;
+    ok: boolean;
+    version?: string;
+    error?: string;
+  };
+  runner?: {
+    command: string;
+    path?: string;
+    ok: boolean;
+    version?: string;
+    error?: string;
+  };
+}
+
+export interface ProviderCatalogSummary {
+  provider: SpawnProvider;
+  label: string;
+  defaultModel?: string;
+  models: Array<{
+    alias: string;
+    label: string;
+    providerModel: string;
+    efforts: SpawnEffort[];
+    defaultEffort?: SpawnEffort;
+    limits?: {
+      contextWindowTokens?: {
+        value: number;
+        source: "catalog" | "provider" | "runtime" | "override";
+        confidence: "declared" | "verified" | "estimated" | "unknown";
+        lastUpdatedAt?: number;
+      };
+      maxOutputTokens?: {
+        value: number;
+        source: "catalog" | "provider" | "runtime" | "override";
+        confidence: "declared" | "verified" | "estimated" | "unknown";
+        lastUpdatedAt?: number;
+      };
+    };
+    capabilities?: {
+      modalities: {
+        input: {
+          text: boolean;
+          image?: boolean;
+          audio?: boolean;
+          video?: boolean;
+          pdf?: boolean;
+        };
+        output: {
+          text: boolean;
+          image?: boolean;
+          audio?: boolean;
+          video?: boolean;
+        };
+      };
+      tools?: {
+        code?: boolean;
+        review?: boolean;
+        debug?: boolean;
+        refactor?: boolean;
+        shell?: boolean;
+        fileRead?: boolean;
+        fileWrite?: boolean;
+        webSearch?: boolean;
+        imageGeneration?: boolean;
+        imageEditing?: boolean;
+      };
+      source: "catalog" | "provider" | "runtime" | "override";
+      confidence: "declared" | "verified" | "estimated" | "unknown";
+      lastUpdatedAt?: number;
+    };
+  }>;
+}
+
 export interface OrchestratorSpawnResult {
   orchestratorId: string;
   provider: SpawnProvider;
+  sessionName?: string;
+  supervisor?: "process" | "systemd" | "unknown";
+  systemdUnit?: string;
+  terminalSession?: string;
+  terminalAvailable?: boolean;
   tmuxSession: string;
   cwd: string;
   label?: string;
@@ -656,9 +1699,11 @@ export interface RecipeAgent {
   capabilities: string[];
   label?: string;
   tags?: string[];
+  memoryTags?: string[];
   approvalMode?: "open" | "guarded" | "read-only";
   prompt?: string;
   model?: string;
+  effort?: SpawnEffort;
   env?: Record<string, string>;
 }
 
@@ -677,6 +1722,20 @@ export interface RecipeRoute {
 export interface RecipeLifecycle {
   mode?: "persistent" | "ephemeral";
   idleTimeoutMs?: number;
+  memory?: RecipeMemoryPolicy;
+}
+
+export interface RecipeMemoryPolicy {
+  injectOnAssign?: boolean;
+  autoCapture?: boolean;
+  captureTypes?: MemoryType[];
+  memoryTags?: string[];
+  alwaysReload?: string[];
+  scope?: string;
+  maxTokens?: number;
+  maxMemories?: number;
+  priorityCutoff?: 1 | 2 | 3;
+  ttlMs?: number;
 }
 
 export interface RecipeInstance {
@@ -687,6 +1746,7 @@ export interface RecipeInstance {
   orchestratorId: string;
   status: "starting" | "running" | "stopping" | "stopped" | "failed";
   agents: RecipeAgentInstance[];
+  artifacts?: Artifact[];
   startedAt: number;
   stoppedAt?: number;
   startedBy: string;
@@ -705,30 +1765,142 @@ export interface ComponentToken {
   sub: string;
   role: "provider" | "channel" | "orchestrator" | "admin" | "dashboard" | string;
   scope: string[];
+  constraints?: TokenConstraints;
   iat: number;
   exp?: number;
   jti?: string;
 }
 
+export interface TokenRecord {
+  jti: string;
+  sub: string;
+  role: string;
+  scope: string[];
+  constraints?: TokenConstraints;
+  profileId?: string;
+  issuedAt: number;
+  expiresAt?: number;
+  revokedAt?: number;
+  createdBy?: string;
+}
+
+export interface TokenProfile {
+  id: string;
+  name: string;
+  description?: string;
+  role: string;
+  scope: string[];
+  constraints?: TokenConstraints;
+  ttlSeconds?: number;
+  builtIn: boolean;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface CreateTokenProfileInput {
+  id?: string;
+  name: string;
+  description?: string;
+  role: string;
+  scope: string[];
+  constraints?: TokenConstraints;
+  ttlSeconds?: number;
+  createdBy?: string;
+}
+
+export type UpdateTokenProfileInput = Partial<Omit<CreateTokenProfileInput, "id">>;
+
+export interface TokenConstraints {
+  agents?: string[];
+  policies?: string[];
+  parentAgents?: string[];
+  targets?: string[];
+  channels?: string[];
+  orchestrators?: string[];
+  hosts?: string[];
+  cwd?: string;
+  cwdPrefixes?: string[];
+  taskIds?: string[];
+  memoryScopes?: string[];
+  integrationNames?: string[];
+  spawnRequestIds?: string[];
+  terminalAttach?: boolean;
+  logsRead?: boolean;
+  canDelegate?: boolean;
+}
+
 export type TokenScope =
+  | "system:admin"
+  | "token:read"
+  | "token:write"
   | "agent:read"
   | "agent:write"
-  | "message:send"
   | "message:read"
-  | "command:spawn"
-  | "command:shutdown"
-  | "command:*"
+  | "message:send"
   | "task:read"
   | "task:write"
+  | "command:read"
+  | "command:write"
+  | "command:*"
+  | "artifact:read"
+  | "artifact:write"
+  | "artifact:admin"
+  | "memory:read"
+  | "memory:write"
+  | "memory:admin"
+  | "mcp:use"
+  | "terminal:attach"
+  | "logs:read"
+  | "integration:read"
+  | "integration:write"
+  | "channel:read"
+  | "channel:write"
+  | "stats:read"
+  | "health:read"
+  | "events:read"
+  | "command:spawn"
+  | "command:shutdown"
   | "recipe:start"
   | "recipe:stop"
   | "admin:*";
 
+export interface MaintenanceJob {
+  id: string;
+  title: string;
+  description?: string;
+  intervalMs: number;
+  timeoutMs: number;
+  enabled: boolean;
+  runOnStart: boolean;
+  lastRunAt?: number;
+  nextRunAt?: number;
+  lastDurationMs?: number;
+  lastStatus: "idle" | "running" | "succeeded" | "failed" | "disabled";
+  lastError?: string;
+  lastResult?: Record<string, unknown>;
+  consecutiveFailures: number;
+  running: boolean;
+  leaseUntil?: number;
+  updatedAt: number;
+}
+
+export interface MaintenanceJobRun {
+  id: string;
+  status: "succeeded" | "failed" | "skipped";
+  startedAt: number;
+  finishedAt: number;
+  durationMs: number;
+  result?: Record<string, unknown>;
+  error?: string;
+}
+
 export interface HealthCheck {
   name: string;
   status: "ok" | "warn" | "error";
   detail?: string;
   count?: number;
+  subjects?: Array<{ id: string; label?: string; status?: string; detail?: string }>;
 }
 
 export interface HealthReport {