@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/channels/contract.ts

@@ -0,0 +1,246 @@
+import { z } from 'zod';
+import type { ReplyPlan } from '../delivery/types';
+
+export const ChannelTurnBody = z.strictObject({
+  provider: z.literal('whatsapp'),
+  bindingId: z.string().regex(/^chb_[A-Za-z0-9_-]{1,120}$/),
+  bindingRevision: z.number().int().positive().safe(),
+  requestId: z.string().min(1).max(180),
+  remoteMessageRef: z.string().regex(/^hmac:[a-f0-9]{64}$/),
+  sessionId: z.string().min(1).max(255).optional(),
+  message: z.string().min(1).max(16_000),
+  context: z.strictObject({ kind: z.literal('companion') }),
+});
+
+export type ChannelTurnInput = z.infer<typeof ChannelTurnBody>;
+
+export const ChannelOrigin = z.strictObject({
+  v: z.literal(1),
+  transport: z.literal('whatsapp'),
+  binding_id: ChannelTurnBody.shape.bindingId,
+  remote_ref: ChannelTurnBody.shape.remoteMessageRef,
+});
+
+export type ChannelOrigin = z.infer<typeof ChannelOrigin>;
+
+export function channelOrigin(
+  channel: Pick<
+    ChannelTurnInput,
+    'provider' | 'bindingId' | 'remoteMessageRef'
+  >,
+): ChannelOrigin {
+  return {
+    v: 1,
+    transport: channel.provider,
+    binding_id: channel.bindingId,
+    remote_ref: channel.remoteMessageRef,
+  };
+}
+
+export interface ChannelIdentity {
+  callerDid: string;
+  provider: 'whatsapp';
+  bindingId: string;
+  bindingRevision: number;
+}
+
+export interface ChannelTurnResponse {
+  requestId: string;
+  runId: string;
+  sessionId: string;
+  status:
+    | 'queued'
+    | 'running'
+    | 'recovering'
+    | 'finished'
+    | 'aborted'
+    | 'interrupted'
+    | 'failed';
+  messageId?: string;
+  text?: string;
+  /**
+   * A finished turn's Reply Plan: the parts to deliver in order (short
+   * messages and artefact links). `text` stays the whole reply as one
+   * message for gateways that predate plans.
+   */
+  plan?: ReplyPlan;
+}
+
+export type ChannelErrorStatus =
+  | 400
+  | 401
+  | 403
+  | 404
+  | 409
+  | 410
+  | 413
+  | 428
+  | 429
+  | 503;
+
+/**
+ * The machine-readable reason a channel turn was refused. The gateway maps
+ * a refusal by `code` first and by HTTP status second. 428 (Precondition
+ * Required) means a precondition on the user's side is missing: fix it
+ * (authorize the oracle again, finish setting up the Companion room) and
+ * retry; it is never a transient outage.
+ *
+ * | code                              | status | meaning                                               |
+ * | --------------------------------- | ------ | ----------------------------------------------------- |
+ * | `invalid_request`                 | 400    | body missing, not UTF-8, not JSON, or the wrong shape |
+ * | `unauthorized`                    | 401    | no valid user-rooted channel invocation               |
+ * | `scope_mismatch`                  | 403    | the invocation does not cover this binding or body    |
+ * | `identity_mismatch`               | 403    | the channel identity does not match the request       |
+ * | `identity_required`               | 403    | the binding check got no channel identity             |
+ * | `binding_inactive`                | 403    | the Auth Hub reports the binding inactive             |
+ * | `channel_grant_not_tool_authority`| 403    | a channel request carried a delegation header         |
+ * | `session_not_found`               | 404    | the session is not the user's Companion session       |
+ * | `request_conflict`                | 409    | the request id already belongs to another message     |
+ * | `session_conflict`                | 409    | the channel is already bound to another session       |
+ * | `room_not_encrypted`              | 409    | the Companion room is not end-to-end encrypted        |
+ * | `response_expired`                | 410    | the run was pruned; the request cannot run again      |
+ * | `request_too_large`               | 413    | the body is over 64 kB                                |
+ * | `room_not_ready`                  | 428    | the user has no Companion room yet                    |
+ * | `delegation_required`             | 428    | no usable delegation to this oracle (see below)       |
+ * | `rate_limited`                    | 429    | too many requests for this user                       |
+ * | `not_configured`                  | 503    | channels or binding validation are not configured     |
+ * | `binding_check_unavailable`       | 503    | the Auth Hub binding check failed or answered badly   |
+ * | `unavailable`                     | 503    | any other failure (the shell logs it)                 |
+ */
+export type ChannelErrorCode =
+  | 'invalid_request'
+  | 'unauthorized'
+  | 'scope_mismatch'
+  | 'identity_mismatch'
+  | 'identity_required'
+  | 'binding_inactive'
+  | 'channel_grant_not_tool_authority'
+  | 'session_not_found'
+  | 'request_conflict'
+  | 'session_conflict'
+  | 'room_not_encrypted'
+  | 'response_expired'
+  | 'request_too_large'
+  | 'room_not_ready'
+  | 'delegation_required'
+  | 'rate_limited'
+  | 'not_configured'
+  | 'binding_check_unavailable'
+  | 'unavailable';
+
+export type ChannelTurnOutcome =
+  | { ok: true; result: ChannelTurnResponse }
+  | {
+      ok: false;
+      status: ChannelErrorStatus;
+      code: ChannelErrorCode;
+      message: string;
+    };
+
+export class ChannelError extends Error {
+  constructor(
+    readonly status: ChannelErrorStatus,
+    message: string,
+    readonly code: ChannelErrorCode,
+  ) {
+    super(message);
+    this.name = 'ChannelError';
+  }
+}
+
+/**
+ * The least lifetime a delegation must have left for a channel turn to be
+ * admitted (seconds): a turn, its tool calls and its owner-copy flush must
+ * not outlive the delegation they run under.
+ */
+export const CHANNEL_DELEGATION_MIN_REMAINING_SECONDS = 900;
+
+/** The user's delegation to this oracle as the user object holds it. */
+export interface ChannelDelegation {
+  raw?: string;
+  /** Unix seconds: the delegation's effective expiry; absent = unknown. */
+  expiration?: number;
+}
+
+export function delegationRequiredError(): ChannelError {
+  return new ChannelError(
+    428,
+    'Companion delegation required: the user must authorize this oracle again',
+    'delegation_required',
+  );
+}
+
+/**
+ * A channel turn runs under the user's stored delegation to this oracle,
+ * like a Matrix turn. Without one, with an unknown expiry, or with less than
+ * `CHANNEL_DELEGATION_MIN_REMAINING_SECONDS` left, there is no tool
+ * authority to run under: the turn is refused with an explicit 428
+ * `delegation_required` instead of running degraded (memory, files and the
+ * sandbox would fail silently).
+ */
+export function requireChannelDelegation(
+  delegation: ChannelDelegation | undefined,
+  nowSeconds: number,
+): void {
+  if (
+    !delegation?.raw ||
+    typeof delegation.expiration !== 'number' ||
+    !Number.isFinite(delegation.expiration) ||
+    delegation.expiration <=
+      nowSeconds + CHANNEL_DELEGATION_MIN_REMAINING_SECONDS
+  )
+    throw delegationRequiredError();
+}
+
+export async function channelRequestHash(raw: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(raw),
+  );
+  return Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('');
+}
+
+export async function readChannelBody(request: Request): Promise<string> {
+  const reader = request.body?.getReader();
+  if (!reader)
+    throw new ChannelError(
+      400,
+      'A channel turn is required',
+      'invalid_request',
+    );
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  while (true) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    size += chunk.value.byteLength;
+    if (size > 64_000) {
+      await reader.cancel();
+      throw new ChannelError(
+        413,
+        'Channel request is too large',
+        'request_too_large',
+      );
+    }
+    chunks.push(chunk.value);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(
+      bytes,
+    );
+  } catch {
+    throw new ChannelError(
+      400,
+      'Channel request must be UTF-8',
+      'invalid_request',
+    );
+  }
+}

