@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/src/knowledge/service/client.js

@@ -1,3 +1,5 @@
+import { AgentSamError, fromHttpError } from '../../errors/index.js';
+
 /** Fetch-only client: safe to import in Cloudflare Workers; no Node runtime dependencies. */
 export function createKnowledgeServiceClient({ baseUrl, token, fetchImpl = globalThis.fetch, timeoutMs = 15000 } = {}) {
   const url = new URL(baseUrl);
@@ -10,7 +12,17 @@ export function createKnowledgeServiceClient({ baseUrl, token, fetchImpl = globa
     const response = await fetchImpl(new URL(route, url), { method: body ? 'POST' : 'GET', headers,
       body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(timeoutMs), redirect: 'error' });
     const value = await response.json();
-    if (!response.ok) throw Object.assign(new Error(value.error || `Knowledge service returned ${response.status}`), { status: response.status });
+    if (!response.ok) {
+      const envelope = fromHttpError({
+        status: response.status,
+        body: value,
+        headers: response.headers,
+        source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'http_server' },
+        domain: 'knowledge',
+        stage: 'request',
+      });
+      throw new AgentSamError(envelope);
+    }
     return value;
   };
   return { repositories: () => call('/v1/repositories'), submit: (body, idempotencyKey) => call('/v1/jobs', { body, idempotencyKey }),

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

@@ -8,6 +8,11 @@ import {
   defaultHttpStatusForCode,
   grpcStatusForCode,
 } from '../../errors/contract.js';
+import {
+  AgentSamError,
+  isErrorEnvelope,
+  normalizeError,
+} from '../../errors/index.js';
 
 const require = createRequire(import.meta.url);
 const knowledgePb = require('../../rpc/generated/knowledge_pb.js');
@@ -47,6 +52,84 @@ function jobId(value) {
   id.setValue(value || '');
   return id;
 }
+function json(value) { return value == null ? '' : JSON.stringify(value); }
+function parseJson(value) {
+  if (!value) return null;
+  try { return JSON.parse(value); } catch { return null; }
+}
+
+export function encodeErrorDetail(value) {
+  const envelope = isErrorEnvelope(value) ? value : normalizeError(value);
+  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);
+  detail.setSeverity(envelope.severity);
+  detail.setSourceKind(envelope.source.kind);
+  detail.setSourceName(envelope.source.name);
+  if (envelope.source.service) detail.setSourceService(envelope.source.service);
+  detail.setResolutionOwner(envelope.resolution_owner);
+  detail.setDomain(envelope.domain);
+  if (envelope.tool) detail.setTool(envelope.tool);
+  if (envelope.stage) detail.setStage(envelope.stage);
+  detail.setRemediationAction(envelope.remediation.action);
+  if (envelope.remediation.message) detail.setRemediationMessage(envelope.remediation.message);
+  detail.setFingerprint(envelope.fingerprint);
+  if (envelope.trace_id) detail.setTraceId(envelope.trace_id);
+  if (envelope.transport) detail.setTransport(envelope.transport);
+  if (envelope.resource) detail.setResourceJson(json(envelope.resource));
+  if (envelope.native) detail.setNativeJson(json(envelope.native));
+  if (envelope.environment) detail.setEnvironmentJson(json(envelope.environment));
+  if (envelope.details != null) detail.setDetailsJson(json(envelope.details));
+  detail.setOccurrenceCount(envelope.occurrence_count || 1);
+  if (envelope.request_id) detail.setRequestId(envelope.request_id);
+  detail.setSchemaVersion(envelope.schema_version || 1);
+  return detail;
+}
+
+export function decodeErrorDetail(detail) {
+  if (!detail) return null;
+  const code = errorCodeNames.get(detail.getCode()) || ERROR_CODE.UNKNOWN;
+  const provider = detail.hasProvider?.() ? detail.getProvider() : null;
+  return createErrorEnvelope({
+    code,
+    reason: detail.getReason?.() || ERROR_REASON.UNKNOWN,
+    message: detail.getMessage?.() || 'Operation failed',
+    retryable: detail.getRetryable?.() || false,
+    retry_after_ms: detail.hasRetryAfterMs?.() ? detail.getRetryAfterMs() : null,
+    http_status: detail.hasHttpStatus?.() ? detail.getHttpStatus() : defaultHttpStatusForCode(code),
+    provider,
+    provider_code: detail.hasProviderCode?.() ? detail.getProviderCode() : null,
+    severity: detail.hasSeverity?.() ? detail.getSeverity() : undefined,
+    source: {
+      kind: detail.hasSourceKind?.() ? detail.getSourceKind() : (provider ? 'provider' : 'agentsam'),
+      name: detail.hasSourceName?.() ? detail.getSourceName() : (provider || 'agentsam-sdk'),
+      service: detail.hasSourceService?.() ? detail.getSourceService() : null,
+    },
+    resolution_owner: detail.hasResolutionOwner?.() ? detail.getResolutionOwner() : undefined,
+    domain: detail.hasDomain?.() ? detail.getDomain() : 'runtime',
+    tool: detail.hasTool?.() ? detail.getTool() : null,
+    stage: detail.hasStage?.() ? detail.getStage() : null,
+    remediation: {
+      action: detail.hasRemediationAction?.() ? detail.getRemediationAction() : undefined,
+      message: detail.hasRemediationMessage?.() ? detail.getRemediationMessage() : null,
+    },
+    fingerprint: detail.hasFingerprint?.() ? detail.getFingerprint() : undefined,
+    trace_id: detail.hasTraceId?.() ? detail.getTraceId() : null,
+    transport: detail.hasTransport?.() ? detail.getTransport() : null,
+    resource: detail.hasResourceJson?.() ? parseJson(detail.getResourceJson()) : null,
+    native: detail.hasNativeJson?.() ? parseJson(detail.getNativeJson()) : null,
+    environment: detail.hasEnvironmentJson?.() ? parseJson(detail.getEnvironmentJson()) : null,
+    details: detail.hasDetailsJson?.() ? parseJson(detail.getDetailsJson()) : null,
+    occurrence_count: detail.hasOccurrenceCount?.() ? detail.getOccurrenceCount() : 1,
+    request_id: detail.hasRequestId?.() ? detail.getRequestId() : null,
+  });
+}
 
 export { grpc, knowledgePb, errorsPb, KnowledgeServiceService, KnowledgeServiceClient };
 
@@ -58,21 +141,20 @@ export function encodeJob(job) {
   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);
-  }
+  const failure = job.failure || (job.error ? createErrorEnvelope({
+    reason: ERROR_REASON.EXECUTION_FAILED,
+    message: job.error,
+    source: { kind: 'agentsam', name: 'agentsam-knowledge' },
+    domain: 'knowledge',
+    stage: 'execute',
+  }) : null);
+  if (failure) message.setFailure(encodeErrorDetail(failure));
   return message;
 }
 
 export function decodeJob(message) {
   const resultJson = message.getResultJson();
-  const failure = message.hasFailure() ? message.getFailure() : null;
+  const failure = message.hasFailure() ? decodeErrorDetail(message.getFailure()) : null;
   return {
     id: message.hasId() ? message.getId().getValue() : '',
     status: statusFromProto.get(message.getStatus()) || 'unknown',
@@ -80,7 +162,8 @@ export function decodeJob(message) {
     created_at: iso(message.getCreatedAt()),
     updated_at: iso(message.getUpdatedAt()),
     result: resultJson ? JSON.parse(resultJson) : null,
-    error: failure ? failure.getMessage() : null,
+    failure,
+    error: failure?.message || null,
   };
 }
 
@@ -174,42 +257,46 @@ export function authorizationFromMetadata(metadata) {
 }
 
 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);
