reploid 0.0.0-stage → 0.1.1

package/server/native-whole-model-fill.js

@@ -0,0 +1,182 @@
+/** Fills a whole-model directory from verified pieces so one machine can hold the complete
+ * model. Every piece is checked against the pinned piece index, every assembled file against
+ * its pinned whole-file hash (the manifest's shard hash or the catalog's file hash), and a
+ * file appears under its final name only after that check (temporary `.partial` + rename).
+ * An interrupted fill resumes: pieces already written and still matching their identity are
+ * reused. The manifest is written last, so a directory with a matching manifest was either
+ * placed by its owner or completed here. Where the bytes come from is the caller's port. */
+import fs from 'node:fs/promises';
+import { constants, createReadStream } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+const assert = (ok, message, code) => { if (!ok) throw Object.assign(new Error(message), code ? { code } : {}); };
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+const plainName = name => typeof name === 'string' && /^[A-Za-z0-9_.-]+$/.test(name) && !/^\.\.?$/.test(name);
+const isMetadataSource = file => plainName(file.path) && file.role !== 'model-piece-index';
+
+async function regularSize(filename) {
+  try { const info = await fs.lstat(filename); return info.isFile() ? info.size : -1; }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function hashFile(filename, signal) {
+  const digest = createHash('sha256');
+  for await (const chunk of createReadStream(filename, { signal })) digest.update(chunk);
+  return digest.digest('hex');
+}
+
+/** True when the directory already holds the catalog manifest and every file it needs at its
+ * pinned size. Reads only the local manifest, so an owner-provided directory never needs peers. */
+export async function wholeModelDirectoryComplete(root, model) {
+  let manifestBytes;
+  try { manifestBytes = await fs.readFile(path.join(root, 'manifest.json')); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  if ('sha256:' + sha256(manifestBytes) !== model.identity) return false;
+  const manifest = JSON.parse(manifestBytes.toString('utf8'));
+  const required = [...(manifest.shards || []).map(shard => ({ path: shard.filename, size: shard.size })),
+    ...(model.source?.files || []).filter(file => isMetadataSource(file) && file.path !== 'manifest.json')
+      .map(file => ({ path: file.path, size: file.sizeBytes }))];
+  for (const file of required) if (await regularSize(path.join(root, file.path)) !== file.size) return false;
+  return true;
+}
+
+/** The files a complete directory holds: every file of the piece index with its pinned whole
+ * hash, then catalog metadata outside the index, the manifest last. */
+export function wholeModelFillPlan({ model, manifest, index }) {
+  assert(manifest.hashAlgorithm === 'sha256', 'Whole-model fill requires SHA-256 shard hashes');
+  const pinned = new Map((model.source?.files || []).map(file => [file.path, file]));
+  const assembled = index.files.map(file => {
+    assert(plainName(file.path), 'Piece index names a file outside the model directory: ' + file.path);
+    const shard = manifest.shards.find(row => row.filename === file.path), source = pinned.get(file.path);
+    const hash = shard ? shard.hash : source?.hashAlgorithm === 'sha256' ? source.hash : null;
+    assert(/^[a-f0-9]{64}$/.test(hash || ''), 'Piece index names an unpinned file: ' + file.path);
+    assert(file.size === (shard ? shard.size : source.sizeBytes), 'Piece index size differs from the pinned file: ' + file.path);
+    let offset = 0;
+    for (const piece of file.pieces) { assert(piece.offset === offset && piece.size > 0, 'Pieces do not cover ' + file.path); offset += piece.size; }
+    assert(offset === file.size, 'Pieces do not cover ' + file.path);
+    return { path: file.path, size: file.size, hash, pieces: file.pieces };
+  });
+  for (const shard of manifest.shards) assert(assembled.some(file => file.path === shard.filename), 'Piece index omits shard ' + shard.filename);
+  const metadata = (model.source?.files || []).filter(file => isMetadataSource(file) && !assembled.some(row => row.path === file.path))
+    .sort((a, b) => (a.path === 'manifest.json') - (b.path === 'manifest.json'));
+  assert(metadata.at(-1)?.path === 'manifest.json', 'Catalog source files must pin manifest.json');
+  return { assembled, metadata };
+}
+
+async function writeAtomically(root, name, bytes, signal) {
+  const temporary = path.join(root, name + '.' + crypto.randomUUID() + '.tmp');
+  let handle;
+  try {
+    handle = await fs.open(temporary, 'wx', 0o600); await handle.writeFile(bytes); await handle.sync(); await handle.close(); handle = null;
+    signal?.throwIfAborted(); await fs.rename(temporary, path.join(root, name));
+  } finally { await handle?.close(); await fs.unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+}
+
+async function readRange(handle, offset, size) {
+  const bytes = new Uint8Array(size); let received = 0;
+  while (received < size) {
+    const part = await handle.read(bytes, received, size - received, offset + received);
+    if (part.bytesRead === 0) return null;
+    received += part.bytesRead;
+  }
+  return bytes;
+}
+
+async function syncDirectory(root) {
+  let handle;
+  try { handle = await fs.open(root, constants.O_RDONLY); await handle.sync(); }
+  catch (error) { if (!['EISDIR', 'EINVAL', 'EPERM', 'EBADF'].includes(error.code)) throw error; }
+  finally { await handle?.close(); }
+}
+
+/**
+ * `acquire(piece, {signal})` returns a piece's bytes, or `{bytes, source}` naming the source,
+ * from an authorized source; they are verified here regardless. `readMetadata(file, signal)` returns a pinned catalog file.
+ * `release(file)` lets the caller drop duplicate piece copies once `file` is in place.
+ * `freeBytes(root)` reports writable space. `onProgress` receives `start`, `piece`, `file`
+ * and `complete` events with cumulative counts.
+ */
+export async function fillWholeModelDirectory({ root, model, manifest, index, acquire, readMetadata,
+  release = async () => {}, freeBytes, concurrency = 1, signal = AbortSignal.timeout(2 ** 31 - 1), onProgress = () => {} }) {
+  assert(Number.isSafeInteger(concurrency) && concurrency > 0, 'Explicit fill concurrency required');
+  const started = Date.now(), plan = wholeModelFillPlan({ model, manifest, index });
+  // Never overwrite a directory that holds another model.
+  try {
+    const present = await fs.readFile(path.join(root, 'manifest.json'));
+    assert('sha256:' + sha256(present) === model.identity, 'Model directory holds a different manifest', 'WHOLE_MODEL_DIRECTORY_CONFLICT');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  // A file already under its final name is used only after its whole hash matches; one that
+  // does not becomes the partial file, so its matching pieces are still reused.
+  const missing = [];
+  for (const file of plan.assembled) {
+    const filename = path.join(root, file.path);
+    if (await regularSize(filename) === file.size && await hashFile(filename, signal) === file.hash) continue;
+    if (await regularSize(filename) !== null) await fs.rename(filename, filename + '.partial');
+    missing.push(file);
+  }
+  const metadata = [];
+  for (const file of plan.metadata) {
+    const filename = path.join(root, file.path);
+    if (file.path !== 'manifest.json' && await regularSize(filename) === file.sizeBytes && await hashFile(filename, signal) === file.hash) continue;
+    metadata.push(file);
+  }
+  const totals = { files: missing.length + metadata.length, pieces: missing.reduce((sum, file) => sum + file.pieces.length, 0),
+    bytes: missing.reduce((sum, file) => sum + file.size, 0) + metadata.reduce((sum, file) => sum + file.sizeBytes, 0) };
+  const progress = { fetchedPieces: 0, fetchedBytes: 0, reusedPieces: 0, reusedBytes: 0, completedFiles: 0, sources: {} };
+  const count = (source, bytes) => { const row = progress.sources[source] ||= { pieces: 0, bytes: 0 }; row.pieces++; row.bytes += bytes; };
+  const emit = (phase, extra = {}) => onProgress(structuredClone({ phase, ...totals, ...progress, elapsedMs: Date.now() - started, ...extra }));
+  const available = await freeBytes(root);
+  assert(available >= totals.bytes, `Model directory needs ${totals.bytes} bytes; ${available} are free`, 'WHOLE_MODEL_STORAGE');
+  emit('start');
+  for (const file of missing) {
+    signal.throwIfAborted();
+    const partial = path.join(root, file.path + '.partial');
+    const handle = await fs.open(partial, constants.O_RDWR | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    try {
+      const info = await handle.stat(); assert(info.isFile(), 'Partial model file must be a regular file');
+      if (info.size > file.size) await handle.truncate(file.size);
+      const queue = file.pieces.slice();
+      const worker = async () => {
+        for (let piece = queue.shift(); piece; piece = queue.shift()) {
+          signal.throwIfAborted();
+          const present = await readRange(handle, piece.offset, piece.size);
+          if (present && 'sha256:' + sha256(present) === piece.identity) {
+            progress.reusedPieces++; progress.reusedBytes += piece.size; count('partial-file', piece.size);
+            emit('piece', { path: file.path, reused: true, source: 'partial-file' }); continue;
+          }
+          const acquired = await acquire({ ...piece, path: file.path }, { signal });
+          const bytes = acquired instanceof Uint8Array ? acquired : acquired?.bytes;
+          const source = acquired instanceof Uint8Array ? 'acquired' : String(acquired?.source || 'acquired');
+          signal.throwIfAborted();
+          assert(bytes instanceof Uint8Array && bytes.byteLength === piece.size && 'sha256:' + sha256(bytes) === piece.identity,
+            `Rejected unverified bytes for piece ${piece.identity} of ${file.path}`, 'WHOLE_MODEL_PIECE_REJECTED');
+          let written = 0;
+          while (written < bytes.byteLength) written += (await handle.write(bytes, written, bytes.byteLength - written, piece.offset + written)).bytesWritten;
+          progress.fetchedPieces++; progress.fetchedBytes += piece.size; count(source, piece.size);
+          emit('piece', { path: file.path, reused: false, source });
+        }
+      };
+      await Promise.all(Array.from({ length: Math.min(concurrency, file.pieces.length) }, worker));
+      await handle.sync();
+    } finally { await handle.close(); }
+    const actual = await hashFile(partial, signal);
+    if (actual !== file.hash) {
+      await fs.unlink(partial);
+      assert(false, `Assembled ${file.path} differs from its pinned hash`, 'WHOLE_MODEL_FILE_REJECTED');
+    }
+    await fs.rename(partial, path.join(root, file.path)); await syncDirectory(root);
+    progress.completedFiles++; emit('file', { path: file.path });
+    await release(file);
+  }
+  for (const file of metadata) {
+    const read = await readMetadata(file, signal);
+    const bytes = read instanceof Uint8Array ? read : read?.bytes;
+    assert(bytes instanceof Uint8Array && bytes.byteLength === file.sizeBytes && sha256(bytes) === file.hash,
+      'Rejected unverified bytes for ' + file.path, 'WHOLE_MODEL_FILE_REJECTED');
+    await writeAtomically(root, file.path, bytes, signal); await syncDirectory(root);
+    progress.completedFiles++; emit('file', { path: file.path, ...(read instanceof Uint8Array ? {} : { source: read?.source }) });
+  }
+  emit('complete');
+  return { ...totals, ...progress, elapsedMs: Date.now() - started };
+}

package/server/native-whole-model.js

@@ -0,0 +1,130 @@
+/** Native whole-model contribution uses the same scoped provider as browser chat. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { sha256Digest } from './hashing.js';
+import { createReploidDopplerRuntimeService } from '../shared/infrastructure/doppler-runtime-service.js';
+import { createWorkResidentProvider } from '../apps/poolday/providers/work-resident-provider.js';
+import { createWorkAdapterResolver, selectWorkAdapters } from '../apps/poolday/providers/work-adapter.js';
+import profile from '../apps/poolday/config/work-profile.json' with { type: 'json' };
+import { resolvePartitionGeneration } from '../apps/poolday/config/partition-generation.js';
+
+/** `fill({signal})`, when given, completes the model directory from verified peer pieces before
+ * the manifest is read (server/native-model-files.js fillWholeModel); stop aborts it. */
+export function createNativeWholeModel({ model, modelDirectory, nativeGpu, owner = null, onChange = () => {}, fill = null,
+  configureMemory = async maxBytes => (await import('doppler-gpu/partitions')).configureDeviceMemoryBudget({ maxBytes }),
+  resolveAdapter = createWorkAdapterResolver({ models: [model] }),
+  service = createReploidDopplerRuntimeService({ loadModule: () => import('doppler-gpu/compat') }),
+  createResident = createWorkResidentProvider }) {
+  model = structuredClone(model);
+  model.adapters = selectWorkAdapters(model);
+  let resident = null, preparing = null, stopping = null, closed = false, enabled = false, filling = null;
+  const ownerAllows = () => {
+    const decision = owner?.decide();
+    return !decision || decision.action === 'admit'
+      || decision.action === 'reduce' && decision.limits.maxConcurrentAttempts > 0;
+  };
+  const getState = () => {
+    const state = resident?.getState() || { phase: filling ? 'acquiring-model' : 'idle', ready: false };
+    return { ...state, mode: 'whole-model', offering: enabled,
+      ready: enabled && !closed && ownerAllows() && state.ready,
+      modelId: model.id, modelIdentity: state.modelIdentity ?? null };
+  };
+  const notify = () => onChange(getState());
+  const stop = () => stopping ||= (async () => {
+    enabled = false; filling?.abort(new Error('Whole-model contribution stopped')); notify();
+    await resident?.close();
+    await preparing?.catch(() => {});
+    resident = null; notify();
+  })().finally(() => { stopping = null; });
+  return Object.freeze({
+    getState,
+    getExecutionState() {
+      const state = getState();
+      return { ...state,
+        // Prepared capacity remains discoverable while its current slot is
+        // occupied. The mesh separately advertises the available slot count.
+        phase: state.ready ? 'ready' : ['ready', 'executing'].includes(state.phase) ? 'idle' : state.phase,
+        activity: { phase: state.phase, completed: state.completed || 0, error: state.error || null }
+      };
+    },
+    async contribute(approved) {
+      if (approved !== true) throw new Error('Approve contribution before loading a whole model');
+      if (closed || stopping) throw new Error('Whole-model contributor is stopping');
+      if (preparing) return preparing;
+      if (resident) return getState();
+      enabled = true;
+      preparing = (async () => {
+        if (fill) {
+          const controller = new AbortController(); filling = controller; notify();
+          try { await fill({ signal: controller.signal }); }
+          finally { if (filling === controller) filling = null; }
+          if (!enabled || closed) throw new Error('Whole-model contribution stopped');
+        }
+        const root = await fs.realpath(modelDirectory);
+        const manifestPath = await fs.realpath(path.join(root, 'manifest.json'));
+        if (!manifestPath.startsWith(root + path.sep)) throw new Error('Native whole-model manifest escapes approved directory');
+        const manifest = await fs.readFile(manifestPath);
+        if (sha256Digest(manifest) !== model.identity) {
+          throw new Error('Native whole-model manifest differs from the catalog');
+        }
+        if (!enabled || closed) throw new Error('Whole-model contribution stopped');
+        await nativeGpu();
+        if (!enabled || closed) throw new Error('Whole-model contribution stopped');
+        const loadOptions = structuredClone(model.loadOptions || {});
+        const budget = loadOptions.runtimeConfig?.shared?.bufferPool?.budget;
+        const maximum = owner?.gpuBufferBytes(budget?.maxTotalBytes ?? Infinity);
+        if (Number.isFinite(maximum)) {
+          // The pool limit alone excludes some persistent weight/state allocations.
+          await configureMemory(maximum);
+          loadOptions.runtimeConfig ??= {};
+          loadOptions.runtimeConfig.shared ??= {};
+          loadOptions.runtimeConfig.shared.bufferPool ??= {};
+          loadOptions.runtimeConfig.shared.bufferPool.budget ??= {};
+          loadOptions.runtimeConfig.shared.bufferPool.budget.maxTotalBytes = maximum;
+          loadOptions.runtimeConfig.inference ??= {};
+          loadOptions.runtimeConfig.inference.session ??= {};
+          loadOptions.runtimeConfig.inference.session.prefillChunkSubmitMode ??= 'sync';
+        }
+        // A catalog model without explicit generation runs whole with its partition route's
+        // policy: the same output budget and a KV cache sized to that policy's context. The work
+        // profile alone left the runtime's default context no larger than its output budget.
+        const generation = model.generation || resolvePartitionGeneration(model);
+        if (!model.generation) {
+          loadOptions.runtimeConfig ??= {};
+          loadOptions.runtimeConfig.inference ??= {};
+          loadOptions.runtimeConfig.inference.session ??= {};
+          loadOptions.runtimeConfig.inference.session.kvcache ??= {};
+          loadOptions.runtimeConfig.inference.session.kvcache.maxSeqLen ??= generation.maxSeqLen;
+        }
+        resident = createResident({ service, model, resolveAdapter, generation,
+          maxOutcomeCharacters: profile.maxOutcomeCharacters, loadOptions,
+          source: { manifest: JSON.parse(manifest.toString('utf8')), manifestText: manifest.toString('utf8'),
+            manifestHash: model.identity.slice(7), baseUrl: pathToFileURL(root + path.sep).href }, onChange: notify });
+        await resident.prepare();
+        return getState();
+      })().catch(async error => {
+        enabled = false;
+        await resident?.close(); resident = null; notify(); throw error;
+      }).finally(() => { preparing = null; });
+      return preparing;
+    },
+    generate(messages, onUpdate, controls) {
+      if (!getState().ready) throw Object.assign(new Error('Whole-model capacity unavailable'), { code: 'CAPACITY_UNAVAILABLE' });
+      const identities = controls.adapterIdentities || [];
+      if (!Array.isArray(identities) || identities.length > 1) throw new Error('Select at most one prepared adapter');
+      const adapters = identities.map(identity => {
+        const selected = model.adapters?.find(adapter => adapter.identity === identity);
+        if (!selected || !getState().adapterIdentities?.includes(identity)) {
+          throw new Error('Requested adapter is not prepared on this contributor');
+        }
+        return structuredClone(selected);
+      });
+      const ownerPolicyDigest = owner?.digest ?? null;
+      return Promise.resolve(resident.generate(messages, onUpdate, { ...controls, adapters }))
+        .then(result => ({ ...result, ownerPolicyDigest }));
+    },
+    stop,
+    async close() { closed = true; await stop(); }
+  });
+}

package/server/public-web-worker.js

@@ -0,0 +1,66 @@
+/** Native contributor result grants and cookie-free public page extraction.
+ * Only URLs returned by this worker's search can be extracted, by the same requester and query.
+ * The guarded reader checks DNS/redirects and bounds compressed and decoded bytes. */
+import { createPageFetcher } from './search/page-fetch.js';
+import { extractDocumentText, selectPassage, sha256Text } from '../packages/reploid/src/retrieval/index.js';
+import policy from '../packages/reploid/src/mesh/web-access-policy.json' with { type: 'json' };
+
+const requireValue = (ok, message) => { if (!ok) throw new Error(message); };
+const text = value => extractDocumentText({ body: new TextEncoder().encode(value), contentType: 'text/html' }).text;
+const field = (item, key) => text(item.match(new RegExp(`<${key}>([\\s\\S]*?)</${key}>`, 'i'))?.[1] || '');
+
+export function createPublicWebWorker({
+  searchFetch = createPageFetcher({ allowedTypes: ['text/xml', 'application/rss+xml'], maxBytes: 256000 }).fetchPage,
+  pageFetch = createPageFetcher().fetchPage, now = Date.now, service = 'bing', searchResults = null
+} = {}) {
+  const grants = new Map();
+  const prune = () => { for (const [token, grant] of grants) if (grant.expiresAt <= now()) grants.delete(token); };
+  const queryValid = query => typeof query === 'string' && query.trim() && query.length <= policy.maxQueryCharacters;
+  return Object.freeze({ service, version: '1',
+    async search({ query, maxResults }, { signal, requester }) {
+      requireValue(queryValid(query) && Number.isInteger(maxResults) && maxResults > 0 && maxResults <= policy.maxResults, 'Invalid search limits');
+      prune(); requireValue(grants.size + maxResults <= policy.maxSeen, 'Search result capacity reached');
+      let rows;
+      if (searchResults) rows = await searchResults({ query, maxResults, signal });
+      else {
+        const url = new URL('https://www.bing.com/search'); url.searchParams.set('format', 'rss'); url.searchParams.set('q', query);
+        const page = await searchFetch(url.href, { signal }); signal?.throwIfAborted();
+        const xml = new TextDecoder().decode(page.body);
+        requireValue(page.status === 200 && /<rss[\s>]/i.test(xml) && !/<!DOCTYPE|<!ENTITY/i.test(xml), 'Search did not return results');
+        rows = [...xml.matchAll(/<item>([\s\S]*?)<\/item>/gi)].map(item => ({
+          url: field(item[1], 'link'), title: field(item[1], 'title'), excerpt: field(item[1], 'description')
+        }));
+      }
+      signal?.throwIfAborted(); prune();
+      requireValue(grants.size + maxResults <= policy.maxSeen, 'Search result capacity reached');
+      const results = [];
+      for (const row of rows) {
+        if (results.length >= maxResults) break;
+        let target;
+        try { target = new URL(row.url); } catch { continue; }
+        if (!['https:', 'http:'].includes(target.protocol) || target.username || target.password) continue;
+        const token = crypto.randomUUID(), sourceId = `web-${results.length + 1}`;
+        grants.set(token, { requester, query, url: target.href, sourceId, expiresAt: now() + policy.resultTtlMs });
+        const excerpt = String(row.excerpt || row.title || '').slice(0, 1500);
+        results.push({ sourceId, url: target.href, title: String(row.title || '').slice(0, 1000),
+          excerpt, contentHash: await sha256Text(excerpt), retrievedAt: now(), fetchToken: token });
+      }
+      return { results, usage: { provider: `contributor-${service}`, requests: 1, costMicroUsd: null } };
+    },
+    async extract({ source, query, maxCharacters }, { signal, requester }) {
+      prune();
+      const grant = grants.get(source?.fetchToken);
+      requireValue(grant && grant.requester === requester && grant.query === query && grant.url === source.url
+        && grant.sourceId === source.sourceId, 'Page is not an authorized search result');
+      requireValue(Number.isInteger(maxCharacters) && maxCharacters > 0 && maxCharacters <= policy.maxSourceCharacters, 'Invalid passage limit');
+      const page = await pageFetch(grant.url, { signal }); signal?.throwIfAborted();
+      const document = extractDocumentText({ body: page.body, contentType: page.contentType });
+      const passage = selectPassage({ text: document.text, query, maxCharacters });
+      requireValue(passage.text.trim(), 'Page has no extractable text');
+      const sha256 = await sha256Text(document.text);
+      return { sourceId: grant.sourceId, url: page.url, title: document.title.slice(0, 1000), text: passage.text,
+        retrievedAt: now(), contentHash: sha256, document: { url: page.url, status: page.status, contentType: page.contentType,
+          characters: document.text.length, sha256, start: passage.start, end: passage.end, bytes: page.body.byteLength }, costMicroUsd: null };
+    }
+  });
+}

package/server/responses.js

@@ -0,0 +1,92 @@
+/** Stateless text Responses protocol. No response store, continuation lookup or tools. */
+import { randomUUID } from 'node:crypto';
+import { parseTextChatCompletion } from './chat-completions.js';
+import { createTextRequester, fail, object, freeze } from './text-requester.js';
+import policy from '../apps/poolday/config/partition-policy.json' with { type: 'json' };
+import { parseRequesterBinding } from './text-request-options.js';
+
+export function parseTextResponse(body) {
+  if (!object(body)) throw fail(400, 'A JSON object is required');
+  for (const key of Object.keys(body)) if (!['model', 'input', 'instructions', 'store', 'stream', 'max_output_tokens', 'text', 'reploid'].includes(key)) throw fail(400, `Unsupported parameter: ${key}`, key);
+  if (body.store !== false) throw fail(400, 'Stateless Responses requires explicit store:false', 'store');
+  if (body.instructions !== undefined && body.instructions !== null && typeof body.instructions !== 'string') throw fail(400, 'instructions must be text', 'instructions');
+  if (body.max_output_tokens !== undefined && (!Number.isSafeInteger(body.max_output_tokens)
+    || body.max_output_tokens <= 0 || body.max_output_tokens > policy.limits.maxTokens)) {
+    throw fail(400, 'max_output_tokens must fit the prepared route budget', 'max_output_tokens');
+  }
+  const jsonObject = body.text !== undefined;
+  if (jsonObject && (!object(body.text) || Object.keys(body.text).join() !== 'format'
+    || !object(body.text.format) || Object.keys(body.text.format).join() !== 'type' || body.text.format.type !== 'json_object')) {
+    throw fail(400, 'Only text.format.type json_object is supported', 'text');
+  }
+  let messages;
+  if (typeof body.input === 'string') messages = [{ role: 'user', content: body.input }];
+  else if (Array.isArray(body.input) && body.input.length > 0 && body.input.length <= 128) messages = body.input.map((value, index) => {
+    if (!object(value) || Object.keys(value).some(key => !['type', 'role', 'content'].includes(key))
+      || value.type !== undefined && value.type !== 'message') throw fail(400, 'Only text message inputs are supported', `input[${index}]`);
+    return { role: value.role, content: value.content };
+  });
+  else throw fail(400, 'Text input or text messages required', 'input');
+  if (typeof body.instructions === 'string') messages.unshift({ role: 'system', content: body.instructions });
+  if (jsonObject) messages.unshift({ role: 'system', content: 'Return exactly one valid JSON object. No markdown fences or commentary.' });
+  const parsed = parseTextChatCompletion({ model: body.model, messages, stream: body.stream });
+  return freeze({ ...parsed, instructions: body.instructions ?? null, jsonObject,
+    ...(body.max_output_tokens === undefined ? {} : { generationRequest: {
+      schema: 'reploid.partition-generation-request/v1', maxOutputTokens: body.max_output_tokens, usage: 'raw-model-tokens/v1',
+    } }), ...(body.reploid === undefined ? {} : { reploid: parseRequesterBinding(body.reploid) }) });
+}
+
+export function createResponses(options) {
+  return createTextRequester(options, { path: '/v1/responses', idPrefix: 'resp_', parse: parseTextResponse,
+    output({ id, created, model, input, write, end, json }) {
+      const itemId = 'msg_' + randomUUID().replaceAll('-', '');
+      let started = false, sequence = 0, observedUsage;
+      const part = text => ({ type: 'output_text', text, annotations: [], logprobs: [] });
+      const item = (text, status) => ({ id: itemId, type: 'message', role: 'assistant', status, content: [part(text)] });
+      const response = (status, output = []) => ({ id, object: 'response', created_at: created, model, status,
+        store: false, background: false, error: null, incomplete_details: status === 'incomplete' ? { reason: 'max_output_tokens' } : null,
+        instructions: input.instructions, output, tools: [], tool_choice: 'none', parallel_tool_calls: false,
+        temperature: null, top_p: null, metadata: null, access_programs: null, previous_response_id: null,
+        text: { format: { type: input.jsonObject ? 'json_object' : 'text' } },
+        ...(observedUsage ? { usage: { input_tokens: observedUsage.inputTokens, output_tokens: observedUsage.outputTokens,
+          total_tokens: observedUsage.inputTokens + observedUsage.outputTokens } } : {}) });
+      const frame = (type, value) => `event: ${type}\ndata: ${JSON.stringify({ ...value, type, sequence_number: sequence++ })}\n\n`;
+      const event = (type, value) => write(frame(type, value));
+      const position = { item_id: itemId, output_index: 0, content_index: 0 };
+      const start = () => {
+        if (started) return; started = true;
+        event('response.created', { response: response('in_progress') });
+        event('response.in_progress', { response: response('in_progress') });
+        event('response.output_item.added', { output_index: 0, item: { ...item('', 'in_progress'), content: [] } });
+        event('response.content_part.added', { ...position, part: part('') });
+      };
+      return {
+        usage(value) { observedUsage = value; },
+        delta(text) { start(); event('response.output_text.delta', { ...position, delta: text, logprobs: [] }); },
+        complete(content, finishReason, reason, usage, evidence) {
+          // The Responses incomplete enum has no context-limit member. Do not
+          // rename a context limit to an output-token budget or successful stop.
+          if (reason === 'context-limit') throw fail(502, 'Requester stopped at its context limit');
+          if (input.jsonObject) {
+            let parsed;
+            try { parsed = JSON.parse(content); } catch { throw fail(502, 'Requester did not return a JSON object'); }
+            if (!object(parsed)) throw fail(502, 'Requester did not return a JSON object');
+          }
+          observedUsage = usage;
+          const status = finishReason === 'length' ? 'incomplete' : 'completed';
+          const finalItem = item(content, status), final = response(status, [finalItem]);
+          if (evidence) final.reploid = evidence;
+          final.completed_at = status === 'completed' ? Math.floor(Date.now() / 1000) : null;
+          if (!input.stream) { json(final); return; }
+          start();
+          event('response.output_text.done', { ...position, text: content, logprobs: [] });
+          event('response.content_part.done', { ...position, part: part(content) });
+          event('response.output_item.done', { output_index: 0, item: finalItem });
+          event(status === 'completed' ? 'response.completed' : 'response.incomplete', { response: final });
+          end();
+        },
+        error(error) { end(frame('error', { code: 'server_error', message: String(error.message).slice(0, 1024), param: error.param })); }
+      };
+    }
+  });
+}

package/server/search/errors.js

@@ -0,0 +1,47 @@
+/** Typed failures for search providers and page fetches. Codes are the contract; messages are for people. */
+class SearchFailure extends Error {
+  constructor(code, { status = null, retryAfterSeconds = null, detail = null, usage = null } = {}, message = code) {
+    super(detail ? `${message}: ${detail}` : message);
+    this.code = code; this.status = status; this.retryAfterSeconds = retryAfterSeconds; this.detail = detail;
+    if (usage) this.usage = usage;
+  }
+}
+
+export class SearchProviderError extends SearchFailure {
+  constructor(code, details = {}) { super(code, details, `Search provider failed (${code})`); this.name = 'SearchProviderError'; }
+}
+
+export class PageFetchError extends SearchFailure {
+  constructor(code, details = {}) { super(code, details, `Page fetch failed (${code})`); this.name = 'PageFetchError'; }
+}
+
+/** Waits `ms` unless `signal` aborts first. */
+export const sleep = (ms, signal = null) => new Promise((resolve, reject) => {
+  if (signal?.aborted) { reject(signal.reason); return; }
+  const timer = setTimeout(() => { signal?.removeEventListener('abort', stop); resolve(); }, ms);
+  const stop = () => { clearTimeout(timer); reject(signal.reason); };
+  signal?.addEventListener('abort', stop, { once: true });
+});
+
+/** Maps a caller abort to timeout or cancellation. */
+export function abortCode(signal) {
+  const reason = signal?.reason;
+  return reason?.name === 'TimeoutError' || reason?.code === 'timeout' ? 'timeout' : 'cancelled';
+}
+
+/** Reads at most `limit` bytes of a fetch Response body. */
+export async function readBounded(response, limit, fail) {
+  const declared = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > limit) { await response.body?.cancel().catch(() => {}); throw fail(); }
+  if (!response.body) return '';
+  const reader = response.body.getReader(), chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > limit) { await reader.cancel().catch(() => {}); throw fail(); }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks.map(chunk => Buffer.from(chunk))).toString('utf8');
+}