@sinas/sdk 0.7.0 → 0.8.0

package/dist/client.d.ts

@@ -139,6 +139,12 @@ interface ChatDetail {
     title: string;
     messages: ChatMessageFull[];
     pendingApprovals: ApprovalRequest[];
+    /**
+     * The ask_user questions the chat is suspended on. Present when the
+     * server reports them (Sinas 0.5+); undefined on older servers, which
+     * have no ask_user.
+     */
+    pendingInputs?: PendingInput[];
 }
 interface ApprovalRequest {
     type: string;
@@ -147,10 +153,133 @@ interface ApprovalRequest {
     functionName: string;
     arguments: Record<string, unknown>;
 }
+/**
+ * What happens to the round after an approval decision (Sinas 0.5+).
+ * `waiting`: other calls of the same round still wait for a decision, so
+ * nothing resumes yet and there is nothing to stream. `queued`: this was the
+ * round's last decision; the round resumes on `channelId` (this includes a
+ * final rejection, which the model gets as a rejection result).
+ */
+type ApprovalResume = 'waiting' | 'queued';
 interface ApprovalResult {
     status: string;
     toolCallId: string;
     channelId: string;
+    /** Undefined on servers before Sinas 0.5, which resume on every approval. */
+    resume?: ApprovalResume;
+    message?: string;
+}
+interface ApproveToolCallOptions {
+    /**
+     * Approve this tool for the rest of the chat: later calls of the same tool
+     * skip the ask. Only applies to an approval (ignored when rejecting).
+     */
+    alwaysAllow?: boolean;
+}
+/** An ask_user question the conversation is suspended on. */
+interface PendingInput {
+    toolCallId: string;
+    question: string;
+    /** Suggested answers, or null for a free-text question. */
+    options: string[] | null;
+    /** ISO timestamp after which the question expires (the round then resumes without it). */
+    expiresAt: string | null;
+    createdAt: string | null;
+}
+/**
+ * How a synchronously answered turn ended.
+ * - `completed`: the final reply is in the response.
+ * - `input_required`: the agent asked the user; see `pendingInputs` and
+ *   answer with `answerPendingInput`.
+ * - `in_progress`: the turn goes on without this request; follow it on
+ *   `channelId` (`streamFromChannel`) or read the chat later.
+ * - `injected`: the chat was busy, so the message was delivered into the
+ *   running (or parked) turn; nothing was answered by this request.
+ */
+type TurnStatus = 'completed' | 'input_required' | 'in_progress' | 'injected';
+/** LLM usage of one request (the reply plus its tool rounds). */
+interface TurnUsage {
+    calls: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Null when calls were made but none could be priced. */
+    costUsd: number | null;
+    unpricedCalls: number;
+    errors: number;
+}
+interface TurnState {
+    status: TurnStatus;
+    pendingInputs: PendingInput[];
+    /** Channel of the turn still going on (`in_progress`) or of the parked turn (`injected`). */
+    channelId: string | null;
+    /** Null when the server could not determine it (or predates Sinas 0.5). */
+    usage: TurnUsage | null;
+}
+/** Result of a non-streaming `sendMessage`. The base fields are unchanged; the turn state is Sinas 0.5+. */
+interface MessageSendResult extends ChatMessage, TurnState {
+}
+interface InvokeOptions {
+    /** Session key for conversation continuity across invokes. */
+    sessionKey?: string;
+    /** Archive the session's existing chat and start fresh. */
+    reset?: boolean;
+    /** Agent input variables (only used when a new chat is created). */
+    input?: Record<string, unknown>;
+}
+interface InvokeResult extends TurnState {
+    /** The final reply (`completed`); what the agent said before asking or waiting otherwise; empty when `injected`. */
+    reply: string;
+    chatId: string;
+    sessionKey: string | null;
+}
+interface AnswerPendingInputOptions {
+    /**
+     * Wait for the resumed turn and return its result instead of a channel to
+     * stream it from.
+     */
+    wait?: boolean;
+}
+/** The answer was recorded (HTTP 202, without `wait`). */
+interface PendingInputAnswerAccepted {
+    status: 'answered';
+    toolCallId: string;
+    /** The answer was the round's last outstanding completion; its resume is queued. */
+    resumed: boolean;
+    /** The last completion, but the resume could not be queued yet; it is retried shortly. */
+    resumePending: boolean;
+    /** Where the resumed turn streams, when `resumed` or `resumePending`. */
+    channelId: string | null;
+    message: string;
+}
+/** The resumed turn's result (HTTP 200, with `wait: true`). */
+interface PendingInputAnswerResult extends TurnState {
+    toolCallId: string;
+    chatId: string;
+    reply: string;
+    /** The message `reply` comes from, when there is one. */
+    message: ChatMessageFull | null;
+}
+interface StreamOptions {
+    /**
+     * Stream the model's thinking text (Sinas 0.5+). Without it, a stream still
+     * gets one empty `thinking` when the model starts thinking.
+     */
+    includeThinking?: boolean;
+}
+interface StreamFromChannelOptions extends StreamOptions {
+    /** Last received stream entry id to resume after (default "0": from the start). */
+    lastId?: string;
+}
+/**
+ * How a stream ended. `completed`: the turn finished. `suspended`: the turn
+ * is parked waiting on the user (an ask_user question); the answer resumes it
+ * on a new channel. `closed`: the connection ended without a `done` event.
+ */
+interface StreamDone {
+    status: 'completed' | 'suspended' | 'closed' | (string & {});
 }
 interface TextContentPart {
     type: 'text';
@@ -186,6 +315,26 @@ interface SSEChunk {
     event: string;
     data: string;
 }
+/** Data of an `input_required` stream event: the agent asked the user (ask_user). */
+interface InputRequiredEvent {
+    type: 'input_required';
+    tool_call_id: string;
+    question: string;
+    options?: string[] | null;
+    expires_at?: string | null;
+}
+/**
+ * Data of a `round_suspended` stream event: the tool round is parked on
+ * deferred work (questions, background runs, sub-agents). It resumes on
+ * `channel_id` when that work lands by itself.
+ */
+interface RoundSuspendedEvent {
+    type: 'round_suspended';
+    tool_call_ids: string[];
+    channel_id?: string | null;
+    pending_completion_id?: string;
+    usage?: Record<string, unknown> | null;
+}
 interface Collection {
     id: string;
     namespace: string;
@@ -380,11 +529,85 @@ declare function stateDelete(client: SinasClient, ns: string, key: string): Prom
 declare function stateList(client: SinasClient, ns: string): Promise<StateListResult>;
 
 declare function createChat(client: SinasClient, agentRef: string, input?: Record<string, unknown>): Promise<ChatCreateResult>;
-declare function sendMessage(client: SinasClient, chatId: string, content: MessageContent): Promise<ChatMessage>;
+/**
+ * Send a message and wait for the turn (non-streaming). On Sinas 0.5+ the
+ * result says how the turn ended (`status`): with `input_required`, answer
+ * the questions in `pendingInputs` with `answerPendingInput`.
+ */
+declare function sendMessage(client: SinasClient, chatId: string, content: MessageContent): Promise<MessageSendResult>;
+/**
+ * Synchronous agent invoke: send a message, get the reply. Creates the chat
+ * (or reuses the one for `sessionKey`). Check `status`: with
+ * `input_required`, answer `pendingInputs` via `answerPendingInput`
+ * (`{ wait: true }` returns the resumed turn's result the same way).
+ */
+declare function invokeAgent(client: SinasClient, agentRef: string, message: MessageContent, options?: InvokeOptions): Promise<InvokeResult>;
 declare function getChat(client: SinasClient, chatId: string): Promise<ChatDetail>;
-declare function approveToolCall(client: SinasClient, chatId: string, toolCallId: string, approved: boolean): Promise<ApprovalResult>;
-declare function streamFromChannel(client: SinasClient, chatId: string, channelId: string, onChunk: (chunk: SSEChunk) => void, onDone?: () => void, onError?: (error: Error) => void): AbortController;
-declare function streamMessage(client: SinasClient, chatId: string, content: MessageContent, onChunk: (chunk: SSEChunk) => void, onDone?: () => void, onError?: (error: Error) => void): AbortController;
+/**
+ * Approve or reject a tool call that asked for approval. On Sinas 0.5+,
+ * `resume` says whether the round resumes now (`queued`, follow `channelId`)
+ * or waits for decisions on its other calls (`waiting`, nothing to stream);
+ * `approvalResumeChannel(result, approved)` picks the channel to follow.
+ */
+declare function approveToolCall(client: SinasClient, chatId: string, toolCallId: string, approved: boolean, options?: ApproveToolCallOptions): Promise<ApprovalResult>;
+/** The ask_user questions the chat is suspended on (Sinas 0.5+). */
+declare function listPendingInputs(client: SinasClient, chatId: string): Promise<PendingInput[]>;
+/**
+ * Answer an ask_user question; the answer becomes the call's tool result.
+ * Without `wait`, resolves once the answer is recorded: follow
+ * `answerResumeChannel(result)` (when not null) to stream the resumed turn.
+ * With `{ wait: true }`, resolves with the resumed turn's result instead
+ * (`input_required` again if the agent asks again).
+ */
+declare function answerPendingInput(client: SinasClient, chatId: string, toolCallId: string, answer: string, options: AnswerPendingInputOptions & {
+    wait: true;
+}): Promise<PendingInputAnswerResult>;
+declare function answerPendingInput(client: SinasClient, chatId: string, toolCallId: string, answer: string, options?: AnswerPendingInputOptions & {
+    wait?: false;
+}): Promise<PendingInputAnswerAccepted>;
+declare function answerPendingInput(client: SinasClient, chatId: string, toolCallId: string, answer: string, options?: AnswerPendingInputOptions): Promise<PendingInputAnswerAccepted | PendingInputAnswerResult>;
+/**
+ * Follow a stream channel: the stream of a resumed round (after an approval
+ * or an answer), an `in_progress` turn, or a reconnect.
+ */
+declare function streamFromChannel(client: SinasClient, chatId: string, channelId: string, onChunk: (chunk: SSEChunk) => void, onDone?: (done: StreamDone) => void, onError?: (error: Error) => void, options?: StreamFromChannelOptions): AbortController;
+/** Send a message and stream the turn as SSE events. */
+declare function streamMessage(client: SinasClient, chatId: string, content: MessageContent, onChunk: (chunk: SSEChunk) => void, onDone?: (done: StreamDone) => void, onError?: (error: Error) => void, options?: StreamOptions): AbortController;
+
+/**
+ * One ask_user question from the API (`GET /chats/{id}/pending-input`, the
+ * chat detail, a turn result, or an `input_required` stream event), or null
+ * when the value isn't one.
+ */
+declare function parsePendingInput(raw: unknown): PendingInput | null;
+declare function parsePendingInputs(raw: unknown): PendingInput[];
+/**
+ * The question an SSE chunk announces, or null. Streams send it as its own
+ * `input_required` event; some earlier backends sent an inline turn's as a
+ * `message` event whose data has `type: "input_required"`. Both are handled.
+ */
+declare function pendingInputFromChunk(chunk: SSEChunk): PendingInput | null;
+/**
+ * The channel to follow after an approval decision, or null when there is
+ * nothing to stream yet. A round with several asked calls resumes once,
+ * after its last decision; until then the response says `resume: "waiting"`.
+ * On servers before 0.5 (no `resume` field) only an approval resumed.
+ */
+declare function approvalResumeChannel(result: {
+    resume?: string | null;
+    channelId?: string | null;
+}, approved?: boolean): string | null;
+/**
+ * The channel to follow after answering a question (202 response), or null.
+ * The answer resumes the conversation only when it was the round's last
+ * outstanding completion (`resumed`) or that resume is being retried
+ * (`resumePending`).
+ */
+declare function answerResumeChannel(result: {
+    resumed?: boolean;
+    resumePending?: boolean;
+    channelId?: string | null;
+}): string | null;
 
 declare function listCollections(client: SinasClient): Promise<Collection[]>;
 declare function listFiles(client: SinasClient, namespace: string, collection: string): Promise<FileInfo[]>;
@@ -428,4 +651,4 @@ declare class SinasTimeoutError extends SinasError {
     constructor(message?: string);
 }
 
-export { type AgentBatchItem, type ApprovalRequest, type ApprovalResult, type AudioContentPart, type AuthMode, type AuthUser, type BatchExecutionItem, type BatchStatus, type ChatCreateResult, type ChatDetail, type ChatMessage, type ChatMessageFull, type Collection, type ComponentContentPart, type ContentPart, type EnqueueFunctionOptions, type EnqueueFunctionResult, type FileContentPart, type FileInfo, type FileUploadRequest, type FileUrlResult, type FunctionResult, type ImageContentPart, type InfoResponse, type LoginRequest, type LoginResponse, type MessageContent, type OTPVerifyRequest, type OTPVerifyResponse, type PermissionCheckRequest, type PermissionCheckResponse, type PermissionCheckResult, type QueryResult, type RefreshResponse, type SSEChunk, SinasAuthError, SinasClient, SinasClientAuth, type SinasClientOptions, type SinasConfig, SinasError, SinasNotFoundError, SinasPermissionError, SinasTimeoutError, type StateGetResult, type StateListResult, type SubmitAgentBatchOptions, type SubmitAgentBatchResult, type SubmitFunctionBatchOptions, type SubmitFunctionBatchResult, type TextContentPart, type ToolCallInfo, approveToolCall, cancelBatch, checkPermissions, createChat, enqueueFunction, executeFunction, executeQuery, generateFileUrl, getBatch, getChat, getInfo, getMe, listBatchExecutions, listCollections, listFiles, login, logout, refresh, sendMessage, stateDelete, stateGet, stateList, stateSet, streamFromChannel, streamMessage, submitAgentBatch, submitFunctionBatch, uploadFile, verifyOTP };
+export { type AgentBatchItem, type AnswerPendingInputOptions, type ApprovalRequest, type ApprovalResult, type ApprovalResume, type ApproveToolCallOptions, type AudioContentPart, type AuthMode, type AuthUser, type BatchExecutionItem, type BatchStatus, type ChatCreateResult, type ChatDetail, type ChatMessage, type ChatMessageFull, type Collection, type ComponentContentPart, type ContentPart, type EnqueueFunctionOptions, type EnqueueFunctionResult, type FileContentPart, type FileInfo, type FileUploadRequest, type FileUrlResult, type FunctionResult, type ImageContentPart, type InfoResponse, type InputRequiredEvent, type InvokeOptions, type InvokeResult, type LoginRequest, type LoginResponse, type MessageContent, type MessageSendResult, type OTPVerifyRequest, type OTPVerifyResponse, type PendingInput, type PendingInputAnswerAccepted, type PendingInputAnswerResult, type PermissionCheckRequest, type PermissionCheckResponse, type PermissionCheckResult, type QueryResult, type RefreshResponse, type RoundSuspendedEvent, type SSEChunk, SinasAuthError, SinasClient, SinasClientAuth, type SinasClientOptions, type SinasConfig, SinasError, SinasNotFoundError, SinasPermissionError, SinasTimeoutError, type StateGetResult, type StateListResult, type StreamDone, type StreamFromChannelOptions, type StreamOptions, type SubmitAgentBatchOptions, type SubmitAgentBatchResult, type SubmitFunctionBatchOptions, type SubmitFunctionBatchResult, type TextContentPart, type ToolCallInfo, type TurnState, type TurnStatus, type TurnUsage, answerPendingInput, answerResumeChannel, approvalResumeChannel, approveToolCall, cancelBatch, checkPermissions, createChat, enqueueFunction, executeFunction, executeQuery, generateFileUrl, getBatch, getChat, getInfo, getMe, invokeAgent, listBatchExecutions, listCollections, listFiles, listPendingInputs, login, logout, parsePendingInput, parsePendingInputs, pendingInputFromChunk, refresh, sendMessage, stateDelete, stateGet, stateList, stateSet, streamFromChannel, streamMessage, submitAgentBatch, submitFunctionBatch, uploadFile, verifyOTP };

package/dist/client.js

@@ -6,6 +6,9 @@ import {
   SinasNotFoundError,
   SinasPermissionError,
   SinasTimeoutError,
+  answerPendingInput,
+  answerResumeChannel,
+  approvalResumeChannel,
   approveToolCall,
   cancelBatch,
   checkPermissions,
@@ -18,11 +21,16 @@ import {
   getChat,
   getInfo,
   getMe,
+  invokeAgent,
   listBatchExecutions,
   listCollections,
   listFiles,
+  listPendingInputs,
   login,
   logout,
+  parsePendingInput,
+  parsePendingInputs,
+  pendingInputFromChunk,
   refresh,
   sendMessage,
   stateDelete,
@@ -35,7 +43,7 @@ import {
   submitFunctionBatch,
   uploadFile,
   verifyOTP
-} from "./chunk-QDIOYYBA.js";
+} from "./chunk-RHQVV5O6.js";
 export {
   SinasAuthError,
   SinasClient,
@@ -44,6 +52,9 @@ export {
   SinasNotFoundError,
   SinasPermissionError,
   SinasTimeoutError,
+  answerPendingInput,
+  answerResumeChannel,
+  approvalResumeChannel,
   approveToolCall,
   cancelBatch,
   checkPermissions,
@@ -56,11 +67,16 @@ export {
   getChat,
   getInfo,
   getMe,
+  invokeAgent,
   listBatchExecutions,
   listCollections,
   listFiles,
+  listPendingInputs,
   login,
   logout,
+  parsePendingInput,
+  parsePendingInputs,
+  pendingInputFromChunk,
   refresh,
   sendMessage,
   stateDelete,