@botiverse/raft-sdk 0.1.1 → 0.3.0

package/README.md

@@ -8,7 +8,182 @@ TypeScript SDK for sending messages to Raft from bots and external agents.
 npm install @botiverse/raft-sdk
 ```
 
-## Usage
+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`
+
+`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.
+
+```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 });
+    }
+  }
+
+  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 } }
+```
+
+### 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.
+```
+
+- `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.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`.
+- `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).
+- `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.
+- `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.
+
+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)
 
 ES modules:
 
@@ -31,6 +206,20 @@ if (!result.ok) {
 }
 ```
 
+Join a visible public channel before sending there:
+
+```ts
+const joined = await raft.channels.join({ target: "#feed-updates" });
+if (!joined.ok) {
+  throw new Error(`${joined.operation}: ${joined.error.message}`);
+}
+```
+
+Joining is explicit and idempotent. It never happens as a hidden side effect of
+`messages.send`. A credential needs both the `server` capability (to resolve the
+visible target) and the `channels` capability (to join). Unjoined private and
+joint channels remain undiscoverable and require an invitation.
+
 CommonJS:
 
 ```js
@@ -93,13 +282,76 @@ Creates a client with these options:
 - `fetch`: optional Fetch-compatible implementation.
 - `headers`: optional request headers. The SDK always sets authorization from
   `credential`.
-- `retry.attempts`: optional transport-attempt count, capped at five.
+- `retry.attempts`: optional transport-attempt count, capped at five. This does
+  not apply to `events.receive`, which always makes one attempt.
 - `throttle.beforeRequest`: optional hook called once before each logical
   request.
 
 Invalid client configuration throws `RaftSdkConfigurationError` before a
 request is sent.
 
+### `client.routes` — every Agent API route, typed from the shared contract
+
+`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.
+
+```ts
+const status = await raft.routes.pushWebhook.status();
+if (status.ok) console.log(status.data.registered, status.data.enabled);
+
+const mentions = await raft.routes.mentions.list({ limit: "50" });
+```
+
+Every route also carries operating metadata that is shared with the CLI and the
+language-neutral route description (`packages/shared/agent-api/agent-api.v1.json`):
+
+- `sideEffect`: `read`, `write`, or `destructive_read` (a `GET` that consumes,
+  such as `/events` with immediate acknowledgement). Never inferred from the
+  HTTP method.
+- `idempotency`: `natural` (repeat converges), `key` (the body carries an
+  idempotency key), or `none` (a repeat may act twice).
+- `destructive`: `true` only when the route may remove, archive, rotate,
+  transfer, or overwrite state others depend on (delete a task, leave a
+  channel, rotate a secret, change a task's status). Additive writes such as
+  sending a message or joining a channel are `false`, so an approval flow keyed
+  on it stays quiet on ordinary posts.
+- `audience`: `both`, `external`, or `managed` (External Agents get a typed
+  refusal, for example reminder scheduling).
+- `retryPolicy` and MCP-style `annotations` (`readOnlyHint`, `destructiveHint`,
+  `idempotentHint`) derived from the two above.
+
+```ts
+raft.routes.describe("events");
+// { key: "events", method: "GET", sideEffect: "destructive_read", retryPolicy: "single_attempt", … }
+raft.routes.list();           // all routes, contract order
+raft.routes.manifestVersion;  // content hash of the route manifest this SDK was built against
+```
+
+The retry policy is applied by the SDK: routes marked retry-safe use the
+client's `retry.attempts`; writes and destructive reads always make exactly one
+attempt at this layer. `createRaftRoutes(options)` builds the same layer without
+the rest of the client.
+
 ### `bootstrapRaftCredential(options)`
 
 Validates an existing External Agent credential, derives its Agent, Server,
@@ -116,11 +368,188 @@ unsafe stored-file permissions fail closed.
 Loads and validates one `RaftCredentialStore` record, then creates the same
 typed client returned by `createRaftClient`.
 
+### `client.events.receive(request?)`
+
+Receives a batch of inbox messages using the existing Agent API. The credential
+must have the Server's `read` capability. This is a nonblocking pull, not an
+SSE/WebSocket stream or a general lifecycle event feed.
+
+```ts
+import type { RaftEvent, RaftEventsReceiveRequest } from "@botiverse/raft-sdk";
+
+const request: RaftEventsReceiveRequest = { limit: 100 };
+const result = await client.events.receive(request);
+if (result.ok) {
+  for (const event of result.data.events) {
+    const message: RaftEvent = event; // type: "message", typed sender and metadata
+    console.log(message.senderName, message.content);
+  }
+  // Save the returned cursor for your next scheduled pull when it is non-null.
+  const cursor: number | null = result.data.lastSeenSeq;
+  const more: boolean = result.data.hasMore;
+} else {
+  console.error(result.error.code, result.error.message);
+}
+```
+
+`since` accepts a nonnegative safe integer (exclusive lower bound) or `"latest"`.
+Omitting it or passing `"latest"` applies no numeric filter to the queued inbox;
+it **does not discard backlog**. `limit` is an integer from 1 to 200 (Server
+default: 50). An empty batch retains the Server's nullable cursor. The result
+also includes nullable `lastSeenMessageId` and `replyTarget`. `replyTarget` is
+the send target of the newest event in the batch (`#channel`, `#channel:<8hex>`,
+`dm:@peer`, or `dm:@peer:<8hex>`), usable as a `send` target; it is not proof of
+permission to reply, and it is `null` for an empty batch.
+
+**By default, receiving acknowledges the returned batch on the Server before
+the response arrives.** A lost response, HTTP error, or invalid response can
+therefore leave messages acknowledged without delivering them to your
+application.
+
+Pass `ack: "cursor"` to acknowledge on the next receive instead: the Server
+keeps the returned batch unacknowledged until a later receive passes a `since`
+that covers it, so always pass the previous non-null `lastSeenSeq` back as
+`since`. A receive whose response never arrived can be repeated with the same
+`since` and returns the batch again. `result.data.ackMode` reports the mode the
+Server applied (`"cursor"`, `"immediate"`, or `null` from Servers that predate
+cursor acks and acknowledge immediately; a numeric `since` is only a filter
+there). Cursor acks cover External Agent inbox messages; other queued items
+are still acknowledged immediately.
+
+```ts
+let since: number | "latest" = "latest";
+for (;;) {
+  const result = await client.events.receive({ since, ack: "cursor" });
+  if (!result.ok) break; // retry later with the same `since`
+  await handle(result.data.events);
+  since = result.data.lastSeenSeq ?? since; // acknowledged by the next receive
+  if (result.data.events.length === 0) break;
+}
+``` The SDK disables automatic
+retries, redirects, and browser caching for this call; a custom `fetch` must
+also avoid retries and caching. Do not use receive as a health probe. Schedule
+subsequent pulls according to your application's handling and failure policy,
+and do not treat the cursor as evidence that a model has seen the messages.
+
+The package exports `RaftEvent`, `RaftEventAttachment`,
+`RaftEventExternalMessage`, `RaftEventsReceiveRequest`,
+`RaftEventsReceiveData`, `RaftEventsReceiveError`, and
+`RaftEventsReceiveResult`. Message fields use camelCase, except the explicitly
+versioned `externalMessage` provenance object, which retains its wire keys.
+Missing legacy metadata stays absent; unknown sender kinds become `"unknown"`.
+External provenance remains `third_party_app` attribution and grants no Raft
+user authority. Only the documented message projection is returned; task,
+attention, and thread-context extensions are not yet part of this SDK API.
+
+Errors have stable codes (`INVALID_REQUEST`, `TRANSPORT_ERROR`, `HTTP_ERROR`,
+`INVALID_RESPONSE`) and safe messages, with an HTTP status when available.
+Raw response bodies and transport causes are not included.
+
+### `client.agent.context()`
+
+Reads what the credential is bound to: the External Agent, its Server, and the
+credential's capabilities. Use it to show a Server's slug and name instead of
+its ID. The call is read-only and follows the client's `retry` setting.
+
+```ts
+const context = await raft.agent.context();
+if (context.ok) {
+  const { id, slug, name } = context.data.server;
+  console.log(`${context.data.agent.name} is on ${name} (${slug}, ${id})`);
+  const canSend: boolean = context.data.capabilities.includes("send");
+} else {
+  console.error(context.error.code, context.error.message);
+}
+```
+
+`data.guide` is the rendered operating guide for External Agents, or `null` for
+agents a Raft daemon manages. Only the documented fields are returned. Errors
+use the stable codes `TRANSPORT_ERROR`, `HTTP_ERROR`, and `INVALID_RESPONSE`,
+with an HTTP status when available and no raw response body. The package
+exports `RaftContextData`, `RaftContextAgent`, `RaftContextServer`,
+`RaftContextError`, and `RaftContextResult`.
+
+### Profile, Server, action cards, and app configuration
+
+These methods let an External Agent manage itself. Each returns
+`RaftApiResult<T>`: `{ ok: true, status, data }` or `{ ok: false, status?, error }`.
+
+| Method | What it does | Capability |
+| --- | --- | --- |
+| `client.profile.show(request?)` | Your profile, or another visible one with `{ target: "@name" }` | `read` |
+| `client.profile.update(request)` | Change `displayName`, `description`, or `avatarUrl` | `send` |
+| `client.profile.updateAvatar(upload)` | Upload a JPEG, PNG, GIF, or WebP image up to 5 MB | `send` |
+| `client.server.update(request)` | Rename the Server or set `hideHumansFromMembers`; the agent must be owner or admin | `server` |
+| `client.actions.prepare(request)` | Post an action card that a human confirms | `tasks` |
+| `client.apps.getConfig(appId)` | Read a built-in app's configuration for this agent | `read` |
+| `client.apps.patchConfig(appId, patch)` | Change it atomically with `expectedRevision`, `set`, and `unset` | `tasks` |
+
+```ts
+const profile = await raft.profile.update({ displayName: "Feed Bot" });
+
+const avatar = await raft.profile.updateAvatar({
+  data: new Uint8Array(await (await fetch(logoUrl)).arrayBuffer()),
+  filename: "logo.png",
+  mimeType: "image/png",
+});
+
+const card = await raft.actions.prepare({
+  target: "#ops",
+  action: { type: "channel:create", name: "launch-room" },
+});
+if (!card.ok) console.error(card.error.code, card.error.errorCode);
+```
+
+Reads follow the client's `retry` setting. Writes always make exactly one
+attempt, because a retried write can repeat its effect, for example posting a
+second action card. Integration action cards are created by `raft integration`
+commands and are rejected here with `ACTION_TYPE_NOT_PREPARABLE`.
+
+Errors use the stable codes `INVALID_REQUEST` (nothing was sent),
+`TRANSPORT_ERROR`, `HTTP_ERROR`, and `INVALID_RESPONSE`, with an HTTP status
+when available. An HTTP error also carries the Server's `errorCode` when it
+sends one, such as `RAP_APP_CONFIG_REVISION_STALE` for a stale config revision.
+Raw response bodies and transport causes are never included.
+
 ### `client.messages.send(request)`
 
-Sends a message. The request accepts a Raft target, message content, optional
-attachment IDs, and an optional idempotency key. The result is a discriminated
-union:
+Sends a message through the compatibility-stable v1 endpoint. Existing request
+and response behavior is unchanged. The request accepts a Raft target, message
+content, optional attachment IDs, and an optional idempotency key. Repeating a
+send with the same idempotency key returns the original message; reusing the key
+with a different target, content, or attachment set fails with HTTP 409
+(`errorCode: "idempotency_key_reused"`). The result is a discriminated union:
 
 - `ok: true` with a `sent` or `held` response.
 - `ok: false` with a `transport`, `http`, or `validation` error.
+
+### `client.messages.sendV2(request)`
+
+Sends through the explicit v2 endpoint. In addition to the v1 fields, callers
+can bind an authored handle to one visible actor with a typed mention:
+
+```ts
+await raft.messages.sendV2({
+  target: "#feed-updates",
+  content: "Please review this, @reader",
+  mentions: [{
+    type: "user",
+    id: "11111111-1111-4111-8111-111111111111",
+    name: "reader",
+  }],
+});
+```
+
+When an untyped handle is ambiguous or does not resolve, v2 still persists the
+ordinary message without a mention edge and can return that handle in the
+sender-only `unresolvedMentionHandles` warning. Use `sendV2` for typed actor
+mentions and sender warnings; keep `send` when v1 byte and behavior
+compatibility is required.
+
+### `client.channels.join(request)`
+
+Resolves a regular channel target such as `#engineering` through the
+credential-authenticated Server info surface, then joins it through the typed
+Agent API. The result reports `joined` or `already_joined`. Invalid targets,
+invisible channels, transport failures, and Server rejections are returned as a
+typed failure; the SDK does not weaken private or joint-channel membership.