@agentic-kit/run-log-client 0.2.0

package/esm/surface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Telling "this database has no run surface" apart from "the read failed".
+ *
+ * A database whose agent module was provisioned without `has_runs` has no
+ * `agent_run`/`agent_event` at all, so the schema rejects the query outright
+ * rather than returning zero rows. That is a configuration fact about the
+ * database, not a failure of the read, and a raw GraphQL validation dump is a
+ * poor way to tell an operator so. The error is still an error — it is only
+ * classified here, never swallowed.
+ */
+import type { RunLogNames } from './names';
+/**
+ * Matched on the validation messages the tenant API returns, because the absence
+ * of the tables is only observable through the schema: the run collection is not
+ * a field and the run filter is not a type.
+ */
+export declare function isMissingRunSurface(error: unknown, names: RunLogNames): boolean;

package/esm/surface.js

@@ -0,0 +1,21 @@
+/**
+ * Telling "this database has no run surface" apart from "the read failed".
+ *
+ * A database whose agent module was provisioned without `has_runs` has no
+ * `agent_run`/`agent_event` at all, so the schema rejects the query outright
+ * rather than returning zero rows. That is a configuration fact about the
+ * database, not a failure of the read, and a raw GraphQL validation dump is a
+ * poor way to tell an operator so. The error is still an error — it is only
+ * classified here, never swallowed.
+ */
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Matched on the validation messages the tenant API returns, because the absence
+ * of the tables is only observable through the schema: the run collection is not
+ * a field and the run filter is not a type.
+ */
+export function isMissingRunSurface(error, names) {
+    const message = messageOf(error);
+    return (message.includes(`Cannot query field "${names.runs}"`) ||
+        message.includes(`Unknown type "${names.runType}Filter"`));
+}

package/esm/transport.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The GraphQL transport, kept behind one function so the store never knows how
+ * a host authenticates.
+ *
+ * The run surface lives in the tenant's own database, so this addresses the
+ * tenant API endpoint the platform UI already resolves per database, with the
+ * user's bearer token — the reader is the user, RLS decides what a run shows,
+ * and no service credential is involved anywhere in this lane.
+ */
+export type GraphqlRequest = <T>(query: string, variables?: Record<string, unknown>) => Promise<T>;
+export interface GraphqlTransportOptions {
+    endpoint: string;
+    /** Resolved per call, so a rotated token is picked up without rebuilding. */
+    headers?: () => Record<string, string>;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}
+/**
+ * A GraphQL error is thrown, never folded into an empty page: a transcript that
+ * failed to load and a run with no events look identical to a renderer, and the
+ * second is a lie a user cannot detect.
+ */
+export declare function createGraphqlRequest(options: GraphqlTransportOptions): GraphqlRequest;

package/esm/transport.js

@@ -0,0 +1,42 @@
+/**
+ * The GraphQL transport, kept behind one function so the store never knows how
+ * a host authenticates.
+ *
+ * The run surface lives in the tenant's own database, so this addresses the
+ * tenant API endpoint the platform UI already resolves per database, with the
+ * user's bearer token — the reader is the user, RLS decides what a run shows,
+ * and no service credential is involved anywhere in this lane.
+ */
+/**
+ * A GraphQL error is thrown, never folded into an empty page: a transcript that
+ * failed to load and a run with no events look identical to a renderer, and the
+ * second is a lie a user cannot detect.
+ */
+export function createGraphqlRequest(options) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    if (!doFetch) {
+        throw new Error('run-log-client needs a fetch implementation');
+    }
+    return async (query, variables) => {
+        const res = await doFetch(options.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(options.headers ? options.headers() : {}),
+            },
+            body: JSON.stringify({ query, variables: variables ?? {} }),
+            signal: options.signal,
+        });
+        if (!res.ok) {
+            throw new Error(`run log request failed: ${res.status} ${await res.text()}`);
+        }
+        const body = (await res.json());
+        if (body.errors && body.errors.length > 0) {
+            throw new Error(`run log request failed: ${body.errors.map((e) => e.message).join('; ')}`);
+        }
+        if (!body.data) {
+            throw new Error('run log request returned no data');
+        }
+        return body.data;
+    };
+}

