@smthrs/gateway 0.34.0 → 1.0.0-rc.3

package/dist/vendor/platform-bun.js

@@ -0,0 +1,107 @@
+import "./chunk-BFBIHJ6X.js";
+import {
+  BunSocketServer_exports
+} from "./chunk-LKCGQEE5.js";
+import {
+  BunWorker_exports
+} from "./chunk-CES4OUM4.js";
+import {
+  BunWorkerRunner_exports
+} from "./chunk-ZCHYLHJH.js";
+import {
+  BunHttpServerRequest_exports
+} from "./chunk-BCK3NJOX.js";
+import {
+  BunRedis_exports
+} from "./chunk-HY7BBL3K.js";
+import {
+  BunRuntime_exports
+} from "./chunk-RGECXXJS.js";
+import "./chunk-TFY7W6D4.js";
+import {
+  BunSink_exports
+} from "./chunk-QR557K66.js";
+import {
+  BunClusterHttp_exports
+} from "./chunk-DX4Z23DM.js";
+import {
+  BunSocket_exports
+} from "./chunk-3ARKKENZ.js";
+import {
+  BunClusterSocket_exports
+} from "./chunk-XCYARUII.js";
+import "./chunk-6UPBD47P.js";
+import "./chunk-Z7QNPJEB.js";
+import "./chunk-YDASSC75.js";
+import {
+  BunHttpClient_exports
+} from "./chunk-3NV2UDBI.js";
+import {
+  BunHttpServer_exports
+} from "./chunk-Z6C7SO5Z.js";
+import {
+  BunMultipart_exports
+} from "./chunk-IFTTT6D5.js";
+import {
+  BunStream_exports
+} from "./chunk-H2Z2Y4QH.js";
+import {
+  BunServices_exports
+} from "./chunk-UHIDPUFF.js";
+import {
+  BunStdio_exports
+} from "./chunk-GUPAV2YZ.js";
+import "./chunk-D64L6YND.js";
+import {
+  BunTerminal_exports
+} from "./chunk-XFZZYSJ4.js";
+import "./chunk-3OSW7CT7.js";
+import {
+  BunPath_exports
+} from "./chunk-KQDSNB7M.js";
+import "./chunk-FOXN6JPJ.js";
+import {
+  BunChildProcessSpawner_exports
+} from "./chunk-XJWJXLXJ.js";
+import "./chunk-DZ2VOUDP.js";
+import "./chunk-B4DHEMBB.js";
+import "./chunk-Z7QPP4YH.js";
+import "./chunk-37CUR3PO.js";
+import {
+  BunCrypto_exports
+} from "./chunk-6C5H7S6B.js";
+import "./chunk-2GCOZTTW.js";
+import {
+  BunHttpPlatform_exports
+} from "./chunk-OBWXQKVP.js";
+import "./chunk-6AQLBC2I.js";
+import {
+  BunFileSystem_exports
+} from "./chunk-UXBGYQR3.js";
+import "./chunk-TOHSFXMV.js";
+import "./chunk-WVFOZ2UL.js";
+import "./chunk-MLKGABMK.js";
+export {
+  BunChildProcessSpawner_exports as BunChildProcessSpawner,
+  BunClusterHttp_exports as BunClusterHttp,
+  BunClusterSocket_exports as BunClusterSocket,
+  BunCrypto_exports as BunCrypto,
+  BunFileSystem_exports as BunFileSystem,
+  BunHttpClient_exports as BunHttpClient,
+  BunHttpPlatform_exports as BunHttpPlatform,
+  BunHttpServer_exports as BunHttpServer,
+  BunHttpServerRequest_exports as BunHttpServerRequest,
+  BunMultipart_exports as BunMultipart,
+  BunPath_exports as BunPath,
+  BunRedis_exports as BunRedis,
+  BunRuntime_exports as BunRuntime,
+  BunServices_exports as BunServices,
+  BunSink_exports as BunSink,
+  BunSocket_exports as BunSocket,
+  BunSocketServer_exports as BunSocketServer,
+  BunStdio_exports as BunStdio,
+  BunStream_exports as BunStream,
+  BunTerminal_exports as BunTerminal,
+  BunWorker_exports as BunWorker,
+  BunWorkerRunner_exports as BunWorkerRunner
+};

