@agentic-kit/run-log-client 0.2.0

package/esm/documents.js

@@ -0,0 +1,107 @@
+/**
+ * The documents this lane needs, built from a module's names.
+ *
+ * Written as strings rather than generated: the run surface belongs to a
+ * tenant's schema, so there is no committed SDK target that carries it, and the
+ * fields queried here are exactly the columns the run generator emits.
+ *
+ * The shapes follow the conventions the generated targets in `sdk/` use against
+ * this platform's GraphQL: a collection takes `where: <Type>Filter` (not
+ * `filter`), there is no single-node query field — one row is a `first: 1`
+ * collection read — and an update takes `{ id, <singular>Patch }`.
+ */
+export const RUN_FIELDS = `
+      id
+      threadId
+      actorId
+      entityId
+      status
+      placement
+      executionId
+      repoUrl
+      branch
+      baseCommit
+      headCommit
+      lastEventSeq
+      attempt
+      parentRunId
+      error
+      artifacts
+      deadlineAt
+      startedAt
+      finishedAt
+      createdAt`;
+// The columns are named for what they describe rather than for the harness that
+// writes them, which is the shape `@agentic-kit/run-log`'s record asserts.
+export const EVENT_FIELDS = `
+      runId
+      seq
+      recordedAt
+      transcriptFormat
+      transcriptVersion
+      entry`;
+export const runsDocument = (names) => `
+query Runs($first: Int!, $where: ${names.runType}Filter) {
+  ${names.runs}(first: $first, where: $where, orderBy: [CREATED_AT_DESC]) {
+    nodes {${RUN_FIELDS}
+    }
+  }
+}`;
+export const runDocument = (names) => `
+query Run($where: ${names.runType}Filter!) {
+  ${names.runs}(first: 1, where: $where) {
+    nodes {${RUN_FIELDS}
+    }
+  }
+}`;
+export const eventsDocument = (names) => `
+query RunEvents($first: Int!, $where: ${names.eventType}Filter!) {
+  ${names.events}(first: $first, where: $where, orderBy: [SEQ_ASC]) {
+    nodes {${EVENT_FIELDS}
+    }
+  }
+}`;
+export const appendDocument = (names) => `
+mutation AppendRunEvent($input: Create${names.eventType}Input!) {
+  ${names.createEvent}(input: $input) {
+    ${names.event} {${EVENT_FIELDS}
+    }
+  }
+}`;
+/**
+ * Open a run.
+ *
+ * A cloud run is opened by the worker on the platform's side of the callback
+ * lane; a local run has no worker, so the host that executes it opens its own
+ * row here — as the user, over the tenant API, which is what makes `actor_id`,
+ * `principal_id` and `entity_id` the session's claims rather than anything this
+ * client could pass. Only the columns a host legitimately chooses are sent.
+ */
+export const createRunDocument = (names) => `
+mutation CreateRun($input: Create${names.runType}Input!) {
+  ${names.createRun}(input: $input) {
+    ${names.run} {${RUN_FIELDS}
+    }
+  }
+}`;
+/**
+ * Open the thread a run hangs from. `agent_run.thread_id` is required and a
+ * local host is the first writer of its own conversation, so it creates one.
+ */
+export const createThreadDocument = (names) => `
+mutation CreateThread($input: Create${names.threadType}Input!) {
+  ${names.createThread}(input: $input) {
+    ${names.thread} {
+      id
+      title
+      createdAt
+    }
+  }
+}`;
+export const advanceRunDocument = (names) => `
+mutation AdvanceRun($input: Update${names.runType}Input!) {
+  ${names.updateRun}(input: $input) {
+    ${names.run} {${RUN_FIELDS}
+    }
+  }
+}`;