package/src/channels/turns.ts

@@ -0,0 +1,280 @@
+import type { DoSqliteDatabase } from '../sqlite/database';
+import type { RunRecord } from '../do/run-store';
+import type { TurnIdentity, TurnRequest } from '../do/contracts';
+import { parseReplyPlan, planText } from '../delivery/schema';
+import type { ReplyPlan } from '../delivery/types';
+import {
+  ChannelError,
+  channelRequestHash,
+  type ChannelTurnInput,
+  type ChannelTurnResponse,
+} from './contract';
+
+interface ReceiptRow extends Record<string, string | number | null> {
+  binding_id: string;
+  request_id: string;
+  request_hash: string;
+  run_id: string;
+  session_id: string | null;
+  /** 1 once the assistant reply was mirrored into the Companion room. */
+  reply_mirrored: number;
+}
+
+export interface ChannelTurnsHost {
+  createSession(identity: TurnIdentity, markerTxnId: string): Promise<string>;
+  assertSession(identity: TurnIdentity, sessionId: string): Promise<void>;
+  /**
+   * Throws a `ChannelError` (428 `delegation_required`) when the user has no
+   * usable delegation for this oracle: none, or one too close to expiry.
+   */
+  requireDelegation(identity: TurnIdentity): Promise<void>;
+  getRun(runId: string): Promise<RunRecord | undefined>;
+  /** The Reply Plan (JSON) a finished run was built into, if any. */
+  getPlan(runId: string): Promise<string | null>;
+  wasPruned(runId: string): Promise<boolean>;
+  begin(runId: string, request: TurnRequest): Promise<RunRecord>;
+  mirror(
+    request: TurnRequest,
+    text: string,
+    author: 'user' | 'oracle',
+  ): Promise<void>;
+  changed(): Promise<void>;
+}
+
+export class ChannelTurns {
+  private admission: Promise<unknown> = Promise.resolve();
+  private setupPromise: Promise<void> | undefined;
+
+  constructor(
+    private readonly db: DoSqliteDatabase,
+    private readonly host: ChannelTurnsHost,
+  ) {}
+
+  private setup(): Promise<void> {
+    this.setupPromise ??= (async () => {
+      await this.db.run(`CREATE TABLE IF NOT EXISTS channel_requests (
+        binding_id TEXT NOT NULL, request_id TEXT NOT NULL, request_hash TEXT NOT NULL,
+        run_id TEXT NOT NULL UNIQUE, session_id TEXT,
+        reply_mirrored INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (binding_id, request_id)
+      )`);
+      // Tables created before the column existed (CREATE TABLE IF NOT
+      // EXISTS leaves them as they were).
+      const columns = await this.db.exec<{ name: string }>(
+        'PRAGMA table_info(channel_requests)',
+      );
+      if (!columns.some((c) => c.name === 'reply_mirrored'))
+        await this.db.run(
+          'ALTER TABLE channel_requests ADD COLUMN reply_mirrored INTEGER NOT NULL DEFAULT 0',
+        );
+      await this.db.run(`CREATE TABLE IF NOT EXISTS channel_sessions (
+        binding_id TEXT PRIMARY KEY, session_id TEXT NOT NULL
+      )`);
+    })().catch((error: unknown) => {
+      this.setupPromise = undefined;
+      throw error;
+    });
+    return this.setupPromise;
+  }
+
+  /** Admissions, reply deliveries and session releases run one at a time. */
+  private serialize<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.admission.then(work);
+    this.admission = next.catch(() => undefined);
+    return next;
+  }
+
+  submit(
+    identity: TurnIdentity,
+    input: ChannelTurnInput,
+    requestHash: string,
+  ): Promise<ChannelTurnResponse> {
+    return this.serialize(() => this.admit(identity, input, requestHash));
+  }
+
+  /**
+   * Mirror a finished run's reply into the Companion room once: the receipt
+   * records the delivery, so later polls of the same request do not send it
+   * again. Called when the run ends; a poll retries a delivery that failed.
+   * `text` is the model's reply; a run with a Reply Plan mirrors the plan
+   * instead, as the channel user received it.
+   */
+  deliverReply(
+    request: TurnRequest,
+    runId: string,
+    text: string,
+  ): Promise<void> {
+    return this.serialize(async () => {
+      await this.deliver(request, runId, await this.reply(runId, text));
+    });
+  }
+
+  /** A finished run's Reply Plan, and the reply as the channel user sees it. */
+  private async reply(
+    runId: string,
+    text: string,
+  ): Promise<{ plan: ReplyPlan | null; rendered: string }> {
+    const plan = parseReplyPlan(await this.host.getPlan(runId));
+    return { plan, rendered: plan ? planText(plan) : text };
+  }
+
+  /**
+   * The session was deleted: release every binding that pointed at it, so
+   * the binding's next message opens a new Companion session. Returns
+   * whether a binding was released.
+   */
+  forgetSession(sessionId: string): Promise<boolean> {
+    return this.serialize(async () => {
+      await this.setup();
+      const released = await this.db.run(
+        'DELETE FROM channel_sessions WHERE session_id = ?',
+        [sessionId],
+      );
+      if (released.changes === 0) return false;
+      await this.host.changed();
+      return true;
+    });
+  }
+
+  private async deliver(
+    request: TurnRequest,
+    runId: string,
+    reply: { rendered: string },
+  ): Promise<void> {
+    await this.setup();
+    const receipt = await this.db.get<{ reply_mirrored: number }>(
+      'SELECT reply_mirrored FROM channel_requests WHERE run_id = ?',
+      [runId],
+    );
+    if (Number(receipt?.reply_mirrored ?? 0) === 1) return;
+    await this.host.mirror(request, reply.rendered, 'oracle');
+    await this.db.run(
+      'UPDATE channel_requests SET reply_mirrored = 1 WHERE run_id = ?',
+      [runId],
+    );
+    await this.host.changed();
+  }
+
+  private async admit(
+    identity: TurnIdentity,
+    input: ChannelTurnInput,
+    requestHash: string,
+  ): Promise<ChannelTurnResponse> {
+    await this.setup();
+    if (
+      !identity.channel ||
+      identity.channel.bindingId !== input.bindingId ||
+      identity.channel.bindingRevision !== input.bindingRevision ||
+      identity.channel.provider !== input.provider
+    )
+      throw new ChannelError(
+        403,
+        'Channel identity does not match this request',
+        'identity_mismatch',
+      );
+    const runId = `channel_${await channelRequestHash(JSON.stringify([input.bindingId, input.requestId]))}`;
+    // Checked before a receipt is written: the receipt of a pruned run is
+    // gone (run-store.ts), and a new one must not take its place.
+    if (await this.host.wasPruned(runId))
+      throw new ChannelError(
+        410,
+        'Channel response has expired; this request cannot execute again',
+        'response_expired',
+      );
+    const admitted = await this.db.run(
+      `INSERT OR IGNORE INTO channel_requests
+      (binding_id, request_id, request_hash, run_id) VALUES (?, ?, ?, ?)`,
+      [input.bindingId, input.requestId, requestHash, runId],
+    );
+    // A poll of an admitted request changes nothing.
+    if (admitted.changes === 1) await this.host.changed();
+    const receipt = await this.db.get<ReceiptRow>(
+      'SELECT * FROM channel_requests WHERE binding_id = ? AND request_id = ?',
+      [input.bindingId, input.requestId],
+    );
+    if (!receipt || receipt.request_hash !== requestHash)
+      throw new ChannelError(
+        409,
+        'This request ID already belongs to another message',
+        'request_conflict',
+      );
+    let sessionId = receipt.session_id;
+    // The session is checked when this request is bound to it, and again
+    // before the request starts a run; a poll of a run that exists already
+    // only reads its receipt and row.
+    let sessionChecked = false;
+    if (!sessionId) {
+      const binding = await this.db.get<{ session_id: string }>(
+        'SELECT session_id FROM channel_sessions WHERE binding_id = ?',
+        [input.bindingId],
+      );
+      if (binding && input.sessionId && binding.session_id !== input.sessionId)
+        throw new ChannelError(
+          409,
+          'This channel already has another session',
+          'session_conflict',
+        );
+      sessionId =
+        binding?.session_id ??
+        input.sessionId ??
+        // The marker transaction id is fixed per binding AND the request that
+        // opens the session: a retry of that request reuses the marker event,
+        // while a binding whose session was deleted gets a new one.
+        (await this.host.createSession(
+          identity,
+          `channel-session-${await channelRequestHash(JSON.stringify([input.bindingId, input.requestId]))}`,
+        ));
+      await this.host.assertSession(identity, sessionId);
+      sessionChecked = true;
+      await this.db.transaction(async () => {
+        await this.db.run(
+          'INSERT OR IGNORE INTO channel_sessions (binding_id, session_id) VALUES (?, ?)',
+          [input.bindingId, sessionId],
+        );
+        await this.db.run(
+          'UPDATE channel_requests SET session_id = ? WHERE run_id = ?',
+          [sessionId, runId],
+        );
+      });
+      await this.host.changed();
+    }
+    const request: TurnRequest = {
+      identity,
+      sessionId,
+      message: input.message,
+      client: 'channel',
+      requestId: input.requestId,
+      multitask: 'enqueue',
+      channel: {
+        provider: input.provider,
+        bindingId: input.bindingId,
+        remoteMessageRef: input.remoteMessageRef,
+      },
+    };
+    let record = await this.host.getRun(runId);
+    if (!record) {
+      if (!sessionChecked) await this.host.assertSession(identity, sessionId);
+      await this.host.requireDelegation(identity);
+      await this.host.mirror(request, request.message, 'user');
+      record = await this.host.begin(runId, request);
+    }
+    const reply =
+      record.status === 'finished'
+        ? await this.reply(runId, record.partialText ?? '')
+        : null;
+    // The Companion room records the reply the channel user received, once.
+    if (reply) await this.deliver(request, runId, reply);
+    return {
+      requestId: input.requestId,
+      runId,
+      sessionId,
+      status: record.status,
+      ...(record.messageId ? { messageId: record.messageId } : {}),
+      // `text` is the whole reply as one message for gateways that predate
+      // plans: the rendered plan when there is one (it carries the artefact
+      // links), else the model's text.
+      ...(reply ? { text: reply.rendered } : {}),
+      ...(reply?.plan ? { plan: reply.plan } : {}),
+    };
+  }
+}