package/dist/vendor/platform-node-shared.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @since 4.0.0
+ */
+/**
+ * @since 4.0.0
+ */
+export * as NodeChildProcessSpawner from "./node-shared/NodeChildProcessSpawner.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterSocket from "./node-shared/NodeClusterSocket.ts";
+/**
+ * @since 1.0.0
+ */
+export * as NodeCrypto from "./node-shared/NodeCrypto.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeFileSystem from "./node-shared/NodeFileSystem.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpCompression from "./node-shared/NodeHttpCompression.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodePath from "./node-shared/NodePath.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRuntime from "./node-shared/NodeRuntime.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSink from "./node-shared/NodeSink.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocket from "./node-shared/NodeSocket.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocketServer from "./node-shared/NodeSocketServer.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStdio from "./node-shared/NodeStdio.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStream from "./node-shared/NodeStream.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeTerminal from "./node-shared/NodeTerminal.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/vendor/platform-node-shared.js

@@ -0,0 +1,58 @@
+import "./chunk-MH2J3BYB.js";
+import {
+  NodeRuntime_exports
+} from "./chunk-TFY7W6D4.js";
+import {
+  NodeClusterSocket_exports
+} from "./chunk-6UPBD47P.js";
+import {
+  NodeSocketServer_exports
+} from "./chunk-Z7QNPJEB.js";
+import {
+  NodeSocket_exports
+} from "./chunk-YDASSC75.js";
+import {
+  NodeStdio_exports
+} from "./chunk-D64L6YND.js";
+import {
+  NodeTerminal_exports
+} from "./chunk-3OSW7CT7.js";
+import {
+  NodePath_exports
+} from "./chunk-FOXN6JPJ.js";
+import {
+  NodeChildProcessSpawner_exports
+} from "./chunk-DZ2VOUDP.js";
+import "./chunk-B4DHEMBB.js";
+import {
+  NodeStream_exports
+} from "./chunk-Z7QPP4YH.js";
+import {
+  NodeSink_exports
+} from "./chunk-37CUR3PO.js";
+import {
+  NodeCrypto_exports
+} from "./chunk-2GCOZTTW.js";
+import {
+  NodeHttpCompression_exports
+} from "./chunk-6AQLBC2I.js";
+import {
+  NodeFileSystem_exports
+} from "./chunk-TOHSFXMV.js";
+import "./chunk-WVFOZ2UL.js";
+import "./chunk-MLKGABMK.js";
+export {
+  NodeChildProcessSpawner_exports as NodeChildProcessSpawner,
+  NodeClusterSocket_exports as NodeClusterSocket,
+  NodeCrypto_exports as NodeCrypto,
+  NodeFileSystem_exports as NodeFileSystem,
+  NodeHttpCompression_exports as NodeHttpCompression,
+  NodePath_exports as NodePath,
+  NodeRuntime_exports as NodeRuntime,
+  NodeSink_exports as NodeSink,
+  NodeSocket_exports as NodeSocket,
+  NodeSocketServer_exports as NodeSocketServer,
+  NodeStdio_exports as NodeStdio,
+  NodeStream_exports as NodeStream,
+  NodeTerminal_exports as NodeTerminal
+};

package/dist/vendor/platform-node.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @since 4.0.0
+ */
+/**
+ * @since 4.0.0
+ */
+export * as NodeChildProcessSpawner from "./node/NodeChildProcessSpawner.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterHttp from "./node/NodeClusterHttp.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterSocket from "./node/NodeClusterSocket.ts";
+/**
+ * @since 1.0.0
+ */
+export * as NodeCrypto from "./node/NodeCrypto.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeFileSystem from "./node/NodeFileSystem.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpClient from "./node/NodeHttpClient.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpIncomingMessage from "./node/NodeHttpIncomingMessage.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpPlatform from "./node/NodeHttpPlatform.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpServer from "./node/NodeHttpServer.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpServerRequest from "./node/NodeHttpServerRequest.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeMultipart from "./node/NodeMultipart.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeMultipartParser from "./node/NodeMultipartParser.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodePath from "./node/NodePath.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRedis from "./node/NodeRedis.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRuntime from "./node/NodeRuntime.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeServices from "./node/NodeServices.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSink from "./node/NodeSink.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocket from "./node/NodeSocket.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocketServer from "./node/NodeSocketServer.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStdio from "./node/NodeStdio.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStream from "./node/NodeStream.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeTerminal from "./node/NodeTerminal.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeWorker from "./node/NodeWorker.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeWorkerRunner from "./node/NodeWorkerRunner.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/vendor/platform-node.js

