@botiverse/raft-sdk 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -430,8 +430,14 @@ export declare function projectRaftMessages(envelopes: readonly AgentApiMessageE
 /** Why the call stopped. */
 type RaftInterruptReason = "unread_messages";
 interface RaftInterruptResume {
-  /** The exact `raft` argv that carries out the interrupted call (for example `["message", "send", "--send-draft", …]`). */
-  argv: string[];
+  /**
+   * The exact `raft` argv that carries out the interrupted call (for example
+   * `["message", "send", "--send-draft", …]`), when the call ran as a command
+   * (CLI or command endpoint) and its input is stored. Absent for an
+   * in-process SDK call: then resuming means calling the same SDK method again
+   * with the same input and `idempotencyKey`.
+   */
+  argv?: string[];
   /** The interrupted call's original idempotency key, when it has one (a send); resuming reuses it. */
   idempotencyKey?: string;
 }
@@ -1351,6 +1357,32 @@ declare const attachmentUploadPathParamsSchema: z.ZodObject<{
   uploadId: z.ZodUUID;
 }, z.core.$strict>;
 //#endregion
+//#region ../shared/src/agentOps/commands/errors.d.ts
+type CommandErrorCode = "MISSING_AGENT_ID" | "MISSING_SERVER_URL" | "MISSING_AGENT_PROXY_URL" | "MULTIPLE_AGENT_PROXY_TOKENS" | "MISSING_AGENT_PROXY_TOKEN" | "MISSING_TOKEN" | "CHECK_FAILED" | "COMMAND_TIMEOUT" | "ARCHIVE_FAILED" | "AMEND_FAILED" | "COMMENTS_FAILED" | "CREATE_FAILED" | "RECEIPT_FAILED" | "INBOX_CHECK_FAILED" | "INBOX_UNAVAILABLE" | "ORIGIN_NOT_ALLOWED" | "TOKEN_FILE_UNREADABLE" | "TOKEN_FILE_EMPTY" | "PROFILE_FILE_UNREADABLE" | "PROFILE_FILE_INVALID" | "PROFILE_MANAGED_CONTEXT_CONFLICT" | "MANAGED_WRAPPER_UNAVAILABLE" | "MANAGED_WRAPPER_REQUIRED" | "MANAGED_WRAPPER_FORWARD_FAILED" | "BRIDGE_EXPECTED_AGENT_REQUIRED" | "BRIDGE_IDENTITY_MISMATCH" | "SEND_HELD_AS_DRAFT" | "SEND_HELD" | "GUIDANCE_DELIVERED" | "SEND_DRAFT_NOT_FOUND" | "SEND_DRAFT_EXPIRED" | "SAVED_DRAFT_IDENTITY_CHANGED" | "DRAFT_PENDING" | "THREAD_CONTEXT_TARGET_CONFIRMATION_REQUIRED" | "INVALID_ARG" | "INVALID_SCOPE" | "INVALID_TARGET" | "INVALID_JSON_RESPONSE" | "IDENTITY_MISMATCH" | "PROMPT_UNAVAILABLE" | "WHOAMI_FAILED" | "INFO_FAILED" | "INTEGRATION_SESSION_HANDOFF_FAILED" | "HISTORY_FAILED" | "JOIN_FAILED" | "KNOWLEDGE_GET_FAILED" | "KNOWLEDGE_SEARCH_FAILED" | "KNOWLEDGE_CONTEXT_INVALID" | "LEAVE_FAILED" | "LIST_FAILED" | "MEMBERS_FAILED" | "MUTE_FAILED" | "MENTION_ACTION_FAILED" | "MENTION_DELIVERY_FAILED" | "AMBIGUOUS_ID" | "BRIDGE_ALREADY_RUNNING" | "BRIDGE_WAKE_HINTS_FAILED" | "BRIDGE_WAKE_STREAM_FAILED" | "BRIDGE_WAKE_STREAM_UNAVAILABLE" | "BRIDGE_ACTIVITY_DRAIN_FAILED" | "BRIDGE_ACTIVITY_FORWARD_FAILED" | "BRIDGE_REQUIRES_PROFILE" | "NOT_FOUND" | "PROFILE_SHOW_FAILED" | "READ_FAILED" | "SEARCH_FAILED" | "SCOPE_DENIED" | "QUERY_TOO_BROAD" | "SEARCH_TIMEOUT" | "SEARCH_UNAVAILABLE" | "SERVER_5XX" | "PROXY_5XX" | "UNFOLLOW_FAILED" | "UNARCHIVE_FAILED" | "UNMUTE_FAILED" | "UNCLAIM_FAILED" | "CLAIM_FAILED" | "CLAIM_CONFLICT" | "ASSIGN_FAILED" | "DELETE_FAILED" | "CONVERT_FAILED" | "UPDATE_FAILED" | "VIEW_FAILED" | "VERSION_UNAVAILABLE" | "WAIT_FAILED" | "LOCAL_WRITE_FAILED" | "LOCAL_WRITE_SOURCE_FAILED" | "LOCAL_WRITE_DESTINATION_FAILED" | "LOCAL_WRITE_PARTIAL_FAILED" | "LOCAL_WRITE_POST_COMMIT_FAILED" | "LOCAL_WRITE_SIZE_EXCEEDED" | "INTERNAL_BUG" | "knowledge_agent_missing" | "knowledge_internal_error" | "knowledge_intent_invalid" | "knowledge_language_unsupported" | "knowledge_not_found" | "knowledge_query_invalid" | "knowledge_reason_invalid" | "knowledge_scope_invalid" | "knowledge_source_invalid" | "knowledge_topic_invalid" | "knowledge_trace_id_invalid" | "knowledge_turn_id_invalid" | "unsupported_capability";
+//#endregion
+//#region ../shared/src/agentOps/commands/types.d.ts
+/**
+ * What the gateway reads besides `text` (design: Response). A command that
+ * stopped for the model's decision is `RaftInterrupted` (interrupt.ts, the
+ * same shape the SDK returns; narrow with `isInterrupted`). A held task write
+ * returns it (exit 0); a held send exits non-zero as it always has
+ * (SEND_HELD_AS_DRAFT) and carries it on `CommandError.interrupted`.
+ */
+type CommandOutcome = {
+  ok: true;
+  state: string;
+  data: unknown;
+  next: RaftNextStep | null;
+} | RaftInterrupted | {
+  ok: false;
+  error: RaftOpError | {
+    code: string;
+    message: string;
+    retryable: boolean;
+  };
+  next: RaftNextStep | null;
+};
+//#endregion
 //#region ../shared/src/agentApiContract.d.ts
 declare const agentApiMethods: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
 type AgentApiMethod = (typeof agentApiMethods)[number];
@@ -1976,6 +2008,23 @@ declare const agentApiActionPrepareBodySchema: z.ZodObject<{
     draftHint: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>], "type">;
 }, z.core.$loose>;
