@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/packages/agentsam-brand/src/presets/product-shot.json

@@ -0,0 +1,11 @@
+{
+  "id": "product-shot",
+  "label": "Product / UI screenshot",
+  "description": "Preserve raw PNG; optional thumb + marketing widths",
+  "role": "product.raw",
+  "semantic": true,
+  "derivatives": [
+    { "id": "thumb-640", "role": "thumb", "format": "png", "width": 640, "height": 640 },
+    { "id": "card-960", "role": "card", "format": "webp", "width": 960, "height": 960, "quality": 90 }
+  ]
+}

package/packages/agentsam-brand/src/presets/social-image.json

@@ -0,0 +1,10 @@
+{
+  "id": "social-image",
+  "label": "Social media set",
+  "description": "OG/Twitter-oriented 1200×630 raster + web formats",
+  "derivatives": [
+    { "id": "png-1200x630", "role": "raster", "format": "png", "width": 1200, "height": 630 },
+    { "id": "webp-1200x630", "role": "web", "format": "webp", "width": 1200, "height": 630, "quality": 90 },
+    { "id": "avif-1200x630", "role": "web", "format": "avif", "width": 1200, "height": 630, "quality": 75 }
+  ]
+}

package/packages/agentsam-brand/src/presets/web-image.json

@@ -0,0 +1,10 @@
+{
+  "id": "web-image",
+  "label": "Standard web image set",
+  "description": "Primary PNG + WebP + AVIF at source dimensions proxy 1600",
+  "derivatives": [
+    { "id": "png-1600", "role": "raster", "format": "png", "width": 1600, "height": 1600 },
+    { "id": "webp-1600", "role": "web", "format": "webp", "width": 1600, "height": 1600, "quality": 90 },
+    { "id": "avif-1600", "role": "web", "format": "avif", "width": 1600, "height": 1600, "quality": 75 }
+  ]
+}

package/packages/agentsam-contracts/src/artifacts.ts

