@agentic-kit/run-log-client 0.2.0

package/names.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_THREAD_TABLE = exports.DEFAULT_EVENT_TABLE = exports.DEFAULT_RUN_TABLE = void 0;
+exports.runLogNames = runLogNames;
+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`;
+};
+exports.DEFAULT_RUN_TABLE = 'agent_run';
+exports.DEFAULT_EVENT_TABLE = 'agent_event';
+exports.DEFAULT_THREAD_TABLE = 'agent_thread';
+function runLogNames(runTable = exports.DEFAULT_RUN_TABLE, eventTable = exports.DEFAULT_EVENT_TABLE, threadTable = exports.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/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@agentic-kit/run-log-client",
+  "version": "0.2.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "The run log as a browser reads it: a tenant-GraphQL RunLogStore over a module's agent_run/agent_event pair, plus the follower loop every run surface uses",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "agentic-kit",
+    "pi",
+    "coding-agent",
+    "run-log",
+    "constructive"
+  ],
+  "dependencies": {
+    "@agentic-kit/run-log": "^0.6.0"
+  },
+  "gitHead": "9bba983b38395277e0400294aaa380e586b049d4"
+}

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

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.changedSubscriptionDocument = exports.changedSubscriptionField = void 0;
+exports.createRealtimeWakeup = createRealtimeWakeup;
+/**
+ * `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.
+ */
+const changedSubscriptionField = (names) => `on${names.eventType}Changed`;
+exports.changedSubscriptionField = changedSubscriptionField;
+/**
+ * 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.
+ */
+const changedSubscriptionDocument = (names, field = (0, exports.changedSubscriptionField)(names)) => `
+subscription RunEventChanged {
+  ${field} {
+    event
+    ${names.event} { __typename }
+    timestamp
+  }
+}`;
+exports.changedSubscriptionDocument = changedSubscriptionDocument;
+/**
+ * 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).
+ */
+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: (0, exports.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();
+        },
+    };
+}

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

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMissingRunSurface = isMissingRunSurface;
+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.
+ */
+function isMissingRunSurface(error, names) {
+    const message = messageOf(error);
+    return (message.includes(`Cannot query field "${names.runs}"`) ||
+        message.includes(`Unknown type "${names.runType}Filter"`));
+}

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

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGraphqlRequest = createGraphqlRequest;
+/**
+ * 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.
+ */
+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/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/view.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFollowable = exports.emptyRunView = void 0;
+exports.mergeRecords = mergeRecords;
+exports.applyRecords = applyRecords;
+exports.applyRun = applyRun;
+exports.applyError = applyError;
+const run_log_1 = require("@agentic-kit/run-log");
+const client_1 = require("./client");
+const project = (records, run, phase, error, projection = {}) => ({
+    run,
+    records,
+    cursor: records.length > 0
+        ? { afterSeq: records[records.length - 1].seq }
+        : run_log_1.START,
+    conversation: (0, run_log_1.projectParts)(records, projection),
+    tools: (0, run_log_1.projectToolState)(records, projection),
+    usage: (0, run_log_1.projectUsage)(records, projection),
+    phase,
+    error,
+});
+const emptyRunView = () => project([], undefined, 'loading');
+exports.emptyRunView = emptyRunView;
+/**
+ * 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.
+ */
+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 && (0, client_1.isTerminalStatus)(run.status) ? 'terminal' : 'live';
+function applyRecords(view, incoming, projection) {
+    const records = mergeRecords(view.records, incoming);
+    return project(records, view.run, phaseFor(view.run), view.error, projection);
+}
+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.
+ */
+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. */
+const isFollowable = (view) => view.phase === 'live' || view.phase === 'loading';
+exports.isFollowable = isFollowable;