101 lines
3.3 KiB
TypeScript
101 lines
3.3 KiB
TypeScript
/**
|
|
* RuntimePresenceTypes — shared types for namespace-scoped runtime discovery.
|
|
*
|
|
* These types define the contract between runtimes that announce their presence
|
|
* and consumers (Director, system.runtimes, monitoring) that discover them.
|
|
*
|
|
* See: ARCHITECTURE/ARCHITECTURE-NAMESPACE-DISCOVERY-AND-RUNTIME-PRESENCE.md
|
|
*/
|
|
|
|
import type { HealthSnapshotV1 } from './service-registry.js';
|
|
import type { RuntimeInventoryPlacementMetadata } from './placement.js';
|
|
|
|
/** What kind of claim a runtime makes on a namespace prefix. */
|
|
export type RuntimeClaimKind = 'authoritative' | 'proxy' | 'mirror' | 'local-only' | 'pool-member';
|
|
|
|
/** How a runtime exposes its actor inventory. */
|
|
export type RuntimeInventoryMode = 'embedded' | 'pull';
|
|
|
|
/** Known runtime types. */
|
|
export type RuntimeType = 'daemon' | 'browser' | 'cell' | 'container' | 'leaf' | 'worker' | 'folder';
|
|
|
|
/** Runtime presence events published on the namespace-scoped presence stream. */
|
|
export type RuntimePresenceEventV1 = 'announce' | 'heartbeat' | 'departed';
|
|
|
|
/** A single actor/component entry in a runtime's inventory. */
|
|
export interface RuntimeInventoryEntryV1 {
|
|
/** Mount path within the namespace (e.g., 'system.agents', 'explorer'). */
|
|
mount: string;
|
|
/** Actor/component type name (e.g., '_AgentsRoot', 'DirectorTree'). */
|
|
type?: string;
|
|
/** What surface this actor provides. */
|
|
surface?: 'headless' | 'dom' | 'webapp';
|
|
/** Which runtime hosts this actor. */
|
|
runtimeId: string;
|
|
/** What kind of claim this actor represents. */
|
|
claimKind: RuntimeClaimKind;
|
|
/** Placement and callability metadata for this actor. */
|
|
placement?: RuntimeInventoryPlacementMetadata;
|
|
/** Human-readable description. */
|
|
description?: string;
|
|
}
|
|
|
|
/** Full presence record for a runtime in a namespace. */
|
|
export interface RuntimePresenceRecordV1 {
|
|
version: '1';
|
|
|
|
/** The namespace this runtime participates in. */
|
|
namespaceRoot: string;
|
|
|
|
/** Unique identity for this runtime instance. */
|
|
runtimeId: string;
|
|
|
|
/** What kind of runtime this is. */
|
|
runtimeType: RuntimeType;
|
|
|
|
/** The NATS transport root this runtime uses. */
|
|
runtimeRoot: string;
|
|
|
|
/** Optional: authority root for deployment/ownership plane. */
|
|
authorityRoot?: string;
|
|
|
|
/** Optional: provider overlay root for hosting plane metadata. */
|
|
platformRoot?: string;
|
|
|
|
/** Optional: human-readable application name. */
|
|
app?: string;
|
|
|
|
/** What namespace prefixes this runtime claims to serve. */
|
|
claims: Array<{
|
|
prefix: string;
|
|
kind: RuntimeClaimKind;
|
|
}>;
|
|
|
|
/** How this runtime exposes its inventory. */
|
|
inventoryMode: RuntimeInventoryMode;
|
|
|
|
/** Inline actor list (when inventoryMode === 'embedded'). */
|
|
inventory?: RuntimeInventoryEntryV1[];
|
|
|
|
/** Mount path of a catalog actor (when inventoryMode === 'pull'). */
|
|
catalogMount?: string;
|
|
|
|
/** Optional: mount path for runtime lifecycle control. */
|
|
controlMount?: string;
|
|
|
|
/** Milliseconds before missing heartbeat means runtime is dead. 0 = no timeout. */
|
|
heartbeatTtlMs: number;
|
|
|
|
/** When this runtime first registered/announced. */
|
|
registeredAt: number;
|
|
|
|
/** Last heartbeat timestamp. */
|
|
lastHeartbeat: number;
|
|
|
|
/** Latest health snapshot from the runtime root actor. */
|
|
health?: HealthSnapshotV1;
|
|
|
|
/** Optional runtime-specific metadata. */
|
|
metadata?: Record<string, unknown>;
|
|
}
|