@ai-sdk-letta/server 0.1.0

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@ai-sdk-letta/server",
+  "version": "0.1.0",
+  "description": "Local HTTP runtime for ai-sdk-letta agents: durable threads and runs, NDJSON events, a token API and a loopback browser app.",
+  "license": "Apache-2.0",
+  "author": "Leonard Schneider",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonardschneider/ai-sdk-letta.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/leonardschneider/ai-sdk-letta/tree/main/packages/server#readme",
+  "bugs": {
+    "url": "https://github.com/leonardschneider/ai-sdk-letta/issues"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "letta",
+    "agent",
+    "server",
+    "ndjson",
+    "express"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "ai-sdk-letta-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p .",
+    "test": "node --conditions=ai-sdk-letta-source --import tsx --test test/*.test.ts",
+    "prepack": "node ../../scripts/check-dist.mjs"
+  },
+  "dependencies": {
+    "@types/express": "^5.0.6",
+    "ai-sdk-letta": "^0.1.0",
+    "express": "^5.2.1"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.118"
+  },
+  "devDependencies": {
+    "@letta-ai/letta-agent-sdk": "0.8.22",
+    "ai": "7.0.118"
+  }
+}

package/src/http.ts

@@ -0,0 +1,108 @@
+import express from 'express';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { IMAGE_LIMITS, IMAGE_MEDIA_TYPES } from 'ai-sdk-letta';
+import type { RuntimeEvent, ThreadRuntime } from './runtime.js';
+import { RuntimeFault } from './runtime.js';
+
+/**
+ * Server-to-server API: bearer token (256-bit hex) plus an owner header, on
+ * 127.0.0.1 only. Browser origins and cross-site requests are never accepted.
+ */
+export function tokenApiApp(runtime: ThreadRuntime, token: string, owner: string, port: number, shutdown?: () => Promise<void>) {
+  if (!/^[a-f0-9]{64}$/.test(token)) throw new Error('A private 256-bit token is required');
+  const app = express(); app.disable('x-powered-by');
+  app.use((req, res, next) => {
+    res.set({ 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
+    const supplied = req.headers.authorization?.replace(/^Bearer /, '');
+    if (req.headers.host !== `127.0.0.1:${port || req.socket.localPort}` || req.headers.origin || req.headers['sec-fetch-site'] === 'cross-site' || !supplied || !/^[a-f0-9]{64}$/.test(supplied) || !timingSafeEqual(Buffer.from(supplied), Buffer.from(token))) return res.status(401).json({ error: 'unauthorized' });
+    if (req.headers['x-runtime-owner'] !== owner) return res.status(403).json({ error: 'forbidden' });
+    next();
+  });
+  return runtimeRoutes(app, runtime, owner, shutdown);
+}
+
+/** JSON body limit for every route except `POST /v1/runs`. */
+export const BODY_LIMIT_BYTES = 24 * 1024;
+/**
+ * JSON body limit for `POST /v1/runs` only: base64 of the largest allowed
+ * image payload plus room for text and JSON. Still bounded; image limits are
+ * enforced again on the decoded bytes.
+ */
+export const RUN_BODY_LIMIT_BYTES = Math.ceil(IMAGE_LIMITS.maxTotalBytes / 3) * 4 + 64 * 1024;
+
+/** Shared routes; the caller must install its transport-specific authentication first. */
+export function runtimeRoutes(app: express.Express, runtime: ThreadRuntime, owner: string, shutdown?: () => Promise<void>) {
+  const small = express.json({ limit: BODY_LIMIT_BYTES });
+  const runs = express.json({ limit: RUN_BODY_LIMIT_BYTES });
+  app.use((req, res, next) => (req.method === 'POST' && req.path === '/v1/runs' ? runs : small)(req, res, next));
+  app.get('/v1/capabilities', (_req, res) => res.json({ version: 1, stateful: true, tools: 'observed-only', interactions: ['approval', 'question'], history: true, replay: true, concurrency: 1, edits: false,
+    images: { mediaTypes: [...IMAGE_MEDIA_TYPES], maxImageBytes: IMAGE_LIMITS.maxImageBytes, maxImages: IMAGE_LIMITS.maxImages, maxTotalBytes: IMAGE_LIMITS.maxTotalBytes } }));
+  app.get('/v1/threads', (_req, res) => res.json(runtime.list(owner)));
+  app.post('/v1/threads', async (req, res) => res.status(201).json(await runtime.create(owner, req.body?.id, req.body?.title)));
+  app.patch('/v1/threads/:id', (req, res) => res.json(runtime.updateMetadata(owner, req.params.id, req.body)));
+  app.get('/v1/threads/:id/history', async (req, res) => res.json(await runtime.history(owner, req.params.id)));
+  app.get('/v1/threads/:id/view', async (req, res) => res.json(await runtime.view(owner, req.params.id)));
+  app.post('/v1/runs', async (req, res) => res.status(202).json(await runtime.start(owner, req.body)));
+  app.post('/v1/runs/:id/answer', (req, res) => { runtime.answer(owner, req.params.id, req.body); res.json({ accepted: true }); });
+  app.post('/v1/runs/:id/cancel', (req, res) => { runtime.cancel(owner, req.params.id); res.json({ accepted: true }); });
+  app.get('/v1/runs/:id/events', (req, res) => {
+    const snapshot = runtime.events(owner, req.params.id, Number(req.query.after ?? 0));
+    res.set({ 'Content-Type': 'application/x-ndjson', 'X-Accel-Buffering': 'no' }); res.flushHeaders();
+    const write = (event: RuntimeEvent) => { if (!res.destroyed) res.write(`${JSON.stringify(event)}\n`); if (event.type === 'completed' || event.type === 'failed') res.end(); };
+    for (const event of snapshot.events) write(event);
+    if (snapshot.status !== 'running') { res.end(); return; }
+    const unsubscribe = runtime.subscribe(req.params.id, write);
+    const heartbeat = setInterval(() => { if (!res.destroyed) res.write('\n'); }, 15_000);
+    res.on('close', () => { clearInterval(heartbeat); unsubscribe(); });
+  });
+  if (shutdown) app.post('/v1/shutdown', async (_req, res) => { await shutdown(); res.json({ stopped: true }); });
+  app.use((_req, res) => res.status(404).json({ error: 'not_found' }));
+  app.use((error: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+    if (res.headersSent) return res.end();
+    // Body parser rejections: fixed codes, never parser messages.
+    if ((error as { type?: unknown } | undefined)?.type === 'entity.too.large') return res.status(413).json({ error: 'payload_too_large' });
+    res.status(error instanceof RuntimeFault ? error.status : error instanceof SyntaxError ? 400 : 503).json({ error: error instanceof RuntimeFault ? error.code : 'runtime_unavailable' });
+  });
+  return app;
+}
+
+/** What the browser may know about the agent. */
+export interface GuiAgentInfo {
+  id: string;
+  name: string;
+  /** Tools whose calls always ask for approval (used for display only). */
+  approvalTools?: readonly string[];
+}
+
+/**
+ * Loopback-only, same-origin browser transport. No bearer token enters the
+ * browser: a random HttpOnly SameSite=Strict session cookie authenticates
+ * reads, and every mutation also needs the exact Origin and an in-memory CSRF
+ * token. Requests with a foreign Host, Origin or cross-site fetch metadata are
+ * rejected. Static assets are served with a strict CSP.
+ */
+export function guiApp(runtime: ThreadRuntime, owner: string, port: number, assets: string, agent: GuiAgentInfo) {
+  const app = express();
+  const session = randomBytes(32).toString('hex');
+  const csrf = randomBytes(32).toString('hex');
+  app.disable('x-powered-by');
+  app.use((req, res, next) => {
+    const host = `127.0.0.1:${port || req.socket.localPort}`;
+    res.set({ 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer',
+      'Content-Security-Policy': "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'" });
+    if (req.headers.host !== host || (req.headers.origin && req.headers.origin !== `http://${host}`) || (req.headers['sec-fetch-site'] && !['same-origin', 'none'].includes(String(req.headers['sec-fetch-site'])))) return res.status(403).json({ error: 'invalid_origin' });
+    next();
+  });
+  app.get('/api/session', (_req, res) => {
+    res.cookie('ai_sdk_letta_session', session, { httpOnly: true, sameSite: 'strict', path: '/' });
+    res.json({ csrf, agent: { id: agent.id, name: agent.name, approvalTools: [...(agent.approvalTools ?? [])] } });
+  });
+  app.use('/api', (req, res, next) => {
+    const cookie = req.headers.cookie?.split(';').map(s => s.trim()).find(s => s.startsWith('ai_sdk_letta_session='))?.slice('ai_sdk_letta_session='.length);
+    if (!cookie || !/^[a-f0-9]{64}$/.test(cookie) || !timingSafeEqual(Buffer.from(cookie), Buffer.from(session))) return res.status(401).json({ error: 'session_required' });
+    if (!['GET', 'HEAD'].includes(req.method) && (req.headers.origin !== `http://127.0.0.1:${port || req.socket.localPort}` || req.headers['x-csrf-token'] !== csrf)) return res.status(403).json({ error: 'csrf_required' });
+    next();
+  }, runtimeRoutes(express(), runtime, owner));
+  app.use(express.static(assets, { index: 'index.html', dotfiles: 'deny' }));
+  return app;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Local HTTP runtime for ai-sdk-letta agents: a durable thread/run service,
+ * a token-authenticated server-to-server API, and a loopback browser app.
+ *
+ * @packageDocumentation
+ */
+export { ThreadRuntime, RuntimeFault, displayRun, toolFailureReason, type RuntimeEvent, type Run, type RunImage, type RunInput, type RuntimeHost, type RuntimeSession } from './runtime.js';
+export { guiApp, tokenApiApp, runtimeRoutes, BODY_LIMIT_BYTES, RUN_BODY_LIMIT_BYTES, type GuiAgentInfo } from './http.js';
+export { startGuiServer, startApiServer, closeOnSignals, DEFAULT_PORT, type ServeOptions, type RunningServer } from './serve.js';

package/src/runtime.ts

@@ -0,0 +1,341 @@
+import { readFileSync, writeFileSync, renameSync, existsSync, openSync, closeSync, fsyncSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { UIMessage, UserContent } from 'ai';
+import { IMAGE_PLACEHOLDER, ImageInputError, MAX_INPUT_CHARACTERS, validateImages, validateResponse, type DecodedImage, type InteractionRequest, type InteractionResponse, type LettaAgent } from 'ai-sdk-letta';
+
+/** One NDJSON event of a run. The application, never the HTTP consumer, owns tools. */
+export type RuntimeEvent = { sequence: number; type: string; data: Record<string, unknown> };
+// createdAt/lastActivityAt are optional: threads recorded before they existed stay valid.
+type Thread = { id: string; owner: string; conversationId?: string; agentId?: string; title: string; archived: boolean; state: 'creating' | 'ready'; createdAt?: string; lastActivityAt?: string };
+/** Metadata of an image sent with a run. The bytes live only in Letta history, never in runtime state. */
+export type RunImage = { mediaType: string; bytes: number; sha256: string };
+/** A single user turn and the events observed while it ran. */
+export type Run = { id: string; threadId: string; input: string; images?: RunImage[]; parentRunId: string | null; status: 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted'; events: RuntimeEvent[]; startedAt?: string };
+/** Input of `POST /v1/runs`. `images` carry base64 data (no data: prefix) and are validated against `IMAGE_LIMITS`. */
+export type RunInput = { id: string; threadId: string; text: string; parentRunId: string | null; images?: { mediaType: string; data: string }[] };
+type State = { version: 1; threads: Thread[]; runs: Run[] };
+/** An opened agent conversation as seen by the runtime. */
+export interface RuntimeSession {
+  agentId: string;
+  conversationId: string;
+  history: UIMessage[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  agent: Pick<LettaAgent<any>, 'stream' | 'interactions' | 'transcript'>;
+}
+/** Opens and closes the single agent session the runtime drives. */
+export interface RuntimeHost {
+  open(options: { conversationId: string } | { newTitle: string }): Promise<RuntimeSession>;
+  close(): Promise<void>;
+}
+/** A client-visible failure with a fixed code and HTTP status. */
+export class RuntimeFault extends Error {
+  constructor(readonly code: string, readonly status = 409) { super(code); }
+}
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+/** Only app-defined, fixed failure codes (e.g. user_denied) are surfaced; never free-form error text. */
+const failureReasons = new Set(['user_denied', 'approval_cancelled', 'tool_denied', 'tool_cancelled', 'tool_timeout', 'tool_failed', 'invalid_arguments', 'interaction_unavailable', 'permission_denied', 'duplicate_or_limit', 'tool_output_limit']);
+export function toolFailureReason(error: unknown): { reason?: string } {
+  let value = error;
+  if (typeof value === 'string') { try { value = JSON.parse(value); } catch { return {}; } }
+  const reason = value && typeof value === 'object' && !Array.isArray(value) ? (value as { error?: unknown }).error : undefined;
+  return typeof reason === 'string' && failureReasons.has(reason) ? { reason } : {};
+}
+
+/** Transport observations for reconnects/failed-turn inspection only, never agent input. */
+export function displayRun(run: Run): UIMessage[] {
+  const parts: UIMessage['parts'] = [];
+  for (const event of run.events) {
+    const data = event.data;
+    if (event.type === 'text') {
+      const last = parts.at(-1);
+      if (last?.type === 'text') last.text += String(data.text);
+      else parts.push({ type: 'text', text: String(data.text) });
+    } else if (event.type === 'tool_started') parts.push({ type: 'dynamic-tool', toolName: String(data.name), toolCallId: String(data.toolCallId), state: 'input-available', input: data.input });
+    else if (event.type === 'tool_completed' || event.type === 'tool_failed') {
+      const index = parts.findIndex(p => p.type === 'dynamic-tool' && p.toolCallId === data.toolCallId);
+      const part = parts[index];
+      if (part?.type === 'dynamic-tool' && part.state === 'input-available') parts[index] = event.type === 'tool_completed'
+        ? { ...part, state: 'output-available', output: data.output }
+        : { ...part, state: 'output-error', errorText: typeof data.reason === 'string' ? JSON.stringify({ error: data.reason }) : String(data.code) };
+    }
+  }
+  if (run.status !== 'completed' && run.status !== 'running') for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (part.type === 'dynamic-tool' && part.state === 'input-available') parts[i] = { ...part, state: 'output-error', errorText: `Turn ${run.status}; execution not confirmed.` };
+  }
+  const metadata = run.startedAt ? { metadata: { createdAt: run.startedAt } } : {};
+  // Runtime state never stores image bytes; failed/reconnecting runs show a placeholder.
+  const user: UIMessage['parts'] = [...(run.input.trim() ? [{ type: 'text' as const, text: run.input }] : []), ...(run.images ?? []).map(() => ({ type: 'text' as const, text: IMAGE_PLACEHOLDER }))];
+  return [{ id: `${run.id}-user`, role: 'user', parts: user, ...metadata }, { id: `${run.id}-assistant`, role: 'assistant', parts }];
+}
+
+const sameImages = (a: RunImage[] = [], b: RunImage[] = []) => a.length === b.length && a.every((image, index) => image.sha256 === b[index]!.sha256);
+
+/**
+ * Single-owner, single-turn thread service over one agent.
+ *
+ * Runs are recorded durably before delivery; a run that was in flight when the
+ * process stopped is marked `interrupted` and blocks further turns on that
+ * thread (uncertain delivery is never replayed). Human answers are validated
+ * and accepted exactly once.
+ */
+export class ThreadRuntime {
+  private state: State;
+  private locked = false;
+  private current?: RuntimeSession;
+  private active?: { run: Run; control: AbortController };
+  private pending?: { runId: string; request: InteractionRequest; resolve(value: InteractionResponse): void };
+  private listeners = new Map<string, Set<(event: RuntimeEvent) => void>>();
+  constructor(private readonly host: RuntimeHost, private readonly filename: string, private readonly owner: string, private readonly deadlineMs = 180_000, private readonly humanWaitMs = 4 * 60_000) {
+    this.state = existsSync(filename) ? JSON.parse(readFileSync(filename, 'utf8')) as State : { version: 1, threads: [], runs: [] };
+    if (this.state.version !== 1 || !Array.isArray(this.state.threads) || !Array.isArray(this.state.runs)) throw new Error('Invalid runtime state');
+    for (const thread of this.state.threads) thread.archived ??= false;
+    for (const run of this.state.runs) if (run.status === 'running') {
+      run.status = 'interrupted';
+      run.events.push({ sequence: run.events.length + 1, type: 'failed', data: { code: 'delivery_uncertain' } });
+    }
+    this.save();
+  }
+  private save() {
+    // A leftover temporary file is an uncertain write, not permission to overwrite it.
+    const fd = openSync(`${this.filename}.tmp`, 'wx', 0o600);
+    try { writeFileSync(fd, JSON.stringify(this.state)); fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(`${this.filename}.tmp`, this.filename);
+    const directory = openSync(dirname(this.filename), 'r');
+    try { fsyncSync(directory); } finally { closeSync(directory); }
+  }
+  private authorize(owner: string) { if (owner !== this.owner) throw new RuntimeFault('forbidden', 403); }
+  private thread(owner: string, id: string) {
+    this.authorize(owner);
+    const thread = this.state.threads.find(t => t.id === id && t.owner === owner);
+    if (!thread) throw new RuntimeFault('not_found', 404);
+    if (thread.state !== 'ready') throw new RuntimeFault('creation_uncertain');
+    return thread;
+  }
+  private run(owner: string, id: string) {
+    this.authorize(owner);
+    const run = this.state.runs.find(r => r.id === id);
+    if (!run) throw new RuntimeFault('not_found', 404);
+    this.thread(owner, run.threadId);
+    return run;
+  }
+  private async exclusive<T>(fn: () => Promise<T>) {
+    if (this.locked || this.active) throw new RuntimeFault('runtime_busy');
+    this.locked = true;
+    try { return await fn(); } finally { this.locked = false; }
+  }
+  private async open(thread: Thread) {
+    if (this.current && this.current.conversationId === thread.conversationId) return this.current;
+    await this.host.close(); this.current = undefined;
+    const session = await this.host.open(thread.conversationId ? { conversationId: thread.conversationId } : { newTitle: thread.title });
+    const identity = this.state.threads.find(t => t.agentId)?.agentId;
+    if (identity && session.agentId !== identity) { await this.host.close(); throw new RuntimeFault('identity_mismatch'); }
+    this.current = session;
+    return session;
+  }
+  /** Display metadata only; timestamps are omitted for legacy threads that never recorded them. */
+  private summary({ id, title, state, archived, createdAt, lastActivityAt }: Thread) {
+    return { id, title, state, archived, ...(createdAt ? { createdAt } : {}), ...(lastActivityAt ? { lastActivityAt } : {}) };
+  }
+  list(owner: string) {
+    this.authorize(owner);
+    return this.state.threads.filter(t => t.owner === owner).map(t => this.summary(t));
+  }
+  /** Local display metadata only: never opens a session or edits backend history. */
+  updateMetadata(owner: string, id: string, input: unknown) {
+    const thread = this.thread(owner, id);
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new RuntimeFault('invalid_input', 400);
+    const fields = Object.keys(input);
+    if (!fields.length || fields.some(key => key !== 'title' && key !== 'archived')) throw new RuntimeFault('invalid_input', 400);
+    const patch = input as { title?: unknown; archived?: unknown };
+    let title = thread.title;
+    if (fields.includes('title')) {
+      // Reject terminal controls and invisible formatting/bidi controls before trimming.
+      if (typeof patch.title !== 'string' || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(patch.title)) throw new RuntimeFault('invalid_input', 400);
+      title = patch.title.trim();
+      if (!title || title.length > 120) throw new RuntimeFault('invalid_input', 400);
+    }
+    if (fields.includes('archived') && typeof patch.archived !== 'boolean') throw new RuntimeFault('invalid_input', 400);
+    // locked covers session opening before start() has installed its active run.
+    if (patch.archived === true && (this.locked || this.active?.run.threadId === id)) throw new RuntimeFault('runtime_busy');
+    thread.title = title;
+    if (typeof patch.archived === 'boolean') thread.archived = patch.archived;
+    this.save();
+    return this.summary(thread);
+  }
+  async create(owner: string, id: string, title: string) {
+    this.authorize(owner);
+    if (!uuid.test(id) || typeof title !== 'string' || !title.trim() || title.length > 120) throw new RuntimeFault('invalid_input', 400);
+    const previous = this.state.threads.find(t => t.id === id);
+    if (previous) {
+      if (previous.owner !== owner || previous.title !== title) throw new RuntimeFault('id_conflict');
+      this.thread(owner, id); return { id, title };
+    }
+    if (this.state.threads.length >= 200) throw new RuntimeFault('capacity_reached');
+    return this.exclusive(async () => {
+      const now = new Date().toISOString();
+      const thread: Thread = { id, owner, title, archived: false, state: 'creating', createdAt: now, lastActivityAt: now };
+      this.state.threads.push(thread); this.save();
+      const session = await this.open(thread);
+      thread.agentId = session.agentId; thread.conversationId = session.conversationId; thread.state = 'ready'; this.save();
+      return { id, title };
+    });
+  }
+  async history(owner: string, id: string) {
+    const thread = this.thread(owner, id);
+    return this.exclusive(async () => {
+      // Refresh through backend history, not a display transcript replay into the agent.
+      await this.host.close(); this.current = undefined;
+      const session = await this.open(thread);
+      return { messages: session.history.filter(m => m.id !== 'session-status'), lastRunId: this.state.runs.filter(r => r.threadId === id).at(-1)?.id ?? null };
+    });
+  }
+  async view(owner: string, id: string) {
+    this.thread(owner, id);
+    const latest = this.state.runs.filter(r => r.threadId === id).at(-1);
+    if (this.active?.run.threadId === id && this.current) return {
+      messages: this.current.history.filter(m => m.id !== 'session-status'),
+      lastRunId: latest?.id ?? null,
+      live: { id: this.active.run.id, input: this.active.run.input, ...(this.active.run.images?.length ? { images: this.active.run.images.length } : {}) },
+      status: 'running',
+    };
+    if (latest && !['running', 'completed'].includes(latest.status)) return {
+      messages: this.state.runs.filter(r => r.threadId === id).flatMap(displayRun),
+      lastRunId: latest.id, live: null, status: latest.status, source: 'transport-observations',
+    };
+    return { ...await this.history(owner, id), live: null, status: latest?.status ?? null, source: 'backend-history' };
+  }
+  private emit(run: Run, type: string, data: Record<string, unknown>) {
+    const event = { sequence: run.events.length + 1, type, data };
+    run.events.push(event); this.save();
+    for (const listener of this.listeners.get(run.id) ?? []) listener(event);
+  }
+  /**
+   * Start one turn. Text, images or both; images are validated (type by
+   * content, size, count, total) and fail with a fixed `image_*` code.
+   * Only image metadata (type, size, SHA-256) is recorded in runtime state.
+   */
+  async start(owner: string, input: RunInput) {
+    this.authorize(owner);
+    if (!input || typeof input !== 'object' || !uuid.test(input.id) || typeof input.text !== 'string' || input.text.length > MAX_INPUT_CHARACTERS || (input.parentRunId !== null && !uuid.test(input.parentRunId)) || (input.images !== undefined && !Array.isArray(input.images))) throw new RuntimeFault('invalid_input', 400);
+    let images: DecodedImage[] = [];
+    try { images = validateImages(input.images ?? []); }
+    catch (error) { throw error instanceof ImageInputError ? new RuntimeFault(error.code, error.code === 'image_too_large' || error.code === 'images_too_large' ? 413 : 400) : error; }
+    if (!input.text.trim() && !images.length) throw new RuntimeFault('invalid_input', 400);
+    const imageMetadata: RunImage[] = images.map(({ mediaType, bytes, sha256 }) => ({ mediaType, bytes, sha256 }));
+    const thread = this.thread(owner, input.threadId);
+    const previous = this.state.runs.find(r => r.id === input.id);
+    if (previous) {
+      if (previous.threadId !== input.threadId || previous.input !== input.text || !sameImages(previous.images, imageMetadata) || previous.parentRunId !== input.parentRunId) throw new RuntimeFault('id_conflict');
+      return { id: previous.id, status: previous.status };
+    }
+    if (thread.archived) throw new RuntimeFault('thread_archived');
+    const latest = this.state.runs.filter(r => r.threadId === thread.id).at(-1);
+    if (input.parentRunId !== (latest?.id ?? null)) throw new RuntimeFault('history_conflict');
+    if (latest && latest.status !== 'completed') throw new RuntimeFault('delivery_uncertain');
+    if (this.state.runs.length >= 200) throw new RuntimeFault('capacity_reached');
+    return this.exclusive(async () => {
+      const session = await this.open(thread);
+      const startedAt = new Date().toISOString();
+      const run: Run = { id: input.id, threadId: input.threadId, input: input.text, ...(imageMetadata.length ? { images: imageMetadata } : {}), parentRunId: input.parentRunId, status: 'running', events: [], startedAt };
+      thread.lastActivityAt = startedAt;
+      this.state.runs.push(run); this.save();
+      const control = new AbortController(); this.active = { run, control };
+      // Exactly the new turn: text (if any) followed by the images, in the order given.
+      const content: UserContent = images.length
+        ? [...(input.text.trim() ? [{ type: 'text' as const, text: input.text }] : []), ...images.map(image => ({ type: 'image' as const, image: image.base64, mediaType: image.mediaType }))]
+        : input.text;
+      void this.drive(session, run, control, content);
+      return { id: run.id, status: run.status };
+    });
+  }
+  private async drive(session: RuntimeSession, run: Run, control: AbortController, content: UserContent) {
+    let timedOut = false;
+    const expire = () => { timedOut = true; control.abort(); };
+    let remaining = this.deadlineMs;
+    // The installed harness caps external tools at five minutes. Finish human
+    // waits explicitly before that limit, rather than accepting a detached result.
+    let remainingWait = this.humanWaitMs;
+    let resumedAt = Date.now();
+    let timer = setTimeout(expire, remaining);
+    // Human reading time does not consume inference time, but the whole turn
+    // remains bounded even if the browser is abandoned or prompts repeat.
+    const hardTimer = setTimeout(expire, this.deadlineMs + this.humanWaitMs);
+    let disconnect = () => {};
+    try {
+      disconnect = session.agent.interactions.connect((request, signal) => new Promise((resolve, reject) => {
+        clearTimeout(timer);
+        remaining = Math.max(1, remaining - (Date.now() - resumedAt));
+        const waitingAt = Date.now();
+        timer = setTimeout(expire, Math.max(1, remainingWait));
+        const resume = () => {
+          clearTimeout(timer); remainingWait -= Date.now() - waitingAt;
+          resumedAt = Date.now(); timer = setTimeout(expire, remaining);
+        };
+        const abort = () => {
+          if (this.pending?.request.id === request.id) {
+            this.pending = undefined;
+            this.emit(run, 'interaction_ended', { id: request.id, code: timedOut ? 'timed_out' : 'cancelled' });
+            resume();
+          }
+          reject(new RuntimeFault('interaction_cancelled'));
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        this.pending = { runId: run.id, request, resolve: value => {
+          signal.removeEventListener('abort', abort);
+          if (this.pending?.request.id === request.id) this.pending = undefined;
+          resume(); resolve(value);
+        } };
+        if (signal.aborted) { abort(); return; }
+        this.emit(run, 'interaction', request);
+      }));
+      this.emit(run, 'started', { threadId: run.threadId });
+      const result = await session.agent.stream(typeof content === 'string'
+        ? { prompt: content, abortSignal: control.signal }
+        : { messages: [...session.agent.transcript, { role: 'user', content }], abortSignal: control.signal });
+      for await (const part of result.fullStream) {
+        if (part.type === 'text-delta') this.emit(run, 'text', { text: part.text });
+        else if (part.type === 'tool-call') this.emit(run, 'tool_started', { toolCallId: part.toolCallId, name: part.toolName, input: part.input, execution: 'external' });
+        else if (part.type === 'tool-result') this.emit(run, 'tool_completed', { toolCallId: part.toolCallId, name: part.toolName, output: part.output, execution: 'external' });
+        else if (part.type === 'tool-error') this.emit(run, 'tool_failed', { toolCallId: part.toolCallId, name: part.toolName, code: 'tool_failed', ...toolFailureReason(part.error), execution: 'external' });
+        else if (part.type === 'error' || part.type === 'abort') throw new RuntimeFault('runtime_failed');
+      }
+      if (this.pending?.runId === run.id) throw new RuntimeFault('interaction_incomplete');
+      if (control.signal.aborted || await result.finishReason !== 'stop') throw new RuntimeFault('runtime_failed');
+      run.status = 'completed'; this.emit(run, 'completed', {});
+    } catch (error) {
+      run.status = control.signal.aborted ? 'cancelled' : 'failed';
+      const code = timedOut ? 'timed_out' : run.status === 'cancelled' ? 'cancelled' : error instanceof RuntimeFault && error.message === 'interaction_incomplete' ? 'interaction_incomplete' : 'runtime_failed';
+      if (this.pending?.runId === run.id) this.emit(run, 'interaction_ended', { id: this.pending.request.id, code });
+      this.emit(run, 'failed', { code });
+    } finally {
+      // Keep the pre-run display snapshot current for browser reconnects without
+      // closing a running SDK session or replaying any transcript into the agent.
+      session.history = [...session.history, ...displayRun(run)];
+      this.pending = undefined; disconnect(); clearTimeout(timer); clearTimeout(hardTimer); this.active = undefined;
+    }
+  }
+  events(owner: string, id: string, after: number) {
+    const run = this.run(owner, id);
+    if (!Number.isSafeInteger(after) || after < 0 || after > run.events.length) throw new RuntimeFault('invalid_cursor', 400);
+    return { events: run.events.slice(after), status: run.status };
+  }
+  subscribe(id: string, listener: (event: RuntimeEvent) => void) {
+    const listeners = this.listeners.get(id) ?? new Set(); listeners.add(listener); this.listeners.set(id, listeners);
+    return () => { listeners.delete(listener); if (!listeners.size) this.listeners.delete(id); };
+  }
+  answer(owner: string, runId: string, response: InteractionResponse) {
+    const run = this.run(owner, runId);
+    const pending = this.pending;
+    if (!pending || pending.runId !== runId || run.status !== 'running') throw new RuntimeFault('stale_interaction');
+    let value: InteractionResponse;
+    try { value = validateResponse(pending.request, response); } catch { throw new RuntimeFault('invalid_response', 400); }
+    this.emit(run, 'interaction_resolved', { id: value.id }); pending.resolve(value);
+  }
+  cancel(owner: string, id: string) {
+    this.run(owner, id);
+    if (this.active?.run.id === id) this.active.control.abort();
+  }
+  async close() { this.active?.control.abort(); await this.host.close(); }
+}
+