@re-cinq/floor-client 0.1.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 re:cinq B.V.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,59 @@
+# @re-cinq/floor-client
+
+The floor over HTTP and its live socket, typed. Every route a floor serves, and a watch that replays a run from a cursor and comes back without losing a frame.
+
+```ts
+import { createFloorClient, serviceToken } from "@re-cinq/floor-client";
+
+const floor = createFloorClient({ url: "https://floor.example.com", token: serviceToken(process.env.FLOOR_SERVICE_TOKEN!) });
+
+const { run } = await floor.lines.start("code-review", {
+  repo: "github.com/re-cinq/lore",
+  startItems: { pr_url: { kind: "value", ref: "https://github.com/re-cinq/lore/pull/412", by: "me" } },
+});
+
+for await (const frame of floor.runs.watch(run.id)) {
+  if (frame.type === "run_settled") break;
+}
+```
+
+## Where this fits
+
+The one way anything reaches a floor from outside it. [`apps/cluster-agent`](../../apps/cluster-agent/README.md), [`@re-cinq/floor-station`](../station/README.md), [`@re-cinq/floor-pipeline`](../pipeline/README.md) and the lore converter all talk to a floor through this, and so does lore. It links no part of the floor's own storage — only [`@re-cinq/floor-contracts`](../contracts/README.md), for the shapes — so a floor's database is not reachable through it even by accident.
+
+See [the map](../../README.md).
+
+## What it decides for you
+
+**Two tokens, and neither fits where the other belongs.** `ServiceToken` and `VisitToken` are branded, so one cannot be passed for the other. `createVisitClient` goes further: it binds the visit id at construction and takes one in no method, so addressing *another* visit is not something a caller can express. The floor refuses that with a 403; this refuses it at the compiler. The same client has no `events.post` — it has `report()`, which fills in the event's name, its visit and its dedupe key, because none of those are the caller's to choose.
+
+**A status that carries meaning is in the return type, not an exception.** Absence is `null`, an empty queue is `[]`, and where a refusal is a real decision it is a named union:
+
+```ts
+const outcome = await floor.stationRuns.brief(visitId);
+
+if (outcome.kind === "reported") return ack(event);      // 409: already done, run nothing
+if (outcome.kind === "absent") return deadLetter(event); // 404: asking again will never find it
+```
+
+That one matters: before this package, a station read both as `null` and could not tell them apart, while the cluster agent threw on both and retried a settled visit until the event died.
+
+Everything else a floor refuses throws a `FloorProblem` carrying the RFC 9457 body — `status`, `title`, `detail`, and the per-field `errors` a 400 lists.
+
+**A filter the floor would 400 on does not compile.** `runs.list`, `events.feed` and `costs.summary` each need at least one filter, and the types say so.
+
+**No runtime validation.** The client casts, in one place. The rule, which the floor already followed and never wrote down: validate across a trust boundary you do not own — `apps/api` validates what a git credential provider answers, because that is somebody else's service — and annotate across one you do. The floor's own handlers are annotated with these same types, so drift is a compile error on the server rather than a throw in someone else's pod.
+
+## The live socket
+
+`runs.watch(runId, options)` is an async iterable. It replays the run's journal from `after`, emits `caught_up`, then follows it live.
+
+**It comes back for you.** The protocol was built for it — every frame but `unsupported` carries the `seq` to return with — so a watch reopens from the last seq it handed out, and misses nothing. It does not come back from a refusal: a bad cursor, a missing token, no such run, or too many viewers. That last one is deliberate. Sixteen viewers is a capacity signal, and a client that retried it invisibly would turn pressure on a busy run into a hidden hammer loop.
+
+There is no idle timeout here on purpose. A caught-up quiet run legitimately says nothing for minutes; the floor's own ping already finds a dead viewer, and a client-side timer would only reconnect healthy watches.
+
+One caveat for a relay: `visit_opened` and `visit_reported` carry the whole visit, `agentSettings` included — the model, the prompt, the image. Filter those before they reach a browser.
+
+## Testing against it
+
+Both seams are injectable and neither needs a server: `fetchFn` for HTTP, `socketFn` for the live socket. With `backoffMs: () => 0`, the whole reconnect table is unit-testable in milliseconds — see `live.test.ts`.

package/dist/blobs.d.ts

@@ -0,0 +1,19 @@
+import type { BlobRef } from "@re-cinq/floor-contracts";
+import { type Reachable } from "./send.js";
+export interface StoredBytes {
+    bytes: Uint8Array;
+    contentType: string;
+}
+export interface BlobsApi {
+    get(hash: string): Promise<StoredBytes | null>;
+    put(bytes: Uint8Array, contentType?: string): Promise<BlobRef>;
+    /** A file need names an absolute url a pod can reach; a worker elsewhere reads the path off it and asks its own floor. */
+    atUrl(url: string): Promise<StoredBytes | null>;
+}
+export declare function blobsApi(floor: Reachable): BlobsApi;
+export interface ConversationApi {
+    /** The archive the named visit saved, for the one visit opened to continue it. */
+    restore(savedBy: string): Promise<Uint8Array | null>;
+    save(visitId: string, archive: Uint8Array): Promise<BlobRef>;
+}
+export declare function conversationApi(floor: Reachable): ConversationApi;

package/dist/blobs.js

