@volter/supercode-orchestrator 0.4.4

package/index.d.ts

@@ -0,0 +1,508 @@
+// Types for the orchestrator IR — docs/ORCHESTRATOR-IR.md §2 is normative.
+//
+// ONT-6: every record shape is the Rust ontology's
+// (`crates/interchange/src/orchestration/`, `crates/interchange/src/ontology/`), reached
+// through `./ontology.d.ts` — written by
+// `node sdk/orchestrator/scripts/generate-types.mjs` from `supercode ontology schema`.
+// Declare no record here; add the field in Rust and regenerate.
+
+import type {
+  Access,
+  AccessPolicy,
+  ArtifactFidelity,
+  Attachment,
+  Binding,
+  ChannelConfig,
+  EndReason,
+  EnvValue,
+  Fidelity,
+  Fire,
+  FireStatus,
+  Handoff,
+  HarnessId,
+  Job,
+  JobOrigin,
+  Obligation,
+  ObligationSource,
+  ObligationState,
+  OutboundContent,
+  PermissionDefault,
+  PermissionPolicy,
+  PermissionUnattended,
+  PersonaRef,
+  Posted,
+  Profile,
+  ProfileResidue,
+  Recurrence,
+  Repeat,
+  Residue,
+  Route,
+  RouteMatch,
+  Schedule,
+  SecretRef,
+  SurfaceKey,
+  Target,
+  Trigger,
+  WebhookSubscription,
+  Worker,
+  WorkerSpec,
+  Orchestration,
+} from './ontology.js';
+
+export type {
+  Access,
+  AccessPolicy,
+  ArtifactFidelity,
+  Attachment,
+  Binding,
+  ChannelConfig,
+  EndReason,
+  EnvValue,
+  Fidelity,
+  Fire,
+  FireStatus,
+  Handoff,
+  HarnessId,
+  Job,
+  JobOrigin,
+  Obligation,
+  ObligationSource,
+  ObligationState,
+  OutboundContent,
+  PermissionDefault,
+  PermissionPolicy,
+  PermissionUnattended,
+  PersonaRef,
+  Posted,
+  Profile,
+  ProfileResidue,
+  Recurrence,
+  Repeat,
+  Residue,
+  Route,
+  RouteMatch,
+  Schedule,
+  SecretRef,
+  SurfaceKey,
+  Target,
+  Trigger,
+  WebhookSubscription,
+  Worker,
+  WorkerSpec,
+  Orchestration,
+};
+
+export type Path = string;
+export type RelPath = string;
+export type Instant = string; // RFC 3339
+export type ProfileName = string;
+export type Platform = string;
+export type UserId = string;
+export type JobId = string;
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+export type ChatType = 'dm' | 'group' | 'channel' | 'thread';
+
+export interface RuntimeState {
+  leases: Record<string, { runtime_id: string; connection: string | null; since: Instant }>;
+  queues: Record<string, { text: string; at: Instant; context_from?: string[] | null; skills?: string[]; job_id?: string }[]>;
+  turns: Record<string, { started_at: Instant; buffer: string }>;
+  starting: Record<string, unknown>;
+  /** The last worker event per lease (§4.3's inactivity limit). */
+  activity: Record<string, Instant>;
+  adapters: Record<Platform, { state: 'up' | 'down' | 'paused'; breaker: { failures: number; until?: Instant } }>;
+  pending_requests: Record<string, { profile: ProfileName; keyString: string; runtime_id: string | null; asked_at: Instant; options: RequestOption[] }>;
+  clock: Instant | null;
+  hostedJobs?: boolean;
+  hostedFires?: Record<string, boolean>;
+}
+
+export interface RequestOption { optionId?: string; name: string; kind?: string; response?: JsonValue }
+
+// ---------------------------------------------------------------- events (§3)
+
+export type WorkerEvent =
+  | { kind: 'started'; runtime_id: string; session_id?: string; connection?: string | null; harness?: HarnessId; reattach_of?: string }
+  | { kind: 'text'; delta: string }
+  /** Any other runtime event (a tool call, reasoning, a turn start): the worker is alive. */
+  | { kind: 'activity' }
+  | { kind: 'final'; text: string | null; outcome?: 'completed' | 'error'; message?: string | null }
+  | { kind: 'request'; id: string; subject: string; options: RequestOption[] }
+  | { kind: 'ended'; reason: string }
+  | { kind: 'error'; message: string };
+
+export type OrchestratorEvent =
+  | {
+      type: 'inbound'; profile: ProfileName; key: SurfaceKey; sender: UserId; sender_name: string | null;
+      text: string; attachments: Attachment[]; at: Instant; adapter: Platform; guild_id: string | null;
+      /** The platform's id for this message: the threading, reaction and edit target (ORC-1 F4). */
+      message_id: string | null;
+      /** Our own echo (§4.1 step 0 drops it), a bot sender (`null` = the SDK's "unknown"), and whether we were @-mentioned. */
+      is_me: boolean; is_bot: boolean | null; mention: boolean;
+    }
+  | { type: 'tick'; at: Instant; inactivity_s?: number | null; max_parallel?: number | null }
+  | { type: 'hosted_result'; profile: ProfileName; fire_id: string; at: Instant; receipt?: HostedReceipt; error?: string }
+  | { type: 'worker'; profile: ProfileName; keyString: string; runtime_id: string | null; ev: WorkerEvent; at: Instant }
+  | { type: 'adapter'; platform: Platform; state: 'up' | 'down'; error: string | null; at: Instant }
+  | { type: 'operator'; verb: string; profile: ProfileName; args: Record<string, unknown>; at: Instant }
+  | { type: 'webhook'; name: string; payload: JsonValue; verified: boolean; at: Instant; event: string | null; delivery_id: string | null }
+  | { type: 'restart'; at: Instant }
+  | { type: 'stopping'; at: Instant };
+
+// ---------------------------------------------------------------- effects (§5)
+
+export type Effect =
+  | { type: 'execute_job'; profile: ProfileName; job_id: string; fire_id: string }
+  | { type: 'runtime_start'; profile: ProfileName; keyString: string; worker: WorkerSpec; prompt: string | null }
+  | { type: 'runtime_close'; profile: ProfileName; keyString: string; lease: RuntimeState['leases'][string] }
+  | { type: 'send_input'; profile: ProfileName; keyString: string; text: string; context_from?: string[] | null; skills?: string[]; job_id?: string }
+  | { type: 'respond'; profile: ProfileName; keyString: string; request_id: string; response: JsonValue }
+  | { type: 'deliver'; profile: ProfileName; obligation_id: string }
+  | { type: 'write_local'; profile: ProfileName; path: RelPath; text: string }
+  | { type: 'save' }
+  | { type: 'log'; level: 'info' | 'warn' | 'error'; message: string };
+
+/** The reducer: mutates `state`, returns effects, performs no I/O. */
+export function step(state: OrchestratorState, event: OrchestratorEvent): Effect[];
+/** Hermes's session reset, as `sessionReset` reads it from the home's `session_reset:`. */
+export interface SessionReset { mode: 'none' | 'daily' | 'idle' | 'both'; at_hour: number; idle_minutes: number }
+export function sessionReset(profile: Profile): SessionReset;
+/** A platform's home channel (`platforms.<p>.home_channel`) as a chat key; with no platform, the first one; or null. */
+export function homeChannel(profile: Profile, platform?: string | null): SurfaceKey | null;
+export function expired(binding: Binding, reset: SessionReset, now: Instant): EndReason | null;
+export function leaseId(profile: ProfileName, keyString: string): string;
+
+export namespace events {
+  function inbound(fields: Omit<Extract<OrchestratorEvent, { type: 'inbound' }>, 'type' | 'attachments' | 'adapter' | 'guild_id' | 'sender_name' | 'message_id' | 'is_me' | 'is_bot' | 'mention'> & { attachments?: Attachment[]; adapter?: Platform; guild_id?: string | null; sender_name?: string | null; message_id?: string | null; is_me?: boolean; is_bot?: boolean | null; mention?: boolean }): Extract<OrchestratorEvent, { type: 'inbound' }>;
+  function tick(at: Instant, inactivity_s?: number | null, max_parallel?: number | null): Extract<OrchestratorEvent, { type: 'tick' }>;
+  function worker(fields: Omit<Extract<OrchestratorEvent, { type: 'worker' }>, 'type'>): Extract<OrchestratorEvent, { type: 'worker' }>;
+  function adapterStatus(fields: Omit<Extract<OrchestratorEvent, { type: 'adapter' }>, 'type' | 'error'> & { error?: string | null }): Extract<OrchestratorEvent, { type: 'adapter' }>;
+  function operator(fields: { verb: string; profile?: ProfileName; args?: Record<string, unknown>; at: Instant }): Extract<OrchestratorEvent, { type: 'operator' }>;
+  function restart(at: Instant): Extract<OrchestratorEvent, { type: 'restart' }>;
+  function stopping(at: Instant): Extract<OrchestratorEvent, { type: 'stopping' }>;
+  function webhook(fields: { name: string; payload?: JsonValue; verified?: boolean; at: Instant; event?: string | null; delivery_id?: string | null }): Extract<OrchestratorEvent, { type: 'webhook' }>;
+}
+
+export function parseCommand(text: string): { name: string; args: string } | null;
+export function frame(profile: ProfileName, key: SurfaceKey, sender: UserId, senderName: string | null, at: Instant, text: string): string;
+export const COMMANDS: Set<string>;
+export const REPLY: Record<string, string | ((arg: string) => string)>;
+
+export function activationEnv(o: { root: Path; profile: Profile; surfaceKey?: string | null; vault?: Vault }): Record<string, string>;
+export function activationCwd(profile: Profile, workdir?: RelPath | null): Path;
+/** Links the profile's `AGENTS.md` into the worker's config home where the harness reads a persona from any cwd (Codex; Claude Code with its `@AGENTS.md` bridge); answers that home, or null. */
+export function materializePersona(profile: Profile): Path | null;
+export const HOME_ENV: Readonly<Record<HarnessId, string>>;
+/** Links each skill the profile has into the worker's config home `skills/` (Codex, Claude Code); answers that folder, or null. */
+export function materializeSkills(profile: Profile): Path | null;
+export const HOME_SKILLS: Readonly<Record<HarnessId, string>>;
+export const HOME_PERSONA: Readonly<Record<HarnessId, Readonly<Record<string, 'link' | 'bridge'>>>>;
+export const ORCH_ENV: Readonly<{ root: string; profile: string; surface: string }>;
+
+// ---------------------------------------------------------------- the loop and adapters (§7)
+
+export interface ChannelAdapter {
+  platform: Platform;
+  connect(emit: (msg: Omit<Extract<OrchestratorEvent, { type: 'inbound' }>, 'type' | 'at' | 'attachments' | 'adapter' | 'guild_id' | 'message_id' | 'is_me' | 'is_bot' | 'mention'> & { at?: Instant; attachments?: Attachment[]; guild_id?: string | null; message_id?: string | null; is_me?: boolean; is_bot?: boolean | null; mention?: boolean }) => unknown): Promise<{ state: 'up' | 'down'; error?: string } | void>;
+  /** A returned `message_id` is recorded on the obligation as `posted` (§2.6). */
+  send(target: SurfaceKey, content: { text: string; at?: Instant } & Partial<OutboundContent>): Promise<{ ok?: boolean; message_id?: string } | unknown>;
+  close?(): Promise<void>;
+}
+
+export class LoopbackAdapter implements ChannelAdapter {
+  constructor(o?: { platform?: Platform; profile?: ProfileName; failSends?: number });
+  platform: Platform;
+  profile: ProfileName;
+  outbox: { target: SurfaceKey; text: string; at: Instant | null }[];
+  failSends: number;
+  connect(emit: Parameters<ChannelAdapter['connect']>[0]): Promise<{ state: 'up' }>;
+  inject(m: { kind?: ChatType; chat_id?: string; thread_id?: string; sender?: UserId; sender_name?: string | null; text: string; at?: Instant; guild_id?: string | null }): unknown;
+  send(target: SurfaceKey, content: { text: string; at?: Instant }): Promise<{ ok: true }>;
+  close(): Promise<void>;
+}
+
+/**
+ * ORC-9: a sidecar over `chat@4.39.0` (`vercel/chat`), one instance per
+ * (platform, account). The platform packages (`@chat-adapter/*`) are imported
+ * lazily at `connect`; a missing one is `{ state: 'down' }`, not a throw.
+ */
+export class ChatSdkAdapter implements ChannelAdapter {
+  constructor(o: {
+    platform: Platform; profile?: ProfileName; channel?: ChannelConfig | null; vault?: Vault;
+    sdkAdapter?: unknown; chat?: unknown; state?: unknown; log?: (level: string, message: string) => void;
+  });
+  platform: Platform;
+  profile: ProfileName;
+  /** thread_id -> the live SDK `Thread` this sidecar last answered on. */
+  readonly threads: Map<string, unknown>;
+  readonly chat: unknown;
+  connect(emit: Parameters<ChannelAdapter['connect']>[0]): Promise<{ state: 'up' | 'down'; error?: string }>;
+  /** The one door from the SDK into the loop: `(thread, message)` -> an `inbound`. */
+  handle(thread: unknown, message: unknown): unknown;
+  send(target: SurfaceKey, content: { text: string; at?: Instant; reply_to?: string }): Promise<{ ok: true; message_id?: string }>;
+  close(): Promise<void>;
+}
+
+export const CHAT_SDK_VERSION: string;
+export const CHAT_SDK_PACKAGE: string;
+export const CHAT_SDK_STATE_PACKAGE: string;
+/** §2.3's four-value `kind` from the Chat SDK's `isDM` / `channelVisibility` split. */
+export function chatType(thread: { isDM?: boolean; channelVisibility?: string }): ChatType;
+export function toAttachment(a: Record<string, unknown>): Attachment;
+export function toInbound(o: { profile: ProfileName; thread: unknown; message: unknown }): Parameters<Parameters<ChannelAdapter['connect']>[0]>[0];
+
+/**
+ * ORC-9: Hermes's `api_server` client API, served by this loop on its own
+ * listener at `platforms.api_server.extra.host|port`. Every route it makes the
+ * loop act on enters as an `inbound` (§3).
+ */
+export class ApiServerAdapter implements ChannelAdapter {
+  constructor(o: {
+    platform?: Platform; profile?: ProfileName; channel?: ChannelConfig | null; vault?: Vault;
+    state: OrchestratorState; clock?: () => Instant; log?: (level: string, message: string) => void;
+  });
+  platform: Platform;
+  profile: ProfileName;
+  /** The bound port; `extra.port: 0` lets the OS choose and tests read it here. */
+  readonly port: number | null;
+  readonly sessions: Map<string, unknown>;
+  readonly runs: Map<string, { run_id: string; status: string; output: string | null }>;
+  connect(emit: Parameters<ChannelAdapter['connect']>[0]): Promise<{ state: 'up' }>;
+  send(target: SurfaceKey, content: { text: string; at?: Instant }): Promise<{ ok: true; message_id: string }>;
+  close(): Promise<void>;
+}
+
+export const API_SERVER_HOST: string;
+export const API_SERVER_PORT: number;
+
+export class Orchestrator {
+  constructor(o: {
+    state: OrchestratorState;
+    vault?: Vault;
+    client: unknown; // SupercodeHarnessClient from @volter/supercode-harness-sdk
+    adapters?: Record<Platform, ChannelAdapter>;
+    clock?: () => Instant;
+    executeJob?: ((task: HostedTask) => Promise<HostedReceipt>) | null;
+    launchFor?: (profile: Profile, worker: WorkerSpec, env: Record<string, string>) => { program: string; arguments: string[]; env: Record<string, string> } | undefined;
+    log?: (level: string, message: string) => void;
+  });
+  readonly state: OrchestratorState;
+  readonly vault: Vault;
+  readonly queue: Promise<unknown>;
+  readonly effectLog: Effect[];
+  readonly webhookPort: number | null;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  tick(at?: Instant): Promise<Effect[]>;
+  drainHosted(): Promise<void>;
+  dispatch(event: OrchestratorEvent): Promise<Effect[]>;
+  enqueue(event: OrchestratorEvent): void;
+  /** §7: effects produced by an MCP tool call, run on the loop's own queue. */
+  /** §7: the model-facing MCP door's loop side, open between start and stop. */
+  readonly bridge: { path: Path; close(): Promise<void> } | null;
+}
+
+export function normalizeWorkerEvent(ev: unknown): WorkerEvent | null;
+
+// ---------------------------------------------------------------- cron and webhooks (ORC-5, §4.3/§4.4)
+
+export interface CronFields { minute: Set<number>; hour: Set<number>; dom: Set<number>; month: Set<number>; dow: Set<number>; domRestricted: boolean; dowRestricted: boolean }
+
+/** The next run strictly after `after`, or null when the schedule is spent. */
+export function nextRunAt(schedule: Schedule, after: Instant): Instant | null;
+export function parseCron(expr: string): CronFields;
+/** Why a schedule cannot be evaluated (bad instant, interval, expression or zone), or null. */
+export function scheduleError(schedule: Schedule): string | null;
+export function dueJobs(profile: Profile, now: Instant): Job[];
+export function claimFire(profile: Profile, job: Job, now: Instant): Fire | null;
+export function finishFire(profile: Profile, fire: Fire, job: Job | null, status: FireStatus, now: Instant, error?: string | null, effects?: Effect[] | null): Fire;
+/** Re-arm after a run; a schedule that cannot be evaluated disables the job and returns why. */
+export function advanceSchedule(job: Job, now: Instant): string | null;
+export function resolveTarget(job: Job | null, profile: Profile, target?: Target | null): SurfaceKey | { kind: 'local' };
+export function cronTick(state: OrchestratorState, ev: Extract<OrchestratorEvent, { type: 'tick' }>, effects: Effect[]): void;
+export function fireFinal(state: OrchestratorState, profile: Profile, binding: Binding, text: string, now: Instant, effects: Effect[]): boolean;
+export function fireFailed(state: OrchestratorState, profile: Profile, binding: Binding, message: string, now: Instant, effects: Effect[]): boolean;
+export function fireSessionName(jobId: JobId, at: Instant): string;
+export function fireSessionId(fire: Fire): string | null;
+export function compactStamp(at: Instant): string;
+export const BACKOFF_MINUTES: readonly number[];
+export const BREAKER_FAILURES: number;
+export const BREAKER_MINUTES: number;
+export const MAX_ATTEMPTS: number;
+export const TICK_MS: number;
+
+export function handleWebhook(state: OrchestratorState, ev: Extract<OrchestratorEvent, { type: 'webhook' }>, effects: Effect[]): void;
+export function renderTemplate(template: string, payload: unknown): string;
+export function signBody(secret: string, body: string): Promise<string>;
+export function verifySignature(secret: string | null, body: string, header: string | null): Promise<boolean>;
+export function subscriptionSecret(sub: WebhookSubscription | null, vault?: Vault): string | null;
+export function findSubscription(state: OrchestratorState, name: string): { profile: Profile; sub: WebhookSubscription } | null;
+export function webhookKey(name: string): SurfaceKey;
+export function startWebhookListener(o: { state: OrchestratorState; vault?: Vault; port?: number; host?: string; dispatch: (event: OrchestratorEvent) => unknown; clock: () => Instant; log?: (level: string, message: string) => void }): Promise<{ server: unknown; port: number; close(): Promise<void> }>;
+/** `gateway.webhook_port` from config residue; 0 when unset. */
+export function webhookPort(state: OrchestratorState): number;
+
+// ---------------------------------------------------------------- §7: the model-facing MCP door
+
+/** One published tool: `name`, `description`, and its JSON Schema. */
+export interface OrchestratorTool { name: string; description: string; inputSchema: Record<string, unknown> }
+export const TOOLS: readonly OrchestratorTool[];
+export const TOOL_NAMES: readonly string[];
+export const SERVER_NAME: string;
+export const PROTOCOL_VERSION: string;
+export const SOCKET_ENV: string;
+export const SERVER_PATH: Path;
+
+/** The door a harness publishes for an MCP server. */
+export type McpDoor = 'flag' | 'toml' | 'json' | 'none' | 'acp';
+export const MCP_DOORS: Readonly<Record<string, McpDoor>>;
+export function doorFor(harness: string): McpDoor;
+
+/** One stdio MCP server, in the uniform shape `harness.v1.runtimes.start` carries. */
+export interface McpServerLaunch { name: string; command: string; arguments: string[]; env: Record<string, string> }
+
+export function mountOrchestratorMcp(o: {
+  root: Path; profile: Profile; harness: string; surfaceKey?: string | null;
+  launch?: { program: string; arguments?: string[]; env?: Record<string, string> };
+  socketPath?: Path; serverPath?: Path; program?: string;
+}): { door: McpDoor; ran: string; launch: unknown; mcp_servers: McpServerLaunch[] | null; path: Path | null };
+
+export function socketPathFor(root: Path): Path;
+export function startBridge(o: { orch: Orchestrator; socketPath: Path; log?: (level: string, message: string) => void }): Promise<{ path: Path; close(): Promise<void> }>;
+export function runVerb(orch: Orchestrator, call: { verb: string; args?: Record<string, unknown>; profile: ProfileName; surface?: string | null }): Promise<{ result?: Record<string, unknown>; effects?: Effect[]; error?: string }>;
+export function parseSchedule(spec: unknown, now: Instant): Schedule;
+export function routedProfile(state: OrchestratorState, key: SurfaceKey): ProfileName | null;
+export function keyFromString(text: string | null): SurfaceKey | null;
+
+/** The binding a spawned MCP server reads out of its environment. */
+export function bindingFromEnv(env?: Record<string, string | undefined>): { root: Path; profile: ProfileName; surface: string | null; socket: Path };
+export function handleRequest(binding: { root: Path; profile: ProfileName; surface: string | null; socket: Path }, request: unknown): Promise<unknown>;
+export function serveStdio(binding: { root: Path; profile: ProfileName; surface: string | null; socket: Path }, input?: unknown, output?: unknown): unknown;
+
+export interface OrchestratorState {
+  root: Path;
+  profiles: Record<ProfileName, Profile>;
+  runtime: RuntimeState;
+}
+
+export type Vault = Map<string, string>;
+
+export class LoadError extends Error { file: string; key: string | null }
+
+/** What `orchestration.decompile` / `orchestration.export` did (the SDK's `OrchestrationDecompiled`). */
+export interface OrchestrationDecompiled {
+  written: ArtifactFidelity[];
+  refused: { file: RelPath; reason: string }[];
+  notes?: string[];
+  rows_byte?: number;
+  rows_emitted?: number;
+}
+/** What `orchestration.import` did: the orchestration as written, the vault's key names, and what was carried by path. */
+export interface OrchestrationImported {
+  orchestration: Omit<OrchestratorState, 'runtime'>;
+  vault_keys: string[];
+  root: Path;
+  carried: RelPath[];
+}
+
+/** Our folder, strict, through `harness.v1.orchestration.load`; the vault is read out of the home's own `.env`. */
+export function load(root: Path): Promise<{ state: OrchestratorState; vault: Vault }>;
+/** Our folder, canonical and byte-stable, through `harness.v1.orchestration.save`. Sends no secret. */
+export function save(state: OrchestratorState, root?: Path): Promise<void>;
+/** Another harness's home as a state value; `vault_keys` names the `.env` keys it would need. */
+export function compile(from: 'hermes' | 'openclaw', home: Path): Promise<{ state: OrchestratorState; vault_keys: string[] }>;
+/** Another harness's home becomes our folder, credentials along (`harness.v1.orchestration.import`). */
+export function importFrom(from: 'hermes' | 'openclaw', home: Path, into: Path): Promise<OrchestrationImported>;
+/** Our folder becomes another harness's home, credentials along (`harness.v1.orchestration.export`). */
+export function exportTo(to: 'hermes' | 'openclaw', root: Path, dest: Path): Promise<OrchestrationDecompiled>;
+/** An orchestration value as the loop's state: the persisted half plus an empty runtime half. */
+export function stateOf(orchestration: Omit<OrchestratorState, 'runtime'>): OrchestratorState;
+/** Hold the door open (a running loop does); balanced by `releaseWorld`, after which it closes itself when idle. */
+export function retainWorld(): void;
+export function releaseWorld(): void;
+/** Close the shared door to `supercode harness serve` now; the next verb opens it again. */
+export function closeWorld(): Promise<void>;
+/** The binary the doors are opened with: `SUPERCODE_BIN`, else this checkout's build, else PATH. */
+export function supercodeCommand(): string;
+
+export function renderSurfaceKey(profile: ProfileName, key: SurfaceKey): string;
+export function parseSurfaceKey(text: string): { profile: ProfileName; key: SurfaceKey } | null;
+export function surfaceKeyString(key: SurfaceKey): string;
+/** `context_from` as Hermes stores it: a list of job ids (or `self`), or null. */
+export function decodeContextFrom(file: string, key: string, value: unknown): string[] | null;
+export function parseTarget(file: string, key: string, word: string | null, extra?: { chat_id?: string; thread_id?: string }): Target | null;
+export function renderTarget(t: Target | null): string | null;
+export function resolveRoute(routes: Route[], key: SurfaceKey, guildId?: string): ProfileName | null;
+export function routeSpecificity(r: Route): number;
+export function emptyState(root: Path): OrchestratorState;
+export function emptyProfile(name: ProfileName, dir: Path): Profile;
+export function emptyRuntime(): RuntimeState;
+export function canonicalJson(value: unknown): string;
+export function persistedView(state: OrchestratorState): Omit<OrchestratorState, 'runtime'>;
+export function parseDotenv(text: string): Map<string, string>;
+
+export const CHAT_TYPES: Set<ChatType>;
+export const END_REASONS: Set<EndReason>;
+export const FIRE_STATUSES: Set<FireStatus>;
+export const OBLIGATION_STATES: Set<ObligationState>;
+
+/** Host receipts confirm dispatch, not the eventual model answer. */
+export interface HostedTask { profile: string; job: Job; fire: Fire }
+export interface HostedReceipt { accepted: true; output: string; profile?: string; fire_id?: string; delivery?: { platform: string; chat_id: string; id: string } }
+export function callOperator(options: { root: string; profile?: string; op: string; args?: Record<string, unknown>; timeoutMs?: number }): Promise<unknown>;
+export function httpJobExecutor(options: { url: string; tokenFile: string; root: string; timeoutMs?: number }): (task: HostedTask) => Promise<HostedReceipt>;
+/** Stop only a hosted daemon owned by this root; wait for native shutdown. */
+export function stopHostedDaemon(options: { root: string; executorUrl?: string; timeoutMs?: number }): Promise<{ stopped: boolean; wasRunning: boolean }>;
+
+// ---------------------------------------------------------------- the agent-setup applier (apply/, plan §7)
+
+/** One agent-setup package: declared records for one home (docs/plans/content-spec-status.md §6). */
+export interface SetupPackage {
+  schema_version: 1;
+  parameters?: Record<string, { default?: string | number | boolean }>;
+  inference?: {
+    models?: Record<string, { provider?: string; model: string; endpoint?: string; base_url?: string; credential?: string; placeholder_key?: string; api_mode?: string }>;
+    default?: string; unattended?: string; delegation?: string; fallbacks?: string[];
+  };
+  jobs?: Record<string, Record<string, unknown>>;
+  extensions?: { hermes?: { config?: Record<string, unknown> } };
+  moved?: Array<{ from: string; to: string }>;
+  removed?: Array<{ key: string; then: 'forget' | 'pause' | 'delete' }>;
+}
+export interface SetupRow { key: string; action: string; id?: string; detail?: string }
+export interface SetupPlan { homeId: string; planOnly: boolean; rows: SetupRow[]; hash: string }
+export interface SetupDoor { target: 'hermes' | 'orchestrator' }
+export function planSetup(o: { door: SetupDoor; homeId: string; spec: SetupPackage; root?: string; params?: Record<string, string> }): Promise<SetupPlan>;
+export function applySetup(o: { door: SetupDoor; homeId: string; spec: SetupPackage; root?: string; params?: Record<string, string>; planHash?: string | null; reviewedPlan?: boolean }): Promise<SetupPlan & { applied: SetupRow[] }>;
+export function adoptSetup(o: { door: SetupDoor; homeId: string; keys: string[]; root?: string }): Promise<SetupRow[]>;
+export function resolveSetup(o: { door: SetupDoor; homeId: string; keys: string[]; root?: string }): Promise<SetupRow[]>;
+export function provisionHome(o: { homeId: string; root?: string }): unknown;
+export function validateSetup(spec: SetupPackage): SetupPackage;
+export function resolveParameters(spec: SetupPackage, values?: Record<string, string>): SetupPackage;
+export function hermesConfig(spec: SetupPackage): Record<string, unknown>;
+export const SETUP_SCHEMA_VERSION: 1;
+export function hermesDoor(o: { home: string; python?: string | null; source?: string | null; runner?: unknown; prefix?: string[] }): SetupDoor;
+export function orchestratorDoor(o: { root: string; profile?: string; load: unknown; socket?: string | null }): Promise<SetupDoor>;
+export function locateHermes(o?: { python?: string | null; source?: string | null }): { python: string; source: string };
+export function localRunner(o: { python: string; source: string; prefix?: string[] }): unknown;
+export function containerRunner(o: { container: string; user?: string; python?: string; source?: string; docker?: string }): unknown;
+
+/** The daemon's lease, `<home>/orchestrator.lock`. */
+export interface OrchestratorLease {
+  pid: number;
+  started_at: string;
+  root: string;
+  /** The machine that wrote it, and that machine's boot (Linux's boot id). */
+  host?: string | null;
+  boot?: string | null;
+  executor_url?: string | null;
+}
+export const LOCK_FILE: 'orchestrator.lock';
+/** This machine's name and, on Linux, its boot id. */
+export function thisHost(): { host: string | null; boot: string | null };
+export function pidIsLive(pid: number): boolean;
+/** Whether a lease is this machine's, since this boot: only then may its pid be signalled. */
+export function leaseIsHere(lease: Pick<OrchestratorLease, 'host' | 'boot'> | null | undefined): boolean;
+/** Whether the daemon a lease names is alive now: here, and its pid live. */
+export function leaseIsLive(lease: OrchestratorLease | null | undefined): boolean;
+export function readLease(root: string): OrchestratorLease | null;