@@ -0,0 +1,115 @@
+import "./chunk-MLFIZ5O2.js";
+import {
+  NodeSocketServer_exports
+} from "./chunk-WHKMOC7Z.js";
+import {
+  NodeWorker_exports
+} from "./chunk-6DY5RBZD.js";
+import {
+  NodeWorkerRunner_exports
+} from "./chunk-TGPIVY4A.js";
+import {
+  NodeHttpServerRequest_exports
+} from "./chunk-V6LUGQ7O.js";
+import {
+  NodeRedis_exports
+} from "./chunk-HAEDVSSM.js";
+import {
+  NodeRuntime_exports
+} from "./chunk-R4QUY7DH.js";
+import {
+  NodeClusterHttp_exports
+} from "./chunk-62R63L74.js";
+import {
+  NodeHttpServer_exports
+} from "./chunk-TGXCX6W3.js";
+import {
+  NodeSocket_exports
+} from "./chunk-FPQF7CR5.js";
+import {
+  NodeMultipart_exports
+} from "./chunk-ML2NAFH2.js";
+import {
+  NodeMultipartParser_exports
+} from "./chunk-ULT6CWUI.js";
+import {
+  NodeServices_exports
+} from "./chunk-ZPIG2CUA.js";
+import {
+  NodeStdio_exports
+} from "./chunk-X73E2UPI.js";
+import {
+  NodeTerminal_exports
+} from "./chunk-ZIQVYVMA.js";
+import {
+  NodePath_exports
+} from "./chunk-LIHLXXGQ.js";
+import {
+  NodeChildProcessSpawner_exports
+} from "./chunk-WAII54GA.js";
+import {
+  NodeClusterSocket_exports
+} from "./chunk-MSCLEMYX.js";
+import {
+  NodeCrypto_exports
+} from "./chunk-DS2R6WOM.js";
+import {
+  NodeHttpClient_exports
+} from "./chunk-WECQDT36.js";
+import {
+  NodeSink_exports
+} from "./chunk-FUTCTCEG.js";
+import {
+  NodeHttpIncomingMessage_exports
+} from "./chunk-W4OASVX6.js";
+import {
+  NodeHttpPlatform_exports
+} from "./chunk-AVVVN75Z.js";
+import {
+  NodeFileSystem_exports
+} from "./chunk-XY3Q62EO.js";
+import {
+  NodeStream_exports
+} from "./chunk-XFEVTDVD.js";
+import "./chunk-TFY7W6D4.js";
+import "./chunk-6UPBD47P.js";
+import "./chunk-Z7QNPJEB.js";
+import "./chunk-YDASSC75.js";
+import "./chunk-D64L6YND.js";
+import "./chunk-3OSW7CT7.js";
+import "./chunk-FOXN6JPJ.js";
+import "./chunk-DZ2VOUDP.js";
+import "./chunk-B4DHEMBB.js";
+import "./chunk-Z7QPP4YH.js";
+import "./chunk-37CUR3PO.js";
+import "./chunk-2GCOZTTW.js";
+import "./chunk-6AQLBC2I.js";
+import "./chunk-TOHSFXMV.js";
+import "./chunk-WVFOZ2UL.js";
+import "./chunk-MLKGABMK.js";
+export {
+  NodeChildProcessSpawner_exports as NodeChildProcessSpawner,
+  NodeClusterHttp_exports as NodeClusterHttp,
+  NodeClusterSocket_exports as NodeClusterSocket,
+  NodeCrypto_exports as NodeCrypto,
+  NodeFileSystem_exports as NodeFileSystem,
+  NodeHttpClient_exports as NodeHttpClient,
+  NodeHttpIncomingMessage_exports as NodeHttpIncomingMessage,
+  NodeHttpPlatform_exports as NodeHttpPlatform,
+  NodeHttpServer_exports as NodeHttpServer,
+  NodeHttpServerRequest_exports as NodeHttpServerRequest,
+  NodeMultipart_exports as NodeMultipart,
+  NodeMultipartParser_exports as NodeMultipartParser,
+  NodePath_exports as NodePath,
+  NodeRedis_exports as NodeRedis,
+  NodeRuntime_exports as NodeRuntime,
+  NodeServices_exports as NodeServices,
+  NodeSink_exports as NodeSink,
+  NodeSocket_exports as NodeSocket,
+  NodeSocketServer_exports as NodeSocketServer,
+  NodeStdio_exports as NodeStdio,
+  NodeStream_exports as NodeStream,
+  NodeTerminal_exports as NodeTerminal,
+  NodeWorker_exports as NodeWorker,
+  NodeWorkerRunner_exports as NodeWorkerRunner
+};

