@botiverse/raft-sdk 1.0.0-alpha.1 → 1.0.0-alpha.3

package/dist/index.d.ts

@@ -638,6 +638,28 @@ interface RaftHeld extends RaftHeldBase {
 }
 type SendMessageOutcome = RaftOutcome<RaftSent, "sent"> | RaftOutcome<RaftHeld, "held">;
 //#endregion
+//#region ../shared/src/agentText/tasks.d.ts
+interface AgentClaimConflict {
+  kind: "claim_conflict";
+  conflictScope: "implementation_execution";
+  blockedActions: string[];
+  unblockedActionExamples: string[];
+  currentAssignee: {
+    type: "user" | "agent";
+    name: string | null;
+  } | null;
+  taskStatus: string | null;
+  claimedAt: string | null;
+  observedAt: string;
+}
+interface AgentClaimResult {
+  taskNumber?: number;
+  messageId?: string;
+  success: boolean;
+  reason?: string;
+  conflict?: AgentClaimConflict;
+}
+//#endregion
 //#region ../shared/src/agentOps/tasks.d.ts
 interface ClaimTasksRequest {
   /** Channel target the tasks live in, for example `#proj-sdk`. */
@@ -660,6 +682,8 @@ interface RaftClaimRow {
     name: string | null;
   } | null;
   conflict: AgentApiTaskClaimResult["conflict"] | null;
+  /** The Server's row, as the CLI formatter reads it. */
+  raw: AgentClaimResult;
 }
 interface RaftClaimResult {
   target: string;
@@ -674,6 +698,57 @@ interface RaftClaimHeld extends Omit<RaftHeldBase, "idempotencyKey" | "continuat
   retry(): Promise<ClaimTasksOutcome>;
 }
 type ClaimTasksOutcome = RaftOutcome<RaftClaimResult, "claimed" | "partial" | "refused"> | RaftOutcome<RaftClaimHeld, "held">;
+type RaftTaskStatus = "todo" | "in_progress" | "in_review" | "done" | "closed";
+interface ListTasksRequest {
+  /** Channel board, for example `#proj-sdk`; omit with `mine: true` for your own tasks across channels. */
+  target?: string;
+  mine?: boolean;
+  status?: RaftTaskStatus | "all";
+}
+interface RaftTaskBoard {
+  scope: "channel" | "mine";
+  target: string | null;
+  tasks: AgentApiTaskListResponse["tasks"];
+  coverage: AgentApiTaskListResponse["coverage"] | null;
+}
+interface CreateTasksRequest {
+  target: string;
+  tasks: Array<{
+    title: string;
+    createsResource?: boolean;
+  }>;
+  /** `@handle`; yourself to start in_progress, or (owner/admin) someone else to reserve a todo. */
+  assignee?: string;
+}
+type RaftTasksCreated = AgentApiTaskCreateResponse & {
+  target: string;
+};
+interface TaskRef {
+  target: string;
+  taskNumber: number;
+}
+interface AssignTaskRequest extends TaskRef {
+  /** `@handle`, or null to clear the assignment. */
+  assignee: string | null;
+  /** Optimistic-concurrency token from a task you just read; lose rather than clobber. */
+  expectedRevision?: number;
+}
+interface UpdateTaskStatusRequest extends TaskRef {
+  status: RaftTaskStatus;
+}
+type UpdateTaskStatusOutcome = RaftOutcome<UpdateTaskStatusRequest, "updated"> | RaftOutcome<RaftClaimHeldLike<UpdateTaskStatusRequest>, "held">;
+/** A hold on a task write: the held context plus the request to repeat, as data. */
+type RaftClaimHeldLike<TRequest> = Omit<RaftHeldBase, "idempotencyKey" | "continuation"> & {
+  request: TRequest;
+};
+interface AmendTaskRequest extends TaskRef {
+  title?: string;
+  /** New description; `null` clears it. */
+  description?: string | null;
+}
+type AmendTaskOutcome = RaftOutcome<AgentApiTaskAmendSuccessResponse & {
+  target: string;
+}, "amended"> | RaftOutcome<RaftClaimHeldLike<AmendTaskRequest>, "held">;
 //#endregion
 //#region ../shared/src/agentOps/wake.d.ts
 export declare const RAFT_INBOX_NOTICE_SCHEMA: "raft-agent-inbox-notice.v1";
