@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/src/knowledge/service/grpc-codec.js

@@ -0,0 +1,237 @@
+import grpc from '@grpc/grpc-js';
+import { createRequire } from 'node:module';
+import {
+  ERROR_CODE,
+  ERROR_REASON,
+  canonicalCodeFromHttpStatus,
+  createErrorEnvelope,
+  defaultHttpStatusForCode,
+  grpcStatusForCode,
+} from '../../errors/contract.js';
+
+const require = createRequire(import.meta.url);
+const knowledgePb = require('../../rpc/generated/knowledge_pb.js');
+const errorsPb = require('../../rpc/generated/errors_pb.js');
+const { KnowledgeServiceService, KnowledgeServiceClient } = require('../../rpc/generated/knowledge_grpc_pb.js');
+const { Timestamp } = require('google-protobuf/google/protobuf/timestamp_pb.js');
+
+const operationToProto = {
+  index: knowledgePb.JobOperation.JOB_OPERATION_INDEX,
+  plan: knowledgePb.JobOperation.JOB_OPERATION_PLAN,
+  search: knowledgePb.JobOperation.JOB_OPERATION_SEARCH,
+};
+const operationFromProto = new Map(Object.entries(operationToProto).map(([key, value]) => [value, key]));
+const statusToProto = {
+  queued: knowledgePb.JobStatus.JOB_STATUS_QUEUED,
+  running: knowledgePb.JobStatus.JOB_STATUS_RUNNING,
+  completed: knowledgePb.JobStatus.JOB_STATUS_COMPLETED,
+  failed: knowledgePb.JobStatus.JOB_STATUS_FAILED,
+};
+const statusFromProto = new Map(Object.entries(statusToProto).map(([key, value]) => [value, key]));
+const protoErrorCode = code => errorsPb.ErrorCode[`ERROR_CODE_${code}`] ?? errorsPb.ErrorCode.ERROR_CODE_UNKNOWN;
+const errorCodeNames = new Map(Object.entries(errorsPb.ErrorCode).map(([key, value]) => [value, key.replace(/^ERROR_CODE_/, '')]));
+
+const grpcToHttp = new Map(Object.entries({
+  1: 499, 2: 500, 3: 400, 4: 504, 5: 404, 6: 409, 7: 403, 8: 429,
+  9: 400, 10: 409, 11: 400, 12: 501, 13: 500, 14: 503, 15: 500, 16: 401,
+}).map(([key, value]) => [Number(key), value]));
+
+function timestamp(value) {
+  const message = new Timestamp();
+  message.fromDate(new Date(value));
+  return message;
+}
+function iso(message) { return message ? message.toDate().toISOString() : null; }
+function jobId(value) {
+  const id = new knowledgePb.JobId();
+  id.setValue(value || '');
+  return id;
+}
+
+export { grpc, knowledgePb, errorsPb, KnowledgeServiceService, KnowledgeServiceClient };
+
+export function encodeJob(job) {
+  const message = new knowledgePb.Job();
+  message.setId(jobId(job.id));
+  message.setStatus(statusToProto[job.status] ?? knowledgePb.JobStatus.JOB_STATUS_UNSPECIFIED);
+  message.setAttempts(job.attempts || 0);
+  message.setCreatedAt(timestamp(job.created_at));
+  message.setUpdatedAt(timestamp(job.updated_at));
+  if (job.result !== null && job.result !== undefined) message.setResultJson(JSON.stringify(job.result));
+  if (job.error) {
+    const failure = new errorsPb.ErrorDetail();
+    failure.setCode(protoErrorCode(ERROR_CODE.INTERNAL));
+    failure.setMessage(job.error);
+    failure.setRetryable(false);
+    failure.setReason(ERROR_REASON.EXECUTION_FAILED);
+    failure.setHttpStatus(500);
+    message.setFailure(failure);
+  }
+  return message;
+}
+
+export function decodeJob(message) {
+  const resultJson = message.getResultJson();
+  const failure = message.hasFailure() ? message.getFailure() : null;
+  return {
+    id: message.hasId() ? message.getId().getValue() : '',
+    status: statusFromProto.get(message.getStatus()) || 'unknown',
+    attempts: message.getAttempts(),
+    created_at: iso(message.getCreatedAt()),
+    updated_at: iso(message.getUpdatedAt()),
+    result: resultJson ? JSON.parse(resultJson) : null,
+    error: failure ? failure.getMessage() : null,
+  };
+}
+
+export function encodeRepositoryList(value) {
+  const response = new knowledgePb.ListRepositoriesResponse();
+  response.setRepositoriesList(value.repositories.map(repo => {
+    const ref = new knowledgePb.RepositoryRef();
+    ref.setAlias(repo.alias);
+    ref.setRepositoryId(repo.repository_id || '');
+    return ref;
+  }));
+  response.setEmbeddingsEnabled(value.embeddings_enabled);
+  return response;
+}
+
+export function decodeRepositoryList(message) {
+  const details = message.getRepositoriesList().map(repo => ({ alias: repo.getAlias(), repository_id: repo.getRepositoryId() }));
+  return { repositories: details.map(repo => repo.alias), repository_details: details, embeddings_enabled: message.getEmbeddingsEnabled() };
+}
+
+export function decodeSubmitRequest(message) {
+  const body = { repository: message.getRepository(), operation: operationFromProto.get(message.getOperation()) };
+  if (message.hasScope()) body.scope = message.getScope();
+  if (message.hasInclude()) body.include = message.getInclude().getValuesList();
+  if (message.hasExclude()) body.exclude = message.getExclude().getValuesList();
+  if (message.hasEmbed()) body.embed = message.getEmbed();
+  if (message.hasSemantic()) body.semantic = message.getSemantic();
+  if (message.hasQuery()) body.query = message.getQuery();
+  if (message.hasTopK()) body.top_k = message.getTopK();
+  if (message.hasTokenBudget()) body.token_budget = message.getTokenBudget();
+  if (message.hasGenerationId()) body.generation_id = message.getGenerationId();
+  if (message.hasMaxInputs()) body.max_inputs = message.getMaxInputs();
+  if (message.hasMaxCharacters()) body.max_characters = message.getMaxCharacters();
+  return { body, idempotencyKey: message.hasIdempotencyKey() ? message.getIdempotencyKey() : undefined };
+}
+
+export function encodeSubmitRequest(body, idempotencyKey) {
+  const message = new knowledgePb.SubmitJobRequest();
+  if (body?.repository !== undefined) message.setRepository(body.repository);
+  if (body?.operation !== undefined) message.setOperation(operationToProto[body.operation] ?? knowledgePb.JobOperation.JOB_OPERATION_UNSPECIFIED);
+  if (body?.scope !== undefined) message.setScope(body.scope);
+  if (body?.include !== undefined) {
+    const list = new knowledgePb.StringList();
+    list.setValuesList(body.include);
+    message.setInclude(list);
+  }
+  if (body?.exclude !== undefined) {
+    const list = new knowledgePb.StringList();
+    list.setValuesList(body.exclude);
+    message.setExclude(list);
+  }
+  if (body?.embed !== undefined) message.setEmbed(body.embed);
+  if (body?.semantic !== undefined) message.setSemantic(body.semantic);
+  if (body?.query !== undefined) message.setQuery(body.query);
+  if (body?.top_k !== undefined) message.setTopK(body.top_k);
+  if (body?.token_budget !== undefined) message.setTokenBudget(body.token_budget);
+  if (body?.generation_id !== undefined) message.setGenerationId(body.generation_id);
+  if (body?.max_inputs !== undefined) message.setMaxInputs(body.max_inputs);
+  if (body?.max_characters !== undefined) message.setMaxCharacters(body.max_characters);
+  if (idempotencyKey !== undefined) message.setIdempotencyKey(idempotencyKey);
+  return message;
+}
+
+export function encodeGetJobRequest(id, RequestType = knowledgePb.GetJobRequest) {
+  const request = new RequestType();
+  request.setJobId(jobId(id));
+  return request;
+}
+export function decodeJobId(request) { return request.hasJobId() ? request.getJobId().getValue() : ''; }
+
+export function encodeJobEvent(job, sequence) {
+  const event = new knowledgePb.JobEvent();
+  event.setJob(encodeJob(job));
+  event.setObservedAt(timestamp(new Date().toISOString()));
+  event.setSequence(sequence);
+  return event;
+}
+export function decodeJobEvent(event) {
+  return { job: decodeJob(event.getJob()), observed_at: iso(event.getObservedAt()), sequence: event.getSequence() };
+}
+
+export function metadataForToken(token) {
+  if (!token) throw new Error('A service token is required.');
+  const metadata = new grpc.Metadata();
+  metadata.set('authorization', `Bearer ${token}`);
+  return metadata;
+}
+export function authorizationFromMetadata(metadata) {
+  const values = metadata?.get('authorization') || [];
+  return values.find(entry => typeof entry === 'string') || '';
+}
+
+export function toGrpcError(error) {
+  const safeMessage = error?.status ? error.message : 'Service request failed.';
+  const legacyCode = error?.code === 'CONFLICT' ? ERROR_CODE.ABORTED : error?.code;
+  const code = Object.values(ERROR_CODE).includes(legacyCode) ? legacyCode : canonicalCodeFromHttpStatus(error?.status);
+  const reason = error?.reason || (code === ERROR_CODE.UNAUTHENTICATED ? ERROR_REASON.AUTH_INVALID
+    : code === ERROR_CODE.PERMISSION_DENIED ? ERROR_REASON.PERMISSION_DENIED
+      : code === ERROR_CODE.NOT_FOUND ? ERROR_REASON.TARGET_NOT_FOUND
+        : code === ERROR_CODE.ABORTED ? ERROR_REASON.CONFLICT
+          : code === ERROR_CODE.RESOURCE_EXHAUSTED ? ERROR_REASON.CAPACITY_EXHAUSTED
+            : code === ERROR_CODE.UNAVAILABLE ? ERROR_REASON.PROVIDER_UNAVAILABLE
+              : code === ERROR_CODE.INVALID_ARGUMENT ? ERROR_REASON.INPUT_INVALID
+                : ERROR_REASON.INTERNAL);
+  const envelope = createErrorEnvelope({
+    code,
+    reason,
+    message: safeMessage,
+    retryable: error?.retryable ?? (error?.status === 429 || error?.status === 503),
+    retry_after_ms: error?.retry_after_ms ?? null,
+    http_status: error?.status ?? defaultHttpStatusForCode(code),
+    provider: error?.provider ?? null,
+    provider_code: error?.provider_code ?? null,
+  });
+  const detail = new errorsPb.ErrorDetail();
+  detail.setCode(protoErrorCode(envelope.code));
+  detail.setMessage(envelope.message);
+  detail.setRetryable(envelope.retryable);
+  detail.setReason(envelope.reason);
+  if (envelope.http_status != null) detail.setHttpStatus(envelope.http_status);
+  if (envelope.retry_after_ms != null) detail.setRetryAfterMs(envelope.retry_after_ms);
+  if (envelope.provider) detail.setProvider(envelope.provider);
+  if (envelope.provider_code) detail.setProviderCode(envelope.provider_code);
+  const metadata = new grpc.Metadata();
+  metadata.set('agentsam-error-bin', Buffer.from(detail.serializeBinary()));
+  return Object.assign(new Error(safeMessage), {
+    code: grpcStatusForCode(envelope.code),
+    details: safeMessage,
+    metadata,
+  });
+}
+
+export function fromGrpcError(error) {
+  let detail = null;
+  try {
+    const values = error?.metadata?.get('agentsam-error-bin') || [];
+    const binary = values.find(value => Buffer.isBuffer(value));
+    if (binary) detail = errorsPb.ErrorDetail.deserializeBinary(new Uint8Array(binary));
+  } catch { /* fall back to gRPC status */ }
+  const message = detail?.getMessage() || error?.details || error?.message || 'Knowledge RPC failed.';
+  const rpcCode = detail ? errorCodeNames.get(detail.getCode()) || 'UNKNOWN' : undefined;
+  return Object.assign(new Error(message), {
+    status: detail?.hasHttpStatus?.() ? detail.getHttpStatus() : grpcToHttp.get(error?.code) ?? 500,
+    grpcCode: error?.code,
+    rpcCode,
+    reason: detail?.getReason?.() || ERROR_REASON.UNKNOWN,
+    retryable: detail?.getRetryable() || false,
+    retry_after_ms: detail?.hasRetryAfterMs?.() ? detail.getRetryAfterMs() : null,
+    provider: detail?.hasProvider?.() ? detail.getProvider() : null,
+    provider_code: detail?.hasProviderCode?.() ? detail.getProviderCode() : null,
+  });
+}
+
+export function isTerminalJob(job) { return job.status === 'completed' || job.status === 'failed'; }