package/index.mjs

@@ -0,0 +1,38 @@
+export {
+  LoadError, sessionReset, homeChannel, CHAT_TYPES, END_REASONS, FIRE_STATUSES, OBLIGATION_STATES,
+  renderSurfaceKey, parseSurfaceKey, surfaceKeyString, parseTarget, renderTarget, resolveRoute, routeSpecificity,
+  emptyState, emptyProfile, emptyRuntime, canonicalJson, persistedView, decodeContextFrom,
+} from './ir.mjs';
+export { load, save, compile, importFrom, exportTo, closeWorld, retainWorld, releaseWorld, stateOf, parseDotenv, supercodeCommand } from './orchestration.mjs';
+export { step, expired, leaseId, accessPolicy, dmBehavior } from './reducer.mjs';
+export * as events from './events.mjs';
+export { parseCommand, frame, COMMANDS, REPLY } from './commands.mjs';
+export { activationEnv, activationCwd, materializePersona, materializeSkills, HOME_ENV, HOME_PERSONA, HOME_SKILLS, ORCH_ENV } from './activation.mjs';
+export { Orchestrator, normalizeWorkerEvent, webhookPort, TICK_MS } from './loop.mjs';
+export {
+  cronTick, dueJobs, nextRunAt, parseCron, scheduleError, claimFire, finishFire, advanceSchedule, resolveTarget,
+  fireFinal, fireFailed, fireSessionName, fireSessionId, compactStamp,
+  BACKOFF_MINUTES, BREAKER_FAILURES, BREAKER_MINUTES, MAX_ATTEMPTS,
+} from './cron.mjs';
+export {
+  handleWebhook, renderTemplate, verifySignature, signBody, subscriptionSecret,
+  findSubscription, webhookKey, startWebhookListener,
+} from './webhook.mjs';
+export { LoopbackAdapter } from './adapters/loopback.mjs';
+export { ChatSdkAdapter, toInbound, toAttachment, chatType, CHAT_SDK_VERSION, CHAT_SDK_PACKAGE, CHAT_SDK_STATE_PACKAGE } from './adapters/chat-sdk.mjs';
+export { ApiServerAdapter, DEFAULT_HOST as API_SERVER_HOST, DEFAULT_PORT as API_SERVER_PORT } from './adapters/api-server.mjs';
+export { Rh2Adapter } from './adapters/rh2.mjs';
+export { TOOLS, TOOL_NAMES, SERVER_NAME, PROTOCOL_VERSION } from './mcp/tools.mjs';
+export { mountOrchestratorMcp, doorFor, MCP_DOORS, SERVER_PATH } from './mcp/mount.mjs';
+export { startBridge } from './mcp/bridge.mjs';
+export { socketPathFor, bindingFromEnv, handleRequest, serveStdio, SOCKET_ENV } from './mcp/server.mjs';
+export { runVerb, parseSchedule, routedProfile, keyFromString } from './mcp/verbs.mjs';
+export { applyOperator, buildJob, performRemoveProfileDir, OPERATOR_OPS, TRASH_DIR } from './operator.mjs';
+
+export { callOperator, httpJobExecutor, stopHostedDaemon } from './hosted.mjs';
+export { plan as planSetup, apply as applySetup, adopt as adoptSetup, resolve as resolveSetup, provision as provisionHome, validate as validateSetup, resolveParameters, hermesConfig, SCHEMA_VERSION as SETUP_SCHEMA_VERSION } from './apply/index.mjs';
+export { hermesDoor, orchestratorDoor, locateHermes, localRunner, containerRunner } from './apply/doors.mjs';
+export { LOCK_FILE, thisHost, pidIsLive, leaseIsHere, leaseIsLive, readLease } from './lease.mjs';
+export { adoptHome, adoptPersona, adoptSkills, managedSkills, skillSources, profileDirs, AGENTS_SKILLS } from './hermes-home.mjs';
+export { hermesAccess, recordIncident, hermesToolEnv, hermesInstall } from './hermes-cli.mjs';
+export { holdGatewayLock, gatewayLockHeld, acquireTokenLock, releaseTokenLock, looksLikeGateway, TOKEN_SCOPES } from './hermes-locks.mjs';