@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.1

package/src/errors/contract.js

@@ -0,0 +1,236 @@
+export const ERROR_SCHEMA_VERSION = 1;
+
+// Mirrors google.rpc.Code / gRPC canonical status names without importing a Node gRPC runtime.
+export const ERROR_CODE = Object.freeze({
+  OK: 'OK',
+  CANCELLED: 'CANCELLED',
+  UNKNOWN: 'UNKNOWN',
+  INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+  DEADLINE_EXCEEDED: 'DEADLINE_EXCEEDED',
+  NOT_FOUND: 'NOT_FOUND',
+  ALREADY_EXISTS: 'ALREADY_EXISTS',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+  RESOURCE_EXHAUSTED: 'RESOURCE_EXHAUSTED',
+  FAILED_PRECONDITION: 'FAILED_PRECONDITION',
+  ABORTED: 'ABORTED',
+  OUT_OF_RANGE: 'OUT_OF_RANGE',
+  UNIMPLEMENTED: 'UNIMPLEMENTED',
+  INTERNAL: 'INTERNAL',
+  UNAVAILABLE: 'UNAVAILABLE',
+  DATA_LOSS: 'DATA_LOSS',
+  UNAUTHENTICATED: 'UNAUTHENTICATED',
+});
+
+export const GRPC_STATUS = Object.freeze({
+  OK: 0,
+  CANCELLED: 1,
+  UNKNOWN: 2,
+  INVALID_ARGUMENT: 3,
+  DEADLINE_EXCEEDED: 4,
+  NOT_FOUND: 5,
+  ALREADY_EXISTS: 6,
+  PERMISSION_DENIED: 7,
+  RESOURCE_EXHAUSTED: 8,
+  FAILED_PRECONDITION: 9,
+  ABORTED: 10,
+  OUT_OF_RANGE: 11,
+  UNIMPLEMENTED: 12,
+  INTERNAL: 13,
+  UNAVAILABLE: 14,
+  DATA_LOSS: 15,
+  UNAUTHENTICATED: 16,
+});
+
+// Stable AgentSam-specific reasons. Add reasons deliberately; callers should not branch on messages.
+export const ERROR_REASON = Object.freeze({
+  UNKNOWN: 'unknown',
+
+  INPUT_INVALID: 'input_invalid',
+  INPUT_OUT_OF_RANGE: 'input_out_of_range',
+  PRECONDITION_FAILED: 'precondition_failed',
+  UNSUPPORTED_OPERATION: 'unsupported_operation',
+
+  AUTH_MISSING: 'auth_missing',
+  AUTH_INVALID: 'auth_invalid',
+  IDENTITY_MISSING: 'identity_missing',
+  PERMISSION_DENIED: 'permission_denied',
+
+  TARGET_NOT_FOUND: 'target_not_found',
+  ALREADY_EXISTS: 'already_exists',
+  CONFLICT: 'conflict',
+  STALE_VERSION: 'stale_version',
+
+  RATE_LIMITED: 'rate_limited',
+  QUOTA_EXHAUSTED: 'quota_exhausted',
+  CAPACITY_EXHAUSTED: 'capacity_exhausted',
+
+  TRANSPORT_UNREACHABLE: 'transport_unreachable',
+  TRANSPORT_REFUSED: 'transport_refused',
+  TRANSPORT_TIMEOUT: 'transport_timeout',
+  UPSTREAM_INVALID_RESPONSE: 'upstream_invalid_response',
+  DNS_UNRESOLVED: 'dns_unresolved',
+  TLS_HANDSHAKE_FAILED: 'tls_handshake_failed',
+  TLS_CERTIFICATE_INVALID: 'tls_certificate_invalid',
+  TUNNEL_CONNECTOR_UNAVAILABLE: 'tunnel_connector_unavailable',
+
+  CANCELLED: 'cancelled',
+  DEADLINE_EXCEEDED: 'deadline_exceeded',
+  EXECUTION_TIMEOUT: 'execution_timeout',
+  EXECUTION_FAILED: 'execution_failed',
+
+  PROVIDER_UNAVAILABLE: 'provider_unavailable',
+  MODEL_NOT_FOUND: 'model_not_found',
+  POLICY_BLOCKED: 'policy_blocked',
+  COPYRIGHT_BLOCKED: 'copyright_blocked',
+
+  PERSISTENCE_FAILED: 'persistence_failed',
+  DATA_CORRUPT: 'data_corrupt',
+  DATA_LOSS: 'data_loss',
+
+  REPOSITORY_SCOPE_VIOLATION: 'repository_scope_violation',
+  REPOSITORY_CHANGED: 'repository_changed',
+  INDEX_STALE: 'index_stale',
+  INDEX_FAILED: 'index_failed',
+  EMBEDDING_FAILED: 'embedding_failed',
+  VECTOR_STORE_FAILED: 'vector_store_failed',
+
+  CAD_CONSTRAINT_UNSATISFIED: 'cad_constraint_unsatisfied',
+  CAD_GEOMETRY_INVALID: 'cad_geometry_invalid',
+  CAD_KERNEL_FAILED: 'cad_kernel_failed',
+  CAD_EXPORT_FAILED: 'cad_export_failed',
+  CAD_RENDER_FAILED: 'cad_render_failed',
+
+  INTERNAL: 'internal',
+});
+
+const DEFAULT_HTTP_STATUS = Object.freeze({
+  [ERROR_CODE.CANCELLED]: 499,
+  [ERROR_CODE.UNKNOWN]: 500,
+  [ERROR_CODE.INVALID_ARGUMENT]: 400,
+  [ERROR_CODE.DEADLINE_EXCEEDED]: 504,
+  [ERROR_CODE.NOT_FOUND]: 404,
+  [ERROR_CODE.ALREADY_EXISTS]: 409,
+  [ERROR_CODE.PERMISSION_DENIED]: 403,
+  [ERROR_CODE.RESOURCE_EXHAUSTED]: 429,
+  [ERROR_CODE.FAILED_PRECONDITION]: 400,
+  [ERROR_CODE.ABORTED]: 409,
+  [ERROR_CODE.OUT_OF_RANGE]: 400,
+  [ERROR_CODE.UNIMPLEMENTED]: 501,
+  [ERROR_CODE.INTERNAL]: 500,
+  [ERROR_CODE.UNAVAILABLE]: 503,
+  [ERROR_CODE.DATA_LOSS]: 500,
+  [ERROR_CODE.UNAUTHENTICATED]: 401,
+});
+
+const HTTP_CODE_OVERRIDES = Object.freeze({
+  400: ERROR_CODE.INVALID_ARGUMENT,
+  401: ERROR_CODE.UNAUTHENTICATED,
+  403: ERROR_CODE.PERMISSION_DENIED,
+  404: ERROR_CODE.NOT_FOUND,
+  408: ERROR_CODE.DEADLINE_EXCEEDED,
+  409: ERROR_CODE.ABORTED,
+  412: ERROR_CODE.FAILED_PRECONDITION,
+  413: ERROR_CODE.RESOURCE_EXHAUSTED,
+  415: ERROR_CODE.INVALID_ARGUMENT,
+  422: ERROR_CODE.INVALID_ARGUMENT,
+  429: ERROR_CODE.RESOURCE_EXHAUSTED,
+  499: ERROR_CODE.CANCELLED,
+  500: ERROR_CODE.INTERNAL,
+  501: ERROR_CODE.UNIMPLEMENTED,
+  502: ERROR_CODE.UNAVAILABLE,
+  503: ERROR_CODE.UNAVAILABLE,
+  504: ERROR_CODE.DEADLINE_EXCEEDED,
+  520: ERROR_CODE.UNAVAILABLE,
+  521: ERROR_CODE.UNAVAILABLE,
+  522: ERROR_CODE.UNAVAILABLE,
+  523: ERROR_CODE.UNAVAILABLE,
+  524: ERROR_CODE.DEADLINE_EXCEEDED,
+  525: ERROR_CODE.UNAVAILABLE,
+  526: ERROR_CODE.UNAVAILABLE,
+  530: ERROR_CODE.UNAVAILABLE,
+});
+
+const GRPC_CODE_BY_NUMBER = new Map(Object.entries(GRPC_STATUS).map(([name, value]) => [value, ERROR_CODE[name]]));
+
+export function canonicalCodeFromHttpStatus(status) {
+  return HTTP_CODE_OVERRIDES[Number(status)] || (Number(status) >= 500 ? ERROR_CODE.INTERNAL : ERROR_CODE.UNKNOWN);
+}
+
+export function canonicalCodeFromGrpcStatus(status) {
+  return GRPC_CODE_BY_NUMBER.get(Number(status)) || ERROR_CODE.UNKNOWN;
+}
+
+export function defaultHttpStatusForCode(code) {
+  return DEFAULT_HTTP_STATUS[code] || 500;
+}
+
+export function grpcStatusForCode(code) {
+  return GRPC_STATUS[code] ?? GRPC_STATUS.UNKNOWN;
+}
+
+export function classifyCloudflareFailure({ httpStatus, cloudflareCode } = {}) {
+  const status = Number(httpStatus || 0) || null;
+  const cf = Number(cloudflareCode || 0) || null;
+  if (cf === 1033) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TUNNEL_CONNECTOR_UNAVAILABLE, retryable: true };
+  if (status === 521) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TRANSPORT_REFUSED, retryable: true };
+  if (status === 522 || status === 523) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TRANSPORT_UNREACHABLE, retryable: true };
+  if (status === 524) return { code: ERROR_CODE.DEADLINE_EXCEEDED, reason: ERROR_REASON.TRANSPORT_TIMEOUT, retryable: true };
+  if (status === 525) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TLS_HANDSHAKE_FAILED, retryable: false };
+  if (status === 526) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TLS_CERTIFICATE_INVALID, retryable: false };
+  if (status === 520 || status === 502) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.UPSTREAM_INVALID_RESPONSE, retryable: true };
+  if (status === 530) return { code: ERROR_CODE.UNAVAILABLE, reason: ERROR_REASON.TRANSPORT_UNREACHABLE, retryable: true };
+  return { code: canonicalCodeFromHttpStatus(status), reason: ERROR_REASON.UNKNOWN, retryable: status != null && status >= 500 };
+}
+
+export function classifyOAuthFailure(error) {
+  switch (String(error || '').toLowerCase()) {
+    case 'invalid_client': return { code: ERROR_CODE.UNAUTHENTICATED, reason: ERROR_REASON.AUTH_INVALID, retryable: false };
+    case 'invalid_grant': return { code: ERROR_CODE.UNAUTHENTICATED, reason: ERROR_REASON.AUTH_INVALID, retryable: false };
+    case 'unauthorized_client':
+    case 'access_denied': return { code: ERROR_CODE.PERMISSION_DENIED, reason: ERROR_REASON.PERMISSION_DENIED, retryable: false };
+    case 'invalid_scope':
+    case 'invalid_request':
+    case 'unsupported_grant_type': return { code: ERROR_CODE.INVALID_ARGUMENT, reason: ERROR_REASON.INPUT_INVALID, retryable: false };
+    default: return { code: ERROR_CODE.UNKNOWN, reason: ERROR_REASON.UNKNOWN, retryable: false };
+  }
+}
+
+export function createErrorEnvelope({
+  code = ERROR_CODE.UNKNOWN,
+  reason = ERROR_REASON.UNKNOWN,
+  message = 'Operation failed',
+  retryable = false,
+  retry_after_ms = null,
+  http_status = null,
+  grpc_status = null,
+  provider = null,
+  provider_code = null,
+  transport = null,
+  request_id = null,
+  trace_id = null,
+  resource = null,
+  details = null,
+} = {}) {
+  if (!Object.values(ERROR_CODE).includes(code)) throw new TypeError(`Unknown AgentSam error code: ${code}`);
+  if (!Object.values(ERROR_REASON).includes(reason)) throw new TypeError(`Unknown AgentSam error reason: ${reason}`);
+  const effectiveHttp = http_status == null ? defaultHttpStatusForCode(code) : Number(http_status);
+  const effectiveGrpc = grpc_status == null ? grpcStatusForCode(code) : Number(grpc_status);
+  return Object.freeze({
+    ok: false,
+    schema_version: ERROR_SCHEMA_VERSION,
+    code,
+    reason,
+    message: String(message || 'Operation failed'),
+    retryable: Boolean(retryable),
+    retry_after_ms: retry_after_ms == null ? null : Math.max(0, Number(retry_after_ms)),
+    http_status: Number.isInteger(effectiveHttp) ? effectiveHttp : null,
+    grpc_status: Number.isInteger(effectiveGrpc) ? effectiveGrpc : null,
+    provider: provider || null,
+    provider_code: provider_code || null,
+    transport: transport || null,
+    request_id: request_id || null,
+    trace_id: trace_id || null,
+    resource: resource || null,
+    details: details || null,
+  });
+}