package/src/knowledge/service/grpc-server.js

@@ -0,0 +1,83 @@
+import { createBearerTokenVerifier } from './auth.js';
+import { serviceError } from './job-engine.js';
+import {
+  grpc,
+  KnowledgeServiceService,
+  authorizationFromMetadata,
+  decodeJobId,
+  decodeSubmitRequest,
+  encodeJob,
+  encodeJobEvent,
+  encodeRepositoryList,
+  isTerminalJob,
+  toGrpcError,
+} from './grpc-codec.js';
+
+export async function startKnowledgeGrpcServer({
+  engine,
+  token,
+  verifyToken,
+  port = 0,
+  host = '127.0.0.1',
+  credentials = grpc.ServerCredentials.createInsecure(),
+} = {}) {
+  if (!engine) throw new Error('Knowledge job engine is required.');
+  const verify = verifyToken || createBearerTokenVerifier(token);
+  const authenticate = call => {
+    if (!verify(authorizationFromMetadata(call.metadata))) throw serviceError(401, 'Unauthorized.', 'UNAUTHENTICATED');
+  };
+  const unary = handler => (call, callback) => {
+    try {
+      authenticate(call);
+      callback(null, handler(call));
+    } catch (error) {
+      callback(toGrpcError(error));
+    }
+  };
+
+  const server = new grpc.Server();
+  server.addService(KnowledgeServiceService, {
+    listRepositories: unary(() => encodeRepositoryList(engine.listRepositories())),
+    submitJob: unary(call => {
+      const { body, idempotencyKey } = decodeSubmitRequest(call.request);
+      return encodeJob(engine.submitJob(body, { idempotencyKey }).job);
+    }),
+    getJob: unary(call => encodeJob(engine.getJob(decodeJobId(call.request)))),
+    watchJob(call) {
+      let unsubscribe = () => {};
+      let ended = false;
+      try {
+        authenticate(call);
+        let sequence = 0;
+        unsubscribe = engine.watchJob(decodeJobId(call.request), job => {
+          if (ended || call.cancelled) return;
+          call.write(encodeJobEvent(job, ++sequence));
+          if (isTerminalJob(job)) {
+            ended = true;
+            queueMicrotask(() => {
+              unsubscribe();
+              if (!call.cancelled) call.end();
+            });
+          }
+        });
+        call.once('cancelled', () => { ended = true; unsubscribe(); });
+        call.once('close', () => { ended = true; unsubscribe(); });
+      } catch (error) {
+        ended = true;
+        unsubscribe();
+        call.emit('error', toGrpcError(error));
+      }
+    },
+  });
+
+  const boundPort = await new Promise((resolve, reject) => {
+    server.bindAsync(`${host}:${port}`, credentials, (error, actualPort) => error ? reject(error) : resolve(actualPort));
+  });
+  return {
+    server,
+    address: { host, port: boundPort },
+    target: `${host}:${boundPort}`,
+    async close() { await new Promise(resolve => server.tryShutdown(resolve)); },
+    forceClose() { server.forceShutdown(); },
+  };
+}