@@ -0,0 +1,18 @@
+import { asked, askedForBytes } from "./send.js";
+const HTTP_NOT_FOUND = 404;
+const OCTET_STREAM = "application/octet-stream";
+const GZIP = "application/gzip";
+export function blobsApi(floor) {
+    return {
+        get: (hash) => askedForBytes(floor, { method: "GET", path: `/blobs/${hash}` }, [HTTP_NOT_FOUND]),
+        put: async (bytes, contentType) => (await asked(floor, { method: "POST", path: "/blobs", bytes: { content: bytes, contentType: contentType ?? OCTET_STREAM } })),
+        atUrl: (url) => askedForBytes(floor, { method: "GET", path: new URL(url).pathname }, [HTTP_NOT_FOUND]),
+    };
+}
+export function conversationApi(floor) {
+    return {
+        restore: async (savedBy) => (await askedForBytes(floor, { method: "GET", path: `/conversations/${savedBy}` }, [HTTP_NOT_FOUND]))?.bytes ?? null,
+        save: async (visitId, archive) => (await asked(floor, { method: "POST", path: `/conversations/${visitId}`, bytes: { content: archive, contentType: GZIP } })),
+    };
+}
+//# sourceMappingURL=blobs.js.map

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+import type { AgentDefinitionBody, LineBody, MigrationBody, PutResult, ScheduleBody, StationBody, DefinitionRowView, FloorEventView } from "@re-cinq/floor-contracts";
+import { type BlobsApi, type ConversationApi } from "./blobs.js";
+import { type DefinitionApi } from "./definitions.js";
+import { type EventsApi } from "./events.js";
+import { type CostsRowsApi, type RunsApi, type StartRun, type StartedRun } from "./runs.js";
+import { type StationRunsApi } from "./station-runs.js";
+import type { SocketFn } from "./live.js";
+import type { ServiceToken } from "./tokens.js";
+export interface FloorAccess {
+    url: string;
+    token: ServiceToken;
+    /** The seam a test injects for HTTP. */
+    fetchFn?: typeof fetch;
+    /** The seam a test injects for the live socket. */
+    socketFn?: SocketFn;
+    timeoutMs?: number;
+}
+export interface LinesApi extends DefinitionApi<LineBody> {
+    /** Answers the run already open on this subject, joined, rather than opening a second one. */
+    start(lineId: string, starting: StartRun): Promise<StartedRun>;
+}
+export interface SchedulesApi extends DefinitionApi<ScheduleBody> {
+    /** Posts this schedule's event now, without waiting for its cron. */
+    trigger(id: string): Promise<FloorEventView | null>;
+}
+export interface MigrationsApi {
+    list(): Promise<DefinitionRowView<MigrationBody>[]>;
+    get(name: string): Promise<DefinitionRowView<MigrationBody> | null>;
+    /** Refused with a 409 when that name already ran with different content. */
+    put(name: string, sha256: string): Promise<PutResult>;
+}
+export interface Version {
+    sha: string;
+    schemaVersion: number;
+    /** Every replica serves; only the one holding the floor's lease runs its loop. */
+    runsLoop: boolean;
+}
+export interface HealthApi {
+    live(): Promise<boolean>;
+    ready(): Promise<boolean>;
+    version(): Promise<Version>;
+}
+export interface FloorClient {
+    readonly health: HealthApi;
+    readonly lines: LinesApi;
+    readonly stations: DefinitionApi<StationBody>;
+    readonly agentDefinitions: DefinitionApi<AgentDefinitionBody>;
+    readonly schedules: SchedulesApi;
+    readonly migrations: MigrationsApi;
+    readonly runs: RunsApi;
+    readonly stationRuns: StationRunsApi;
+    readonly events: EventsApi;
+    readonly blobs: BlobsApi;
+    readonly conversations: ConversationApi;
+    readonly costs: CostsRowsApi;
+}
+export declare function createFloorClient(access: FloorAccess): FloorClient;

package/dist/client.js

