@dungle-scrubs/admin-ui-soft 0.0.0-stage → 0.1.0

package/dist/ai/types.d.ts

@@ -0,0 +1,323 @@
+//#region src/ai/types.d.ts
+/** A JSON value: what Tether stores in its `jsonb` columns. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+  readonly [key: string]: JsonValue;
+};
+/** A JSON object, such as a task's `input` or a tool call's arguments. */
+export type JsonObject = {
+  readonly [key: string]: JsonValue;
+};
+/**
+ * Where a run is in its lifecycle.
+ *
+ * Tether mapping: derived from `TaskRecord`'s lifecycle timestamps the way
+ * `TaskSnapshot.status` is. `pending`: created, or released or claim-expired
+ * and not yet claimed again. `running`: `claimedAt` set and no terminal
+ * timestamp. `waiting`: running with an approval not yet recorded.
+ * `succeeded`: `completedAt`. `failed`: `failedAt`. `cancelled`: `cancelledAt`.
+ */
+export type RunStatus = "pending" | "running" | "waiting" | "succeeded" | "failed" | "cancelled";
+/**
+ * Why a run or a step failed.
+ *
+ * Tether mapping: `TaskRecord.failure` (JSONB). Read `message` and `code` from
+ * it when the harness writes them; otherwise stringify the object into
+ * `message`.
+ */
+export type RunError = {
+  /** A human-readable explanation, shown in place. */
+  readonly message: string;
+  /** A machine-readable code, such as `SMTP_554` or `rate_limited`. */
+  readonly code?: string;
+  /** Whether retrying the same input can succeed. */
+  readonly retryable?: boolean;
+};
+/**
+ * An owner decision on a gated action (a tool call, or a whole task).
+ *
+ * Tether mapping: `TaskApprovalRecord` (`task_approvals` row, or the
+ * `approval.recorded` event payload). `decision` is its `decision`
+ * (`approved` / `rejected`), `reason` its `reason` (JSONB; a string, or the
+ * object's text), `decidedAt` its `decidedAt`, `decidedBy` its
+ * `decidedByParticipantId` resolved to a display name. Tether has no field for
+ * amended arguments or standing permissions; `amendedArgs` and
+ * `byStandingPermission` stay empty until a harness adds them.
+ */
+export type Approval = {
+  /** The decision. */
+  readonly decision: "approved" | "rejected";
+  /** The optional reason the owner gave. */
+  readonly reason?: string;
+  /** When the decision was recorded (ISO 8601). */
+  readonly decidedAt: string;
+  /** Who decided, as a display name. */
+  readonly decidedBy?: string;
+  /** Arguments the owner edited before approving, if any. */
+  readonly amendedArgs?: JsonObject;
+  /**
+   * The call ran under a standing permission ("always allow") the owner gave
+   * earlier, not a decision on this call. `decidedAt` is when the call was
+   * allowed. Tether has no source for it yet.
+   */
+  readonly byStandingPermission?: boolean;
+};
+/** Where one tool call stands. */
+export type ToolCallStatus = "running" | "awaiting-approval" | "succeeded" | "failed" | "denied" | "cancelled";
+/**
+ * One tool call an agent made.
+ *
+ * Tether mapping: no harness records tool-call arguments or results today
+ * (hub#46). The nearest records are outcome-level: email's `Action`
+ * (`surface` as `name`, `attempts` as retries), a delegated child task
+ * (`TaskRecord` with `parentTaskId`: `kind` as `name`, `input` as `args`,
+ * `result` as `result`). A harness that adopts RunInspector or
+ * TranscriptViewer adds a tool-call event to Tether.
+ */
+export type ToolCall = {
+  /** Stable id of this invocation. */
+  readonly id: string;
+  /** The tool's name, such as `archive_message`. */
+  readonly name: string;
+  /** The arguments the agent passed. */
+  readonly args: JsonObject;
+  /** What the tool returned; absent while it runs. */
+  readonly result?: JsonValue;
+  /** Where the call stands. */
+  readonly status: ToolCallStatus;
+  /** Whether the tool is marked dangerous (needs press-and-hold to approve). */
+  readonly dangerous?: boolean;
+  /** When the call started (ISO 8601). */
+  readonly startedAt?: string;
+  /** When the result landed (ISO 8601). */
+  readonly endedAt?: string;
+  /** The owner's decision, for a gated tool. */
+  readonly approval?: Approval;
+  /** Why the call failed, when `status` is `failed`. */
+  readonly error?: RunError;
+};
+/**
+ * What kind of thing a run step is. A `plan` step is the agent's plan or todo
+ * list at that point of the run (see `RunStep.plan`).
+ */
+export type RunStepKind = "message" | "reasoning" | "tool-call" | "approval" | "progress" | "plan" | "error";
+/**
+ * One item of an agent's plan or todo list.
+ *
+ * Tether mapping: no Tether event carries a plan yet. A harness that records
+ * one (a todo-list tool's arguments, or a planner's output) maps each entry
+ * here; `id` is the entry's stable key, or its position.
+ */
+export type PlanItem = {
+  /** Stable id of the item. */
+  readonly id: string;
+  /** What the item is, such as "Classify the 42 new messages". */
+  readonly label: string;
+  /** Whether the agent has finished it. */
+  readonly done: boolean;
+  /** A note under the label. */
+  readonly description?: string;
+};
+/** Where one run step stands. */
+export type RunStepStatus = "pending" | "running" | "succeeded" | "failed" | "skipped";
+/**
+ * One step on a run's timeline.
+ *
+ * Tether mapping: one `SessionEvent` scoped to the task. `id` is its
+ * `eventId`, `seq` its `seq`, `startedAt` its `createdAt`. `kind` follows the
+ * event `type`: `agent.output` and `user.message` are `message`,
+ * `task.progress` is `progress`, `approval.recorded` is `approval`,
+ * `task.failed` is `error`; `reasoning` and `tool-call` have no Tether event
+ * yet. `endedAt` is the next step's `createdAt` when the harness records no
+ * end. A retried step repeats with a higher `attempt`.
+ */
+export type RunStep = {
+  /** Stable id of the step. */
+  readonly id: string;
+  /** The event sequence number within the session, for ordering and anchors. */
+  readonly seq?: number;
+  /** What kind of step this is. */
+  readonly kind: RunStepKind;
+  /** A short label, such as "Classified 42 messages". */
+  readonly label: string;
+  /** Where the step stands. */
+  readonly status: RunStepStatus;
+  /** When the step started (ISO 8601). */
+  readonly startedAt: string;
+  /** When the step ended (ISO 8601); absent while it runs. */
+  readonly endedAt?: string;
+  /** The enclosing step, for nesting in a waterfall. */
+  readonly parentStepId?: string;
+  /** 1 for the first try; 2 and up for retries. */
+  readonly attempt?: number;
+  /** Message or reasoning text, for `message` and `reasoning` steps. */
+  readonly text?: string;
+  /** The call, for `tool-call` steps. */
+  readonly toolCall?: ToolCall;
+  /** The decision, for `approval` steps. */
+  readonly approval?: Approval;
+  /** Why the step failed, when `status` is `failed`. */
+  readonly error?: RunError;
+  /**
+   * The plan or todo list, in order, for `plan` steps. A later plan step
+   * holds the list as it stood then.
+   */
+  readonly plan?: readonly PlanItem[];
+  /**
+   * The id of the step this one retries, when `attempt` is 2 or more. It
+   * links the attempts of one action, so each can be reached from the
+   * others. Tether has no source yet.
+   */
+  readonly retryOf?: string;
+};
+/**
+ * Model usage for a run, a message or a thread.
+ *
+ * Tether mapping: Tether records no tokens or cost (hub#46). Today's real
+ * signals are `model` (email `Classification.model`, rolodex
+ * `model_version`, ollama identity on `SessionSummaryRecord`) and
+ * `latencyMs` (email `Classification.latencyMs`). Token and cost fields wait
+ * for a harness to persist the provider's usage object.
+ */
+export type Usage = {
+  /** The model id, such as `claude-sonnet-4-5` or `qwen3-14b`. */
+  readonly model?: string;
+  /** Prompt tokens sent to the model. */
+  readonly inputTokens?: number;
+  /** Tokens the model generated. */
+  readonly outputTokens?: number;
+  /** Prompt tokens served from the provider's cache, a subset of `inputTokens`. */
+  readonly cachedInputTokens?: number;
+  /** Generated tokens spent on reasoning, a subset of `outputTokens`. */
+  readonly reasoningTokens?: number;
+  /** Cost in US dollars. */
+  readonly costUsd?: number;
+  /** The model's context window in tokens, to show how full it is. */
+  readonly contextWindow?: number;
+  /** Wall-clock latency of the call or run, in milliseconds. */
+  readonly latencyMs?: number;
+};
+/**
+ * One agent run: a unit of work with a lifecycle, input, result and timeline.
+ *
+ * Tether mapping: a `TaskRecord` (or `TaskSnapshot`). `id` is `taskId`,
+ * `sessionId` `sessionId`, `parentRunId` `parentTaskId`, `kind` `kind`,
+ * `objective` `objective`, `input` / `result` the JSONB columns, `error`
+ * `failure`. `createdAt` is `createdAt`, `startedAt` `claimedAt`, `endedAt`
+ * whichever of `completedAt` / `failedAt` / `cancelledAt` is set. `agent` is
+ * the assignee or claimant participant's display name. `steps` come from the
+ * session's events for the task; `approvals` from `TaskSnapshot.approvals`.
+ */
+export type Run = {
+  /** Stable id of the run. */
+  readonly id: string;
+  /** The session (conversation) the run belongs to. */
+  readonly sessionId?: string;
+  /** The run that delegated this one, if any. */
+  readonly parentRunId?: string;
+  /** The agent that ran it, as a display name, such as "Email agent". */
+  readonly agent: string;
+  /** The task kind, such as `email_triage` or `email_fetch_signin`. */
+  readonly kind: string;
+  /** What the run set out to do, in a sentence. */
+  readonly objective: string;
+  /** Where the run stands. */
+  readonly status: RunStatus;
+  /** The run's input. */
+  readonly input?: JsonObject;
+  /** The run's result, once it succeeded. */
+  readonly result?: JsonObject;
+  /** Why it failed, once it failed. */
+  readonly error?: RunError;
+  /** When it was created (ISO 8601). */
+  readonly createdAt: string;
+  /** When an agent picked it up (ISO 8601). */
+  readonly startedAt?: string;
+  /** When it reached a terminal status (ISO 8601). */
+  readonly endedAt?: string;
+  /** The timeline, oldest first. */
+  readonly steps: readonly RunStep[];
+  /** Decisions recorded on the run, oldest first. */
+  readonly approvals?: readonly Approval[];
+  /** Model usage for the whole run. */
+  readonly usage?: Usage;
+};
+/**
+ * One message of a stored conversation, for read-only display.
+ *
+ * Tether mapping: a `user.message` or `agent.output` `SessionEvent`. `id` is
+ * the chat-v1 `messageId` or the event's `eventId`; `role` is `user` for
+ * `user.message` and `assistant` for `agent.output`; `text` is the payload's
+ * `text` (chat-v1) or `output`; `author` the `senderId` resolved to a display
+ * name; `createdAt` the payload's `recordedAt` or the event's `createdAt`;
+ * `runId` the `agent.output` payload's `taskId`. Tether stores no reasoning,
+ * tool calls or usage for a message today.
+ */
+export type TranscriptMessage = {
+  /** Stable id, used as the message's link anchor. */
+  readonly id: string;
+  /** Who spoke. */
+  readonly role: "user" | "assistant" | "system";
+  /** The speaker's display name, such as "Kevin" or "Email agent". */
+  readonly author?: string;
+  /** When it was sent (ISO 8601). */
+  readonly createdAt: string;
+  /** The message body, as markdown. */
+  readonly text: string;
+  /** The agent's reasoning before it answered, if recorded. */
+  readonly reasoning?: string;
+  /** Tool calls the agent made while answering, in order. */
+  readonly toolCalls?: readonly ToolCall[];
+  /** The run that produced this message, for linking to RunInspector. */
+  readonly runId?: string;
+  /** Model usage for this message. */
+  readonly usage?: Usage;
+};
+/**
+ * One fact a gated summary let through to a hosted agent.
+ *
+ * Tether mapping: a `SessionSummaryFact`: `category` its `category`,
+ * `statement` its `statement`, `sourceEventIds` its `sourceEventIds`. Rolodex
+ * `gateView` `publicFacts` map the same way.
+ */
+export type GatedFact = {
+  /** The fact's category, such as `approval` or `decision`. */
+  readonly category: string;
+  /** The fact as the hosted agent received it. */
+  readonly statement: string;
+  /** The events the fact was drawn from, for linking back. */
+  readonly sourceEventIds?: readonly string[];
+};
+/**
+ * The fields a gate withheld in one category. Names only: this type has no
+ * place for a withheld value, by design (RFC-02 Design 4).
+ */
+export type WithheldGroup = {
+  /** The sensitivity category, such as `health`, `money` or `credentials`. */
+  readonly category: string;
+  /** The names of the withheld fields, such as `body` or `sign_in_code`. */
+  readonly fields: readonly string[];
+};
+/**
+ * What a hosted agent received from a privacy gate, and what it did not.
+ *
+ * Tether mapping: a gated artifact. Chat's digest or interrupt-card payload
+ * (`summary` is the writer summary, `withheld` lists the message fields the
+ * payload omits), a `SessionSummaryRecord` (`summary` is `headline` plus
+ * `narrative`, `facts` its `facts`), or rolodex `gateView` (`facts` from
+ * `publicFacts`; `heldFactsCount` becomes one group of unnamed fields when
+ * the categories must stay unnamed). `producedAt` is the artifact's
+ * `published_at` or the summary's creation time.
+ */
+export type Redaction = {
+  /** The gated summary the hosted agent received. */
+  readonly summary: string;
+  /** Individual facts that passed the gate, if the gate itemizes them. */
+  readonly facts?: readonly GatedFact[];
+  /** What was withheld, grouped by category. Names only, never values. */
+  readonly withheld: readonly WithheldGroup[];
+  /** The gate that produced this, such as `chat-digest` or `rolodex-gate`. */
+  readonly gate?: string;
+  /** When the gated payload was produced (ISO 8601). */
+  readonly producedAt?: string;
+};
+//#endregion