ompchamber 0.3.0

package/src/server/lib/omp/subagent/history/transcript.test.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import { join } from 'path';
+
+import { readSubagentTranscriptPage } from '@/server/lib/omp/subagent/history/transcript';
+
+const tempDirs: string[] = [];
+
+/** Build a parent session file plus its sibling artifacts dir. */
+async function makeSession(childFiles: Record<string, string>): Promise<string> {
+  const dir = await fs.promises.mkdtemp('omp-transcript-');
+  tempDirs.push(dir);
+  const sessionFile = join(dir, 'parent.jsonl');
+  await Bun.write(sessionFile, '{"type":"session"}\n');
+  const siblingDir = join(dir, 'parent');
+  await fs.promises.mkdir(siblingDir, { recursive: true });
+  for (const [name, body] of Object.entries(childFiles)) {
+    await Bun.write(join(siblingDir, name), body);
+  }
+  return sessionFile;
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const twoLines = '{"type":"message","id":"1"}\n{"type":"message","id":"2"}\n';
+
+describe('readSubagentTranscriptPage', () => {
+  test('resolves a page for a child transcript on disk', async () => {
+    const sessionFile = await makeSession({ 'child.jsonl': twoLines });
+    const page = await readSubagentTranscriptPage(sessionFile, 'child', 0);
+    expect(page).not.toBeNull();
+    expect(page!.messages).toHaveLength(2);
+    expect(page!.totalBytes).toBe(Buffer.byteLength(twoLines, 'utf8'));
+    expect(page!.nextByte).toBe(Buffer.byteLength(twoLines, 'utf8'));
+  });
+
+  test('returns null for an unknown subagent id', async () => {
+    const sessionFile = await makeSession({ 'child.jsonl': twoLines });
+    expect(await readSubagentTranscriptPage(sessionFile, 'missing', 0)).toBeNull();
+  });
+
+  test('rejects ids that do not match the grammar before touching the fs', async () => {
+    const sessionFile = await makeSession({ 'child.jsonl': twoLines });
+    for (const id of ['../etc/passwd', 'a/b', '', 'x'.repeat(101)]) {
+      expect(await readSubagentTranscriptPage(sessionFile, id, 0)).toBeNull();
+    }
+  });
+
+  test('refuses a symlink that escapes the sibling dir', async () => {
+    const sessionFile = await makeSession({});
+    const dir = tempDirs[tempDirs.length - 1];
+    const outside = join(dir, 'outside.jsonl');
+    await Bun.write(outside, '{"secret":true}\n');
+    await fs.promises.symlink(outside, join(dir, 'parent', 'escaped.jsonl'));
+    expect(await readSubagentTranscriptPage(sessionFile, 'escaped', 0)).toBeNull();
+  });
+
+  test('pages forward by byte window and resets past the end', async () => {
+    const sessionFile = await makeSession({ 'child.jsonl': twoLines });
+    const first = await readSubagentTranscriptPage(sessionFile, 'child', 0, 30);
+    expect(first!.messages).toHaveLength(1);
+    expect(first!.nextByte).toBeGreaterThan(0);
+
+    const second = await readSubagentTranscriptPage(sessionFile, 'child', first!.nextByte, 30);
+    expect(second!.messages).toHaveLength(1);
+    expect(second!.nextByte).toBe(Buffer.byteLength(twoLines, 'utf8'));
+
+    const past = await readSubagentTranscriptPage(sessionFile, 'child', 99_999, 30);
+    expect(past!.reset).toBe(true);
+    expect(past!.fromByte).toBe(0);
+  });
+
+  test('returns null when the parent has no sibling artifacts dir', async () => {
+    const dir = await fs.promises.mkdtemp('omp-transcript-');
+    tempDirs.push(dir);
+    const sessionFile = join(dir, 'lonely.jsonl');
+    await Bun.write(sessionFile, '{"type":"session"}\n');
+    expect(await readSubagentTranscriptPage(sessionFile, 'child', 0)).toBeNull();
+  });
+});

package/src/server/lib/omp/subagent/history/transcript.ts

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Byte-window transcript paging for on-disk subagent histories.
+ *
+ * The child transcript is a plain omp session JSONL (`<parent>/<id>.jsonl`);
+ * pages are read positionally from `fromByte` so a pagination walk is O(n) in
+ * I/O and a page never materializes more than `maxBytes`. Entries are returned
+ * raw — the client converts them to chat messages, so message bodies are never
+ * parsed server-side beyond splitting complete JSONL lines.
+ *
+ * Mirrors omp-web/lib/subagent-history.ts readSubagentTranscriptPage, with the
+ * child path resolved from the parent session file + subagent id.
+ */
+
+import { promises as fsp } from 'fs';
+import { dirname, join } from 'path';
+import { parseJsonlLenient } from '@/shared/lib/omp/session/jsonl';
+import { SUBAGENT_ID_MAX_LENGTH, SUBAGENT_ID_RE, siblingDirForSession } from '@/server/lib/omp/subagent/history/paths';
+import type { SubagentMessagesPage } from '@/shared/types/omp/subagent';
+
+/** Bytes read per page call — bounds each response window. */
+export const SUBAGENT_TRANSCRIPT_PAGE_BYTES = 256 * 1024;
+
+/**
+ * Resolve a subagent transcript inside the parent session's sibling artifacts
+ * dir, with symlink confinement: the candidate's REAL path must land directly
+ * inside the REAL artifacts dir and be a regular file. The id grammar is
+ * validated by the caller, so no traversal form can reach the join.
+ */
+async function resolveTranscriptPath(sessionFilePath: string, subagentId: string): Promise<string | null> {
+  let realDir: string;
+  try {
+    realDir = await fsp.realpath(siblingDirForSession(sessionFilePath));
+  } catch {
+    return null;
+  }
+  const candidate = join(realDir, `${subagentId}.jsonl`);
+  let realCandidate: string;
+  try {
+    realCandidate = await fsp.realpath(candidate);
+  } catch {
+    return null;
+  }
+  if (dirname(realCandidate) !== realDir) return null;
+  try {
+    if (!(await Bun.file(realCandidate).stat()).isFile()) return null;
+  } catch {
+    return null;
+  }
+  return realCandidate;
+}
+
+/**
+ * Read a byte window of a subagent transcript starting at `fromByte`.
+ * Returns null when the parent has no sibling dir or the child transcript is
+ * missing. `reset` is set when `fromByte` sits past the file end (retruncated
+ * transcript) — the caller must restart paging from the returned fromByte.
+ */
+export async function readSubagentTranscriptPage(
+  sessionFilePath: string,
+  subagentId: string,
+  fromByte = 0,
+  maxBytes: number = SUBAGENT_TRANSCRIPT_PAGE_BYTES,
+): Promise<SubagentMessagesPage | null> {
+  if (!SUBAGENT_ID_RE.test(subagentId) || subagentId.length > SUBAGENT_ID_MAX_LENGTH) return null;
+  const transcriptPath = await resolveTranscriptPath(sessionFilePath, subagentId);
+  if (!transcriptPath) return null;
+
+  let size: number;
+  try {
+    size = (await Bun.file(transcriptPath).stat()).size;
+  } catch {
+    return null;
+  }
+
+  const requested = typeof fromByte === 'number' && Number.isFinite(fromByte)
+    ? Math.max(0, Math.trunc(fromByte))
+    : 0;
+  const reset = requested > size;
+  const startByte = reset ? 0 : requested;
+  const pageBytes = Number.isFinite(maxBytes) && maxBytes > 0
+    ? Math.trunc(maxBytes)
+    : SUBAGENT_TRANSCRIPT_PAGE_BYTES;
+  const endByte = Math.min(size, startByte + pageBytes);
+
+  let body = '';
+  try {
+    // Slice by BYTE offsets, not string indices: startByte is a UTF-8 offset
+    // while string indices are UTF-16 code units — slicing the decoded string
+    // would misalign every later page once non-ASCII text precedes the offset.
+    const windowBytes = endByte - startByte;
+    if (windowBytes > 0) {
+      body = await Bun.file(transcriptPath).slice(startByte, endByte).text();
+    }
+  } catch {
+    return {
+      sessionFile: transcriptPath,
+      fromByte: startByte,
+      nextByte: startByte,
+      reset,
+      messages: [],
+      totalBytes: size,
+    };
+  }
+
+  // JSON.stringify never emits raw newlines, so only complete lines are safe to
+  // deliver — a torn tail line is left for the next page.
+  const lastNewline = body.lastIndexOf('\n');
+  const completeText = lastNewline >= 0 ? body.slice(0, lastNewline + 1) : '';
+  const messages = completeText.length > 0 ? parseJsonlLenient<unknown>(completeText) : [];
+  let nextByte = startByte + Buffer.byteLength(completeText, 'utf8');
+  // Guarantee forward progress: when the window ends mid-line and more content
+  // remains, the partial line has no newline to complete it — skip it instead
+  // of returning the same offset forever.
+  if (nextByte === startByte && endByte < size) nextByte = endByte;
+
+  return { sessionFile: transcriptPath, fromByte: startByte, nextByte, reset, messages, totalBytes: size };
+}

package/src/server/lib/remix-compat.ts

@@ -0,0 +1,29 @@
+/**
+ * The `@remix-run/node` surface the API route modules actually used: the
+ * `json()` response helper and the two context argument types. Elysia serves
+ * these modules now (see `@/server/lib/route-adapter`), so the shim keeps the
+ * loader/action bodies — and therefore every status code and payload — intact.
+ */
+export interface LoaderFunctionArgs {
+  request: Request;
+  params: Record<string, string>;
+}
+
+export interface ActionFunctionArgs {
+  request: Request;
+  params: Record<string, string>;
+}
+
+export interface JsonInit {
+  status?: number;
+  headers?: Record<string, string>;
+}
+
+export function json(data: unknown, init: JsonInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has('content-type')) headers.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify(data), { status: init.status ?? 200, headers });
+}
+
+/** Shared no-store response headers for endpoints that must never be cached. */
+export const NO_STORE_HEADERS: Record<string, string> = { 'cache-control': 'no-store' };