package/esm/follow-run.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The follower a run surface subscribes to: one view per change, until the run
+ * is terminal or the caller aborts.
+ *
+ * This is a loop of its own rather than `@agentic-kit/run-log`'s `follow`
+ * because a surface follows two things, not one: the log *and* the run row.
+ * Status, the attached execution and the head commit live on the row, and a run
+ * that goes idle or finishes emits no event announcing it — so a follower that
+ * only tailed events would show a finished run as still running.
+ *
+ * Catch-up needs no special path. Every read is `seq > cursor`, so a client that
+ * was asleep for an hour resumes with the same call it makes when live, and the
+ * view merges by `seq` so an overlapping read cannot duplicate a turn.
+ */
+import type { RunLogCursor } from '@agentic-kit/run-log';
+import type { GraphqlRunLogClient } from './client';
+import { type RunView } from './view';
+export interface FollowRunOptions {
+    cursor?: RunLogCursor;
+    /** Delay between reads when no wakeup arrives. */
+    pollIntervalMs?: number;
+    /** Records per read; a backlog is drained in pages, not in one query. */
+    limit?: number;
+    /** From `createRealtimeWakeup`, when the app has DataRealtime on the table. */
+    waitForChange?: (signal?: AbortSignal) => Promise<void>;
+    signal?: AbortSignal;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * Reads after a terminal status, so the tail written as a run finishes is not
+     * lost to a race between the last append and the status update.
+     */
+    drainReads?: number;
+}
+/**
+ * Yield a view whenever the run changes. The first yield is the run's whole
+ * history, so a caller renders once rather than animating a backlog.
+ */
+export declare function followRun(client: GraphqlRunLogClient, runId: string, options?: FollowRunOptions): AsyncGenerator<RunView, void, void>;

package/esm/follow-run.js

@@ -0,0 +1,91 @@
+/**
+ * The follower a run surface subscribes to: one view per change, until the run
+ * is terminal or the caller aborts.
+ *
+ * This is a loop of its own rather than `@agentic-kit/run-log`'s `follow`
+ * because a surface follows two things, not one: the log *and* the run row.
+ * Status, the attached execution and the head commit live on the row, and a run
+ * that goes idle or finishes emits no event announcing it — so a follower that
+ * only tailed events would show a finished run as still running.
+ *
+ * Catch-up needs no special path. Every read is `seq > cursor`, so a client that
+ * was asleep for an hour resumes with the same call it makes when live, and the
+ * view merges by `seq` so an overlapping read cannot duplicate a turn.
+ */
+import { START } from '@agentic-kit/run-log';
+import { applyError, applyRecords, applyRun, emptyRunView, isFollowable, } from './view';
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_LIMIT = 200;
+const DEFAULT_DRAIN_READS = 1;
+const defaultSleep = (ms, signal) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        resolve();
+    }, { once: true });
+});
+/**
+ * Yield a view whenever the run changes. The first yield is the run's whole
+ * history, so a caller renders once rather than animating a backlog.
+ */
+export async function* followRun(client, runId, options = {}) {
+    const sleep = options.sleep ?? defaultSleep;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const drainReads = options.drainReads ?? DEFAULT_DRAIN_READS;
+    // The formats this client can read are the formats the view can project: a
+    // surface following a run written by a second harness renders it with no
+    // configuration of its own.
+    const projection = { readers: client.readers };
+    let view = emptyRunView();
+    let cursor = options.cursor ?? START;
+    let drainsLeft = drainReads;
+    while (!options.signal?.aborted) {
+        let batch = [];
+        try {
+            view = applyRun(view, await client.getRun(runId), projection);
+            // Drain the backlog before yielding: a run with a thousand events should
+            // render once, not a thousand times.
+            for (;;) {
+                const page = await client.read(runId, cursor, limit);
+                if (page.records.length === 0)
+                    break;
+                cursor = page.cursor;
+                batch = batch.concat(page.records);
+                if (page.records.length < limit)
+                    break;
+            }
+        }
+        catch (error) {
+            // Yielded, not thrown: a surface that loses the API for a moment should
+            // show that it did, and the caller decides whether to abort.
+            yield applyError(view, error, projection);
+            if (options.signal?.aborted)
+                return;
+            await sleep(pollIntervalMs, options.signal);
+            continue;
+        }
+        // A successful pass clears a previous failure: the surface is reading again.
+        view = applyRecords({ ...view, error: undefined }, batch, projection);
+        yield view;
+        if (!isFollowable(view)) {
+            if (drainsLeft <= 0)
+                return;
+            drainsLeft -= 1;
+        }
+        else {
+            drainsLeft = drainReads;
+        }
+        if (options.signal?.aborted)
+            return;
+        if (options.waitForChange) {
+            await Promise.race([
+                options.waitForChange(options.signal),
+                sleep(pollIntervalMs, options.signal),
+            ]);
+        }
+        else {
+            await sleep(pollIntervalMs, options.signal);
+        }
+    }
+}