+  let envelope;
+  if (isErrorEnvelope(error) || error instanceof AgentSamError || isErrorEnvelope(error?.envelope)) {
+    envelope = normalizeError(error);
+  } else {
+    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.TRANSPORT_UNREACHABLE
+                : code === ERROR_CODE.DEADLINE_EXCEEDED ? ERROR_REASON.DEADLINE_EXCEEDED
+                  : code === ERROR_CODE.INVALID_ARGUMENT ? ERROR_REASON.INPUT_INVALID
+                    : ERROR_REASON.INTERNAL);
+    envelope = createErrorEnvelope({
+      code,
+      reason,
+      message: safeMessage,
+      retryable: error?.retryable ?? (error?.status === 429 || error?.status === 503 || error?.status === 504),
+      retry_after_ms: error?.retry_after_ms ?? null,
+      http_status: error?.status ?? defaultHttpStatusForCode(code),
+      provider: error?.provider ?? null,
+      provider_code: error?.provider_code ?? null,
+      source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'grpc' },
+      resolution_owner: code === ERROR_CODE.UNAVAILABLE ? 'agentsam' : undefined,
+      domain: 'knowledge',
+      stage: 'request',
+      trace_id: error?.trace_id ?? null,
+    });
+  }
+  const detail = encodeErrorDetail(envelope);
   const metadata = new grpc.Metadata();
   metadata.set('agentsam-error-bin', Buffer.from(detail.serializeBinary()));
