@agentic-kit/run-log-client 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @agentic-kit/run-log-client
+
+The run log as a browser reads it.
+
+This package provides a tenant-GraphQL `RunLogStore` over an agent run and its events.
+It also includes the follower loop shared by each run surface.
+Use it to read append-only run entries and project them into browser-facing views.
+The client works with the published `@agentic-kit/run-log` data model.
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/client.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The run log, as a browser reads and writes it.
+ *
+ * A Job writes through the worker's callback lane because it holds no tenant
+ * credential; a user's browser is the opposite case — it already authenticates
+ * as the user against the tenant API, and RLS on `agent_run`/`agent_event` is
+ * exactly the visibility rule a run surface should obey. So this store speaks
+ * the tenant's own GraphQL and implements the same `RunLogStore` contract as
+ * every other host, which is what lets one renderer draw a local run, a cloud
+ * run and a replayed run without knowing which it has.
+ */
+import { type AppendOptions, type ApprovalResolutionInput, type PiMessage, type RunEventRecord, type RunLogCursor, type RunLogPage, type RunLogStore, type TranscriptEntry, type TranscriptReaderRegistry } from '@agentic-kit/run-log';
+import { type RunLogNames } from './names';
+import type { GraphqlRequest } from './transport';
+export type RunStatus = 'pending' | 'running' | 'waiting' | 'idle' | 'succeeded' | 'failed' | 'cancelled';
+/** A run holding, or able to hold, compute. */
+export declare const ATTACHABLE_STATUSES: readonly RunStatus[];
+/** A run that will never append again. */
+export declare const TERMINAL_STATUSES: readonly RunStatus[];
+export declare const isTerminalStatus: (status: string) => boolean;
+/**
+ * The run row as a surface reads it. `executionId` is the *currently attached*
+ * execution and is null for an idle run — the attach/detach history lives in the
+ * log, so a null here means "holds no compute right now", never "never ran".
+ */
+export interface RunSummary {
+    id: string;
+    threadId: string | null;
+    /** Who invoked the run. */
+    actorId: string | null;
+    /** Who is billed for it — the actor themselves for a personal run. */
+    entityId: string | null;
+    status: string;
+    placement: string | null;
+    executionId: string | null;
+    repoUrl: string | null;
+    branch: string | null;
+    baseCommit: string | null;
+    headCommit: string | null;
+    lastEventSeq: number;
+    attempt: number | null;
+    parentRunId: string | null;
+    error: string | null;
+    artifacts: unknown;
+    deadlineAt: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    createdAt: string | null;
+}
+/**
+ * What a host chooses when it opens a run.
+ *
+ * Deliberately holds no identity: `actor_id`, `principal_id` and `entity_id`
+ * default from the claims of the transaction the tenant API opens for this
+ * request, so who the run belongs to is the authenticated session and not
+ * something a caller can name.
+ */
+export interface CreateRunInput {
+    threadId: string;
+    /**
+     * `local` for a run executed by a host on the user's machine, `cloud` for a
+     * Job. The column defaults to `cloud`, so a local host states it.
+     */
+    placement: 'cloud' | 'local';
+    status?: RunStatus;
+    repoUrl?: string;
+    branch?: string;
+}
+/** The lifecycle columns a host that owns a run moves as it runs. */
+export interface RunPatch {
+    status?: RunStatus;
+    error?: string | null;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+}
+export interface CreateThreadInput {
+    title?: string;
+    /** `agent` for a tool-enabled run, which is what a coding host opens. */
+    mode?: 'ask' | 'agent';
+}
+export interface ThreadSummary {
+    id: string;
+    title: string | null;
+    createdAt: string | null;
+}
+export interface ListRunsArgs {
+    first?: number;
+    threadId?: string;
+    status?: string;
+}
+export interface RunLogClientOptions {
+    request: GraphqlRequest;
+    /** From the module loader; defaults to the app-scope names. */
+    runTable?: string;
+    eventTable?: string;
+    threadTable?: string;
+    /**
+     * A browser has no row lock, so two writers can pick the same next `seq`;
+     * `UNIQUE (run_id, seq)` rejects the loser and it re-reads and retries. Bounded
+     * so a genuinely broken write surfaces as an error instead of spinning.
+     */
+    maxAppendAttempts?: number;
+    newId?: () => string;
+    now?: () => Date;
+    /**
+     * Readers that validate the entries this client writes and reads. Defaults to
+     * the process registry, so a host that registered a second harness's reader
+     * at startup reads that harness's runs without passing anything here.
+     */
+    readers?: TranscriptReaderRegistry;
+}
+/**
+ * A conflict on `(run_id, seq)` — the only error this store retries. Matched on
+ * the message because the tenant API reports it as a GraphQL error string; any
+ * other failure is rethrown untouched.
+ */
+export declare const isSeqConflict: (error: unknown) => boolean;
+export declare class GraphqlRunLogClient implements RunLogStore {
+    readonly names: RunLogNames;
+    /**
+     * Read by a follower so the view projects exactly the formats this client
+     * accepts — one registry decides both what a run may store and what a surface
+     * can draw.
+     */
+    readonly readers: TranscriptReaderRegistry;
+    private readonly request;
+    private readonly maxAppendAttempts;
+    private readonly newId;
+    private readonly now;
+    constructor(options: RunLogClientOptions);
+    listRuns(args?: ListRunsArgs): Promise<RunSummary[]>;
+    /**
+     * Open a thread. A cloud run is opened against a thread the web UI already
+     * created; a host on the user's machine is the first writer of its own
+     * conversation, so it creates one and then hangs its runs off it.
+     */
+    createThread(input?: CreateThreadInput): Promise<ThreadSummary>;
+    /** Open a run. See {@link CreateRunInput} on why identity is not an argument. */
+    createRun(input: CreateRunInput): Promise<RunSummary>;
+    /**
+     * Move a run's lifecycle columns. The transcript is the history; this row is
+     * the current state a list view reads without replaying it.
+     */
+    updateRun(runId: string, patch: RunPatch): Promise<RunSummary>;
+    getRun(runId: string): Promise<RunSummary>;
+    read(runId: string, cursor?: RunLogCursor, limit?: number): Promise<RunLogPage>;
+    /**
+     * Append entries, allocating `seq` from the run's cursor and advancing it.
+     *
+     * Two writers racing is normal here (a user sends a message while the Job
+     * appends a result), so the sequence is not reserved up front: each insert is
+     * attempted at the next free position and a rejected one re-reads the run.
+     * Entries already present by entry id are skipped, so a retried call is a
+     * no-op rather than a duplicated turn.
+     */
+    append(runId: string, entries: readonly TranscriptEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
+    /**
+     * Append one pi message as an entry, chained to the run's current tail.
+     *
+     * The composer's own turn is the one place this store still writes a
+     * transcript rather than relaying one, so it writes the format it declares in
+     * `insertEvent`; a second harness contributes its own message builder beside
+     * this one and appends through the neutral `append`.
+     */
+    appendMessage(runId: string, message: PiMessage, options?: AppendOptions): Promise<RunEventRecord[]>;
+    /** The user's turn: what a run surface's composer sends. */
+    prompt(runId: string, text: string): Promise<RunEventRecord[]>;
+    /**
+     * Answer a pending approval. The decision is a log entry like any other, so
+     * the Job sees it on its next cursor read and the history records who allowed
+     * what — there is no side channel to reconcile.
+     */
+    resolveApproval(runId: string, input: ApprovalResolutionInput): Promise<RunEventRecord[]>;
+    private insertEvent;
+    private advanceRun;
+    /**
+     * Skip entries a previous attempt already wrote. Only the tail is inspected —
+     * as many records as the call is trying to append — because that is where a
+     * partially applied attempt of *this* call can be, and scanning the whole run
+     * to make a retry idempotent would make every append cost the run's length.
+     */
+    private dropAlreadyWritten;
+    private tailEntryId;
+}
+export declare const createRunLogClient: (options: RunLogClientOptions) => GraphqlRunLogClient;

package/client.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * The run log, as a browser reads and writes it.
+ *
+ * A Job writes through the worker's callback lane because it holds no tenant
+ * credential; a user's browser is the opposite case — it already authenticates
+ * as the user against the tenant API, and RLS on `agent_run`/`agent_event` is
+ * exactly the visibility rule a run surface should obey. So this store speaks
+ * the tenant's own GraphQL and implements the same `RunLogStore` contract as
+ * every other host, which is what lets one renderer draw a local run, a cloud
+ * run and a replayed run without knowing which it has.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRunLogClient = exports.GraphqlRunLogClient = exports.isSeqConflict = exports.isTerminalStatus = exports.TERMINAL_STATUSES = exports.ATTACHABLE_STATUSES = void 0;
+const run_log_1 = require("@agentic-kit/run-log");
+const documents_1 = require("./documents");
+const names_1 = require("./names");
+/** A run holding, or able to hold, compute. */
+exports.ATTACHABLE_STATUSES = [
+    'pending',
+    'running',
+    'waiting',
+    'idle',
+];
+/** A run that will never append again. */
+exports.TERMINAL_STATUSES = [
+    'succeeded',
+    'failed',
+    'cancelled',
+];
+const isTerminalStatus = (status) => exports.TERMINAL_STATUSES.includes(status);
+exports.isTerminalStatus = isTerminalStatus;
+const DEFAULT_MAX_APPEND_ATTEMPTS = 5;
+const DEFAULT_READ_LIMIT = 200;
+const DEFAULT_RUN_LIMIT = 50;
+/**
+ * A conflict on `(run_id, seq)` — the only error this store retries. Matched on
+ * the message because the tenant API reports it as a GraphQL error string; any
+ * other failure is rethrown untouched.
+ */
+const isSeqConflict = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return /duplicate key|unique constraint|already exists/i.test(message);
+};
+exports.isSeqConflict = isSeqConflict;
+const entryId = (entry) => typeof entry.id === 'string' ? entry.id : undefined;
+class GraphqlRunLogClient {
+    names;
+    /**
+     * Read by a follower so the view projects exactly the formats this client
+     * accepts — one registry decides both what a run may store and what a surface
+     * can draw.
+     */
+    readers;
+    request;
+    maxAppendAttempts;
+    newId;
+    now;
+    constructor(options) {
+        this.request = options.request;
+        this.names = (0, names_1.runLogNames)(options.runTable, options.eventTable, options.threadTable);
+        this.maxAppendAttempts =
+            options.maxAppendAttempts ?? DEFAULT_MAX_APPEND_ATTEMPTS;
+        this.newId = options.newId ?? (() => globalThis.crypto.randomUUID());
+        this.now = options.now ?? (() => new Date());
+        this.readers = options.readers ?? run_log_1.transcriptReaders;
+    }
+    async listRuns(args = {}) {
+        const where = {};
+        if (args.threadId)
+            where.threadId = { equalTo: args.threadId };
+        if (args.status)
+            where.status = { equalTo: args.status };
+        const data = await this.request((0, documents_1.runsDocument)(this.names), {
+            first: args.first ?? DEFAULT_RUN_LIMIT,
+            where: Object.keys(where).length > 0 ? where : undefined,
+        });
+        return data[this.names.runs].nodes;
+    }
+    /**
+     * Open a thread. A cloud run is opened against a thread the web UI already
+     * created; a host on the user's machine is the first writer of its own
+     * conversation, so it creates one and then hangs its runs off it.
+     */
+    async createThread(input = {}) {
+        const data = await this.request((0, documents_1.createThreadDocument)(this.names), {
+            input: {
+                [this.names.thread]: {
+                    ...(input.title === undefined ? {} : { title: input.title }),
+                    mode: input.mode ?? 'agent',
+                },
+            },
+        });
+        const thread = data[this.names.createThread]?.[this.names.thread];
+        if (!thread) {
+            throw new Error(`${this.names.createThread} returned no thread; the run surface is not writable by this user`);
+        }
+        return thread;
+    }
+    /** Open a run. See {@link CreateRunInput} on why identity is not an argument. */
+    async createRun(input) {
+        const data = await this.request((0, documents_1.createRunDocument)(this.names), {
+            input: {
+                [this.names.run]: {
+                    threadId: input.threadId,
+                    placement: input.placement,
+                    ...(input.status === undefined ? {} : { status: input.status }),
+                    ...(input.repoUrl === undefined ? {} : { repoUrl: input.repoUrl }),
+                    ...(input.branch === undefined ? {} : { branch: input.branch }),
+                },
+            },
+        });
+        const run = data[this.names.createRun]?.[this.names.run];
+        if (!run) {
+            throw new Error(`${this.names.createRun} returned no run; the run surface is not writable by this user`);
+        }
+        return run;
+    }
+    /**
+     * Move a run's lifecycle columns. The transcript is the history; this row is
+     * the current state a list view reads without replaying it.
+     */
+    async updateRun(runId, patch) {
+        if (Object.keys(patch).length === 0) {
+            throw new Error(`run ${runId}: updateRun called with an empty patch`);
+        }
+        const data = await this.request((0, documents_1.advanceRunDocument)(this.names), {
+            input: { id: runId, [this.names.runPatch]: patch },
+        });
+        const run = data[this.names.updateRun]?.[this.names.run];
+        if (!run) {
+            throw new Error(`run ${runId} was not updated; it is not visible or not writable by this user`);
+        }
+        return run;
+    }
+    async getRun(runId) {
+        const data = await this.request((0, documents_1.runDocument)(this.names), { where: { id: { equalTo: runId } } });
+        const run = data[this.names.runs].nodes[0];
+        if (!run) {
+            throw new Error(`run ${runId} not found, or not visible to this user`);
+        }
+        return run;
+    }
+    async read(runId, cursor = run_log_1.START, limit) {
+        const data = await this.request((0, documents_1.eventsDocument)(this.names), {
+            first: limit ?? DEFAULT_READ_LIMIT,
+            where: {
+                runId: { equalTo: runId },
+                seq: { greaterThan: cursor.afterSeq },
+            },
+        });
+        const records = data[this.names.events].nodes.map((node) => (0, run_log_1.assertRunEventRecord)(node, this.readers));
+        return {
+            records,
+            cursor: {
+                afterSeq: records.length > 0
+                    ? records[records.length - 1].seq
+                    : cursor.afterSeq,
+            },
+        };
+    }
+    /**
+     * Append entries, allocating `seq` from the run's cursor and advancing it.
+     *
+     * Two writers racing is normal here (a user sends a message while the Job
+     * appends a result), so the sequence is not reserved up front: each insert is
+     * attempted at the next free position and a rejected one re-reads the run.
+     * Entries already present by entry id are skipped, so a retried call is a
+     * no-op rather than a duplicated turn.
+     */
+    async append(runId, entries, options) {
+        if (entries.length === 0)
+            return [];
+        const written = [];
+        let pending = [...entries];
+        for (let attempt = 0; attempt < this.maxAppendAttempts; attempt += 1) {
+            const run = await this.getRun(runId);
+            pending = await this.dropAlreadyWritten(runId, run, pending);
+            if (pending.length === 0)
+                break;
+            let seq = run.lastEventSeq;
+            try {
+                while (pending.length > 0) {
+                    seq += 1;
+                    written.push(await this.insertEvent(runId, seq, pending[0], options));
+                    pending = pending.slice(1);
+                }
+            }
+            catch (error) {
+                if (!(0, exports.isSeqConflict)(error))
+                    throw error;
+                continue;
+            }
+            await this.advanceRun(runId, seq);
+            return written;
+        }
+        if (pending.length > 0) {
+            throw new Error(`run ${runId}: could not append ${pending.length} entr${pending.length === 1 ? 'y' : 'ies'} after ${this.maxAppendAttempts} attempts — the run's sequence is contended`);
+        }
+        return written;
+    }
+    /**
+     * Append one pi message as an entry, chained to the run's current tail.
+     *
+     * The composer's own turn is the one place this store still writes a
+     * transcript rather than relaying one, so it writes the format it declares in
+     * `insertEvent`; a second harness contributes its own message builder beside
+     * this one and appends through the neutral `append`.
+     */
+    async appendMessage(runId, message, options) {
+        const parentId = await this.tailEntryId(runId);
+        const entry = {
+            id: this.newId(),
+            parentId,
+            timestamp: this.now().toISOString(),
+            type: 'message',
+            message,
+        };
+        return this.append(runId, [entry], options);
+    }
+    /** The user's turn: what a run surface's composer sends. */
+    async prompt(runId, text) {
+        if (!text.trim())
+            throw new Error('cannot append an empty prompt');
+        return this.appendMessage(runId, {
+            role: 'user',
+            content: text,
+            timestamp: this.now().getTime(),
+        });
+    }
+    /**
+     * Answer a pending approval. The decision is a log entry like any other, so
+     * the Job sees it on its next cursor read and the history records who allowed
+     * what — there is no side channel to reconcile.
+     */
+    async resolveApproval(runId, input) {
+        return this.appendMessage(runId, (0, run_log_1.approvalResolutionMessage)(input));
+    }
+    async insertEvent(runId, seq, entry, options) {
+        const data = await this.request((0, documents_1.appendDocument)(this.names), {
+            input: {
+                [this.names.event]: {
+                    runId,
+                    seq,
+                    recordedAt: options?.recordedAt ?? this.now().toISOString(),
+                    // A caller that read its entries out of a harness names that
+                    // harness's format; only the composer path below leaves it unset,
+                    // which is why the fallback is pi's.
+                    transcriptFormat: options?.transcriptFormat ?? run_log_1.PI_TRANSCRIPT_FORMAT,
+                    transcriptVersion: options?.transcriptVersion ?? run_log_1.SUPPORTED_PI_TRANSCRIPT_VERSION,
+                    entry,
+                },
+            },
+        });
+        return (0, run_log_1.assertRunEventRecord)(data[this.names.createEvent][this.names.event], this.readers);
+    }
+    async advanceRun(runId, seq) {
+        await this.request((0, documents_1.advanceRunDocument)(this.names), {
+            input: { id: runId, [this.names.runPatch]: { lastEventSeq: seq } },
+        });
+    }
+    /**
+     * Skip entries a previous attempt already wrote. Only the tail is inspected —
+     * as many records as the call is trying to append — because that is where a
+     * partially applied attempt of *this* call can be, and scanning the whole run
+     * to make a retry idempotent would make every append cost the run's length.
+     */
+    async dropAlreadyWritten(runId, run, pending) {
+        const ids = pending.map(entryId).filter((id) => !!id);
+        if (ids.length === 0 || run.lastEventSeq === 0)
+            return [...pending];
+        const window = Math.max(0, run.lastEventSeq - pending.length);
+        const page = await this.read(runId, { afterSeq: window }, pending.length);
+        const present = new Set(page.records.map((record) => entryId(record.entry)).filter(Boolean));
+        return pending.filter((entry) => {
+            const id = entryId(entry);
+            return !id || !present.has(id);
+        });
+    }
+    async tailEntryId(runId) {
+        const run = await this.getRun(runId);
+        if (run.lastEventSeq === 0)
+            return null;
+        const page = await this.read(runId, { afterSeq: run.lastEventSeq - 1 }, 1);
+        const last = page.records[page.records.length - 1];
+        return last ? (entryId(last.entry) ?? null) : null;
+    }
+}
+exports.GraphqlRunLogClient = GraphqlRunLogClient;
+const createRunLogClient = (options) => new GraphqlRunLogClient(options);
+exports.createRunLogClient = createRunLogClient;

package/documents.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 }`.
+ */
+import type { RunLogNames } from './names';
+export declare const RUN_FIELDS = "\n      id\n      threadId\n      actorId\n      entityId\n      status\n      placement\n      executionId\n      repoUrl\n      branch\n      baseCommit\n      headCommit\n      lastEventSeq\n      attempt\n      parentRunId\n      error\n      artifacts\n      deadlineAt\n      startedAt\n      finishedAt\n      createdAt";
+export declare const EVENT_FIELDS = "\n      runId\n      seq\n      recordedAt\n      transcriptFormat\n      transcriptVersion\n      entry";
+export declare const runsDocument: (names: RunLogNames) => string;
+export declare const runDocument: (names: RunLogNames) => string;
+export declare const eventsDocument: (names: RunLogNames) => string;
+export declare const appendDocument: (names: RunLogNames) => string;
+/**
+ * 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 declare const createRunDocument: (names: RunLogNames) => string;
+/**
+ * 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 declare const createThreadDocument: (names: RunLogNames) => string;
+export declare const advanceRunDocument: (names: RunLogNames) => string;