@@ -12,12 +12,53 @@ export type AgentArtifactKind =
 
 export interface AgentAttachment {
   id: string;
+  /** @deprecated prefer kind — kept for backward compatibility */
   name: string;
   mimeType?: string;
   size?: number;
+  /** @deprecated text-file shortcut — do not use for images */
   text?: string;
   url?: string;
   metadata?: Record<string, unknown>;
+
+  /** Structured multimodal fields (v1+) */
+  kind?:
+    | 'image'
+    | 'document'
+    | 'text'
+    | 'archive'
+    | 'audio'
+    | 'video'
+    | 'model'
+    | 'binary';
+  source?:
+    | { type: 'local_path'; path: string }
+    | { type: 'blob'; blobId: string }
+    | { type: 'url'; url: string }
+    | { type: 'r2'; bucket: string; key: string }
+    | { type: 'artifact'; artifactId: string };
+  sha256?: string;
+  image?: {
+    width: number;
+    height: number;
+    alpha?: boolean;
+    orientation?: number;
+  };
+  preview?: {
+    url?: string;
+    localPath?: string;
+  };
+  inference?: {
+    mimeType: string;
+    source:
+      | { type: 'local_path'; path: string }
+      | { type: 'blob'; blobId: string }
+      | { type: 'url'; url: string };
+    width?: number;
+    height?: number;
+    bytes?: number;
+  };
+  lifetime?: 'ephemeral' | 'conversation' | 'project' | 'artifact' | 'brand';
 }
 
 export interface AgentArtifact {

package/packages/agentsam-contracts/src/errors.ts

@@ -1,4 +1,5 @@
 // GENERATED by scripts/generate-error-contracts.mjs. Do not edit by hand.
+
 export const AGENTSAM_ERROR_SCHEMA_VERSION = 1 as const;
 
 export type AgentSamErrorCode = "OK" | "CANCELLED" | "UNKNOWN" | "INVALID_ARGUMENT" | "DEADLINE_EXCEEDED" | "NOT_FOUND" | "ALREADY_EXISTS" | "PERMISSION_DENIED" | "RESOURCE_EXHAUSTED" | "FAILED_PRECONDITION" | "ABORTED" | "OUT_OF_RANGE" | "UNIMPLEMENTED" | "INTERNAL" | "UNAVAILABLE" | "DATA_LOSS" | "UNAUTHENTICATED";
@@ -8,12 +9,19 @@ export type AgentSamErrorSourceKind = "user" | "agentsam" | "provider" | "depend
 export type AgentSamErrorResolutionOwner = "user" | "agentsam" | "provider" | "organization_admin" | "policy" | "unknown";
 export type AgentSamErrorDomain = "runtime" | "provider" | "auth" | "device" | "terminal" | "transport" | "repository" | "indexing" | "knowledge" | "cad" | "deployment" | "persistence" | "policy" | "tool";
 export type AgentSamRemediationAction = "none" | "retry" | "retry_later" | "reauthenticate" | "connect_provider" | "configure_provider_credential" | "refresh_provider_credential" | "request_permission" | "reenroll_device" | "reconnect_service" | "install_dependency" | "upgrade_dependency" | "configure_dependency" | "change_configuration" | "change_input" | "reduce_scope" | "increase_quota" | "add_budget" | "select_model" | "change_region" | "restart_runtime" | "inspect_platform" | "contact_provider" | "contact_agentsam" | "contact_organization_admin";
+export type AgentSamErrorSideEffectState = "none" | "not_started" | "confirmed_not_applied" | "confirmed_applied" | "partially_applied" | "unknown";
+export type AgentSamErrorOutcomeStatus = "success" | "partial" | "failure";
 
 export interface AgentSamErrorSource { kind: AgentSamErrorSourceKind; name: string; service: string | null; }
 export interface AgentSamErrorRemediation { action: AgentSamRemediationAction; message: string | null; automatic: boolean; command: string | null; url: string | null; }
 export interface AgentSamErrorResource { type: string; id: string | null; name: string | null; }
 export interface AgentSamNativeErrorEvidence { code: string | null; exception_type: string | null; exit_code: number | null; signal: string | null; stderr: string | null; stdout: string | null; stack: string | null; }
 export interface AgentSamEnvironmentEvidence { detected_version: string | null; required_version: string | null; component: string | null; runtime: string | null; platform: string | null; }
+export interface AgentSamErrorOperation { kind?: string | null; action?: string | null; resource_type?: string | null; resource_id?: string | null; read_only?: boolean; idempotent?: boolean; side_effect_state?: AgentSamErrorSideEffectState; }
+export interface AgentSamErrorRetry { allowed?: boolean; strategy?: string; retry_after_ms?: number | null; max_attempts?: number | null; requires_idempotency_key?: boolean; }
+export interface AgentSamErrorFallback { allowed?: boolean; strategy?: string | null; preserve_semantics?: boolean; target?: string | null; }
+export interface AgentSamErrorNotification { user?: string; operator?: string; agent?: string; }
+export interface AgentSamErrorPartialResult { completed?: number; failed?: number; failures?: unknown[]; }
 
 export interface AgentSamErrorEnvelope {
   ok: false;
@@ -43,4 +51,12 @@ export interface AgentSamErrorEnvelope {
   fingerprint: string;
   occurrence_count: number;
   details: unknown;
+  failure_class?: string;
+  operation?: AgentSamErrorOperation;
+  retry?: AgentSamErrorRetry;
+  fallback?: AgentSamErrorFallback;
+  notify?: AgentSamErrorNotification;
+  cause?: unknown;
+  status?: AgentSamErrorOutcomeStatus;
+  partial?: AgentSamErrorPartialResult;
 }

package/packages/agentsam-errors/src/envelope.js

@@ -166,6 +166,59 @@ export function createErrorEnvelope(input = {}) {
   if (!Number.isInteger(envelope.http_status) || envelope.http_status < 100 || envelope.http_status > 599) envelope.http_status = null;
   if (!Number.isInteger(envelope.grpc_status) || envelope.grpc_status < 0 || envelope.grpc_status > 16) envelope.grpc_status = null;
   envelope.fingerprint = optional(input.fingerprint, 128) || fingerprintError(envelope);
+
+  // Optional recovery dimensions (v1-compatible extras — orthogonal to reason enum)
+  const failureClass = input.failure_class || null;
+  if (failureClass) envelope.failure_class = clean(failureClass);
+  if (input.operation && typeof input.operation === 'object') {
+    envelope.operation = Object.freeze({
+      kind: optional(input.operation.kind, 256),
+      action: optional(input.operation.action, 256),
+      resource_type: optional(input.operation.resource_type, 128),
+      resource_id: optional(input.operation.resource_id, 512),
+      read_only: input.operation.read_only === true,
+      idempotent: input.operation.idempotent === true,
+      side_effect_state: optional(input.operation.side_effect_state, 64) || 'unknown',
+    });
+  }
+  if (input.retry && typeof input.retry === 'object') {
+    envelope.retry = Object.freeze({
+      allowed: input.retry.allowed == null ? retryable : Boolean(input.retry.allowed),
+      strategy: optional(input.retry.strategy, 64) || (retryable ? 'exponential_backoff' : 'none'),
+      retry_after_ms: input.retry.retry_after_ms == null ? envelope.retry_after_ms : Math.max(0, Math.round(Number(input.retry.retry_after_ms) || 0)),
+      max_attempts: Number.isInteger(input.retry.max_attempts) ? input.retry.max_attempts : null,
+      requires_idempotency_key: input.retry.requires_idempotency_key === true,
+    });
+  }
+  if (input.fallback && typeof input.fallback === 'object') {
+    envelope.fallback = Object.freeze({
+      allowed: Boolean(input.fallback.allowed),
+      strategy: optional(input.fallback.strategy, 64),
+      preserve_semantics: input.fallback.preserve_semantics !== false,
+      target: optional(input.fallback.target, 256),
+    });
+  }
+  if (input.notify && typeof input.notify === 'object') {
+    envelope.notify = Object.freeze({
+      user: optional(input.notify.user, 64) || 'immediately',
+      operator: optional(input.notify.operator, 64) || 'never',
+      agent: optional(input.notify.agent, 64) || 'stop',
+    });
+  }
+  if (input.cause && typeof input.cause === 'object') {
+    envelope.cause = input.cause;
+  }
+  if (input.status === 'partial' || input.status === 'success' || input.status === 'failure') {
+    envelope.status = input.status;
+  }
+  if (input.completed != null || input.failed != null) {
+    envelope.partial = Object.freeze({
+      completed: Number(input.completed) || 0,
+      failed: Number(input.failed) || 0,
+      failures: Array.isArray(input.failures) ? input.failures : [],
+    });
+  }
+
   return deepFreeze(envelope);
 }
 

package/packages/agentsam-errors/src/index.js

@@ -5,6 +5,7 @@ export * from './normalize.js';
 export * from './redaction.js';
 export * from './fingerprint.js';
 export * from './retry.js';
+export * from './recovery.js';
 export * from './transport.js';
 export * from './render.js';
 export * from './adapters/index.js';

package/packages/agentsam-errors/src/recovery.js

@@ -0,0 +1,301 @@
+/**
+ * Recovery policy — separates "what failed" from "what to do".
+ *
+ * ErrorEnvelope → planRecovery → RecoveryPlan → SAM executes
+ *
+ * Critical rule: unknown side_effect_state ⇒ reconcile before retry.
+ */
+
+export const FAILURE_CLASS = Object.freeze({
+  INPUT: 'input',
+  AUTHENTICATION: 'authentication',
+  AUTHORIZATION: 'authorization',
+  POLICY: 'policy',
+  DISCOVERY: 'discovery',
+  RESOLUTION: 'resolution',
+  TRANSPORT: 'transport',
+  PROTOCOL: 'protocol',
+  TIMEOUT: 'timeout',
+  RATE_LIMIT: 'rate_limit',
+  CAPACITY: 'capacity',
+  RESOURCE: 'resource',
+  FILESYSTEM: 'filesystem',
+  PERSISTENCE: 'persistence',
+  CONSISTENCY: 'consistency',
+  CONFLICT: 'conflict',
+  DEPENDENCY: 'dependency',
+  PROCESS: 'process',
+  IPC: 'ipc',
+  DATA_INTEGRITY: 'data_integrity',
+  CANCELLED: 'cancelled',
+  UNKNOWN: 'unknown',
+});
+
+export const SIDE_EFFECT_STATE = Object.freeze({
+  NONE: 'none',
+  NOT_STARTED: 'not_started',
+  CONFIRMED_NOT_APPLIED: 'confirmed_not_applied',
+  CONFIRMED_APPLIED: 'confirmed_applied',
+  PARTIALLY_APPLIED: 'partially_applied',
+  UNKNOWN: 'unknown',
+});
+
+export const RECOVERY_SCHEMA = 'agentsam.recovery.v1';
+
+const NO_RETRY_OWNERS = new Set(['policy']);
+const CANCEL_REASONS = new Set([
+  'cancelled_by_user',
+  'cancelled_by_agent',
+  'cancelled_by_policy',
+  'cancelled_by_timeout',
+  'cancelled_by_parent',
+  'cancelled',
+]);
+
+/**
+ * Infer failure_class from reason/code when not supplied.
+ * @param {object} error
+ */
+export function inferFailureClass(error = {}) {
+  const given = error.failure_class;
+  if (given && Object.values(FAILURE_CLASS).includes(given)) return given;
+  const reason = String(error.reason || '');
+  const code = String(error.code || '');
+  if (CANCEL_REASONS.has(reason) || code === 'CANCELLED') return FAILURE_CLASS.CANCELLED;
+  if (/^auth_|unauthenticated|credential/.test(reason) || code === 'UNAUTHENTICATED') return FAILURE_CLASS.AUTHENTICATION;
+  if (/permission|authorization|capability/.test(reason) || code === 'PERMISSION_DENIED') return FAILURE_CLASS.AUTHORIZATION;
+  if (/policy/.test(reason)) return FAILURE_CLASS.POLICY;
+  if (/rate_limit|resource_exhausted|quota|budget/.test(reason) || code === 'RESOURCE_EXHAUSTED') return FAILURE_CLASS.RATE_LIMIT;
+  if (/timeout|deadline/.test(reason) || code === 'DEADLINE_EXCEEDED') return FAILURE_CLASS.TIMEOUT;
+  if (/^fs_|filesystem|path_escape|version_conflict/.test(reason)) return FAILURE_CLASS.FILESYSTEM;
+  if (/^db_|persistence|sqlite|d1/.test(reason)) return FAILURE_CLASS.PERSISTENCE;
+  if (/conflict|etag|precondition|serialization/.test(reason) || code === 'ABORTED') return FAILURE_CLASS.CONFLICT;
+  if (/^pty_|process_|ipc_/.test(reason)) return FAILURE_CLASS.PROCESS;
+  if (/transport|connection|dns|tls|websocket|grpc_unavailable/.test(reason) || code === 'UNAVAILABLE') {
+    return FAILURE_CLASS.TRANSPORT;
+  }
+  if (/corrupt|checksum|integrity|data_loss/.test(reason) || code === 'DATA_LOSS') return FAILURE_CLASS.DATA_INTEGRITY;
+  if (/input_|invalid_argument|malformed/.test(reason) || code === 'INVALID_ARGUMENT') return FAILURE_CLASS.INPUT;
+  return FAILURE_CLASS.UNKNOWN;
+}
+
+/**
+ * Infer side_effect_state for the failed operation.
+ * @param {object} error
+ * @param {object} [operationContext]
+ */
+export function inferSideEffectState(error = {}, operationContext = {}) {
+  const op = error.operation || operationContext.operation || {};
+  if (op.side_effect_state) return op.side_effect_state;
+  if (op.read_only === true || op.side_effect_state === SIDE_EFFECT_STATE.NONE) {
+    return SIDE_EFFECT_STATE.NONE;
+  }
+  if (op.idempotent === true && error.retryable) {
+    return SIDE_EFFECT_STATE.CONFIRMED_NOT_APPLIED;
+  }
+  // Timeouts / connection drops on mutating ops → outcome unknown
+  const reason = String(error.reason || '');
+  const code = String(error.code || '');
+  if (
+    code === 'DEADLINE_EXCEEDED'
+    || /timeout|connection_reset|connection_closed|truncated/.test(reason)
+  ) {
+    if (op.read_only) return SIDE_EFFECT_STATE.NONE;
+    return SIDE_EFFECT_STATE.UNKNOWN;
+  }
+  if (error.retryable === false && /permission|auth|input|policy/.test(reason)) {
+    return SIDE_EFFECT_STATE.CONFIRMED_NOT_APPLIED;
+  }
+  return op.kind ? SIDE_EFFECT_STATE.UNKNOWN : SIDE_EFFECT_STATE.NONE;
+}
+
+/**
+ * Central recovery planner — one policy for CLI / Worker / Studio / MCP.
+ *
+ * @param {object} error  ErrorEnvelope (v1+)
+ * @param {object} [operationContext]
+ * @returns {object} RecoveryPlan
+ */
+export function planRecovery(error = {}, operationContext = {}) {
+  const failure_class = inferFailureClass(error);
+  const side_effect_state = inferSideEffectState(error, operationContext);
+  const attempt = Number(operationContext.attempt || error.retry?.attempt || 1);
+  const maxAttempts = Number(
+    operationContext.max_attempts
+    ?? error.retry?.max_attempts
+    ?? (error.retryable ? 4 : 1),
+  );
+  const evidence = [];
+  evidence.push(`failure_class=${failure_class}`);
+  evidence.push(`side_effect_state=${side_effect_state}`);
+  evidence.push(`reason=${error.reason || 'unknown'}`);
+
+  /** @type {object} */
+  let plan = {
+    schema: RECOVERY_SCHEMA,
+    error_fingerprint: error.fingerprint || null,
+    disposition: 'abort',
+    attempts: { current: attempt, maximum: maxAttempts },
+    delay_ms: null,
+    fallback: null,
+    notify: {
+      user: 'immediately',
+      operator: 'never',
+      agent: 'stop',
+    },
+    reason: error.reason || 'unknown',
+    evidence,
+  };
+
+  // Cancellations are not defects
+  if (failure_class === FAILURE_CLASS.CANCELLED) {
+    return freezePlan({
+      ...plan,
+      disposition: 'abort',
+      notify: { user: 'never', operator: 'never', agent: 'stop' },
+      reason: 'cancelled',
+      evidence: [...evidence, 'cancellation_is_not_a_defect'],
+    });
+  }
+
+  // Ambiguous side effects: NEVER blind retry
+  if (
+    side_effect_state === SIDE_EFFECT_STATE.UNKNOWN
+    || side_effect_state === SIDE_EFFECT_STATE.PARTIALLY_APPLIED
+  ) {
+    return freezePlan({
+      ...plan,
+      disposition: 'reconcile',
+      notify: { user: 'immediately', operator: 'warning', agent: 'wait' },
+      reason: 'side_effect_uncertain',
+      evidence: [...evidence, 'reconcile_before_retry'],
+    });
+  }
+
+  // Policy / auth hard stops
+  if (
+    failure_class === FAILURE_CLASS.POLICY
+    || failure_class === FAILURE_CLASS.AUTHORIZATION
+    || NO_RETRY_OWNERS.has(error.resolution_owner)
+  ) {
+    return freezePlan({
+      ...plan,
+      disposition: 'await_user',
+      notify: { user: 'immediately', operator: 'never', agent: 'wait' },
+      reason: 'policy_or_auth_blocks_retry',
+    });
+  }
+
+  if (failure_class === FAILURE_CLASS.AUTHENTICATION) {
+    return freezePlan({
+      ...plan,
+      disposition: 'await_user',
+      notify: { user: 'immediately', operator: 'never', agent: 'wait' },
+      reason: 'authentication_required',
+    });
+  }
+
+  if (failure_class === FAILURE_CLASS.INPUT || failure_class === FAILURE_CLASS.CONFLICT) {
+    const disposition = failure_class === FAILURE_CLASS.CONFLICT && error.retryable
+      ? 'retry'
+      : 'await_user';
+    return freezePlan({
+      ...plan,
+      disposition,
+      delay_ms: disposition === 'retry' ? 0 : null,
+      attempts: { current: attempt, maximum: Math.min(maxAttempts, 2) },
+      notify: {
+        user: disposition === 'await_user' ? 'immediately' : 'after_retry_exhausted',
+        operator: 'never',
+        agent: disposition === 'retry' ? 'retry' : 'wait',
+      },
+      reason: failure_class === FAILURE_CLASS.CONFLICT ? 'optimistic_concurrency' : 'invalid_input',
+    });
+  }
+
+  // Safe retry path
+  if (error.retryable && attempt < maxAttempts) {
+    const delay = retryDelayFor(error, attempt, failure_class);
+    return freezePlan({
+      ...plan,
+      disposition: failure_class === FAILURE_CLASS.TRANSPORT || /pty_|websocket|connection/.test(String(error.reason))
+        ? 'reconnect'
+        : 'retry',
+      delay_ms: delay,
+      notify: {
+        user: attempt >= 2 ? 'on_degradation' : 'never',
+        operator: 'never',
+        agent: 'retry',
+      },
+      reason: 'retry_budget_remaining',
+      evidence: [...evidence, `delay_ms=${delay}`],
+    });
+  }
+
+  // Fallback if permitted and semantics-preserving
+  const fallbackAllowed = error.fallback?.allowed === true
+    || operationContext.fallback_allowed === true;
+  const preserve = error.fallback?.preserve_semantics !== false
+    && operationContext.preserve_semantics !== false;
+  if (fallbackAllowed && preserve) {
+    return freezePlan({
+      ...plan,
+      disposition: 'fallback',
+      fallback: {
+        kind: error.fallback?.strategy || operationContext.fallback_strategy || 'degraded_mode',
+        target: error.fallback?.target || operationContext.fallback_target || null,
+      },
+      notify: { user: 'on_degradation', operator: 'warning', agent: 'continue' },
+      reason: 'semantic_fallback_allowed',
+    });
+  }
+
+  // Replan if GOAP/A* context available
+  if (operationContext.replan_allowed) {
+    return freezePlan({
+      ...plan,
+      disposition: 'replan',
+      notify: { user: 'on_degradation', operator: 'never', agent: 'replan' },
+      reason: 'retry_exhausted_replan',
+    });
+  }
+
+  // Terminal block
+  return freezePlan({
+    ...plan,
+    disposition: error.resolution_owner === 'user' ? 'await_user' : 'abort',
+    notify: {
+      user: 'immediately',
+      operator: error.severity === 'blocking_internal' ? 'incident' : 'warning',
+      agent: 'stop',
+    },
+    reason: 'recovery_exhausted',
+  });
+}
+
+function retryDelayFor(error, attempt, failureClass) {
+  if (Number.isFinite(error.retry_after_ms) && error.retry_after_ms >= 0) {
+    return Math.round(error.retry_after_ms);
+  }
+  if (failureClass === FAILURE_CLASS.RATE_LIMIT) {
+    return Math.min(60_000, Math.round(1000 * (2 ** Math.min(6, attempt - 1))));
+  }
+  if (failureClass === FAILURE_CLASS.TRANSPORT || failureClass === FAILURE_CLASS.TIMEOUT) {
+    const base = 250;
+    const capped = Math.min(8_000, base * (2 ** Math.min(5, attempt - 1)));
+    const jitter = Math.floor(Math.random() * Math.max(50, capped * 0.2));
+    return capped + jitter;
+  }
+  if (failureClass === FAILURE_CLASS.CONFLICT) return 0;
+  return Math.min(4_000, 500 * (2 ** Math.min(4, attempt - 1)));
+}
+
+function freezePlan(plan) {
+  return Object.freeze({
+    ...plan,
+    attempts: Object.freeze({ ...plan.attempts }),
+    notify: Object.freeze({ ...plan.notify }),
+    fallback: plan.fallback ? Object.freeze({ ...plan.fallback }) : null,
+    evidence: Object.freeze([...(plan.evidence || [])]),
+  });
+}

package/packages/agentsam-knowledge/src/autorag/index.js

@@ -13,7 +13,7 @@ function findScopes(root) {
 }
 export async function discoverAutoRag({ root = process.cwd(), env = process.env, companyAdapter = null, fetchImpl } = {}) {
   const isGit = Boolean(git(root, ['rev-parse', '--is-inside-work-tree']));
-  const providerRegistry = createProviderRegistry({ gemini: { apiKey: env.GEMINI_API_KEY, fetchImpl }, openai: { apiKey: env.OPENAI_API_KEY, fetchImpl }, ollama: { endpoint: env.OLLAMA_HOST || 'http://127.0.0.1:11434', fetchImpl } });
+  const providerRegistry = createProviderRegistry({ gemini: { apiKey: env.GEMINI_API_KEY, fetchImpl }, openai: { apiKey: env.OPENAI_API_KEY, fetchImpl }, ollama: { env, fetchImpl } });
   const providers = await providerRegistry.capabilities();
   const docker = git(root, ['--version']) && (() => { try { return Boolean(execFileSync('docker', ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })); } catch { return false; } })();
   const repositoryId = git(root, ['config', '--get', 'remote.origin.url']) || `local:${path.basename(root)}`;

package/packages/agentsam-knowledge/src/providers/index.js

@@ -1,3 +1,4 @@
+import { resolveOllamaEndpoint } from './ollama-endpoint.js';
 const clean = value => String(value || '').trim();
 const finiteVector = (vector, dimensions) => {
   if (!Array.isArray(vector) || vector.length !== dimensions || vector.some(value => typeof value !== 'number' || !Number.isFinite(value))) {
@@ -6,13 +7,13 @@ const finiteVector = (vector, dimensions) => {
   return vector;
 };
 
-function httpAdapter({ id, env, models, request, credentials = env }) {
+function httpAdapter({ id, env, models, request, credentials = env, allowAnyModel = false }) {
   return Object.freeze({
     id,
     capabilities: () => ({ id, operational: Boolean(credentials()), models, credentials: credentials() ? 'available' : 'missing' }),
     validate(profile) {
       if (clean(profile?.provider) !== id) throw new Error(`provider_profile_mismatch:${id}`);
-      if (!models.includes(clean(profile?.model))) throw new Error(`provider_model_unsupported:${id}:${profile?.model}`);
+      if (!allowAnyModel && !models.includes(clean(profile?.model))) throw new Error(`provider_model_unsupported:${id}:${profile?.model}`);
       if (!Number.isInteger(profile?.dimensions) || profile.dimensions < 1) throw new Error('provider_dimensions_required');
       if (!credentials()) throw new Error(`provider_credentials_unavailable:${id}`);
     },
@@ -70,13 +71,26 @@ export function createWorkersAiProvider({ binding } = {}) {
   });
 }
 
-export function createOllamaProvider({ endpoint = process.env.OLLAMA_HOST || 'http://127.0.0.1:11434', fetchImpl = globalThis.fetch } = {}) {
-  return httpAdapter({ id: 'ollama', env: 'OLLAMA_HOST', models: ['nomic-embed-text', 'mxbai-embed-large'], credentials: () => endpoint,
+export function createOllamaProvider({ endpoint, env = process.env, fetchImpl = globalThis.fetch, models } = {}) {
+  // Model allowlist is advisory only — live `ollama list` / tags are authoritative at selection time.
+  const resolvedEndpoint = resolveOllamaEndpoint({ endpoint, env });
+  const known = Array.isArray(models) && models.length ? models : ['mxbai-embed-large', 'nomic-embed-text'];
+  return httpAdapter({
+    id: 'ollama',
+    env: 'AGENTSAM_OLLAMA_ENDPOINT',
+    models: known,
+    allowAnyModel: true,
+    credentials: () => resolvedEndpoint,
     request: async (text, profile) => {
-      const response = await fetchImpl(new URL('/api/embed', endpoint), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model: profile.model, input: text }) });
+      const response = await fetchImpl(new URL('/api/embed', resolvedEndpoint + '/'), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ model: profile.model, input: text }),
+      });
       if (!response.ok) throw new Error(`provider_request_failed:ollama:${response.status}`);
       return finiteVector((await response.json()).embeddings?.[0], profile.dimensions);
-    } });
+    },
+  });
 }
 
 export function createProviderRegistry(options = {}) {

package/packages/agentsam-knowledge/src/providers/ollama-endpoint.js

@@ -0,0 +1,31 @@
+export const OLLAMA_DEFAULT_ENDPOINT = 'http://127.0.0.1:11434';
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function normalizeOllamaEndpoint(value = OLLAMA_DEFAULT_ENDPOINT) {
+  let raw = clean(value) || OLLAMA_DEFAULT_ENDPOINT;
+  if (!raw.includes('://')) raw = 'http://' + raw;
+
+  const url = new URL(raw);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('ollama_endpoint_protocol_invalid:' + url.protocol);
+  }
+
+  if (url.hostname === '0.0.0.0') url.hostname = '127.0.0.1';
+
+  url.pathname = url.pathname.replace(/\/+$/, '') || '/';
+  const normalized = url.toString();
+  return normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;
+}
+
+export function resolveOllamaEndpoint({ endpoint, env = process.env } = {}) {
+  return normalizeOllamaEndpoint(
+    endpoint
+      || env.AGENTSAM_OLLAMA_ENDPOINT
+      || env.OLLAMA_BASE_URL
+      || env.OLLAMA_HOST
+      || OLLAMA_DEFAULT_ENDPOINT,
+  );
+}

