@botiverse/raft-sdk 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -332,11 +332,28 @@ interface AgentApiToolAnnotations {
  */
 type AgentApiRetryPolicy = "retry" | "retry_when_keyed" | "single_attempt";
 //#endregion
+//#region ../shared/src/agentOps/hint.d.ts
+/** How hints are rendered: `cli` (default) as `raft …` commands, `tool` as operation tool calls. */
+type RaftHintStyle = "cli" | "tool";
+/** The operation a next step maps to: manifest name and arguments in manifest shape. */
+interface RaftNextOperation {
+  /** Manifest name (`RAFT_OPERATIONS`), for example `messages.read`. */
+  name: string;
+  args: Record<string, unknown>;
+  /** Some required arguments are left for the caller (for example a message's `content`). */
+  partial?: true;
+}
+/** `tasks.updateStatus` → `tasks_update_status`: the manifest's tool name for an operation name. */
+export declare function raftToolNameFor(name: string): string;
+//#endregion
 //#region ../shared/src/agentOps/outcome.d.ts
 interface RaftNextStep {
   /** Stable step kind, for example `read_target`, `run_inbox_check`, `retry_after_review`. */
   kind: string;
-  /** The exact CLI command an agent would run for this step, when one exists. */
+  /**
+   * The exact CLI command an agent would run for this step, when one exists;
+   * with `createRaft({ hints: "tool" })`, the tool call instead.
+   */
   command?: string;
   /**
    * Structured arguments for the step: plain, serialisable data (never a
@@ -345,6 +362,12 @@ interface RaftNextStep {
    * (An interrupted call's resume is `interrupt.resume`, not `args`.)
    */
   args?: Record<string, unknown>;
+  /**
+   * The manifest operation that takes this step, with its arguments in
+   * manifest shape (valid for that operation's schema). `partial: true` when
+   * some required arguments are the caller's to supply (a send's `content`).
+   */
+  operation?: RaftNextOperation;
   /** One sentence explaining why this is the next step. */
   why: string;
 }
@@ -424,9 +447,9 @@ interface RaftMessage {
  */
 export declare function hasAgentMessageIdentity(envelope: AgentApiMessageEnvelope): boolean;
 /** Project one envelope; `null` when it has no conversation identity (skip it rather than render `#undefined`). */
-export declare function projectRaftMessage(envelope: AgentApiMessageEnvelope): RaftMessage | null;
+export declare function projectRaftMessage(envelope: AgentApiMessageEnvelope, style?: RaftHintStyle): RaftMessage | null;
 /** Project a list, skipping envelopes without a conversation identity. */
-export declare function projectRaftMessages(envelopes: readonly AgentApiMessageEnvelope[]): RaftMessage[];
+export declare function projectRaftMessages(envelopes: readonly AgentApiMessageEnvelope[], style?: RaftHintStyle): RaftMessage[];
 //#endregion
 //#region ../shared/src/agentOps/interrupt.d.ts
 /** Why the call stopped. */
@@ -666,7 +689,7 @@ interface RaftInboxConversation {
   activitySeq: number;
   latestSenderName: string | null;
   latestAt: string | null;
-  /** The exact command that opens this conversation from the agent's read position. */
+  /** The exact command that opens this conversation from the agent's read position (the tool call with `hints: "tool"`). */
   openCommand: string;
 }
 interface RaftInboxListing {
@@ -878,6 +901,19 @@ interface CreateTasksRequest {
   }>;
   /** `@handle`; yourself to start in_progress, or (owner/admin) someone else to reserve a todo. */
   assignee?: string;
+  /**
+   * One key per logical create. Generated with `crypto.randomUUID()` when
+   * omitted and returned as `data.idempotencyKey` (and, on a retryable
+   * failure, as `next.args.idempotencyKey`). Repeating the same request with
+   * the same key returns the first result (same task numbers) and creates
+   * nothing; the same key with a different request fails with
+   * `IDEMPOTENCY_KEY_REUSED`. A key is valid for 24 hours: retry within that
+   * window; after it the Server forgets the key and the same request creates
+   * again. The SDK never retries on its own: Servers
+   * without keyed task create ignore the key, and a repeat there creates the
+   * tasks again.
+   */
+  idempotencyKey?: string;
 }
 export declare const createTasksRequestSchema: z.ZodObject<{
   target: z.ZodString;
@@ -886,9 +922,12 @@ export declare const createTasksRequestSchema: z.ZodObject<{
     createsResource: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$strip>>;
   assignee: z.ZodOptional<z.ZodString>;
+  idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type RaftTasksCreated = AgentApiTaskCreateResponse & {
   target: string;
+  /** The key this create was sent with (the caller's, or the generated one). */
+  idempotencyKey: string;
 };
 interface TaskRef {
   target: string;
@@ -1087,6 +1126,8 @@ interface ServerInfoRequest {
   limit?: number;
   /** Channels only: restrict to joined channels. */
   joined?: boolean;
+  /** Sections only: keep rows whose visible text contains this (case-insensitive), like the CLI's `--query`. */
+  query?: string;
 }
 export declare const serverInfoRequestSchema: z.ZodObject<{
   view: z.ZodOptional<z.ZodEnum<{
@@ -1099,6 +1140,7 @@ export declare const serverInfoRequestSchema: z.ZodObject<{
   offset: z.ZodOptional<z.ZodNumber>;
   limit: z.ZodOptional<z.ZodNumber>;
   joined: z.ZodOptional<z.ZodBoolean>;
+  query: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const showProfileRequestSchema: z.ZodObject<{
   target: z.ZodOptional<z.ZodString>;
@@ -1152,6 +1194,9 @@ export declare const attachmentCommentsRequestSchema: z.ZodObject<{
   attachmentId: z.ZodString;
   limit: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+export declare const downloadAttachmentUrlRequestSchema: z.ZodObject<{
+  attachmentId: z.ZodString;
+}, z.core.$strip>;
 /** Explicit type wins; otherwise sniff the bytes, then the filename extension, then octet-stream. */
 export declare function inferAttachmentMimeType(filename: string, bytes: Uint8Array, explicit?: string | null): string;
 interface UploadAttachmentRequest {
@@ -1170,6 +1215,8 @@ interface RaftAttachmentBytes {
   attachmentId: string;
   bytes: Uint8Array;
 }
+/** A short-lived download URL: what a runtime fetches the bytes from itself (`attachments.downloadUrl`). */
+type RaftAttachmentDownloadUrl = Pick<AgentApiAttachmentDownloadUrlResponse, "url" | "expiresAt" | "filename" | "mimeType">;
 //#endregion
 //#region ../shared/src/agentOps/search.d.ts
 interface SearchMessagesRequest {
@@ -1330,6 +1377,15 @@ export declare function parseRaftState(value: unknown): RaftState | null;
 export declare function hashRaftSendContent(target: string, content: string, attachmentIds?: readonly string[]): Promise<string>;
 //#endregion
 //#region ../shared/src/agentOps/actions.d.ts
+/**
+ * `idempotencyKey`: one key per logical prepare. Generated with
+ * `crypto.randomUUID()` when omitted and returned as `data.idempotencyKey`
+ * (and, on a retryable failure, as `next.args.idempotencyKey`). Repeating the
+ * same request with the same key returns the first card (same `messageId`)
+ * and posts nothing; the same key with a different request fails with
+ * `IDEMPOTENCY_KEY_REUSED`. A key is valid for 24 hours; after that the
+ * Server forgets it. Servers without keyed prepare ignore the key.
+ */
 type PrepareActionCardRequest = AgentApiActionPrepareBody;
 /**
  * The Agent API's own body schema (a discriminated union over the card
@@ -1412,11 +1468,14 @@ export declare const prepareActionCardRequestSchema: import("zod").ZodObject<{
     targetAgent: import("zod").ZodString;
     draftHint: import("zod").ZodOptional<import("zod").ZodString>;
   }, import("zod/v4/core").$strip>], "type">;
+  idempotencyKey: import("zod").ZodOptional<import("zod").ZodString>;
 }, import("zod/v4/core").$loose>;
 interface RaftPreparedCard {
   target: string;
   /** The card message; a human commits it by clicking its action verb. */
   messageId: string;
+  /** The key this prepare was sent with (the caller's `idempotencyKey`, or the generated one). */
+  idempotencyKey: string;
 }
 //#endregion
 //#region ../shared/src/agentApiRawClient.d.ts
@@ -1967,6 +2026,18 @@ declare const agentApiChannelLifecycleBodySchema: z.ZodObject<{
 declare const agentApiAttachmentDownloadParamsSchema: z.ZodObject<{
   attachmentId: z.ZodString;
 }, z.core.$loose>;
+/**
+ * Short-lived download URL for an attachment visible to the bound agent
+ * credential (`GET /attachments/:attachmentId/url`). For runtimes that cannot
+ * take binary tool results: the agent fetches the bytes itself from `url`
+ * before `expiresAt`. The URL is a bearer capability; never log it.
+ */
+declare const agentApiAttachmentDownloadUrlResponseSchema: z.ZodObject<{
+  url: z.ZodString;
+  expiresAt: z.ZodString;
+  filename: z.ZodString;
+  mimeType: z.ZodString;
+}, z.core.$loose>;
 declare const agentApiAttachmentCommentsParamsSchema: z.ZodObject<{
   attachmentId: z.ZodString;
 }, z.core.$loose>;
@@ -2112,6 +2183,7 @@ declare const agentApiTaskCreateBodySchema: z.ZodObject<{
     creates_resource: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$loose>>;
   assignee: z.ZodOptional<z.ZodString>;
+  idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 declare const agentApiTaskUnclaimBodySchema: z.ZodObject<{
   channel: z.ZodString;
@@ -2393,6 +2465,7 @@ declare const agentApiActionPrepareBodySchema: z.ZodObject<{
     targetAgent: z.ZodString;
     draftHint: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>], "type">;
+  idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 declare const agentApiServerUpdateBodySchema: z.ZodObject<{
   name: z.ZodOptional<z.ZodString>;
@@ -6151,6 +6224,7 @@ declare const agentApiContract: {
           creates_resource: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
         assignee: z.ZodOptional<z.ZodString>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
       }, z.core.$loose>;
     };
     readonly response: {
@@ -7993,6 +8067,7 @@ declare const agentApiContract: {
           targetAgent: z.ZodString;
           draftHint: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>], "type">;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
       }, z.core.$loose>;
     };
     readonly response: {
@@ -8233,6 +8308,32 @@ declare const agentApiContract: {
   } & {
     fullPath: string;
   };
+  readonly attachmentDownloadUrl: {
+    readonly key: "attachmentDownloadUrl";
+    readonly method: "GET";
+    readonly path: "/attachments/:attachmentId/url";
+    readonly client: {
+      readonly resource: "attachments";
+      readonly method: "downloadUrl";
+    };
+    readonly capability: "read";
+    readonly description: "Mint a short-lived (5 minute) download URL for an attachment visible to the bound agent credential, with its filename and MIME type. 409 download_url_unavailable when this Server's storage cannot presign; use the binary download instead.";
+    readonly request: {
+      readonly params: z.ZodObject<{
+        attachmentId: z.ZodString;
+      }, z.core.$loose>;
+    };
+    readonly response: {
+      readonly body: z.ZodObject<{
+        url: z.ZodString;
+        expiresAt: z.ZodString;
+        filename: z.ZodString;
+        mimeType: z.ZodString;
+      }, z.core.$loose>;
+    };
+  } & {
+    fullPath: string;
+  };
   readonly attachmentCommentsList: {
     readonly key: "attachmentCommentsList";
     readonly method: "GET";
@@ -8485,6 +8586,7 @@ type AgentApiAttachmentUploadSessionCreateResponse = z.infer<typeof createAttach
 type AgentApiAttachmentUploadSessionCompleteResponse = z.infer<typeof completeAttachmentUploadSessionResponseSchema>;
 type AgentApiAttachmentUploadSessionResponse = z.infer<typeof attachmentUploadSessionSchema>;
 type AgentApiAttachmentDownloadResponse = Uint8Array;
+type AgentApiAttachmentDownloadUrlResponse = z.infer<typeof agentApiAttachmentDownloadUrlResponseSchema>;
 interface AgentApiEventsInboxHint {
   unread_conversations: number;
   command: "raft inbox check";
@@ -8677,6 +8779,7 @@ type AgentApiRequestParamsByRoute = {
   messageReactionAdd: AgentApiMessageReactionParams;
   messageReactionRemove: AgentApiMessageReactionParams;
   attachmentDownload: AgentApiAttachmentDownloadParams;
+  attachmentDownloadUrl: AgentApiAttachmentDownloadParams;
   attachmentCommentsList: AgentApiAttachmentCommentsParams;
   channelJoin: AgentApiChannelMembershipParams;
   channelLeave: AgentApiChannelMembershipParams;
@@ -8757,6 +8860,7 @@ type AgentApiRequestQueryByRoute = {
   messageReactionAdd: never;
   messageReactionRemove: never;
   attachmentDownload: never;
+  attachmentDownloadUrl: never;
   attachmentCommentsList: AgentApiAttachmentCommentsQuery;
   channelJoin: never;
   channelLeave: never;
@@ -8837,6 +8941,7 @@ type AgentApiRequestBodyByRoute = {
   messageReactionAdd: AgentApiMessageReactionBody;
   messageReactionRemove: AgentApiMessageReactionBody;
   attachmentDownload: never;
+  attachmentDownloadUrl: never;
   attachmentCommentsList: never;
   channelJoin: never;
   channelLeave: never;
@@ -8917,6 +9022,7 @@ type AgentApiResponseByRoute = {
   messageReactionAdd: AgentApiMessageEnvelope;
   messageReactionRemove: AgentApiMessageEnvelope;
   attachmentDownload: AgentApiAttachmentDownloadResponse;
+  attachmentDownloadUrl: AgentApiAttachmentDownloadUrlResponse;
   attachmentCommentsList: AgentApiAttachmentCommentsResponse;
   channelJoin: AgentApiOkResponse;
   channelLeave: AgentApiOkResponse;
@@ -9764,6 +9870,21 @@ declare const OPERATION_DEFS: readonly [{
     mayBeLarge: false;
     boundBy: never[];
   };
+}, {
+  readonly name: "attachments.downloadUrl";
+  readonly description: "Get a short-lived (5 minute) URL for an attachment's bytes, with its filename and MIME type, for runtimes that fetch files themselves. The URL grants access to the file: do not post it in messages.";
+  readonly schema: z.ZodObject<{
+    attachmentId: z.ZodString;
+  }, z.core.$strip>;
+  readonly routes: readonly ["attachmentDownloadUrl"];
+  readonly consumes: {
+    model: never[];
+    code: never[];
+  };
+  readonly output: {
+    mayBeLarge: false;
+    boundBy: never[];
+  };
 }, {
   readonly name: "attachments.comments";
   readonly description: "List the comments on an attachment.";
@@ -9908,12 +10029,15 @@ declare const OPERATION_DEFS: readonly [{
       targetAgent: z.ZodString;
       draftHint: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "type">;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>;
   readonly fieldDescriptions: {
     readonly target: "Conversation to post the card in: `#channel`, `dm:@peer`, or a thread.";
     readonly action: "The operation the card proposes: `type` picks it, and the other fields apply per type as described.";
+    readonly idempotencyKey: "One key per logical prepare; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without posting a second card.";
   };
   readonly routes: readonly ["actionPrepare"];
+  readonly idempotencyArg: "idempotencyKey";
   readonly consumes: {
     model: never[];
     code: never[];
@@ -10009,8 +10133,10 @@ declare const OPERATION_DEFS: readonly [{
       createsResource: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     assignee: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
   readonly routes: readonly ["taskCreate"];
+  readonly idempotencyArg: "idempotencyKey";
   readonly consumes: {
     model: never[];
     code: never[];
@@ -10310,6 +10436,7 @@ declare const OPERATION_DEFS: readonly [{
     offset: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodOptional<z.ZodNumber>;
     joined: z.ZodOptional<z.ZodBoolean>;
+    query: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
   readonly routes: readonly ["serverInfo"];
   readonly consumes: {
@@ -10377,8 +10504,6 @@ declare const OPERATION_DEFS: readonly [{
 }];
 /** The dotted name of every operation in the manifest (the `invoke` key). */
 type RaftOperationName = (typeof OPERATION_DEFS)[number]["name"];
-/** `tasks.updateStatus` → `tasks_update_status`. */
-export declare function raftToolNameFor(name: string): string;
 /** Every agent operation on `createRaft`, in a stable order. */
 export declare const RAFT_OPERATIONS: readonly RaftOperationSpec[];
 /** Content hash of `RAFT_OPERATIONS` (16 hex digits); changes whenever any field of any operation changes. */
@@ -10423,6 +10548,15 @@ interface CreateRaftOptions {
   state?: RaftStateStore;
   /** Called when loading or saving the state fails or is rejected as stale. */
   onStateSaveError?: RaftStateSaveErrorHandler;
+  /**
+   * How "do this next" hints render in every outcome's `text` and
+   * `next.command`. `cli` (default): the `raft …` command, exactly as the CLI
+   * prints it. `tool`: the operation as a tool call, `messages_read({ target:
+   * "#ops" })`, for runtimes that hand operations to the model as tools
+   * (required arguments the model supplies show as `content: …`). Either way
+   * `next.operation` carries the structured call.
+   */
+  hints?: RaftHintStyle;
 }
 interface RaftInboxCommitResult {
   /** The committed cursor, or null when there was nothing to commit. */
@@ -10531,6 +10665,15 @@ interface Raft {
     download(request: {
       attachmentId: string;
     }): Promise<RaftOutcome<RaftAttachmentBytes, "downloaded">>;
+    /**
+     * A short-lived (5 minute) URL for the bytes, for runtimes whose tools
+     * cannot return binary data; fetch it yourself before `expiresAt` and do
+     * not log it. A Server that cannot presign fails with `CONFLICT`
+     * (`download_url_unavailable`) and `next` pointing at `download`.
+     */
+    downloadUrl(request: {
+      attachmentId: string;
+    }): Promise<RaftOutcome<RaftAttachmentDownloadUrl, "url">>;
     comments(request: {
       attachmentId: string;
       limit?: number;
@@ -10686,4 +10829,4 @@ export declare const commitInboxRequestSchema: z.ZodObject<{
   cursor: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 //#endregion
-export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, ConvertMessageToTaskRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelInfo, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftConsumption, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxDrained, RaftInboxListing, RaftInboxNotice, RaftInterrupt, RaftInterruptCancel, RaftInterruptReason, RaftInterruptResume, RaftInterrupted, RaftInvokeCaller, RaftInvokeResult, RaftJsonSchema, RaftJsonSchemaType, RaftLatestReadThread, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOperationIdempotency, RaftOperationName, RaftOperationSpec, RaftOperationsDocument, RaftOutcome, RaftPendingMentions, RaftPreparedCard, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftState, RaftStateContinuation, RaftStateSaveErrorHandler, RaftStateStore, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftUserInfo, RaftUserRef, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, ReadLatestReadThreadOptions, ReplyToRequest, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, UserInfoRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };
+export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, ConvertMessageToTaskRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentDownloadUrl, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelInfo, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftConsumption, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHintStyle, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxDrained, RaftInboxListing, RaftInboxNotice, RaftInterrupt, RaftInterruptCancel, RaftInterruptReason, RaftInterruptResume, RaftInterrupted, RaftInvokeCaller, RaftInvokeResult, RaftJsonSchema, RaftJsonSchemaType, RaftLatestReadThread, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextOperation, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOperationIdempotency, RaftOperationName, RaftOperationSpec, RaftOperationsDocument, RaftOutcome, RaftPendingMentions, RaftPreparedCard, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftState, RaftStateContinuation, RaftStateSaveErrorHandler, RaftStateStore, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftUserInfo, RaftUserRef, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, ReadLatestReadThreadOptions, ReplyToRequest, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, UserInfoRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };

package/operations.json

@@ -1,6 +1,6 @@
 {
   "schema": "raft-sdk-operations.v1",
-  "version": "90a77ae0a9067bc0",
+  "version": "4e70c891e417cd51",
   "operations": [
     {
       "name": "identity.whoami",
@@ -620,6 +620,40 @@
         "boundBy": []
       }
     },
+    {
+      "name": "attachments.downloadUrl",
+      "toolName": "attachments_download_url",
+      "description": "Get a short-lived (5 minute) URL for an attachment's bytes, with its filename and MIME type, for runtimes that fetch files themselves. The URL grants access to the file: do not post it in messages.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "attachmentId": {
+            "type": "string",
+            "description": "The attachment id, as message lines show it (`id:…`)."
+          }
+        },
+        "required": [
+          "attachmentId"
+        ]
+      },
+      "sideEffect": "read",
+      "idempotency": {
+        "kind": "natural"
+      },
+      "capability": [
+        "read"
+      ],
+      "modelOnly": false,
+      "mayInterrupt": false,
+      "consumes": {
+        "model": [],
+        "code": []
+      },
+      "output": {
+        "mayBeLarge": false,
+        "boundBy": []
+      }
+    },
     {
       "name": "attachments.comments",
       "toolName": "attachments_comments",
@@ -961,6 +995,10 @@
               "type"
             ],
             "description": "The operation the card proposes: `type` picks it, and the other fields apply per type as described."
+          },
+          "idempotencyKey": {
+            "type": "string",
+            "description": "One key per logical prepare; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without posting a second card."
           }
         },
         "required": [
@@ -970,7 +1008,8 @@
       },
       "sideEffect": "write",
       "idempotency": {
-        "kind": "none"
+        "kind": "key",
+        "arg": "idempotencyKey"
       },
       "capability": [
         "tasks"
@@ -1218,6 +1257,10 @@
           "assignee": {
             "type": "string",
             "description": "`@handle`: yourself to start in_progress, or (owner/admin) someone else to reserve a todo."
+          },
+          "idempotencyKey": {
+            "type": "string",
+            "description": "One key per logical create; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without creating the tasks twice."
           }
         },
         "required": [
@@ -1227,7 +1270,8 @@
       },
       "sideEffect": "write",
       "idempotency": {
-        "kind": "none"
+        "kind": "key",
+        "arg": "idempotencyKey"
       },
       "capability": [
         "tasks"
@@ -1940,6 +1984,10 @@
           "joined": {
             "type": "boolean",
             "description": "channels view only: only channels you have joined."
+          },
+          "query": {
+            "type": "string",
+            "description": "channels / agents / humans view only: keep rows whose name, description, or other visible text contains this (case-insensitive)."
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "FSL-1.1-ALv2",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",