@botiverse/raft-sdk 0.4.0 → 0.4.1

package/README.md

@@ -190,7 +190,7 @@ gateway can handle it without knowing the command (`isInterrupted(outcome)`):
 interface RaftInterrupt {
   reason: "unread_messages";
   context: string;                                   // what the model reads (the CLI's held text)
-  resume: { argv: string[]; idempotencyKey?: string }; // always present
+  resume: { argv?: string[]; idempotencyKey?: string }; // always present; argv absent for an in-process send
   cancel?: { argv: string[] };                       // only when there is something to clean up
   target: string;
   newMessageCount: number;
@@ -203,11 +203,16 @@ interface RaftInterrupt {
 }
 ```
 
-- A held send: `resume.argv` is
+- A held send run as a command (the CLI, or the hosted command endpoint,
+  which store 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
   carries `K`.
+- A held send from this SDK in-process: the SDK stores no draft, so there is
+  **no argv and no `cancel`**. `resume` is `{ idempotencyKey: K }`: to go
+  ahead, call `messages.send` again with the same input and
+  `idempotencyKey: K`; to drop it, don't call it (nothing is left behind).
 - A held claim or task write: `resume.argv` is the identical command; there is
   no `cancel` (nothing was saved). An absent `cancel` means cancelling needs no
   request: just don't execute `resume`.
@@ -215,10 +220,12 @@ interface RaftInterrupt {
   `frontier.recordHeld(interrupt)` if it saw it (nothing is recorded when the
   context was withheld or `contextComplete` is false; have it read the
   conversation first), then resume or cancel.
-- In-process, the SDK keeps no draft: resuming is calling the same operation
-  with the same request (a send under `interrupt.resume.idempotencyKey`), and
-  cancelling is not calling it. The argv are the command form a gateway hands
-  to the model.
+- 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

package/dist/cjs/index.cjs

@@ -10966,34 +10966,9 @@ function unreadMessagesInterrupt(input) {
 		contextComplete: !withheld && heldMessages.length + omittedMessageCount >= newMessageCount
 	};
 }
-/** `raft message send --send-draft` for the draft a held send saved, under its original key. */
-function sendDraftResume(target, idempotencyKey, extraArgv = []) {
-	return {
-		argv: [
-			"message",
-			"send",
-			"--send-draft",
-			"--target",
-			target,
-			"--expected-draft-key",
-			idempotencyKey,
-			...extraArgv
-		],
-		idempotencyKey
-	};
-}
-/** `raft message send --discard-draft` for the draft a held send saved (compare-and-clear on its key). */
-function discardDraftCancel(target, idempotencyKey, extraArgv = []) {
-	return { argv: [
-		"message",
-		"send",
-		"--discard-draft",
-		"--target",
-		target,
-		"--expected-draft-key",
-		idempotencyKey,
-		...extraArgv
-	] };
+/** Resume of an in-process SDK send: no argv (the SDK stores no draft), only the original key to call again with. */
+function inProcessSendResume(idempotencyKey) {
+	return { idempotencyKey };
 }
 /** `raft task claim` argv for a claim request (resume of a held claim). */
 function taskClaimArgv(target, taskNumbers, messageIds, extraArgv = []) {
@@ -11555,7 +11530,7 @@ async function sendMessage(client, request, frontier) {
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
-		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", sendDraftResume(request.target, idempotencyKey), discardDraftCancel(request.target, idempotencyKey));
+		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", inProcessSendResume(idempotencyKey));
 		return {
 			ok: true,
 			state: "interrupted",

package/dist/esm/index.js

@@ -10965,34 +10965,9 @@ function unreadMessagesInterrupt(input) {
 		contextComplete: !withheld && heldMessages.length + omittedMessageCount >= newMessageCount
 	};
 }
-/** `raft message send --send-draft` for the draft a held send saved, under its original key. */
-function sendDraftResume(target, idempotencyKey, extraArgv = []) {
-	return {
-		argv: [
-			"message",
-			"send",
-			"--send-draft",
-			"--target",
-			target,
-			"--expected-draft-key",
-			idempotencyKey,
-			...extraArgv
-		],
-		idempotencyKey
-	};
-}
-/** `raft message send --discard-draft` for the draft a held send saved (compare-and-clear on its key). */
-function discardDraftCancel(target, idempotencyKey, extraArgv = []) {
-	return { argv: [
-		"message",
-		"send",
-		"--discard-draft",
-		"--target",
-		target,
-		"--expected-draft-key",
-		idempotencyKey,
-		...extraArgv
-	] };
+/** Resume of an in-process SDK send: no argv (the SDK stores no draft), only the original key to call again with. */
+function inProcessSendResume(idempotencyKey) {
+	return { idempotencyKey };
 }
 /** `raft task claim` argv for a claim request (resume of a held claim). */
 function taskClaimArgv(target, taskNumbers, messageIds, extraArgv = []) {
@@ -11554,7 +11529,7 @@ async function sendMessage(client, request, frontier) {
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
-		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", sendDraftResume(request.target, idempotencyKey), discardDraftCancel(request.target, idempotencyKey));
+		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", inProcessSendResume(idempotencyKey));
 		return {
 			ok: true,
 			state: "interrupted",

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;
 }
@@ -9250,4 +9256,7 @@ interface Raft {
 }
 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/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" | "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
+export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CommandErrorCode, 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 };

package/package.json

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