-  return Object.assign(new Error(safeMessage), {
+  return Object.assign(new Error(envelope.message), {
     code: grpcStatusForCode(envelope.code),
-    details: safeMessage,
+    details: envelope.message,
     metadata,
+    envelope,
   });
 }
 
@@ -220,17 +307,33 @@ export function fromGrpcError(error) {
     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,
+  let envelope;
+  if (detail) {
+    envelope = decodeErrorDetail(detail);
+  } else {
+    const status = grpcToHttp.get(error?.code) ?? 500;
+    const code = canonicalCodeFromHttpStatus(status);
+    envelope = createErrorEnvelope({
+      code,
+      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.RESOURCE_EXHAUSTED ? ERROR_REASON.CAPACITY_EXHAUSTED
+              : code === ERROR_CODE.UNAVAILABLE ? ERROR_REASON.TRANSPORT_UNREACHABLE
+                : code === ERROR_CODE.DEADLINE_EXCEEDED ? ERROR_REASON.DEADLINE_EXCEEDED
+                  : code === ERROR_CODE.INVALID_ARGUMENT ? ERROR_REASON.INPUT_INVALID
+                    : ERROR_REASON.INTERNAL,
+      message: error?.details || error?.message || 'Knowledge RPC failed.',
+      http_status: status,
+      retryable: [8, 14, 4].includes(Number(error?.code)),
+      source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'grpc' },
+      domain: 'knowledge',
+      stage: 'request',
+    });
+  }
+  return Object.assign(new AgentSamError(envelope), {
     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,
+    rpcCode: envelope.code,
   });
 }
 

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

@@ -5,23 +5,83 @@ import { fork } from 'node:child_process';
 import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 import { fingerprint, validateConfig } from '../config.js';
+import {
+  AgentSamError,
+  ERROR_CODE,
+  ERROR_REASON,
+  createErrorEnvelope,
+  normalizeError,
+  parseError,
+} from '../../errors/index.js';
 
 const defaultWorkerPath = fileURLToPath(new URL('./job-worker.js', import.meta.url));
 const TERMINAL_STATUSES = new Set(['completed', 'failed']);
 
