agent-relay-sdk 0.2.0 → 0.2.2

package/dist/types.d.ts

@@ -12,12 +12,335 @@ export interface AgentCard {
     status: AgentStatus;
     instanceId?: string;
     epoch: number;
+    providerCapabilities?: ProviderCapabilities;
+    context?: ContextState;
     meta?: Record<string, unknown>;
     lastSeen: number;
     createdAt: number;
 }
 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" | "task" | "pair" | "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;
@@ -33,11 +356,68 @@ 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;
@@ -48,6 +428,8 @@ export interface SendMessageInput {
     replyTo?: number;
     claimable?: boolean;
     idempotencyKey?: string;
+    maxAgeSeconds?: number;
+    attachments?: AttachmentRef[];
     payload?: Record<string, unknown>;
     meta?: Record<string, unknown>;
 }
@@ -152,6 +534,8 @@ export interface RegisterAgentInput {
     ready?: boolean;
     status?: AgentCard["status"];
     instanceId?: string;
+    providerCapabilities?: ProviderCapabilities;
+    context?: ContextState;
     meta?: Record<string, unknown>;
 }
 export interface AgentSessionGuard {
@@ -232,6 +616,7 @@ export interface IntegrationEventInput {
     channel?: string;
     dedupeKey?: string;
     externalUrl?: string;
+    attachments?: AttachmentRef[];
     metadata?: Record<string, unknown>;
 }
 export interface IntegrationTaskStats {
@@ -245,8 +630,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[];
@@ -259,6 +655,23 @@ 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";
@@ -276,13 +689,22 @@ 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;
@@ -373,6 +795,9 @@ export type ChannelRouteTarget = {
 } | {
     type: "pool";
     id: string;
+} | {
+    type: "policy";
+    id: string;
 };
 export type ChannelBindingMode = "exclusive" | "broadcast";
 export interface ChannelBinding {
@@ -423,6 +848,20 @@ export interface ChannelSummary {
     lastSeen: number;
     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;
@@ -452,6 +891,26 @@ export interface InboxState {
     threads: InboxThreadState[];
     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 {
     id: number;
@@ -490,70 +949,555 @@ 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;
+    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;
     hostname: string;
     status: OrchestratorStatus;
     agentId: string;
     providers: SpawnProvider[];
+    providerStatus?: ProviderStatusReport[];
+    providerCatalog?: ProviderCatalogSummary[];
     baseDir: string;
     apiUrl?: string;
     envKeys: string[];
+    package?: RuntimePackageMetadata;
+    contracts?: RuntimeContracts;
+    capabilities?: RuntimeCapabilities;
+    contractCompatibility?: ContractCompatibility;
     version?: string;
     protocolVersion?: number;
     gitSha?: string;
     health?: OrchestratorHealth;
+    supervisor?: "process" | "systemd" | "unknown";
+    selfUnit?: string;
+    runtimePrefix?: string;
+    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;
     }>;
 }
 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;
     meta?: Record<string, unknown>;
 }
 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;
@@ -577,9 +1521,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>;
 }
 export interface RecipeWorkflow {
@@ -595,6 +1541,19 @@ 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 {
     id: string;
@@ -604,6 +1563,7 @@ export interface RecipeInstance {
     orchestratorId: string;
     status: "starting" | "running" | "stopping" | "stopped" | "failed";
     agents: RecipeAgentInstance[];
+    artifacts?: Artifact[];
     startedAt: number;
     stoppedAt?: number;
     startedBy: string;
@@ -620,16 +1580,105 @@ export interface ComponentToken {
     sub: string;
     role: "provider" | "channel" | "orchestrator" | "admin" | "dashboard" | string;
     scope: string[];
+    constraints?: TokenConstraints;
     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 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:read" | "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 {
     status: "ok" | "degraded" | "error";