/** * Thin client for the LongMemory cloud API (`/api/longmemory`). * * - Every call carries `Authorization: Bearer `; 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 = { 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 if (typeof body.error === 'string') code = body.error else if (body.error !== null && typeof body.error === 'object') { const nested = body.error as Record 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(method: string, path: string, body?: unknown, tokenOverride?: string): Promise> { const token = tokenOverride ?? this.options.token() const base = this.options.baseUrl() const url = `${base}${path}` const headers: Record = { 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> { return this.request('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> { return this.request('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> { const result = await this.request('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> { const result = await this.request('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> { const body: Record = { query, k } if (project !== undefined && project !== '') body.filters = { project_id: project } return this.request('POST', '/memory/query', body) } /** Read one memory by id (memory token). */ read(id: string): Promise> { return this.request('GET', `/memory/${encodeURIComponent(id)}`) } /** List memories with optional paging filters (memory token). */ list(options: { limit?: number; offset?: number; project?: string } = {}): Promise> { 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('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> { const body: Record = { 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('POST', '/memory/add', body) } /** List the account's projects (memory token). */ projects(): Promise> { return this.request('GET', '/dashboard/projects') } /** Storage configuration state (memory token). */ storageStatus(): Promise>> { return this.request>('GET', '/storage/status') } /** List the cloud skill center inventory (memory token). */ listSkills(): Promise> { return this.request('GET', '/skills') } /** Fetch one skill bundle with hashed, base64-carried files (memory token). */ skillBundle(name: string): Promise> { return this.request('GET', `/skills/${encodeURIComponent(name)}/bundle`) } /** Create one skill in the center; `expected_revision` must be 0 (memory token). */ createSkill(body: Record): Promise> { return this.request('POST', '/skills', body) } /** Replace one skill's files/description at an expected revision (memory token). */ updateSkill(name: string, body: Record): Promise> { return this.request('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 = { 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> { 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> { 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}` }