@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/src/plugins/registry.js

@@ -0,0 +1,207 @@
+import { normalizePluginManifest } from './contracts.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function json(value, fallback) { try { return JSON.parse(String(value ?? '')); } catch { return fallback; } }
+function id(prefix) { return `${prefix}_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`; }
+
+async function runMutation(db, sql, args = []) {
+  const prepared = db.prepare(sql);
+  const bound = args.length ? prepared.bind(...args) : prepared;
+  if (typeof bound.run === 'function') return bound.run();
+  if (typeof bound.all === 'function') return bound.all();
+  if (typeof prepared.run === 'function') return prepared.run(...args);
+  throw new TypeError('database_statement_runner_unavailable');
+}
+
+export async function installPlugin(db, options = {}) {
+  if (!db?.prepare) throw new TypeError('D1-compatible database binding required');
+  const accountId = clean(options.accountId);
+  const environment = clean(options.environment || 'production');
+  if (!accountId) throw new Error('plugin_account_id_required');
+  const manifest = normalizePluginManifest(options.manifest);
+  let plugin = await db.prepare(`
+    SELECT id FROM agentsam_plugins
+    WHERE account_id = ? AND environment = ? AND plugin_key = ? AND installation_key = ?
+    LIMIT 1
+  `).bind(accountId, environment, manifest.plugin_key, manifest.installation_key).first();
+  const pluginId = plugin?.id || id('plg');
+  const values = [
+    manifest.provider_key, manifest.plugin_kind, manifest.category, manifest.display_name, manifest.short_name,
+    manifest.description, JSON.stringify(manifest.mention_aliases), manifest.endpoint_url, manifest.transport,
+    manifest.auth_type, manifest.secret_ref, manifest.oauth_connect_url,
+    JSON.stringify(manifest.capabilities.map((row) => row.capability_key)), JSON.stringify(manifest.tool_lanes),
+    JSON.stringify(manifest.resource_scope), JSON.stringify(manifest.config), JSON.stringify(manifest.metadata),
+    manifest.icon_url, manifest.icon_dark_url, manifest.icon_alt, manifest.icon_fit,
+    manifest.composer_visible ? 1 : 0, manifest.settings_visible ? 1 : 0, manifest.sort_priority,
+    manifest.health_strategy,
+  ];
+  if (plugin?.id) {
+    await runMutation(db, `
+      UPDATE agentsam_plugins SET
+        provider_key=?, plugin_kind=?, category=?, display_name=?, short_name=?, description=?, mention_aliases_json=?,
+        endpoint_url=?, transport=?, auth_type=?, secret_ref=?, oauth_connect_url=?, capabilities_json=?, tool_lanes_json=?,
+        resource_scope_json=?, config_json=?, metadata_json=?, icon_url=?, icon_dark_url=?, icon_alt=?, icon_fit=?,
+        composer_visible=?, settings_visible=?, sort_priority=?, health_strategy=?, is_enabled=1, updated_at=unixepoch()
+      WHERE id=?
+    `, [...values, pluginId]);
+  } else {
+    await runMutation(db, `
+      INSERT INTO agentsam_plugins (
+        id, account_id, plugin_key, provider_key, installation_key, environment, plugin_kind, category,
+        display_name, short_name, description, mention_aliases_json, endpoint_url, transport, auth_type,
+        secret_ref, oauth_connect_url, capabilities_json, tool_lanes_json, resource_scope_json, config_json,
+        metadata_json, icon_url, icon_dark_url, icon_alt, icon_fit, composer_visible, settings_visible,
+        sort_priority, is_enabled, setup_status, health_strategy, health_status, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 'unconfigured', ?, 'unknown', unixepoch(), unixepoch())
+    `, [pluginId, accountId, manifest.plugin_key, manifest.provider_key, manifest.installation_key, environment, ...values.slice(1)]);
+  }
+
+  for (const capability of manifest.capabilities) {
+    await runMutation(db, `
+      INSERT INTO agentsam_capabilities (capability_key, domain, verb, description, is_mutating, is_active, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, 1, unixepoch(), unixepoch())
+      ON CONFLICT(capability_key) DO UPDATE SET
+        domain=excluded.domain, verb=excluded.verb, description=excluded.description,
+        is_mutating=excluded.is_mutating, is_active=1, updated_at=unixepoch()
+    `, [capability.capability_key, capability.domain, capability.verb, capability.description, capability.is_mutating ? 1 : 0]);
+  }
+
+  for (const tool of manifest.tools) {
+    const existing = await db.prepare(`
+      SELECT id, tool_name FROM agentsam_tools
+      WHERE plugin_id = ? AND account_id = ? AND tool_key = ?
+      LIMIT 1
+    `).bind(pluginId, accountId, tool.tool_key).first();
+    const toolId = existing?.id || id('ast');
+    // The canonical schema intentionally keeps tool_name globally unique even
+    // though installed tools belong to an account. tool_key is the stable,
+    // model-facing identifier; tool_name is an internal unique function name.
+    const installedToolName = existing?.tool_name || `${tool.tool_name}__${toolId}`;
+    if (existing?.id) {
+      await runMutation(db, `
+        UPDATE agentsam_tools SET
+          display_name=?, tool_category=?, handler_type=?, description=?, input_schema=?, output_schema=?, handler_config=?,
+          intent_tags=?, risk_level=?, requires_approval=?, requires_confirmation=?, is_active=?, updated_at=unixepoch(),
+          tool_key=?, capability_key=?, handler_key=?, domain=?, oauth_visible=1, dispatch_target=?, connector_visible=?,
+          connector_priority=?, connector_access_class=?, account_id=?, plugin_key=?, plugin_id=?
+        WHERE id=?
+      `, [
+        tool.display_name, tool.tool_category, tool.handler_type, tool.description, JSON.stringify(tool.input_schema),
+        tool.output_schema ? JSON.stringify(tool.output_schema) : null, JSON.stringify(tool.handler_config), JSON.stringify(tool.intent_tags),
+        tool.risk_level, tool.requires_approval ? 1 : 0, tool.requires_confirmation ? 1 : 0, tool.is_active ? 1 : 0,
+        tool.tool_key, tool.capability_key, tool.handler_key, manifest.provider_key, tool.dispatch_target,
+        tool.connector_visible ? 1 : 0, manifest.sort_priority, tool.connector_access_class, accountId, manifest.plugin_key, pluginId, toolId,
+      ]);
+    } else {
+      await runMutation(db, `
+        INSERT INTO agentsam_tools (
+          id, tool_name, display_name, tool_category, handler_type, description, input_schema, output_schema,
+          handler_config, intent_tags, risk_level, requires_approval, requires_confirmation, is_active,
+          tool_key, capability_key, handler_key, domain, oauth_visible, dispatch_target, connector_visible,
+          connector_priority, connector_access_class, account_id, plugin_key, plugin_id, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?, unixepoch(), unixepoch())
+      `, [
+        toolId, installedToolName, tool.display_name, tool.tool_category, tool.handler_type, tool.description,
+        JSON.stringify(tool.input_schema), tool.output_schema ? JSON.stringify(tool.output_schema) : null,
+        JSON.stringify(tool.handler_config), JSON.stringify(tool.intent_tags), tool.risk_level,
+        tool.requires_approval ? 1 : 0, tool.requires_confirmation ? 1 : 0, tool.is_active ? 1 : 0,
+        tool.tool_key, tool.capability_key, tool.handler_key, manifest.provider_key, tool.dispatch_target,
+        tool.connector_visible ? 1 : 0, manifest.sort_priority, tool.connector_access_class, accountId, manifest.plugin_key, pluginId,
+      ]);
+    }
+    await runMutation(db, `
+      INSERT OR REPLACE INTO agentsam_tool_capabilities
+        (tool_id, capability_key, requirement_type, is_primary, operations_json, created_at)
+      VALUES (?, ?, 'required', 1, ?, unixepoch())
+    `, [toolId, tool.capability_key, JSON.stringify([tool.handler_key])]);
+  }
+  return { plugin_id: pluginId, account_id: accountId, plugin_key: manifest.plugin_key, tools: manifest.tools.length };
+}
+
+export async function listPlugins(db, options = {}) {
+  const accountId = clean(options.accountId);
+  const environment = clean(options.environment || 'production');
+  const result = await db.prepare(`
+    SELECT * FROM agentsam_plugins
+    WHERE account_id = ? AND environment = ? AND is_enabled = 1
+    ORDER BY sort_priority, display_name
+  `).bind(accountId, environment).all();
+  return (result?.results || []).map((row) => ({
+    ...row,
+    mention_aliases: json(row.mention_aliases_json, []), capabilities: json(row.capabilities_json, []),
+    tool_lanes: json(row.tool_lanes_json, []), resource_scope: json(row.resource_scope_json, {}),
+    config: json(row.config_json, {}), metadata: json(row.metadata_json, {}),
+  }));
+}
+
+export async function listPluginTools(db, options = {}) {
+  const accountId = clean(options.accountId);
+  const result = await db.prepare(`
+    SELECT t.* FROM agentsam_tools t
+    JOIN agentsam_plugins p ON p.id = t.plugin_id
+    WHERE t.account_id = ? AND t.is_active = 1 AND p.is_enabled = 1
+    ORDER BY t.connector_priority, t.sort_priority, t.tool_name
+  `).bind(accountId).all();
+  return (result?.results || []).map((row) => ({
+    ...row, input_schema: json(row.input_schema, {}), output_schema: json(row.output_schema, null),
+    handler_config: json(row.handler_config, {}), intent_tags: json(row.intent_tags, []),
+  }));
+}
+
+export async function recordPluginHealthCheck(db, value = {}) {
+  const startedAt = Number(value.startedAt || Math.floor(Date.now() / 1000));
+  const completedAt = Number(value.completedAt || Math.floor(Date.now() / 1000));
+  const checkId = id('plgh');
+  await runMutation(db, `
+    INSERT INTO agentsam_plugin_health_checks (
+      id, plugin_id, plugin_key, account_id, environment, check_kind, check_source, status,
+      started_at, completed_at, latency_ms, http_status, provider_request_id, error_code, error_message, details_json, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, unixepoch())
+  `, [
+    checkId, value.pluginId, value.pluginKey, value.accountId, value.environment || 'production', value.checkKind || 'adapter',
+    value.checkSource || 'manual', value.status, startedAt, completedAt, value.latencyMs ?? null, value.httpStatus ?? null,
+    value.providerRequestId || null, value.errorCode || null, value.errorMessage || null, JSON.stringify(value.details || {}),
+  ]);
+  const healthy = value.status === 'healthy';
+  await runMutation(db, `
+    UPDATE agentsam_plugins SET health_status=?, last_health_at=?,
+      last_healthy_at=CASE WHEN ? THEN ? ELSE last_healthy_at END,
+      consecutive_failures=CASE WHEN ? THEN 0 ELSE consecutive_failures + 1 END,
+      avg_latency_ms=CASE
+        WHEN ? IS NULL THEN avg_latency_ms
+        WHEN avg_latency_ms IS NULL THEN ?
+        ELSE ((avg_latency_ms * 4) + ?) / 5
+      END,
+      error_rate_24h=COALESCE((
+        SELECT CAST(SUM(CASE WHEN status = 'healthy' THEN 0 ELSE 1 END) AS REAL) / COUNT(*)
+        FROM agentsam_plugin_health_checks
+        WHERE plugin_id = ? AND created_at >= unixepoch() - 86400
+      ), 0),
+      last_error_code=?, last_error_message=?, updated_at=unixepoch()
+    WHERE id=? AND account_id=?
+  `, [
+    value.status, completedAt, healthy ? 1 : 0, completedAt, healthy ? 1 : 0,
+    value.latencyMs ?? null, value.latencyMs ?? null, value.latencyMs ?? null, value.pluginId,
+    value.errorCode || null, value.errorMessage || null,
+    value.pluginId, value.accountId,
+  ]);
+  return { id: checkId, status: value.status };
+}
+
+export async function recordToolCall(db, value = {}) {
+  const callId = clean(value.id) || id('atcl');
+  await runMutation(db, `
+    INSERT INTO agentsam_tool_call_log (
+      id, account_id, agent_run_id, conversation_id, call_index, tool_key, status, duration_ms,
+      error_code, failure_origin, cost_usd, input_tokens, output_tokens, cost_basis, source_client,
+      cache_hit, external_execution, result_source, created_at_unix, cache_eligible
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, unixepoch(), ?)
+  `, [
+    callId, value.accountId, value.agentRunId || null, value.conversationId || null, value.callIndex ?? null,
+    value.toolKey, value.status, Math.max(0, Number(value.durationMs || 0)), value.errorCode || '', value.failureOrigin || null,
+    Math.max(0, Number(value.costUsd || 0)), Math.max(0, Number(value.inputTokens || 0)), Math.max(0, Number(value.outputTokens || 0)),
+    value.costBasis || 'unknown', value.sourceClient || 'agentsam-sdk', value.cacheHit ? 1 : 0, value.externalExecution === false ? 0 : 1,
+    value.resultSource || 'live', value.cacheEligible ? 1 : 0,
+  ]);
+  return callId;
+}

