@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/src/models/discovery.js

@@ -50,10 +50,12 @@ function baseRecord(provider, id, values = {}) {
   const contextWindow = positiveInt(values.context_window ?? values.contextWindow ?? fallback?.context_window);
   const maxOutput = positiveInt(values.max_output_tokens ?? values.maxOutputTokens ?? fallback?.max_output_tokens);
   return Object.freeze({
-    model_key: `${provider}:${id}`,
+    model_key: provider + ':' + id,
     provider,
     provider_model_id: id,
     label: clean(values.label) || fallback?.label || id,
+    kind: clean(values.kind) || fallback?.kind || 'unknown',
+    description: clean(values.description) || fallback?.description || null,
     availability: 'available',
     availability_source: 'provider_api',
     context_window: contextWindow,
@@ -64,6 +66,8 @@ function baseRecord(provider, id, values = {}) {
     max_output_tokens_source: values.max_output_tokens != null || values.maxOutputTokens != null
       ? 'provider_api'
       : fallback?.max_output_tokens ? 'sdk_reference' : 'unknown',
+    knowledge_cutoff: values.knowledge_cutoff || fallback?.knowledge_cutoff || null,
+    default_reasoning_effort: clean(values.default_reasoning_effort) || fallback?.default_reasoning_effort || null,
     reasoning_efforts: Object.freeze(
       Array.isArray(values.reasoning_efforts) && values.reasoning_efforts.length
         ? [...values.reasoning_efforts]
@@ -87,10 +91,26 @@ function baseRecord(provider, id, values = {}) {
       discovered_at: new Date().toISOString(),
       fallback: fallback?.source || null,
     }),
-    metadata: Object.freeze(values.metadata && typeof values.metadata === 'object' ? { ...values.metadata } : {}),
+    metadata: Object.freeze({
+      ...(fallback?.metadata && typeof fallback.metadata === 'object' ? fallback.metadata : {}),
+      ...(values.metadata && typeof values.metadata === 'object' ? values.metadata : {}),
+    }),
   });
 }
 
+function openAIModelCapabilities(id) {
+  const fallback = fallbackRecord('openai', id);
+  if (fallback?.capabilities) return {};
+  if (/^text-embedding-/i.test(id)) return { agent_runtime: false, embeddings: true };
+  if (/^(?:gpt-image|chatgpt-image|gpt-audio|gpt-realtime|sora|tts|whisper|omni-moderation)/i.test(id)) {
+    return { agent_runtime: false };
+  }
+  if (/^(?:gpt-(?:4o|4\.1|5|6)|o[1-9])/i.test(id)) {
+    return { agent_runtime: true, responses: true };
+  }
+  return { agent_runtime: false };
+}
+
 async function fetchJson(fetchImpl, url, init) {
   const response = await fetchImpl(url, { ...init, signal: init?.signal || timeoutSignal() });
   let body = null;
@@ -115,7 +135,7 @@ export async function discoverOpenAIModels(apiKey, fetchImpl = fetch) {
       .filter(Boolean)
       .map((id) => baseRecord('openai', id, {
         source_url: 'https://api.openai.com/v1/models',
-        capabilities: { responses: true },
+        capabilities: openAIModelCapabilities(id),
       }));
     return { attempted: true, ok: true, models, error: null };
   } catch (error) { return failure(error); }
@@ -284,7 +304,7 @@ function cloudflareTaskName(task) {
 
 export async function discoverCloudflareModels(apiToken, accountId, fetchImpl = fetch) {
   if (!clean(apiToken)) return failure('credential unavailable', false);
-  if (!clean(accountId)) return failure('ACCOUNT_ID is required for Workers AI discovery');
+  if (!clean(accountId)) return failure('CLOUDFLARE_ACCOUNT_ID is required for Workers AI discovery');
   try {
     const url = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(clean(accountId))}/ai/models/search`;
     const body = await fetchJson(fetchImpl, url, {
@@ -295,11 +315,19 @@ export async function discoverCloudflareModels(apiToken, accountId, fetchImpl =
       .map((row) => {
         const id = clean(row?.name);
         const task = cloudflareTaskName(row?.task);
-        if (!id || task.toLowerCase() !== 'text generation') return null;
+        const taskLower = task.toLowerCase();
+        // Text Generation = chat/agent pool. Text Embeddings = Vectorize / Workers AI embed pool.
+        // Never drop embeddings here — chat allowlisting happens in inventory curation only.
+        if (!id || (taskLower !== 'text generation' && taskLower !== 'text embeddings')) return null;
+        const isEmbed = taskLower === 'text embeddings';
         return baseRecord('cloudflare', id, {
           label: id,
           source_url: url,
-          capabilities: { workers_ai: true },
+          capabilities: {
+            workers_ai: true,
+            embeddings: isEmbed,
+            agent_runtime: !isEmbed,
+          },
           metadata: {
             task,
             author: clean(row?.author) || null,

package/src/models/index.js

@@ -3,5 +3,7 @@ export {
   MODEL_CATALOG,
   listModelCatalog,
   getModelRecord,
+  mergeModelReference,
   calculateModelCost,
 } from './catalog.js';
+export { normalizeModelPolicy, loadModelPolicy } from './policy.js';

package/src/models/inventory-core.js

@@ -0,0 +1,190 @@
+/**
+ * Credential-plane helpers and Workers-safe inventory core (no Node fs / Ollama).
+ */
+import { discoverProviderModels } from './discovery.js';
+
+export const INVENTORY_API_PROVIDERS = Object.freeze([
+  { id: 'openai', label: 'OpenAI', service: 'openai', env: 'OPENAI_API_KEY' },
+  { id: 'anthropic', label: 'Anthropic', service: 'anthropic', env: 'ANTHROPIC_API_KEY' },
+  { id: 'gemini', label: 'Gemini', service: 'gemini', env: 'GEMINI_API_KEY' },
+  { id: 'grok', label: 'Grok / xAI', service: 'xai', env: 'XAI_API_KEY', aliases: ['xai', 'grok'] },
+  { id: 'cursor', label: 'Cursor', service: 'cursor', env: 'CURSOR_API_KEY' },
+  { id: 'cloudflare', label: 'Cloudflare', service: 'cloudflare', env: 'CLOUDFLARE_API_TOKEN' },
+]);
+
+export const WORKERS_AI_CURATED_MODEL_IDS = Object.freeze([
+  '@cf/qwen/qwen2.5-coder-32b-instruct',
+  '@cf/moonshotai/kimi-k2.7-code',
+  '@cf/zai-org/glm-5.3',
+  '@cf/deepseek-ai/deepseek-v4-pro-0813',
+  '@cf/deepseek-ai/deepseek-v4-flash-0731',
+  '@cf/qwen/qwen3.8-27b',
+  '@cf/openai/gpt-oss-120b',
+  '@cf/meta/llama-4-scout-17b-16e-instruct',
+]);
+
+const CURATED = new Set(WORKERS_AI_CURATED_MODEL_IDS);
+
+const SERVICE_TO_PROVIDER = Object.freeze({
+  openai: 'openai',
+  anthropic: 'anthropic',
+  gemini: 'gemini',
+  xai: 'grok',
+  grok: 'grok',
+  cursor: 'cursor',
+  cloudflare: 'cloudflare',
+});
+
+export function providerIdForService(serviceName) {
+  const key = String(serviceName || '').trim().toLowerCase();
+  return SERVICE_TO_PROVIDER[key] || null;
+}
+
+export function filterWorkersAiCurated(models = [], options = {}) {
+  if (options.curated === false) return [...models];
+  // Chat/agent pool: curated allowlist. Embedding models always pass —
+  // Vectorize / Workers AI embed lanes must not be limited by the chat allowlist.
+  return models.filter((row) => {
+    const id = String(row?.provider_model_id || row?.model_id || '');
+    const caps = row?.capabilities || {};
+    const task = String(row?.metadata?.task || '').toLowerCase();
+    if (caps.embeddings === true || task === 'text embeddings' || /embed/i.test(id)) return true;
+    return CURATED.has(id);
+  });
+}
+
+/**
+ * @param {Map<string, { value: string, source?: string, account_id?: string }>} credentialByProvider
+ */
+export function makeMapCredentialResolver(credentialByProvider) {
+  return async (providerId) => {
+    const row = credentialByProvider.get(providerId);
+    if (!row?.value) return { configured: false, value: '', source: null, error: null };
+    return {
+      configured: true,
+      value: row.value,
+      source: row.source || 'injected',
+      env: INVENTORY_API_PROVIDERS.find((p) => p.id === providerId)?.env || null,
+      account_id: row.account_id || null,
+    };
+  };
+}
+
+/**
+ * Merge vault credentials (preferred) with optional platform env credentials.
+ * Never returns secret material in the inventory result.
+ */
+export async function collectCredentialScopedInventory(options = {}) {
+  const fetchImpl = options.fetchImpl || fetch;
+  const credentialPlane = options.credentialPlane || 'studio_vault';
+  const curateWorkersAi = options.curateWorkersAi !== false;
+  const resolveCredential = options.resolveCredential;
+  if (typeof resolveCredential !== 'function') {
+    throw new TypeError('resolveCredential is required');
+  }
+
+  const providers = [];
+  const discovery = {};
+  const providerModels = {};
+
+  await Promise.all(INVENTORY_API_PROVIDERS.map(async (provider) => {
+    const credential = await resolveCredential(provider.id);
+    providers.push({
+      id: provider.id,
+      label: provider.label,
+      configured: credential?.configured === true,
+      source: credential?.source || null,
+      credentialError: credential?.error || null,
+    });
+
+    let result = { attempted: false, ok: false, models: [], error: null };
+    if (options.discoverRemote !== false && credential?.configured) {
+      result = await discoverProviderModels(provider.id, credential, { fetchImpl });
+      if (provider.id === 'cloudflare' && result.ok && curateWorkersAi) {
+        const curated = filterWorkersAiCurated(result.models || []);
+        result = { ...result, models: curated, curation: 'agentsam_workers_ai_allowlist' };
+      }
+    }
+    discovery[provider.id] = {
+      attempted: result.attempted === true,
+      ok: result.ok === true,
+      error: result.error || null,
+      returnedModelCount: Array.isArray(result.models) ? result.models.length : 0,
+      ...(result.curation ? { curation: result.curation } : {}),
+    };
+    providerModels[provider.id] = result.models || [];
+  }));
+
+  const availableModels = Object.values(providerModels)
+    .flat()
+    .filter((row) => row.availability === 'available');
+
+  return {
+    schemaVersion: 'agentsam-model-inventory-v3',
+    generatedAt: new Date().toISOString(),
+    authority: 'per_credential_provider_discovery',
+    credential_plane: credentialPlane,
+    providers,
+    discovery,
+    providerModels,
+    availableModels,
+  };
+}
+
+export function sanitizeInventoryForClient(status = {}) {
+  const out = {
+    schemaVersion: status.schemaVersion,
+    generatedAt: status.generatedAt,
+    authority: status.authority,
+    credential_plane: status.credential_plane,
+    providers: (status.providers || []).map((row) => ({
+      id: row.id,
+      label: row.label,
+      configured: row.configured === true,
+      source: row.source || null,
+      credentialError: row.credentialError || null,
+    })),
+    discovery: status.discovery || {},
+    availableModels: (status.availableModels || []).map((row) => ({
+      provider: row.provider,
+      model_id: row.provider_model_id || row.model_id,
+      model_key: row.model_key || null,
+      label: row.label || row.provider_model_id || row.model_id,
+      availability: row.availability,
+      availability_source: row.availability_source || null,
+      context_window: row.context_window ?? null,
+      reasoning_efforts: row.reasoning_efforts || [],
+      service_tiers: row.service_tiers || [],
+      capabilities: row.capabilities || {},
+    })),
+  };
+  if (status.local) {
+    out.local = {
+      provider: status.local.provider,
+      online: status.local.online === true,
+      models: (status.local.models || []).map((row) => ({ name: row.name })),
+    };
+  }
+  return out;
+}
+
+/** Fail-closed check used by chat routers. */
+export function assertModelAvailableForProvider(inventory, provider, modelId) {
+  const p = String(provider || '').trim().toLowerCase();
+  const m = String(modelId || '').trim();
+  if (!p || !m) {
+    const err = new Error('provider_and_model_required');
+    err.code = 'provider_and_model_required';
+    throw err;
+  }
+  const row = (inventory?.availableModels || []).find(
+    (item) => String(item.provider).toLowerCase() === p
+      && (item.model_id === m || item.provider_model_id === m || item.model_key === m),
+  );
+  if (!row) {
+    const err = new Error(`selected_model_not_available_for_credential:${p}:${m}`);
+    err.code = 'selected_model_not_available_for_credential';
+    throw err;
+  }
+  return row;
+}

package/src/models/policy.js

@@ -0,0 +1,20 @@
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+export function normalizeModelPolicy(row = {}) {
+  const out = {};
+  for (const key of ['target_input_tokens','compact_at_tokens','intervene_at_tokens','max_normal_input_tokens','pricing_threshold_tokens','max_cumulative_input_tokens','safety_margin_tokens']) {
+    if (row[key] != null && Number.isFinite(Number(row[key]))) out[key] = Math.floor(Number(row[key]));
+  }
+  if (row.compaction_strategy) out.compaction_strategy = clean(row.compaction_strategy);
+  return Object.freeze(out);
+}
+
+export async function loadModelPolicy(db, { provider, modelKey }) {
+  if (!db?.prepare) throw new TypeError('database_required');
+  const row = await db.prepare(`
+    SELECT * FROM agentsam_model_policies
+    WHERE provider = ? AND model_key = ? AND is_active = 1
+    LIMIT 1
+  `).bind(clean(provider), clean(modelKey)).first();
+  return row ? normalizeModelPolicy(row) : null;
+}

package/src/plugins/cloudflare.js

@@ -0,0 +1,103 @@
+import { normalizePluginManifest } from './contracts.js';
+
+export const AGENTSAM_MCP_PLUGIN_MANIFEST = normalizePluginManifest({
+  plugin_key: 'agentsam-mcp',
+  provider_key: 'cloudflare',
+  plugin_kind: 'oauth',
+  category: 'developer_platform',
+  display_name: 'AgentSam MCP',
+  short_name: 'AgentSam MCP',
+  description: 'Connect a Cloudflare account to AgentSam through the centralized OAuth approval flow.',
+  mention_aliases: ['@agentsam-mcp', 'agentsam mcp'],
+  endpoint_url: 'https://api.cloudflare.com/client/v4',
+  transport: 'http_rest',
+  auth_type: 'oauth',
+  oauth_connect_url: '/api/connections/cloudflare/start',
+  capabilities: [
+    { capability_key: 'cloudflare.api.docs', domain: 'cloudflare', verb: 'read', description: 'Search Cloudflare developer documentation.', is_mutating: false },
+    { capability_key: 'cloudflare.api.search', domain: 'cloudflare', verb: 'search', description: 'Search the Cloudflare OpenAPI operation catalog.', is_mutating: false },
+    { capability_key: 'cloudflare.api.execute', domain: 'cloudflare', verb: 'execute', description: 'Execute a bounded Cloudflare API Code Mode program.', is_mutating: true },
+  ],
+  tool_lanes: ['typed', 'mcp', 'api', 'codemode'],
+  resource_scope: { owner: 'account', oauth_connection_table: 'agentsam_cloudflare_connections' },
+  config: {
+    oauth_authority: 'cloudflare',
+    oauth_client_id: 'c0704bd7a7aab7216b362603e1985499',
+    client_name: 'AgentSam Local Studio',
+    client_uri: 'https://agentsam.inneranimalmedia.com',
+    callback_url: 'https://agentsam.inneranimalmedia.com/api/connections/cloudflare/callback',
+    authorization_endpoint: 'https://dash.cloudflare.com/oauth2/auth',
+    token_endpoint: 'https://dash.cloudflare.com/oauth2/token',
+    revoke_endpoint: 'https://dash.cloudflare.com/oauth2/revoke',
+    userinfo_endpoint: 'https://dash.cloudflare.com/oauth2/userinfo',
+    jwks_uri: 'https://dash.cloudflare.com/.well-known/jwks.json',
+    openid_configuration: 'https://dash.cloudflare.com/.well-known/openid-configuration',
+    token_auth_method: 'none_pkce',
+    disconnect_url: '/api/connections/cloudflare/disconnect',
+    status_url: '/api/connections/cloudflare',
+  },
+  metadata: { execution_strategy: 'runtime_selected', code_mode_is_plugin: false },
+  health_strategy: 'oauth_probe',
+  tools: [
+    {
+      tool_key: 'agentsam-mcp.docs', tool_name: 'agentsam_mcp_docs', display_name: 'Cloudflare docs',
+      description: 'Search Cloudflare developer documentation.', handler_type: 'cf', dispatch_target: 'mcp',
+      capability_key: 'cloudflare.api.docs', handler_config: { server_url: 'https://mcp.cloudflare.com/mcp', remote_tool: 'docs' },
+      input_schema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'], additionalProperties: false },
+      risk_level: 'low', connector_access_class: 'read', intent_tags: ['cloudflare', 'docs', 'search'],
+    },
+    {
+      tool_key: 'agentsam-mcp.search', tool_name: 'agentsam_mcp_search', display_name: 'Search Cloudflare API',
+      description: 'Search Cloudflare’s current OpenAPI spec for operations before executing code.', handler_type: 'cf', dispatch_target: 'plugin',
+      capability_key: 'cloudflare.api.search', handler_config: { server_url: 'https://mcp.cloudflare.com/mcp', remote_tool: 'search', network: 'none' },
+      input_schema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'], additionalProperties: false },
+      risk_level: 'low', connector_access_class: 'read', intent_tags: ['cloudflare', 'openapi', 'search'],
+    },
+    {
+      tool_key: 'agentsam-mcp.execute', tool_name: 'agentsam_mcp_execute', display_name: 'Execute Cloudflare API',
+      description: 'Run an approved AgentSam Cloudflare program with the connected OAuth token kept outside generated code.', handler_type: 'cf', dispatch_target: 'codemode',
+      capability_key: 'cloudflare.api.execute', handler_config: { server_url: 'https://mcp.cloudflare.com/mcp', remote_tool: 'execute', network: 'cloudflare_api_only' },
+      input_schema: { type: 'object', properties: { code: { type: 'string' }, account_id: { type: 'string' } }, required: ['code'], additionalProperties: false },
+      risk_level: 'high', requires_approval: true, requires_confirmation: true, connector_access_class: 'write', intent_tags: ['cloudflare', 'api', 'execute'],
+    },
+  ],
+});
+
+// Backward-compatible export name for early SDK adopters. The installed
+// identity is @agentsam-mcp; Cloudflare is the provider and OAuth authority.
+export const CLOUDFLARE_PLUGIN_MANIFEST = AGENTSAM_MCP_PLUGIN_MANIFEST;
+
+// Inner Animal Media Platform owns a separate confidential Cloudflare OAuth
+// client. It is a distinct installation from Local Studio's public PKCE client
+// and deliberately has no SDK-dispatched tools.
+export const INNERANIMALMEDIA_CLOUDFLARE_OAUTH_PLUGIN_MANIFEST = normalizePluginManifest({
+  plugin_key: 'inneranimalmedia-cf-oauth',
+  provider_key: 'cloudflare',
+  installation_key: 'default',
+  plugin_kind: 'oauth',
+  category: 'developer_platform',
+  display_name: 'Inner Animal Media Cloudflare OAuth',
+  short_name: 'IAM Cloudflare',
+  description: 'Inner Animal Media Platform confidential Cloudflare OAuth connection.',
+  mention_aliases: ['@inneranimalmedia-cf-oauth'],
+  endpoint_url: 'https://dash.cloudflare.com/oauth2/auth',
+  transport: 'http_rest',
+  auth_type: 'oauth_via_iam',
+  oauth_connect_url: 'https://inneranimalmedia.com/api/oauth/cloudflare/start',
+  capabilities: [],
+  tool_lanes: [],
+  resource_scope: { owner: 'account', token_authority: 'inneranimalmedia_platform' },
+  config: {
+    oauth_client_id: '0f2f3c826d800118b70863d8d59e12cc',
+    client_name: 'Inner Animal Media Platform',
+    client_uri: 'https://inneranimalmedia.com',
+    callback_url: 'https://inneranimalmedia.com/api/oauth/cloudflare/callback',
+    authorization_endpoint: 'https://dash.cloudflare.com/oauth2/auth',
+    token_endpoint: 'https://dash.cloudflare.com/oauth2/token',
+    token_auth_method: 'client_secret_basic',
+    secret_authority: 'inneranimalmedia_platform_vault',
+  },
+  metadata: { execution_strategy: 'host_owned', client_visibility: 'public' },
+  health_strategy: 'oauth_probe',
+  tools: [],
+});

package/src/plugins/completeful.js

@@ -0,0 +1,69 @@
+import { normalizePluginManifest } from './contracts.js';
+
+// Curated ecommerce capabilities are part of the reusable
+// ecommerce-cms-agentsam native family. FNF is the first packaged deployment;
+// the handler remains an injected app adapter, never a hard-coded store.
+const readSchema = {
+  type: 'object', properties: {}, additionalProperties: true,
+};
+
+export const COMPLETEFUL_PLUGIN_MANIFEST = normalizePluginManifest({
+  plugin_key: 'completeful',
+  provider_key: 'completeful',
+  plugin_kind: 'native',
+  category: 'commerce',
+  display_name: 'Completeful',
+  short_name: 'Completeful',
+  description: 'Curated ecommerce catalog, design, publishing, and order capabilities.',
+  mention_aliases: ['@completeful', 'completeful'],
+  transport: 'native',
+  auth_type: 'api_key_secret',
+  capabilities: [
+    { capability_key: 'catalog.search', domain: 'commerce', verb: 'search', description: 'Search the Completeful catalog.', is_mutating: false },
+    { capability_key: 'catalog.read', domain: 'commerce', verb: 'read', description: 'Read Completeful catalog records.', is_mutating: false },
+    { capability_key: 'catalog.sync', domain: 'commerce', verb: 'sync', description: 'Synchronize catalog data.', is_mutating: true },
+    { capability_key: 'design.create', domain: 'commerce', verb: 'create', description: 'Create a Completeful design.', is_mutating: true },
+    { capability_key: 'product.publish', domain: 'commerce', verb: 'publish', description: 'Publish a product.', is_mutating: true },
+    { capability_key: 'product.sync', domain: 'commerce', verb: 'sync', description: 'Synchronize a product.', is_mutating: true },
+    { capability_key: 'order.quote', domain: 'commerce', verb: 'quote', description: 'Quote an order.', is_mutating: false },
+    { capability_key: 'order.create', domain: 'commerce', verb: 'create', description: 'Create an order.', is_mutating: true },
+  ],
+  tool_lanes: ['native', 'curated'],
+  metadata: { family: 'ecommerce-cms-agentsam', packaged_deployment: 'fuelnfreetime' },
+  health_strategy: 'provider_probe',
+  tools: [
+    ['completeful_catalog_list', 'Catalog list', 'catalog.list', 'low', false],
+    ['completeful_catalog_sync', 'Catalog sync', 'catalog.sync', 'medium', true],
+    ['completeful_catalog_get', 'Catalog get', 'catalog.read', 'low', false],
+    ['completeful_catalog_semantic_search', 'Catalog semantic search', 'catalog.search', 'low', false],
+    ['completeful_design_create', 'Create design', 'design.create', 'medium', true],
+    ['completeful_product_publish', 'Publish product', 'product.publish', 'high', true],
+    ['completeful_product_sync', 'Product sync', 'product.sync', 'medium', true],
+    ['completeful_order_quote', 'Order quote', 'order.quote', 'low', false],
+    ['completeful_order_create', 'Create order', 'order.create', 'high', true],
+  ].map(([tool_key, display_name, capability_key, risk_level, mutating]) => ({
+    tool_key,
+    tool_name: tool_key,
+    display_name,
+    description: tool_key === 'completeful_catalog_semantic_search'
+      ? 'Hybrid Completeful catalog search using Voyage recall, lexical/taxonomy fusion, and optional reranking.'
+      : `Execute the curated Completeful ${display_name.toLowerCase()} capability.`,
+    tool_category: 'ecommerce-cms-agentsam',
+    // The live agentsam_tools contract reserves `cms` as the native family;
+    // handler_key carries the provider identity so older D1 schemas remain
+    // valid while dispatch stays generic.
+    handler_type: 'cms',
+    handler_key: 'completeful',
+    dispatch_target: 'internal',
+    capability_key,
+    handler_config: { family: 'ecommerce-cms-agentsam', operation: capability_key },
+    input_schema: tool_key === 'completeful_catalog_semantic_search'
+      ? { type: 'object', properties: { q: { type: 'string' }, limit: { type: 'integer', minimum: 1, maximum: 100 }, include: { type: 'string' } }, required: ['q'], additionalProperties: false }
+      : readSchema,
+    risk_level,
+    requires_approval: mutating && risk_level !== 'medium',
+    requires_confirmation: risk_level === 'high',
+    connector_access_class: mutating ? 'write' : 'read',
+    intent_tags: ['completeful', 'commerce', capability_key],
+  })),
+});

package/src/plugins/contracts.js

@@ -0,0 +1,86 @@
+export const AGENTSAM_PLUGIN_SCHEMA_VERSION = 1;
+
+const KINDS = new Set(['mcp', 'api', 'oauth', 'native', 'webhook', 'database', 'storage', 'ai']);
+const TRANSPORTS = new Set(['remote_jsonrpc', 'iam_mcp_catalog', 'http_rest', 'http_graphql', 'webhook', 'workers_binding', 'native', 'none']);
+const AUTH_TYPES = new Set(['none', 'bridge', 'oauth', 'oauth_via_iam', 'bearer_secret', 'api_key_secret', 'workers_binding']);
+const DISPATCH_TARGETS = new Set(['native', 'internal', 'plugin', 'mcp', 'codemode', 'workflow']);
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function object(value) { return Boolean(value) && typeof value === 'object' && !Array.isArray(value); }
+
+export function normalizePluginKey(value) {
+  const key = clean(value).toLowerCase().replace(/^@/, '').replace(/^inneranimalmedia\//, '').replace(/[^a-z0-9._-]+/g, '-');
+  if (!key || key.length > 80) throw new Error('invalid_plugin_key');
+  return key;
+}
+
+export function normalizePluginManifest(value) {
+  if (!object(value)) throw new TypeError('plugin_manifest_object_required');
+  const pluginKey = normalizePluginKey(value.plugin_key || value.key);
+  const kind = clean(value.plugin_kind || 'api');
+  const transport = clean(value.transport || 'none');
+  const authType = clean(value.auth_type || 'none');
+  if (!KINDS.has(kind)) throw new Error(`invalid_plugin_kind:${kind}`);
+  if (!TRANSPORTS.has(transport)) throw new Error(`invalid_plugin_transport:${transport}`);
+  if (!AUTH_TYPES.has(authType)) throw new Error(`invalid_plugin_auth_type:${authType}`);
+  const tools = (value.tools || []).map((tool) => {
+    const toolKey = clean(tool.tool_key || tool.tool_name);
+    if (!toolKey.startsWith(`${pluginKey}.`) && !toolKey.startsWith(`${pluginKey}_`)) {
+      throw new Error(`plugin_tool_key_must_start_with:${pluginKey}.`);
+    }
+    const dispatchTarget = clean(tool.dispatch_target || 'plugin');
+    if (!DISPATCH_TARGETS.has(dispatchTarget)) throw new Error(`invalid_dispatch_target:${dispatchTarget}`);
+    return Object.freeze({
+      tool_key: toolKey,
+      tool_name: clean(tool.tool_name || toolKey.replaceAll('.', '_')),
+      display_name: clean(tool.display_name || toolKey),
+      description: clean(tool.description),
+      tool_category: clean(tool.tool_category || 'integrations'),
+      handler_type: clean(tool.handler_type || 'integrations'),
+      handler_key: clean(tool.handler_key || toolKey),
+      dispatch_target: dispatchTarget,
+      capability_key: clean(tool.capability_key || toolKey),
+      input_schema: object(tool.input_schema) ? structuredClone(tool.input_schema) : { type: 'object', properties: {}, required: [], additionalProperties: false },
+      output_schema: object(tool.output_schema) ? structuredClone(tool.output_schema) : null,
+      handler_config: object(tool.handler_config) ? structuredClone(tool.handler_config) : {},
+      intent_tags: Array.isArray(tool.intent_tags) ? [...tool.intent_tags] : [],
+      risk_level: clean(tool.risk_level || 'low'),
+      requires_approval: tool.requires_approval === true,
+      requires_confirmation: tool.requires_confirmation === true,
+      connector_visible: tool.connector_visible !== false,
+      connector_access_class: clean(tool.connector_access_class || 'read'),
+      is_active: tool.is_active !== false,
+    });
+  });
+  return Object.freeze({
+    schema_version: AGENTSAM_PLUGIN_SCHEMA_VERSION,
+    plugin_key: pluginKey,
+    provider_key: clean(value.provider_key || pluginKey),
+    installation_key: clean(value.installation_key || 'default'),
+    plugin_kind: kind,
+    category: clean(value.category || 'integration'),
+    display_name: clean(value.display_name || pluginKey),
+    short_name: clean(value.short_name) || null,
+    description: clean(value.description) || null,
+    mention_aliases: Object.freeze(Array.isArray(value.mention_aliases) ? [...value.mention_aliases] : [`@${pluginKey}`]),
+    endpoint_url: clean(value.endpoint_url) || null,
+    transport,
+    auth_type: authType,
+    secret_ref: clean(value.secret_ref) || null,
+    oauth_connect_url: clean(value.oauth_connect_url) || null,
+    capabilities: Object.freeze(Array.isArray(value.capabilities) ? value.capabilities.map((row) => Object.freeze({ ...row })) : []),
+    tool_lanes: Object.freeze(Array.isArray(value.tool_lanes) ? [...value.tool_lanes] : []),
+    resource_scope: Object.freeze(object(value.resource_scope) ? structuredClone(value.resource_scope) : {}),
+    config: Object.freeze(object(value.config) ? structuredClone(value.config) : {}),
+    metadata: Object.freeze(object(value.metadata) ? structuredClone(value.metadata) : {}),
+    icon_url: clean(value.icon_url) || null,
+    icon_dark_url: clean(value.icon_dark_url) || null,
+    icon_alt: clean(value.icon_alt) || null,
+    icon_fit: clean(value.icon_fit || 'contain'),
+    composer_visible: value.composer_visible !== false,
+    settings_visible: value.settings_visible !== false,
+    sort_priority: Number.isFinite(Number(value.sort_priority)) ? Number(value.sort_priority) : 50,
+    health_strategy: clean(value.health_strategy || 'adapter'),
+    tools: Object.freeze(tools),
+  });
+}

package/src/plugins/index.js

@@ -0,0 +1,11 @@
+export { AGENTSAM_PLUGIN_SCHEMA_VERSION, normalizePluginKey, normalizePluginManifest } from './contracts.js';
+export {
+  AGENTSAM_MCP_PLUGIN_MANIFEST,
+  CLOUDFLARE_PLUGIN_MANIFEST,
+  INNERANIMALMEDIA_CLOUDFLARE_OAUTH_PLUGIN_MANIFEST,
+} from './cloudflare.js';
+export { COMPLETEFUL_PLUGIN_MANIFEST } from './completeful.js';
+export { installPlugin, listPlugins, listPluginTools, recordPluginHealthCheck, recordToolCall } from './registry.js';
+export { createPluginRuntime, createPluginCapabilityAdapter, executeAgentSamTool } from './runtime.js';
+export { resolveProjectPluginScope, resolveProjectPluginResources, resolveProjectRuntimeResources, resolveProjectVectorizeScope } from './resource-scope.js';
+export { resolveVectorizeConfig, executeVectorizeTool } from './vectorize.js';