mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-08-31 08:13:11 +03:00
chengyongruandGitHub
4d204ba077
* feat(tui): support pasting clipboard images * fix(tui): keep image placeholders atomic * fix(tui): reconcile duplicate image placeholders * fix(tui): retain highlighted image placeholders * fix(tui): preserve image placeholder layout * fix(tui): keep image display state local * fix(tui): reject images in commands
1422 lines
46 KiB
TypeScript
1422 lines
46 KiB
TypeScript
export type ConnectionStatus =
|
|
| "starting"
|
|
| "connecting"
|
|
| "connected"
|
|
| "reconnecting"
|
|
| "unavailable"
|
|
| "closed"
|
|
| "error"
|
|
|
|
export interface ConnectionStatusInfo {
|
|
endpoint: string
|
|
attempt: number
|
|
elapsedMs: number
|
|
retryInMs?: number
|
|
health?: GatewayHealthStatus
|
|
}
|
|
|
|
export type GatewayHealthStatus = "ready" | "degraded" | "unreachable"
|
|
|
|
export interface ToolProgressEvent {
|
|
version?: number
|
|
phase?: "start" | "end" | "error" | string
|
|
call_id?: string
|
|
name?: string
|
|
arguments?: unknown
|
|
result?: unknown
|
|
error?: unknown
|
|
files?: unknown[]
|
|
embeds?: unknown[]
|
|
}
|
|
|
|
export interface FileEditEvent {
|
|
version?: number
|
|
call_id?: string
|
|
tool?: string
|
|
path?: string
|
|
absolute_path?: string
|
|
phase?: "start" | "end" | "error" | string
|
|
added?: number
|
|
deleted?: number
|
|
approximate?: boolean
|
|
status?: "editing" | "done" | "error" | string
|
|
operation?: "edit" | "delete" | string
|
|
binary?: boolean
|
|
error?: string
|
|
diff?: FileDiff
|
|
}
|
|
|
|
interface FileDiff {
|
|
format: "unified" | string
|
|
context?: number
|
|
truncated?: boolean
|
|
text?: string
|
|
}
|
|
|
|
export interface MediaAttachment {
|
|
kind: "image" | "video" | "file"
|
|
url: string
|
|
name?: string
|
|
}
|
|
|
|
export interface OutboundMedia {
|
|
data_url: string
|
|
name?: string
|
|
}
|
|
|
|
export interface WorkspaceScopePayload {
|
|
project_path: string
|
|
project_name?: string
|
|
access_mode: "restricted" | "full"
|
|
restrict_to_workspace?: boolean
|
|
}
|
|
|
|
export interface RuntimeControls {
|
|
modelPresets: Array<{ name: string; model: string }>
|
|
canUseFullAccess: boolean
|
|
}
|
|
|
|
export type RecoveryStatus = "resuming" | "awaiting_user" | "recovered" | "failed"
|
|
|
|
export interface RecoveryState {
|
|
status: RecoveryStatus
|
|
recovery_id: string
|
|
reason?: string
|
|
attempts?: number
|
|
can_continue?: boolean
|
|
}
|
|
|
|
export type InboundEvent =
|
|
| { event: "ready"; chat_id: string; client_id: string }
|
|
| {
|
|
event: "attached"
|
|
chat_id: string
|
|
model_preset?: string | null
|
|
usage?: TokenUsage
|
|
recovery_state?: RecoveryState
|
|
}
|
|
| {
|
|
event: "message_accepted"
|
|
chat_id: string
|
|
turn_id: string
|
|
starts_turn?: boolean
|
|
active_turn_id?: string
|
|
started_at?: number
|
|
}
|
|
| {
|
|
event: "user_message"
|
|
chat_id: string
|
|
text: string
|
|
turn_id?: string
|
|
active_turn_id?: string
|
|
starts_turn: boolean
|
|
started_at?: number
|
|
media_urls?: MediaAttachment[]
|
|
}
|
|
| {
|
|
event: "message"
|
|
chat_id: string
|
|
text: string
|
|
kind?: "tool_hint" | "progress" | "reasoning"
|
|
tool_events?: ToolProgressEvent[]
|
|
turn_id?: string
|
|
}
|
|
| { event: "file_edit"; chat_id: string; edits: FileEditEvent[]; turn_id?: string }
|
|
| { event: "delta"; chat_id: string; text: string; stream_id?: string; turn_id?: string }
|
|
| {
|
|
event: "stream_end"
|
|
chat_id: string
|
|
text?: string
|
|
stream_id?: string
|
|
resuming?: boolean
|
|
merge_next?: boolean
|
|
turn_id?: string
|
|
}
|
|
| { event: "reasoning_delta"; chat_id: string; text: string; turn_id?: string }
|
|
| { event: "reasoning_end"; chat_id: string; turn_id?: string }
|
|
| {
|
|
event: "turn_end"
|
|
chat_id: string
|
|
latency_ms?: number
|
|
turn_id?: string
|
|
usage?: TokenUsage
|
|
context_window_tokens?: number
|
|
goal_state?: Record<string, unknown>
|
|
}
|
|
| {
|
|
event: "goal_status"
|
|
chat_id: string
|
|
status: "running" | "idle"
|
|
started_at?: number
|
|
turn_id?: string
|
|
}
|
|
| { event: "goal_state"; chat_id: string; goal_state: Record<string, unknown> }
|
|
| ({ event: "recovery_state"; chat_id: string } & RecoveryState)
|
|
| {
|
|
event: "session_updated"
|
|
chat_id: string
|
|
scope?: string
|
|
workspace_scope?: WorkspaceScopePayload
|
|
}
|
|
| { event: "runtime_model_updated"; model_name: string; model_preset?: string | null }
|
|
| {
|
|
event: "turn_model_updated"
|
|
chat_id: string
|
|
model_name: string
|
|
model_preset?: string | null
|
|
context_window_tokens?: number
|
|
}
|
|
| { event: "error"; chat_id?: string; detail?: string; reason?: string; turn_id?: string }
|
|
|
|
type OutboundEvent =
|
|
| { type: "new_chat"; workspace_scope?: WorkspaceScopePayload }
|
|
| { type: "fork_chat"; source_chat_id: string; before_user_index: number; title?: string }
|
|
| { type: "attach"; chat_id: string }
|
|
| { type: "set_workspace_scope"; chat_id: string; workspace_scope: WorkspaceScopePayload }
|
|
| {
|
|
type: "webui_request"
|
|
request_id: string
|
|
action: string
|
|
payload: Record<string, unknown>
|
|
}
|
|
| {
|
|
type: "message"
|
|
chat_id: string
|
|
content: string
|
|
turn_id: string
|
|
webui: true
|
|
workspace_scope?: WorkspaceScopePayload
|
|
media?: OutboundMedia[]
|
|
cli_apps?: Array<{ name: string }>
|
|
mcp_presets?: Array<{ name: string }>
|
|
session_mentions?: SessionMention[]
|
|
}
|
|
|
|
export interface ClientOptions {
|
|
url?: string
|
|
resolveConnection?: () => Promise<GatewayConnection>
|
|
checkHealth?: () => Promise<GatewayHealthStatus>
|
|
onConnection?: (connection: GatewayConnection) => void
|
|
targetEndpoint?: string
|
|
startupFailureDelayMs?: number
|
|
startupRetryMaxDelayMs?: number
|
|
chatId?: string
|
|
initialWorkspaceScope?: WorkspaceScopePayload
|
|
reconnectDelayMs?: number
|
|
onEvent: (event: InboundEvent) => void
|
|
onStatus: (status: ConnectionStatus, detail?: string, info?: ConnectionStatusInfo) => void
|
|
}
|
|
|
|
export interface GatewayApiConnection {
|
|
apiUrl: string
|
|
apiToken: string
|
|
}
|
|
|
|
export interface GatewayConnection extends GatewayApiConnection {
|
|
wsUrl: string
|
|
}
|
|
|
|
export type ApiReauthenticator = (
|
|
rejectedApiToken: string,
|
|
) => Promise<GatewayApiConnection>
|
|
|
|
export class GatewayConnectionError extends Error {
|
|
constructor(message: string, readonly retryable: boolean) {
|
|
super(message)
|
|
this.name = "GatewayConnectionError"
|
|
}
|
|
}
|
|
|
|
export interface HistoryMessage {
|
|
role: "user" | "assistant" | "activity"
|
|
content: string
|
|
turnId?: string
|
|
media?: MediaAttachment[]
|
|
toolEvents?: ToolProgressEvent[]
|
|
fileEdits?: FileEditEvent[]
|
|
forkIndex?: number
|
|
}
|
|
|
|
export interface HistorySnapshot {
|
|
messages: HistoryMessage[]
|
|
hasMoreBefore: boolean
|
|
beforeCursor: string | null
|
|
userMessageOffset: number
|
|
}
|
|
|
|
export interface TokenUsage {
|
|
prompt_tokens?: number
|
|
completion_tokens?: number
|
|
cached_tokens?: number
|
|
cache_write_tokens?: number
|
|
total_tokens?: number
|
|
context_tokens?: number
|
|
request_count?: number
|
|
provider_tokens?: number
|
|
estimated_tokens?: number
|
|
cost_usd?: number
|
|
generation_ms?: number
|
|
measured_completion_tokens?: number
|
|
ttft_ms?: number
|
|
timed_requests?: number
|
|
}
|
|
|
|
export interface SessionContextSnapshot {
|
|
totalMessages: number
|
|
archivedMessages: number
|
|
replayMessages: number
|
|
estimatedReplayTokens: number
|
|
estimatedSummaryTokens: number
|
|
estimatedSessionTokens: number
|
|
archivedSummary: string | null
|
|
archivedSummaryAt: string | null
|
|
lastUsage: TokenUsage | null
|
|
}
|
|
|
|
interface SessionMention {
|
|
name: string
|
|
session_key: string
|
|
title?: string
|
|
}
|
|
|
|
export interface MentionCandidate {
|
|
kind: "session" | "cli" | "mcp"
|
|
name: string
|
|
targetName?: string
|
|
displayName: string
|
|
description: string
|
|
session?: SessionMention
|
|
}
|
|
|
|
export interface SkillCandidate {
|
|
name: string
|
|
description: string
|
|
source: string
|
|
}
|
|
|
|
export interface MessageOptions {
|
|
media?: OutboundMedia[]
|
|
cliApps?: Array<{ name: string }>
|
|
mcpPresets?: Array<{ name: string }>
|
|
sessionMentions?: SessionMention[]
|
|
userShell?: boolean
|
|
}
|
|
|
|
export interface SlashCommand {
|
|
command: string
|
|
title: string
|
|
description: string
|
|
argHint: string
|
|
lifecycle: SlashCommandLifecycle
|
|
acceptsArgs: boolean
|
|
}
|
|
|
|
export type SlashCommandLifecycle =
|
|
| "side_channel"
|
|
| "finalize_active_turn"
|
|
| "stop_active_turn"
|
|
| "agent_turn"
|
|
| "agent_turn_with_args"
|
|
|
|
export interface SessionSummary {
|
|
chatId: string
|
|
title: string
|
|
preview: string
|
|
createdAt: string | null
|
|
updatedAt: string | null
|
|
runStartedAt: number | null
|
|
modelPreset: string | null
|
|
recoveryState?: RecoveryState | null
|
|
workspaceScope?: WorkspaceScopePayload | null
|
|
pinned: boolean
|
|
archived: boolean
|
|
}
|
|
|
|
const SKILL_REFERENCE_NAME = /^[A-Za-z0-9_-]+$/u
|
|
|
|
const SLASH_COMMAND_LIFECYCLES = new Set([
|
|
"side_channel",
|
|
"finalize_active_turn",
|
|
"stop_active_turn",
|
|
"agent_turn",
|
|
"agent_turn_with_args",
|
|
])
|
|
|
|
const CHAT_EVENTS = new Set([
|
|
"attached",
|
|
"message_accepted",
|
|
"user_message",
|
|
"message",
|
|
"file_edit",
|
|
"delta",
|
|
"stream_end",
|
|
"reasoning_delta",
|
|
"reasoning_end",
|
|
"turn_end",
|
|
"goal_status",
|
|
"goal_state",
|
|
"recovery_state",
|
|
"session_updated",
|
|
"turn_model_updated",
|
|
"error",
|
|
])
|
|
|
|
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
return Boolean(value) && typeof value === "object" && !Array.isArray(value)
|
|
}
|
|
|
|
function optional(value: unknown, type: "boolean" | "number" | "string"): boolean {
|
|
return value === undefined || typeof value === type
|
|
}
|
|
|
|
function isToolEvent(value: unknown): value is ToolProgressEvent {
|
|
if (!isRecord(value)) return false
|
|
return optional(value.version, "number")
|
|
&& optional(value.phase, "string")
|
|
&& optional(value.call_id, "string")
|
|
&& optional(value.name, "string")
|
|
&& (value.files === undefined || Array.isArray(value.files))
|
|
&& (value.embeds === undefined || Array.isArray(value.embeds))
|
|
}
|
|
|
|
function isFileEdit(value: unknown): value is FileEditEvent {
|
|
if (!isRecord(value)) return false
|
|
return optional(value.version, "number")
|
|
&& optional(value.call_id, "string")
|
|
&& optional(value.tool, "string")
|
|
&& optional(value.path, "string")
|
|
&& optional(value.absolute_path, "string")
|
|
&& optional(value.phase, "string")
|
|
&& optional(value.status, "string")
|
|
&& optional(value.added, "number")
|
|
&& optional(value.deleted, "number")
|
|
&& optional(value.approximate, "boolean")
|
|
&& optional(value.operation, "string")
|
|
&& optional(value.binary, "boolean")
|
|
&& optional(value.error, "string")
|
|
&& (value.diff === undefined || isFileDiff(value.diff))
|
|
}
|
|
|
|
function isFileDiff(value: unknown): value is FileDiff {
|
|
if (!isRecord(value) || typeof value.format !== "string") return false
|
|
return optional(value.context, "number")
|
|
&& optional(value.truncated, "boolean")
|
|
&& optional(value.text, "string")
|
|
}
|
|
|
|
function isTokenUsage(value: unknown): value is TokenUsage {
|
|
if (!isRecord(value)) return false
|
|
return [
|
|
"prompt_tokens",
|
|
"completion_tokens",
|
|
"cached_tokens",
|
|
"cache_write_tokens",
|
|
"total_tokens",
|
|
"context_tokens",
|
|
"request_count",
|
|
"provider_tokens",
|
|
"estimated_tokens",
|
|
"cost_usd",
|
|
"generation_ms",
|
|
"measured_completion_tokens",
|
|
"ttft_ms",
|
|
"timed_requests",
|
|
].every((key) => optional(value[key], "number"))
|
|
}
|
|
|
|
function isMediaAttachment(value: unknown): value is MediaAttachment {
|
|
return isRecord(value)
|
|
&& (value.kind === "image" || value.kind === "video" || value.kind === "file")
|
|
&& typeof value.url === "string"
|
|
&& optional(value.name, "string")
|
|
}
|
|
|
|
function isWorkspaceScope(value: unknown): value is WorkspaceScopePayload {
|
|
return isRecord(value)
|
|
&& typeof value.project_path === "string"
|
|
&& (value.access_mode === "restricted" || value.access_mode === "full")
|
|
&& optional(value.project_name, "string")
|
|
&& optional(value.restrict_to_workspace, "boolean")
|
|
}
|
|
|
|
function isRecoveryState(value: unknown): value is RecoveryState {
|
|
return isRecord(value)
|
|
&& ["resuming", "awaiting_user", "recovered", "failed"].includes(String(value.status))
|
|
&& typeof value.recovery_id === "string"
|
|
&& optional(value.reason, "string")
|
|
&& optional(value.attempts, "number")
|
|
&& optional(value.can_continue, "boolean")
|
|
}
|
|
|
|
interface WebUIResponseEvent {
|
|
event: "webui_response"
|
|
request_id: string
|
|
ok: boolean
|
|
result?: unknown
|
|
error?: { status: number; message: string }
|
|
}
|
|
|
|
function decodeWebUIResponse(value: unknown): WebUIResponseEvent | null | undefined {
|
|
if (!isRecord(value) || value.event !== "webui_response") return undefined
|
|
if (typeof value.request_id !== "string" || typeof value.ok !== "boolean") return null
|
|
if (value.ok) return value as unknown as WebUIResponseEvent
|
|
return isRecord(value.error)
|
|
&& typeof value.error.status === "number"
|
|
&& typeof value.error.message === "string"
|
|
? value as unknown as WebUIResponseEvent
|
|
: null
|
|
}
|
|
|
|
function decodeInboundEvent(value: unknown): InboundEvent | null | undefined {
|
|
if (!isRecord(value)) return null
|
|
const record = value
|
|
const name = record.event
|
|
if (typeof name !== "string") return null
|
|
if (name === "ready") {
|
|
return typeof record.chat_id === "string" && typeof record.client_id === "string"
|
|
? value as InboundEvent
|
|
: null
|
|
}
|
|
if (name === "runtime_model_updated") {
|
|
return typeof record.model_name === "string"
|
|
&& (record.model_preset === undefined
|
|
|| record.model_preset === null
|
|
|| typeof record.model_preset === "string")
|
|
? value as InboundEvent
|
|
: null
|
|
}
|
|
if (name === "error" && (record.chat_id === undefined || typeof record.chat_id === "string")) {
|
|
return optional(record.detail, "string") && optional(record.reason, "string")
|
|
? value as InboundEvent
|
|
: null
|
|
}
|
|
if (!CHAT_EVENTS.has(name)) return undefined // Forward-compatible additive event.
|
|
if (typeof record.chat_id !== "string") return null
|
|
if (
|
|
name === "attached"
|
|
&& ((record.model_preset !== undefined
|
|
&& record.model_preset !== null
|
|
&& typeof record.model_preset !== "string")
|
|
|| (record.usage !== undefined && !isTokenUsage(record.usage))
|
|
|| (record.recovery_state !== undefined && !isRecoveryState(record.recovery_state)))
|
|
) return null
|
|
if (
|
|
["user_message", "message", "delta", "reasoning_delta"].includes(name)
|
|
&& typeof record.text !== "string"
|
|
) {
|
|
return null
|
|
}
|
|
if (
|
|
["message_accepted", "user_message"].includes(name)
|
|
&& (
|
|
(name === "user_message" && typeof record.starts_turn !== "boolean")
|
|
|| !optional(record.starts_turn, "boolean")
|
|
|| !optional(record.active_turn_id, "string")
|
|
|| !optional(record.started_at, "number")
|
|
)
|
|
) return null
|
|
if (
|
|
name === "user_message"
|
|
&& record.media_urls !== undefined
|
|
&& (!Array.isArray(record.media_urls) || !record.media_urls.every(isMediaAttachment))
|
|
) return null
|
|
if (
|
|
name === "message"
|
|
&& record.tool_events !== undefined
|
|
&& (!Array.isArray(record.tool_events) || !record.tool_events.every(isToolEvent))
|
|
) return null
|
|
if (name === "file_edit" && (!Array.isArray(record.edits) || !record.edits.every(isFileEdit))) {
|
|
return null
|
|
}
|
|
if (
|
|
name === "stream_end"
|
|
&& (!optional(record.text, "string")
|
|
|| !optional(record.resuming, "boolean")
|
|
|| !optional(record.merge_next, "boolean"))
|
|
) return null
|
|
if (
|
|
name === "turn_end"
|
|
&& (!optional(record.latency_ms, "number")
|
|
|| !optional(record.context_window_tokens, "number")
|
|
|| (record.usage !== undefined && !isTokenUsage(record.usage))
|
|
|| (record.goal_state !== undefined && !isRecord(record.goal_state)))
|
|
) return null
|
|
if (name === "goal_status" && record.status !== "running" && record.status !== "idle") return null
|
|
if (name === "goal_state" && !isRecord(record.goal_state)) return null
|
|
if (name === "recovery_state" && !isRecoveryState(record)) return null
|
|
if (
|
|
name === "session_updated"
|
|
&& (!optional(record.scope, "string")
|
|
|| (record.workspace_scope !== undefined && !isWorkspaceScope(record.workspace_scope)))
|
|
) return null
|
|
if (
|
|
name === "turn_model_updated"
|
|
&& (typeof record.model_name !== "string"
|
|
|| (record.model_preset !== undefined
|
|
&& record.model_preset !== null
|
|
&& typeof record.model_preset !== "string")
|
|
|| !optional(record.context_window_tokens, "number"))
|
|
) return null
|
|
return value as InboundEvent
|
|
}
|
|
|
|
async function fetchApi(
|
|
apiUrl: string,
|
|
apiToken: string,
|
|
path: string,
|
|
reauthenticate?: ApiReauthenticator,
|
|
): Promise<Response> {
|
|
const request = (connection: GatewayApiConnection) => fetch(`${connection.apiUrl}${path}`, {
|
|
headers: { Authorization: `Bearer ${connection.apiToken}` },
|
|
})
|
|
const response = await request({ apiUrl, apiToken })
|
|
if (response.status !== 401 || !reauthenticate) return response
|
|
return request(await reauthenticate(apiToken))
|
|
}
|
|
|
|
export async function fetchHistory(
|
|
apiUrl: string,
|
|
apiToken: string,
|
|
chatId: string,
|
|
beforeCursor?: string | null,
|
|
reauthenticate?: ApiReauthenticator,
|
|
): Promise<HistorySnapshot> {
|
|
if (!apiUrl || !apiToken) {
|
|
return { messages: [], hasMoreBefore: false, beforeCursor: null, userMessageOffset: 0 }
|
|
}
|
|
const key = encodeURIComponent(`websocket:${chatId}`)
|
|
const params = new URLSearchParams({ limit: "120", direction: "latest" })
|
|
if (beforeCursor) params.set("before", beforeCursor)
|
|
const response = await fetchApi(
|
|
apiUrl,
|
|
apiToken,
|
|
`/api/sessions/${key}/webui-thread?${params}`,
|
|
reauthenticate,
|
|
)
|
|
if (response.status === 404) {
|
|
return { messages: [], hasMoreBefore: false, beforeCursor: null, userMessageOffset: 0 }
|
|
}
|
|
if (!response.ok) throw new Error(`history request failed: HTTP ${response.status}`)
|
|
const payload = (await response.json()) as {
|
|
messages?: Array<Record<string, unknown>>
|
|
page?: { has_more_before?: boolean; before_cursor?: string; user_message_offset?: number }
|
|
}
|
|
let userIndex = typeof payload.page?.user_message_offset === "number"
|
|
? Math.max(0, payload.page.user_message_offset)
|
|
: 0
|
|
const messages: HistoryMessage[] = []
|
|
for (const message of payload.messages || []) {
|
|
const role = message.role
|
|
const content = message.content
|
|
if (role === "tool" && message.kind === "trace") {
|
|
const traces = Array.isArray(message.traces)
|
|
? message.traces.filter((value): value is string => typeof value === "string")
|
|
: []
|
|
const toolEvents = Array.isArray(message.toolEvents)
|
|
? message.toolEvents.filter(isToolEvent)
|
|
: undefined
|
|
const fileEdits = Array.isArray(message.fileEdits)
|
|
? message.fileEdits.filter(isFileEdit)
|
|
: undefined
|
|
const activity = traces.join("\n") || (typeof content === "string" ? content : "")
|
|
messages.push({
|
|
role: "activity",
|
|
content: activity,
|
|
...(toolEvents?.length ? { toolEvents } : {}),
|
|
...(fileEdits?.length ? { fileEdits } : {}),
|
|
})
|
|
continue
|
|
}
|
|
if (
|
|
(role !== "user" && role !== "assistant")
|
|
|| message.kind === "reasoning"
|
|
|| typeof content !== "string"
|
|
) {
|
|
continue
|
|
}
|
|
const media = Array.isArray(message.media) ? message.media.filter(isMediaAttachment) : []
|
|
if (role === "user") {
|
|
if (!content.trim() && !media.length) continue
|
|
userIndex += 1
|
|
messages.push({
|
|
role: "user",
|
|
content,
|
|
...(media.length ? { media } : {}),
|
|
...(typeof message.turnId === "string" ? { turnId: message.turnId } : {}),
|
|
})
|
|
} else if (content.trim()) {
|
|
messages.push({ role: "assistant", content, forkIndex: userIndex })
|
|
}
|
|
}
|
|
return {
|
|
messages,
|
|
hasMoreBefore: payload.page?.has_more_before === true,
|
|
beforeCursor: typeof payload.page?.before_cursor === "string"
|
|
? payload.page.before_cursor
|
|
: null,
|
|
userMessageOffset: typeof payload.page?.user_message_offset === "number"
|
|
? Math.max(0, payload.page.user_message_offset)
|
|
: 0,
|
|
}
|
|
}
|
|
|
|
export async function fetchSessionContext(
|
|
apiUrl: string,
|
|
apiToken: string,
|
|
chatId: string,
|
|
reauthenticate?: ApiReauthenticator,
|
|
): Promise<SessionContextSnapshot | null> {
|
|
if (!apiUrl || !apiToken) return null
|
|
const key = encodeURIComponent(`websocket:${chatId}`)
|
|
const response = await fetchApi(
|
|
apiUrl,
|
|
apiToken,
|
|
`/api/sessions/${key}/context`,
|
|
reauthenticate,
|
|
)
|
|
if (response.status === 404) return null
|
|
if (!response.ok) throw new Error(`context request failed: HTTP ${response.status}`)
|
|
const value = await response.json() as Record<string, unknown>
|
|
const number = (key: string) => typeof value[key] === "number" ? value[key] as number : 0
|
|
return {
|
|
totalMessages: number("total_messages"),
|
|
archivedMessages: number("archived_messages"),
|
|
replayMessages: number("replay_messages"),
|
|
estimatedReplayTokens: number("estimated_replay_tokens"),
|
|
estimatedSummaryTokens: number("estimated_summary_tokens"),
|
|
estimatedSessionTokens: number("estimated_session_tokens"),
|
|
archivedSummary: typeof value.archived_summary === "string" ? value.archived_summary : null,
|
|
archivedSummaryAt: typeof value.archived_summary_at === "string"
|
|
? value.archived_summary_at
|
|
: null,
|
|
lastUsage: isTokenUsage(value.last_usage) ? value.last_usage : null,
|
|
}
|
|
}
|
|
|
|
export async function fetchSlashCommands(
|
|
apiUrl: string,
|
|
apiToken: string,
|
|
reauthenticate?: ApiReauthenticator,
|
|
): Promise<SlashCommand[]> {
|
|
if (!apiUrl || !apiToken) return []
|
|
const response = await fetchApi(apiUrl, apiToken, "/api/commands", reauthenticate)
|
|
if (!response.ok) throw new Error(`command request failed: HTTP ${response.status}`)
|
|
const payload = await response.json() as { commands?: unknown[] }
|
|
return (payload.commands || []).flatMap((value) => {
|
|
if (
|
|
!isRecord(value)
|
|
|| typeof value.command !== "string"
|
|
|| typeof value.lifecycle !== "string"
|
|
|| !SLASH_COMMAND_LIFECYCLES.has(value.lifecycle)
|
|
) return []
|
|
return [{
|
|
command: value.command,
|
|
title: typeof value.title === "string" ? value.title : value.command,
|
|
description: typeof value.description === "string" ? value.description : "",
|
|
argHint: typeof value.arg_hint === "string" ? value.arg_hint : "",
|
|
lifecycle: value.lifecycle as SlashCommandLifecycle,
|
|
acceptsArgs: value.accepts_args === true,
|
|
}]
|
|
})
|
|
}
|
|
|
|
export async function fetchAvailableSkills(
|
|
apiUrl: string,
|
|
apiToken: string,
|
|
reauthenticate?: ApiReauthenticator,
|
|
): Promise<SkillCandidate[]> {
|
|
if (!apiUrl || !apiToken) return []
|
|
const response = await fetchApi(apiUrl, apiToken, "/api/webui/skills", reauthenticate)
|
|
if (!response.ok) throw new Error(`skill request failed: HTTP ${response.status}`)
|
|
const payload = await response.json() as { skills?: unknown[] }
|
|
return (payload.skills || []).flatMap((value) => {
|
|
if (
|
|
!isRecord(value)
|
|
|| typeof value.name !== "string"
|
|
|| !SKILL_REFERENCE_NAME.test(value.name)
|
|
|| value.enabled !== true
|
|
|| value.available !== true
|
|
) return []
|
|
return [{
|
|
name: value.name,
|
|
description: typeof value.description === "string" ? value.description : value.name,
|
|
source: typeof value.source === "string" ? value.source : "unknown",
|
|
}]
|
|
})
|
|
}
|
|
|
|
export async function fetchRuntimeControls(
|
|
apiUrl: string,
|
|
apiToken: string,
|
|
reauthenticate?: ApiReauthenticator,
|
|
): Promise<RuntimeControls> {
|
|
if (!apiUrl || !apiToken) return { modelPresets: [], canUseFullAccess: false }
|
|
const [settingsResponse, workspacesResponse] = await Promise.all([
|
|
fetchApi(apiUrl, apiToken, "/api/settings", reauthenticate),
|
|
fetchApi(apiUrl, apiToken, "/api/workspaces", reauthenticate).catch(() => null),
|
|
])
|
|
if (!settingsResponse.ok) {
|
|
throw new Error(`settings request failed: HTTP ${settingsResponse.status}`)
|
|
}
|
|
const settings = await settingsResponse.json() as { model_presets?: unknown[] }
|
|
const workspaces = workspacesResponse?.ok
|
|
? await workspacesResponse.json() as { controls?: unknown }
|
|
: {}
|
|
const modelPresets = (settings.model_presets || []).flatMap((value) => {
|
|
if (!isRecord(value) || typeof value.name !== "string" || typeof value.model !== "string") {
|
|
return []
|
|
}
|
|
const name = value.name.trim()
|
|
return name ? [{ name, model: value.model.trim() }] : []
|
|
})
|
|
const controls = isRecord(workspaces.controls) ? workspaces.controls : {}
|
|
return {
|
|
modelPresets,
|
|
canUseFullAccess: controls.can_use_full_access === true,
|
|
}
|
|
}
|
|
|
|
export async function fetchSessions(
|
|
apiUrl: string,
|
|
apiToken: string,
|
|
reauthenticate?: ApiReauthenticator,
|
|
): Promise<SessionSummary[]> {
|
|
if (!apiUrl || !apiToken) return []
|
|
const [response, sidebarResponse] = await Promise.all([
|
|
fetchApi(apiUrl, apiToken, "/api/sessions", reauthenticate),
|
|
fetchApi(apiUrl, apiToken, "/api/webui/sidebar-state", reauthenticate).catch(() => null),
|
|
])
|
|
if (!response.ok) throw new Error(`session request failed: HTTP ${response.status}`)
|
|
const payload = await response.json() as { sessions?: unknown[] }
|
|
let sidebar: Record<string, unknown> = {}
|
|
if (sidebarResponse?.ok) {
|
|
try {
|
|
const value: unknown = await sidebarResponse.json()
|
|
if (isRecord(value)) sidebar = value
|
|
} catch {
|
|
// Session navigation remains available against older or damaged sidebar state.
|
|
}
|
|
}
|
|
const pinned = new Set(Array.isArray(sidebar.pinned_keys) ? sidebar.pinned_keys : [])
|
|
const archived = new Set(Array.isArray(sidebar.archived_keys) ? sidebar.archived_keys : [])
|
|
const titles = isRecord(sidebar.title_overrides) ? sidebar.title_overrides : {}
|
|
return (payload.sessions || []).flatMap((value) => {
|
|
if (!isRecord(value) || typeof value.key !== "string" || !value.key.startsWith("websocket:")) {
|
|
return []
|
|
}
|
|
const chatId = value.key.slice("websocket:".length)
|
|
if (!chatId) return []
|
|
const titleOverride = titles[value.key]
|
|
return [{
|
|
chatId,
|
|
title: typeof titleOverride === "string"
|
|
? titleOverride
|
|
: typeof value.title === "string" ? value.title : "",
|
|
preview: typeof value.preview === "string" ? value.preview : "",
|
|
createdAt: typeof value.created_at === "string" ? value.created_at : null,
|
|
updatedAt: typeof value.updated_at === "string" ? value.updated_at : null,
|
|
runStartedAt: typeof value.run_started_at === "number" ? value.run_started_at : null,
|
|
modelPreset: typeof value.model_preset === "string" && value.model_preset.trim()
|
|
? value.model_preset.trim()
|
|
: null,
|
|
...(isRecoveryState(value.recovery_state)
|
|
? { recoveryState: value.recovery_state }
|
|
: {}),
|
|
...(isWorkspaceScope(value.workspace_scope) ? { workspaceScope: value.workspace_scope } : {}),
|
|
pinned: pinned.has(value.key),
|
|
archived: archived.has(value.key),
|
|
}]
|
|
})
|
|
}
|
|
|
|
function sessionMentionName(session: SessionSummary): string {
|
|
const label = (session.title || session.preview || "session")
|
|
.normalize("NFKC")
|
|
.replace(/\s+/gu, "-")
|
|
.replace(/[^\p{L}\p{N}_-]+/gu, "")
|
|
.replace(/-+/gu, "-")
|
|
.replace(/^-|-$/gu, "")
|
|
return Array.from(label || "session").slice(0, 40).join("")
|
|
}
|
|
|
|
/** Installed capabilities and saved chats share one mention namespace. */
|
|
export async function fetchMentionCandidates(
|
|
apiUrl: string,
|
|
apiToken: string,
|
|
reauthenticate?: ApiReauthenticator,
|
|
): Promise<MentionCandidate[]> {
|
|
if (!apiUrl || !apiToken) return []
|
|
const [sessions, appsResponse, mcpResponse] = await Promise.all([
|
|
fetchSessions(apiUrl, apiToken, reauthenticate),
|
|
fetchApi(
|
|
apiUrl,
|
|
apiToken,
|
|
"/api/settings/cli-apps?installed_only=1",
|
|
reauthenticate,
|
|
).catch(() => null),
|
|
fetchApi(apiUrl, apiToken, "/api/settings/mcp-presets", reauthenticate).catch(() => null),
|
|
])
|
|
const used = new Set<string>()
|
|
const uniqueName = (raw: string) => {
|
|
const base = raw || "session"
|
|
let name = base
|
|
let suffix = 2
|
|
while (used.has(name.toLocaleLowerCase())) name = `${base}-${suffix++}`
|
|
used.add(name.toLocaleLowerCase())
|
|
return name
|
|
}
|
|
const candidates: MentionCandidate[] = []
|
|
if (appsResponse?.ok) {
|
|
const payload = await appsResponse.json() as { apps?: unknown[] }
|
|
for (const value of payload.apps || []) {
|
|
if (!isRecord(value) || value.installed !== true || typeof value.name !== "string") continue
|
|
const name = uniqueName(value.name)
|
|
candidates.push({
|
|
kind: "cli",
|
|
name,
|
|
...(name === value.name ? {} : { targetName: value.name }),
|
|
displayName: typeof value.display_name === "string" ? value.display_name : name,
|
|
description: typeof value.description === "string" ? value.description : "CLI app",
|
|
})
|
|
}
|
|
}
|
|
if (mcpResponse?.ok) {
|
|
const payload = await mcpResponse.json() as { presets?: unknown[] }
|
|
for (const value of payload.presets || []) {
|
|
if (
|
|
!isRecord(value)
|
|
|| value.installed !== true
|
|
|| value.configured !== true
|
|
|| typeof value.name !== "string"
|
|
) continue
|
|
const name = uniqueName(value.name)
|
|
candidates.push({
|
|
kind: "mcp",
|
|
name,
|
|
...(name === value.name ? {} : { targetName: value.name }),
|
|
displayName: typeof value.display_name === "string" ? value.display_name : name,
|
|
description: typeof value.description === "string" ? value.description : "MCP server",
|
|
})
|
|
}
|
|
}
|
|
for (const session of sessions) {
|
|
const name = uniqueName(sessionMentionName(session))
|
|
candidates.push({
|
|
kind: "session",
|
|
name,
|
|
displayName: sessionLabelForMention(session),
|
|
description: session.preview || "Saved session",
|
|
session: {
|
|
name,
|
|
session_key: `websocket:${session.chatId}`,
|
|
title: session.title || undefined,
|
|
},
|
|
})
|
|
}
|
|
return candidates
|
|
}
|
|
|
|
function sessionLabelForMention(session: SessionSummary): string {
|
|
return (session.title || session.preview || "Untitled chat").replace(/\s+/gu, " ").trim()
|
|
}
|
|
|
|
/** Resolve fresh short-lived credentials once the local gateway is reachable. */
|
|
export async function fetchGatewayConnection(
|
|
bootstrapUrl: string,
|
|
bootstrapSecret: string,
|
|
apiUrl: string,
|
|
clientId: string,
|
|
): Promise<GatewayConnection> {
|
|
const response = await fetch(bootstrapUrl, {
|
|
headers: bootstrapSecret ? { "X-Nanobot-Auth": bootstrapSecret } : {},
|
|
})
|
|
if (!response.ok) {
|
|
const retryable = response.status === 408 || response.status === 429 || response.status >= 500
|
|
throw new GatewayConnectionError(
|
|
`gateway bootstrap failed: HTTP ${response.status}`,
|
|
retryable,
|
|
)
|
|
}
|
|
let payload: unknown
|
|
try {
|
|
payload = await response.json()
|
|
} catch {
|
|
throw new GatewayConnectionError("gateway bootstrap response is invalid", false)
|
|
}
|
|
if (!isRecord(payload)) {
|
|
throw new GatewayConnectionError("gateway bootstrap response is invalid", false)
|
|
}
|
|
if (typeof payload.ws_url !== "string" || !payload.ws_url.trim()) {
|
|
throw new GatewayConnectionError("gateway bootstrap response is missing ws_url", false)
|
|
}
|
|
let wsUrl: URL
|
|
try {
|
|
wsUrl = new URL(payload.ws_url)
|
|
} catch {
|
|
throw new GatewayConnectionError("gateway bootstrap response has an invalid ws_url", false)
|
|
}
|
|
if (wsUrl.protocol !== "ws:" && wsUrl.protocol !== "wss:") {
|
|
throw new GatewayConnectionError("gateway bootstrap response has an invalid ws_url", false)
|
|
}
|
|
if (typeof payload.token === "string" && payload.token) {
|
|
wsUrl.searchParams.append("token", payload.token)
|
|
}
|
|
wsUrl.searchParams.append("client_id", clientId)
|
|
return {
|
|
wsUrl: wsUrl.toString(),
|
|
apiUrl,
|
|
apiToken: typeof payload.api_token === "string" ? payload.api_token : "",
|
|
}
|
|
}
|
|
|
|
/** Read gateway readiness without sending bootstrap or API credentials. */
|
|
export async function fetchGatewayHealth(
|
|
healthUrl: string,
|
|
timeoutMs = 400,
|
|
): Promise<GatewayHealthStatus> {
|
|
const controller = new AbortController()
|
|
const timer = setTimeout(() => controller.abort(), timeoutMs)
|
|
try {
|
|
const response = await fetch(healthUrl, { signal: controller.signal })
|
|
if (response.status !== 200 && response.status !== 503) return "unreachable"
|
|
const payload: unknown = await response.json()
|
|
if (!isRecord(payload)) return "unreachable"
|
|
if (
|
|
response.status === 503
|
|
&& payload.status === "degraded"
|
|
&& payload.ready === false
|
|
&& payload.process === "alive"
|
|
) return "degraded"
|
|
if (response.status === 200 && payload.status === "ok" && payload.ready !== false) {
|
|
return "ready"
|
|
}
|
|
return "unreachable"
|
|
} catch {
|
|
return "unreachable"
|
|
} finally {
|
|
clearTimeout(timer)
|
|
}
|
|
}
|
|
|
|
/** Return only the authority users can act on, never credentials or an authenticated path. */
|
|
export function connectionEndpoint(value: string | undefined): string {
|
|
if (!value) return "local gateway"
|
|
try {
|
|
return new URL(value).host || "local gateway"
|
|
} catch {
|
|
return "local gateway"
|
|
}
|
|
}
|
|
|
|
/** Reduce arbitrary fetch/WebSocket errors to a small set of credential-safe reasons. */
|
|
export function sanitizeConnectionFailure(error: unknown): string {
|
|
const signals: string[] = []
|
|
const seen = new Set<unknown>()
|
|
const collect = (value: unknown): void => {
|
|
if (value === null || value === undefined || seen.has(value)) return
|
|
if (typeof value === "object") seen.add(value)
|
|
if (typeof value === "string") {
|
|
signals.push(value)
|
|
return
|
|
}
|
|
if (value instanceof Error) {
|
|
signals.push(value.name, value.message)
|
|
collect(value.cause)
|
|
if (value instanceof AggregateError) {
|
|
for (const nested of value.errors) collect(nested)
|
|
}
|
|
return
|
|
}
|
|
if (!isRecord(value)) return
|
|
if (typeof value.code === "string") signals.push(value.code)
|
|
collect(value.cause)
|
|
if (Array.isArray(value.errors)) {
|
|
for (const nested of value.errors) collect(nested)
|
|
}
|
|
}
|
|
collect(error)
|
|
const signal = signals.join(" ")
|
|
if (/ECONNREFUSED|connection refused/iu.test(signal)) return "connection refused"
|
|
if (/ETIMEDOUT|timed? out|timeout/iu.test(signal)) return "connection timed out"
|
|
if (/ENOTFOUND|EAI_AGAIN|name not resolved|host not found/iu.test(signal)) {
|
|
return "host not found"
|
|
}
|
|
if (/certificate|TLS|SSL/iu.test(signal)) return "secure connection failed"
|
|
const bootstrapStatus = signal.match(/gateway bootstrap failed:\s*HTTP\s*(\d{3})/iu)
|
|
if (bootstrapStatus?.[1]) return `gateway bootstrap failed: HTTP ${bootstrapStatus[1]}`
|
|
if (/bootstrap response is missing ws_url/iu.test(signal)) {
|
|
return "gateway bootstrap response is missing ws_url"
|
|
}
|
|
if (/bootstrap response (?:has an invalid ws_url|is invalid)/iu.test(signal)) {
|
|
return "gateway bootstrap response is invalid"
|
|
}
|
|
if (/gateway is still starting/iu.test(signal)) return "gateway is still starting"
|
|
if (/fetch failed|failed to fetch|network error/iu.test(signal)) return "network request failed"
|
|
return "connection failed"
|
|
}
|
|
|
|
export class NanobotClient {
|
|
private socket: WebSocket | null = null
|
|
private chatId = ""
|
|
private workspaceScope?: WorkspaceScopePayload
|
|
private reconnectTimer: ReturnType<typeof setTimeout> | null = null
|
|
private reconnectAttempt = 0
|
|
private closedByClient = false
|
|
private opening = false
|
|
private connectedOnce = false
|
|
private connectionAttempt = 0
|
|
private retryStartedAt = 0
|
|
private nextRetryAt = 0
|
|
private lastFailure = ""
|
|
private healthStatus: GatewayHealthStatus | undefined
|
|
private failureEscalationTimer: ReturnType<typeof setTimeout> | null = null
|
|
private readonly endpoint: string
|
|
private readonly pendingMutations = new Map<string, {
|
|
resolve: (value: unknown) => void
|
|
reject: (error: Error) => void
|
|
timer: ReturnType<typeof setTimeout>
|
|
}>()
|
|
|
|
constructor(private readonly options: ClientOptions) {
|
|
this.endpoint = options.targetEndpoint || connectionEndpoint(options.url)
|
|
}
|
|
|
|
get activeChatId(): string {
|
|
return this.chatId
|
|
}
|
|
|
|
connect(): void {
|
|
this.closedByClient = false
|
|
this.connectionAttempt = 0
|
|
this.reconnectAttempt = 0
|
|
this.retryStartedAt = Date.now()
|
|
this.nextRetryAt = 0
|
|
this.lastFailure = ""
|
|
this.healthStatus = undefined
|
|
void this.open()
|
|
}
|
|
|
|
private async open(): Promise<void> {
|
|
if (this.socket || this.opening || this.closedByClient) return
|
|
this.opening = true
|
|
this.nextRetryAt = 0
|
|
this.connectionAttempt += 1
|
|
this.reportConnectionProgress()
|
|
let url = this.options.url
|
|
try {
|
|
if (this.options.resolveConnection) {
|
|
const connection = await this.options.resolveConnection()
|
|
if (this.closedByClient) return
|
|
this.options.onConnection?.(connection)
|
|
url = connection.wsUrl
|
|
}
|
|
} catch (error) {
|
|
if (!this.closedByClient) {
|
|
this.lastFailure = sanitizeConnectionFailure(error)
|
|
if (error instanceof GatewayConnectionError && !error.retryable) {
|
|
this.clearFailureEscalation()
|
|
this.options.onStatus("error", this.lastFailure, this.connectionInfo())
|
|
return
|
|
}
|
|
await this.checkHealthAndScheduleReconnect()
|
|
}
|
|
return
|
|
} finally {
|
|
this.opening = false
|
|
}
|
|
if (!url) {
|
|
this.options.onStatus("error", "gateway URL is not configured", this.connectionInfo())
|
|
return
|
|
}
|
|
let socket: WebSocket
|
|
try {
|
|
socket = new WebSocket(url)
|
|
} catch (error) {
|
|
this.lastFailure = sanitizeConnectionFailure(error)
|
|
await this.checkHealthAndScheduleReconnect()
|
|
return
|
|
}
|
|
let opened = false
|
|
this.socket = socket
|
|
socket.addEventListener("open", () => {
|
|
if (this.socket !== socket) return
|
|
opened = true
|
|
this.connectedOnce = true
|
|
this.connectionAttempt = 0
|
|
this.reconnectAttempt = 0
|
|
this.retryStartedAt = 0
|
|
this.nextRetryAt = 0
|
|
this.lastFailure = ""
|
|
this.healthStatus = "ready"
|
|
this.clearFailureEscalation()
|
|
this.options.onStatus("connected", undefined, this.connectionInfo())
|
|
})
|
|
socket.addEventListener("message", (message) => {
|
|
if (this.socket === socket) this.handleMessage(String(message.data))
|
|
})
|
|
socket.addEventListener("error", () => {
|
|
if (this.socket !== socket) return
|
|
this.lastFailure = "connection failed"
|
|
this.reportRetryState()
|
|
})
|
|
socket.addEventListener("close", () => {
|
|
if (this.socket !== socket) return
|
|
this.socket = null
|
|
this.rejectPendingMutations("gateway connection closed")
|
|
if (this.closedByClient) {
|
|
this.options.onStatus("closed")
|
|
return
|
|
}
|
|
if (opened) {
|
|
this.connectionAttempt = 0
|
|
this.reconnectAttempt = 0
|
|
this.retryStartedAt = Date.now()
|
|
}
|
|
if (!this.lastFailure) this.lastFailure = "connection closed"
|
|
this.reportRetryState()
|
|
void this.checkHealthAndScheduleReconnect()
|
|
})
|
|
}
|
|
|
|
close(): void {
|
|
this.closedByClient = true
|
|
if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
|
|
this.reconnectTimer = null
|
|
this.clearFailureEscalation()
|
|
const socket = this.socket
|
|
this.socket = null
|
|
socket?.close()
|
|
this.rejectPendingMutations("gateway connection closed")
|
|
}
|
|
|
|
send(content: string, options: MessageOptions = {}): string {
|
|
if (!this.chatId) throw new Error("chat is not ready")
|
|
const turnId = crypto.randomUUID()
|
|
this.write({
|
|
type: "message",
|
|
chat_id: this.chatId,
|
|
content,
|
|
turn_id: turnId,
|
|
webui: true,
|
|
...(this.workspaceScope ? { workspace_scope: this.workspaceScope } : {}),
|
|
...(options.userShell ? { user_shell: true } : {}),
|
|
...(options.media?.length ? { media: options.media } : {}),
|
|
...(options.cliApps?.length ? { cli_apps: options.cliApps } : {}),
|
|
...(options.mcpPresets?.length ? { mcp_presets: options.mcpPresets } : {}),
|
|
...(options.sessionMentions?.length
|
|
? { session_mentions: options.sessionMentions }
|
|
: {}),
|
|
})
|
|
return turnId
|
|
}
|
|
|
|
attach(chatId: string): void {
|
|
if (!chatId) throw new Error("chat id is required")
|
|
this.workspaceScope = undefined
|
|
this.write({ type: "attach", chat_id: chatId })
|
|
}
|
|
|
|
newChat(scope?: WorkspaceScopePayload): void {
|
|
this.workspaceScope = scope
|
|
this.write({ type: "new_chat", ...(scope ? { workspace_scope: scope } : {}) })
|
|
}
|
|
|
|
forkChat(sourceChatId: string, beforeUserIndex: number, title?: string): void {
|
|
this.write({
|
|
type: "fork_chat",
|
|
source_chat_id: sourceChatId,
|
|
before_user_index: beforeUserIndex,
|
|
...(title?.trim() ? { title: title.trim() } : {}),
|
|
})
|
|
}
|
|
|
|
setWorkspaceScope(scope: WorkspaceScopePayload): void {
|
|
if (!this.chatId) throw new Error("chat is not ready")
|
|
this.workspaceScope = scope
|
|
this.write({ type: "set_workspace_scope", chat_id: this.chatId, workspace_scope: scope })
|
|
}
|
|
|
|
updateRecovery(
|
|
action: "continue" | "dismiss",
|
|
chatId: string,
|
|
recoveryId: string,
|
|
): Promise<RecoveryState> {
|
|
return this.requestMutation<unknown>(`recovery.${action}`, {
|
|
chat_id: chatId,
|
|
recovery_id: recoveryId,
|
|
}).then((result) => {
|
|
if (!isRecoveryState(result)) throw new Error("gateway returned an invalid recovery state")
|
|
return result
|
|
})
|
|
}
|
|
|
|
private requestMutation<T>(
|
|
action: string,
|
|
payload: Record<string, unknown> = {},
|
|
timeoutMs = 20_000,
|
|
): Promise<T> {
|
|
if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
|
|
return Promise.reject(new Error("gateway connection is not open"))
|
|
}
|
|
const requestId = crypto.randomUUID()
|
|
const frame = JSON.stringify({
|
|
type: "webui_request",
|
|
request_id: requestId,
|
|
action,
|
|
payload,
|
|
} satisfies OutboundEvent)
|
|
return new Promise<T>((resolve, reject) => {
|
|
const timer = setTimeout(() => {
|
|
this.pendingMutations.delete(requestId)
|
|
reject(new Error(`gateway request timed out after ${timeoutMs}ms`))
|
|
}, timeoutMs)
|
|
this.pendingMutations.set(requestId, {
|
|
resolve: (value) => resolve(value as T),
|
|
reject,
|
|
timer,
|
|
})
|
|
try {
|
|
this.socket?.send(frame)
|
|
} catch {
|
|
clearTimeout(timer)
|
|
this.pendingMutations.delete(requestId)
|
|
reject(new Error("could not send gateway request"))
|
|
}
|
|
})
|
|
}
|
|
|
|
private rejectPendingMutations(message: string): void {
|
|
for (const pending of this.pendingMutations.values()) {
|
|
clearTimeout(pending.timer)
|
|
pending.reject(new Error(message))
|
|
}
|
|
this.pendingMutations.clear()
|
|
}
|
|
|
|
private handleMessage(raw: string): void {
|
|
let value: unknown
|
|
try {
|
|
value = JSON.parse(raw) as unknown
|
|
} catch {
|
|
this.options.onStatus("error", "gateway sent invalid JSON")
|
|
return
|
|
}
|
|
const response = decodeWebUIResponse(value)
|
|
if (response === null) {
|
|
this.options.onStatus("error", "gateway sent an invalid event")
|
|
return
|
|
}
|
|
if (response) {
|
|
const pending = this.pendingMutations.get(response.request_id)
|
|
if (!pending) return
|
|
clearTimeout(pending.timer)
|
|
this.pendingMutations.delete(response.request_id)
|
|
if (response.ok) pending.resolve(response.result)
|
|
else pending.reject(new Error(response.error?.message || "gateway request failed"))
|
|
return
|
|
}
|
|
const event = decodeInboundEvent(value)
|
|
if (event === undefined) return
|
|
if (event === null) {
|
|
this.options.onStatus("error", "gateway sent an invalid event")
|
|
return
|
|
}
|
|
|
|
if (event.event === "ready") {
|
|
const requestedChatId = this.chatId || this.options.chatId
|
|
if (requestedChatId) {
|
|
this.chatId = requestedChatId
|
|
this.write({ type: "attach", chat_id: this.chatId })
|
|
} else {
|
|
this.newChat(this.options.initialWorkspaceScope)
|
|
}
|
|
} else if (event.event === "attached") {
|
|
this.chatId = event.chat_id
|
|
} else if (event.event === "session_updated" && event.workspace_scope) {
|
|
this.workspaceScope = event.workspace_scope
|
|
}
|
|
this.options.onEvent(event)
|
|
}
|
|
|
|
private scheduleReconnect(): void {
|
|
if (this.reconnectTimer || this.closedByClient) return
|
|
if (!this.retryStartedAt) this.retryStartedAt = Date.now()
|
|
const base = this.options.reconnectDelayMs ?? 500
|
|
const maxDelay = this.connectedOnce
|
|
? 8_000
|
|
: this.options.startupRetryMaxDelayMs ?? 8_000
|
|
const delay = Math.min(maxDelay, base * 2 ** Math.min(this.reconnectAttempt++, 4))
|
|
this.nextRetryAt = Date.now() + delay
|
|
this.reportRetryState()
|
|
this.reconnectTimer = setTimeout(() => {
|
|
this.reconnectTimer = null
|
|
void this.open()
|
|
}, delay)
|
|
}
|
|
|
|
private async checkHealthAndScheduleReconnect(): Promise<void> {
|
|
if (this.options.checkHealth) {
|
|
try {
|
|
this.healthStatus = await this.options.checkHealth()
|
|
} catch {
|
|
this.healthStatus = "unreachable"
|
|
}
|
|
}
|
|
if (!this.closedByClient) this.scheduleReconnect()
|
|
}
|
|
|
|
private connectionInfo(): ConnectionStatusInfo {
|
|
return {
|
|
endpoint: this.endpoint,
|
|
attempt: Math.max(1, this.connectionAttempt),
|
|
elapsedMs: this.retryStartedAt ? Math.max(0, Date.now() - this.retryStartedAt) : 0,
|
|
...(this.nextRetryAt
|
|
? { retryInMs: Math.max(0, this.nextRetryAt - Date.now()) }
|
|
: {}),
|
|
...(this.healthStatus ? { health: this.healthStatus } : {}),
|
|
}
|
|
}
|
|
|
|
private reportConnectionProgress(): void {
|
|
if (this.connectedOnce) {
|
|
this.options.onStatus("reconnecting", this.lastFailure || undefined, this.connectionInfo())
|
|
return
|
|
}
|
|
const phase = this.options.resolveConnection ? "starting" : "connecting"
|
|
this.options.onStatus(phase, undefined, this.connectionInfo())
|
|
}
|
|
|
|
private reportRetryState(): void {
|
|
const info = this.connectionInfo()
|
|
if (this.connectedOnce) {
|
|
this.options.onStatus("reconnecting", this.lastFailure, info)
|
|
return
|
|
}
|
|
const failureDelay = this.options.startupFailureDelayMs ?? 3_000
|
|
if (info.elapsedMs >= failureDelay) {
|
|
this.clearFailureEscalation()
|
|
this.options.onStatus("unavailable", this.lastFailure, info)
|
|
return
|
|
}
|
|
this.reportConnectionProgress()
|
|
if (this.failureEscalationTimer) return
|
|
this.failureEscalationTimer = setTimeout(() => {
|
|
this.failureEscalationTimer = null
|
|
if (this.closedByClient || this.connectedOnce || !this.lastFailure) return
|
|
this.options.onStatus("unavailable", this.lastFailure, this.connectionInfo())
|
|
}, Math.max(0, failureDelay - info.elapsedMs))
|
|
}
|
|
|
|
private clearFailureEscalation(): void {
|
|
if (this.failureEscalationTimer) clearTimeout(this.failureEscalationTimer)
|
|
this.failureEscalationTimer = null
|
|
}
|
|
|
|
private write(event: OutboundEvent): void {
|
|
if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
|
|
throw new Error("gateway connection is not open")
|
|
}
|
|
this.socket.send(JSON.stringify(event))
|
|
}
|
|
}
|