+declare const agentApiCommandBodySchema: z.ZodObject<{
+  argv: z.ZodArray<z.ZodString>;
+  stdin: z.ZodOptional<z.ZodString>;
+  origin: z.ZodOptional<z.ZodEnum<{
+    code: "code";
+    model: "model";
+  }>>;
+  idempotencyKey: z.ZodOptional<z.ZodString>;
+  timezone: z.ZodOptional<z.ZodString>;
+  contextId: z.ZodOptional<z.ZodString>;
+  ackEventsCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+declare const agentApiCommandResponseSchema: z.ZodObject<{
+  exitCode: z.ZodNumber;
+  text: z.ZodString;
+  outcome: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
 declare const agentApiServerUpdateBodySchema: z.ZodObject<{
   name: z.ZodOptional<z.ZodString>;
   hideHumansFromMembers: z.ZodOptional<z.ZodBoolean>;
@@ -7588,6 +7637,40 @@ declare const agentApiContract: {
   } & {
     fullPath: string;
   };
+  readonly agentCommand: {
+    readonly key: "agentCommand";
+    readonly method: "POST";
+    readonly path: "/command";
+    readonly client: {
+      readonly resource: "commands";
+      readonly method: "run";
+    };
+    readonly capability: "read";
+    readonly description: "Run one `raft` command as the bound agent and return the text the CLI prints, its exit code and its outcome. HTTP 200 whenever the command ran, failed commands included; each request the command makes is authorized on its own.";
+    readonly request: {
+      readonly body: z.ZodObject<{
+        argv: z.ZodArray<z.ZodString>;
+        stdin: z.ZodOptional<z.ZodString>;
+        origin: z.ZodOptional<z.ZodEnum<{
+          code: "code";
+          model: "model";
+        }>>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+        contextId: z.ZodOptional<z.ZodString>;
+        ackEventsCursor: z.ZodOptional<z.ZodString>;
+      }, z.core.$loose>;
+    };
+    readonly response: {
+      readonly body: z.ZodObject<{
+        exitCode: z.ZodNumber;
+        text: z.ZodString;
+        outcome: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+      }, z.core.$loose>;
+    };
+  } & {
+    fullPath: string;
+  };
   readonly attachmentUpload: {
     readonly key: "attachmentUpload";
     readonly method: "POST";
@@ -8206,6 +8289,11 @@ type AgentApiTaskHistoryResponse = z.infer<typeof agentApiTaskHistoryResponseSch
 type AgentApiProfileView = z.infer<typeof agentApiProfileViewSchema>;
 type AgentApiOkResponse = z.infer<typeof agentApiOkResponseSchema>;
 type AgentApiActionPrepareResponse = z.infer<typeof agentApiActionPrepareResponseSchema>;
+type AgentApiCommandBody = z.infer<typeof agentApiCommandBodySchema>;
+/** `outcome` is the command registry's CommandOutcome (agentOps/commands/types.ts), or null when nothing ran. */
+type AgentApiCommandResponse = Omit<z.infer<typeof agentApiCommandResponseSchema>, "outcome"> & {
+  outcome: CommandOutcome | null;
+};
 type AgentApiAgentContextResponse = z.infer<typeof agentApiAgentContextResponseSchema>;
 type AgentApiServerInfoResponse = z.infer<typeof agentApiServerInfoResponseSchema>;
 type AgentApiServerUpdateBody = z.infer<typeof agentApiServerUpdateBodySchema>;
@@ -8312,6 +8400,7 @@ type AgentApiRequestParamsByRoute = {
   integrationAppList: never;
   integrationAppStatus: never;
   actionPrepare: never;
+  agentCommand: never;
   attachmentUpload: never;
   attachmentUploadCapabilities: never;
   attachmentUploadSessionCreate: never;
@@ -8392,6 +8481,7 @@ type AgentApiRequestQueryByRoute = {
   integrationAppList: never;
   integrationAppStatus: AgentApiIntegrationAppStatusQuery;
   actionPrepare: never;
+  agentCommand: never;
   attachmentUpload: never;
   attachmentUploadCapabilities: never;
   attachmentUploadSessionCreate: never;
@@ -8472,6 +8562,7 @@ type AgentApiRequestBodyByRoute = {
   integrationAppList: never;
   integrationAppStatus: never;
   actionPrepare: AgentApiActionPrepareBody;
+  agentCommand: AgentApiCommandBody;
   attachmentUpload: never;
   attachmentUploadCapabilities: never;
   attachmentUploadSessionCreate: z.infer<typeof createAttachmentUploadSessionRequestSchema>;
@@ -8552,6 +8643,7 @@ type AgentApiResponseByRoute = {
   integrationAppList: AgentApiIntegrationAppListResponse;
   integrationAppStatus: AgentApiIntegrationAppStatusResponse;
   actionPrepare: AgentApiActionPrepareResponse;
+  agentCommand: AgentApiCommandResponse;
   attachmentUpload: AgentApiAttachmentUploadResponse;
   attachmentUploadCapabilities: AgentApiAttachmentUploadCapabilitiesResponse;
   attachmentUploadSessionCreate: AgentApiAttachmentUploadSessionCreateResponse;
@@ -8853,6 +8945,27 @@ interface RaftManageClient {
   };
 }
 //#endregion
+//#region src/command.d.ts
+/**
+ * A command to run: `argv` without the leading `raft`, plus the gateway's
+ * context (`origin`, `contextId`, `timezone`, `idempotencyKey`,
+ * `ackEventsCursor`, `stdin`). See the field comments on the contract.
+ */
+type RaftCommandRequest = AgentApiCommandBody;
+/** The command ran (it may still have failed or been interrupted: read `outcome`). */
+interface RaftCommandRan {
+  ok: true;
+  /** The CLI's exit code for the same command. Not a reliable signal for "held"; use `outcome`. */
+  exitCode: AgentApiCommandResponse["exitCode"];
+  /** Exactly what `raft …` prints locally (stdout and stderr, in order). */
+  text: AgentApiCommandResponse["text"];
+  /** The structured result; null only when nothing ran (for example `--help`). */
+  outcome: AgentApiCommandResponse["outcome"];
+}
+type RaftCommandResult = RaftCommandRan | RaftFailure;
+/** Run one `raft` command on the Server for the agent this credential belongs to. */
+export declare function runCommand(routes: Pick<RaftRoutes, "request">, request: RaftCommandRequest): Promise<RaftCommandResult>;
+//#endregion
 //#region src/client.d.ts
 type RaftClient = AgentApiMessageClient & RaftManageClient & {
   events: {
@@ -8868,6 +8981,12 @@ type RaftClient = AgentApiMessageClient & RaftManageClient & {
    * Retry policy follows the contract: reads may retry, writes make one attempt.
    */
   routes: RaftRoutes;
+  /**
+   * Run a `raft` command on the Server for this agent (the hosted command
+   * endpoint): `argv` without the leading `raft`. Returns the CLI's exact
+   * text and the structured outcome; one attempt, never retried.
+   */
+  runCommand(request: RaftCommandRequest): Promise<RaftCommandResult>;
   agent: {
     /** Read the bound agent, its Server (id, slug, name), and credential capabilities. */
     context(): Promise<RaftContextResult>;
@@ -9247,7 +9366,37 @@ interface Raft {
   };
   /** Every Agent API route, typed from the shared contract. */
   routes: RaftRoutes;
+  /**
+   * Run a `raft` command on the Server for this agent (the hosted command
+   * endpoint): `argv` without the leading `raft`. Returns the CLI's exact
+   * text and the structured outcome; one attempt, never retried. The
+   * Server keeps that path's state (seen messages, drafts); it does not use
+   * this process's `frontier`.
+   */
+  runCommand(request: RaftCommandRequest): Promise<RaftCommandResult>;
 }
 export declare function createRaft(options: CreateRaftOptions): Raft;
 //#endregion
-export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxListing, RaftInboxNotice, RaftInterrupt, RaftInterruptCancel, RaftInterruptReason, RaftInterruptResume, RaftInterrupted, RaftLatestReadThread, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, 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, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, ReadLatestReadThreadOptions, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };
+//#region ../shared/src/agentOps/commands/entries/inbox.d.ts
+/**
+ * `message check`'s outcome data (`outcome.data` of a successful check).
+ */
+interface MessageCheckOutcomeData {
+  messageCount: number;
+  hasMore: boolean;
+  drainComplete: boolean;
+  leases: number;
+  ackedLeases: number;
+  /**
+   * Hosted agents only (the command endpoint): the cursor that acknowledges
+   * this batch. The batch stays unacknowledged on the server until a later
+   * request carries this value as `ackEventsCursor`; the gateway sends it
+   * back only after this result reached the model. A request without it (or
+   * with any other value) acknowledges nothing and the batch is delivered
+   * again. Absent when nothing is pending or the server acknowledged the
+   * batch immediately.
+   */
+  eventsCursor?: string;
+}
+//#endregion
+export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CommandErrorCode, CommandOutcome, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, MessageCheckOutcomeData, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftCommandRan, RaftCommandRequest, RaftCommandResult, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxListing, RaftInboxNotice, RaftInterrupt, RaftInterruptCancel, RaftInterruptReason, RaftInterruptResume, RaftInterrupted, RaftLatestReadThread, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, 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, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, ReadLatestReadThreadOptions, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };

package/package.json

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