package/src/errors/index.js

@@ -1,3 +1,17 @@
+export {
+  ERROR_SCHEMA_VERSION,
+  ERROR_CODE,
+  ERROR_REASON,
+  GRPC_STATUS,
+  canonicalCodeFromHttpStatus,
+  canonicalCodeFromGrpcStatus,
+  defaultHttpStatusForCode,
+  grpcStatusForCode,
+  classifyCloudflareFailure,
+  classifyOAuthFailure,
+  createErrorEnvelope,
+} from './contract.js';
+
 export {
   AgentSamDiagnosticError,
   classifyOpenAIError,

package/src/index.js

@@ -19,7 +19,7 @@ export {
   normalizeGitRemote,
   resolveGitContext,
   tryResolveGitContext,
-} from './lib/git-context.js';
+} from '../packages/agentsam-repository/src/git-context.js';
 export {
   resolveAgentSamBaseUrl,
   resolveBridgeKey,
@@ -40,6 +40,18 @@ export {
   repositorySnapshot,
 } from './capabilities/index.js';
 export { getPreset, listPresets, resolvePreset, getAddon, listAddons } from './presets/index.js';
+export {
+  COMPANY_REPOSITORY_GRAPH_SCHEMA_VERSION,
+  REPOSITORY_STATUSES,
+  REPOSITORY_CONTRACT_TYPES,
+  REPOSITORY_CONTRACT_STATUSES,
+  REPOSITORY_DEPENDENCY_TYPES,
+  REPOSITORY_DEPENDENCY_CRITICALITIES,
+  REPOSITORY_FAILURE_POLICIES,
+  createRepositoryIdentity,
+  createRepositoryContract,
+  createRepositoryDependency,
+} from '../packages/agentsam-repository/src/contracts.js';
 export {
   DEFAULT_CONTEXT_RATIOS,
   DEFAULT_RESULT_POLICY,

package/src/knowledge/service/auth.js

@@ -0,0 +1,13 @@
+import { timingSafeEqual } from 'node:crypto';
+
+export function createBearerTokenVerifier(token) {
+  if (typeof token !== 'string' || token.length < 32 || token.length > 256) {
+    throw new Error('Service token must be 32..256 characters.');
+  }
+  const secret = Buffer.from(token);
+  return authorization => {
+    const raw = typeof authorization === 'string' ? authorization : '';
+    const provided = Buffer.from(raw.replace(/^Bearer /, ''));
+    return provided.length === secret.length && timingSafeEqual(provided, secret);
+  };
+}

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

@@ -0,0 +1,115 @@
+import {
+  grpc,
+  KnowledgeServiceClient,
+  decodeJob,
+  decodeJobEvent,
+  decodeRepositoryList,
+  encodeGetJobRequest,
+  encodeSubmitRequest,
+  fromGrpcError,
+  knowledgePb,
+  metadataForToken,
+} from './grpc-codec.js';
+
+function normalizeTimeout(value, fallback) {
+  const timeout = value === undefined ? fallback : value;
+  if (timeout == null) return null;
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('timeoutMs must be a positive number or null.');
+  return timeout;
+}
+
+function validateJobId(id) {
+  if (typeof id !== 'string' || !/^[a-f0-9-]{36}$/.test(id)) throw new Error('Invalid job id.');
+  return id;
+}
+
+/** Node/native gRPC client. Keep this separate from the fetch-only Worker-safe client. */
+export function createKnowledgeGrpcClient({
+  target,
+  token,
+  timeoutMs = 15000,
+  credentials = grpc.credentials.createInsecure(),
+  clientOptions,
+} = {}) {
+  if (typeof target !== 'string' || !target.trim()) throw new Error('A gRPC target is required.');
+  if (!token) throw new Error('A service token is required.');
+  const client = new KnowledgeServiceClient(target.trim(), credentials, clientOptions);
+
+  const unary = (method, request, options = {}) => new Promise((resolve, reject) => {
+    const timeout = normalizeTimeout(options.timeoutMs, timeoutMs);
+    const callOptions = timeout == null ? {} : { deadline: new Date(Date.now() + timeout) };
+    client[method](request, metadataForToken(token), callOptions, (error, response) => {
+      if (error) reject(fromGrpcError(error));
+      else resolve(response);
+    });
+  });
+
+  async function repositories(options = {}) {
+    const response = await unary('listRepositories', new knowledgePb.ListRepositoriesRequest(), options);
+    return decodeRepositoryList(response);
+  }
+
+  async function submit(body, idempotencyKey, options = {}) {
+    const response = await unary('submitJob', encodeSubmitRequest(body, idempotencyKey), options);
+    return decodeJob(response);
+  }
+
+  async function job(id, options = {}) {
+    const response = await unary('getJob', encodeGetJobRequest(validateJobId(id)), options);
+    return decodeJob(response);
+  }
+
+  async function* watch(id, options = {}) {
+    validateJobId(id);
+    const timeout = normalizeTimeout(options.timeoutMs, null);
+    const callOptions = timeout == null ? {} : { deadline: new Date(Date.now() + timeout) };
+    const stream = client.watchJob(
+      encodeGetJobRequest(id, knowledgePb.WatchJobRequest),
+      metadataForToken(token),
+      callOptions,
+    );
+    const queue = [];
+    let done = false;
+    let failure = null;
+    let wake = null;
+    const notify = () => { const resolve = wake; wake = null; resolve?.(); };
+    const onData = event => { queue.push(decodeJobEvent(event)); notify(); };
+    const onEnd = () => { done = true; notify(); };
+    const onError = error => {
+      if (options.signal?.aborted && error?.code === grpc.status.CANCELLED) {
+        done = true;
+      } else {
+        failure = fromGrpcError(error);
+        done = true;
+      }
+      notify();
+    };
+    const onAbort = () => stream.cancel();
+    stream.on('data', onData);
+    stream.once('end', onEnd);
+    stream.once('error', onError);
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    if (options.signal?.aborted) onAbort();
+
+    try {
+      while (!done || queue.length) {
+        if (!queue.length) await new Promise(resolve => { wake = resolve; });
+        while (queue.length) yield queue.shift();
+        if (failure) throw failure;
+      }
+      if (failure) throw failure;
+    } finally {
+      options.signal?.removeEventListener('abort', onAbort);
+      stream.off('data', onData);
+      if (!done) stream.cancel();
+    }
+  }
+
+  return Object.freeze({
+    repositories,
+    submit,
+    job,
+    watch,
+    close() { client.close(); },
+  });
+}

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'; }