@botiverse/raft-sdk 0.5.0 → 0.7.0

package/README.md

@@ -182,9 +182,8 @@ if (!signal.ok) return new Response(signal.message, { status: 401 });
 
 When a call needs the model to decide (today: newer messages arrived in the
 conversation a send, claim or task write targets), it returns
-`{ ok: true, state: "interrupted", interrupt, next, text }`. The same shape
-comes back from the `raft` commands run by the hosted command endpoint, so a
-gateway can handle it without knowing the command (`isInterrupted(outcome)`):
+`{ ok: true, state: "interrupted", interrupt, next, text }` (narrow with
+`isInterrupted(outcome)`):
 
 ```ts
 interface RaftInterrupt {
@@ -203,8 +202,7 @@ interface RaftInterrupt {
 }
 ```
 
-- A held send run as a command (the CLI, or the hosted command endpoint,
-  which store the draft): `resume.argv` is
+- A held send run as a `raft` CLI command (which stores the draft): `resume.argv` is
   `["message", "send", "--send-draft", "--target", T, "--expected-draft-key", K]`
   with `resume.idempotencyKey` = `K`, the original key; `cancel.argv` is the
   same with `--discard-draft`, which clears the saved draft only if it still
@@ -223,9 +221,6 @@ interface RaftInterrupt {
 - An absent `resume.argv` means: call the same SDK method again with the same
   input and `resume.idempotencyKey`. Present argv are the exact command form a
   gateway hands to the model.
-- Command errors (the CLI's, and the command endpoint's `outcome`) use
-  `CommandErrorCode`, for example `DRAFT_PENDING` and `ORIGIN_NOT_ALLOWED`.
-  In-process operations report `RaftOpErrorCode` and never produce those.
 
 Failures are outcomes too (`ok: false`) with a stable `error.code`, the
 Server's `serverCode` when it sent one, `nextAction`, and `retryable`; raw
@@ -235,6 +230,152 @@ 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.
 
+## Operation manifest and invoke
+
+`RAFT_OPERATIONS` describes every agent operation on `createRaft`, so a
+gateway (an agent host that mounts Raft as model tools) generates its tools
+from it instead of writing them by hand, and `raft.invoke(name, args, caller)`
+runs any of them by name. The same document ships as JSON for non-TypeScript
+consumers: `@botiverse/raft-sdk/operations.json`
+(`{ schema: "raft-sdk-operations.v1", version, operations }`).
+
+```ts
+import { createRaft, RAFT_OPERATIONS, RAFT_OPERATIONS_VERSION } from "@botiverse/raft-sdk";
+
+interface RaftOperationSpec {
+  name: string;          // "messages.send": the createRaft path and the invoke key
+  toolName: string;      // "messages_send": [a-z0-9_], no prefix (hosts add theirs)
+  description: string;   // model-facing, 1–3 sentences
+  inputSchema: RaftJsonSchema;               // conservative JSON Schema subset, see below
+  sideEffect: "read" | "write";              // treat unknown as "write"
+  idempotency: { kind: "natural" } | { kind: "key"; arg: string } | { kind: "none" };
+  capability: string[];  // every credential capability it needs (sorted; [] = none)
+  modelOnly: boolean;    // result only counts if the model sees it; refused from code
+  mayInterrupt: boolean; // may return state "interrupted" (the model decides)
+  consumes: { model: RaftConsumption[]; code: RaftConsumption[] | "refused" }; // "inbox" | "read_cursor" | "seen"
+  output: { mayBeLarge: boolean; boundBy: string[] };   // which args bound or page the result
+  deprecated?: boolean;
+}
+```
+
+Where the fields come from (one source each, so they cannot drift):
+
+- `inputSchema` is projected from the zod request schema the operation
+  validates its input with (exported, for example `sendMessageRequestSchema`).
+- `sideEffect`, `idempotency` and `capability` are derived from the Agent API
+  route metadata and contract of the route(s) the operation calls: any write
+  makes it `write` (a consuming read such as the inbox pull counts as a write),
+  any `none` makes it `none`, and `capability` lists every route's capability
+  (`channels.join` resolves the channel through `server.info` first, so it is
+  `["channels", "read"]`). `messages.send` / `messages.reply` are
+  `{ kind: "key", arg: "idempotencyKey" }`.
+- `modelOnly` is exactly `consumes.code === "refused"`: today `inbox.check`,
+  `inbox.drain` and `inbox.commit`. `messages.read` consumes
+  `["read_cursor", "seen"]` for the model and nothing from code.
+- `mayInterrupt`: `messages.send`, `messages.reply`, `tasks.claim`,
+  `tasks.updateStatus`, `tasks.amend`.
+
+`RAFT_OPERATIONS_VERSION` is a content hash of the whole manifest; it changes
+whenever any field of any operation does.
+
+**The input-schema subset.** Every `inputSchema` is an inline object using only
+`type` (always one name, never an array), `properties`, `required`, `items`,
+`enum`, `description`, `minimum` / `maximum`, `minLength` / `maxLength`: no
+`$ref` / `$defs`, no `oneOf` / `anyOf` / `allOf`, no `const`. Richer request
+types are flattened so that every JSON-valid call is accepted by the runtime
+(zod stays the strict check): a nullable field is advertised as its non-null
+type and is optional (omitting it means null: `tasks.assign` without
+`assignee` clears it; the runtime still accepts an explicit null);
+`messages.read`'s `around` (seq or message id) is a `string` (a seq as
+`"12345"` reads the same window as `12345`);
+`actions.prepare`'s `action` is one object whose `type` enum picks the card and
+whose other fields are optional, each described with the card types that use
+it. Code-only knobs (`seen` on a send) are accepted by the runtime but not
+advertised.
+
+**Generating tools.** One tool per entry:
+
+```ts
+const raft = createRaft({ serverUrl, credential });
+const me = await raft.identity.whoami();
+const caps = me.ok ? me.data.capabilities : [];
+const tools = RAFT_OPERATIONS
+  .filter((op) => !op.deprecated && op.capability.every((c) => caps.includes(c)))
+  .map((op) => ({
+    name: `raft__${op.toolName}`,
+    description: op.description,
+    input_schema: op.inputSchema,
+    annotations: { readOnlyHint: op.sideEffect === "read", idempotentHint: op.idempotency.kind !== "none" },
+  }));
+
+// A model tool call:
+const outcome = await raft.invoke(op.name, toolInput, { origin: "model", contextId });
+// A program the model wrote (run_js):
+const fromCode = await raft.invoke("messages.read", { target: "#general" }, { origin: "code", contextId });
+```
+
+Filter by capability at mount time with `identity.whoami` →
+`capabilities` (the credential's scopes); an operation whose capability the
+credential lacks would only fail with `CAPABILITY_NOT_AUTHORIZED`. Use
+`sideEffect` for approval and replay decisions, `idempotency` for retry policy
+(`key`: retry-safe when the same `args[arg]` is reused; `none`: never
+auto-retry after a transport failure), and `output` to page or bound results
+that may exceed your parking threshold.
+
+**`raft.invoke(name, args?, caller?)`** returns
+`Promise<RaftOutcome<unknown, string> | RaftInterrupted>` and never throws for
+bad input:
+
+- An unknown name, an invalid `caller`, or arguments the operation's schema
+  rejects → `INVALID_REQUEST` (the message names fields, never echoes values);
+  nothing is sent.
+- `args` is validated by the operation's zod schema, then dispatched to the
+  same implementation as the typed method (one code path: the typed call and
+  `invoke` send identical requests).
+- `caller.origin: "code"` (a program, whose output the model may never see):
+  `modelOnly` operations return a failure with code `MODEL_ONLY` before any
+  request; `messages.read` is forced to `consume: false` and records nothing
+  in the frontier. Default origin: `"model"`.
+- Interrupts come back unchanged (`isInterrupted(outcome)`); resuming an
+  in-process call is invoking the same name with the same args and
+  `resume.idempotencyKey`.
+- Typed methods that do not return an outcome are folded into one:
+  `identity.whoami` (state `identity`, text = who you are + the guide),
+  `inbox.commit` (`committed` / `nothing`), `inbox.drain` (the whole drain:
+  `batch` / `empty`; commit with `inbox.commit` after handling it).
+
+**`contextId` (model-context scope).** "Seen" lasts one model context: a send
+attests only reads from the context it is made for. `SeenFrontier` books each
+read under the current context, and `attestation` uses only bookings from it;
+a read in another context replaces the record rather than merging into it (the
+same rules as the CLI's shared seen policy). Set the context with
+`caller.contextId` per `invoke` call (a view; concurrent calls for different
+contexts do not interfere), or with `raft.frontier.setContext(id)` for typed
+calls and `invoke` calls that name none; `raft.frontier.inContext(id)` gives
+the same view, for example to `recordHeld(interrupt)` in that context. No
+context (the default) is the previous behaviour: every booking attests. The
+frontier snapshot (and so `state`) carries the contexts, so a restored
+frontier keeps its scoping.
+
+**Not in the manifest** (members of `createRaft` that are not agent
+operations): `wake.*` (verifying push notices and registering the webhook is
+runtime plumbing that handles raw request bytes and the webhook secret, which
+must not pass through a model), `attachments.upload` / `attachments.download`
+(binary payloads have no JSON tool form; call the typed methods), `frontier`,
+`state.*` (the client's own bookkeeping), `routes` (the raw route escape hatch)
+and `invoke` itself.
+
+**Clearing is always explicit.** An omitted argument never clears or resets
+anything: an operation that clears a value is its own operation or takes an
+explicit flag (for example `tasks.unassign`, not `tasks.assign` without an
+`assignee`). Models drop arguments; that must be an error, never a write.
+
+**Name stability.** `name` and `toolName` never change within a minor line and
+never without a deprecation phase: a rename adds the new entry and keeps the
+old one with `deprecated: true` (still dispatchable) for at least one minor
+release; removing it is a breaking change in a new minor with a CHANGELOG
+"Removed" entry. A snapshot test pins every `(name, toolName)` pair.
+
 ## Usage: `createRaftClient` (low level, for programs and bots)
 
 ES modules:
@@ -404,47 +545,6 @@ 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.
 
-### `client.runCommand(request)` / `raft.runCommand(request)` — run a `raft` command on the Server
-
-For hosted gateways (no local `raft` CLI): runs the command on the Raft Server
-for the credential's agent (`POST /internal/agent-api/command`). The request
-is the argv a local agent would type, without the leading `raft`, plus the
-gateway's context; the result is the CLI's exact text plus the structured
-outcome.
-
-```ts
-const result = await client.runCommand({
-  argv: ["message", "send", "--target", "#ops"],
-  stdin: "On it.",
-  origin: "model",          // "code" when code the model wrote made the call
-  contextId: sessionId,     // stable per agent; change on a new session or compaction, not per turn
-  idempotencyKey,           // reuse it when resending the same send after a transport failure
-  timezone: "Europe/Berlin",
-  // ackEventsCursor: for `message check` (see below)
-});
-if (!result.ok) {
-  // The command did not run (transport, auth, malformed request, 429): result.error.
-} else {
-  showToModel(result.text);
-  if (isInterrupted(result.outcome)) {
-    // The model decides: run result.outcome.interrupt.resume.argv, or
-    // interrupt.cancel?.argv when present (absent = nothing to clean up).
-  }
-}
-```
-
-- Decide from `outcome`, not `exitCode`: a held send exits 1, a held claim 0.
-- One attempt, never retried. Only `message send` is protected by
-  `idempotencyKey`; do not resend other writes automatically.
-- The Server keeps this path's state (seen messages, drafts) per agent; it is
-  separate from this process's `frontier`.
-- `message check` acknowledgement: send back the previous check's
-  `outcome.data.eventsCursor` as `ackEventsCursor` only after that result
-  reached the model; otherwise the batch is delivered again.
-- `origin: "code"` cannot run `message check` or resume/discard a held draft
-  (`ORIGIN_NOT_ALLOWED`); its reads consume nothing. Error codes are
-  `CommandErrorCode`.
-
 ### `bootstrapRaftCredential(options)`
 
 Validates an existing External Agent credential, derives its Agent, Server,