carthagent 0.0.0-stage → 1.0.7

package/plugins/carthagent/src/archive-rpc.ts

@@ -0,0 +1,46 @@
+import { Rpc } from '@opencode/plugin/rpc';
+
+const id = { type: 'string', minLength: 1, maxLength: 128 } as const;
+const page = { type: 'integer', minimum: 0, maximum: 1_000_000 } as const;
+const limit = { type: 'integer', minimum: 1, maximum: 100 } as const;
+const item = {
+  type: 'object', properties: {
+    id, createdAt: {}, messageCount: { type: 'integer', minimum: 0 }, malformedLines: { type: 'array', items: { type: 'object', properties: { line: { type: 'integer', minimum: 1 } }, required: ['line'], additionalProperties: false } }, moreMalformedLines: { type: 'boolean' },
+    excerpt: { type: 'string' }, archiveOnly: { type: 'boolean', const: true },
+  }, required: ['id', 'messageCount', 'malformedLines', 'moreMalformedLines', 'archiveOnly'], additionalProperties: false,
+} as const;
+const errors = {
+  archive_error: {
+    type: 'object', properties: {
+      code: { type: 'string', enum: ['invalid_request', 'not_found', 'limit_exceeded', 'archive_io'] },
+    }, required: ['code'], additionalProperties: false,
+  },
+} as const;
+
+/** Opaque-ID-only contract. Clients never provide filesystem paths. */
+export const Archive = Rpc.define({
+  id: 'carthagent.archive',
+  methods: {
+    list: {
+      errors,
+      input: { type: 'object', properties: { offset: page, limit }, additionalProperties: false },
+      output: { type: 'object', properties: { items: { type: 'array', items: item }, total: { type: 'integer', minimum: 0 }, offset: page, limit }, required: ['items', 'total', 'offset', 'limit'], additionalProperties: false },
+    },
+    search: {
+      errors,
+      input: { type: 'object', properties: { query: { type: 'string', minLength: 1, maxLength: 200 }, offset: page, limit }, required: ['query'], additionalProperties: false },
+      output: { type: 'object', properties: { items: { type: 'array', items: item }, total: { type: 'integer', minimum: 0 }, offset: page, limit }, required: ['items', 'total', 'offset', 'limit'], additionalProperties: false },
+    },
+    read: {
+      errors,
+      input: { type: 'object', properties: { id }, required: ['id'], additionalProperties: false },
+      output: { type: 'object', properties: { id, records: { type: 'array', items: {} }, malformedLines: item.properties.malformedLines, moreMalformedLines: { type: 'boolean' }, archiveOnly: { type: 'boolean', const: true } }, required: ['id', 'records', 'malformedLines', 'moreMalformedLines', 'archiveOnly'], additionalProperties: false },
+    },
+    export: {
+      errors,
+      input: { type: 'object', properties: { id, format: { type: 'string', enum: ['json', 'jsonl'] } }, required: ['id'], additionalProperties: false },
+      output: { type: 'object', properties: { id, format: { type: 'string', enum: ['json', 'jsonl'] }, content: { type: 'string', maxLength: 5_000_000 }, archiveOnly: { type: 'boolean', const: true } }, required: ['id', 'format', 'content', 'archiveOnly'], additionalProperties: false },
+    },
+  },
+  events: {},
+});

package/plugins/carthagent/src/bootstrap.ts