package/src/knowledge/service/job-engine.js

@@ -0,0 +1,248 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fork } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import { fingerprint, validateConfig } from '../config.js';
+
+const defaultWorkerPath = fileURLToPath(new URL('./job-worker.js', import.meta.url));
+const TERMINAL_STATUSES = new Set(['completed', 'failed']);
+
+export function serviceError(status, message, code) {
+  return Object.assign(new Error(message), { status, code });
+}
+
+function decode(row) {
+  return row && {
+    id: row.id,
+    status: row.status,
+    attempts: row.attempts,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+    result: row.result ? JSON.parse(row.result) : null,
+    error: row.error,
+  };
+}
+
+function normalizeRepositories(repositories) {
+  if (!repositories || !Object.keys(repositories).length) throw new Error('Register at least one repository.');
+  return Object.fromEntries(Object.entries(repositories).map(([name, repo]) => {
+    if (!/^[a-z][a-z0-9_-]{0,47}$/.test(name)) throw new Error('Invalid repository alias.');
+    const root = fs.realpathSync(repo.root);
+    if (!fs.statSync(root).isDirectory()) throw new Error('Repository root must be a directory.');
+    const config = validateConfig(repo.config);
+    if (config.storage.driver !== 'sqlite') throw new Error('This service release uses its durable SQLite volume; Postgres is not configured by this preset.');
+    return [name, { root, config }];
+  }));
+}
+
+function normalizeRequest(body, repositories, allowEmbeddings) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) throw serviceError(400, 'Expected a JSON object.', 'INVALID_ARGUMENT');
+  const keys = ['repository', 'operation', 'scope', 'include', 'exclude', 'embed', 'semantic', 'query', 'top_k', 'token_budget', 'generation_id', 'max_inputs', 'max_characters'];
+  if (Object.keys(body).some(k => !keys.includes(k))) throw serviceError(400, 'Unknown job field.', 'INVALID_ARGUMENT');
+  const repo = Object.hasOwn(repositories, body.repository) && repositories[body.repository];
+  if (!repo) throw serviceError(404, 'Repository is not registered.', 'NOT_FOUND');
+  if (!['index', 'plan', 'search'].includes(body.operation)) throw serviceError(400, 'operation must be index, plan, or search.', 'INVALID_ARGUMENT');
+  for (const key of ['embed', 'semantic']) {
+    if (body[key] !== undefined && typeof body[key] !== 'boolean') throw serviceError(400, `${key} must be a boolean.`, 'INVALID_ARGUMENT');
+  }
+  if (((body.embed && body.operation !== 'plan') || body.semantic) && !allowEmbeddings) {
+    throw serviceError(403, 'Embedding calls are disabled on this service.', 'PERMISSION_DENIED');
+  }
+  if (body.exclude !== undefined && !Array.isArray(body.exclude)) throw serviceError(400, 'exclude must be an array.', 'INVALID_ARGUMENT');
+  if (body.operation === 'search' && (typeof body.query !== 'string' || !body.query.trim() || body.query.length > 8000)) {
+    throw serviceError(400, 'A query of 1..8000 characters is required.', 'INVALID_ARGUMENT');
+  }
+  const bounded = (key, fallback, min, max) => {
+    const value = body[key] ?? fallback;
+    if (!Number.isInteger(value) || value < min || value > max) throw serviceError(400, `${key} must be ${min}..${max}.`, 'INVALID_ARGUMENT');
+    return value;
+  };
+  const request = {
+    ...body,
+    embed: body.embed ?? false,
+    semantic: body.semantic ?? false,
+    max_inputs: bounded('max_inputs', 100, 0, 1000),
+    max_characters: bounded('max_characters', 200000, 0, 2000000),
+    top_k: bounded('top_k', 8, 1, 8),
+    token_budget: bounded('token_budget', 6000, 256, 6000),
+  };
+  const config = structuredClone(repo.config);
+  if (body.scope !== undefined) config.scope.name = body.scope;
+  if (body.include !== undefined) config.scope.include = body.include;
+  if (body.exclude !== undefined) config.scope.exclude = [...config.scope.exclude, ...body.exclude];
+  let checked;
+  try {
+    checked = validateConfig(config);
+  } catch (error) {
+    throw serviceError(400, error.message, 'INVALID_ARGUMENT');
+  }
+  if (checked.scope.include.some(p => !repo.config.scope.include.some(allowed => allowed === '.' || p === allowed || p.startsWith(allowed + '/')))) {
+    throw serviceError(403, 'Requested include is outside the registered scope.', 'PERMISSION_DENIED');
+  }
+  return { request, config: checked, root: repo.root };
+}
+
+export function createKnowledgeJobEngine({
+  stateDir,
+  repositories,
+  allowEmbeddings = false,
+  maxQueued = 32,
+  maxFiles = 2000,
+  jobTimeoutMs = 600000,
+  workerPath = defaultWorkerPath,
+} = {}) {
+  const registry = normalizeRepositories(repositories);
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const jobsFile = path.join(stateDir, 'jobs.sqlite');
+  const db = new DatabaseSync(jobsFile);
+  db.exec(`PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;
+    CREATE TABLE IF NOT EXISTS jobs (id TEXT PRIMARY KEY, idem TEXT UNIQUE, digest TEXT NOT NULL,
+      payload TEXT NOT NULL, status TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL, result TEXT, error TEXT);
+    CREATE INDEX IF NOT EXISTS jobs_pending ON jobs(status, created_at);`);
+  fs.chmodSync(jobsFile, 0o600);
+  db.prepare("UPDATE jobs SET status=CASE WHEN attempts>=3 THEN 'failed' ELSE 'queued' END, error=CASE WHEN attempts>=3 THEN 'Interrupted three times; submit a new job after investigation.' ELSE NULL END WHERE status='running'").run();
+
+  let child = null;
+  let closing = false;
+  let closed = false;
+  let pumping = false;
+  const watchers = new Map();
+
+  const getRaw = id => decode(db.prepare('SELECT * FROM jobs WHERE id=?').get(id));
+  const publish = job => {
+    const listeners = watchers.get(job.id);
+    if (!listeners) return;
+    for (const listener of [...listeners]) {
+      try { listener(job); } catch { /* transport observers cannot break durable state transitions */ }
+    }
+    if (TERMINAL_STATUSES.has(job.status)) watchers.delete(job.id);
+  };
+  const updateStatus = (id, status, { result = null, error = null } = {}) => {
+    db.prepare('UPDATE jobs SET status=?,result=?,error=?,updated_at=? WHERE id=?').run(
+      status,
+      result === null ? null : JSON.stringify(result),
+      error,
+      new Date().toISOString(),
+      id,
+    );
+    const job = getRaw(id);
+    publish(job);
+    return job;
+  };
+
+  const pump = () => {
+    if (closing || pumping) return;
+    const row = db.prepare("SELECT * FROM jobs WHERE status='queued' ORDER BY created_at,rowid LIMIT 1").get();
+    if (!row) return;
+    pumping = true;
+    db.prepare("UPDATE jobs SET status='running',attempts=attempts+1,updated_at=? WHERE id=?").run(new Date().toISOString(), row.id);
+    publish(getRaw(row.id));
+    let response = null;
+    let timedOut = false;
+    child = fork(workerPath, [], { execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'], env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
+    const timer = setTimeout(() => { timedOut = true; child?.kill('SIGKILL'); }, jobTimeoutMs);
+    child.once('message', value => { response = value; });
+    child.once('error', () => { response = { ok: false, error: 'Could not start indexing process.' }; });
+    child.once('close', () => {
+      clearTimeout(timer);
+      child = null;
+      if (!closing) {
+        const ok = response?.ok && !timedOut;
+        updateStatus(row.id, ok ? 'completed' : 'failed', {
+          result: ok ? response.result : null,
+          error: ok ? null : timedOut ? 'Job exceeded its time limit; narrow the scope.' : response?.error || 'Indexing process exited unexpectedly.',
+        });
+      }
+      pumping = false;
+      if (!closing) setImmediate(pump);
+    });
+    const payload = JSON.parse(row.payload);
+    const registered = registry[payload.request.repository];
+    if (!registered || registered.config.repository_id !== payload.config.repository_id || fingerprint(registered.config.scope) !== payload.registered_scope || (!allowEmbeddings && ((payload.request.embed && payload.request.operation !== 'plan') || payload.request.semantic))) {
+      response = { ok: false, error: 'Repository registration changed; resubmit this job.' };
+      child.kill();
+      return;
+    }
+    child.send({ ...payload, root: registered.root, filename: path.join(stateDir, 'knowledge.sqlite'), maxFiles });
+  };
+
+  const api = {
+    listRepositories() {
+      return {
+        repositories: Object.entries(registry).map(([alias, repo]) => ({ alias, repository_id: repo.config.repository_id })),
+        embeddings_enabled: allowEmbeddings,
+      };
+    },
+    getJob(id) {
+      if (typeof id !== 'string' || !/^[a-f0-9-]{36}$/.test(id)) throw serviceError(400, 'Invalid job id.', 'INVALID_ARGUMENT');
+      const job = getRaw(id);
+      if (!job) throw serviceError(404, 'Job not found.', 'NOT_FOUND');
+      return job;
+    },
+    submitJob(body, { idempotencyKey } = {}) {
+      if (closing) throw serviceError(503, 'Service is stopping.', 'UNAVAILABLE');
+      const payload = normalizeRequest(body, registry, allowEmbeddings);
+      payload.registered_scope = fingerprint(registry[payload.request.repository].config.scope);
+      if (idempotencyKey !== undefined && (typeof idempotencyKey !== 'string' || !/^[\w:.-]{1,128}$/.test(idempotencyKey))) {
+        throw serviceError(400, 'Invalid Idempotency-Key.', 'INVALID_ARGUMENT');
+      }
+      const digest = fingerprint(payload);
+      const idem = idempotencyKey ? fingerprint([payload.config.repository_id, payload.registered_scope, idempotencyKey]) : null;
+      const previous = idem && db.prepare('SELECT * FROM jobs WHERE idem=?').get(idem);
+      if (previous) {
+        if (previous.digest !== digest) throw serviceError(409, 'Idempotency-Key already used for a different job.', 'CONFLICT');
+        return { job: decode(previous), created: false };
+      }
+      if (db.prepare("SELECT COUNT(*) AS n FROM jobs WHERE status IN ('queued','running')").get().n >= maxQueued) {
+        throw serviceError(429, 'Job queue is full; retry later with the same Idempotency-Key.', 'RESOURCE_EXHAUSTED');
+      }
+      const id = randomUUID();
+      const now = new Date().toISOString();
+      db.prepare("INSERT INTO jobs(id,idem,digest,payload,status,created_at,updated_at) VALUES(?,?,?,?,'queued',?,?)").run(
+        id,
+        idem,
+        digest,
+        JSON.stringify(payload),
+        now,
+        now,
+      );
+      const job = getRaw(id);
+      publish(job);
+      setImmediate(pump);
+      return { job, created: true };
+    },
+    watchJob(id, listener) {
+      if (typeof listener !== 'function') throw new TypeError('watchJob listener must be a function.');
+      const current = api.getJob(id);
+      listener(current);
+      if (TERMINAL_STATUSES.has(current.status)) return () => {};
+      let listeners = watchers.get(id);
+      if (!listeners) watchers.set(id, listeners = new Set());
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+        if (!listeners.size) watchers.delete(id);
+      };
+    },
+    isClosing() {
+      return closing;
+    },
+    async close() {
+      if (closed) return;
+      closing = true;
+      watchers.clear();
+      if (child) {
+        const active = child;
+        await new Promise(resolve => { active.once('close', resolve); active.kill('SIGKILL'); });
+      }
+      db.close();
+      closed = true;
+    },
+  };
+
+  setImmediate(pump);
+  return api;
+}