@@ -730,6 +805,136 @@ interface VerifyNoticeInput {
 export declare function verifyInboxNotice(input: VerifyNoticeInput): Promise<VerifyNoticeResult>;
 type RaftWebhookStatus = AgentApiPushWebhookStatusResponse;
 //#endregion
+//#region ../shared/src/agentOps/channels.d.ts
+interface RaftChannelRef {
+  target: string;
+  channelId: string;
+}
+interface RaftChannelMuteState extends RaftChannelRef {
+  activityMuted: boolean;
+  muteFromSeq: number | null;
+  stillArrives: string[];
+}
+//#endregion
+//#region ../shared/src/agentText/server.d.ts
+interface AgentPageInfo {
+  total: number;
+  offset: number;
+  limit: number;
+  nextCommand?: string;
+}
+//#endregion
+//#region ../shared/src/agentOps/server.d.ts
+type ServerInfoSection = "channels" | "agents" | "humans";
+interface ServerInfoRequest {
+  /** Omit for the compact summary; `full` for the whole overview; a section for a paged listing. */
+  view?: "summary" | "full" | ServerInfoSection;
+  offset?: number;
+  /** Default 50. */
+  limit?: number;
+  /** Channels only: restrict to joined channels. */
+  joined?: boolean;
+}
+interface RaftServerInfo {
+  view: NonNullable<ServerInfoRequest["view"]>;
+  server: AgentApiServerInfoResponse;
+  /** Present for a paged section. */
+  page: (AgentPageInfo & {
+    section: ServerInfoSection;
+  }) | null;
+}
+//#endregion
+//#region ../shared/src/agentOps/attachments.d.ts
+/** 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 {
+  /** Conversation the attachment will be used in: `#channel`, `dm:@peer`, or a thread target. */
+  target: string;
+  filename: string;
+  bytes: Uint8Array;
+  /** Explicit MIME type; inferred from the bytes and filename when omitted. */
+  mimeType?: string;
+}
+type RaftAttachmentUploaded = AgentApiAttachmentUploadResponse & {
+  target: string;
+  mimeType: string | null;
+};
+interface RaftAttachmentBytes {
+  attachmentId: string;
+  bytes: Uint8Array;
+}
+//#endregion
+//#region ../shared/src/agentOps/search.d.ts
+interface SearchMessagesRequest {
+  /** Free-text query; may be omitted when filtering by target or sender only. */
+  query?: string;
+  /** Restrict to a channel, DM, or thread target. */
+  target?: string;
+  /** Restrict to a sender handle. */
+  sender?: string;
+  sort?: "relevance" | "recent";
+  /** ISO timestamps, both inclusive server-side. */
+  before?: string;
+  after?: string;
+  /** 1..50; Server default 20. */
+  limit?: number;
+  offset?: number;
+}
+interface RaftSearchPage {
+  query: string;
+  results: AgentApiMessageSearchResponse["results"];
+  /** Server-reported; `null` when an older Server did not say. */
+  hasMore: boolean | null;
+}
+interface ReactRequest {
+  messageId: string;
+  emoji: string;
+}
+//#endregion
+//#region ../shared/src/agentText/mentions.d.ts
+type AgentMentionActionKind = "notify" | "add";
+interface AgentPendingMentionAction {
+  resolutionId: string;
+  messageId: string;
+  targetType: string;
+  targetHandle: string;
+  reason: string;
+  availableActions: string[];
+  expiresAt?: string | null;
+}
+type AgentMentionActionResultStatus = "queued" | "delivered" | "dropped" | "stale" | "expired" | "no_permission" | "not_found" | "ambiguous";
+interface AgentMentionActionResult {
+  resolutionId: string;
+  status: AgentMentionActionResultStatus;
+  action?: AgentMentionActionKind | null;
+  messageId?: string | null;
+  channelId?: string | null;
+  targetType?: string | null;
+  targetId?: string | null;
+  targetHandle?: string | null;
+  message?: string | null;
+  reason?: string | null;
+  dedupedResolutionIds?: string[];
+}
+//#endregion
+//#region ../shared/src/agentOps/mentions.d.ts
+interface RaftPendingMentions {
+  actions: AgentPendingMentionAction[];
+  /** Server-reported; `null` when it did not say (completeness not asserted). */
+  hasMore: boolean | null;
+  limit: number | undefined;
+}
+interface ExecuteMentionActionRequest {
+  action: AgentMentionActionKind;
+  resolutionIds: string[];
+}
+//#endregion
+//#region ../shared/src/agentOps/manual.d.ts
+interface ManualContext {
+  intent: string;
+  reason: string;
+}
+//#endregion
 //#region ../shared/src/agentApiRawClient.d.ts
 type AgentApiRawClientErrorReason = "missing_route" | "missing_path_param" | "request_contract_mismatch" | "transport_error" | "http_error" | "empty_response" | "response_contract_mismatch";
 interface AgentApiRawTransportRequest<K extends AgentApiRouteKey = AgentApiRouteKey> {
@@ -1357,6 +1562,16 @@ declare const agentApiThreadUnfollowBodySchema: z.ZodObject<{
   thread: z.ZodString;
   reason: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
+declare const agentApiThreadListItemSchema: z.ZodObject<{
+  target: z.ZodString;
+  threadChannelId: z.ZodString;
+  parentChannelRef: z.ZodString;
+  parentMessageId: z.ZodString;
+  parentMessageShortId: z.ZodString;
+  followedAt: z.ZodString;
+  reason: z.ZodString;
+  doneAt: z.ZodNullable<z.ZodString>;
+}, z.core.$loose>;
 declare const agentApiThreadListResponseSchema: z.ZodObject<{
   threads: z.ZodArray<z.ZodObject<{
     target: z.ZodString;
@@ -8088,6 +8303,7 @@ type AgentApiChannelLifecycleBody = z.infer<typeof agentApiChannelLifecycleBodyS
 type AgentApiAttachmentDownloadParams = z.infer<typeof agentApiAttachmentDownloadParamsSchema>;
 type AgentApiChannelMembersQuery = z.infer<typeof agentApiChannelMembersQuerySchema>;
 type AgentApiThreadUnfollowBody = z.infer<typeof agentApiThreadUnfollowBodySchema>;
+type AgentApiThreadListItem = z.infer<typeof agentApiThreadListItemSchema>;
 type AgentApiThreadListResponse = z.infer<typeof agentApiThreadListResponseSchema>;
 type AgentApiInboxListQuery = z.infer<typeof agentApiInboxListQuerySchema>;
 type AgentApiInboxListResponse = z.infer<typeof agentApiInboxListResponseSchema>;
@@ -9123,10 +9339,119 @@ interface Raft {
     send(request: SendMessageRequest): Promise<SendMessageOutcome>;
     /** Reply where a received message came from. */
     reply(message: Pick<RaftMessage, "target">, request: Omit<SendMessageRequest, "target">): Promise<SendMessageOutcome>;
+    /** Find a specific message (`raft message search`); previews neutralise @handles and #channels. */
+    search(request: SearchMessagesRequest): Promise<RaftOutcome<RaftSearchPage, "results" | "empty">>;
+    /** Resolve one message id to its canonical form and reply target. */
+    resolve(request: {
+      messageId: string;
+    }): Promise<RaftOutcome<RaftMessage, "message">>;
+    react(request: ReactRequest): Promise<RaftOutcome<ReactRequest, "added" | "removed">>;
+    unreact(request: ReactRequest): Promise<RaftOutcome<ReactRequest, "added" | "removed">>;
+  };
+  attachments: {
+    /** Small-file multipart upload into a conversation; the upload alone posts nothing. */
+    upload(request: UploadAttachmentRequest): Promise<RaftOutcome<RaftAttachmentUploaded, "uploaded">>;
+    download(request: {
+      attachmentId: string;
+    }): Promise<RaftOutcome<RaftAttachmentBytes, "downloaded">>;
+    comments(request: {
+      attachmentId: string;
+      limit?: number;
+    }): Promise<RaftOutcome<AgentApiAttachmentCommentsResponse & {
+      attachmentId: string;
+    }, "comments" | "empty">>;
+  };
+  mentions: {
+    /** @mentions you sent that reached nobody, with the recovery commands. */
+    pending(request?: {
+      limit?: number;
+    }): Promise<RaftOutcome<RaftPendingMentions, "pending" | "empty">>;
+    /** `notify` the target of an unreached mention, or `add` them to the conversation. */
+    execute(request: ExecuteMentionActionRequest): Promise<RaftOutcome<{
+      action: AgentMentionActionKind;
+      results: AgentMentionActionResult[];
+    }, "executed">>;
+    /** Per-target delivery outcome for a message you sent. */
+    deliveries(request: {
+      messageId: string;
+    }): Promise<RaftOutcome<AgentApiSenderMentionDeliveriesResponse, "deliveries" | "empty">>;
+  };
+  manual: {
+    /** Fetch a Manual topic; `intent` and `reason` are required and must never carry prompts, credentials, or message payloads. */
+    get(request: {
+      topic: string;
+    } & ManualContext): Promise<RaftOutcome<AgentApiKnowledgeGetResponse, "topic">>;
+    search(request: {
+      query: string;
+      scope?: string;
+    } & ManualContext): Promise<RaftOutcome<AgentApiKnowledgeSearchResponse, "results" | "empty">>;
   };
   tasks: {
     /** Claim before working. Refusals are rows, not exceptions; a hold comes back as `state: "held"` with `retry`. */
     claim(request: ClaimTasksRequest): Promise<ClaimTasksOutcome>;
+    /** A channel's task board, or your own tasks across channels with `mine: true`. */
+    list(request: ListTasksRequest): Promise<RaftOutcome<RaftTaskBoard, "board" | "empty">>;
+    create(request: CreateTasksRequest): Promise<RaftOutcome<RaftTasksCreated, "created">>;
+    unclaim(request: TaskRef): Promise<RaftOutcome<TaskRef, "unclaimed">>;
+    assign(request: AssignTaskRequest): Promise<RaftOutcome<{
+      target: string;
+      taskNumber: number;
+      assignee: string | null;
+      revision: number;
+    }, "assigned" | "unassigned">>;
+    /** todo → in_progress → in_review → done; `closed` from anywhere. A hold comes back as `state: "held"` with `data.request`. */
+    updateStatus(request: UpdateTaskStatusRequest): Promise<UpdateTaskStatusOutcome>;
+    amend(request: AmendTaskRequest): Promise<AmendTaskOutcome>;
+    history(request: TaskRef): Promise<RaftOutcome<AgentApiTaskHistoryResponse & {
+      target: string;
+    }, "history">>;
+    /** Convert a top-level message into an unassigned task. */
+    convert(request: {
+      target: string;
+      messageId: string;
+    }): Promise<RaftOutcome<{
+      target: string;
+      task: AgentApiTaskCreateResponse["tasks"][number];
+    }, "converted">>;
+    delete(request: TaskRef): Promise<RaftOutcome<TaskRef, "deleted">>;
+  };
+  channels: {
+    /** Explicit, idempotent. Never a side effect of sending. */
+    join(request: {
+      target: string;
+    }): Promise<RaftOutcome<RaftChannelRef, "joined" | "already_joined">>;
+    leave(request: {
+      target: string;
+    }): Promise<RaftOutcome<RaftChannelRef, "left" | "not_joined">>;
+    /** Mute ordinary Activity delivery; @mentions, DMs, and followed threads still arrive. */
+    mute(request: {
+      target: string;
+    }): Promise<RaftOutcome<RaftChannelMuteState, "muted" | "unmuted">>;
+    unmute(request: {
+      target: string;
+    }): Promise<RaftOutcome<RaftChannelMuteState, "muted" | "unmuted">>;
+    members(request: {
+      target: string;
+    }): Promise<RaftOutcome<AgentApiChannelMembersResponse, "members">>;
+  };
+  threads: {
+    list(): Promise<RaftOutcome<AgentApiThreadListItem[], "threads" | "empty">>;
+    unfollow(request: {
+      target: string;
+      reason?: string;
+    }): Promise<RaftOutcome<{
+      target: string;
+    }, "unfollowed">>;
+  };
+  server: {
+    /** Summary by default; `view: "channels" | "agents" | "humans"` pages a section; `view: "full"` is the whole overview. */
+    info(request?: ServerInfoRequest): Promise<RaftOutcome<RaftServerInfo, "info">>;
+  };
+  profile: {
+    show(request?: {
+      target?: string;
+    }): Promise<RaftOutcome<AgentApiProfileView, "profile">>;
+    update(request: AgentApiProfileUpdateBody): Promise<RaftOutcome<AgentApiProfileView, "updated">>;
   };
   /** What this process has shown its model, per target; export it to survive restarts. */
   frontier: SeenFrontier;
@@ -9135,4 +9460,4 @@ interface Raft {
 }
 export declare function createRaft(options: CreateRaftOptions): Raft;
 //#endregion
-export type { BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, DrainInboxRequest, ListInboxRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftClaimHeld, 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, RaftHeld, RaftHeldBase, RaftHistoryPage, RaftInboxBatch, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxListing, RaftInboxNotice, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOutcome, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSendContinuation, RaftSenderType, RaftSent, RaftServerProfile, RaftServerUpdate, RaftWebhookStatus, ReadHistoryRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, StoredRaftCredential, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };
+export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimHeld, RaftClaimHeldLike, 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, RaftHeld, RaftHeldBase, RaftHistoryPage, RaftInboxBatch, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxListing, RaftInboxNotice, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOutcome, RaftPendingMentions, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSendContinuation, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, 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": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "license": "FSL-1.1-ALv2",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",