@volter/supercode-orchestrator 0.4.4

package/ontology.d.ts

@@ -0,0 +1,557 @@
+// GENERATED from `supercode ontology schema` — do not edit; run node sdk/orchestrator/scripts/generate-types.mjs
+//
+// The Rust records in `crates/interchange/src/world/` and
+// `crates/interchange/src/ontology/` are the source of truth (`docs/ONTOLOGY.md` §2).
+
+/** The access record, as Hermes's stores hold it. */
+export interface Access {
+  /** Allowed senders per platform. */
+  allowlist?: Record<string, string[]>;
+  /** Admins per platform. */
+  admins?: Record<string, string[]>;
+  /** Policy per platform; `allowlist` when absent. */
+  policy?: Record<string, AccessPolicy>;
+}
+
+/** Per-platform policy. */
+export type AccessPolicy =
+  /** Only allowlisted (or paired) senders. */
+  | 'allowlist'
+  /** Anyone. */
+  | 'open';
+
+/** What one artifact reached on the way in or out. */
+export interface ArtifactFidelity {
+  /** Path relative to the home the codec read or wrote. */
+  path: string;
+  /** The tier reached. */
+  fidelity: Fidelity;
+  /** Named loss; non-empty only when `fidelity` tolerates residue. */
+  loss?: string[];
+}
+
+/** Something attached to an outbound message. */
+export interface Attachment {
+  /** `image` | `file` | `video` | `audio`. */
+  kind: string;
+  /** File name. */
+  name?: string | null;
+  /** MIME type. */
+  mime?: string | null;
+  /** Size in bytes. */
+  size?: number | null;
+  /** A URL to fetch it from. */
+  url?: string | null;
+  /** A local path. */
+  path?: string | null;
+  /** Adapter data to re-fetch it. */
+  ref?: unknown;
+}
+
+/** The conversation record. */
+export interface Binding {
+  /** The surface; degenerate (all `None`) on a terminal. */
+  key: SurfaceKey;
+  /** The profile that owns it (`None` = the home's default). */
+  profile?: string | null;
+  /** The worker session. */
+  worker: Worker;
+  /**
+   * Why the conversation exists. The orchestrator's own store keeps no
+   * trigger column (it is derived from the key and recurrence), so the
+   * wire may omit it.
+   */
+  trigger?: Trigger;
+  /** The job this conversation is a fire of. */
+  recurrence?: Recurrence | null;
+  /** Moved (or moving) to another surface. */
+  handoff?: Handoff | null;
+  /** RFC3339 instants where the source has them. */
+  started_at?: string | null;
+  /** Last activity, RFC3339. */
+  last_activity_at?: string | null;
+  /** End, RFC3339, when ended. */
+  ended_at?: string | null;
+  /** Why it ended. */
+  end_reason?: EndReason | null;
+  /** Source fields the record does not model, verbatim. */
+  residue?: Residue;
+}
+
+/** One platform's configuration. */
+export interface ChannelConfig {
+  /** The platform name (`telegram`, `slack`, `api_server`, …). */
+  platform: string;
+  /** Whether the adapter is enabled. */
+  enabled?: boolean;
+  /** Credential keys by reference; presence is checked at load, values never held. */
+  credentials?: Record<string, SecretRef>;
+  /** Adapter-specific settings, verbatim (`extra.<key>` for the nested block). */
+  extra?: Record<string, unknown>;
+}
+
+/** Why a binding ended (`docs/ORCHESTRATOR-IR.md` §2.5). */
+export type EndReason =
+  /** Idle expiry. */
+  | 'idle'
+  /** The daily reset boundary. */
+  | 'daily'
+  /** `/reset` (or the operator verb). */
+  | 'reset'
+  /** `/new` (or the operator verb). */
+  | 'new'
+  /** Moved to another surface. */
+  | 'handoff'
+  /** The worker failed. */
+  | 'error';
+
+/** A worker environment value: a literal, or a secret by reference. */
+export type EnvValue =
+  /** A plain, non-secret value. */
+  | string
+  /** A secret, named and never held. */
+  | SecretRef;
+
+/**
+ * How faithfully a reconstruction reproduces its source.
+ *
+ * One vocabulary for every surface that has to state what it gave up. It was
+ * introduced for session ARTIFACTS (`harness.v1.sessions.export` reports a
+ * level plus a named residue list); session LOADS report the same pair,
+ * because a read-only VIEW of a session is allowed to settle for
+ * [`Fidelity::Semantic`] where a continuation is not (see
+ * a session loader's explicitly semantic/read-only mode).
+ */
+export type Fidelity =
+  /** The reconstruction reproduces the source bytes exactly. */
+  | 'byte_lossless'
+  /** Every value survives; only the container bytes were re-synthesized. */
+  | 'value_lossless'
+  /** Meaning survives; the named residue says exactly what did not. */
+  | 'semantic';
+
+/** One fire. */
+export interface Fire {
+  /** The fire id, which is also its session name `cron_<job_id>_<ts>`. */
+  id: string;
+  /** The job. */
+  job_id: string;
+  /** The session it opened, when known. */
+  session_id?: string | null;
+  /** Status. */
+  status: FireStatus;
+  /** Claim instant. */
+  claimed_at: string;
+  /** Start instant. */
+  started_at?: string | null;
+  /** Finish instant. */
+  finished_at?: string | null;
+  /** The error, on failure. */
+  error?: string | null;
+  /** The delivery this fire produced, if any. */
+  obligation_id?: string | null;
+  /** Ledger columns the record does not model (`source`, `pid`, …), verbatim. */
+  residue?: Residue;
+}
+
+/**
+ * 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`.
+ */
+export type FireStatus =
+  /** Claimed, not yet started. */
+  | 'claimed'
+  /** Running (read from Hermes; never written by us). */
+  | 'running'
+  /** Finished with a result. */
+  | 'succeeded'
+  /** Finished with an error. */
+  | 'failed'
+  /** The session ended without a result. */
+  | 'timeout'
+  /** The scheduler restarted under it. */
+  | 'unknown';
+
+/** A conversation moved (or moving) to another surface — Hermes `handoff_*`. */
+export interface Handoff {
+  /** The destination platform. */
+  to?: string | null;
+  /** `pending` | `done` | `failed` (the source's own word, verbatim). */
+  state: string;
+  /** The failure, when `state` is `failed`. */
+  error?: string | null;
+}
+
+/** Extensible identifier for a coding harness. */
+export type HarnessId = string;
+
+/** One scheduled job. */
+export interface Job {
+  /** The id (a file-name-safe token). */
+  id: string;
+  /** When it fires. */
+  schedule: Schedule;
+  /** The prompt. */
+  prompt?: string | null;
+  /** Working directory: relative to the profile dir, or absolute. */
+  workdir?: string | null;
+  /** Model override. */
+  model?: string | null;
+  /** Skills to load. */
+  skills?: string[];
+  /** Job ids (or `self`) whose newest output is prepended at fire time. */
+  context_from?: string[] | null;
+  /** Where the result goes. */
+  deliver: Target;
+  /** Where a failure goes; `deliver` with a prefix when absent. */
+  failure_deliver?: Target | null;
+  /** The creating conversation. */
+  origin?: JobOrigin | null;
+  /** Hermes: mirror the fire's output into the target conversation's transcript. */
+  attach_to_session?: boolean | null;
+  /** Remaining-runs counter for `once` jobs. */
+  repeat?: Repeat | null;
+  /** Whether it fires at all. */
+  enabled?: boolean;
+  /** Next fire, RFC3339. */
+  next_run_at?: string | null;
+  /** Last fire, RFC3339. */
+  last_run_at?: string | null;
+  /** Last fire's status word. */
+  last_status?: string | null;
+  /** Creation, RFC3339. */
+  created_at?: string | null;
+  /** Source fields the record does not model, verbatim. */
+  residue?: Residue;
+}
+
+/** The conversation a job was created from (Hermes `origin`). */
+export interface JobOrigin {
+  /** The platform. */
+  platform: string;
+  /** The chat type, when known. */
+  chat_type?: string | null;
+  /** The chat. */
+  chat_id?: string | null;
+  /** The thread. */
+  thread_id?: string | null;
+}
+
+/** One delivery obligation. */
+export interface Obligation {
+  /** The id. */
+  id: string;
+  /** The surface it goes to. */
+  target: SurfaceKey;
+  /** Hermes's `session_key` column, verbatim. */
+  session_key?: string | null;
+  /** What is delivered. */
+  content: OutboundContent;
+  /** State. */
+  state: ObligationState;
+  /** Attempts so far. */
+  attempts?: number;
+  /** The last failure. */
+  last_error?: string | null;
+  /** Creation instant (Hermes: epoch seconds as text). */
+  created_at: string;
+  /** Last transition instant. */
+  updated_at: string;
+  /** When it was sent. */
+  delivered_at?: string | null;
+  /** The platform's handle for what was sent. */
+  posted?: Posted | null;
+  /** Where it came from. */
+  source: ObligationSource;
+  /** Ledger columns the record does not model, verbatim. */
+  residue?: Residue;
+}
+
+/** Where an obligation came from. */
+export type ObligationSource =
+  /** A conversation's turn. */
+  | { key?: SurfaceKey | null; kind: 'turn' }
+  /** A job fire. */
+  | { fire_id: string; kind: 'fire' }
+  /** A webhook. */
+  | { name: string; kind: 'webhook' };
+
+/** Delivery state; `sent` is Hermes's `delivered`. */
+export type ObligationState =
+  /** Not yet delivered. */
+  | 'pending'
+  /** Delivered. */
+  | 'sent'
+  /** Gave up. */
+  | 'failed'
+  /** Dropped on purpose. */
+  | 'dropped';
+
+/**
+ * The whole home: the persisted half of `OrchestratorState` (§2.1); the
+ * runtime half is never written and is not part of the wire.
+ */
+export interface Orchestration {
+  /** The home folder. */
+  root: string;
+  /** `default` is the root folder; the rest are `profiles/<name>/`. */
+  profiles: Record<string, Profile>;
+}
+
+/** What is delivered. */
+export interface OutboundContent {
+  /** The text. */
+  text: string;
+  /** Attachments. */
+  attachments?: Attachment[] | null;
+  /** The message this replies to. */
+  reply_to?: string | null;
+  /** `text` | `markdown`. */
+  format?: string | null;
+}
+
+/** What happens to a worker's permission prompt when no human answers. */
+export type PermissionDefault =
+  /** Refuse after the timeout. */
+  | 'deny'
+  /** Allow after the timeout. */
+  | 'allow';
+
+/** How prompts are answered when no human is reachable (§4.6). */
+export interface PermissionPolicy {
+  /** Seconds a relayed prompt waits for an answer. */
+  timeout_seconds?: number;
+  /** The answer given when nobody replies in time. */
+  default?: PermissionDefault;
+  /** The answer given at once where nobody attends: a cron fire or a webhook turn. */
+  unattended?: PermissionUnattended;
+}
+
+/**
+ * What a prompt raised where nobody attends (a cron fire, a webhook turn) is answered with, at
+ * once (Hermes `approvals.cron_mode`).
+ */
+export type PermissionUnattended =
+  /** Refuse it. */
+  | 'deny'
+  /** Approve it. */
+  | 'approve';
+
+/** The persona: `AGENTS.md` at the profile root, content hash first. */
+export interface PersonaRef {
+  /** Always `AGENTS.md` in our folder (`SOUL.md` in a Hermes home). */
+  path: string;
+  /** The text, when loaded. */
+  text?: string | null;
+  /** Hex sha256 of the text. */
+  sha256: string;
+}
+
+/** The platform's handle for what was sent. */
+export interface Posted {
+  /** The platform message id. */
+  message_id: string;
+}
+
+/** One profile: a folder with `AGENTS.md` at its root. */
+export interface Profile {
+  /** `default` for the root, else the folder name. */
+  name: string;
+  /** The folder. */
+  dir: string;
+  /** O — which harness runs it. */
+  worker?: WorkerSpec | null;
+  /** O — `AGENTS.md`. */
+  persona?: PersonaRef | null;
+  /** H — `config.yaml` `platforms:` blocks. */
+  channels?: Record<string, ChannelConfig>;
+  /** H — `gateway.profile_routes`. */
+  routes?: Route[];
+  /** H — `cron/jobs.json`. */
+  jobs?: Record<string, Job>;
+  /** H — `webhook_subscriptions.json`. */
+  subscriptions?: Record<string, WebhookSubscription>;
+  /** H — allowlists and pairing. */
+  access?: Access;
+  /**
+   * O — the conversations, keyed by their slot (the surface key string for
+   * a live one, `<key>#<started_at>[#n]` for ended ones).
+   */
+  bindings?: Record<string, Binding>;
+  /** H — `cron/executions.db`. */
+  fires?: Fire[];
+  /** H — `delivery_obligations`. */
+  obligations?: Obligation[];
+  /** What the model does not interpret. */
+  residue?: ProfileResidue;
+}
+
+/** What a profile carries that the model does not interpret. */
+export interface ProfileResidue {
+  /** `config.yaml` keys that are the source harness's, verbatim. */
+  config?: Record<string, unknown>;
+  /** Unmodeled files, by path relative to the profile dir; copied verbatim. */
+  files?: string[];
+}
+
+/** ORCH-3: the job a recurring session belongs to. */
+export interface Recurrence {
+  /** The job id. */
+  job_id: string;
+  /** `cron` | `heartbeat`. */
+  kind?: string;
+}
+
+/** Hermes 0.21.0's `repeat`: `{times: N | null, completed: M}`; `null` times = forever. */
+export interface Repeat {
+  /** Remaining fires, or `None` for forever. */
+  times?: number | null;
+  /** Fires so far. */
+  completed?: number;
+}
+
+/** Unmodeled source fields, keyed by the source's own field name. */
+export type Residue = Record<string, unknown>;
+
+/** One route. */
+export interface Route {
+  /** Optional name. */
+  name?: string | null;
+  /** What it matches. */
+  match: RouteMatch;
+  /** The profile that answers. */
+  profile: string;
+  /** Unmodeled fields of the route, verbatim. */
+  residue?: Residue;
+}
+
+/** What a route matches; most specific wins. */
+export interface RouteMatch {
+  /** The platform. */
+  platform: string;
+  /** Discord-style guild id. */
+  guild_id?: string | null;
+  /** The chat. */
+  chat_id?: string | null;
+  /** The thread. */
+  thread_id?: string | null;
+}
+
+/** When a job fires. */
+export type Schedule =
+  /** Once, at an instant. */
+  | { run_at: string; kind: 'once' }
+  /** Every N minutes. */
+  | { minutes: number; kind: 'interval' }
+  /** A five-field cron expression in a timezone. */
+  | { expr: string; tz?: string | null; kind: 'cron' };
+
+/** Where a secret value lives. Wire form: `{"env": NAME}` or `{"dotenv": KEY}`. */
+export type SecretRef =
+  /** An environment variable of the process that resolves it. */
+  | { env: string }
+  /** A key in the home's own `.env` file. */
+  | { dotenv: string };
+
+/**
+ * ORCH-3: the conversation identity on a surface. Full tuple on a channel;
+ * degenerate (all `None`) on a terminal.
+ */
+export interface SurfaceKey {
+  /** The harness's own key string, verbatim. */
+  key?: string | null;
+  /** Transport / platform (`telegram`, `slack`, `acp`, …). */
+  platform?: string | null;
+  /**
+   * `dm` | `group` | `channel` | `thread` | `main` (harness vocabulary, verbatim).
+   * `chat_type` is the orchestrator IR's spelling of the same field.
+   */
+  kind?: string | null;
+  /** The chat / group / channel id on the platform. */
+  chat_id?: string | null;
+  /** The thread or topic within the chat. */
+  thread_id?: string | null;
+  /** The participant, when the surface is per person. */
+  participant_id?: string | null;
+}
+
+/** Where a result goes. */
+export type Target =
+  /** The surface the job was created from. */
+  | { kind: 'origin' }
+  /** The profile's `/sethome` surface. */
+  | { kind: 'home' }
+  /** A file under the profile dir (the fire's own output file). */
+  | { kind: 'local' }
+  /** A named surface, as `hermes send --to` spells one. */
+  | { platform: string; chat_id?: string | null; thread_id?: string | null; kind: 'explicit' };
+
+/** ORCH-3: why a session exists (the trigger noun; `docs/HERMES-IDEAL-SUPPORT-DESIGN.md` §3). */
+export type Trigger =
+  /** A person started it on a terminal, IDE, or chat surface. */
+  | 'human'
+  /** A message on a channel opened it. */
+  | 'channel'
+  /** A scheduled job fired it. */
+  | 'cron'
+  /** A periodic main-session turn. */
+  | 'heartbeat'
+  /** An inbound webhook / mapped hook. */
+  | 'webhook'
+  /** Spawned by a parent session (delegate / subagent). */
+  | 'parent'
+  /** An HTTP API / bridge client. */
+  | 'api'
+  /** A board's dispatcher spawned it to work a task (the workflow layer). */
+  | 'task'
+  /** The source does not say. */
+  | 'unknown';
+
+/** One subscription: the route is `/webhooks/<name>`. */
+export interface WebhookSubscription {
+  /** The name. */
+  name: string;
+  /** The HMAC secret, by reference. */
+  secret?: SecretRef | null;
+  /** Accepted event names; all when absent. */
+  events?: string[] | null;
+  /** The prompt, rendered with the payload. */
+  prompt_template?: string;
+  /** Where the answer goes. */
+  deliver?: Target | null;
+  /** Skills to load. */
+  skills?: string[];
+  /** Description. */
+  description?: string | null;
+  /** Creation, RFC3339. */
+  created_at?: string | null;
+  /** Unmodeled fields, verbatim. */
+  residue?: Residue;
+}
+
+/** The worker session a binding points at. */
+export interface Worker {
+  /** Which harness runs the conversation. */
+  harness: HarnessId;
+  /** The harness's own session id, when one exists yet. */
+  session_id?: string | null;
+  /** Where that session's transcript can be read (a path or store address). */
+  locator?: string | null;
+}
+
+/** The worker specification (O-record; Hermes has no worker choice). */
+export interface WorkerSpec {
+  /** Any registry id whose runtime can start a session. */
+  harness: HarnessId;
+  /** Model, where the harness's door accepts one. */
+  model?: string | null;
+  /** supercode preset name. */
+  preset?: string | null;
+  /** Relative to the profile dir; `.` by default. */
+  cwd?: string;
+  /** Extra environment for the worker process; secrets by reference. */
+  env?: Record<string, EnvValue>;
+  /** Permission prompt policy. */
+  permission?: PermissionPolicy;
+}