@smthrs/control 0.0.0-stage → 1.0.0-rc.3

package/docs/guides/serve-over-rpc.md

@@ -0,0 +1,220 @@
+---
+title: "Serve the control plane over RPC"
+description: "Mount the same Control service as HTTP and WebSocket RPC, project it back into the Control interface on a client, authenticate with a bearer token, and read the transport failures a client can retry."
+sidebar:
+  order: 9
+---
+
+`ControlServer.layerHttp` mounts the `Control` service as RPC;
+`ControlClient.layer` projects the RPC client back into the same interface.
+Remote operations also require transport configuration and authentication.
+
+## Mount the server
+
+```ts
+import { NodeHttpServer } from "@effect/platform-node"
+import * as ControlRpcs from "@smthrs/control/ControlRpcs"
+import * as ControlServer from "@smthrs/control/ControlServer"
+import * as Layer from "effect/Layer"
+import { HttpRouter } from "effect/unstable/http"
+import { RpcSerialization } from "effect/unstable/rpc"
+import { createServer } from "node:http"
+
+const served = HttpRouter.serve(
+  ControlServer.layerHttp.pipe(
+    Layer.provide(ControlRpcs.layerBearerAuth({
+      token: process.env["SMITHERS_CONTROL_TOKEN"] ?? "",
+      principal: { id: "operator", kind: "bearer" }
+    })),
+    Layer.provide(RpcSerialization.layerNdjson)
+  )
+).pipe(
+  Layer.provideMerge(NodeHttpServer.layer(createServer, { host: "127.0.0.1", port: 0 }))
+)
+```
+
+`layerHttp` mounts both protocols together: unary procedures over
+`POST /rpc`, and the `watch` stream over `WebSocket /rpc/ws`. The operations
+divide cleanly. Plan, approve, run, and list are requests with answers; `watch`
+is a projection that keeps arriving, so it rides a socket.
+
+`ControlServer.layer` is the handler layer alone, for a host that mounts its
+own protocols.
+
+## Connect a client
+
+`credential` authenticates HTTP requests only. Authenticated `watch` also
+requires an `Authorization` header on the WebSocket upgrade. An ordinary
+`NodeSocket.layerWebSocket` does not send it and watch fails with
+`Unauthorized`. This Node composition uses the `ws` constructor exported by
+`NodeSocket` to supply the upgrade header:
+
+```ts
+import { NodeHttpClient, NodeSocket } from "@effect/platform-node"
+import * as ControlClient from "@smthrs/control/ControlClient"
+import * as Layer from "effect/Layer"
+import { RpcSerialization } from "effect/unstable/rpc"
+import { Socket } from "effect/unstable/socket"
+
+const credential = process.env["SMITHERS_CONTROL_TOKEN"] ?? ""
+const authenticatedSocket = Socket.layerWebSocket("ws://127.0.0.1:4000/rpc/ws").pipe(
+  Layer.provide(
+    Layer.succeed(Socket.WebSocketConstructor)((url, options) => {
+      const configured = options !== undefined && typeof options !== "string" && !Array.isArray(options)
+        ? options
+        : undefined
+      const protocols = configured === undefined ? options as string | Array<string> | undefined : undefined
+      const socket = new NodeSocket.NodeWS.WebSocket(url, protocols, {
+        ...configured,
+        headers: { ...configured?.headers, Authorization: `Bearer ${credential}` }
+      })
+      // Effect removes reader listeners before closing. `ws` can report a
+      // late handshake error during that close; keep Node from treating it as
+      // an unhandled event. Active Effect listeners still receive all errors.
+      socket.on("error", () => {})
+      return socket
+    })
+  )
+)
+
+const client = ControlClient.layer({
+  url: "http://127.0.0.1:4000/rpc",
+  credential
+}).pipe(
+  Layer.provide([
+    NodeHttpClient.layerUndici,
+    authenticatedSocket,
+    RpcSerialization.layerNdjson
+  ])
+)
+```
+
+With both HTTP and the socket upgrade authenticated, programs written against
+`Control` can use this client layer. Handle `TransportError` and `Unauthorized`
+in addition to each operation's domain failures; both are declared on every
+`Control.Service` method.
+
+Browser WebSockets cannot set upgrade headers. Browser deployments need a
+trusted proxy that authenticates the caller and supplies the header. Tokens
+in URL query strings are not supported.
+
+`layerHttp` refuses, with 403 and before authentication, any request whose
+`Origin` header does not match its `Host` header, on POST `/rpc` and on the
+`/rpc/ws` upgrade. A browser always sends `Origin`, so a page on another site
+cannot use a credential the proxy attaches for its victim. Non-browser
+clients send no `Origin` and are unaffected. Serve the browser app from the
+same origin as the control mount, and keep the proxy's `Host` header intact.
+
+## Authenticate
+
+`ControlRpcs.ControlAuth` is the middleware boundary, and it provides
+`ControlPrincipal` to every handler.
+
+| Layer                                   | Use                                                                      |
+| --------------------------------------- | ------------------------------------------------------------------------ |
+| `layerBearerAuth({ token, principal })` | One shared token. Every request carrying it receives the same principal. |
+| `layerAuth(authenticator)`              | Your own header authenticator, returning a principal or `Unauthorized`.  |
+| `layerNoopAuth(principal?)`             | Trusted in-process use and tests. Authenticates nothing.                 |
+
+The bearer comparison is constant time, and a missing, malformed, empty, or
+incorrect credential all fail closed with the same `Unauthorized` response.
+
+## Who reads which runs
+
+Every run the control plane launches records the principal that launched it as
+`RunSummary.launchedBy`. `List` and `Watch` answer an operator with every run
+and every other principal with only the runs it launched: its own run
+summaries, the fires that started them, and their events. `Steer`, `Signal`,
+`Cancel` and `Resume` accept the same runs. Triggers, a plan's events and a run
+the engine created (a child, a fork, a later round) reach operators only.
+Another principal's run answers `RunNotFound`, exactly as a missing one does.
+
+The authentication layer names the operators, because it knows which
+identities it stamps. `layerBearerAuth` and `layerNoopAuth` stamp one principal
+and make it the operator. `layerAuth` takes the rule as `seesAllRuns`, and
+without it no principal is an operator:
+
+```ts
+const auth = ControlRpcs.layerAuth(authenticator, {
+  seesAllRuns: (principal) => principal.kind === "operator"
+})
+```
+
+An authenticator also receives the call it is guarding, `{ rpc, payload }`,
+on every in-band frame and nothing at a transport edge; `anyAuthenticator`
+asks several in turn. `ScopedToken.authenticator` uses the call to confine a
+minted token to the procedures, run, or flow it names, and composes with the
+bearer:
+
+```ts
+import * as ControlRpcs from "@smthrs/control/ControlRpcs"
+import * as ScopedToken from "@smthrs/control/ScopedToken"
+
+const auth = ControlRpcs.layerAuth(ControlRpcs.anyAuthenticator([
+  ControlRpcs.bearerAuthenticator({ token, principal: { id: "gateway", kind: "bearer" } }),
+  ScopedToken.authenticator({ key: token, principal: { id: "gateway", kind: "scoped" } })
+]))
+```
+
+A custom authenticator is an object with one method:
+
+```ts
+import { Unauthorized } from "@smthrs/control/ControlError"
+import type * as ControlRpcs from "@smthrs/control/ControlRpcs"
+import * as Effect from "effect/Effect"
+
+const authenticator: ControlRpcs.Authenticator = {
+  authenticate: (headers) =>
+    lookupSession(headers["x-session"]).pipe(
+      Effect.map((session) => ({ id: session.userId, kind: "user", stampedAt: Date.now() })),
+      Effect.mapError(() => new Unauthorized({ message: "A valid session is required" }))
+    )
+}
+```
+
+## The server stamps identity, always
+
+Every mutation that records who asked reads `ControlPrincipal` and stamps it,
+rather than forwarding whatever the client sent. The identity the middleware
+authenticated is the only one the server can stand behind, and it is what
+reaches the journal, `RunSummary.cancellation`, and a steer's notification
+provenance.
+
+`Steer` is the one payload that carries a principal on the wire, because an
+in-process caller names one that is not an operator. Over RPC the
+authenticated identity replaces whatever arrived. See
+[attribution over a wire](./steer-a-run.md).
+
+## Failures a client sees
+
+`ControlClient` normalizes everything into `ControlError`. A declared control
+failure crosses the wire as itself; anything else becomes `TransportError`,
+whose `retryable` flag classifies only the transport phase:
+
+| Cause                                                  | `retryable` |
+| ------------------------------------------------------ | ----------- |
+| Connection, socket open, read, write, or close failure | `true`      |
+| HTTP 5xx                                               | `true`      |
+| HTTP 4xx                                               | `false`     |
+| Request encode failure                                 | `false`     |
+| Response decode failure                                | `false`     |
+| Invalid client URL                                     | `false`     |
+
+Resend a retryable mutation only when its idempotency key makes replay safe. A
+keyless request can have reached the server even when its response was lost.
+
+`ControlClient.isControlError` is `Schema.is` of the same union the errors are
+declared in, so an error class added to the package reaches the refinement
+without anyone updating a second list.
+
+An operator's own interruption is re-raised exactly as it arrived rather than
+described as a transport failure. Cancelling a request is not the server
+failing.
+
+## Where to go next
+
+- [The complete loopback example](https://github.com/smithersai/smithers/blob/main/examples/src/24-control-plane-and-gateway.ts):
+  a discovered flow planned, approved, launched, and watched over the wire.
+- [Watch a run's events](./watch-a-run.md): the operation the WebSocket exists
+  for.
+- [`smthrs serve`](/cli/serve): the shipped server over this layer.

package/docs/guides/signal-a-run.md

@@ -0,0 +1,53 @@
+# Signal a run
+
+`Control.signal` admits a named JSON payload under an actor-scoped idempotency
+key. `Accepted` confirms that admission is durable. It does not claim that the
+run has consumed the payload. Reusing the key with different input returns
+`Conflict` before the conflicting payload reaches an executor.
+
+The command, its receipt, and `control.signal.admitted` journal event commit
+in the control database first. Execution occurs after that transaction ends;
+there is no transaction spanning control.db and engine.db.
+
+The production executor binds each command to one concrete durable wait token
+before applying it. One token has at most one admitted command. Application
+atomically checks the engine's current wait token, and recovery verifies the
+stored deferred result. A crash after application but before acknowledgment
+retries the original token. It cannot move the command to a later wait.
+
+Commands without a visible wait remain pending. The running executor
+reconciles a bounded page every 250 milliseconds, starting at host startup,
+so a signal admitted before its wait opens does not require a restart or
+manual resend. Pages rotate so unavailable waits cannot starve later commands.
+Malformed stored payloads are rejected and logged rather than blocking a page.
+
+`ControlRuntime.signalCommand(commandId)` exposes `pending`, `delivered`,
+`rejected`, and `terminal` dispositions for integrations holding the admitted
+command identity. The CLI does not yet expose a dedicated delivery-status
+lookup. A definite incompatible wait raises `NoMatchingWait`; retries preserve
+that refusal. A signal initially submitted to a settled run returns `Terminal`.
+
+A human wait, one parked with reason `approval` such as a `HumanTask`
+question, is an approval gate. `Control.signal` stamps the caller's principal
+on the admitted command. Before the executor completes a human wait, it asks
+`ApprovalAuthority` whether that principal may approve the wait's `Node`
+target, with the wait name as `requestId`, the wait token as `digest`, and
+scope `once`. A refused principal fails `Unauthorized`, the command is
+rejected, and the wait stays open. A replay after restart is judged by the
+principal recorded at admission; a command with no recorded principal cannot
+answer a human wait. Plain `WaitFor` events need no approval.
+
+A signal from a webhook channel carries the principal
+`{ id: <channel name>, kind: "channel" }`. It can answer a human wait only if
+the host delegates approval to that principal.
+
+`WaitFor` names one durable fact per `(flowName, executionId, name)`. Calling
+it twice with the same name in the same execution intentionally observes the
+same fact. Use distinct names for distinct rendezvous points. This is not a
+stream of repeated same-name events.
+
+Legacy `control_run_messages` signals have no application identity or token
+binding. They remain readable through `deliveredSignals`, but are not
+replayed automatically by the new inbox. Operators must inspect legacy wait
+state before explicitly resubmitting under a new key; silently replaying them
+could apply historical intent to a different wait.

package/docs/guides/steer-a-run.md

@@ -0,0 +1,138 @@
+---
+title: "Steer a running agent"
+description: "Send a message, a seat change, a thinking level, or a tool set to a run's next turn boundary: the four variants, which parks a steer wakes, and the two durable moments a steer has."
+sidebar:
+  order: 4
+---
+
+`steer` writes one durable item into the notification queue and journals the
+enqueue beside it. The run picks it up at its next turn boundary.
+
+```ts
+import { Control } from "@smthrs/control/Control"
+import * as Effect from "effect/Effect"
+
+const steer = Effect.gen(function*() {
+  const control = yield* Control
+  return yield* control.steer({
+    runId: "run-17",
+    message: {
+      messageId: "steer-1",
+      runId: "run-17",
+      principal: { id: "ada", kind: "user", stampedAt: Date.now() },
+      createdAt: Date.now(),
+      body: "prefer the smaller diff"
+    },
+    idempotencyKey: "steer:run-17:1"
+  })
+})
+```
+
+## The four variants
+
+An operator steers a run for four different reasons, and only one of them is
+something to tell the model. Saying "your seat changed" would spend a turn on
+bookkeeping; changing the seat is what was asked for.
+
+| Variant                                                     | Field       | What the next turn does               |
+| ----------------------------------------------------------- | ----------- | ------------------------------------- |
+| `Message` (the default, and what a `body` alone decodes as) | `body`      | Inserts the body into the transcript. |
+| `Seat`                                                      | `seat`      | Runs the turn on that model seat.     |
+| `Thinking`                                                  | `thinking`  | Runs the turn at that thinking level. |
+| `Tools`                                                     | `toolNames` | Adds those tools to the active set.   |
+
+`kind` is optional on `Message` and required on the other three, which is what
+keeps a steer written before the vocabulary widened readable: a body and no
+kind is a message, and always was.
+
+```ts
+import { steerItem } from "@smthrs/control/ControlSchema"
+
+steerItem({ ...envelope, body: "prefer the smaller diff" })
+// { kind: "Message", body: "prefer the smaller diff" }
+steerItem({ ...envelope, kind: "Seat", seat: "anthropic:claude-sonnet-4-5" })
+// { kind: "Seat", seat: "anthropic:claude-sonnet-4-5" }
+```
+
+`ControlSchema.steerItem` strips the control envelope, which is who asked,
+when, and for which run, and returns the
+[`@smthrs/notifications`](/api/notifications) payload the harness reads back.
+The harness maps each payload onto its matching steering item, so a seat steer
+changes the seat instead of spending a turn announcing it.
+
+## The two durable moments
+
+| Event                     | Writer                                                                             | Payload                                 |
+| ------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------- |
+| `control.steer.enqueued`  | `Control.steer`                                                                    | `{ runId, messageId, kind, createdAt }` |
+| `control.steer.delivered` | derived by `Steering.derive` from the queue's `flows/notifications/Promoted` entry | `{ runId, messageId, boundary }`        |
+
+Delivery is derived rather than recorded, because the boundary that delivered
+the steer runs in the agent process and not in the control plane. A control
+plane that wrote its own delivery record would be asserting a fact it did not
+observe.
+
+One promotion entry names a batch, so it derives one delta per message id, each
+carrying the sequence of the entry it came from. Checkpoint `event.cursor`
+and resume with `afterCursor` to continue even between deliveries in a batch.
+
+`RunSummary.steering.pending` counts what has been admitted and not yet
+promoted. It comes from the queue rather than a column, because the queue owns
+both halves.
+
+## Waking a parked run
+
+A steer resumes a parked run when the park is one a message can end:
+
+| `waitingReason`              | Steered                                                                                                                         |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `event`                      | Resumed. The run is waiting for something to arrive, and a steer is something arriving.                                         |
+| `released`                   | Resumed. A sweep took the run away from a dead owner, and nothing is coming to claim it.                                        |
+| `approval`, `timer`, `quota` | Left parked. The run is waiting for a decision, a clock, or a budget that a message does not supply.                            |
+| absent                       | Left parked. A park with no reason is an operator's own park, and a message queued behind it is queued for when they resume it. |
+
+A reason this table does not name is left parked too: a control plane that
+cannot explain a park should not end it. The wake claims with
+`scope: "launched"`, so a run another driver created keeps its park and that
+driver delivers the steer at the run's next boundary. The steer is already
+durable either way.
+
+A successful wake journals `control.steer.woke` with the run's new status.
+
+## Refusals
+
+A steer whose `message.runId` names a different run than the call does is
+refused before anything is admitted:
+
+```text
+InvalidInput: message.runId: must be "run-17", received "run-18"
+```
+
+The notification would be admitted to the call's run while the stored message
+claimed another, so an operator reading it later would be told it belongs
+somewhere it was never delivered.
+
+A steer to a run that already reached `cancelled`, `completed`, or `failed`
+answers `Terminal` and stores nothing. Storing it anyway would leave an
+operator watching a message with no boundary left to deliver it.
+
+## Attribution over a wire
+
+`SteerMessage` carries a `principal` even though `cancel` refuses one on the
+wire, and the difference is who the callers are. A cancel is only ever an
+operator command, so the server can be its sole source of identity. A steer is
+not: `agent/send` steers a child run and attributes the message to the parent
+flow, which is an identity no authenticator knows and no operator issued.
+
+So the field stays, and `ControlServer` overwrites it with the authenticated
+principal on every steer that arrives over RPC. An in-process caller keeps
+naming its own. The value reaches the notification's `sourceActor` and the run
+transcript, which is exactly where a spoofed name would be read as truth.
+
+## Where to go next
+
+- [Watch a run's events](./watch-a-run.md): where both moments show up.
+- [Deliver a signal to a waiting run](./signal-a-run.md): the other way to
+  reach a parked run, and why it is not the same thing.
+- [`smthrs runs steer`](/cli/runs) and
+  [steering on smithers.sh](/docs/guides/steering/): the operator surface.

package/docs/guides/store-credentials.md

@@ -0,0 +1,164 @@
+---
+title: "Store and resolve a credential"
+description: "Keep a connection secret out of flow input, plan digests, journals, and model context: the reference that crosses the boundary, the store and cipher ports behind it, and the compare-and-set that serializes a rotation."
+sidebar:
+  order: 12
+---
+
+Credentials are capabilities. They must never enter flow input, plan digests,
+journal payloads, or model context, so only a `CredentialRef` crosses the
+browser-safe contract:
+
+```ts
+interface CredentialRef {
+  readonly id: string
+  readonly name: string
+}
+```
+
+Plaintext exists in exactly two places: inside a `Redacted` handed to `create`
+or `rotate`, and inside the `Redacted` returned by `resolve`.
+
+## Compose the boundary
+
+`Credential` composes two ports, and a host chooses an adapter for each:
+
+```ts
+import * as Credential from "@smthrs/control/Credential"
+import * as CredentialStore from "@smthrs/control/CredentialStore"
+import * as WebCryptoCipher from "@smthrs/control/WebCryptoCipher"
+import * as Layer from "effect/Layer"
+import * as Redacted from "effect/Redacted"
+
+const credentials = Credential.layer().pipe(
+  Layer.provide(Layer.merge(
+    CredentialStore.layerMemory,
+    WebCryptoCipher.layer({ key: Redacted.make(process.env["SMITHERS_CREDENTIAL_KEY"]!) })
+  ))
+)
+```
+
+| Port               | What it does                                                      | Adapters                                               |
+| ------------------ | ----------------------------------------------------------------- | ------------------------------------------------------ |
+| `CredentialStore`  | Persists an opaque sealed record, with compare-and-set on writes. | `layerMemory`, `SqlCredentialStore.layer`, `layerNoop` |
+| `CredentialCipher` | Seals and opens the secret under host-managed keys.               | `WebCryptoCipher.layer`, `layerNoop`                   |
+
+`Credential.layerNoop` is the whole boundary reporting `Unavailable`, which is
+the honest composition for a host with no credential storage.
+
+## Use it
+
+```ts
+const program = Effect.gen(function*() {
+  const credentials = yield* Credential.Credential
+
+  const reference = yield* credentials.create({
+    id: "github-webhook",
+    name: "GitHub webhook",
+    secret: Redacted.make(incomingSecret)
+  })
+
+  // Only this call sees plaintext again.
+  const secret = yield* credentials.resolve(reference)
+
+  const rotated = yield* credentials.rotate(reference, Redacted.make(nextSecret))
+  yield* credentials.revoke(rotated)
+})
+```
+
+`list` and `get` answer references. `resolve` is the one operation that crosses
+into a secret-bearing adapter boundary.
+
+## Authorization is the host's
+
+`Credential.layer({ authorize })` injects a policy hook, called with the
+operation and the reference before anything else runs:
+
+```ts
+Credential.layer({
+  authorize: (operation, reference) =>
+    operation === "resolve" && !Option.exists(reference, allowed)
+      ? Effect.fail(new Unauthorized({ message: "Not available to this caller" }))
+      : Effect.void
+})
+```
+
+The default allows every operation, which is correct for a single-principal
+local process. The six operations are `list`, `get`, `create`, `resolve`,
+`rotate`, and `revoke`.
+
+A reference is also _authenticated_ on every operation: caller-owned fields are
+snapshotted before policy effects run, and a forged or stale `CredentialRef` is
+refused because the snapshotted name must still match the stored record. The
+refusal for a missing credential and the refusal for a denied one are
+deliberately indistinguishable, because telling an unauthorized caller which
+ids exist is itself a leak.
+
+## What is stored, and what is not
+
+`SealedRecord` is everything at rest:
+
+| Field         | Meaning                                                      |
+| ------------- | ------------------------------------------------------------ |
+| `id`, `name`  | Opaque metadata, and the cipher's authenticated data.        |
+| `ciphertext`  | Base64, produced by the cipher.                              |
+| `nonce`       | Base64, per record, never reused across versions.            |
+| `version`     | Monotonic write counter, 1 for a freshly created credential. |
+| `updatedAtMs` | When the record was last written.                            |
+
+The key never reaches the store, so a stolen store is ciphertext and nothing
+else. `WebCryptoCipher` holds it as a non-extractable `CryptoKey`, so it cannot
+be read back out of the cipher either.
+
+The id, name, and version are written beside the blob _and_ authenticated with
+it, so moving a blob to another id, name, or version makes it unreadable.
+
+## Rotation is serialized
+
+Writes are compare-and-set on `version`. A writer that read version _n_ commits
+version _n + 1_; a concurrent writer that read the same _n_ is refused with
+`CredentialConflict` carrying both versions, rather than silently overwriting
+the winner.
+
+`SqlCredentialStore` does the read and the write in one transaction, so the
+version a writer read and the row it guards cannot interleave.
+
+## The key
+
+`WebCryptoCipher` uses AES-256-GCM over the Web Crypto API, which is the
+browser's own and has been Node's since v19, so this adapter imports nothing
+from `node:*` and runs unmodified on a server. `Options.key` is 32 raw bytes,
+base64-encoded, held redacted so it cannot be printed or serialized by
+accident.
+
+A host without Web Crypto, an old runtime or a locked-down worker, fails with
+the typed `Unavailable` rather than a defect. A key that is not 32
+base64-encoded bytes fails with `InvalidInput`.
+
+A record that does not open fails with `PersistenceError` on operation
+`credential.open`, and the host log records why. The message names a malformed
+stored nonce, or a failed authentication: the key is not the one that sealed
+the record, the record's id, name or version changed, or the ciphertext was
+tampered with.
+
+## Durable storage
+
+```ts
+import * as SqlCredentialStore from "@smthrs/control/SqlCredentialStore"
+
+const store = SqlCredentialStore.layer
+```
+
+It requires `DurableWriter` and `SqlClient`, and creates `control_credentials`
+on construction. The table is part of the package's
+[migration set](./durable-storage.md), so a host that composes that set has it
+already.
+
+## Where to go next
+
+- [Accept a webhook](./ingest-a-webhook.md): the caller that carries a
+  `CredentialRef` into a signature verifier.
+- [Store control state in a database](./durable-storage.md): the migration set
+  the credential table belongs to.
+- [Troubleshooting](../troubleshooting.md): what `Unavailable` and
+  `CredentialConflict` mean in practice.