package/src/plugins/resource-scope.js

@@ -0,0 +1,45 @@
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+export function resolveProjectPluginResources(projectConfig, pluginKey, resourceKey = null) {
+  return resolveProjectPluginScope(projectConfig, pluginKey, resourceKey);
+}
+
+export function resolveProjectRuntimeResources(projectConfig, pluginKey, resourceKey = null) {
+  const scope = resolveProjectPluginScope(projectConfig, pluginKey, resourceKey);
+  return Object.freeze({
+    project_name: clean(projectConfig?.project?.name) || null,
+    repository_id: clean(projectConfig?.repository?.id) || null,
+    plugin_key: scope.plugin_key,
+    resource_key: scope.resource_key || resourceKey || null,
+    resource: scope,
+  });
+}
+
+/** Resolve only the active project's declared resource scope. */
+export function resolveProjectPluginScope(projectConfig, pluginKey, resourceKey = null) {
+  const key = clean(pluginKey).replace(/^@/, '');
+  if (!key) throw new Error('plugin_key_required');
+  const plugins = projectConfig?.plugins || projectConfig?.integrations || {};
+  const plugin = plugins[key] || plugins[`@${key}`];
+  if (!plugin || typeof plugin !== 'object') throw new Error(`project_plugin_scope_missing:${key}`);
+  const resources = plugin.resources && typeof plugin.resources === 'object' ? plugin.resources : plugin;
+  if (resourceKey == null) return { plugin_key: key, ...resources };
+  const resource = resources[resourceKey];
+  if (!resource || typeof resource !== 'object') throw new Error(`project_resource_missing:${key}:${resourceKey}`);
+  return { plugin_key: key, resource_key: resourceKey, ...resource };
+}
+
+export function resolveProjectVectorizeScope(projectConfig, options = {}) {
+  const pluginKey = clean(options.pluginKey || 'cloudflare');
+  const resourceKey = clean(options.resourceKey || options.index || options.binding);
+  const scope = resolveProjectPluginScope(projectConfig, pluginKey, resourceKey || null);
+  const vectorize = scope.vectorize || scope;
+  const binding = clean(options.binding || vectorize.binding || vectorize.binding_name);
+  const index = clean(options.index || vectorize.index || vectorize.index_name);
+  const model = clean(options.model || vectorize.model || vectorize.embedding_model);
+  const dimensions = Number(options.dimensions || vectorize.dimensions || vectorize.dimension);
+  if (!binding || !index || !model || !Number.isInteger(dimensions) || dimensions < 1) {
+    throw new Error(`project_vectorize_scope_incomplete:${pluginKey}:${resourceKey || 'default'}`);
+  }
+  return Object.freeze({ plugin_key: pluginKey, resource_key: resourceKey || null, binding, index, model, dimensions });
+}

