// Client for the languid service (src/server.ts). Holds no agent credentials: // only the service URL and the owner's bearer token. import type { RunRecord } from './runs.ts' import type { ComputerRules } from './permissions.ts' import type { Policy } from './policy.ts' import { createAssistantMessageEventStream, type AssistantMessage, type AssistantMessageEvent, type AssistantMessageEventStream, type ClientIdentity, type Message, type Model, type SystemMessage, type ToolResultMessage, type UserMessage, } from '@earendil-works/pi-ai' import { xrpc } from './atproto/xrpc.ts' import type { Block, Via, Schedule, Wakeup, StrongRef, Machine, MachineTrigger } from './records.ts' import type { SpaceRecord } from './atproto/space.ts' import type { ToolContent } from './runner.ts' import type { State } from './state.ts' import type { ErrorReport, FeedbackItem, FeedbackReply, ReplyStatus, Sharing, TelemetryStatus } from './telemetry.ts' /** An open approval request, as ai.languid.approval.list returns it. */ export interface ApprovalRequestView { uri: string cid: string thread: string call: { uri: string; cid: string } n?: number method?: string tool: string arguments: string intention?: string computer?: string always?: { command?: string } /** A Machine run's ask: the Machine. It waits with no run. */ machine?: { uri: string; cid: string } expiresAt: string createdAt: string /** Absent for a Machine's ask. */ run?: string } export interface AgentInfo { name: string did: string handle: string space: string model: { provider: string; id: string } blocks: Block[] /** Recorded assistant and compaction usage across retained threads; absent on older services. */ usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; totalTokens: number } computers: string[] threads: { rkey: string; title: string }[] } export type RunEvent = | { seq: number; type: 'text'; text: string } | { seq: number; type: 'tool_call'; id: string; tool: string; arguments: string; computer?: string } | { seq: number; type: 'tool_result'; id: string; tool: string; output: string; isError: boolean } /** Only in runs that ask the owner (the web chat). */ | { seq: number; type: 'approval'; id: string; tool: string; arguments: string; computer?: string } | { seq: number; type: 'decision'; id: string; approved: boolean; reason?: string } /** How the service took a message (ai.languid.agent.run). */ export interface RunStarted { /** The run answering it: a new one, or the thread's running one. Empty for a duplicate with no run going. */ run: string thread: string accepted: 'started' | 'queued' | 'duplicate' /** Where this message's events start in the run's events. */ since: number /** The message record's AT URI. */ message: string } export interface RunStatus { run: string agent: string thread: string status: 'running' | 'done' | 'error' error?: string events: RunEvent[] /** Assistant text streamed so far in the current turn. */ partial?: string stopped?: boolean next: number startedAt: string finishedAt?: string } export interface ServiceModel { provider: string id: string name: string reasoning: boolean input: ('text' | 'image')[] cost: { input: number; output: number; cacheRead: number; cacheWrite: number } contextWindow: number maxTokens: number } export interface ComputerStatus { name: string online: boolean lastSeenAt?: string registeredAt?: string /** Registered by an older version (tailnet runner); can't connect until it joins again. */ legacy?: boolean } export interface ThreadInfo { rkey: string title: string /** What to show for it: its title if the owner named it, else the start of the first user message. */ name: string /** The owner named this thread, so `title` is a name rather than the placeholder it was created with. */ named: boolean createdAt: string updatedAt: string messages: number /** Start of the first user message. */ preview: string } /** Where a client works: the computer its computer tools default to, and its working directory there. */ export interface Session { computer?: string cwd?: string /** The window of the model this client runs turns on, when that isn't the agent's (local inference). */ contextWindow?: number } export interface AgentPermissions { /** Each computer the agent has, and any with rules left for a name it no longer has (attached: false). */ computers: { computer: string; attached: boolean; rules: ComputerRules }[] policy: Policy /** The agent uses the default script rules. */ defaultPolicy: boolean } /** A tool that runs on a computer without asking (ai.languid.computer.permissions). */ export interface PermissionRule { computer: string tool: string } export interface RecordedCall { callId: string tool: string computer?: string needsApproval: boolean blocked?: string } export type OwnerSummary = { did: string; handle: string; createdAt: string; budgetUsd?: number; spentUsd: number; model?: { provider: string; model: string }; agents?: string[] } export class LanguidClient { url: string agent: string /** The client label recorded on user turns this client sends (see VIA in records.ts). */ via: Via = 'api' private headers: Record constructor(url: string, token: string, agent: string) { this.url = url this.agent = agent this.headers = { authorization: `Bearer ${token}` } } createSchedule(input: { prompt: string; startsAt: string; intervalSeconds?: number; enabled?: boolean }) { return this.post<{ schedule: SpaceRecord }>('ai.languid.run.createSchedule', input) } setScheduleEnabled(rkey: string, enabled: boolean) { return this.post('ai.languid.run.setScheduleEnabled', { rkey, enabled }) } deleteSchedule(rkey: string) { return this.post('ai.languid.run.deleteSchedule', { rkey }) } setJobWakeups(enabled: boolean) { return this.post('ai.languid.run.setJobWakeups', { enabled }) } listWakeups() { return this.get<{ schedules: SpaceRecord[]; machines: SpaceRecord[]; wakeups: SpaceRecord[]; pending: StrongRef[]; wakeOnJobEnd: boolean }>('ai.languid.run.list') } /** The agent's runs, newest first (docs/site/records.md). Pass the returned cursor for the next page. */ listRuns(params: { limit?: number; cursor?: string } = {}) { return this.get<{ runs: SpaceRecord[]; cursor?: string }>('ai.languid.run.listRuns', params) } /** The agent's Machines (docs/machines.md), each with its runs today and latest run. */ listMachines() { return this.get<{ machines: (SpaceRecord & { runsToday: number; lastRun?: { uri: string; thread: string; createdAt: string; status: 'done' | 'waiting' | 'pending' } })[] }>('ai.languid.machine.listMachines') } createMachine(input: Partial> & { trigger: Partial & { type: MachineTrigger['type'] } }) { return this.post<{ machine: SpaceRecord }>('ai.languid.machine.create', input) } /** Change some of a Machine's fields; `model: null` or `permissions: null` clears them. */ updateMachine(rkey: string, input: Record) { return this.post<{ machine: SpaceRecord }>('ai.languid.machine.update', { rkey, ...input }) } deleteMachine(rkey: string) { return this.post('ai.languid.machine.delete', { rkey }) } /** This agent's error reports, and whether they're shared (src/telemetry.ts). */ telemetryStatus() { return this.get('ai.languid.telemetry.getStatus') } /** Record a client-side error (a CLI crash) for this agent. */ reportError(error: { name: string; message: string; stack?: string; method?: string; version?: string; platform?: string }) { return this.post<{ rkey?: string; decided: boolean; shared: boolean; recipient: string }>('ai.languid.telemetry.report', { error }) } setErrorSharing(share: boolean) { return this.post<{ sharing: Sharing }>('ai.languid.telemetry.setSharing', { share }) } /** Private maintainer triage. Never sends a reply or changes the original report. */ triageFeedback(input: { feedback: string; status: 'open' | 'resolved'; note?: string; fix?: string }) { return this.post<{ triage: import('./feedback-triage.ts').FeedbackTriage }>('ai.languid.telemetry.triageFeedback', input) } /** Save the agent's feedback in its error-reports space (the feedback tool, run outside the service). */ sendFeedback(feedback: { kind?: unknown; text?: unknown; provider?: string; model?: string }) { return this.post<{ saved: boolean; shared: boolean; recipient: string }>('ai.languid.telemetry.sendFeedback', feedback) } /** What agents shared with the maintainer, as text. The installation owner only. */ feedbackInbox(opts: { kind?: string; limit?: number; status?: string; open?: boolean } = {}) { return xrpc<{ text: string }>(this.url, 'ai.languid.telemetry.feedbackInbox', { params: { ...opts, open: opts.open ? 'true' : undefined }, headers: this.headers }) } /** * Shared feedback as items: each one's agent, rkey, private triage, and replyStatus (the latest * reply's status, or 'open' until there is one). The installation owner only. */ feedbackItems(opts: { kind?: string; open?: boolean; status?: string; limit?: number } = {}) { const params: Record = { format: 'json', ...(opts.kind ? { kind: opts.kind } : {}), ...(opts.open ? { open: 'true' } : {}), ...(opts.status ? { status: opts.status } : {}), ...(opts.limit ? { limit: opts.limit } : {}) } return xrpc<{ items: (FeedbackItem & { uri: string; cid: string; agent: string; handle: string; replyStatus: string; triage?: import('./feedback-triage.ts').FeedbackTriage })[] }>(this.url, 'ai.languid.telemetry.feedbackInbox', { params, headers: this.headers }) } /** Answer one agent's feedback; the agent is told on its next turn. The installation owner only. */ replyFeedback(reply: { agent: string; rkey: string; status: ReplyStatus; text: string; version?: string }) { return xrpc<{ rkey: string; reply: FeedbackReply }>(this.url, 'ai.languid.telemetry.replyFeedback', { body: reply, headers: this.headers }) } /** The maintainer's replies this agent hasn't been told of yet, as notes; marked told (a local run's next turn). */ takeFeedbackReplies() { return this.post<{ notes: string[] }>('ai.languid.telemetry.takeReplies') } clearErrors() { return this.post<{ deleted: number }>('ai.languid.telemetry.clear') } /** Error reports other owners shared with the signed-in account. */ listSharedErrors(limit = 100) { return xrpc<{ agents: { agent: string; handle: string; reports: (ErrorReport & { rkey: string })[]; feedback?: (FeedbackItem & { uri: string; cid: string })[] }[] }>(this.url, 'ai.languid.telemetry.listShared', { params: { limit }, headers: this.headers }) } /** A client for the service configured in local state (`languid serve` writes it). */ static fromState(state: State, agent: string) { const url = process.env.LANGUID_SERVER ?? state.server?.url const token = process.env.LANGUID_SERVER_TOKEN ?? state.server?.token if (!url || !token) throw new Error('no languid service configured; start one with: languid serve') return new LanguidClient(url, token, agent) } private get(nsid: string, params: Record = {}) { return xrpc(this.url, nsid, { params: { agent: this.agent, ...params }, headers: this.headers }) } private post(nsid: string, body: Record = {}) { return xrpc(this.url, nsid, { body: { agent: this.agent, ...body }, headers: this.headers }) } describe() { return this.get('ai.languid.agent.describe') } /** Create an agent for the signed-in owner. Its space is created under the owner's own DID. */ createAgent(name: string, model?: { provider: string; model: string }) { return xrpc<{ name: string; did: string; handle: string; space: string }>(this.url, 'ai.languid.agent.create', { body: { name, model }, headers: this.headers }) } /** Models the service can call for its agents. */ async listModels() { return (await this.get<{ models: ServiceModel[] }>('ai.languid.model.list')).models } /** * One model call, made by the service: it compiles the context from the agent's records and calls * the agent's configured model with its own credentials. Returns pi-ai's event stream, so it can be a * pi provider's streamSimple. `model` only labels errors; the service decides which model answers. */ streamModel(model: Model, thread: string, opts: Session & { reasoning?: string; identity?: ClientIdentity; signal?: AbortSignal } = {}): AssistantMessageEventStream { const stream = createAssistantMessageEventStream() const fail = (message: string, reason: 'error' | 'aborted' = 'error') => { const error: AssistantMessage = { role: 'assistant', content: [], api: model.api, provider: model.provider, model: model.id, usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }, stopReason: reason, errorMessage: message, timestamp: Date.now(), } stream.push({ type: 'error', reason, error }) } ;(async () => { let res: Response try { res = await fetch(new URL('/xrpc/ai.languid.model.stream', this.url), { method: 'POST', headers: { ...this.headers, 'content-type': 'application/json' }, body: JSON.stringify({ agent: this.agent, thread, computer: opts.computer, cwd: opts.cwd, reasoning: opts.reasoning, identity: opts.identity }), signal: opts.signal, }) } catch (e: any) { return fail(opts.signal?.aborted ? 'aborted' : `languid service unreachable: ${e.message}`, opts.signal?.aborted ? 'aborted' : 'error') } if (!res.ok || !res.body) { const body: any = await res.json().catch(() => ({})) return fail(`languid service: ${body.error ?? res.status}${body.message ? `: ${body.message}` : ''}`) } let partial: AssistantMessage | undefined let buffer = '' let ended = false const handle = (line: string) => { if (!line.trim()) return const event = JSON.parse(line) as AssistantMessageEvent if ('partial' in event && event.partial) partial = event.partial else if (partial && (event.type === 'text_delta' || event.type === 'thinking_delta')) { const block: any = partial.content[event.contentIndex] if (block?.type === 'text' && event.type === 'text_delta') block.text += event.delta if (block?.type === 'thinking' && event.type === 'thinking_delta') block.thinking += event.delta ;(event as any).partial = partial } if (event.type === 'done' || event.type === 'error') ended = true stream.push(event) } try { const decoder = new TextDecoder() for await (const chunk of res.body as any) { buffer += decoder.decode(chunk, { stream: true }) let nl while ((nl = buffer.indexOf('\n')) >= 0) { handle(buffer.slice(0, nl)) buffer = buffer.slice(nl + 1) } } handle(buffer) if (!ended) fail('languid service closed the stream early') } catch (e: any) { if (!ended) fail(opts.signal?.aborted ? 'aborted' : `languid stream failed: ${e.message}`, opts.signal?.aborted ? 'aborted' : 'error') } })() return stream } async getContext(thread: string, session: Session = {}) { return (await this.get<{ messages: (SystemMessage | Message)[] }>('ai.languid.agent.getContext', { thread, ...session })).messages } /** The agent's threads, most recently active first. */ async listThreads() { return (await this.get<{ threads: ThreadInfo[] }>('ai.languid.thread.list', {})).threads } async createThread(title?: string) { return (await this.post<{ thread: string }>('ai.languid.thread.create', { title })).thread } /** Retitle a thread. The rkey, its messages and its createdAt are unchanged. */ async renameThread(thread: string, title: string) { return this.post<{ thread: string; title: string }>('ai.languid.thread.rename', { thread, title }) } async recordMessage(thread: string, message: UserMessage | AssistantMessage | ToolResultMessage, session: Session = {}) { return this.post<{ calls?: RecordedCall[] }>('ai.languid.message.record', { thread, message, via: this.via, ...session }) } executeTool(callId: string, tool: string, args: unknown, approved = false) { return this.post<{ output: string; isError: boolean; computer?: string; content?: ToolContent[]; details?: unknown }>('ai.languid.tool.execute', { callId, tool, args, approved, }) } /** * Send a message and have the service answer it: a new run, or the thread's running run when it * has one (accepted: "queued"; follow that run's events from `since`). With a clientMessageId, * sending the same message again returns the first one (accepted: "duplicate"). Poll getRun. */ run(prompt: string, opts: Session & { thread?: string; continue?: boolean; approveWrites?: boolean; approval?: 'ask' | 'allow' | 'auto' | 'deny'; clientMessageId?: string; images?: { data: string; mimeType: string }[] } = {}) { return this.post('ai.languid.agent.run', { prompt, via: this.via, ...opts }) } /** Calls waiting for the owner's yes (runs started with approval: "ask"), optionally in one thread. */ async listApprovals(thread?: string) { return (await this.get<{ approvals: ApprovalRequestView[] }>('ai.languid.approval.list', thread ? { thread } : {})).approvals } /** Answer one: records the owner's ai.languid.tool.approval and wakes the run. `always` also saves its always-allow rule. */ answerApproval(request: string, approved: boolean, opts: { always?: boolean; via?: string } = {}) { return this.post<{ rule?: { computer: string; tool: string; command?: string } }>('ai.languid.approval.answer', { request, approved, ...opts }) } /** The agent's always-allow rules: which tools run on which of its computers without asking. */ async listPermissions() { return (await this.get<{ rules: PermissionRule[] }>('ai.languid.computer.listPermissions')).rules } /** Always allow a tool on one of the agent's computers (saved in its space). */ async allowTool(computer: string, tool: string) { return (await this.post<{ rules: PermissionRule[] }>('ai.languid.computer.allowTool', { computer, tool })).rules } /** Ask before a tool on a computer again; without a tool, before every tool there. */ async revokeTool(computer: string, tool?: string) { return (await this.post<{ rules: PermissionRule[] }>('ai.languid.computer.revokeTool', { computer, tool })).rules } /** Every permission the owner set for the agent: each computer's rules, and its script rules. */ getPermissions() { return this.get('ai.languid.agent.getPermissions') } /** Replace one computer's rules (all lists empty: back to asking before everything). */ async setComputerRules(computer: string, rules: ComputerRules) { return (await this.post<{ computer: string; rules: ComputerRules }>('ai.languid.computer.setRules', { computer, rules })).rules } /** Replace the agent's script rules; null goes back to the default. */ setPolicy(policy: Policy | null) { return this.post<{ policy: Policy; defaultPolicy: boolean }>('ai.languid.agent.setPolicy', { policy }) } getRun(run: string, since = 0) { return this.get('ai.languid.agent.getRun', { run, since }) } /** Start a run and wait for it, calling onEvent for each event as it arrives. */ async runToCompletion(prompt: string, opts: Parameters[1] & { onEvent?: (e: RunEvent) => void; pollMs?: number } = {}) { const { onEvent, pollMs = 500, ...runOpts } = opts const { run, thread, since: from } = await this.run(prompt, runOpts) let since = from ?? 0 if (!run) throw new Error('that message was already sent (same clientMessageId), and no run is going on its thread') for (;;) { const st = await this.getRun(run, since) for (const e of st.events) onEvent?.(e) since = st.next if (st.status !== 'running') return { ...st, thread } await new Promise((r) => setTimeout(r, pollMs)) } } /** Summarize the thread's older messages now. `force: false` compacts only if it's over the threshold. */ compact(thread: string, opts: { instructions?: string; force?: boolean; trigger?: 'manual' | 'threshold' | 'overflow'; contextWindow?: number } = {}) { return this.post<{ compacted: boolean; reason?: string; summary?: string; tokensBefore?: number; tokensAfter?: number }>( 'ai.languid.thread.compact', { thread, ...opts }, ) } // ---- computers (owner-wide, not per agent) ---- /** A one-time join code for a new computer; no agents means all of them. */ /** A one-time sign-up link for a new owner (installation owner only). */ inviteOwner(opts: { ttlDays?: number; budgetUsd?: number; model?: { provider: string; model: string }; uses?: number }) { return xrpc<{ code: string; url?: string; expiresAt: string; budgetUsd?: number; model?: { provider: string; model: string }; uses?: number }>( this.url, 'ai.languid.admin.inviteOwner', { body: opts, headers: this.headers }, ) } /** Invited owners, what they've spent, and how many invites are still open (installation owner only). */ listOwners() { return xrpc<{ owners: OwnerSummary[]; openInvites: number }>(this.url, 'ai.languid.admin.listOwners', { headers: this.headers }) } /** Set (or with undefined, remove) an invited owner's model budget, in US dollars (installation owner only). */ setBudget(owner: string, budgetUsd: number | undefined) { return xrpc(this.url, 'ai.languid.admin.setBudget', { body: { owner, budgetUsd }, headers: this.headers }) } inviteComputer(agents?: string[], ttlMinutes?: number) { return this.post<{ code: string; expiresAt: string; agents: string[]; url?: string }>('ai.languid.computer.invite', { agents, ttlMinutes }) } async listComputers() { return (await this.get<{ computers: ComputerStatus[] }>('ai.languid.computer.list')).computers } attachComputer(name: string, agents: string[]) { return this.post<{ name: string; agents: string[]; attachedTo: number }>('ai.languid.computer.attach', { name, agents }) } removeComputer(name: string) { return this.post<{ removedFrom: number; hadRunner: boolean }>('ai.languid.computer.remove', { name }) } setModel(provider: string, model: string) { return this.post('ai.languid.agent.setModel', { provider, model }) } }