package/esm/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@agentic-kit/run-log-client` — the run log as a user's browser sees it.
+ *
+ * One tenant-GraphQL `RunLogStore` over a module's `agent_run`/`agent_event`
+ * pair, a follower that tails the run row alongside the log, and the pure
+ * reduction a surface renders. No React, no node builtins: the platform UI, a
+ * desktop pane and a test all consume the same three pieces.
+ */
+/**
+ * The projections and record types a surface renders, re-exported so a host
+ * imports one package rather than reaching past this one into the kernel.
+ */
+export { ATTACHABLE_STATUSES, createRunLogClient, type CreateRunInput, type CreateThreadInput, GraphqlRunLogClient, isSeqConflict, isTerminalStatus, type ListRunsArgs, type RunLogClientOptions, type RunPatch, type RunStatus, type RunSummary, TERMINAL_STATUSES, type ThreadSummary, } from './client';
+export { advanceRunDocument, appendDocument, createRunDocument, createThreadDocument, EVENT_FIELDS, eventsDocument, RUN_FIELDS, runDocument, runsDocument, } from './documents';
+export { followRun, type FollowRunOptions } from './follow-run';
+export { adoptLocalRun, type LocalRun, markLocalRunFailed, markLocalRunIdle, markLocalRunRunning, openLocalRun, type OpenLocalRunOptions, } from './local-run';
+export { DEFAULT_EVENT_TABLE, DEFAULT_RUN_TABLE, DEFAULT_THREAD_TABLE, type RunLogNames, runLogNames, } from './names';
+export { changedSubscriptionDocument, changedSubscriptionField, createRealtimeWakeup, type RealtimeWakeup, type RealtimeWakeupOptions, type RunLogWsClient, } from './realtime';
+export { isMissingRunSurface } from './surface';
+export { createGraphqlRequest, type GraphqlRequest, type GraphqlTransportOptions, } from './transport';
+export { applyError, applyRecords, applyRun, emptyRunView, isFollowable, mergeRecords, type RunView, type RunViewPhase, type RunViewProjection, } from './view';
+export type { ApprovalResolutionInput, ApprovalState, Conversation, ConversationPart, ModelUsage, RunEventRecord, RunLogCursor, RunLogPage, RunUsage, ToolCallState, ToolCallStatus, ToolStateProjection, } from '@agentic-kit/run-log';

package/esm/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@agentic-kit/run-log-client` — the run log as a user's browser sees it.
+ *
+ * One tenant-GraphQL `RunLogStore` over a module's `agent_run`/`agent_event`
+ * pair, a follower that tails the run row alongside the log, and the pure
+ * reduction a surface renders. No React, no node builtins: the platform UI, a
+ * desktop pane and a test all consume the same three pieces.
+ */
+/**
+ * The projections and record types a surface renders, re-exported so a host
+ * imports one package rather than reaching past this one into the kernel.
+ */
+export { ATTACHABLE_STATUSES, createRunLogClient, GraphqlRunLogClient, isSeqConflict, isTerminalStatus, TERMINAL_STATUSES, } from './client';
+export { advanceRunDocument, appendDocument, createRunDocument, createThreadDocument, EVENT_FIELDS, eventsDocument, RUN_FIELDS, runDocument, runsDocument, } from './documents';
+export { followRun } from './follow-run';
+export { adoptLocalRun, markLocalRunFailed, markLocalRunIdle, markLocalRunRunning, openLocalRun, } from './local-run';
+export { DEFAULT_EVENT_TABLE, DEFAULT_RUN_TABLE, DEFAULT_THREAD_TABLE, runLogNames, } from './names';
+export { changedSubscriptionDocument, changedSubscriptionField, createRealtimeWakeup, } from './realtime';
+export { isMissingRunSurface } from './surface';
+export { createGraphqlRequest, } from './transport';
+export { applyError, applyRecords, applyRun, emptyRunView, isFollowable, mergeRecords, } from './view';