@@ -0,0 +1,38 @@
+import { Plugin } from '@opencode/plugin/tui';
+import { Carthagent } from './rpc';
+
+/** Foundation diagnostic; replaced by the full UI entrypoint at integration. */
+export default Plugin.define({
+  id: 'carthagent.tui',
+  setup(context) {
+    context.keymap.layer(() => ({
+      mode: 'global',
+      commands: [{
+        id: 'carthagent.health',
+        title: 'Carthagent runtime status',
+        palette: true,
+        slash: { name: 'ctg-status' },
+        async run() {
+          try {
+            const result = await context.client.rpc(Carthagent).health({}, {
+              location: context.location ?? context.data.location.default(),
+              signal: AbortSignal.timeout(10_000),
+            });
+            const health = result as { hostVersion: string; directory: string };
+            context.ui.toast.show({
+              title: 'Carthagent',
+              message: `OpenCode ${health.hostVersion} · ${context.ui.format.path(health.directory)}`,
+              variant: 'success',
+            });
+          } catch (error) {
+            context.ui.toast.show({
+              title: 'Carthagent runtime unavailable',
+              message: error instanceof Error ? error.message : 'Could not read runtime status',
+              variant: 'error',
+            });
+          }
+        },
+      }],
+    }));
+  },
+});

package/plugins/carthagent/src/index.ts

@@ -0,0 +1,62 @@
+import { Plugin } from '@opencode/plugin';
+import { Carthagent } from './rpc';
+import { registerProviders } from './server/providers';
+import { createDeviceAuthController } from './server/device-auth.ts';
+import { shipAgentDir } from '../../../lib/ship-auth.mjs';
+import { registerSessionControls } from './server/session-controls';
+import { registerNativeDelivery } from './server/native-delivery';
+
+async function cleanup(resources: Array<() => Promise<void>>, originalError?: unknown) {
+  const failures: unknown[] = [];
+  for (const dispose of resources.reverse()) {
+    try { await dispose(); }
+    catch (error) { failures.push(error); }
+  }
+  if (originalError !== undefined && failures.length) {
+    throw new AggregateError([originalError, ...failures], 'Plugin setup failed and one or more completed registrations could not be disposed.');
+  }
+  if (originalError !== undefined) throw originalError;
+  if (failures.length) throw new AggregateError(failures, 'One or more plugin registrations could not be disposed.');
+}
+
+export async function setupCarthagent(context: Parameters<typeof registerSessionControls>[0], options: { delivery?: boolean; deliveryOptions?: Parameters<typeof registerNativeDelivery>[1] } = {}) {
+    const cleanups: Array<() => Promise<void>> = [];
+    try {
+      cleanups.push(await registerSessionControls(context));
+      const deviceAuth = createDeviceAuthController({ env: process.env, agentDir: shipAgentDir() });
+      cleanups.push(() => deviceAuth.cleanup());
+      const rpcRegistration = await context.rpc.register(Carthagent, {
+        health: async () => ({
+          protocol: 1,
+          hostVersion: context.app.version,
+          directory: context.location.directory,
+        }),
+        echo: async input => ({ text: (input as { text: string }).text }),
+        authStart: async (_input, call) => {
+          call.signal.throwIfAborted();
+          const flow = await deviceAuth.start(call.signal);
+          const cancel = () => deviceAuth.cancel(flow.flowId);
+          if (call.signal.aborted) cancel();
+          else call.signal.addEventListener('abort', cancel, { once: true });
+          return {
+            flowId: flow.flowId,
+            userCode: flow.authorization.userCode,
+            verificationUri: flow.authorization.verificationUriComplete || flow.authorization.verificationUri,
+            expiresAt: flow.expiresAt,
+          };
+        },
+        authCancel: async (input, call) => {
+          call.signal.throwIfAborted();
+          return { cancelled: deviceAuth.cancel((input as { flowId: string }).flowId) };
+        },
+      });
+      cleanups.push(() => rpcRegistration.dispose());
+      cleanups.push(await registerProviders(context, { deviceAuth }));
+      if (options.delivery) cleanups.push(await registerNativeDelivery(context, options.deliveryOptions));
+    } catch (error) {
+      await cleanup(cleanups, error);
+    }
+    return async () => cleanup(cleanups);
+}
+
+export default Plugin.define({ id: 'carthagent', setup: setupCarthagent });

package/plugins/carthagent/src/pull-request-rpc.ts