package/src/plugins/runtime.js

@@ -0,0 +1,118 @@
+import { recordToolCall } from './registry.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+export async function executeAgentSamTool(options = {}) {
+  const tool = options.tool;
+  if (!tool?.tool_key) throw new Error('agentsam_tool_required');
+  const context = options.context || {};
+  const started = Date.now();
+  let status = 'success';
+  let errorCode = '';
+  let failureOrigin = null;
+  try {
+    if (typeof options.authorizeTool === 'function') {
+      const authorization = await options.authorizeTool({ tool, args: options.args || {}, context });
+      if (authorization === false || authorization?.allowed === false) {
+        const error = new Error(`tool_not_authorized:${tool.tool_key}`);
+        error.code = 'AGENTSAM_TOOL_NOT_AUTHORIZED';
+        throw error;
+      }
+    }
+    if (Boolean(tool.requires_approval) || Boolean(tool.requires_confirmation)) {
+      const approved = typeof options.requireApproval === 'function'
+        ? await options.requireApproval({ tool, args: options.args || {}, context })
+        : false;
+      if (approved !== true) {
+        const error = new Error(`tool_not_approved:${tool.tool_key}`);
+        error.code = 'AGENTSAM_TOOL_NOT_APPROVED';
+        throw error;
+      }
+    }
+    const target = clean(tool.dispatch_target || 'plugin');
+    // The persisted row selects the lane and handler family. This keeps
+    // installed plugins generic instead of embedding provider names in the
+    // AgentSam orchestration loop.
+    const dispatcher = typeof options.resolveDispatcher === 'function'
+      ? await options.resolveDispatcher({ tool, target, context })
+      : options.dispatchers?.[target]
+        || options.dispatchers?.[clean(tool.handler_type)]
+        || options.handlers?.[clean(tool.handler_type)]
+        || options.handlers?.[clean(tool.handler_key)];
+    if (typeof dispatcher !== 'function') throw new Error(`tool_dispatcher_unavailable:${target}`);
+    return await dispatcher({ tool, args: options.args || {}, context });
+  } catch (error) {
+    status = error?.code === 'AGENTSAM_TOOL_NOT_AUTHORIZED' || error?.code === 'AGENTSAM_TOOL_NOT_APPROVED' ? 'blocked' : 'error';
+    errorCode = clean(error?.code || error?.message || 'tool_error').slice(0, 160);
+    failureOrigin = status === 'blocked' ? 'policy' : 'tool';
+    throw error;
+  } finally {
+    if (options.db?.prepare && context.accountId) {
+      try {
+        await recordToolCall(options.db, {
+          accountId: context.accountId,
+          agentRunId: context.agentRunId,
+          conversationId: context.conversationId,
+          callIndex: context.callIndex,
+          toolKey: tool.tool_key,
+          status,
+          durationMs: Date.now() - started,
+          errorCode,
+          failureOrigin,
+          sourceClient: context.sourceClient || 'agentsam-sdk',
+          externalExecution: true,
+        });
+      } catch {
+        // Execution evidence is best-effort here; the primary tool result wins.
+      }
+    }
+  }
+}
+
+export function createPluginRuntime(options = {}) {
+  const tools = Array.isArray(options.tools) ? options.tools : [];
+  const byKey = new Map(tools.map((tool) => [clean(tool.tool_key), tool]));
+  return Object.freeze({
+    tools: Object.freeze([...tools]),
+    toolDescriptors() {
+      return tools.map((tool) => ({
+        name: tool.tool_key,
+        description: tool.description || '',
+        category: tool.tool_category || tool.plugin_key || 'integrations',
+        risk: tool.risk_level || 'low',
+        input_schema: tool.input_schema || { type: 'object', properties: {}, required: [], additionalProperties: false },
+        requires_approval: Boolean(tool.requires_approval),
+        requires_confirmation: Boolean(tool.requires_confirmation),
+        dispatch_target: tool.dispatch_target,
+      }));
+    },
+    resolveTool(toolKey) { return byKey.get(clean(toolKey)) || null; },
+    execute(toolKey, args = {}, context = {}) {
+      const tool = byKey.get(clean(toolKey));
+      if (!tool) throw new Error(`agentsam_tool_not_found:${toolKey}`);
+      return executeAgentSamTool({
+        tool, args, context, db: options.db, dispatchers: options.dispatchers,
+        handlers: options.handlers, resolveDispatcher: options.resolveDispatcher,
+        authorizeTool: options.authorizeTool, requireApproval: options.requireApproval,
+      });
+    },
+  });
+}
+
+export function createPluginCapabilityAdapter(pluginRuntime, baseAdapter = null) {
+  if (!pluginRuntime?.toolDescriptors || !pluginRuntime?.execute) throw new TypeError('plugin_runtime_required');
+  return Object.freeze({
+    toolDescriptors(options = {}) {
+      const base = baseAdapter?.toolDescriptors?.(options) || [];
+      return [...base, ...pluginRuntime.toolDescriptors()];
+    },
+    canInvoke(id) { return Boolean(pluginRuntime.resolveTool(id) || baseAdapter?.canInvoke?.(id)); },
+    async invoke(id, input = {}) {
+      if (pluginRuntime.resolveTool(id)) {
+        return { capability_id: id, capability_version: 'plugin-v1', result: await pluginRuntime.execute(id, input) };
+      }
+      if (!baseAdapter?.invoke) throw new Error(`capability_handler_unavailable:${id}`);
+      return baseAdapter.invoke(id, input);
+    },
+  });
+}