package/esm/local-run.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A run executed by a host on the user's own machine.
+ *
+ * The cloud lane opens its run on the platform's side — the worker creates the
+ * row, then hands the Job a callback lane to append through. A local host has no
+ * worker in front of it: it authenticates as the user against the tenant API and
+ * so opens its own thread and run, which is why `placement` is stated here
+ * rather than defaulted, and why nothing in this file passes an identity. The
+ * claims of the request's transaction are the run's owner, and RLS on
+ * `agent_run`/`agent_event` is the same visibility rule a cloud run obeys.
+ *
+ * Kept in this package rather than in the desktop app so the host that opens a
+ * local run and the reader the web UI draws it with are the same code.
+ */
+import type { GraphqlRunLogClient, RunSummary } from './client';
+export interface OpenLocalRunOptions {
+    store: GraphqlRunLogClient;
+    /** Title for the thread this run opens; the first prompt makes a good one. */
+    title?: string;
+    /** An existing thread to append this run to, when the host already has one. */
+    threadId?: string;
+    repoUrl?: string;
+    branch?: string;
+}
+export interface LocalRun {
+    runId: string;
+    threadId: string;
+}
+/**
+ * Open a durable local run: a thread if the host does not already have one, then
+ * a `pending` run marked `placement: 'local'`.
+ */
+export declare function openLocalRun(options: OpenLocalRunOptions): Promise<LocalRun>;
+/**
+ * Adopt a run this host opened earlier — the resume path, and the check that a
+ * cached run id still belongs to the signed-in user. Throws when the run is gone
+ * or invisible, so a stale cache cannot silently start a second history.
+ */
+export declare function adoptLocalRun(store: GraphqlRunLogClient, runId: string): Promise<RunSummary>;
+/** The host has picked the run up and is about to drive the model. */
+export declare function markLocalRunRunning(store: GraphqlRunLogClient, runId: string, now?: Date): Promise<void>;
+/**
+ * The turn finished and the host is waiting for the user. `idle` rather than
+ * `succeeded` for the same reason a cloud chat run goes idle: the session can be
+ * prompted again, and only a closed session is terminal.
+ */
+export declare function markLocalRunIdle(store: GraphqlRunLogClient, runId: string): Promise<void>;
+/** The turn failed. The message is recorded on the run before it is rethrown. */
+export declare function markLocalRunFailed(store: GraphqlRunLogClient, runId: string, error: unknown, now?: Date): Promise<void>;

package/esm/local-run.js

@@ -0,0 +1,69 @@
+/**
+ * A run executed by a host on the user's own machine.
+ *
+ * The cloud lane opens its run on the platform's side — the worker creates the
+ * row, then hands the Job a callback lane to append through. A local host has no
+ * worker in front of it: it authenticates as the user against the tenant API and
+ * so opens its own thread and run, which is why `placement` is stated here
+ * rather than defaulted, and why nothing in this file passes an identity. The
+ * claims of the request's transaction are the run's owner, and RLS on
+ * `agent_run`/`agent_event` is the same visibility rule a cloud run obeys.
+ *
+ * Kept in this package rather than in the desktop app so the host that opens a
+ * local run and the reader the web UI draws it with are the same code.
+ */
+/**
+ * Open a durable local run: a thread if the host does not already have one, then
+ * a `pending` run marked `placement: 'local'`.
+ */
+export async function openLocalRun(options) {
+    const { store } = options;
+    const threadId = options.threadId ??
+        (await store.createThread({ title: options.title, mode: 'agent' })).id;
+    const run = await store.createRun({
+        threadId,
+        placement: 'local',
+        status: 'pending',
+        ...(options.repoUrl === undefined ? {} : { repoUrl: options.repoUrl }),
+        ...(options.branch === undefined ? {} : { branch: options.branch }),
+    });
+    if (run.placement !== 'local') {
+        throw new Error(`run ${run.id} was opened as placement '${run.placement}', not 'local'; the tenant refused the placement this host declared`);
+    }
+    return { runId: run.id, threadId };
+}
+/**
+ * Adopt a run this host opened earlier — the resume path, and the check that a
+ * cached run id still belongs to the signed-in user. Throws when the run is gone
+ * or invisible, so a stale cache cannot silently start a second history.
+ */
+export async function adoptLocalRun(store, runId) {
+    const run = await store.getRun(runId);
+    if (run.placement !== 'local') {
+        throw new Error(`run ${runId} has placement '${run.placement}'; a local host must not take over a cloud run`);
+    }
+    return run;
+}
+/** The host has picked the run up and is about to drive the model. */
+export async function markLocalRunRunning(store, runId, now = new Date()) {
+    await store.updateRun(runId, {
+        status: 'running',
+        startedAt: now.toISOString(),
+    });
+}
+/**
+ * The turn finished and the host is waiting for the user. `idle` rather than
+ * `succeeded` for the same reason a cloud chat run goes idle: the session can be
+ * prompted again, and only a closed session is terminal.
+ */
+export async function markLocalRunIdle(store, runId) {
+    await store.updateRun(runId, { status: 'idle' });
+}
+/** The turn failed. The message is recorded on the run before it is rethrown. */
+export async function markLocalRunFailed(store, runId, error, now = new Date()) {
+    await store.updateRun(runId, {
+        status: 'failed',
+        error: error instanceof Error ? error.message : String(error),
+        finishedAt: now.toISOString(),
+    });
+}