@@ -0,0 +1,54 @@
+import { Rpc } from '@opencode/plugin/rpc';
+
+const id = { type: 'string', minLength: 1, maxLength: 128 } as const;
+const ref = { type: 'string', minLength: 1, maxLength: 255 } as const;
+const hash = { type: 'string', minLength: 40, maxLength: 64 } as const;
+const url = { type: 'string', minLength: 1, maxLength: 2048 } as const;
+const errors = {
+  pull_request_error: {
+    type: 'object', properties: {
+      code: { type: 'string', enum: ['invalid_request', 'not_owned', 'not_associated', 'github_unavailable', 'github_invalid', 'cache_invalid', 'cache_limit', 'cache_busy', 'worktree_unavailable', 'canceled', 'internal'] },
+    }, required: ['code'], additionalProperties: false,
+  },
+} as const;
+const input = {
+  type: 'object', properties: { sessionID: id, taskID: id, number: { type: 'integer', minimum: 1, maximum: 2147483647 } },
+  required: ['sessionID', 'taskID'], additionalProperties: false,
+} as const;
+const pullRequest = {
+  type: 'object', properties: {
+    taskID: id, number: { type: 'integer', minimum: 1, maximum: 2147483647 }, url, state: { type: 'string', enum: ['open', 'closed'] }, draft: { type: 'boolean' },
+    head: hash, headRef: ref, headRepository: { type: 'string', minLength: 3, maxLength: 511 }, base: hash, baseRef: ref,
+    checks: { type: 'string', enum: ['passed', 'failed', 'pending', 'partial', 'none'] },
+    review: { type: 'string', enum: ['approved-unverified', 'changes-requested', 'unverified', 'unreviewed'] },
+    source: { type: 'string', enum: ['current', 'stale-source'] }, sourceSnapshot: hash, updatedAt: { type: 'string', minLength: 20, maxLength: 40 },
+  }, required: ['taskID', 'number', 'url', 'state', 'draft', 'head', 'headRef', 'headRepository', 'base', 'baseRef', 'checks', 'review', 'source', 'sourceSnapshot', 'updatedAt'], additionalProperties: false,
+} as const;
+
+/** Separate native host contract so workspace RPC composition remains owned by its host. */
+export const PullRequests = Rpc.define({
+  id: 'carthagent.pull-requests',
+  methods: {
+    list: {
+      errors,
+      input: { type: 'object', properties: { sessionID: id, taskID: id }, required: ['sessionID', 'taskID'], additionalProperties: false },
+      output: { type: 'object', properties: { pullRequests: { type: 'array', maxItems: 100, items: pullRequest } }, required: ['pullRequests'], additionalProperties: false },
+    },
+    associate: {
+      errors,
+      input,
+      output: { type: 'object', properties: { pullRequest }, required: ['pullRequest'], additionalProperties: false },
+    },
+    refresh: {
+      errors,
+      input,
+      output: { type: 'object', properties: { pullRequest }, required: ['pullRequest'], additionalProperties: false },
+    },
+  },
+  events: {},
+});
+
+export type PullRequestRecord = {
+  taskID: string; number: number; url: string; state: string; draft: boolean; head: string; headRef: string; headRepository: string; base: string; baseRef: string;
+  checks: string; review: string; source: string; sourceSnapshot: string; updatedAt: string;
+};

package/plugins/carthagent/src/rpc.ts

