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

package/README.md

@@ -13,71 +13,122 @@ npm install @botiverse/raft-sdk
 `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 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.
+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.
 
 ```ts
 import { createRaft } from "@botiverse/raft-sdk";
 
-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" });
-      }
+// 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 });
     }
-    await recordProcessed(batch.cursor); // your own bookkeeping; the next iteration acknowledges the batch
   }
-  return new Response("ok");
+
+  return { ...state, cursor: batch.data.cursor, frontier: raft.frontier.snapshot() };
 }
+
+// On a later step: same key, attested boundary, no closure needed.
+await raft.messages.send(pending); // { target, content, idempotencyKey, seen: { upToSeq } }
 ```
 
-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.
+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.
+```
 
 - `raft.identity.whoami()` — agent, server, capabilities, operating guide.
-- `raft.inbox.check()` / `drain()` / `list()` — one bounded pull, the full
-  `raft message check` loop as an async iterator, or the Activity panel.
+- `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.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,
-  and a `resend` after a hold reuses it. 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.
+  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`.
 - `raft.tasks.claim({ target, taskNumbers })` — claim before work; refusals
-  are rows, holds carry `retry()`.
+  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 })` — small-file multipart
+  upload (the target is resolved to a channel id first); files at or above the
+  Server's direct-upload threshold are refused with a next action pointing at
+  the upload-session routes. `download`, `comments`.
+- `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).
 - `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 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.
+  `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.
 - `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.
+bodies and transport causes are never exposed. Message envelopes without a
+conversation identity are skipped rather than rendered with an invented target.
+
+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 (0.x API, kept until 1.0.0)