+function serviceReason(code) {
+  switch (code) {
+    case ERROR_CODE.UNAUTHENTICATED: return ERROR_REASON.AUTH_INVALID;
+    case ERROR_CODE.PERMISSION_DENIED: return ERROR_REASON.PERMISSION_DENIED;
+    case ERROR_CODE.NOT_FOUND: return ERROR_REASON.TARGET_NOT_FOUND;
+    case ERROR_CODE.ABORTED: return ERROR_REASON.CONFLICT;
+    case ERROR_CODE.RESOURCE_EXHAUSTED: return ERROR_REASON.CAPACITY_EXHAUSTED;
+    case ERROR_CODE.UNAVAILABLE: return ERROR_REASON.TRANSPORT_UNREACHABLE;
+    case ERROR_CODE.DEADLINE_EXCEEDED: return ERROR_REASON.DEADLINE_EXCEEDED;
+    case ERROR_CODE.INVALID_ARGUMENT: return ERROR_REASON.INPUT_INVALID;
+    default: return ERROR_REASON.INTERNAL;
+  }
+}
+
 export function serviceError(status, message, code) {
-  return Object.assign(new Error(message), { status, code });
+  const canonical = code === 'CONFLICT' ? ERROR_CODE.ABORTED : (Object.values(ERROR_CODE).includes(code) ? code : ERROR_CODE.INTERNAL);
+  const envelope = createErrorEnvelope({
+    code: canonical,
+    reason: serviceReason(canonical),
+    message,
+    http_status: status,
+    retryable: [429, 503, 504].includes(Number(status)),
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+    resolution_owner: canonical === ERROR_CODE.UNAVAILABLE ? 'agentsam' : undefined,
+    domain: 'knowledge',
+    stage: 'request',
+  });
+  return new AgentSamError(envelope);
+}
+
+function decodeFailure(row) {
+  if (row?.failure_json) {
+    try { return parseError(row.failure_json); }
+    catch {
+      return createErrorEnvelope({
+        reason: ERROR_REASON.INTERNAL_CONTRACT_VIOLATION,
+        message: 'Stored knowledge failure could not be decoded.',
+        source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+        domain: 'knowledge',
+        stage: 'persistence',
+      });
+    }
+  }
+  if (!row?.error) return null;
+  return createErrorEnvelope({
+    reason: ERROR_REASON.EXECUTION_FAILED,
+    message: row.error,
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'legacy_job_row' },
+    domain: 'knowledge',
+    stage: 'execute',
+  });
 }
 
 function decode(row) {
-  return row && {
+  if (!row) return null;
+  const failure = decodeFailure(row);
+  return {
     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,
+    failure,
+    error: failure?.message || row.error || null,
   };
 }
 
@@ -100,10 +160,22 @@ export function createKnowledgeJobEngine({
   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);
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL, result TEXT, error TEXT, failure_json TEXT);
     CREATE INDEX IF NOT EXISTS jobs_pending ON jobs(status, created_at);`);
+  const columns = new Set(db.prepare('PRAGMA table_info(jobs)').all().map(row => row.name));
+  if (!columns.has('failure_json')) db.exec('ALTER TABLE jobs ADD COLUMN failure_json TEXT');
   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();
+  const interruptedFailure = createErrorEnvelope({
+    reason: ERROR_REASON.EXECUTION_FAILED,
+    message: 'Interrupted three times; submit a new job after investigation.',
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+    domain: 'knowledge',
+    stage: 'recovery',
+  });
+  db.prepare("UPDATE jobs SET status=CASE WHEN attempts>=3 THEN 'failed' ELSE 'queued' END, error=CASE WHEN attempts>=3 THEN ? ELSE NULL END, failure_json=CASE WHEN attempts>=3 THEN ? ELSE NULL END WHERE status='running'").run(
+    interruptedFailure.message,
+    JSON.stringify(interruptedFailure),
+  );
 
   let child = null;
   let closing = false;
@@ -120,11 +192,17 @@ export function createKnowledgeJobEngine({
     }
     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(
+  const updateStatus = (id, status, { result = null, failure = null, error = null } = {}) => {
+    const normalizedFailure = failure
+      ? normalizeError(failure, { source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' }, domain: 'knowledge', stage: 'execute' })
+      : error
+        ? createErrorEnvelope({ reason: ERROR_REASON.EXECUTION_FAILED, message: error, source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' }, domain: 'knowledge', stage: 'execute' })
+        : null;
+    db.prepare('UPDATE jobs SET status=?,result=?,error=?,failure_json=?,updated_at=? WHERE id=?').run(
       status,
       result === null ? null : JSON.stringify(result),
-      error,
+      normalizedFailure?.message || null,
+      normalizedFailure ? JSON.stringify(normalizedFailure) : null,
       new Date().toISOString(),
       id,
     );
@@ -145,15 +223,49 @@ export function createKnowledgeJobEngine({
     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('error', (cause) => {
+      response = {
+        ok: false,
+        failure: createErrorEnvelope({
+          reason: ERROR_REASON.INTERNAL_DEPENDENCY_FAILED,
+          message: 'Could not start indexing process.',
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+          domain: 'knowledge',
+          stage: 'spawn',
+          native: { code: cause?.code || null, exception_type: cause?.name || null, stack: cause?.stack || null },
+        }),
+      };
+    });
     child.once('close', () => {
       clearTimeout(timer);
       child = null;
       if (!closing) {
         const ok = response?.ok && !timedOut;
+        let failure = null;
+        if (!ok) {
+          if (timedOut) {
+            failure = createErrorEnvelope({
+              reason: ERROR_REASON.EXECUTION_TIMEOUT,
+              message: 'Knowledge job exceeded its time limit; narrow the scope and retry.',
+              source: { kind: 'runtime', name: 'agentsam-knowledge-worker' },
+              domain: 'knowledge',
+              stage: 'execute',
+            });
+          } else if (response?.failure) {
+            failure = normalizeError(response.failure, { source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' }, domain: 'knowledge', stage: 'execute' });
+          } else {
+            failure = createErrorEnvelope({
+              reason: ERROR_REASON.EXECUTION_FAILED,
+              message: response?.error || 'Indexing process exited unexpectedly.',
+              source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+              domain: 'knowledge',
+              stage: 'execute',
+            });
+          }
+        }
         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.',
+          failure,
         });
       }
       pumping = false;
@@ -162,7 +274,17 @@ export function createKnowledgeJobEngine({
     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.' };
+      response = {
+        ok: false,
+        failure: createErrorEnvelope({
+          reason: ERROR_REASON.REPOSITORY_CHANGED,
+          message: 'Repository registration changed; resubmit this job.',
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'repository_registry' },
+          domain: 'repository',
+          stage: 'execute',
+          resource: { type: 'repository', id: payload.config.repository_id || null },
+        }),
+      };
       child.kill();
       return;
     }

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

@@ -3,12 +3,27 @@ import { openSqliteStore } from '../stores/sqlite.js';
 import { createGeminiEmbedder } from '../providers/gemini.js';
 import { inventory } from '../source.js';
 import { scopeKey } from '../config.js';
+import {
+  AgentSamError,
+  ERROR_REASON,
+  createErrorEnvelope,
+  normalizeError,
+} from '../../errors/index.js';
 
 // Parsing and vector ranking run in a child process, keeping HTTP acceptance responsive.
 process.once('message', async ({ root, config, filename, request, maxFiles }) => {
   let store;
   try {
-    if (request.operation !== 'search' && inventory(root, config.scope).length > maxFiles) throw new Error(`Scope exceeds ${maxFiles} files; choose a smaller include set.`);
+    if (request.operation !== 'search' && inventory(root, config.scope).length > maxFiles) throw new AgentSamError(createErrorEnvelope({
+      reason: ERROR_REASON.INPUT_OUT_OF_RANGE,
+      message: `Scope exceeds ${maxFiles} files; choose a smaller include set.`,
+      source: { kind: 'user', name: 'knowledge_request' },
+      resolution_owner: 'user',
+      domain: 'knowledge',
+      stage: 'inventory',
+      remediation: { action: 'reduce_scope', message: 'Narrow the repository include scope and retry.' },
+      resource: { type: 'repository', id: config.repository_id || null },
+    }));
     store = await openSqliteStore(filename);
     const embedder = request.operation !== 'plan' && (request.embed || request.semantic) ? createGeminiEmbedder({ apiKey: process.env.GEMINI_API_KEY }) : undefined;
     let result;
@@ -18,7 +33,15 @@ process.once('message', async ({ root, config, filename, request, maxFiles }) =>
       const generation = request.generation_id ? await store.getGeneration(scopeKey(config), request.generation_id) : await store.active(scopeKey(config));
       const under = (file, selection) => selection === '.' || file === selection || file.startsWith(selection + '/');
       if (generation?.files.some(file => !config.scope.include.some(p => under(file.path, p)) || config.scope.exclude.some(p => under(file.path, p)))) {
-        throw new Error('Generation exceeds the requested scope; select a matching scope or reindex.');
+        throw new AgentSamError(createErrorEnvelope({
+          reason: ERROR_REASON.PRECONDITION_FAILED,
+          message: 'Generation exceeds the requested scope; select a matching scope or reindex.',
+          source: { kind: 'user', name: 'knowledge_request' },
+          domain: 'knowledge',
+          stage: 'search',
+          remediation: { action: 'change_configuration', message: 'Select a matching indexed scope or reindex the requested scope.' },
+          resource: { type: 'repository', id: config.repository_id || null },
+        }));
       }
       result = await retrieve({ store, config, text: request.query, semantic: request.semantic, embedder,
         topK: request.top_k, tokenBudget: request.token_budget, generationId: request.generation_id });
@@ -27,8 +50,14 @@ process.once('message', async ({ root, config, filename, request, maxFiles }) =>
     process.send({ ok: true, result }, () => process.exit(0));
   } catch (error) {
     await store?.close();
-    // Provider error strings may include sensitive request details. Never persist them.
-    const message = request.embed || request.semantic ? 'Embedding job failed; check provider configuration, budgets, and availability.' : String(error.message).slice(0, 500);
-    process.send({ ok: false, error: message }, () => process.exit(1));
+    const failure = normalizeError(error, {
+      source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+      domain: 'knowledge',
+      stage: request.embed || request.semantic ? 'embedding' : request.operation || 'execute',
+      message: request.embed || request.semantic
+        ? 'Embedding job failed; inspect the canonical failure for provider/configuration details.'
+        : undefined,
+    });
+    process.send({ ok: false, failure }, () => process.exit(1));
   }
 });

package/src/knowledge/service/server.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createBearerTokenVerifier } from './auth.js';
 import { createKnowledgeJobEngine, serviceError } from './job-engine.js';
+import { normalizeError, toHttpError } from '../../errors/index.js';
 
 async function readBody(req) {
   const chunks = [];
@@ -44,7 +45,15 @@ export async function startKnowledgeHttpServer({ engine, token, verifyToken, por
       const { job, created } = engine.submitJob(await readBody(req), { idempotencyKey: req.headers['idempotency-key'] });
       return send(created ? 202 : 200, job);
     } catch (error) {
-      if (!res.writableEnded) send(error.status || 500, { error: error.status ? error.message : 'Service request failed.' });
+      if (!res.writableEnded) {
+        const envelope = normalizeError(error, {
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'http_server' },
+          domain: 'knowledge',
+          stage: 'request',
+        });
+        const httpError = toHttpError(envelope);
+        send(httpError.status, httpError.body);
+      }
     }
   });
   server.requestTimeout = 15000;

package/src/knowledge/store-discovery.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_PATH, readConfig, validateConfig, defaultConfig } from './config.js';
+import { findCliProjectRoot } from '../lib/cli-preferences.js';
+import { runtimeDatabasePath } from '../local/runtime-store.js';
+import { getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
+
+// Configuration evidence only. No connection probes, credential reads, or schema writes.
+export async function discoverProjectStores(cwd, env = process.env) {
+  const root = findCliProjectRoot(cwd);
+  const config = fs.existsSync(path.join(root, CONFIG_PATH)) ? readConfig(root) : null;
+  const candidates = [
+    { id: 'runtime:sqlite', driver: 'sqlite', role: 'runtime', path: runtimeDatabasePath(root), selected: true },
+    { id: 'knowledge:sqlite', driver: 'sqlite', role: 'knowledge', path: path.join(root, '.agentsam/knowledge/index.sqlite'), selected: !config || config.storage.driver === 'sqlite', selectable: true },
+  ];
+  const envNames = new Set(['AGENTSAM_DATABASE_URL', 'DATABASE_URL', 'POSTGRES_URL', config?.storage?.connection_env].filter(Boolean));
+  for (const name of envNames) {
+    if (!Object.hasOwn(env, name) && name !== config?.storage?.connection_env) continue;
+    candidates.push({ id: `knowledge:postgres:${name}`, driver: 'postgres', role: 'knowledge', connection_env: name, configured: Boolean(env[name]), selected: config?.storage?.driver === 'postgres' && config.storage.connection_env === name, selectable: true });
+  }
+  const warnings = [];
+  let visited = 0;
+  const skip = new Set(['node_modules', '.git', '.agentsam', '.output', 'dist', 'build', 'vendor', '.wrangler']);
+  const configs = [];
+  function scan(dir, depth) {
+    if (depth > 5 || visited >= 4000) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (++visited >= 4000) break;
+      if (entry.isSymbolicLink() || skip.has(entry.name)) continue;
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) scan(file, depth + 1);
+      else if (['wrangler.json', 'wrangler.jsonc'].includes(entry.name)) configs.push(file);
+      else if (entry.name === 'wrangler.toml') warnings.push(`${path.relative(root, file)}: TOML discovery is not implemented; inspect this configuration explicitly.`);
+    }
+  }
+  scan(root, 0);
+  if (visited >= 4000) warnings.push('Discovery reached its 4000-entry bound; inspect additional config paths explicitly.');
+  if (configs.length) {
+    const { parseConfigFileTextToJson } = await import('typescript');
+    for (const file of configs) {
+      const source = path.relative(root, file);
+      if (fs.statSync(file).size > 1024 * 1024) { warnings.push(`${source}: configuration too large`); continue; }
+      const parsed = parseConfigFileTextToJson(file, fs.readFileSync(file, 'utf8'));
+      if (parsed.error) { warnings.push(`${source}: invalid JSONC`); continue; }
+      const add = (cfg, environment = null) => {
+        for (const [key, driver, label] of [['d1_databases', 'd1', 'database_name'], ['hyperdrive', 'postgres-hyperdrive', 'id'], ['r2_buckets', 'r2', 'bucket_name']]) {
+          for (const binding of Array.isArray(cfg?.[key]) ? cfg[key] : []) {
+            candidates.push({ id: `${source}:${environment || 'default'}:${binding.binding}`, driver, role: 'application', binding: binding.binding, name: binding[label], source, environment, selectable: false, status: 'declared; connectivity not verified' });
+          }
+        }
+      };
+      add(parsed.config);
+      for (const [environment, cfg] of Object.entries(parsed.config?.env || {})) add(cfg, environment);
+    }
+  }
+  return { root, candidates, warnings, knowledge_config: CONFIG_PATH };
+}
+
+export function selectKnowledgeStore(cwd, driver, connectionEnv) {
+  const root = findCliProjectRoot(cwd);
+  if (!['sqlite', 'postgres'].includes(driver)) throw new Error('knowledge_store_adapter_unavailable: choose sqlite or postgres; D1 application bindings retain their existing authority');
+  const filename = path.join(root, CONFIG_PATH);
+  let config;
+  if (fs.existsSync(filename)) config = readConfig(root);
+  else {
+    const repositoryId = getRepositoryId(tryReadProjectConfig(root)) || portableRepositoryIdFromGit(root);
+    if (!repositoryId) throw new Error('repository_identity_required: run agentsam init . --yes first');
+    config = defaultConfig({ repositoryId });
+  }
+  config.storage = driver === 'sqlite' ? { driver } : { driver, connection_env: connectionEnv || 'AGENTSAM_DATABASE_URL' };
+  config = validateConfig(config);
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const temp = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(temp, filename);
+  return { storage: config.storage, config: CONFIG_PATH, next: driver === 'sqlite' ? 'agentsam index run' : 'agentsam index setup-store', note: 'Selection saved. Existing data remains in its original store; no migration or connection probe ran.' };
+}