dsh-brain/src/api.ts

509 lines
19 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* Thin client for the LongMemory cloud API (`/api/longmemory`).
*
* - Every call carries `Authorization: Bearer <token>`; the owner is injected
* server-side, so no request ever names a user.
* - Errors normalize to `{ status, code, message }`; a network failure is
* status 0 with code `network_error`, so callers can retry safely.
* - Only metadata ever leaves this process: turn ids, timestamps, statuses, and
* the memory content the user explicitly asked to save.
*/
import type { TurnStatus } from './reporter.ts'
/** Normalized non-2xx outcome. */
export interface CloudError {
/** HTTP status, or 0 for a transport failure. */
status: number
/** Machine-readable code from the service, or a local fallback. */
code: string
/** Human-readable message (already safe to show: never contains secrets). */
message: string
/** Milliseconds the service asked us to wait (429 handling). */
retryAfterMs?: number
}
/** One request outcome. */
export type CloudResult<T> = { ok: true; status: number; data: T } | { ok: false; error: CloudError }
/** Activity turn payload — exactly the six fields the service accepts. */
export interface TurnPayload {
client_id: string
conversation_id: string
turn_id: string
status: TurnStatus
started_at: number
completed_at: number
}
/** Activity turn outcome. */
export interface TurnAck {
recorded?: boolean
duplicate?: boolean
}
/** One transcript message sent for turn summarization (text only). */
export interface SummaryMessage {
role: 'user' | 'assistant'
text: string
}
/** `POST /activity/summary` request body. */
export interface SummaryPayload {
conversation_id: string
turn_id: string
messages: SummaryMessage[]
}
/** Staging outcome: how many proposals were queued for confirmation. */
export interface SummaryAck {
staged?: number
skipped?: number
full?: boolean
}
/** One search hit as the service indexes it. */
export interface MemoryHit {
id?: string
content?: string
tags?: string[]
project_id?: string | null
primary_sector?: string
revision?: number
created_at?: number
updated_at?: number
[key: string]: unknown
}
/** `POST /memory/query` response. */
export interface SearchResponse {
matches?: MemoryHit[]
total?: number
search_mode?: string
[key: string]: unknown
}
/** `GET /memory/all` response. */
export interface ListResponse {
items?: MemoryHit[]
total?: number
[key: string]: unknown
}
/** `GET /dashboard/projects` response. */
export interface ProjectsResponse {
projects?: { id?: string; name?: string; [key: string]: unknown }[]
[key: string]: unknown
}
/** `POST /memory/add` response. */
export interface AddResponse {
id?: string
revision?: number
deleted?: boolean
state?: string
remote_saved?: boolean
memory?: MemoryHit | null
[key: string]: unknown
}
/** One skill as the cloud skill center lists it (`GET /skills` item). */
export interface SkillSummary {
name: string
description?: string
category?: string | null
execution_mode?: string
enabled?: boolean
revision?: number
manifest_sha256?: string
files?: number
bytes?: number
script_changed?: boolean
[key: string]: unknown
}
/** `GET /skills` response. */
export interface SkillListing {
items?: SkillSummary[]
total?: number
trash_total?: number
[key: string]: unknown
}
/** One file inside a skill bundle (`GET /skills/:name/bundle`). */
export interface SkillBundleFile {
path: string
sha256: string
size?: number
encoding?: string
/** Base64 payload; present on every bundle file. */
data: string
}
/** `GET /skills/:name/bundle` response. */
export interface SkillBundle {
name: string
revision: number
manifest_sha256: string
script_changed?: boolean
script_changes?: string[]
files: SkillBundleFile[]
[key: string]: unknown
}
/** One file in a skill write payload: text inline, or base64 for binaries. */
export type SkillUploadFile = { path: string; content: string } | { path: string; base64: string }
/** `POST /skills` / `PATCH /skills/:name` outcome. */
export interface SkillWriteResult {
skill?: SkillSummary
revision?: number
manifest_sha256?: string
[key: string]: unknown
}
/** One dashboard account as the login endpoint returns it. */
export interface AccountInfo {
id?: string
username?: string
role?: string
[key: string]: unknown
}
/** Outcome of a password login: the account plus the session cookie to spend. */
export interface LoginOutcome {
user: AccountInfo
/** `name=value` pair ready for a Cookie header; never leaves this process. */
sessionCookie: string
}
/** One freshly minted API token. */
export interface IssuedToken {
id?: string
token?: string
scope?: string
label?: string
}
/**
* Derive the dashboard auth root (`/api/auth`) from the memory base URL
* (`.../api/longmemory`): login and token minting live one segment over.
*/
function authBase(baseUrl: string): string {
try {
const url = new URL(baseUrl)
const prefix = url.pathname.replace(/\/longmemory\/?$/i, '')
return `${url.origin}${prefix}/auth`
} catch {
return ''
}
}
/** True when sending a password to this URL is safe (TLS, or loopback). */
export function isSecureLoginTarget(baseUrl: string): boolean {
try {
const url = new URL(baseUrl)
if (url.protocol === 'https:') return true
return url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
} catch {
return false
}
}
/** Pull the first cookie pair out of one or more Set-Cookie headers. */
function sessionCookieOf(headers: Headers): string {
// `getSetCookie` exists on undici/Node 18.14+ but is not in every Headers type.
const withCookies = headers as Headers & { getSetCookie?: () => string[] }
const list = typeof withCookies.getSetCookie === 'function' ? withCookies.getSetCookie() : [headers.get('set-cookie') ?? '']
for (const entry of list) {
if (entry === '') continue
const pair = entry.split(';', 1)[0]
if (pair !== undefined && pair.includes('=') && !pair.startsWith('=')) return pair.trim()
}
return ''
}
/** Options for one {@link CloudClient}. */
export interface CloudClientOptions {
/** Effective base URL (no trailing slash). */
baseUrl: () => string
/** Bearer token for the call's scope. */
token: () => string
/** Request timeout in milliseconds. */
timeoutMs: () => number
}
/** Map one HTTP error body onto a {@link CloudError}. */
function errorFromBody(status: number, raw: string, retryAfterHeader: string | null): CloudError {
let code = `http_${status}`
let message = raw.slice(0, 300)
try {
const parsed: unknown = JSON.parse(raw)
if (parsed !== null && typeof parsed === 'object') {
const body = parsed as Record<string, unknown>
if (typeof body.error === 'string') code = body.error
else if (body.error !== null && typeof body.error === 'object') {
const nested = body.error as Record<string, unknown>
if (typeof nested.code === 'string') code = nested.code
if (typeof nested.message === 'string') message = nested.message
}
if (typeof body.message === 'string') message = body.message
}
} catch {
// Non-JSON error (proxy HTML page, empty body): keep the text snippet.
}
const error: CloudError = { status, code, message: message === '' ? code : message }
if (status === 429) {
const header = retryAfterHeader === null ? Number.NaN : Number(retryAfterHeader)
error.retryAfterMs = Number.isFinite(header) && header > 0 ? header * 1000 : 900_000
}
return error
}
/**
* One cloud endpoint handle. Instances are cheap: construct per call site and
* keep the live settings behind closures so a settings edit applies at once.
*/
export class CloudClient {
constructor(private readonly options: CloudClientOptions) {}
private async request<T>(method: string, path: string, body?: unknown, tokenOverride?: string): Promise<CloudResult<T>> {
const token = tokenOverride ?? this.options.token()
const base = this.options.baseUrl()
const url = `${base}${path}`
const headers: Record<string, string> = { Accept: 'application/json' }
if (token !== '') headers.Authorization = `Bearer ${token}`
const init: RequestInit = { method, headers, signal: AbortSignal.timeout(this.options.timeoutMs()) }
if (body !== undefined) {
headers['Content-Type'] = 'application/json'
init.body = JSON.stringify(body)
}
let response: Response
try {
response = await fetch(url, init)
} catch (error) {
const reason = error instanceof Error ? error.message : String(error)
return { ok: false, error: { status: 0, code: 'network_error', message: `${method} ${path}: ${reason}` } }
}
const text = await response.text().catch(() => '')
if (!response.ok) {
return { ok: false, error: errorFromBody(response.status, text, response.headers.get('retry-after')) }
}
if (text.trim() === '') return { ok: true, status: response.status, data: {} as T }
try {
return { ok: true, status: response.status, data: JSON.parse(text) as T }
} catch {
return { ok: false, error: { status: response.status, code: 'invalid_json', message: 'response was not JSON' } }
}
}
/** Report one conversation turn (activity:write token). */
reportTurn(payload: TurnPayload, token: string): Promise<CloudResult<TurnAck>> {
return this.request<TurnAck>('POST', '/activity/turn', payload, token)
}
/**
* Read-only reachability probe: any HTTP answer (even 401 or 404) proves the
* host is up. This is what separates "服务不可达" from "令牌无效" in the card,
* and it never sends a credential.
*/
async reach(): Promise<{ ok: boolean; status: number; message: string }> {
try {
const response = await fetch(`${this.options.baseUrl()}/status`, {
method: 'GET',
headers: { Accept: 'application/json' },
signal: AbortSignal.timeout(this.options.timeoutMs()),
})
return { ok: true, status: response.status, message: `服务可达(HTTP ${response.status})` }
} catch (error) {
const reason = error instanceof Error ? error.message : String(error)
return { ok: false, status: 0, message: `服务不可达:${reason}` }
}
}
/** Stage one turn summary as pending proposals (summary:write token). */
submitSummary(payload: SummaryPayload, token: string): Promise<CloudResult<SummaryAck>> {
return this.request<SummaryAck>('POST', '/activity/summary', payload, token)
}
/**
* Verify a summary token without staging anything.
*
* The endpoint authenticates before it validates the body, so an empty
* object coming back `400 invalid_input` proves the scope is right.
*/
async probeSummary(token: string): Promise<CloudResult<{ authenticated: true }>> {
const result = await this.request<unknown>('POST', '/activity/summary', {}, token)
if (result.ok) return { ok: true, status: result.status, data: { authenticated: true } }
if (result.error.status === 400) return { ok: true, status: 400, data: { authenticated: true } }
return { ok: false, error: result.error }
}
/**
* Verify an activity token without recording anything.
*
* `/activity/turn` validates auth before the payload, so an empty body that
* comes back `400 invalid_event` proves the token carries `activity:write`.
* A 401/403 is a token problem; anything else is reported verbatim.
*/
async probeActivity(token: string): Promise<CloudResult<{ authenticated: true }>> {
const result = await this.request<unknown>('POST', '/activity/turn', {}, token)
if (result.ok) return { ok: true, status: result.status, data: { authenticated: true } }
// 400 means the credentials were accepted and only the body was rejected.
if (result.error.status === 400) {
return { ok: true, status: 400, data: { authenticated: true } }
}
return { ok: false, error: result.error }
}
/** Keyword search over stored memories (memory token). */
async search(query: string, k: number, project?: string): Promise<CloudResult<SearchResponse>> {
const body: Record<string, unknown> = { query, k }
if (project !== undefined && project !== '') body.filters = { project_id: project }
return this.request<SearchResponse>('POST', '/memory/query', body)
}
/** Read one memory by id (memory token). */
read(id: string): Promise<CloudResult<MemoryHit>> {
return this.request<MemoryHit>('GET', `/memory/${encodeURIComponent(id)}`)
}
/** List memories with optional paging filters (memory token). */
list(options: { limit?: number; offset?: number; project?: string } = {}): Promise<CloudResult<ListResponse>> {
const params = new URLSearchParams()
if (options.limit !== undefined) params.set('limit', String(options.limit))
if (options.offset !== undefined) params.set('offset', String(options.offset))
if (options.project !== undefined && options.project !== '') params.set('project_id', options.project)
const suffix = params.toString() === '' ? '' : `?${params.toString()}`
return this.request<ListResponse>('GET', `/memory/all${suffix}`)
}
/** Store one memory; `operationId` makes the write idempotent (memory token). */
add(input: { content: string; tags?: string[]; project?: string; sector?: string; operationId: string }): Promise<CloudResult<AddResponse>> {
const body: Record<string, unknown> = {
operation_id: input.operationId,
content: input.content,
}
if (input.tags !== undefined && input.tags.length > 0) body.tags = input.tags
if (input.project !== undefined && input.project !== '') body.project_id = input.project
if (input.sector !== undefined && input.sector !== '') body.metadata = { primary_sector: input.sector }
return this.request<AddResponse>('POST', '/memory/add', body)
}
/** List the account's projects (memory token). */
projects(): Promise<CloudResult<ProjectsResponse>> {
return this.request<ProjectsResponse>('GET', '/dashboard/projects')
}
/** Storage configuration state (memory token). */
storageStatus(): Promise<CloudResult<Record<string, unknown>>> {
return this.request<Record<string, unknown>>('GET', '/storage/status')
}
/** List the cloud skill center inventory (memory token). */
listSkills(): Promise<CloudResult<SkillListing>> {
return this.request<SkillListing>('GET', '/skills')
}
/** Fetch one skill bundle with hashed, base64-carried files (memory token). */
skillBundle(name: string): Promise<CloudResult<SkillBundle>> {
return this.request<SkillBundle>('GET', `/skills/${encodeURIComponent(name)}/bundle`)
}
/** Create one skill in the center; `expected_revision` must be 0 (memory token). */
createSkill(body: Record<string, unknown>): Promise<CloudResult<SkillWriteResult>> {
return this.request<SkillWriteResult>('POST', '/skills', body)
}
/** Replace one skill's files/description at an expected revision (memory token). */
updateSkill(name: string, body: Record<string, unknown>): Promise<CloudResult<SkillWriteResult>> {
return this.request<SkillWriteResult>('PATCH', `/skills/${encodeURIComponent(name)}`, body)
}
/**
* One call against the dashboard auth surface (`/api/auth/*`).
*
* These endpoints authorize by session cookie, not by Bearer token, and they
* reject any non-GET without a matching `Origin` (the server's CSRF gate), so
* the origin of the configured base URL is sent explicitly — that is a header
* only a non-browser client can set, which is exactly what this is.
*/
private async authFetch(
method: string,
path: string,
body?: unknown,
cookie?: string,
): Promise<{ ok: true; status: number; body: unknown; headers: Headers } | { ok: false; error: CloudError }> {
const baseUrl = this.options.baseUrl()
const base = authBase(baseUrl)
if (base === '') return { ok: false, error: { status: 0, code: 'invalid_base_url', message: '服务地址无效,无法登录' } }
const headers: Record<string, string> = { Accept: 'application/json' }
try {
headers.Origin = new URL(baseUrl).origin
} catch {
return { ok: false, error: { status: 0, code: 'invalid_base_url', message: '服务地址无效,无法登录' } }
}
if (cookie !== undefined && cookie !== '') headers.Cookie = cookie
const init: RequestInit = { method, headers, signal: AbortSignal.timeout(this.options.timeoutMs()) }
if (body !== undefined) {
headers['Content-Type'] = 'application/json'
init.body = JSON.stringify(body)
}
let response: Response
try {
response = await fetch(`${base}${path}`, init)
} catch (error) {
const reason = error instanceof Error ? error.message : String(error)
return { ok: false, error: { status: 0, code: 'network_error', message: `${method} /auth${path}: ${reason}` } }
}
const text = await response.text().catch(() => '')
if (!response.ok) {
return { ok: false, error: errorFromBody(response.status, text, response.headers.get('retry-after')) }
}
let parsed: unknown = {}
if (text.trim() !== '') {
try {
parsed = JSON.parse(text)
} catch {
parsed = {}
}
}
return { ok: true, status: response.status, body: parsed, headers: response.headers }
}
/**
* Password login against the dashboard.
*
* The password is used once, in this call, and never stored: what comes back
* is a short-lived session cookie that the caller immediately spends on
* {@link CloudClient.mintToken} and then drops.
*/
async login(username: string, password: string): Promise<CloudResult<LoginOutcome>> {
const sent = await this.authFetch('POST', '/login', { username, password })
if (!sent.ok) return sent
const cookie = sessionCookieOf(sent.headers)
if (cookie === '') {
return { ok: false, error: { status: sent.status, code: 'no_session', message: '登录成功,但服务端没有下发会话' } }
}
const body = sent.body as { user?: AccountInfo }
return { ok: true, status: sent.status, data: { user: body.user ?? {}, sessionCookie: cookie } }
}
/** Mint one scoped API token using a live session cookie. */
async mintToken(sessionCookie: string, scope: string, label: string): Promise<CloudResult<IssuedToken>> {
const sent = await this.authFetch('POST', '/tokens', { scope, label }, sessionCookie)
if (!sent.ok) return sent
const body = sent.body as { token?: IssuedToken }
const issued = body.token
if (issued === undefined || typeof issued.token !== 'string' || issued.token === '') {
return { ok: false, error: { status: sent.status, code: 'no_token', message: '服务端没有返回令牌' } }
}
return { ok: true, status: sent.status, data: issued }
}
}
/** Render a {@link CloudError} as one display line. */
export function describeError(error: CloudError): string {
if (error.status === 0) return `网络不可用:${error.message}`
return `HTTP ${error.status} ${error.code}:${error.message}`
}