package/src/server/lib/route-adapter.ts

@@ -0,0 +1,144 @@
+import { json, type ActionFunctionArgs, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { maybeCompress } from '@/server/plugins/compress';
+
+/**
+ * Serves ported Remix route modules from Elysia.
+ *
+ * The API modules were written against Remix's `loader`/`action` contract and
+ * each one encodes its own method dispatch, status codes, and error envelopes.
+ * Rewriting them by hand would put every one of those behaviors at risk, so
+ * instead each domain module exports a table of `{ method, path, handler }`
+ * bindings and `routes/index.ts` projects them onto one Elysia instance.
+ *
+ * Bindings are plain data, which sidesteps Elysia's invariant per-prefix
+ * instance generics: no module has to thread a parameterized Elysia type
+ * around just to contribute routes.
+ */
+
+export type RouteModule = {
+  loader?: (args: LoaderFunctionArgs) => unknown;
+  action?: (args: ActionFunctionArgs) => unknown;
+};
+
+export type RouteMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export type RouteHandler = (args: LoaderFunctionArgs | ActionFunctionArgs) => unknown;
+
+export interface HandlerBinding {
+  method: RouteMethod;
+  path: string;
+  handler: RouteHandler;
+}
+
+export interface MountOptions {
+  mutating?: readonly Exclude<RouteMethod, 'GET'>[];
+}
+
+export function bindingsFor(module: RouteModule, path: string, options: MountOptions = {}): HandlerBinding[] {
+  const bindings: HandlerBinding[] = [];
+  if (module.loader) bindings.push({ method: 'GET', path, handler: module.loader });
+  else if (module.action) bindings.push({ method: 'GET', path, handler: methodNotAllowed });
+  if (module.action) {
+    for (const method of options.mutating ?? (['POST', 'PUT', 'PATCH', 'DELETE'] as const)) {
+      bindings.push({ method, path, handler: module.action });
+    }
+  }
+  return bindings;
+}
+
+/**
+ * Remix answered a GET on an action-only route with 405, not 404 — the route
+ * exists, the verb does not. Keeping that shape means a mistyped client call
+ * reports the real problem instead of looking like a missing endpoint.
+ */
+export const methodNotAllowed: RouteHandler = () =>
+  new Response(JSON.stringify({ error: 'Method not allowed' }), {
+    status: 405,
+    headers: { 'content-type': 'application/json; charset=utf-8' },
+  });
+
+/** Parse a JSON request body without throwing. Caller decides the status code. */
+export async function parseJsonBody<T = unknown>(
+  request: Request,
+): Promise<{ ok: true; body: T } | { ok: false; error: string }> {
+  try {
+    return { ok: true, body: (await request.json()) as T };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Extract a required route param; returns null when absent or empty. */
+export function requireParam(params: Record<string, string>, name: string): string | null {
+  const value = params[name];
+  return value ? value : null;
+}
+
+/** JSON error envelope with the given status (default 500). */
+export function errorResponse(error: unknown, status = 500): Response {
+  return json({ error: error instanceof Error ? error.message : String(error) }, { status });
+}
+
+async function toResponse(value: unknown): Promise<Response> {
+  if (value instanceof Response) return value;
+  if (value instanceof ReadableStream) {
+    return new Response(value, {
+      headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' },
+    });
+  }
+  return new Response(JSON.stringify(value ?? null), {
+    status: 200,
+    headers: { 'content-type': 'application/json; charset=utf-8' },
+  });
+}
+
+export function adaptHandler(handler: RouteHandler) {
+  return async ({ request, params }: { request: Request; params: Record<string, string> }) => {
+    try {
+      const response = await toResponse(await handler({ request, params }));
+      return await maybeCompress(response, request.headers.get('accept-encoding'));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return new Response(JSON.stringify({ error: message }), {
+        status: 500,
+        headers: { 'content-type': 'application/json; charset=utf-8' },
+      });
+    }
+  };
+}
+
+/** Register binding tables on an Elysia app. Returns the same instance. */
+export function mountBindings<T extends {
+  get: (path: string, handler: never) => T;
+  post: (path: string, handler: never) => T;
+  put: (path: string, handler: never) => T;
+  patch: (path: string, handler: never) => T;
+  delete: (path: string, handler: never) => T;
+}>(app: T, bindings: readonly HandlerBinding[]): T {
+  let next = app;
+  for (const { method, path, handler } of bindings) {
+    const adapted = adaptHandler(handler) as never;
+    if (method === 'GET') next = next.get(path, adapted);
+    else if (method === 'POST') next = next.post(path, adapted);
+    else if (method === 'PUT') next = next.put(path, adapted);
+    else if (method === 'PATCH') next = next.patch(path, adapted);
+    else next = next.delete(path, adapted);
+  }
+  return next;
+}
+
+/**
+ * Mutating verbs for a directly-exported action handler. Pass `getHandler` when
+ * the same path also serves a GET; otherwise a 405 GET fallback is added so a
+ * mistyped verb reports the real problem instead of a missing route.
+ */
+export function actionBindings(
+  handler: RouteHandler,
+  path: string,
+  getHandler?: RouteHandler,
+): HandlerBinding[] {
+  return [
+    { method: 'GET', path, handler: getHandler ?? methodNotAllowed },
+    ...(['POST', 'PUT', 'PATCH', 'DELETE'] as const).map((method) => ({ method, path, handler })),
+  ];
+}

package/src/server/lib/sse.ts

@@ -0,0 +1,248 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared Server-Sent Events plumbing for the chamber's streaming routes.
+ *
+ * Six SSE endpoints hand-rolled the same lifecycle — a `TextEncoder`, a
+ * `ReadableStream`, `event:`/`data:` frame encoding, an optional comment-frame
+ * heartbeat, abort teardown, and a `text/event-stream` Response. The agent SSE
+ * and WebSocket transports additionally hand-rolled the same latest-wins
+ * backpressure policy. This module owns both pieces:
+ *
+ * - `createSseStream` — the HTTP lifecycle and wire format.
+ * - `createEventCoalescer` — the coalescing policy, transport-agnostic so the
+ *   WebSocket twin can reuse it over `ws.send` instead of `controller.enqueue`.
+ *
+ * Wire format is fixed: `event: <name>\ndata: <json>\n\n`, or `data: <json>\n\n`
+ * when no event name is supplied (the agent/omp-login data-only frames).
+ */
+
+/** Emit one SSE frame. An empty `event` writes a data-only frame. */
+export type SseSend = (event: string, data: unknown) => void;
+
+export interface SseHandlers {
+  send: SseSend;
+  /** Idempotent teardown: timers, abort listener, caller cleanup, close. */
+  close: () => void;
+  /** True while the consumer is behind (`desiredSize < 0`). */
+  isBackpressured: () => boolean;
+  /** True once the stream has been torn down. */
+  isClosed: () => boolean;
+}
+
+export interface SseStream {
+  /** `text/event-stream` Response ready to return from a loader/action. */
+  response: Response;
+  /** Emit one frame. An empty `event` writes a data-only frame. */
+  send: SseSend;
+  /** Idempotent teardown: timers, abort listener, caller cleanup, close. */
+  close: () => void;
+  /** True while the consumer is behind (`desiredSize < 0`). */
+  isBackpressured: () => boolean;
+  /** True once the stream has been torn down. */
+  isClosed: () => boolean;
+}
+
+export interface SseStreamOptions {
+  /**
+   * Runs inside `ReadableStream.start` after the abort listener is armed. May
+   * be async; may return a cleanup callback (run on teardown, before close).
+   */
+  onStart?: (handlers: SseHandlers) => void | (() => void) | Promise<void | (() => void)>;
+  /** Comment-frame heartbeat interval (`:\n\n`). Omit for no heartbeat. */
+  heartbeatMs?: number;
+  /** Runs before each heartbeat; return false to skip that beat. */
+  beforeHeartbeat?: () => boolean;
+  /** Abort signal that tears the stream down (client disconnect). */
+  signal?: AbortSignal;
+  /** Extra/overriding headers merged over the defaults. */
+  headers?: Record<string, string>;
+}
+
+export function createSseStream(options: SseStreamOptions = {}): SseStream {
+  const encoder = new TextEncoder();
+  let streamController: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let closed = false;
+  let cleaned = false;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let onStartCleanup: (() => void) | null = null;
+
+  function cleanup(): void {
+    if (cleaned) return;
+    cleaned = true;
+    closed = true;
+    if (heartbeatTimer !== null) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    options.signal?.removeEventListener('abort', onAbort);
+    const fn = onStartCleanup;
+    onStartCleanup = null;
+    if (fn) {
+      try {
+        fn();
+      } catch {
+        // Caller cleanup is best-effort.
+      }
+    }
+    try {
+      streamController?.close();
+    } catch {
+      // Controller already closed.
+    }
+  }
+
+  const onAbort = (): void => cleanup();
+
+  const send: SseSend = (event, data) => {
+    if (closed || !streamController) return;
+    const frame = event
+      ? `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
+      : `data: ${JSON.stringify(data)}\n\n`;
+    try {
+      streamController.enqueue(encoder.encode(frame));
+    } catch {
+      cleanup();
+    }
+  };
+
+  const isBackpressured = (): boolean => {
+    const controller = streamController;
+    return controller !== null && controller.desiredSize !== null && controller.desiredSize < 0;
+  };
+
+  const handlers: SseHandlers = { send, close: cleanup, isBackpressured, isClosed: () => closed };
+
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      streamController = controller;
+
+      if (options.heartbeatMs !== undefined) {
+        heartbeatTimer = setInterval(() => {
+          if (closed) return;
+          if (options.beforeHeartbeat && !options.beforeHeartbeat()) return;
+          if (closed) return;
+          try {
+            controller.enqueue(encoder.encode(':\n\n'));
+          } catch {
+            cleanup();
+          }
+        }, options.heartbeatMs);
+      }
+
+      if (options.signal) {
+        options.signal.addEventListener('abort', onAbort);
+        if (options.signal.aborted) {
+          cleanup();
+          return;
+        }
+      }
+
+      const result = await options.onStart?.(handlers);
+      onStartCleanup = typeof result === 'function' ? result : null;
+      if (cleaned) {
+        const fn = onStartCleanup;
+        onStartCleanup = null;
+        try {
+          fn?.();
+        } catch {
+          // Caller cleanup is best-effort.
+        }
+      }
+    },
+    cancel() {
+      cleanup();
+    },
+  });
+
+  const response = new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      ...options.headers,
+    },
+  });
+
+  return { response, send, close: cleanup, isBackpressured, isClosed: () => closed };
+}
+
+export interface EventCoalescer {
+  /** Coalesce replaceable frames while backpressured, else send immediately. */
+  push: (event: string, data: unknown) => void;
+  /** Force the pending frame out now. False when the sink is already torn down. */
+  flush: () => boolean;
+  /** Drop the pending frame and cancel the delayed flush. */
+  dispose: () => void;
+}
+
+export interface EventCoalescerOptions {
+  send: SseSend;
+  /** Backpressure probe — `desiredSize < 0` for SSE, buffered bytes for WS. */
+  isBackpressured: () => boolean;
+  /** Longest a coalesced frame waits before it is flushed anyway. */
+  flushDelayMs: number;
+}
+
+/**
+ * Latest-wins coalescer for replaceable `message_update` frames. Control frames
+ * are never dropped; they flush the pending update first so ordering is kept.
+ */
+export function createEventCoalescer(options: EventCoalescerOptions): EventCoalescer {
+  let pending: unknown = null;
+  let pendingEvent = '';
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let disposed = false;
+
+  const flush = (): boolean => {
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    const data = pending;
+    const event = pendingEvent;
+    pending = null;
+    pendingEvent = '';
+    if (data === null) return true;
+    if (disposed) return false;
+    options.send(event, data);
+    return !disposed;
+  };
+
+  const scheduleFlush = (): void => {
+    if (flushTimer !== null) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      if (!disposed) flush();
+    }, options.flushDelayMs);
+  };
+
+  return {
+    push(event, data) {
+      if (disposed) return;
+      const type = (data as { type?: string } | null)?.type;
+      if (type === 'message_update' && options.isBackpressured()) {
+        pending = data;
+        pendingEvent = event;
+        scheduleFlush();
+        return;
+      }
+      if (!flush()) return;
+      options.send(event, data);
+    },
+    flush,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      pending = null;
+      pendingEvent = '';
+      if (flushTimer !== null) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+    },
+  };
+}

package/src/server/lib/updates/apply.ts

@@ -0,0 +1,46 @@
+/**
+ * Applies a requested update. oh-my-pi is updated through the omp binary;
+ * OMPChamber through the shared self-update engine, which replaces the running
+ * install in place (bun global install, or git fast-forward + rebuild).
+ */
+
+import { updateOmpChamber } from '@/server/lib/updates/install';
+import { applyOmpUpdate } from '@/server/lib/updates/omp';
+import type { UpdateApplyResult, UpdateTarget } from '@/shared/types/updates';
+
+/** A server cannot replace its own process, so the user restarts it. */
+const RESTART_NOTE = ' Restart the server (`ompchamber restart`) to apply it.';
+
+export async function applyUpdate(target: UpdateTarget): Promise<UpdateApplyResult> {
+  if (target === 'omp') {
+    try {
+      const { output } = await applyOmpUpdate();
+      return { success: true, target: 'omp', manual: false, message: 'oh-my-pi updated', output };
+    } catch (err) {
+      return {
+        success: false,
+        target: 'omp',
+        manual: false,
+        message: err instanceof Error ? err.message : 'Failed to update oh-my-pi',
+      };
+    }
+  }
+
+  if (target === 'ompchamber') {
+    const result = await updateOmpChamber();
+    return {
+      success: result.success,
+      target: 'ompchamber',
+      manual: result.manual,
+      message: `${result.message}${result.updated ? RESTART_NOTE : ''}`,
+      output: result.output || undefined,
+    };
+  }
+
+  return {
+    success: false,
+    target,
+    manual: true,
+    message: 'Unknown update target',
+  };
+}