@botiverse/raft-sdk 0.9.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 {
@@ -1103,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<{
@@ -1115,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>;
@@ -1168,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 {
@@ -1186,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 {
@@ -1995,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>;
@@ -8265,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";
@@ -8517,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";
@@ -8709,6 +8779,7 @@ type AgentApiRequestParamsByRoute = {
   messageReactionAdd: AgentApiMessageReactionParams;
   messageReactionRemove: AgentApiMessageReactionParams;
   attachmentDownload: AgentApiAttachmentDownloadParams;
+  attachmentDownloadUrl: AgentApiAttachmentDownloadParams;
   attachmentCommentsList: AgentApiAttachmentCommentsParams;
   channelJoin: AgentApiChannelMembershipParams;
   channelLeave: AgentApiChannelMembershipParams;
@@ -8789,6 +8860,7 @@ type AgentApiRequestQueryByRoute = {
   messageReactionAdd: never;
   messageReactionRemove: never;
   attachmentDownload: never;
+  attachmentDownloadUrl: never;
   attachmentCommentsList: AgentApiAttachmentCommentsQuery;
   channelJoin: never;
   channelLeave: never;
@@ -8869,6 +8941,7 @@ type AgentApiRequestBodyByRoute = {
   messageReactionAdd: AgentApiMessageReactionBody;
   messageReactionRemove: AgentApiMessageReactionBody;
   attachmentDownload: never;
+  attachmentDownloadUrl: never;
   attachmentCommentsList: never;
   channelJoin: never;
   channelLeave: never;
@@ -8949,6 +9022,7 @@ type AgentApiResponseByRoute = {
   messageReactionAdd: AgentApiMessageEnvelope;
   messageReactionRemove: AgentApiMessageEnvelope;
   attachmentDownload: AgentApiAttachmentDownloadResponse;
+  attachmentDownloadUrl: AgentApiAttachmentDownloadUrlResponse;
   attachmentCommentsList: AgentApiAttachmentCommentsResponse;
   channelJoin: AgentApiOkResponse;
   channelLeave: AgentApiOkResponse;
@@ -9796,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.";
@@ -10347,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: {
@@ -10414,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. */
@@ -10460,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. */
@@ -10568,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;
@@ -10723,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": "c2d4e5cdeb300d10",
+  "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",
@@ -1950,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.9.0",
+  "version": "0.10.0",
   "license": "FSL-1.1-ALv2",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",