package/esm/view.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The run view: everything a surface draws, derived from the log and nothing
+ * else.
+ *
+ * Kept as a pure reducer over records so the rendering layer holds no
+ * transcript logic of its own — the same reduction runs in a React panel, a
+ * test, or a CLI tail. Records are merged by `seq` rather than appended, which
+ * is what makes a reconnect safe: catching up re-reads a window that may overlap
+ * what is already held, and an overlapping read must be idempotent rather than
+ * duplicating turns.
+ */
+import { type Conversation, type RunEventRecord, type RunLogCursor, type RunUsage, type ToolStateProjection, type TranscriptReaderRegistry } from '@agentic-kit/run-log';
+import { type RunSummary } from './client';
+export type RunViewPhase = 'loading' | 'live' | 'terminal' | 'error';
+export interface RunView {
+    run?: RunSummary;
+    /** Records held, by ascending `seq`, without duplicates. */
+    records: RunEventRecord[];
+    cursor: RunLogCursor;
+    conversation: Conversation;
+    tools: ToolStateProjection;
+    usage: RunUsage;
+    phase: RunViewPhase;
+    /** Set when a read or a subscription failed; never hidden behind an empty view. */
+    error?: string;
+}
+/**
+ * Which transcript formats this view can read. Absent means the default
+ * registry, so a surface that only ever sees one format configures nothing;
+ * a host wired to a second harness passes its registry and the same reducers
+ * project its records.
+ */
+export interface RunViewProjection {
+    readers?: TranscriptReaderRegistry;
+}
+export declare const emptyRunView: () => RunView;
+/**
+ * Merge by `seq`: a later read of the same position replaces the earlier copy
+ * (the row is immutable, so they are the same record), and order is by position
+ * rather than arrival.
+ */
+export declare function mergeRecords(existing: readonly RunEventRecord[], incoming: readonly RunEventRecord[]): RunEventRecord[];
+export declare function applyRecords(view: RunView, incoming: readonly RunEventRecord[], projection?: RunViewProjection): RunView;
+export declare function applyRun(view: RunView, run: RunSummary, projection?: RunViewProjection): RunView;
+/**
+ * A failed read is a visible error, not an empty transcript: a surface that
+ * cannot reach the log must say so, because "no events yet" and "I could not
+ * read your events" look identical to a user otherwise.
+ */
+export declare function applyError(view: RunView, error: unknown, projection?: RunViewProjection): RunView;
+/** True while the run may still append — the only reason to keep following. */
+export declare const isFollowable: (view: RunView) => boolean;

package/esm/view.js

@@ -0,0 +1,59 @@
+/**
+ * The run view: everything a surface draws, derived from the log and nothing
+ * else.
+ *
+ * Kept as a pure reducer over records so the rendering layer holds no
+ * transcript logic of its own — the same reduction runs in a React panel, a
+ * test, or a CLI tail. Records are merged by `seq` rather than appended, which
+ * is what makes a reconnect safe: catching up re-reads a window that may overlap
+ * what is already held, and an overlapping read must be idempotent rather than
+ * duplicating turns.
+ */
+import { projectParts, projectToolState, projectUsage, START, } from '@agentic-kit/run-log';
+import { isTerminalStatus } from './client';
+const project = (records, run, phase, error, projection = {}) => ({
+    run,
+    records,
+    cursor: records.length > 0
+        ? { afterSeq: records[records.length - 1].seq }
+        : START,
+    conversation: projectParts(records, projection),
+    tools: projectToolState(records, projection),
+    usage: projectUsage(records, projection),
+    phase,
+    error,
+});
+export const emptyRunView = () => project([], undefined, 'loading');
+/**
+ * Merge by `seq`: a later read of the same position replaces the earlier copy
+ * (the row is immutable, so they are the same record), and order is by position
+ * rather than arrival.
+ */
+export function mergeRecords(existing, incoming) {
+    if (incoming.length === 0)
+        return [...existing];
+    const bySeq = new Map();
+    for (const record of existing)
+        bySeq.set(record.seq, record);
+    for (const record of incoming)
+        bySeq.set(record.seq, record);
+    return [...bySeq.values()].sort((a, b) => a.seq - b.seq);
+}
+const phaseFor = (run) => run && isTerminalStatus(run.status) ? 'terminal' : 'live';
+export function applyRecords(view, incoming, projection) {
+    const records = mergeRecords(view.records, incoming);
+    return project(records, view.run, phaseFor(view.run), view.error, projection);
+}
+export function applyRun(view, run, projection) {
+    return project(view.records, run, phaseFor(run), view.error, projection);
+}
+/**
+ * A failed read is a visible error, not an empty transcript: a surface that
+ * cannot reach the log must say so, because "no events yet" and "I could not
+ * read your events" look identical to a user otherwise.
+ */
+export function applyError(view, error, projection) {
+    return project(view.records, view.run, 'error', error instanceof Error ? error.message : String(error), projection);
+}
+/** True while the run may still append — the only reason to keep following. */
+export const isFollowable = (view) => view.phase === 'live' || view.phase === 'loading';