package/esm/names.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The GraphQL names a module's run surface is exposed under.
+ *
+ * The tables are provisioned per agent module (`agent_module.has_runs`), and a
+ * module carries its own table names — `agent_run`/`agent_event` at app scope,
+ * `org_agent_run`/`org_agent_event` at org scope — so a reader cannot hardcode
+ * the fields it queries. Everything here is derived from the two physical names
+ * the module loader already reports, using the same inflection the generated
+ * SDK targets use: `agent_event` → node `agentEvent`, connection `agentEvents`,
+ * mutation `createAgentEvent`, order-by `SEQ_ASC`.
+ *
+ * Derived rather than injected because the alternative is a table of names per
+ * tenant, which drifts the moment a module is provisioned under a new scope.
+ */
+export interface RunLogNames {
+    /** Physical table name the rest of the names derive from. */
+    runTable: string;
+    eventTable: string;
+    /**
+     * The thread a run hangs from. `agent_run.thread_id` is required, so a host
+     * that opens its own run — a local one — needs the thread's names too; a host
+     * that only reads runs never touches them.
+     */
+    threadTable: string;
+    /** Single-node field, e.g. `agentRun`. */
+    run: string;
+    event: string;
+    thread: string;
+    /** Connection field, e.g. `agentRuns`. */
+    runs: string;
+    events: string;
+    threads: string;
+    /** Type name, e.g. `AgentRun` — filters and inputs are named after it. */
+    runType: string;
+    eventType: string;
+    threadType: string;
+    createEvent: string;
+    createRun: string;
+    createThread: string;
+    updateRun: string;
+    /** Patch field on the update input, e.g. `agentRunPatch`. */
+    runPatch: string;
+}
+export declare const DEFAULT_RUN_TABLE = "agent_run";
+export declare const DEFAULT_EVENT_TABLE = "agent_event";
+export declare const DEFAULT_THREAD_TABLE = "agent_thread";
+export declare function runLogNames(runTable?: string, eventTable?: string, threadTable?: string): RunLogNames;

package/esm/names.js