package/docs/README.md

@@ -0,0 +1,158 @@
+---
+title: "@smthrs/gateway"
+description: "One HTTP surface over a Smithers workspace: the control plane, live projections of every run, the journal sync read path, and a health probe, served on one socket that any client can read."
+---
+
+`@smthrs/gateway` puts a Smithers workspace on a socket. One HTTP server carries
+four things: the control plane that starts, approves, steers, and cancels runs;
+read-only projections of what those runs are doing; the journal sync read path a
+follower replicates from; and an unauthenticated health probe that answers which
+workspace this process belongs to.
+
+You install it when you want a workspace readable and controllable from outside
+the process that owns it: a dashboard, a browser relay, a CI job, another agent,
+or your own service.
+
+## The problem it solves
+
+An agent run that takes hours outlives the terminal that started it, and the
+people who need to see it are not sitting at that terminal. Handing them the
+database is the wrong answer: a reader that opens the engine's tables couples
+itself to storage that changes, and it can read things no client should see.
+
+This package answers with a contract instead, and holds three promises:
+
+- **A row is a fold, not a table.** Every served row is computed from the
+  ordered control events a run already publishes. The gateway never opens the
+  engine database, so a projection cannot drift by reading a column the control
+  plane does not expose.
+- **A remote reader and a local reader see the same thing.** The rows a browser
+  receives through a relay are the rows a local process computes from the same
+  events, because there is one code path and no privileged one.
+- **A network bind fails closed.** Loopback needs no credential. Anything
+  reachable from another machine needs both an explicit opt-in and a bearer
+  credential, or the bind is refused before it serves.
+
+Reach for it when you are writing the client, the host, or the relay. Reach for
+the command line instead when you want to drive runs from a shell.
+
+## How it relates to the smthrs CLI
+
+[`@smthrs/cli`](/api/cli) is the `smthrs` command line, and it is the top-level
+package the rest of Smithers sits under. Start there if you are new.
+
+[`smthrs serve`](/cli/serve) is a host over this package: it resolves a project
+on disk, builds the control plane and the journal over that project's database,
+and hands the assembly here to bind and serve. Every mount you read in these
+pages is the surface that one command puts on a port, which is why a client
+written against this contract works against a gateway the CLI serves and against
+one you host yourself.
+
+The dependency runs one way. `@smthrs/cli` depends on `@smthrs/gateway`; this
+package knows nothing about a terminal, a project directory, or a database file.
+Install [`@smthrs/cli`](/api/cli) when you want a gateway without writing code.
+Install `@smthrs/gateway` when you are writing a client against the wire, or
+embedding the surface in a process of your own.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+The package needs Node.js 26.4.0 or later. For the peers and the
+services a running composition supplies, see [Installation](./installation.md).
+
+## The smallest real example
+
+The `smthrs` executable comes from [`@smthrs/cli`](/api/cli), not from this
+package; [install it](https://github.com/smithersai/smithers/blob/main/packages/smithers/docs/installation.md#install-the-cli), then serve a project you already have runs in:
+
+```bash
+smthrs serve
+```
+
+Then, from anywhere that can reach the port, ask the workspace what its runs
+did. The read path speaks RPC over newline-delimited JSON, so one request is one
+line:
+
+```bash
+curl -s http://127.0.0.1:3000/projections \
+  -H 'content-type: application/json' \
+  --data-binary '{"_tag":"Request","id":1,"tag":"Projection.Snapshot","payload":{"selector":{"_tag":"workspace-runs"}},"headers":[]}
+' | head -1 | jq -ac '.exit.value.rows[] | {runId, verdict}'
+```
+
+```json
+{"runId":"run-1","verdict":"completed \u2014 shipped"}
+{"runId":"run-2","verdict":"waiting-approval \u2014 asks: Write to src/index.ts?"}
+{"runId":"run-3","verdict":"failed \u2014 could not resolve seat anthropic:claude-sonnet-4-5"}
+```
+
+No client library, no schema of your own, and nothing that knows what a table
+looks like. The tag, not the mount, decides whether a request streams, and
+`/projections/ws` addresses both procedures: `Projection.Snapshot` there still
+answers once, while `Projection.Subscribe` with the same payload on
+`/projections/ws` answers a snapshot and then keeps sending, so a view follows
+a run instead of polling it.
+
+The folds behind those rows are exported, so a program holding a run's control
+events computes the identical row with no gateway at all:
+
+```ts
+import * as GatewayProjection from "@smthrs/gateway/GatewayProjection"
+
+const row = GatewayProjection.runSummary(run, events)
+// row.verdict is the single line a run card leads with.
+```
+
+That bind is loopback, so it needs no credential and no opt-in. Its requests
+still need a loopback `Host`, and any supplied browser `Origin` must be a
+canonical HTTP(S) origin whose host and port equal the request's `Host`;
+Origin-less CLI clients remain accepted. Anything else needs both a
+bind opt-in and a bearer, and the layer fails with a typed `bind_failed`
+`GatewayError` rather than binding. See
+[Serve beyond loopback](./guides/serve-beyond-loopback.md).
+
+For a gateway you can probe and read within a minute, start with the
+[Quickstart](./quickstart.md).
+
+## The package at a glance
+
+The root entry point exports one namespace per module, and each is also
+importable from `@smthrs/gateway/<Module>`:
+
+| Namespace           | What it is                                                                                                      |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `GatewayServer`     | The whole HTTP surface as one application layer: seven mounts, the ingress guard, and the keepalives.           |
+| `node/NodeGateway`  | The Node host that binds that surface to a socket under the bind and credential policy.                         |
+| `Projections`       | The served read path: a snapshot of any selector, or a snapshot followed by a live tail.                        |
+| `GatewaySchema`     | The wire vocabulary: selectors, cursors, snapshots, and the five subscription frames.                           |
+| `GatewayProjection` | The served row types and the pure folds that compute them from control events.                                  |
+| `GatewayRpcs`       | The remote procedures this package adds: the read path, and the composite approval mutation.                    |
+| `Diagnosis`         | What happened to a run, folded from its own events and rendered as a verdict line and a card.                   |
+| `GatewayError`      | Every stable failure code the gateway answers with, from a refused bind to a refused read.                      |
+| `Sync`              | [`@smthrs/sync`](/api/smithers-sync) re-exported whole, so a host mounts the journal read path from one import. |
+
+Every export, with its signature, is on the [API reference](./api.md).
+
+## Where to go next
+
+- [Installation](./installation.md): requirements, the public import forms, and
+  the four services a host supplies.
+- [Quickstart](./quickstart.md): serve a workspace, probe its identity, read a
+  snapshot off the wire, and follow one run live.
+- Concepts: [projections](./concepts/projections.md),
+  [subscriptions and cursors](./concepts/subscriptions.md), and
+  [the trust boundary](./concepts/trust-boundary.md).
+- Guides: [host the gateway in your own process](./guides/host-the-gateway.md),
+  [read a projection over HTTP](./guides/read-a-projection.md),
+  [follow a run over a WebSocket](./guides/follow-a-run.md),
+  [submit an approval from a client](./guides/submit-an-approval.md),
+  [serve beyond loopback](./guides/serve-beyond-loopback.md),
+  [diagnose what happened to a run](./guides/diagnose-a-run.md), and
+  [test against a real gateway](./guides/testing.md).
+- [Troubleshooting](./troubleshooting.md): every refusal this package answers
+  with, what causes it, and what to change.
+- [`@smthrs/control`](/api/control): the control plane these projections fold,
+  and the contract `/rpc` mounts unchanged.
+- [`@smthrs/cli`](/api/cli): the `smthrs` command line that hosts this gateway,
+  and the package the rest of Smithers sits under.