@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/src/knowledge/engine.js

@@ -3,6 +3,7 @@ import { validateConfig, fingerprint, scopeKey, cacheNamespace, gitEvidence } fr
 import { PARSER, inventory, readSource, parseSource } from './source.js';
 import { createContextPack } from './context-pack.js';
 import { normalizeResultPolicy } from '../context/result-policy.js';
+import { buildMerkleTree } from '../../packages/agentsam-repository/src/merkle/index.js';
 
 export const embeddingProfileId = profile => fingerprint({ ...profile, input_format: 'agentsam-code-content:1' });
 export function validateVector(vector, dimensions) {
@@ -14,20 +15,27 @@ function changes(before = [], after = []) {
   return { added: after.filter(f => !old.has(f.path)).map(f => f.path), changed: after.filter(f => old.has(f.path) && old.get(f.path) !== f.hash).map(f => f.path), removed: before.filter(f => !now.has(f.path)).map(f => f.path) };
 }
 /** Planning never persists, calls an embedding provider, or changes active state. */
-export async function planIndex({ root, config: input, store, embed = false }) {
+export async function planIndex({ root, config: input, store, embed = false, limits = null }) {
   const config = validateConfig(input), scope = scopeKey(config), namespace = cacheNamespace(config);
+  if (embed && config.embedding.provider === 'none') throw new Error('Embedding is explicitly disabled for this knowledge profile. Configure a provider before --embed.');
+  const maxFiles = limits?.maxFiles == null ? Infinity : Number(limits.maxFiles);
+  const maxChunks = limits?.maxChunks == null ? Infinity : Number(limits.maxChunks);
+  if ((maxFiles !== Infinity && (!Number.isInteger(maxFiles) || maxFiles < 1)) || (maxChunks !== Infinity && (!Number.isInteger(maxChunks) || maxChunks < 1))) throw new Error('Index limits must be positive integers.');
   const previous = await store?.active(scope), profileId = embed ? embeddingProfileId(config.embedding) : null;
   const files = [], chunks = [], symbols = [], edges = [], parseWrites = [], skipped = [];
   const parseProfile = fingerprint([PARSER, config.chunking]);
   let parsedFiles = 0;
-  for (const file of inventory(root, config.scope)) {
+  for (const file of inventory(root, config.scope).slice(0, maxFiles)) {
     const source = readSource(root, file);
     if (!source) { skipped.push(file); continue; }
     const key = `${namespace}:parse:${fingerprint([source.hash, file.split('.').pop(), parseProfile])}`;
     let parsed = await store?.cacheGet(key);
     if (!parsed) { parsed = parseSource(file, source.content, config.chunking.max_chars); parseWrites.push([key, parsed]); parsedFiles++; }
     files.push({ path: file, hash: source.hash, bytes: source.bytes, parser: parsed.parser });
-    for (const [ordinal, c] of parsed.chunks.entries()) chunks.push({ ...c, path: file, ordinal, id: fingerprint([file, ordinal, c.content_hash]), embedding_key: embed ? `${namespace}:vector:${profileId}:${c.content_hash}` : null });
+    for (const [ordinal, c] of parsed.chunks.entries()) {
+      if (chunks.length >= maxChunks) break;
+      chunks.push({ ...c, path: file, ordinal, id: fingerprint([file, ordinal, c.content_hash]), embedding_key: embed ? `${namespace}:vector:${profileId}:${c.content_hash}` : null });
+    }
     symbols.push(...parsed.symbols.map(s => ({ ...s, path: file })));
     edges.push(...parsed.edges.map(e => ({ ...e, path: file })));
   }
@@ -36,19 +44,25 @@ export async function planIndex({ root, config: input, store, embed = false }) {
     if (!missing.has(chunk.embedding_key) && !(await store?.cacheGet(chunk.embedding_key))) missing.set(chunk.embedding_key, chunk.content);
   }
   const sourceHash = fingerprint(files.map(f => [f.path, f.hash]));
-  const configHash = fingerprint([config.scope, config.chunking, PARSER, profileId]);
+  const configHash = fingerprint([config.scope, config.chunking, PARSER, profileId, Number.isFinite(maxFiles) ? maxFiles : null, Number.isFinite(maxChunks) ? maxChunks : null]);
+  let merkle = null;
+  try { merkle = await buildMerkleTree(root, { semantic: true }); } catch { merkle = null; }
+  const previousMerkle = previous?.receipt?.merkle_root || null;
+  const changedMerklePaths = merkle && previousMerkle !== merkle.rootHash ? files.filter(file => !previous?.files?.some(before => before.path === file.path && before.hash === file.hash)).map(file => file.path) : [];
   const noChange = previous?.source_hash === sourceHash && previous?.config_hash === configHash && !missing.size;
   return { root, config, previous, files, chunks, symbols, edges, parseWrites, missing,
     receipt: { scope: config.scope, files: files.length, chunks: chunks.length, symbols: symbols.length, edges: edges.length,
       parsed_files: parsedFiles, embedding_inputs: missing.size, embedding_characters: [...missing.values()].reduce((n, s) => n + s.length, 0),
       estimated_tokens: Math.ceil([...missing.values()].reduce((n, s) => n + s.length + 24, 0) / 4), token_estimate_method: 'characters / 4; not billable usage',
-      profile_id: profileId, skipped, changes: changes(previous?.files, files), no_change: Boolean(noChange), source_hash: sourceHash, config_hash: configHash } };
+      profile_id: profileId, skipped, changes: changes(previous?.files, files), no_change: Boolean(noChange), source_hash: sourceHash, config_hash: configHash,
+      merkle_root: merkle?.rootHash || null, semantic_metadata_root: merkle?.semantic?.rootHash || null, merkle_changed_paths: changedMerklePaths,
+      limits: Number.isFinite(maxFiles) || Number.isFinite(maxChunks) ? { max_files: maxFiles, max_chunks: maxChunks } : null } };
 }
 
-export async function runIndex({ root, config, store, embedder, embed = false, maxInputs = 100, maxCharacters = 200000 }) {
+export async function runIndex({ root, config, store, embedder, embed = false, maxInputs = 100, maxCharacters = 200000, limits = null }) {
   if (!store) throw new Error('A writable knowledge store is required.');
   if (!Number.isInteger(maxInputs) || maxInputs < 0 || !Number.isInteger(maxCharacters) || maxCharacters < 0) throw new Error('Embedding budgets must be nonnegative integers.');
-  const plan = await planIndex({ root, config, store, embed });
+  const plan = await planIndex({ root, config, store, embed, limits });
   const { receipt } = plan;
   if (receipt.no_change) return { ...receipt, generation_id: plan.previous.id, published: false };
   if (receipt.embedding_inputs > maxInputs || receipt.embedding_characters > maxCharacters) throw new Error(`Embedding budget exceeded: ${receipt.embedding_inputs} unique inputs / ${receipt.embedding_characters} characters. Review index plan before raising limits.`);
@@ -64,7 +78,8 @@ export async function runIndex({ root, config, store, embedder, embed = false, m
   }
   // A generation describes one coherent source snapshot. Never publish after a mid-run edit.
   const check = [];
-  for (const file of inventory(root, plan.config.scope)) { const source = readSource(root, file); if (source) check.push([file, source.hash]); }
+  const checkFiles = inventory(root, plan.config.scope).slice(0, limits?.maxFiles == null ? Infinity : limits.maxFiles);
+  for (const file of checkFiles) { const source = readSource(root, file); if (source) check.push([file, source.hash]); }
   if (fingerprint(check) !== receipt.source_hash) throw new Error('Repository changed while indexing; cached work retained, active generation unchanged. Rerun.');
   const generation = { id: randomUUID(), scope_key: scopeKey(plan.config), created_at: new Date().toISOString(),
     source_hash: receipt.source_hash, config_hash: receipt.config_hash, config: plan.config, profile_id: receipt.profile_id,

package/src/knowledge/index.js

@@ -8,3 +8,4 @@ export { openSqliteStore } from './stores/sqlite.js';
 export { createPostgresStore, openPostgresStore, postgresSchema } from './stores/postgres.js';
 export { createGeminiEmbedder } from './providers/gemini.js';
 export { compareObservations } from './evolution.js';
+export { normalizeRetrievalLane, selectProjectRetrievalLanes, loadProjectRetrievalLanes } from './lane-registry.js';

package/src/knowledge/lane-registry.js

@@ -0,0 +1,46 @@
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function json(value, fallback = {}) { try { return JSON.parse(String(value || '')); } catch { return fallback; } }
+
+export function normalizeRetrievalLane(row = {}) {
+  return Object.freeze({
+    id: clean(row.id),
+    account_id: clean(row.account_id) || null,
+    repository_id: clean(row.repository_id) || null,
+    database_id: clean(row.database_id) || null,
+    backend_kind: clean(row.backend_kind || 'pgvector'),
+    provider_key: clean(row.provider_key) || null,
+    resource_id: clean(row.resource_id) || null,
+    binding_name: clean(row.binding_name) || null,
+    index_name: clean(row.index_name) || null,
+    // Namespace is provider/project-owned. Never silently force the shared
+    // `agentsam` schema onto a new application's retrieval lane.
+    schema_name: clean(row.schema_name) || null,
+    table_name: clean(row.table_name),
+    purpose: clean(row.purpose),
+    dimensions: Number(row.dimensions) || null,
+    metric: clean(row.metric || 'cosine'),
+    embedding_model: clean(row.embedding_model) || null,
+    metadata: json(row.metadata_json, {}),
+    is_active: Number(row.is_active) === 1,
+  });
+}
+
+/** Project selection is explicit; no global preferred vector store exists. */
+export function selectProjectRetrievalLanes(rows, { accountId, repositoryId, purpose } = {}) {
+  const account = clean(accountId);
+  const repository = clean(repositoryId);
+  if (!account || !repository) throw new Error('project_retrieval_identity_required');
+  return (Array.isArray(rows) ? rows : [])
+    .map(normalizeRetrievalLane)
+    .filter((lane) => lane.is_active && lane.account_id === account && lane.repository_id === repository && (!purpose || lane.purpose === purpose));
+}
+
+export async function loadProjectRetrievalLanes(db, identity = {}) {
+  if (!db?.prepare) throw new TypeError('database_required');
+  const result = await db.prepare(`
+    SELECT * FROM agentsam_pgvector_lane_registry
+    WHERE account_id = ? AND repository_id = ? AND is_active = 1
+    ORDER BY purpose, id
+  `).bind(clean(identity.accountId), clean(identity.repositoryId)).all();
+  return selectProjectRetrievalLanes(result?.results || [], identity);
+}

package/src/knowledge/providers/gemini.js

@@ -1,12 +1,20 @@
+import { AgentSamError, classifyGeminiFailure } from '../../errors/index.js';
+
 /** Gemini Embedding 2 adapter; profile is supplied per job, never read globally. */
 export function createGeminiEmbedder({ apiKey, fetchImpl = globalThis.fetch, sleep = ms => new Promise(r => setTimeout(r, ms)), maxAttempts = 3, timeoutMs = 30000 } = {}) {
-  if (!apiKey) throw new Error('GEMINI_API_KEY is required only for embedding/search with --semantic.');
-  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 5) throw new Error('maxAttempts must be 1..5.');
+  if (!apiKey) throw new AgentSamError(classifyGeminiFailure({
+    credential_state: 'missing',
+    message: 'GEMINI_API_KEY is required only for embedding/search with --semantic.',
+  }, { domain: 'knowledge', tool: 'gemini', stage: 'embedding' }));
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 5) throw new AgentSamError(classifyGeminiFailure({
+    status: 400,
+    message: 'maxAttempts must be 1..5.',
+  }, { domain: 'knowledge', tool: 'gemini', stage: 'configuration', request_origin: 'user' }));
   return {
     validate(profile) {
-      if (profile.provider !== 'gemini' || profile.model !== 'gemini-embedding-2') throw new Error('This adapter supports gemini-embedding-2; inject a different adapter for other models.');
-      if (profile.dimensions < 128 || profile.dimensions > 3072) throw new Error('Gemini Embedding 2 dimensions must be 128..3072.');
-      if (Object.keys(profile.parameters).some(k => k !== 'task') || !['code retrieval', 'search result', 'question answering'].includes(profile.parameters.task)) throw new Error('Unsupported Gemini embedding parameters.');
+      if (profile.provider !== 'gemini' || profile.model !== 'gemini-embedding-2') throw new AgentSamError(classifyGeminiFailure({ status: 400, message: 'This adapter supports gemini-embedding-2; inject a different adapter for other models.' }, { domain: 'knowledge', tool: 'gemini', stage: 'configuration', request_origin: 'user' }));
+      if (profile.dimensions < 128 || profile.dimensions > 3072) throw new AgentSamError(classifyGeminiFailure({ status: 400, message: 'Gemini Embedding 2 dimensions must be 128..3072.' }, { domain: 'knowledge', tool: 'gemini', stage: 'configuration', request_origin: 'user' }));
+      if (Object.keys(profile.parameters).some(k => k !== 'task') || !['code retrieval', 'search result', 'question answering'].includes(profile.parameters.task)) throw new AgentSamError(classifyGeminiFailure({ status: 400, message: 'Unsupported Gemini embedding parameters.' }, { domain: 'knowledge', tool: 'gemini', stage: 'configuration', request_origin: 'user' }));
     },
     async embed(text, profile, { kind = 'document' } = {}) {
       this.validate(profile);
@@ -19,10 +27,42 @@ export function createGeminiEmbedder({ apiKey, fetchImpl = globalThis.fetch, sle
             method: 'POST', headers: { 'Content-Type': 'application/json', 'x-goog-api-key': apiKey }, signal: AbortSignal.timeout(timeoutMs),
             body: JSON.stringify({ model: `models/${profile.model}`, content: { parts: [{ text: input }] }, outputDimensionality: profile.dimensions }),
           });
-        } catch { if (attempt + 1 === maxAttempts) throw new Error('Gemini embedding request failed or timed out.'); }
+        } catch (cause) {
+          if (attempt + 1 === maxAttempts) {
+            throw new AgentSamError(classifyGeminiFailure({
+              status: 504,
+              status_name: 'UNAVAILABLE',
+              message: 'Gemini embedding request failed or timed out.',
+              exception_type: cause?.name,
+              stack: cause?.stack,
+            }, { domain: 'knowledge', tool: 'gemini', stage: 'embedding', reason: 'transport_timeout' }), { cause });
+          }
+        }
         if (response?.ok) return (await response.json()).embedding?.values;
-        if (response && ![408, 429, 500, 502, 503, 504].includes(response.status)) throw new Error(`Gemini embedding failed (HTTP ${response.status}).`);
-        if (attempt + 1 === maxAttempts) throw new Error(`Gemini embedding retry limit reached${response ? ` (HTTP ${response.status})` : ''}.`);
+        let providerBody = null;
+        if (response) {
+          try { providerBody = await response.clone().json(); } catch { providerBody = null; }
+        }
+        if (response && ![408, 429, 500, 502, 503, 504].includes(response.status)) {
+          throw new AgentSamError(classifyGeminiFailure({
+            status: response.status,
+            status_name: providerBody?.error?.status,
+            code: providerBody?.error?.code,
+            message: providerBody?.error?.message || `Gemini embedding failed (HTTP ${response.status}).`,
+            headers: response.headers,
+            body: providerBody,
+          }, { domain: 'knowledge', tool: 'gemini', stage: 'embedding', request_origin: 'agentsam' }));
+        }
+        if (attempt + 1 === maxAttempts) {
+          throw new AgentSamError(classifyGeminiFailure({
+            status: response?.status || 503,
+            status_name: providerBody?.error?.status,
+            code: providerBody?.error?.code,
+            message: providerBody?.error?.message || `Gemini embedding retry limit reached${response ? ` (HTTP ${response.status})` : ''}.`,
+            headers: response?.headers,
+            body: providerBody,
+          }, { domain: 'knowledge', tool: 'gemini', stage: 'embedding' }));
+        }
         await response?.body?.cancel();
         await sleep(Math.min(10000, 500 * 2 ** attempt + Math.floor(Math.random() * 250)));
       }

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,
   });
 }