package/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/follow-run.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.followRun = followRun;
+const run_log_1 = require("@agentic-kit/run-log");
+const view_1 = require("./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.
+ */
+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 = (0, view_1.emptyRunView)();
+    let cursor = options.cursor ?? run_log_1.START;
+    let drainsLeft = drainReads;
+    while (!options.signal?.aborted) {
+        let batch = [];
+        try {
+            view = (0, view_1.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 (0, view_1.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 = (0, view_1.applyRecords)({ ...view, error: undefined }, batch, projection);
+        yield view;
+        if (!(0, view_1.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/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/index.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * `@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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeRecords = exports.isFollowable = exports.emptyRunView = exports.applyRun = exports.applyRecords = exports.applyError = exports.createGraphqlRequest = exports.isMissingRunSurface = exports.createRealtimeWakeup = exports.changedSubscriptionField = exports.changedSubscriptionDocument = exports.runLogNames = exports.DEFAULT_THREAD_TABLE = exports.DEFAULT_RUN_TABLE = exports.DEFAULT_EVENT_TABLE = exports.openLocalRun = exports.markLocalRunRunning = exports.markLocalRunIdle = exports.markLocalRunFailed = exports.adoptLocalRun = exports.followRun = exports.runsDocument = exports.runDocument = exports.RUN_FIELDS = exports.eventsDocument = exports.EVENT_FIELDS = exports.createThreadDocument = exports.createRunDocument = exports.appendDocument = exports.advanceRunDocument = exports.TERMINAL_STATUSES = exports.isTerminalStatus = exports.isSeqConflict = exports.GraphqlRunLogClient = exports.createRunLogClient = exports.ATTACHABLE_STATUSES = void 0;
+/**
+ * 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.
+ */
+var client_1 = require("./client");
+Object.defineProperty(exports, "ATTACHABLE_STATUSES", { enumerable: true, get: function () { return client_1.ATTACHABLE_STATUSES; } });
+Object.defineProperty(exports, "createRunLogClient", { enumerable: true, get: function () { return client_1.createRunLogClient; } });
+Object.defineProperty(exports, "GraphqlRunLogClient", { enumerable: true, get: function () { return client_1.GraphqlRunLogClient; } });
+Object.defineProperty(exports, "isSeqConflict", { enumerable: true, get: function () { return client_1.isSeqConflict; } });
+Object.defineProperty(exports, "isTerminalStatus", { enumerable: true, get: function () { return client_1.isTerminalStatus; } });
+Object.defineProperty(exports, "TERMINAL_STATUSES", { enumerable: true, get: function () { return client_1.TERMINAL_STATUSES; } });
+var documents_1 = require("./documents");
+Object.defineProperty(exports, "advanceRunDocument", { enumerable: true, get: function () { return documents_1.advanceRunDocument; } });
+Object.defineProperty(exports, "appendDocument", { enumerable: true, get: function () { return documents_1.appendDocument; } });
+Object.defineProperty(exports, "createRunDocument", { enumerable: true, get: function () { return documents_1.createRunDocument; } });
+Object.defineProperty(exports, "createThreadDocument", { enumerable: true, get: function () { return documents_1.createThreadDocument; } });
+Object.defineProperty(exports, "EVENT_FIELDS", { enumerable: true, get: function () { return documents_1.EVENT_FIELDS; } });
+Object.defineProperty(exports, "eventsDocument", { enumerable: true, get: function () { return documents_1.eventsDocument; } });
+Object.defineProperty(exports, "RUN_FIELDS", { enumerable: true, get: function () { return documents_1.RUN_FIELDS; } });
+Object.defineProperty(exports, "runDocument", { enumerable: true, get: function () { return documents_1.runDocument; } });
+Object.defineProperty(exports, "runsDocument", { enumerable: true, get: function () { return documents_1.runsDocument; } });
+var follow_run_1 = require("./follow-run");
+Object.defineProperty(exports, "followRun", { enumerable: true, get: function () { return follow_run_1.followRun; } });
+var local_run_1 = require("./local-run");
+Object.defineProperty(exports, "adoptLocalRun", { enumerable: true, get: function () { return local_run_1.adoptLocalRun; } });
+Object.defineProperty(exports, "markLocalRunFailed", { enumerable: true, get: function () { return local_run_1.markLocalRunFailed; } });
+Object.defineProperty(exports, "markLocalRunIdle", { enumerable: true, get: function () { return local_run_1.markLocalRunIdle; } });
+Object.defineProperty(exports, "markLocalRunRunning", { enumerable: true, get: function () { return local_run_1.markLocalRunRunning; } });
+Object.defineProperty(exports, "openLocalRun", { enumerable: true, get: function () { return local_run_1.openLocalRun; } });
+var names_1 = require("./names");
+Object.defineProperty(exports, "DEFAULT_EVENT_TABLE", { enumerable: true, get: function () { return names_1.DEFAULT_EVENT_TABLE; } });
+Object.defineProperty(exports, "DEFAULT_RUN_TABLE", { enumerable: true, get: function () { return names_1.DEFAULT_RUN_TABLE; } });
+Object.defineProperty(exports, "DEFAULT_THREAD_TABLE", { enumerable: true, get: function () { return names_1.DEFAULT_THREAD_TABLE; } });
+Object.defineProperty(exports, "runLogNames", { enumerable: true, get: function () { return names_1.runLogNames; } });
+var realtime_1 = require("./realtime");
+Object.defineProperty(exports, "changedSubscriptionDocument", { enumerable: true, get: function () { return realtime_1.changedSubscriptionDocument; } });
+Object.defineProperty(exports, "changedSubscriptionField", { enumerable: true, get: function () { return realtime_1.changedSubscriptionField; } });
+Object.defineProperty(exports, "createRealtimeWakeup", { enumerable: true, get: function () { return realtime_1.createRealtimeWakeup; } });
+var surface_1 = require("./surface");
+Object.defineProperty(exports, "isMissingRunSurface", { enumerable: true, get: function () { return surface_1.isMissingRunSurface; } });
+var transport_1 = require("./transport");
+Object.defineProperty(exports, "createGraphqlRequest", { enumerable: true, get: function () { return transport_1.createGraphqlRequest; } });
+var view_1 = require("./view");
+Object.defineProperty(exports, "applyError", { enumerable: true, get: function () { return view_1.applyError; } });
+Object.defineProperty(exports, "applyRecords", { enumerable: true, get: function () { return view_1.applyRecords; } });
+Object.defineProperty(exports, "applyRun", { enumerable: true, get: function () { return view_1.applyRun; } });
+Object.defineProperty(exports, "emptyRunView", { enumerable: true, get: function () { return view_1.emptyRunView; } });
+Object.defineProperty(exports, "isFollowable", { enumerable: true, get: function () { return view_1.isFollowable; } });
+Object.defineProperty(exports, "mergeRecords", { enumerable: true, get: function () { return view_1.mergeRecords; } });

package/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/local-run.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openLocalRun = openLocalRun;
+exports.adoptLocalRun = adoptLocalRun;
+exports.markLocalRunRunning = markLocalRunRunning;
+exports.markLocalRunIdle = markLocalRunIdle;
+exports.markLocalRunFailed = markLocalRunFailed;
+/**
+ * Open a durable local run: a thread if the host does not already have one, then
+ * a `pending` run marked `placement: 'local'`.
+ */
+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.
+ */
+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. */
+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.
+ */
+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. */
+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/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;