@@ -0,0 +1,76 @@
+import { Rpc } from '@opencode/plugin/rpc';
+
+/** Public CTG protocol. Clients use snapshots after reconnect, never event replay. */
+export const Carthagent = Rpc.define({
+  id: 'carthagent',
+  methods: {
+    health: {
+      input: { type: 'object', additionalProperties: false },
+      output: {
+        type: 'object',
+        properties: {
+          protocol: { type: 'integer', const: 1 },
+          hostVersion: { type: 'string' },
+          directory: { type: 'string' },
+        },
+        required: ['protocol', 'hostVersion', 'directory'],
+        additionalProperties: false,
+      },
+    },
+    echo: {
+      input: {
+        type: 'object',
+        properties: { text: { type: 'string' } },
+        required: ['text'],
+        additionalProperties: false,
+      },
+      output: {
+        type: 'object',
+        properties: { text: { type: 'string' } },
+        required: ['text'],
+        additionalProperties: false,
+      },
+    },
+    authStart: {
+      input: { type: 'object', additionalProperties: false },
+      output: {
+        type: 'object',
+        properties: {
+          flowId: { type: 'string' },
+          userCode: { type: 'string' },
+          verificationUri: { type: 'string' },
+          expiresAt: { type: 'integer' },
+        },
+        required: ['flowId', 'userCode', 'verificationUri', 'expiresAt'],
+        additionalProperties: false,
+      },
+    },
+    authCancel: {
+      input: {
+        type: 'object',
+        properties: { flowId: { type: 'string' } },
+        required: ['flowId'],
+        additionalProperties: false,
+      },
+      output: {
+        type: 'object',
+        properties: { cancelled: { type: 'boolean' } },
+        required: ['cancelled'],
+        additionalProperties: false,
+      },
+    },
+  },
+  events: {
+    changed: {
+      schema: {
+        type: 'object',
+        properties: {
+          sessionID: { type: 'string' },
+          domain: { type: 'string' },
+        },
+        required: ['domain'],
+        additionalProperties: false,
+      },
+    },
+  },
+});

package/plugins/carthagent/src/server/archive-rpc.ts