package/src/plugins/vectorize.js

@@ -0,0 +1,31 @@
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+export function resolveVectorizeConfig(tool, context = {}, args = {}) {
+  const config = tool?.handler_config || {};
+  const scope = context.resourceScope || context.resource_scope || {};
+  const bindingName = clean(args.binding || config.binding || scope.binding);
+  const indexName = clean(args.index || config.index || scope.index);
+  const model = clean(args.model || config.model || scope.model) || null;
+  if (!bindingName || !indexName) throw new Error('project_vectorize_binding_and_index_required');
+  const binding = typeof context.resolveBinding === 'function'
+    ? context.resolveBinding(bindingName, { tool, scope })
+    : context.bindings?.[bindingName];
+  if (!binding || typeof binding.query !== 'function') throw new Error(`project_vectorize_binding_unavailable:${bindingName}`);
+  return { binding, bindingName, indexName, model, dimensions: Number(config.dimensions || scope.dimensions || 0) || null };
+}
+
+export async function executeVectorizeTool({ tool, args = {}, context = {} }) {
+  const { binding, bindingName, indexName, model, dimensions } = resolveVectorizeConfig(tool, context, args);
+  const operation = clean(args.operation || tool.handler_config?.operation || 'query').toLowerCase();
+  const index = typeof binding.get === 'function' ? binding.get(indexName) : binding;
+  if (!index) throw new Error(`project_vectorize_index_unavailable:${bindingName}:${indexName}`);
+  if (operation === 'query') {
+    const vector = args.vector || (typeof context.embed === 'function' ? await context.embed(String(args.text || args.q || ''), { model, dimensions }) : null);
+    if (!Array.isArray(vector)) throw new Error('project_vectorize_query_vector_required');
+    if (dimensions && vector.length !== dimensions) throw new Error(`project_vectorize_dimension_mismatch:${vector.length}!=${dimensions}`);
+    return index.query(vector, { topK: Number(args.topK || args.top_k || 10), returnMetadata: args.returnMetadata !== false, namespace: args.namespace });
+  }
+  if (operation === 'upsert') return index.upsert(args.vectors || args.items || []);
+  if (operation === 'delete') return index.deleteByIds(args.ids || []);
+  throw new Error(`project_vectorize_operation_unsupported:${operation}`);
+}