@@ -0,0 +1,69 @@
+/**
+ * The GraphQL names a module's run surface is exposed under.
+ *
+ * The tables are provisioned per agent module (`agent_module.has_runs`), and a
+ * module carries its own table names — `agent_run`/`agent_event` at app scope,
+ * `org_agent_run`/`org_agent_event` at org scope — so a reader cannot hardcode
+ * the fields it queries. Everything here is derived from the two physical names
+ * the module loader already reports, using the same inflection the generated
+ * SDK targets use: `agent_event` → node `agentEvent`, connection `agentEvents`,
+ * mutation `createAgentEvent`, order-by `SEQ_ASC`.
+ *
+ * Derived rather than injected because the alternative is a table of names per
+ * tenant, which drifts the moment a module is provisioned under a new scope.
+ */
+const camelize = (snake) => snake
+    .split('_')
+    .filter((part) => part.length > 0)
+    .map((part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+const pascalize = (snake) => {
+    const camel = camelize(snake);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+};
+/**
+ * Graphile's pluralisation for the shapes a table name can take here. Only the
+ * regular cases and the two irregular endings a generated name can hit are
+ * handled: a table whose name pluralises irregularly would produce a field this
+ * cannot name, and that is a schema this reader must not silently mis-address.
+ */
+const pluralize = (word) => {
+    if (/(s|x|z|ch|sh)$/.test(word))
+        return `${word}es`;
+    if (/[^aeiou]y$/.test(word))
+        return `${word.slice(0, -1)}ies`;
+    return `${word}s`;
+};
+export const DEFAULT_RUN_TABLE = 'agent_run';
+export const DEFAULT_EVENT_TABLE = 'agent_event';
+export const DEFAULT_THREAD_TABLE = 'agent_thread';
+export function runLogNames(runTable = DEFAULT_RUN_TABLE, eventTable = DEFAULT_EVENT_TABLE, threadTable = DEFAULT_THREAD_TABLE) {
+    if (!runTable || !eventTable || !threadTable) {
+        throw new Error('runLogNames requires the run, event and thread table names; a module without a run surface has none of them');
+    }
+    const run = camelize(runTable);
+    const event = camelize(eventTable);
+    const thread = camelize(threadTable);
+    const runType = pascalize(runTable);
+    const eventType = pascalize(eventTable);
+    const threadType = pascalize(threadTable);
+    return {
+        runTable,
+        eventTable,
+        threadTable,
+        run,
+        event,
+        thread,
+        runs: pluralize(run),
+        events: pluralize(event),
+        threads: pluralize(thread),
+        runType,
+        eventType,
+        threadType,
+        createEvent: `create${eventType}`,
+        createRun: `create${runType}`,
+        createThread: `create${threadType}`,
+        updateRun: `update${runType}`,
+        runPatch: `${run}Patch`,
+    };
+}

package/esm/realtime.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The push wakeup, when the app has one.
+ *
+ * A run surface is correct without this: `follow` polls, and every read is a
+ * cursor read, so nothing is missed by a reader that woke late. What realtime
+ * buys is latency, and it costs nothing in correctness — which is why it is a
+ * wakeup here rather than a delivery mechanism. Records are never taken from a
+ * subscription payload: the notification says *something changed*, the cursor
+ * read says *what*, so a dropped, duplicated or out-of-order notification cannot
+ * corrupt a transcript, and a reconnecting client catches up by reading rather
+ * than by replaying a socket.
+ *
+ * This is the platform's existing DataRealtime lane (statement-level triggers →
+ * `change_log` → the `on<Table>Changed` subscription field), not a new transport.
+ * The event table only carries it when the app declares DataRealtime on it, so
+ * the subscription is optional everywhere in this package.
+ */
+import type { RunLogNames } from './names';
+interface WsSink {
+    next(value: {
+        data?: unknown;
+        errors?: readonly {
+            message: string;
+        }[];
+    }): void;
+    error(error: unknown): void;
+    complete(): void;
+}
+/** The graphql-ws surface this package uses — supplied by the host, never imported. */
+export interface RunLogWsClient {
+    subscribe(payload: {
+        query: string;
+        variables?: Record<string, unknown>;
+    }, sink: WsSink): () => void;
+}
+/**
+ * `on<Type>Changed`, the name the platform's codegen gives a DataRealtime table's
+ * subscription field. A host that reads the field out of `_meta`
+ * (`MetaRealtime.subscriptionFieldName`) can pass it instead.
+ */
+export declare const changedSubscriptionField: (names: RunLogNames) => string;
+/**
+ * The generated subscription takes no arguments and is per-table, not per-run, so
+ * a wakeup may be for somebody else's run — harmless, because the follower's
+ * cursor read is what decides whether there is anything new for *this* one.
+ */
+export declare const changedSubscriptionDocument: (names: RunLogNames, field?: string) => string;
+export interface RealtimeWakeupOptions {
+    client: RunLogWsClient;
+    names: RunLogNames;
+    /** Override when the host resolves the field name from `_meta` instead. */
+    subscriptionField?: string;
+    /** Surfaced to the caller; a failed socket must not silently become silence. */
+    onError?: (error: Error) => void;
+}
+export interface RealtimeWakeup {
+    /** Passed to `follow` as `waitForChange`. */
+    waitForChange: (signal?: AbortSignal) => Promise<void>;
+    close: () => void;
+}
+/**
+ * One subscription, many waits: the socket stays open across follow iterations
+ * and each `waitForChange` resolves on the next notification (or immediately, if
+ * one arrived while the follower was busy reading — otherwise a change landing
+ * mid-read would leave the follower asleep until the poll timer).
+ */
+export declare function createRealtimeWakeup(options: RealtimeWakeupOptions): RealtimeWakeup;
+export {};

package/esm/realtime.js

@@ -0,0 +1,89 @@
+/**
+ * The push wakeup, when the app has one.
+ *
+ * A run surface is correct without this: `follow` polls, and every read is a
+ * cursor read, so nothing is missed by a reader that woke late. What realtime
+ * buys is latency, and it costs nothing in correctness — which is why it is a
+ * wakeup here rather than a delivery mechanism. Records are never taken from a
+ * subscription payload: the notification says *something changed*, the cursor
+ * read says *what*, so a dropped, duplicated or out-of-order notification cannot
+ * corrupt a transcript, and a reconnecting client catches up by reading rather
+ * than by replaying a socket.
+ *
+ * This is the platform's existing DataRealtime lane (statement-level triggers →
+ * `change_log` → the `on<Table>Changed` subscription field), not a new transport.
+ * The event table only carries it when the app declares DataRealtime on it, so
+ * the subscription is optional everywhere in this package.
+ */
+/**
+ * `on<Type>Changed`, the name the platform's codegen gives a DataRealtime table's
+ * subscription field. A host that reads the field out of `_meta`
+ * (`MetaRealtime.subscriptionFieldName`) can pass it instead.
+ */
+export const changedSubscriptionField = (names) => `on${names.eventType}Changed`;
+/**
+ * The generated subscription takes no arguments and is per-table, not per-run, so
+ * a wakeup may be for somebody else's run — harmless, because the follower's
+ * cursor read is what decides whether there is anything new for *this* one.
+ */
+export const changedSubscriptionDocument = (names, field = changedSubscriptionField(names)) => `
+subscription RunEventChanged {
+  ${field} {
+    event
+    ${names.event} { __typename }
+    timestamp
+  }
+}`;
+/**
+ * One subscription, many waits: the socket stays open across follow iterations
+ * and each `waitForChange` resolves on the next notification (or immediately, if
+ * one arrived while the follower was busy reading — otherwise a change landing
+ * mid-read would leave the follower asleep until the poll timer).
+ */
+export function createRealtimeWakeup(options) {
+    let pendingChange = false;
+    let wake = null;
+    let closed = false;
+    const signalChange = () => {
+        pendingChange = true;
+        const resume = wake;
+        wake = null;
+        if (resume)
+            resume();
+    };
+    const unsubscribe = options.client.subscribe({
+        query: changedSubscriptionDocument(options.names, options.subscriptionField),
+    }, {
+        next: (result) => {
+            if (result.errors && result.errors.length > 0) {
+                options.onError?.(new Error(result.errors.map((e) => e.message).join('; ')));
+                return;
+            }
+            signalChange();
+        },
+        error: (error) => {
+            options.onError?.(error instanceof Error ? error : new Error(String(error)));
+            // Wake the follower so it falls back to polling instead of waiting on a
+            // socket that is gone.
+            signalChange();
+        },
+        complete: () => signalChange(),
+    });
+    return {
+        waitForChange: (signal) => {
+            if (pendingChange || closed) {
+                pendingChange = false;
+                return Promise.resolve();
+            }
+            return new Promise((resolve) => {
+                wake = resolve;
+                signal?.addEventListener('abort', () => resolve(), { once: true });
+            });
+        },
+        close: () => {
+            closed = true;
+            unsubscribe();
+            signalChange();
+        },
+    };
+}