@@ -0,0 +1,327 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, opendir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import type { Context } from '@opencode/plugin/promise/plugin';
+import { Archive } from '../archive-rpc';
+
+const MAX_FILE_BYTES = 4_000_000;
+const MAX_FILES = 2_000;
+const MAX_ENTRIES = 10_000;
+const MAX_TOTAL_BYTES = 50_000_000;
+const MAX_PAGE = 100;
+const MAX_DIAGNOSTICS = 1000;
+const MAX_RECORDS = 10_000;
+const MAX_SCAN_RECORDS = 100_000;
+const READ_CHUNK = 64 * 1024;
+
+type Options = { archiveRoots?: string[]; archiveDir?: string };
+type FileInfo = { path: string; root: string; id: string; size: number };
+type Row = { type?: string; timestamp?: unknown; message?: unknown; [key: string]: unknown };
+type Parsed = { records: Row[]; malformedLines: Array<{ line: number }>; moreMalformedLines: boolean; recordsBytes: number; recordCount: number };
+type ArchiveItem = { path: string; id: string; createdAt: unknown; messageCount: number; malformedLines: Array<{ line: number }>; moreMalformedLines: boolean; searchText: string; excerpt?: string };
+type FailureCode = 'invalid_request' | 'not_found' | 'limit_exceeded' | 'archive_io';
+class ArchiveFailure extends Error {
+  constructor(readonly code: FailureCode, message: string) { super(message); }
+}
+
+function inside(root: string, path: string) {
+  const fromRoot = relative(root, path);
+  return fromRoot === '' || (fromRoot !== '..' && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot));
+}
+
+async function rootsFrom(options: Options): Promise<string[]> {
+  const configured = options.archiveRoots ?? (options.archiveDir ? [options.archiveDir] : undefined);
+  const roots = configured ?? [join(homedir(), '.carthagent', 'agent', 'sessions')];
+  if (!Array.isArray(roots) || roots.some(root => typeof root !== 'string' || !isAbsolute(root) || resolve(root) !== root)) {
+    throw new ArchiveFailure('invalid_request', 'Archive roots must be normalized absolute paths configured by the host');
+  }
+  const canonicalRoots: string[] = [];
+  for (const root of roots) {
+    try { canonicalRoots.push(await realpath(root)); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') canonicalRoots.push(root);
+      else throw new ArchiveFailure('archive_io', 'Unable to resolve a configured archive root');
+    }
+  }
+  return [...new Set(canonicalRoots)];
+}
+
+function aborted(signal: AbortSignal) {
+  if (signal.aborted) throw signal.reason ?? new DOMException('Operation aborted', 'AbortError');
+}
+
+function sameFile(
+  left: NonNullable<Awaited<ReturnType<import('node:fs/promises').FileHandle['stat']>>>,
+  right: NonNullable<Awaited<ReturnType<import('node:fs/promises').FileHandle['stat']>>>,
+) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+/** Bind path containment and opened descriptor identity before any bytes are consumed. */
+export async function verifyOpenedTarget(file: Pick<FileInfo, 'path' | 'root'>, handle: Awaited<ReturnType<typeof open>>) {
+  let canonical: string;
+  let pathStat;
+  let descriptorStat;
+  try {
+    [canonical, pathStat, descriptorStat] = await Promise.all([realpath(file.path), stat(file.path), handle.stat()]);
+  } catch {
+    throw new ArchiveFailure('not_found', 'Archive transcript changed while opening');
+  }
+  if (!inside(file.root, canonical) || canonical !== file.path || !pathStat.isFile() || !descriptorStat.isFile() || !sameFile(pathStat, descriptorStat)) {
+    throw new ArchiveFailure('not_found', 'Archive transcript target changed outside its configured root');
+  }
+  return descriptorStat;
+}
+
+async function enumerate(roots: string[], signal: AbortSignal): Promise<FileInfo[]> {
+  let entriesSeen = 0;
+  let totalBytes = 0;
+  const found: FileInfo[] = [];
+  for (const root of roots) {
+    aborted(signal);
+    let metadata;
+    try { metadata = await stat(root); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+      throw new ArchiveFailure('archive_io', 'Unable to inspect a configured archive root');
+    }
+    if (!metadata.isDirectory()) continue;
+    const pending = [root];
+    while (pending.length) {
+      aborted(signal);
+      const directoryPath = pending.pop()!;
+      let canonicalDirectory: string;
+      try { canonicalDirectory = await realpath(directoryPath); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw new ArchiveFailure('archive_io', 'Unable to resolve an archive directory');
+      }
+      if (!inside(root, canonicalDirectory)) continue;
+      let directory;
+      try { directory = await opendir(directoryPath); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw new ArchiveFailure('archive_io', 'Unable to enumerate a configured archive root');
+      }
+      for await (const entry of directory) {
+        aborted(signal);
+        entriesSeen++;
+        if (entriesSeen > MAX_ENTRIES) throw new ArchiveFailure('limit_exceeded', `Archive exceeds the ${MAX_ENTRIES} entry scan limit`);
+        if (entry.isSymbolicLink()) continue;
+        const path = join(directoryPath, entry.name);
+        if (entry.isDirectory()) { pending.push(path); continue; }
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+        if (found.length >= MAX_FILES) throw new ArchiveFailure('limit_exceeded', `Archive exceeds the ${MAX_FILES} transcript scan limit`);
+        let canonical;
+        try { canonical = await realpath(path); }
+        catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+          throw new ArchiveFailure('archive_io', 'Unable to resolve an archive transcript');
+        }
+        if (!inside(root, canonical)) continue;
+        const id = createHash('sha256').update(root).update('\0').update(canonical).digest('hex');
+        // Do not trust Dirent or pathname stat sizes. The descriptor is fstat'd
+        // immediately before reading and the reader independently enforces cap.
+        found.push({ path: canonical, root, id, size: -1 });
+      }
+    }
+  }
+  found.sort((a, b) => a.id.localeCompare(b.id));
+  // Cheap bounded admission accounting uses descriptor metadata, not stat(path).
+  for (const file of found) {
+    aborted(signal);
+    const handle = await openReadHandle(file.path);
+    try {
+      const info = await verifyOpenedTarget(file, handle);
+      if (!info.isFile()) continue;
+      if (info.size > MAX_FILE_BYTES) throw new ArchiveFailure('limit_exceeded', `Archive transcript exceeds the ${MAX_FILE_BYTES} byte limit`);
+      totalBytes += info.size;
+      if (totalBytes > MAX_TOTAL_BYTES) throw new ArchiveFailure('limit_exceeded', `Archive exceeds the ${MAX_TOTAL_BYTES} byte scan limit`);
+      file.size = info.size;
+    } finally { await handle.close(); }
+  }
+  return found.filter(file => file.size >= 0);
+}
+
+async function openReadHandle(path: string) {
+  try { return await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)); }
+  catch (error) { throw new ArchiveFailure('archive_io', (error as NodeJS.ErrnoException).code === 'ELOOP' ? 'Archive transcript changed to a symbolic link' : 'Unable to open an archive transcript'); }
+}
+
+async function readBounded(file: FileInfo, signal: AbortSignal, maxBytes = MAX_FILE_BYTES): Promise<Buffer> {
+  aborted(signal);
+  const handle = await openReadHandle(file.path);
+  try {
+    const info = await verifyOpenedTarget(file, handle);
+    if (info.size > MAX_FILE_BYTES) throw new ArchiveFailure('limit_exceeded', `Archive transcript exceeds the ${MAX_FILE_BYTES} byte limit`);
+    if (info.size > maxBytes) throw new ArchiveFailure('limit_exceeded', `Archive exceeds the ${MAX_TOTAL_BYTES} byte scan limit`);
+    totalLimitCheck(info.size);
+    const parts: Buffer[] = [];
+    let position = 0;
+    while (position < info.size) {
+      aborted(signal);
+      const buffer = Buffer.allocUnsafe(Math.min(READ_CHUNK, info.size - position));
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+      if (bytesRead === 0) break;
+      parts.push(bytesRead === buffer.length ? buffer : buffer.subarray(0, bytesRead));
+      position += bytesRead;
+      if (position > MAX_FILE_BYTES) throw new ArchiveFailure('limit_exceeded', `Archive transcript exceeds the ${MAX_FILE_BYTES} byte limit`);
+    }
+    aborted(signal);
+    const after = await handle.stat();
+    if (after.size > MAX_FILE_BYTES || after.size !== info.size || position !== info.size) {
+      throw new ArchiveFailure('limit_exceeded', `Archive transcript changed or exceeds the ${MAX_FILE_BYTES} byte limit`);
+    }
+    return Buffer.concat(parts, position);
+  } finally { await handle.close(); }
+}
+
+function totalLimitCheck(size: number) {
+  if (size > MAX_FILE_BYTES) throw new ArchiveFailure('limit_exceeded', `Archive transcript exceeds the ${MAX_FILE_BYTES} byte limit`);
+}
+
+function parse(bytes: Buffer, maxRecords = MAX_RECORDS): Parsed {
+  const records: Row[] = [];
+  const malformedLines: Array<{ line: number }> = [];
+  let lineStart = 0;
+  let lineNumber = 0;
+  let moreMalformedLines = false;
+  let encodedRecordsBytes = 0;
+  for (let end = 0; end <= bytes.length; end++) {
+    if (end !== bytes.length && bytes[end] !== 0x0a) continue;
+    lineNumber++;
+    let lineEnd = end;
+    if (lineEnd > lineStart && bytes[lineEnd - 1] === 0x0d) lineEnd--;
+    const line = bytes.toString('utf8', lineStart, lineEnd);
+    lineStart = end + 1;
+    if (!line.trim()) continue;
+    try {
+      const record = JSON.parse(line) as Row;
+      if (records.length >= maxRecords) throw new ArchiveFailure('limit_exceeded', `Archive transcript exceeds the ${maxRecords} record processing limit`);
+      // Account before retaining parsed objects; no full transcript stringify.
+      encodedRecordsBytes += Buffer.byteLength(JSON.stringify(record));
+      if (encodedRecordsBytes > MAX_FILE_BYTES) throw new ArchiveFailure('limit_exceeded', 'Archive transcript response exceeds the 4,000,000 character limit');
+      records.push(record);
+    } catch (error) {
+      if (error instanceof ArchiveFailure) throw error;
+      if (malformedLines.length < MAX_DIAGNOSTICS) malformedLines.push({ line: lineNumber });
+      else moreMalformedLines = true;
+    }
+  }
+  return { records, malformedLines, moreMalformedLines, recordsBytes: encodedRecordsBytes, recordCount: records.length };
+}
+
+async function itemFor(file: FileInfo, signal: AbortSignal, maxBytes: number, maxRecords: number): Promise<{ item: ArchiveItem; bytes: number; records: number }> {
+  const bytes = await readBounded(file, signal, maxBytes);
+  const transcript = parse(bytes, maxRecords);
+  const header = transcript.records.find(row => row?.type === 'session') ?? transcript.records[0] ?? {};
+  const messages = transcript.records.filter(row => row?.type === 'message');
+  const searchText = messages.map(row => JSON.stringify(row.message ?? row)).join('\n');
+  return { item: {
+    path: file.path, id: file.id, createdAt: header.timestamp ?? null,
+    messageCount: messages.length, malformedLines: transcript.malformedLines.slice(0, MAX_DIAGNOSTICS),
+    moreMalformedLines: transcript.moreMalformedLines, searchText,
+  }, bytes: bytes.length, records: transcript.recordCount };
+}
+
+function pageArgs(input: { offset?: number; limit?: number }) {
+  const offset = input.offset ?? 0;
+  const limit = input.limit ?? MAX_PAGE;
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > 1_000_000) throw new ArchiveFailure('invalid_request', 'Archive offset must be between 0 and 1000000');
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_PAGE) throw new ArchiveFailure('invalid_request', `Archive page limit must be between 1 and ${MAX_PAGE}`);
+  return { offset, limit };
+}
+
+function publicItems(items: ArchiveItem[], offset: number, limit: number, total: number) {
+  return {
+    items: items.slice(offset, offset + limit).map(item => ({
+      id: item.id, createdAt: item.createdAt, messageCount: item.messageCount,
+      malformedLines: item.malformedLines, moreMalformedLines: item.moreMalformedLines,
+      ...(item.excerpt ? { excerpt: item.excerpt.slice(0, 400) } : {}), archiveOnly: true,
+    })), total, offset, limit,
+  };
+}
+
+async function allItems(roots: string[], signal: AbortSignal) {
+  const indexed = await enumerate(roots, signal);
+  const items: ArchiveItem[] = [];
+  let bytesRead = 0;
+  let recordsRead = 0;
+  for (const file of indexed) {
+    aborted(signal);
+    const result = await itemFor(file, signal, MAX_TOTAL_BYTES - bytesRead, MAX_SCAN_RECORDS - recordsRead);
+    bytesRead += result.bytes;
+    recordsRead += result.records;
+    items.push(result.item);
+  }
+  return { indexed, items };
+}
+
+function failure(call: { error: (type: 'archive_error', message: string, data: { code: FailureCode }) => unknown }, error: unknown) {
+  const failure = error instanceof ArchiveFailure ? error : new ArchiveFailure('archive_io', 'Unable to read the configured archive');
+  return call.error('archive_error', failure.message, { code: failure.code });
+}
+
+/** Registers a read-only view of host-configured legacy transcript roots. */
+export async function registerArchive(ctx: Context, options: Options = {}) {
+  const roots = await rootsFrom(options);
+  return ctx.rpc.register(Archive, {
+    list: async (input, call) => {
+      try {
+        aborted(call.signal);
+        const { offset, limit } = pageArgs(input as { offset?: number; limit?: number });
+        const { items } = await allItems(roots, call.signal);
+        aborted(call.signal);
+        return publicItems(items, offset, limit, items.length);
+      } catch (error) { if (call.signal.aborted) throw error; return failure(call, error); }
+    },
+    search: async (input, call) => {
+      try {
+        aborted(call.signal);
+        const { query, ...paging } = input as { query: string; offset?: number; limit?: number };
+        if (!query.trim() || query.length > 200) throw new ArchiveFailure('invalid_request', 'Archive search query must contain 1 to 200 characters');
+        const { offset, limit } = pageArgs(paging);
+        const { items } = await allItems(roots, call.signal);
+        const needle = query.toLocaleLowerCase();
+        const matches = items.flatMap(item => {
+          const index = item.searchText.toLocaleLowerCase().indexOf(needle);
+          return index < 0 ? [] : [{ ...item, excerpt: item.searchText.slice(Math.max(0, index - 120), index + needle.length + 180) }];
+        });
+        aborted(call.signal);
+        return publicItems(matches, offset, limit, matches.length);
+      } catch (error) { if (call.signal.aborted) throw error; return failure(call, error); }
+    },
+    read: async (input, call) => {
+      try {
+        aborted(call.signal);
+        const { id } = input as { id: string };
+        const file = (await enumerate(roots, call.signal)).find(candidate => candidate.id === id);
+        if (!file) throw new ArchiveFailure('not_found', 'Archive transcript ID was not found in configured roots');
+        const transcript = parse(await readBounded(file, call.signal));
+        if (transcript.recordsBytes > MAX_FILE_BYTES) throw new ArchiveFailure('limit_exceeded', 'Archive transcript response exceeds the 4,000,000 character limit');
+        aborted(call.signal);
+        return { id, records: transcript.records, malformedLines: transcript.malformedLines, moreMalformedLines: transcript.moreMalformedLines, archiveOnly: true };
+      } catch (error) { if (call.signal.aborted) throw error; return failure(call, error); }
+    },
+    export: async (input, call) => {
+      try {
+        aborted(call.signal);
+        const { id, format = 'json' } = input as { id: string; format?: 'json' | 'jsonl' };
+        if (format !== 'json' && format !== 'jsonl') throw new ArchiveFailure('invalid_request', 'Export format must be json or jsonl');
+        const file = (await enumerate(roots, call.signal)).find(candidate => candidate.id === id);
+        if (!file) throw new ArchiveFailure('not_found', 'Archive transcript ID was not found in configured roots');
+        const bytes = await readBounded(file, call.signal);
+        const parsed = format === 'json' ? parse(bytes) : undefined;
+        if (parsed && parsed.recordsBytes + parsed.records.length + 2 > MAX_FILE_BYTES) {
+          throw new ArchiveFailure('limit_exceeded', 'Archive JSON export exceeds the 4,000,000 byte response limit');
+        }
+        const content = format === 'jsonl' ? bytes.toString('utf8') : `${JSON.stringify(parsed!.records)}\n`;
+        if (Buffer.byteLength(content) > MAX_FILE_BYTES) throw new ArchiveFailure('limit_exceeded', 'Archive export exceeds the 4,000,000 byte response limit');
+        aborted(call.signal);
+        return { id, format, content, archiveOnly: true };
+      } catch (error) { if (call.signal.aborted) throw error; return failure(call, error); }
+    },
+  });
+}

package/plugins/carthagent/src/server/budgets.ts

@@ -0,0 +1,21 @@
+import { budgetLimits, newBudget, budgetReason, budgetSnapshot } from "../../../../lib/budget.mjs"
+
+export type Budget = ReturnType<typeof newBudget>
+
+export function readBudgetLimits(options: Record<string, unknown>) {
+  return budgetLimits((name: string) => options[name] ?? "0")
+}
+
+export function budgetForSession(saved: Budget | undefined, limits: ReturnType<typeof budgetLimits>) {
+  return saved ? structuredClone(saved) : newBudget(limits)
+}
+
+export function checkBudget(budget: Budget, action?: "tool" | "repair", now = Date.now()) {
+  const reason = budgetReason(budget, action, now)
+  if (reason) return reason
+  if (action === "tool") budget.tools++
+  if (action === "repair") budget.repairs++
+  return null
+}
+
+export { budgetSnapshot }