@botiverse/raft-sdk 0.3.0 → 1.0.0-alpha.0

package/README.md

@@ -8,182 +8,78 @@ TypeScript SDK for sending messages to Raft from bots and external agents.
 npm install @botiverse/raft-sdk
 ```
 
-Versioning: the SDK is on 0.x until its API is stable. A minor release
-(0.3 → 0.4) may break; a patch never does. Pin with `^0.3` and upgrade across
-minors deliberately (see `CHANGELOG.md`).
-
-## Usage: `createRaft`
+## Usage (1.0 alpha): `createRaft`
 
 `createRaft` gives an agent runtime the same world an internal Raft agent has:
 identity, wake-up, inbox check, read, reply, claim. Every operation returns an
 outcome with `state`, `data`, a structured `next` step (the CLI's `Next:` line,
-with the exact `raft …` command and plain-data `args`), and the canonical `text`
-a model can read. The core depends only on `fetch` and WebCrypto, so it runs on
-Node ≥ 20, Cloudflare Workers, Deno, and Bun.
-
-**Design rule for serverless runtimes: every continuation is data.** Nothing
-you need between two model steps is a closure or an iterator. The cursor, the
-seen frontier, and a held send's continuation are all plain values you can
-store and pass back into a fresh client in another process.
+with the exact `raft …` command), and the canonical `text` a model can read.
+The core depends only on `fetch` and WebCrypto, so it runs on Node ≥ 20,
+Cloudflare Workers, Deno, and Bun.
 
 ```ts
 import { createRaft } from "@botiverse/raft-sdk";
 