@@ -0,0 +1,52 @@
+import { blobsApi, conversationApi } from "./blobs.js";
+import { definitionApi } from "./definitions.js";
+import { eventsApi } from "./events.js";
+import { costsApi, runsApi } from "./runs.js";
+import { asked, reach } from "./send.js";
+import { stationRunsApi } from "./station-runs.js";
+const HTTP_NOT_FOUND = 404;
+export function createFloorClient(access) {
+    const floor = { ...reach(access.url, access.token, { fetchFn: access.fetchFn, timeoutMs: access.timeoutMs }), socketFn: access.socketFn };
+    return {
+        health: healthApi(floor),
+        lines: { ...definitionApi(floor, "assembly-lines"), start: (lineId, starting) => startRun(floor, lineId, starting) },
+        stations: definitionApi(floor, "stations"),
+        agentDefinitions: definitionApi(floor, "agent-definitions"),
+        schedules: { ...definitionApi(floor, "schedules"), trigger: (id) => asked(floor, { method: "POST", path: `/schedules/${id}/trigger` }, [HTTP_NOT_FOUND]) },
+        migrations: migrationsApi(floor),
+        runs: runsApi(floor),
+        stationRuns: stationRunsApi(floor),
+        events: eventsApi(floor),
+        blobs: blobsApi(floor),
+        conversations: conversationApi(floor),
+        costs: costsApi(floor),
+    };
+}
+async function startRun(floor, lineId, starting) {
+    return (await asked(floor, { method: "POST", path: `/assembly-lines/${lineId}/start`, body: starting }));
+}
+function migrationsApi(floor) {
+    const rows = definitionApi(floor, "migrations");
+    return {
+        list: () => rows.list(),
+        get: (name) => rows.get(name),
+        put: (name, sha256) => rows.put(name, { sha256 }),
+    };
+}
+// Health is unauthenticated, so a probe answers rather than throwing when the floor is not up yet.
+function healthApi(floor) {
+    const answers = async (path) => {
+        try {
+            return (await asked(floor, { method: "GET", path })) !== null;
+        }
+        catch {
+            return false;
+        }
+    };
+    return {
+        live: () => answers("/healthz"),
+        ready: () => answers("/readyz"),
+        version: async () => (await asked(floor, { method: "GET", path: "/version" })),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/definitions.d.ts

@@ -0,0 +1,13 @@
+import type { DefinitionRowView, PutResult } from "@re-cinq/floor-contracts";
+import { type Reachable } from "./send.js";
+export interface DefinitionApi<Body> {
+    list(name?: string): Promise<DefinitionRowView<Body>[]>;
+    /** Null when nothing of that id is there, or it was archived. */
+    get(id: string): Promise<DefinitionRowView<Body> | null>;
+    versions(id: string): Promise<DefinitionRowView<Body>[]>;
+    version(id: string, hash: string): Promise<DefinitionRowView<Body> | null>;
+    /** A version is its content: putting the same body twice answers the same hash, created false the second time. */
+    put(id: string, body: Body): Promise<PutResult>;
+    archive(id: string): Promise<void>;
+}
+export declare function definitionApi<Body>(floor: Reachable, base: string): DefinitionApi<Body>;

package/dist/definitions.js

@@ -0,0 +1,19 @@
+import { asked, done } from "./send.js";
+const HTTP_NOT_FOUND = 404;
+export function definitionApi(floor, base) {
+    const rows = async (path, query) => {
+        const page = await asked(floor, { method: "GET", path, query });
+        return page?.items ?? [];
+    };
+    return {
+        list: (name) => rows(`/${base}`, { name }),
+        get: (id) => asked(floor, { method: "GET", path: `/${base}/${id}` }, [HTTP_NOT_FOUND]),
+        versions: (id) => rows(`/${base}/${id}/versions`),
+        version: (id, hash) => asked(floor, { method: "GET", path: `/${base}/${id}/versions/${hash}` }, [HTTP_NOT_FOUND]),
+        put: async (id, body) => (await asked(floor, { method: "PUT", path: `/${base}/${id}`, body })),
+        archive: async (id) => {
+            await done(floor, { method: "DELETE", path: `/${base}/${id}` });
+        },
+    };
+}
+//# sourceMappingURL=definitions.js.map

package/dist/events.d.ts

@@ -0,0 +1,33 @@
+import type { ClaimedEvent, FloorEventView } from "@re-cinq/floor-contracts";
+import type { EventFilter } from "./filters.js";
+import { type Reachable } from "./send.js";
+export interface EnqueueEvent {
+    name: string;
+    payload: Record<string, unknown>;
+    /** The same key twice is the same event: a redelivered webhook enqueues once. */
+    dedupeKey?: string;
+    availableAt?: Date;
+    runId?: string;
+}
+export interface EventsPage {
+    items: FloorEventView[];
+    nextCursor: string | null;
+}
+export interface EventsApi {
+    feed(filter: EventFilter, page?: {
+        limit?: number;
+    }): Promise<EventsPage>;
+    get(eventId: string): Promise<FloorEventView | null>;
+    post(event: EnqueueEvent): Promise<FloorEventView>;
+    /** Empty when nothing matching the tags is waiting. */
+    claim(claiming: {
+        tags: string[];
+        limit: number;
+    }): Promise<ClaimedEvent[]>;
+    ack(eventId: string): Promise<void>;
+    /** Back on the queue after a backoff, and dead-lettered once it has been tried too often. */
+    fail(eventId: string, error: string): Promise<void>;
+    /** Straight to the dead letters: trying again would never help. */
+    deadLetter(eventId: string, error: string): Promise<void>;
+}
+export declare function eventsApi(floor: Reachable): EventsApi;

package/dist/events.js

@@ -0,0 +1,19 @@
+import { asked, done } from "./send.js";
+const HTTP_NOT_FOUND = 404;
+export function eventsApi(floor) {
+    const refused = async (eventId, body) => {
+        await done(floor, { method: "POST", path: `/events/${eventId}/fail`, body });
+    };
+    return {
+        feed: async (filter, page) => (await asked(floor, { method: "GET", path: "/events", query: { ...filter, ...page } })),
+        get: (eventId) => asked(floor, { method: "GET", path: `/events/${eventId}` }, [HTTP_NOT_FOUND]),
+        post: async (event) => (await asked(floor, { method: "POST", path: "/events", body: { ...event, availableAt: event.availableAt?.toISOString() } })),
+        claim: async (claiming) => (await asked(floor, { method: "POST", path: "/events/claim", body: claiming })) ?? [],
+        ack: async (eventId) => {
+            await done(floor, { method: "POST", path: `/events/${eventId}/ack` });
+        },
+        fail: (eventId, error) => refused(eventId, { error, permanent: false }),
+        deadLetter: (eventId, error) => refused(eventId, { error, permanent: true }),
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/filters.d.ts

@@ -0,0 +1,25 @@
+/** At least one of these, and any of the rest beside it. */
+export type OneOf<Fields> = {
+    [Named in keyof Fields]-?: Required<Pick<Fields, Named>> & Partial<Omit<Fields, Named>>;
+}[keyof Fields];
+export type RunFilter = OneOf<{
+    line: string;
+    repo: string;
+    subject: string;
+    open: boolean;
+}>;
+export type EventFilter = OneOf<{
+    since: string;
+    name: string;
+    run: string;
+    stationRun: string;
+}>;
+export type CostsFilter = OneOf<{
+    run: string;
+    repo: string;
+    line: string;
+    station: string;
+    since: string;
+    until: string;
+}>;
+export type CostsGroupBy = "day" | "line" | "station" | "model" | "run";

package/dist/filters.js

@@ -0,0 +1,3 @@
+// Three routes refuse a request that narrows nothing. OneOf makes that a compile error rather than a 400.
+export {};
+//# sourceMappingURL=filters.js.map

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { createFloorClient } from "./client.js";
+export { createVisitClient } from "./visit.js";
+export { serviceToken, visitToken } from "./tokens.js";
+export { FloorProblem, isFloorProblem } from "./problem.js";
+export { reach, asked, send } from "./send.js";
+export { CLOSE, watchRun } from "./live.js";
+export type { FloorAccess, FloorClient, HealthApi, LinesApi, MigrationsApi, SchedulesApi, Version } from "./client.js";
+export type { AppendRecord, GitCredentialOutcome, VisitAccess, VisitClient } from "./visit.js";
+export type { ServiceToken, VisitToken } from "./tokens.js";
+export type { Asking, Reachable } from "./send.js";
+export type { BlobsApi, ConversationApi, StoredBytes } from "./blobs.js";
+export type { DefinitionApi } from "./definitions.js";
+export type { EnqueueEvent, EventsApi, EventsPage } from "./events.js";
+export type { CostsFilter, CostsGroupBy, EventFilter, OneOf, RunFilter } from "./filters.js";
+export type { CostsRowsApi, RunPage, RunsApi, StartRun, StartedRun } from "./runs.js";
+export type { BriefOutcome, RecordsPage, StationRunsApi } from "./station-runs.js";
+export type { LiveSocket, RefusalCode, RunWatch, SocketFn, WatchEnd, WatchOptions } from "./live.js";
+export type * from "@re-cinq/floor-contracts";

package/dist/index.js

@@ -0,0 +1,8 @@
+// The floor, typed. One client for a service, one for a single visit, and a watch over the live socket.
+export { createFloorClient } from "./client.js";
+export { createVisitClient } from "./visit.js";
+export { serviceToken, visitToken } from "./tokens.js";
+export { FloorProblem, isFloorProblem } from "./problem.js";
+export { reach, asked, send } from "./send.js";
+export { CLOSE, watchRun } from "./live.js";
+//# sourceMappingURL=index.js.map

package/dist/live.d.ts

@@ -0,0 +1,57 @@
+import type { LiveFrame } from "@re-cinq/floor-contracts";
+import type { Reachable } from "./send.js";
+/** The floor terminates a viewer it cannot reach, and a dropped connection reports the same code. */
+export declare const CLOSE: {
+    readonly settled: 1000;
+    readonly stopping: 1001;
+    readonly dropped: 1006;
+    readonly unreadable: 1011;
+    readonly badCursor: 4400;
+    readonly noServiceToken: 4401;
+    readonly noSuchRun: 4404;
+    readonly tooManyViewers: 4429;
+};
+declare const REFUSALS: readonly [4400, 4401, 4404, 4429];
+export type RefusalCode = (typeof REFUSALS)[number];
+export type WatchEnd = {
+    reason: "settled";
+} | {
+    reason: "stopped";
+} | {
+    reason: "refused";
+    code: RefusalCode;
+    detail: string;
+};
+export interface Closed {
+    code: number;
+    reason: string;
+}
+/** The seam, in this package's own shape rather than the browser's: a test drives it with no server and no port. */
+export interface LiveSocket {
+    onFrame(heard: (frame: string) => void): void;
+    onClosed(heard: (closed: Closed) => void): void;
+    close(code?: number, reason?: string): void;
+}
+export type SocketFn = (url: string, init: {
+    headers: Record<string, string>;
+}) => LiveSocket;
+export type LiveReachable = Reachable & {
+    socketFn?: SocketFn;
+};
+export interface WatchOptions {
+    /** The last seq already seen. Left out, the run is replayed from its start. */
+    after?: number;
+    /** False leaves every close to the caller. */
+    reconnect?: boolean;
+    /** Attempt to delay. Return 0 in a test. */
+    backoffMs?: (attempt: number) => number;
+    signal?: AbortSignal;
+}
+export interface RunWatch extends AsyncIterable<LiveFrame> {
+    /** The last seq handed out. Give it to the next watch and lose nothing. */
+    readonly seq: number;
+    readonly ended: Promise<WatchEnd>;
+    stop(): void;
+}
+export declare function watchRun(floor: LiveReachable, runId: string, options?: WatchOptions): RunWatch;
+export {};

package/dist/live.js

@@ -0,0 +1,164 @@
+/** The floor terminates a viewer it cannot reach, and a dropped connection reports the same code. */
+export const CLOSE = { settled: 1000, stopping: 1001, dropped: 1006, unreadable: 1011, badCursor: 4400, noServiceToken: 4401, noSuchRun: 4404, tooManyViewers: 4429 };
+const REFUSALS = [CLOSE.badCursor, CLOSE.noServiceToken, CLOSE.noSuchRun, CLOSE.tooManyViewers];
+const BACKOFF_START_MS = 250;
+const BACKOFF_CAP_MS = 10_000;
+export function watchRun(floor, runId, options = {}) {
+    const watch = openWatch(cursorOf(options.after));
+    options.signal?.addEventListener("abort", () => watch.stop());
+    void follow({ floor, runId, options, watch });
+    return watch;
+}
+function openWatch(from) {
+    const journal = journalFrom(from);
+    const socket = { current: null };
+    const reading = journal.reading;
+    return {
+        get seq() {
+            return reading.seq;
+        },
+        waiting: reading.waiting,
+        ended: reading.ended,
+        endedYet: reading.endedYet,
+        settle: reading.settle,
+        take: reading.take,
+        socket,
+        stop: () => {
+            socket.current?.close(CLOSE.settled, "the watcher stopped");
+            reading.settle({ reason: "stopped" });
+        },
+        [Symbol.asyncIterator]: () => reading[Symbol.asyncIterator](),
+    };
+}
+/** What has arrived and not yet been handed out, the cursor it moved, and whether the watch is over. */
+function journalFrom(from) {
+    const held = { seq: from, end: null };
+    const waiting = [];
+    const { sleep, wake } = sleeper();
+    const { ended, finish } = promised();
+    const settle = (end) => {
+        if (held.end)
+            return;
+        held.end = end;
+        finish(end);
+        wake();
+    };
+    return {
+        reading: {
+            get seq() {
+                return held.seq;
+            },
+            waiting,
+            ended,
+            endedYet: () => held.end,
+            settle,
+            take: (frame) => {
+                if (frame.type !== "unsupported")
+                    held.seq = frame.seq;
+                waiting.push(frame);
+                wake();
+            },
+            [Symbol.asyncIterator]: () => handOut(waiting, { endedYet: () => held.end, sleep }),
+        },
+    };
+}
+/** A reader waiting on the next frame, woken when one arrives or when the watch is over. */
+function sleeper() {
+    let waking = null;
+    return {
+        sleep: () => new Promise((resolve) => {
+            waking = resolve;
+        }),
+        wake: () => {
+            const woken = waking;
+            waking = null;
+            woken?.();
+        },
+    };
+}
+function promised() {
+    let finish;
+    const ended = new Promise((resolve) => {
+        finish = resolve;
+    });
+    return { ended, finish };
+}
+function handOut(waiting, watch) {
+    return {
+        async next() {
+            while (waiting.length === 0) {
+                if (watch.endedYet())
+                    return { value: undefined, done: true };
+                await watch.sleep();
+            }
+            return { value: waiting.shift(), done: false };
+        },
+    };
+}
+async function follow(following) {
+    const { options, watch } = following;
+    let attempt = 0;
+    while (!watch.endedYet()) {
+        const closed = await connected(following);
+        const end = endFor(closed, options);
+        if (watch.endedYet())
+            return;
+        if (end)
+            return watch.settle(end);
+        await new Promise((resolve) => setTimeout(resolve, delayFor(attempt, options.backoffMs)));
+        attempt += 1;
+    }
+}
+// Settled is the end; a refusal will be refused again; anything else is worth coming back from.
+function endFor(closed, options) {
+    if (closed.code === CLOSE.settled)
+        return { reason: "settled" };
+    if (refused(closed.code))
+        return { reason: "refused", code: closed.code, detail: closed.reason };
+    return options.reconnect === false ? { reason: "stopped" } : null;
+}
+function connected(following) {
+    const { floor, watch } = following;
+    const open = floor.socketFn ?? defaultSocket;
+    const socket = open(liveUrl(floor.url, following.runId, watch.seq), { headers: { authorization: `Bearer ${floor.token}` } });
+    watch.socket.current = socket;
+    return new Promise((resolve) => {
+        socket.onFrame((said) => {
+            const frame = frameOf(said);
+            if (frame)
+                watch.take(frame);
+        });
+        socket.onClosed(resolve);
+    });
+}
+function refused(code) {
+    return REFUSALS.includes(code);
+}
+// A whole number is what the floor accepts; anything else spends a connection to be told 4400.
+function cursorOf(after) {
+    return Math.max(0, Math.trunc(after ?? 0));
+}
+function delayFor(attempt, backoffMs) {
+    return backoffMs ? backoffMs(attempt) : Math.min(BACKOFF_CAP_MS, BACKOFF_START_MS * 2 ** attempt);
+}
+function liveUrl(base, runId, after) {
+    return `${base.replace(/^http/, "ws")}/assembly-runs/${runId}/live?after=${after}`;
+}
+function frameOf(said) {
+    try {
+        return JSON.parse(said);
+    }
+    catch {
+        return null;
+    }
+}
+// Node 22's global WebSocket takes headers through undici's options bag, which is the only way the floor sees the token: it reads the upgrade's authorization header and has no query fallback.
+function defaultSocket(url, init) {
+    const socket = new WebSocket(url, init);
+    return {
+        onFrame: (heard) => socket.addEventListener("message", (said) => heard(String(said.data))),
+        onClosed: (heard) => socket.addEventListener("close", (closed) => heard({ code: closed.code, reason: closed.reason })),
+        close: (code, reason) => socket.close(code, reason),
+    };
+}
+//# sourceMappingURL=live.js.map

package/dist/problem.d.ts

@@ -0,0 +1,17 @@
+import type { Problem } from "@re-cinq/floor-contracts";
+export declare class FloorProblem extends Error implements Problem {
+    readonly type: string;
+    readonly title: string;
+    readonly status: number;
+    readonly detail?: string;
+    /** What a 400 lists when a body failed to parse, one sentence a field. */
+    readonly errors?: string[];
+    readonly method: string;
+    readonly path: string;
+    constructor(problem: Problem, asked: {
+        method: string;
+        path: string;
+    });
+}
+export declare function isFloorProblem(error: unknown): error is FloorProblem;
+export declare function problemOf(response: Response): Promise<Problem>;

package/dist/problem.js

@@ -0,0 +1,42 @@
+const PROBLEM_TYPE = "application/problem+json";
+export class FloorProblem extends Error {
+    type;
+    title;
+    status;
+    detail;
+    /** What a 400 lists when a body failed to parse, one sentence a field. */
+    errors;
+    method;
+    path;
+    constructor(problem, asked) {
+        super(`the floor refused ${asked.method} ${asked.path} with ${problem.status}: ${problem.detail ?? problem.title}`);
+        this.name = "FloorProblem";
+        this.type = problem.type;
+        this.title = problem.title;
+        this.status = problem.status;
+        this.detail = problem.detail;
+        this.errors = problem.errors;
+        this.method = asked.method;
+        this.path = asked.path;
+    }
+}
+export function isFloorProblem(error) {
+    return error instanceof FloorProblem;
+}
+export async function problemOf(response) {
+    const said = await response.text().catch(() => "");
+    return statedIn(response, said) ?? { type: "about:blank", title: response.statusText || "the floor refused", status: response.status, detail: said || undefined };
+}
+function statedIn(response, said) {
+    const contentType = response.headers.get("content-type") ?? "";
+    return contentType.startsWith(PROBLEM_TYPE) ? parsed(said) : null;
+}
+function parsed(said) {
+    try {
+        return JSON.parse(said);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=problem.js.map

package/dist/runs.d.ts

@@ -0,0 +1,37 @@
+import type { CostsRow, Item, RunView } from "@re-cinq/floor-contracts";
+import type { CostsFilter, CostsGroupBy, RunFilter } from "./filters.js";
+import { type Reachable } from "./send.js";
+import { type RunWatch, type WatchOptions } from "./live.js";
+export interface StartRun {
+    repo: string;
+    startItems: Record<string, Item>;
+    /** Starts somewhere other than the line's entry; the node must exist. */
+    entry?: string;
+}
+export interface StartedRun {
+    run: RunView;
+    /** True when a run was already open on this subject and this start joined it rather than opening a second. */
+    joined: boolean;
+}
+export interface RunPage {
+    items: RunView[];
+    nextCursor: string | null;
+}
+export interface RunsApi {
+    list(filter: RunFilter, page?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<RunPage>;
+    get(runId: string): Promise<{
+        run: RunView;
+        bag: Record<string, Item>;
+    } | null>;
+    cancel(runId: string, reason: string): Promise<RunView>;
+    /** Replays the run from `after`, then follows it live. Reconnects from the last seq it handed out. */
+    watch(runId: string, options?: WatchOptions): RunWatch;
+}
+export declare function runsApi(floor: Reachable): RunsApi;
+export interface CostsRowsApi {
+    summary(filter: CostsFilter, group: CostsGroupBy): Promise<CostsRow[]>;
+}
+export declare function costsApi(floor: Reachable): CostsRowsApi;

package/dist/runs.js

@@ -0,0 +1,20 @@
+import { asked } from "./send.js";
+import { watchRun } from "./live.js";
+const HTTP_NOT_FOUND = 404;
+export function runsApi(floor) {
+    return {
+        list: async (filter, page) => (await asked(floor, { method: "GET", path: "/assembly-runs", query: { ...filter, ...page } })),
+        get: (runId) => asked(floor, { method: "GET", path: `/assembly-runs/${runId}` }, [HTTP_NOT_FOUND]),
+        cancel: async (runId, reason) => (await asked(floor, { method: "POST", path: `/assembly-runs/${runId}/cancel`, body: { reason } })),
+        watch: (runId, options) => watchRun(floor, runId, options),
+    };
+}
+export function costsApi(floor) {
+    return {
+        summary: async (filter, group) => {
+            const page = await asked(floor, { method: "GET", path: "/costs", query: { ...filter, group } });
+            return page?.items ?? [];
+        },
+    };
+}
+//# sourceMappingURL=runs.js.map

package/dist/send.d.ts

@@ -0,0 +1,30 @@
+import type { ServiceToken, VisitToken } from "./tokens.js";
+export interface Reachable {
+    /** Where the floor answers. A trailing slash is trimmed, so either spelling works. */
+    url: string;
+    token: ServiceToken | VisitToken;
+    /** The seam a test injects. Left out, the global fetch is used. */
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface Asking {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** Bytes instead of JSON, with the type they are stored under. */
+    bytes?: {
+        content: Uint8Array;
+        contentType: string;
+    };
+}
+export declare function reach(url: string, token: ServiceToken | VisitToken, options?: Omit<Reachable, "url" | "token">): Reachable;
+export declare function send(floor: Reachable, asking: Asking): Promise<Response>;
+/** The answer, or null for a status this caller reads as absence. Anything else the floor refused throws a FloorProblem. */
+export declare function asked<Answer>(floor: Reachable, asking: Asking, absent?: number[]): Promise<Answer | null>;
+export declare function askedForBytes(floor: Reachable, asking: Asking, absent?: number[]): Promise<{
+    bytes: Uint8Array;
+    contentType: string;
+} | null>;
+/** Nothing to read: the floor either did it or refused. */
+export declare function done(floor: Reachable, asking: Asking, absent?: number[]): Promise<boolean>;

package/dist/send.js

@@ -0,0 +1,66 @@
+// The one place this package calls a floor. Everything else asks through here, so the bearer header, the timeout and the refusal are written once.
+import { FloorProblem, problemOf } from "./problem.js";
+const REQUEST_TIMEOUT_MS = 30_000;
+const HTTP_NO_CONTENT = 204;
+export function reach(url, token, options = {}) {
+    return { url: url.replace(/\/+$/, ""), token, ...options };
+}
+export async function send(floor, asking) {
+    const call = floor.fetchFn ?? fetch;
+    return call(`${floor.url}${asking.path}${queryOf(asking.query)}`, {
+        method: asking.method,
+        headers: headersFor(floor, asking),
+        body: bodyOf(asking),
+        signal: AbortSignal.timeout(floor.timeoutMs ?? REQUEST_TIMEOUT_MS),
+    });
+}
+/** The answer, or null for a status this caller reads as absence. Anything else the floor refused throws a FloorProblem. */
+export async function asked(floor, asking, absent = []) {
+    const response = await accepted(floor, asking, absent);
+    if (!response)
+        return null;
+    const said = await response.text();
+    return said ? JSON.parse(said) : null;
+}
+export async function askedForBytes(floor, asking, absent = []) {
+    const response = await accepted(floor, asking, absent);
+    if (!response)
+        return null;
+    return { bytes: new Uint8Array(await response.arrayBuffer()), contentType: response.headers.get("content-type") ?? "application/octet-stream" };
+}
+/** Nothing to read: the floor either did it or refused. */
+export async function done(floor, asking, absent = []) {
+    return (await accepted(floor, asking, absent)) !== null;
+}
+async function accepted(floor, asking, absent) {
+    const response = await send(floor, asking);
+    if (absent.includes(response.status) || response.status === HTTP_NO_CONTENT)
+        return null;
+    if (response.ok)
+        return response;
+    throw new FloorProblem(await problemOf(response), asking);
+}
+function headersFor(floor, asking) {
+    const headers = { authorization: `Bearer ${floor.token}` };
+    const contentType = contentTypeOf(asking);
+    if (contentType)
+        headers["content-type"] = contentType;
+    return headers;
+}
+// Bytes go up under the type they are stored as; a JSON body says so; a request with no body says nothing.
+function contentTypeOf(asking) {
+    if (asking.bytes)
+        return asking.bytes.contentType;
+    return asking.body === undefined ? null : "application/json";
+}
+function bodyOf(asking) {
+    if (asking.bytes)
+        return asking.bytes.content;
+    return asking.body === undefined ? undefined : JSON.stringify(asking.body);
+}
+function queryOf(query) {
+    const stated = Object.entries(query ?? {}).filter((entry) => entry[1] !== undefined);
+    const search = new URLSearchParams(stated.map(([name, value]) => [name, String(value)]));
+    return search.size > 0 ? `?${search.toString()}` : "";
+}
+//# sourceMappingURL=send.js.map

package/dist/station-runs.d.ts

@@ -0,0 +1,38 @@
+import type { RecordKind, StationRunRecordView, VisitBrief, VisitView } from "@re-cinq/floor-contracts";
+import { type Reachable } from "./send.js";
+/** A brief is asked for once a dispatch is claimed, and the answer decides what the worker does next. */
+export type BriefOutcome = {
+    kind: "brief";
+    brief: VisitBrief;
+}
+/** The visit already reported: ack the dispatch and run nothing. */
+ | {
+    kind: "reported";
+}
+/** No such visit: dead-letter the dispatch, since trying again will never find it. */
+ | {
+    kind: "absent";
+};
+export interface RecordsPage {
+    items: StationRunRecordView[];
+    /** Null once the records have been read to their end. */
+    nextCursor: number | null;
+}
+export interface StationRunsApi {
+    list(query: {
+        run: string;
+        node?: string;
+        open?: boolean;
+    }): Promise<VisitView[]>;
+    get(visitId: string): Promise<(VisitView & {
+        cost: unknown;
+    }) | null>;
+    brief(visitId: string): Promise<BriefOutcome>;
+    records(visitId: string, query: {
+        kind: RecordKind;
+        since?: number;
+        limit?: number;
+    }): Promise<RecordsPage>;
+}
+export declare function stationRunsApi(floor: Reachable): StationRunsApi;
+export declare function briefOutcome(floor: Reachable, visitId: string): Promise<BriefOutcome>;

package/dist/station-runs.js

@@ -0,0 +1,28 @@
+import { FloorProblem, problemOf } from "./problem.js";
+import { asked, send } from "./send.js";
+const HTTP_NOT_FOUND = 404;
+const HTTP_CONFLICT = 409;
+export function stationRunsApi(floor) {
+    return {
+        list: async (query) => {
+            const page = await asked(floor, { method: "GET", path: "/station-runs", query });
+            return page?.items ?? [];
+        },
+        get: (visitId) => asked(floor, { method: "GET", path: `/station-runs/${visitId}` }, [HTTP_NOT_FOUND]),
+        brief: (visitId) => briefOutcome(floor, visitId),
+        records: async (visitId, query) => (await asked(floor, { method: "GET", path: `/station-runs/${visitId}/records`, query })),
+    };
+}
+// Which of the three it is, is the status: `asked` would collapse both refusals to null, and the two mean opposite things to a claim loop.
+export async function briefOutcome(floor, visitId) {
+    const asking = { method: "GET", path: `/station-runs/${visitId}/brief` };
+    const response = await send(floor, asking);
+    if (response.status === HTTP_CONFLICT)
+        return { kind: "reported" };
+    if (response.status === HTTP_NOT_FOUND)
+        return { kind: "absent" };
+    if (!response.ok)
+        throw new FloorProblem(await problemOf(response), asking);
+    return { kind: "brief", brief: (await response.json()) };
+}
+//# sourceMappingURL=station-runs.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,11 @@
+declare const tokenKind: unique symbol;
+export type ServiceToken = string & {
+    readonly [tokenKind]: "service";
+};
+export type VisitToken = string & {
+    readonly [tokenKind]: "visit";
+};
+export declare function serviceToken(raw: string): ServiceToken;
+/** A visit token comes from that visit's brief, and stops being accepted when the visit reports. */
+export declare function visitToken(raw: string): VisitToken;
+export {};

package/dist/tokens.js

@@ -0,0 +1,9 @@
+// Two tokens reach a floor and they are not interchangeable: a service token may read any visit, a visit token only its own. Branding them keeps one from being passed where the other belongs.
+export function serviceToken(raw) {
+    return raw;
+}
+/** A visit token comes from that visit's brief, and stops being accepted when the visit reports. */
+export function visitToken(raw) {
+    return raw;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/visit.d.ts

@@ -0,0 +1,46 @@
+import type { BlobRef, RecordKind, Report, StationRunRecordView } from "@re-cinq/floor-contracts";
+import { type StoredBytes } from "./blobs.js";
+import { type BriefOutcome } from "./station-runs.js";
+import type { VisitToken } from "./tokens.js";
+export interface VisitAccess {
+    url: string;
+    token: VisitToken;
+    visitId: string;
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}
+export type GitCredentialOutcome = {
+    kind: "credential";
+    username: string;
+    password: string;
+}
+/** This floor was given no credential provider, so no visit may write to a repository. */
+ | {
+    kind: "unconfigured";
+}
+/** This visit declared no need for that repository, or only to read it. */
+ | {
+    kind: "ungranted";
+};
+export interface AppendRecord {
+    kind: Extract<RecordKind, "log" | "turn" | "llm_call">;
+    body: unknown;
+    occurredAt: Date;
+}
+export interface VisitClient {
+    brief(): Promise<BriefOutcome>;
+    /** One enveloped event from the subsystem's supervisor. */
+    sink(event: unknown): Promise<void>;
+    gitCredential(repo: string): Promise<GitCredentialOutcome>;
+    append(records: AppendRecord[]): Promise<StationRunRecordView[]>;
+    readBlob(hashOrUrl: string): Promise<StoredBytes | null>;
+    storeBlob(bytes: Uint8Array, contentType?: string): Promise<BlobRef>;
+    saveConversation(archive: Uint8Array): Promise<BlobRef>;
+    restoreConversation(savedBy: string): Promise<Uint8Array | null>;
+    /** The one thing a visit token may post to the queue. Its name, its visit and its dedupe key are not the caller's to choose. */
+    report(reported: {
+        report: Report;
+        worker: string;
+    }): Promise<void>;
+}
+export declare function createVisitClient(access: VisitAccess): VisitClient;

package/dist/visit.js

@@ -0,0 +1,50 @@
+import { blobsApi, conversationApi } from "./blobs.js";
+import { briefOutcome } from "./station-runs.js";
+import { FloorProblem, problemOf } from "./problem.js";
+import { asked, done, send } from "./send.js";
+const HTTP_NOT_IMPLEMENTED = 501;
+const HTTP_FORBIDDEN = 403;
+export function createVisitClient(access) {
+    const floor = { url: access.url.replace(/\/+$/, ""), token: access.token, fetchFn: access.fetchFn, timeoutMs: access.timeoutMs };
+    const visitId = access.visitId;
+    const blobs = blobsApi(floor);
+    const conversation = conversationApi(floor);
+    return {
+        brief: () => briefOutcome(floor, visitId),
+        sink: async (event) => {
+            await done(floor, { method: "POST", path: `/station-runs/${visitId}/sink`, body: event });
+        },
+        gitCredential: (repo) => gitCredential(floor, visitId, repo),
+        append: async (records) => {
+            const written = await asked(floor, { method: "POST", path: `/station-runs/${visitId}/records`, body: { records: records.map(onTheWire) } });
+            return written?.items ?? [];
+        },
+        readBlob: (hashOrUrl) => (hashOrUrl.includes("://") ? blobs.atUrl(hashOrUrl) : blobs.get(hashOrUrl)),
+        storeBlob: (bytes, contentType) => blobs.put(bytes, contentType),
+        saveConversation: (archive) => conversation.save(visitId, archive),
+        restoreConversation: (savedBy) => conversation.restore(savedBy),
+        report: async (reported) => {
+            await done(floor, {
+                method: "POST",
+                path: "/events",
+                body: { name: "station_run.reported", payload: { visitId, worker: reported.worker, report: reported.report }, dedupeKey: `station_run.reported:${visitId}` },
+            });
+        },
+    };
+}
+function onTheWire(record) {
+    return { kind: record.kind, body: record.body, occurredAt: record.occurredAt.toISOString() };
+}
+// The two refusals mean opposite things — the floor has no provider at all, or this visit was not given that repository — so the status is read rather than collapsed.
+async function gitCredential(floor, visitId, repo) {
+    const asking = { method: "POST", path: `/station-runs/${visitId}/git-credential`, body: { repo } };
+    const response = await send(floor, asking);
+    if (response.status === HTTP_NOT_IMPLEMENTED)
+        return { kind: "unconfigured" };
+    if (response.status === HTTP_FORBIDDEN)
+        return { kind: "ungranted" };
+    if (!response.ok)
+        throw new FloorProblem(await problemOf(response), asking);
+    return { kind: "credential", ...(await response.json()) };
+}
+//# sourceMappingURL=visit.js.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@re-cinq/floor-client",
+  "version": "0.1.2",
+  "description": "The floor over HTTP and its live socket, typed: definitions, runs, visits, blobs, events, schedules and costs, plus a watch that replays a run from a cursor and reconnects without losing a frame.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/re-cinq/floor.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/re-cinq/floor/tree/main/packages/client#readme",
+  "bugs": {
+    "url": "https://github.com/re-cinq/floor/issues"
+  },
+  "keywords": [
+    "floor",
+    "client",
+    "orchestration",
+    "agents"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@re-cinq/floor-contracts": "0.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}