Module orchestration

Expand description

The orchestration piece of the ontology: a harness’s operational home as one typed value. The orchestration piece of the ontology (docs/ONTOLOGY.md §2.7, docs/ORCHESTRATOR-IR.md §2): a harness’s operational home as ONE typed value. These are the records the orchestrator loads, steps and saves; a Hermes or OpenClaw home compiles into them and decompiles back (the codecs are ONT-3’s). The wire form is the orchestrator IR’s canonical JSON: the runtime half is never persisted and is not here.

Modules§

access: Allowlists, admins and policy, read from Hermes’s own stores (docs/plans/hermes-compat.md row 8): the home’s .env allowlists and allow-all flags, the approved pairings under platforms/pairing/, and each platform’s allow_admin_from. Pairing codes are Hermes’s: its pairing store issues and approves them.
agent: The agent layer (mirrored ontology C8, docs/architecture/orchestrator.md §2.10): declared agents, conversations separate from sessions (G5, as amended by M3), transfers and handoffs (G2), usage and budgets (G3). Bindings name their conversation and agent (G1); routes name an agent. Agent identity itself (ids, sponsor, lineage) lives with Teams and the orchestrator’s agent store; these records are the home’s intent and its conversations’ record.
channel: A channel: one platform block of config.yaml (§2.4). Credential values never enter the model; they are references.
codec: The orchestration codecs (docs/ONTOLOGY.md §2.5, §3): a home folder ⇄ [Orchestration].
fire: Fires: one execution of a job (§2.6; Hermes cron/executions.db).
job: Scheduled jobs (§2.6; Hermes cron/jobs.json).
obligation: Delivery obligations (§2.6; Hermes delivery_obligations).
profile: The home and its profiles (§2.1): the root folder IS the default profile; profiles/<name>/ are the named ones.
route: Routes: which profile answers a surface (§2.3, Hermes gateway.profile_routes).
subscription: Webhook subscriptions (§2.6; Hermes webhook_subscriptions.json).
worker: The worker: which harness runs a profile’s conversations, and how (§2.2).
workflow: How a board is worked (docs/architecture/orchestrator.md §2.9): the whole dispatch behaviour as data, a statechart in the manner of Amazon States Language and XState. A card is always in one of the workflow’s statuses; a status may run an actor for as long as the card is in it (XState’s invoke, ASL’s Task); events move cards between statuses through transitions that say who may send them, what must hold, and what happens (Jira’s conditions, validators and post functions); the dispatcher’s scheduling is data too.

Structs§

Access: The access record, as Hermes’s stores hold it.
AgentDecl: One agent this home declares: who answers, and which profile is its template. A named profile implies its own agent of the same name; a declaration names others (several agents may share one profile) and the parent each is declared under.
Attachment: Something attached to an outbound message.
Budget: A per-action gate on a profile’s agents: a start or resume over it is refused, with the reason, and the refusal is told to the manager and the sponsor. It never pauses or ends anything itself.
BudgetLimit: What a budget bounds.
ChannelConfig: One platform’s configuration.
Conversation: A conversation, a Resource separate from the sessions bound to it (G5, amended by M3).
Cost: A cost, as the provider reported it or a rate table priced it.
Fire: One fire.
Job: One scheduled job.
JobOrigin: The conversation a job was created from (Hermes origin).
Obligation: One delivery obligation.
Orchestration: The whole home: the persisted half of OrchestratorState (§2.1); the runtime half is never written and is not part of the wire.
OutboundContent: What is delivered.
Participant: A person or an agent in a conversation.
PermissionPolicy: How prompts are answered when no human is reachable (§4.6).
PersonaRef: The persona: AGENTS.md at the profile root, content hash first.
Posted: The platform’s handle for what was sent.
Profile: One profile: a folder with AGENTS.md at its root.
ProfileResidue: What a profile carries that the model does not interpret.
Repeat: Hermes 0.21.0’s repeat: {times: N | null, completed: M}; null times = forever.
Route: One route.
RouteMatch: What a route matches; most specific wins.
SessionUsage: A session’s usage, kept on the session and summed upward (session → agent → sponsor → Org).
Transfer: One agent handing a conversation to another (OpenAI handoff, AutoGen Swarm, voice hand_off).
Usage: One measured use of a model, from the harness’s own records (G3).
WebhookSubscription: One subscription: the route is /webhooks/<name>.
WorkerSpec: The worker specification (O-record; Hermes has no worker choice).
Workflow: A board’s workflow.

Enums§

AccessPolicy: Per-platform policy.
BudgetPeriod: A budget’s window.
ConversationKind: thread: a root and its replies, wherever it is shown; private: a harness session’s own input.
EnvValue: A worker environment value: a literal, or a secret by reference.
FireStatus: A fire’s status. unknown is Hermes’s own word for a fire whose scheduler restarted under it; completed ⇄ succeeded on the codec boundary and timeout writes back as failed.
HandoffState: A handoff’s progress.
HistoryRef: Where a conversation’s record lives.
ObligationSource: Where an obligation came from.
ObligationState: Delivery state; sent is Hermes’s delivered.
ParticipantRole: How a participant is addressed on a thread (amendment M3).
PermissionDefault: What happens to a worker’s permission prompt when no human answers.
PermissionUnattended: What a prompt raised where nobody attends (a cron fire, a webhook turn) is answered with, at once (Hermes approvals.cron_mode).
Schedule: When a job fires.
SpeakerPolicy: Which bound agents receive a line on a shared surface (G1).
Target: Where a result goes.
TransferHistory: How much of the conversation a transfer’s receiver is given.
TransferState: A transfer’s progress.
WorkerHome: Whose Claude home (or harness home) a worker runs in.
WorkerSurface: How a board task’s session runs when the board dispatches it to this profile.

Constants§

RECORDS: Every name schema_for answers.

Functions§

hermes_instance: Hermes’s dispatcher, transcribed as data (hermes_cli/kanban_db.py): the workflow a home runs when it declares none.
resolve_route: The agent a surface routes to, or None for the adapter’s own profile’s agent. Ties are broken by declaration order, as Hermes does.
route_specificity: Most-specific-first: thread > chat > guild > platform.
schema: The JSON Schema of the whole orchestration value, with every record it contains as a definition — what supercode ontology schema prints and what the TypeScript types are generated from (ONT-6).
schema_for: The schema of one record by name, for readers who want a single type.