package/packages/agentsam-knowledge/test/autorag.test.mjs

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { createFixtureProvider, createProviderRegistry, createBackendRegistry, recommendAutoRag, safeAutoRagConfig, selectIntentRoute, routeCompanyQuestion } from '../src/index.js';
+import { createFixtureProvider, createOllamaProvider, createProviderRegistry, createBackendRegistry, recommendAutoRag, safeAutoRagConfig, selectIntentRoute, routeCompanyQuestion } from '../src/index.js';
 
 test('provider registry is explicit, deterministic, and fails closed', async () => {
   const registry = createProviderRegistry({ fixture: { dimensions: 3 }, gemini: { apiKey: null }, openai: { apiKey: null } });
@@ -12,6 +12,27 @@ test('provider registry is explicit, deterministic, and fails closed', async ()
   assert.equal((await registry.capabilities()).find(item => item.id === 'gemini').operational, false);
 });
 
+test('Ollama provider normalizes bind hosts before issuing embed requests', async () => {
+  let seenUrl = null;
+  const provider = createOllamaProvider({
+    endpoint: '0.0.0.0:11434',
+    fetchImpl: async (url) => {
+      seenUrl = String(url);
+      return new Response(JSON.stringify({ embeddings: [[1, 2, 3]] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    },
+  });
+  const vector = await provider.embedQuery('hello', {
+    provider: 'ollama',
+    model: 'mxbai-embed-large',
+    dimensions: 3,
+  });
+  assert.deepEqual(vector, [1, 2, 3]);
+  assert.equal(seenUrl, 'http://127.0.0.1:11434/api/embed');
+});
+
 test('backend registry requires explicit resources and dimensions', () => {
   const registry = createBackendRegistry();
   assert.deepEqual(registry.get('local_exact').prepare({ backend: 'local_exact', dimensions: 3 }), { id: 'local_exact', dimensions: 3 });

package/packages/agentsam-nav/package.json

@@ -28,8 +28,8 @@
     "react-dom": ">=18"
   },
   "devDependencies": {
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.3",
     "esbuild": "^0.28.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",