package/src/progression/engine.js

@@ -0,0 +1,171 @@
+/**
+ * Generic AgentSam progression engine — not brand-specific.
+ * Capabilities emit state + findings; this ranks next_actions for any domain.
+ */
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   label: string,
+ *   reason: string,
+ *   command?: string,
+ *   capability?: string,
+ *   priority?: number,
+ *   requires_model?: boolean,
+ *   safe?: boolean,
+ * }} NextAction
+ */
+
+/**
+ * @param {{
+ *   capability: string,
+ *   result?: object,
+ *   session?: object,
+ *   rules?: Array<{
+ *     when: (ctx: object) => boolean,
+ *     action: NextAction | ((ctx: object) => NextAction)
+ *   }>
+ * }} opts
+ * @returns {{ next_actions: NextAction[] }}
+ */
+export function suggestNextActions(opts = {}) {
+  const ctx = {
+    capability: opts.capability || '',
+    result: opts.result || {},
+    session: opts.session || {},
+  };
+
+  const rules = opts.rules?.length ? opts.rules : defaultRules();
+  const out = [];
+  for (const rule of rules) {
+    try {
+      if (!rule.when(ctx)) continue;
+      const action = typeof rule.action === 'function' ? rule.action(ctx) : rule.action;
+      if (action?.id) out.push({
+        requires_model: false,
+        safe: true,
+        priority: 50,
+        ...action,
+      });
+    } catch {
+      // ignore broken rules
+    }
+  }
+
+  out.sort((a, b) => (b.priority || 0) - (a.priority || 0));
+  // de-dupe by id
+  const seen = new Set();
+  const next_actions = [];
+  for (const a of out) {
+    if (seen.has(a.id)) continue;
+    seen.add(a.id);
+    next_actions.push(a);
+  }
+  return { next_actions };
+}
+
+function defaultRules() {
+  return [
+    {
+      when: (ctx) => ctx.capability === 'brand.scan' && (ctx.result.conflicts?.length || 0) > 0,
+      action: (ctx) => ({
+        id: 'brand.inspect.conflicts',
+        label: 'Inspect token conflicts',
+        reason: `${ctx.result.conflicts.length} probable conflicts discovered`,
+        command: 'agentsam brand inspect conflicts',
+        capability: 'brand.inspect',
+        priority: 90,
+      }),
+    },
+    {
+      when: (ctx) => ctx.capability === 'brand.scan' && ctx.result.complete !== false,
+      action: {
+        id: 'brand.plan',
+        label: 'Generate a brand normalization plan',
+        reason: 'Scan complete — plan preserve/normalize/migrate steps',
+        command: 'agentsam plan brand',
+        capability: 'brand.plan',
+        priority: 80,
+      },
+    },
+    {
+      when: (ctx) => ctx.capability === 'brand.scan',
+      action: {
+        id: 'brand.resolve',
+        label: 'Resolve semantic color roles',
+        reason: 'Cluster near-duplicate colors into inferred roles',
+        command: 'agentsam brand resolve',
+        capability: 'brand.resolve',
+        priority: 75,
+      },
+    },
+    {
+      when: (ctx) => ctx.capability === 'brand.plan',
+      action: {
+        id: 'brand.apply.preview',
+        label: 'Review apply steps (dry-run)',
+        reason: 'Mutations require explicit approval',
+        command: 'agentsam brand apply --dry-run',
+        capability: 'brand.apply',
+        priority: 70,
+        safe: true,
+      },
+    },
+    {
+      when: (ctx) => ctx.capability === 'repository.snapshot',
+      action: {
+        id: 'brand.scan',
+        label: 'Scan brand evidence',
+        reason: 'Repository authority ready — discover visual language',
+        command: 'agentsam brand scan',
+        capability: 'brand.scan',
+        priority: 85,
+      },
+    },
+    {
+      when: (ctx) => ctx.capability === 'brand.scan' || ctx.capability === 'repository.snapshot',
+      action: {
+        id: 'inspect.repository',
+        label: 'Inspect repository snapshot',
+        reason: 'Review classified files and trust boundary',
+        command: 'agentsam inspect',
+        capability: 'repository.snapshot',
+        priority: 40,
+      },
+    },
+  ];
+}
+
+/**
+ * Deterministic intent router for free-text without a model.
+ */
+export function routeDeterministicIntent(text, session = {}) {
+  const q = String(text || '').trim().toLowerCase();
+  if (!q) return null;
+
+  if (/^(status|where am i)\b/.test(q) || q === 'status') {
+    return { intent: 'status', command: 'agentsam status' };
+  }
+  if (/what (should|can) i do next|what next|^next\b|suggest/.test(q)) {
+    return { intent: 'next', use_progression: true };
+  }
+  if (/show (me )?(the )?brand|brand status|what.*(brand|colors)/.test(q)) {
+    return { intent: 'show-brand', command: 'agentsam brand' };
+  }
+  if (/show (me )?(the )?plan|what.*(plan)/.test(q)) {
+    return { intent: 'show-plan', command: 'agentsam plan brand' };
+  }
+  if (/what (did you )?find|show findings|inconsisten/.test(q)) {
+    return { intent: 'show-findings', command: 'agentsam brand inspect conflicts' };
+  }
+  if (/^help\b|\?$/.test(q)) {
+    return { intent: 'help', command: 'agentsam help' };
+  }
+  if (/continue|keep going/.test(q)) {
+    return { intent: 'continue', use_progression: true };
+  }
+  if (session.last_capability && /explain|why/.test(q)) {
+    return { intent: 'explain-last', command: null };
+  }
+  return null;
+}