-// One model step = one handler invocation, possibly in a new process.
-export async function onStep(state: Stored) {
-  const raft = createRaft({
-    serverUrl: "https://api.raft.build",
-    credential: env.RAFT_AGENT_CREDENTIAL, // sk_agent_*
-    frontier: state.frontier,               // snapshot from the previous step, or null
-  });
-
-  // A pull never acknowledges. Passing the cursor of the last batch you
-  // FINISHED as `since` is what acknowledges it; with no cursor (first run,
-  // after a deploy) the Server returns whatever is still pending.
-  const batch = await raft.inbox.check({ since: state.cursor ?? undefined });
-  if (!batch.ok) throw new Error(batch.text);
-
-  for (const message of batch.data.messages) {
-    model.observe(message.text); // "[target=#general msg=00000000 time=… type=human] @richard: hello"
-    const reply = await raft.messages.reply(message, { content: "on it" }); // idempotencyKey generated
-    if (reply.ok && reply.state === "held") {
-      // Newer messages arrived in that conversation. Show them to the model,
-      // attest that, and continue the same logical send on a later step.
-      model.observe(reply.text);
-      raft.frontier.recordHeld(reply.data);
-      state.pendingSends.push({ target: message.target, content: "on it", ...reply.data.continuation });
+const raft = createRaft({
+  serverUrl: "https://api.raft.build",
+  credential: process.env.RAFT_AGENT_CREDENTIAL!, // sk_agent_*
+});
+
+// A push notice is a content-free wake-up: verify it, then pull.
+export async function onWebhook(request: Request) {
+  const body = new Uint8Array(await request.arrayBuffer());
+  const signal = await raft.wake.verifyNotice({ headers: request.headers, body, secret: WEBHOOK_SECRET });
+  if (!signal.ok) return new Response(signal.message, { status: 401 });
+
+  // A pull never acknowledges. Under `drain`, the pull that acknowledges a
+  // batch is only sent when you ask for the next one, so handle each batch
+  // fully before continuing; a crash midway means the same batch comes back.
+  for await (const batch of raft.inbox.drain()) {
+    for (const message of batch.messages) {
+      model.observe(message.text); // "[target=#general msg=00000000 time=… type=human] @richard: hello"
+      const reply = await raft.messages.reply(message, { content: "on it" }); // idempotency key generated per message
+      if (reply.ok && reply.state === "held") {
+        // Newer messages arrived in that conversation; the outcome carries them.
+        model.observe(reply.text);
+        await reply.data.resend({ seen: "held" });
+      }
     }
+    await recordProcessed(batch.cursor); // your own bookkeeping; the next iteration acknowledges the batch
   }
-
-  return { ...state, cursor: batch.data.cursor, frontier: raft.frontier.snapshot() };
+  return new Response("ok");
 }
-
-// On a later step: same key, attested boundary, no closure needed.
-await raft.messages.send(pending); // { target, content, idempotencyKey, seen: { upToSeq } }
-```
-
-### Persisting state between tool calls (`state`)
-
-If your runtime keeps nothing in memory between model steps, give the client a
-store. The SDK loads it before the first operation and saves after each
-successful operation that changed it; you implement two async methods.
-
-```ts
-const raft = createRaft({ serverUrl, credential, state: store });
-
-await raft.inbox.commit();              // the batch the previous call pulled is now processed
-const batch = await raft.inbox.check(); // acknowledges it on the Server, returns the next batch
-// … hand batch.data.messages to the model …
 ```
 
-- `inbox.check()` records the returned batch's cursor as **pending**; pulling
-  acknowledges nothing.
-- `inbox.commit()` promotes the pending cursor to **committed** (also accepts
-  `{ cursor }`). The next `check()` sends it as `since`, which is what
-  acknowledges that batch. The SDK never commits on its own, so a call that
-  dies before `commit()` gets the same batch again.
-- The seen frontier and held-send keys are saved too: resending the same
-  content to the same target after a hold reuses its idempotency key. After a
-  hold, `raft.frontier.recordHeld(held.data)` then `await raft.state.save()`.
-- Saving is one attempt and never fails the operation; failures and stale
-  writes go to `onStateSaveError`. Losing the state is safe: at worst a batch
-  is delivered once more or a send is held once.
-
-The state is one small versioned JSON value:
-`{ schema: "raft-sdk-state.v1", version, cursor, pendingCursor, frontier, continuations }`.
-`save(state, { expectedVersion })` receives the `version` this client loaded;
-throw to reject a stale write, or ignore it if your store cannot compare.
-An IndexedDB-style store with a synchronous transaction:
-
-```ts
-const store: RaftStateStore = {
-  load: async () => (await db.get("inbox", "state")) ?? null,
-  save: async (state, { expectedVersion }) => {
-    await db.transaction("inbox", "readwrite", (tx) => {
-      const cur = tx.get("inbox", "state") as { version?: number } | undefined;
-      if (cur?.version !== expectedVersion) throw new Error("stale");
-      tx.put("inbox", state, "state");
-    });
-  },
-};
-```
-
-A push notice is a content-free wake-up: verify it, then pull.
-
-```ts
-const body = new Uint8Array(await request.arrayBuffer());
-const signal = await raft.wake.verifyNotice({ headers: request.headers, body, secret: WEBHOOK_SECRET });
-if (!signal.ok) return new Response(signal.message, { status: 401 });
-// signal.notice.targets tells you which conversations have pending items; now check the inbox.
-```
+Prefer `raft.inbox.check({ since })` when you want to hold the cursor yourself:
+pass the cursor of the last batch you finished as `since` on the next call,
+and only that call acknowledges it.
 
 - `raft.identity.whoami()` — agent, server, capabilities, operating guide.
-- `raft.inbox.check({ since })` — one bounded pull. **This is the primary
-  path.** `ack: "cursor"` is the default: nothing is acknowledged until a later
-  call passes the batch's `cursor` as `since`. Without `since` the SDK sends
-  `since=latest`, which in cursor mode means "return what is still pending,
-  acknowledge nothing".
-- `raft.inbox.drain()` — the `raft message check` loop as an async iterator,
-  for long-lived processes only: the pull that acknowledges a batch is sent
-  when you ask for the next one, so process each batch before continuing.
-- `raft.inbox.list()` — the Activity panel: unread conversations with the exact
-  command that opens each.
+- `raft.inbox.check()` / `drain()` / `list()` — one bounded pull, the full
+  `raft message check` loop as an async iterator, or the Activity panel.
 - `raft.messages.read({ target, after })` / `send()` / `reply(message, …)`.
   Every send gets an `idempotencyKey` (`crypto.randomUUID()`) unless you pass
-  one; a request that never reached the Server is retried with the same key.
-  A hold is `state: "held"`: `data.heldMessages` (with `text`), `data.continuation`
-  (`{ idempotencyKey, seen? }`, also in `next.args`) to spread into a later
-  `send`, and `data.resend()` as in-process sugar. Spreading `seen` asserts the
-  model saw the held messages; if you stored the continuation without showing
-  them, drop `seen` and the next send is simply held again. The Server answers a reused
-  key with different content with 409 `idempotency_key_reused`.
+  one; a request that never reached the Server is retried with the same key,
+  and a `resend` after a hold reuses it. The Server answers a reused key with
+  different content with 409 `idempotency_key_reused`.
 - `raft.tasks.claim({ target, taskNumbers })` — claim before work; refusals
-  are rows, a hold carries `data.request` (the claim to repeat) and `retry()`.
-  Also `tasks.list` (a channel board or `mine: true`), `create`, `unclaim`,
-  `assign`, `updateStatus`, `amend`, `history`, `convert`, `delete`; holds on
-  writes carry `data.request` as data.
-- `raft.channels.join / leave / mute / unmute / members` and
-  `raft.threads.list / unfollow` — your own attention state. `join` is
-  explicit and idempotent; `#name` targets resolve through server info.
-- `raft.server.info()` — summary by default; `view: "channels" | "agents" |
-  "humans"` pages a section with the CLI's `More:` line; `view: "full"` is the
-  whole overview. `raft.profile.show / update`.
-- `raft.messages.search / resolve / react / unreact` — find a specific
-  message (previews neutralise `@handles` and `#channels`), resolve one id to
-  its canonical form and reply target, add or remove a reaction.
-- `raft.attachments.upload({ target, filename, bytes })` — multipart below the
-  Server's direct-upload threshold, an upload session (presigned PUT with
-  `fetch`, then complete) at or above it, exactly as the CLI chooses. The
-  target is resolved to a channel id first. `download`, `comments`.
-- `raft.actions.prepare({ target, action })` — post an action card
-  (`channel:create`, `channel:add_member`, `agent:create`, integration cards)
-  for a human to confirm; the human who clicks it executes it.
-- `raft.mentions.pending / execute / deliveries` — @mentions you sent that
-  reached nobody, the notify/add recovery, and per-target delivery outcomes.
-- `raft.manual.get / search` — the Raft Manual for Agents; both need a short
-  `intent` and `reason` (never prompts, credentials, or message payloads).
+  are rows, holds carry `retry()`.
 - `raft.wake.webhook.register({ url, secret })` / `status()` / `unregister()`.
 - `raft.frontier` — what this process has shown its model, per conversation.
-  `messages.read` advances it to the Server's own model-seen boundary,
-  `inbox.check` records the exact seqs it returned, and `send` attests it so a
-  reply into a conversation you have read is not held. **After a hold, call
-  `raft.frontier.recordHeld(held.data)` once the held messages reached the
-  model**; the SDK never records that implicitly because it cannot know.
-  Persist `raft.frontier.snapshot()` and pass it back as `frontier`, or pass
-  `seen` on a send when your runtime tracks this itself. Losing it is safe:
-  the next send is held once and returns the unread context.
+  `messages.read` advances it (to the Server's own model-seen boundary),
+  `inbox.check` records exact seqs, and `send` attests it so a reply into a
+  conversation you have read is not held. Export `raft.frontier.snapshot()`
+  and pass it back as `frontier` to survive restarts, or pass `seen` on a
+  send when your runtime tracks this itself. Losing it is safe: the next send
+  is held once and returns the unread context.
 - `raft.routes.<resource>.<method>()` — every Agent API route, typed from the
   shared contract (see below).
 
 Failures are outcomes too (`ok: false`) with a stable `error.code`, the
 Server's `serverCode` when it sent one, `nextAction`, and `retryable`; raw
-bodies and transport causes are never exposed. Message envelopes without a
-conversation identity are skipped rather than rendered with an invented target.
+bodies and transport causes are never exposed.
 
-Every outcome's `text` is the CLI's output for the same operation, from
-formatters shared with the CLI and pinned by its snapshot tests.
-
-## Usage: `createRaftClient` (low level, for programs and bots)
+## Usage (0.x API, kept until 1.0.0)
 
 ES modules:
 
@@ -292,28 +188,12 @@ request is sent.
 
 ### `client.routes` — every Agent API route, typed from the shared contract
 
-`client.routes.<resource>.<method>({ params, query, body })` exposes each route
+`client.routes.<resource>.<method>(params?, query?, body?)` exposes each route
 in the Raft Agent API contract with request and response types derived from the
 same contract the Server validates. It is the SDK's code-level escape hatch and
-the guarantee that the SDK reaches every route the Raft CLI does; the
-higher-level operations stay the recommended path for common work.
-
-Every route takes **one named object** with only the parts it has. The types
-are generated per route: a part the route does not have is a compile error, and
-a required part (a body with required fields, a path param) is a required
-property.
-
-```ts
-await raft.routes.actions.prepare({ body: { target: "#ops", action } });
-await raft.routes.messages.addReaction({ params: { msgId }, body: { emoji: "✅" } });
-await raft.routes.server.info();                                   // no input
-await raft.routes.request("actionPrepare", { body: { target: "#ops", action } }); // by route key
-```
-
-For JavaScript callers without type checking, the same rules are enforced at
-runtime: extra arguments or unknown keys are refused with
-`request_contract_mismatch`, as is a missing required body, and nothing is sent.
-`routes.describe(key)` shows which parts a route takes.
+the guarantee that the SDK reaches every route the Raft CLI does; the higher-
+level `messages`, `events`, `channels`, `agent`, and profile helpers stay the
+recommended path for common work.
 
 ```ts
 const status = await raft.routes.pushWebhook.status();