package/src/progression/index.js

@@ -0,0 +1 @@
+export { suggestNextActions, routeDeterministicIntent } from './engine.js';

package/src/providers/cloudflare-chat.js

@@ -48,7 +48,7 @@ function toolCalls(message = {}) {
 export function createCloudflareChatAdapter(options = {}) {
   const credential = options.credential || {};
   const apiToken = clean(credential.value || process.env.CLOUDFLARE_API_TOKEN);
-  const accountId = clean(credential.account_id || process.env.CLOUDFLARE_ACCOUNT_ID || process.env.ACCOUNT_ID);
+  const accountId = clean(credential.account_id || process.env.CLOUDFLARE_ACCOUNT_ID);
   const gatewayId = clean(options.gatewayId || process.env.CLOUDFLARE_AI_GATEWAY_ID || 'default');
   const fetchImpl = options.fetchImpl || fetch;
 

package/src/providers/gemini-generate-content.js

@@ -1,3 +1,4 @@
+import { compileToolSchema } from './tool-schema.js';
 import { createAgentEvent, createUsageSnapshot } from '../telemetry/index.js';
 import { calculateModelCost } from '../models/index.js';
 import { diagnosticFromError } from '../errors/index.js';
@@ -14,7 +15,7 @@ function toolDeclarations(tools = []) {
   return tools.map((tool) => ({
     name: tool.name,
     description: tool.description || '',
-    parameters: tool.parameters || { type: 'object', properties: {} },
+    parametersJsonSchema: compileToolSchema({ provider: 'gemini', canonicalSchema: tool.parameters, name: tool.name }).providerSchema,
   }));
 }
 function usageParts(response = {}) {