@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/src/tools/redact.js

@@ -0,0 +1,64 @@
+const ALWAYS_SENSITIVE_KEY = /^(authorization|proxy-authorization|api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password|credential|credentials)$/i;
+const REDACTED = '[REDACTED]';
+
+function cloneAndRedactSecrets(value, seen = new WeakSet()) {
+  if (value == null || typeof value !== 'object') return value;
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.map((item) => cloneAndRedactSecrets(item, seen));
+  }
+
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    output[key] = ALWAYS_SENSITIVE_KEY.test(key)
+      ? REDACTED
+      : cloneAndRedactSecrets(child, seen);
+  }
+  return output;
+}
+
+function redactMatchingKey(value, keyName) {
+  if (!value || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    for (const item of value) redactMatchingKey(item, keyName);
+    return;
+  }
+  for (const key of Object.keys(value)) {
+    if (key === keyName) value[key] = REDACTED;
+    else redactMatchingKey(value[key], keyName);
+  }
+}
+
+function redactPath(value, path) {
+  const parts = String(path || '').split('.').map((part) => part.trim()).filter(Boolean);
+  if (!parts.length || !value || typeof value !== 'object') return;
+
+  if (parts.length === 1) {
+    redactMatchingKey(value, parts[0]);
+    return;
+  }
+
+  let current = value;
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    if (!current || typeof current !== 'object') return;
+    current = current[parts[index]];
+  }
+  if (current && typeof current === 'object' && Object.hasOwn(current, parts.at(-1))) {
+    current[parts.at(-1)] = REDACTED;
+  }
+}
+
+export function redactToolValue(value, sensitivePaths = []) {
+  const safe = cloneAndRedactSecrets(value);
+  for (const path of sensitivePaths || []) redactPath(safe, path);
+  return safe;
+}
+
+export function receiptPayload(value, { mode = 'full', sensitivePaths = [] } = {}) {
+  if (mode === 'metadata_only') return undefined;
+  return redactToolValue(value, mode === 'redacted' ? sensitivePaths : []);
+}
+
+export { REDACTED as AGENTSAM_REDACTED_VALUE };

package/src/tools/registry.js

@@ -0,0 +1,83 @@
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function assertToolDefinition(definition) {
+  if (!definition || typeof definition !== 'object') {
+    throw new TypeError('tool definition must be an object');
+  }
+  if (!clean(definition.toolKey)) throw new TypeError('tool definition requires toolKey');
+  if (!clean(definition.capabilityKey)) throw new TypeError(`tool ${definition.toolKey} requires capabilityKey`);
+  if (!definition.inputSchema || typeof definition.inputSchema !== 'object') {
+    throw new TypeError(`tool ${definition.toolKey} requires inputSchema`);
+  }
+  if (!definition.outputSchema || typeof definition.outputSchema !== 'object') {
+    throw new TypeError(`tool ${definition.toolKey} requires outputSchema`);
+  }
+  return definition;
+}
+
+export function createToolRegistry({ tools = [], adapters = [], handlers = [] } = {}) {
+  const toolsByKey = new Map();
+  const adaptersByProvider = new Map();
+  const handlersByRef = new Map();
+
+  function registerTool(definition) {
+    assertToolDefinition(definition);
+    const key = clean(definition.toolKey);
+    if (toolsByKey.has(key)) throw new Error(`duplicate tool definition: ${key}`);
+    toolsByKey.set(key, Object.freeze({ ...definition }));
+    return toolsByKey.get(key);
+  }
+
+  function registerAdapter(adapter) {
+    const providerKey = clean(adapter?.providerKey);
+    if (!providerKey || typeof adapter?.invoke !== 'function') {
+      throw new TypeError('provider adapter requires providerKey and invoke()');
+    }
+    if (adaptersByProvider.has(providerKey)) throw new Error(`duplicate provider adapter: ${providerKey}`);
+    adaptersByProvider.set(providerKey, adapter);
+    return adapter;
+  }
+
+  function registerHandler(ref, handler) {
+    const key = clean(ref);
+    if (!key || typeof handler !== 'function') {
+      throw new TypeError('tool handler requires a ref and function');
+    }
+    if (handlersByRef.has(key)) throw new Error(`duplicate tool handler: ${key}`);
+    handlersByRef.set(key, handler);
+    return handler;
+  }
+
+  for (const definition of tools) registerTool(definition);
+  for (const adapter of adapters) registerAdapter(adapter);
+  if (handlers instanceof Map) {
+    for (const [ref, handler] of handlers) registerHandler(ref, handler);
+  } else if (Array.isArray(handlers)) {
+    for (const entry of handlers) registerHandler(entry?.ref, entry?.handler);
+  } else if (handlers && typeof handlers === 'object') {
+    for (const [ref, handler] of Object.entries(handlers)) registerHandler(ref, handler);
+  }
+
+  return Object.freeze({
+    registerTool,
+    registerAdapter,
+    registerHandler,
+    getTool(toolKey) {
+      return toolsByKey.get(clean(toolKey)) || null;
+    },
+    getAdapter(providerKey) {
+      return adaptersByProvider.get(clean(providerKey)) || null;
+    },
+    getHandler(ref) {
+      return handlersByRef.get(clean(ref)) || null;
+    },
+    listTools({ activeOnly = true } = {}) {
+      return [...toolsByKey.values()].filter((tool) => !activeOnly || tool.active !== false);
+    },
+    listProviders() {
+      return [...adaptersByProvider.keys()];
+    },
+  });
+}

package/src/tools/runtime.js

@@ -0,0 +1,257 @@
+import { ERROR_REASON_POLICY, normalizeError } from '../errors/index.js';
+import { receiptPayload, redactToolValue } from './redact.js';
+
+function defaultId(prefix) {
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+
+function reasonForError(error) {
+  const status = Number(error?.status || error?.http_status || 0);
+  if (status === 401) return 'provider_credential_invalid';
+  if (status === 403) return 'provider_scope_insufficient';
+  if (status === 409) return 'conflict';
+  if (status === 429) return 'provider_rate_limited';
+  if (status === 408 || status === 504) return 'transport_timeout';
+  if (status >= 500) return 'provider_unavailable';
+  if (status === 400 || status === 422) return 'provider_request_invalid';
+  if (error?.code === 'completeful_idempotency_required') return 'input_invalid';
+  if (error instanceof TypeError) return 'input_invalid';
+  return 'execution_failed';
+}
+
+function normalizeToolError(error, definition) {
+  const reason = reasonForError(error);
+  const policy = ERROR_REASON_POLICY[reason] || ERROR_REASON_POLICY.execution_failed;
+  return normalizeError(error, {
+    code: policy.code,
+    reason,
+    source: definition.provider
+      ? { kind: 'provider', name: definition.provider, service: definition.provider }
+      : { kind: 'runtime', name: 'agentsam-tool-runtime' },
+    domain: 'tool',
+    tool: definition.toolKey,
+    provider: definition.provider || null,
+    provider_code: error?.code || null,
+    request_id: error?.requestId || null,
+    details: {
+      path: error?.path || null,
+      remediation: error?.remediation || null,
+    },
+  });
+}
+
+function invocationFromRequest(definition, request, makeId, now) {
+  const id = String(request.id || makeId('inv'));
+  const requestedAt = Number(request.requestedAt || now());
+  const explicitIdempotencyKey = String(request.idempotencyKey || '').trim();
+  const idempotencyKey =
+    explicitIdempotencyKey ||
+    (definition.idempotencyMode === 'required' ? id : undefined);
+
+  return {
+    id,
+    toolKey: definition.toolKey,
+    input: request.input ?? {},
+    requestedAt,
+    accountId: request.accountId,
+    correlationId: request.correlationId,
+    causationId: request.causationId,
+    idempotencyKey,
+    metadata: request.metadata,
+  };
+}
+
+async function resolveExecutionTarget(registry, definition) {
+  const handler = definition.handler?.ref ? registry.getHandler(definition.handler.ref) : null;
+  if (handler) {
+    return async (invocation, context) => handler(invocation, context, definition);
+  }
+
+  if (definition.provider) {
+    const adapter = registry.getAdapter(definition.provider);
+    if (!adapter) throw new Error(`provider adapter not registered: ${definition.provider}`);
+    return (invocation, context) => adapter.invoke(invocation, context);
+  }
+
+  throw new Error(`tool has no registered execution target: ${definition.toolKey}`);
+}
+
+async function observe(callback, value, label) {
+  if (typeof callback !== 'function') return null;
+  try {
+    await callback(value);
+    return null;
+  } catch (error) {
+    return {
+      observer: label,
+      message: String(error?.message || error),
+    };
+  }
+}
+
+export function createToolExecutor({
+  registry,
+  resolveAuthority,
+  recordReceipt,
+  onEvent,
+  now = () => Date.now(),
+  makeId = defaultId,
+} = {}) {
+  if (!registry?.getTool) throw new TypeError('tool executor requires a registry');
+
+  async function execute(request = {}) {
+    const definition = registry.getTool(request.toolKey);
+    if (!definition) throw new Error(`tool not registered: ${request.toolKey || '<missing>'}`);
+    if (definition.active === false) throw new Error(`tool is inactive: ${definition.toolKey}`);
+
+    const invocation = invocationFromRequest(definition, request, makeId, now);
+    const startedAt = now();
+    const safeInput = receiptPayload(invocation.input, {
+      mode: definition.receiptMode || 'full',
+      sensitivePaths: definition.sensitiveInputPaths || [],
+    });
+
+    let authority;
+    if (typeof resolveAuthority === 'function' && definition.authority?.length) {
+      authority = await resolveAuthority(definition.authority, { definition, invocation });
+    }
+
+    const context = {
+      authority,
+      accountId: invocation.accountId,
+      deadlineAt: definition.timeoutMs ? startedAt + definition.timeoutMs : undefined,
+      metadata: {
+        toolKey: definition.toolKey,
+        capabilityKey: definition.capabilityKey,
+        riskLevel: definition.riskLevel,
+        sideEffectLevel: definition.sideEffectLevel,
+      },
+    };
+
+    let invoke;
+    try {
+      invoke = await resolveExecutionTarget(registry, definition);
+    } catch (error) {
+      const normalized = normalizeToolError(error, definition);
+      const completedAt = now();
+      const receipt = {
+        invocationId: invocation.id,
+        toolKey: definition.toolKey,
+        status: 'failed',
+        ok: false,
+        attempt: 1,
+        startedAt,
+        completedAt,
+        durationMs: Math.max(0, completedAt - startedAt),
+        provider: definition.provider,
+        input: safeInput,
+        error: normalized,
+      };
+      const observerErrors = [];
+      const receiptObserverError = await observe(recordReceipt, receipt, 'recordReceipt');
+      if (receiptObserverError) observerErrors.push(receiptObserverError);
+      return { ok: false, definition, invocation, error: normalized, receipt, events: [], observerErrors };
+    }
+
+    try {
+      const result = (await invoke(invocation, context)) || {};
+      const completedAt = now();
+      const mode = definition.receiptMode || 'full';
+      const safeOutput = receiptPayload(result.output, {
+        mode,
+        sensitivePaths: definition.sensitiveOutputPaths || [],
+      });
+      const safeMetadata = redactToolValue(result.metadata || {});
+
+      const events = (definition.emitsEvents || []).map((eventKey) => ({
+        id: makeId('evt'),
+        eventKey,
+        occurredAt: completedAt,
+        source: {
+          kind: 'tool',
+          provider: definition.provider || undefined,
+          ref: invocation.id,
+          metadata: {
+            tool_key: definition.toolKey,
+            capability_key: definition.capabilityKey,
+          },
+        },
+        payload: {
+          tool_key: definition.toolKey,
+          output: safeOutput,
+          provider_request_id: result.providerRequestId || null,
+        },
+        accountId: invocation.accountId,
+        correlationId: invocation.correlationId,
+        causationId: invocation.id,
+      }));
+
+      const receipt = {
+        invocationId: invocation.id,
+        toolKey: definition.toolKey,
+        status: 'completed',
+        ok: true,
+        attempt: 1,
+        startedAt,
+        completedAt,
+        durationMs: Math.max(0, completedAt - startedAt),
+        provider: definition.provider,
+        input: safeInput,
+        output: safeOutput,
+        emittedEventIds: events.map((event) => event.id),
+        providerRequestId: result.providerRequestId,
+        usage: redactToolValue(result.usage || {}),
+        metadata: safeMetadata,
+      };
+
+      const observerErrors = [];
+      const receiptObserverError = await observe(recordReceipt, receipt, 'recordReceipt');
+      if (receiptObserverError) observerErrors.push(receiptObserverError);
+      for (const event of events) {
+        const eventObserverError = await observe(onEvent, event, 'onEvent');
+        if (eventObserverError) observerErrors.push(eventObserverError);
+      }
+
+      return {
+        ok: true,
+        definition,
+        invocation,
+        output: result.output,
+        receipt,
+        events,
+        observerErrors,
+      };
+    } catch (error) {
+      const completedAt = now();
+      const normalized = normalizeToolError(error, definition);
+      const receipt = {
+        invocationId: invocation.id,
+        toolKey: definition.toolKey,
+        status: 'failed',
+        ok: false,
+        attempt: 1,
+        startedAt,
+        completedAt,
+        durationMs: Math.max(0, completedAt - startedAt),
+        provider: definition.provider,
+        input: safeInput,
+        error: normalized,
+      };
+      const observerErrors = [];
+      const receiptObserverError = await observe(recordReceipt, receipt, 'recordReceipt');
+      if (receiptObserverError) observerErrors.push(receiptObserverError);
+
+      return {
+        ok: false,
+        definition,
+        invocation,
+        error: normalized,
+        receipt,
+        events: [],
+        observerErrors,
+      };
+    }
+  }
+
+  return Object.freeze({ execute });
+}

package/src/tools/search.js

@@ -2,19 +2,32 @@ import { DEFAULT_RESULT_POLICY, normalizeResultPolicy } from '../context/result-
 
 function text(value) { return value == null ? '' : String(value).trim(); }
 
+function toolName(tool) {
+  return text(tool.toolKey || tool.tool || tool.name);
+}
+
+function toolRisk(tool) {
+  const legacy = text(tool.risk);
+  if (legacy) return legacy;
+  if (tool.sideEffectLevel === 'none') return 'read';
+  return text(tool.riskLevel) || 'write';
+}
+
 export function toToolCard(tool = {}) {
   const required = Array.isArray(tool.required)
     ? tool.required
-    : Array.isArray(tool.input_schema?.required)
-      ? tool.input_schema.required
-      : [];
+    : Array.isArray(tool.inputSchema?.required)
+      ? tool.inputSchema.required
+      : Array.isArray(tool.input_schema?.required)
+        ? tool.input_schema.required
+        : [];
   return Object.freeze({
-    tool: text(tool.tool || tool.name),
-    summary: text(tool.summary || tool.description),
-    category: text(tool.category) || undefined,
-    risk: text(tool.risk) || 'read',
+    tool: toolName(tool),
+    summary: text(tool.summary || tool.description || tool.displayName),
+    category: text(tool.category || tool.provider || tool.pluginId) || undefined,
+    risk: toolRisk(tool),
     required: Object.freeze([...required]),
-    result_class: text(tool.result_class) || 'bounded_evidence',
+    result_class: text(tool.result_class || tool.resultClass) || 'bounded_evidence',
   });
 }
 

package/src/ui/ansi.js

@@ -1,4 +1,5 @@
 import pc from 'picocolors';
+import { buildStatusActionPlan, formatStatusNextSteps } from '../status/actions.js';
 
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 
@@ -51,17 +52,130 @@ export function renderLocalStatus(status) {
     ),
   );
   lines.push(row('sqlite', `${state(status.db.ready)} · ${status.db.tables.length} tables`, width));
-  lines.push(row('api', `${state(status.api.online)} · ${status.api.url}`, width));
+  const liveOk = status.live?.online === true;
+  const apiLine = liveOk
+    ? `${state(true, 'live')} · ${status.live.url}`
+    : `${state(status.api.online)} · ${status.api.url}`;
+  lines.push(row('api', apiLine, width));
   lines.push(row('pty', `${state(status.pty.online)} · ${status.pty.url.replace('/health', '')}`, width));
   lines.push(row('deploy', status.deployTarget || pc.dim('local only'), width));
   lines.push(`${pc.cyan('├')}${pc.cyan('─'.repeat(width - 2))}${pc.cyan('┤')}`);
 
   const actions = [];
+  if (liveOk) {
+    const liveApp = String(status.live?.url || '').replace(/\/(?:api\/)?health\/?$/i, '');
+    if (liveApp) actions.push(`open ${liveApp}`);
+    actions.push('agentsam cloudflare status');
+  }
   if (!status.db.ready) actions.push('agentsam db init');
-  if (!status.api.online) actions.push('npm run dev');
+  if (!liveOk && !status.api.online && status.deployTarget !== 'cloudflare') actions.push('npm run dev');
+  if (!liveOk && status.deployTarget === 'cloudflare') actions.push('agentsam cloudflare status');
   if (!status.pty.online) actions.push('npm run pty');
-  if (!actions.length) actions.push('local stack healthy');
+  if (!actions.length) actions.push('stack healthy');
   lines.push(row('next', pc.bold(actions.join(' · ')), width));
   lines.push(`${pc.cyan('╰')}${pc.cyan('─'.repeat(width - 2))}${pc.cyan('╯')}`);
   return lines.join('\n');
 }
+
+function yesNo(value, yes = 'ready', no = 'not ready') {
+  return value ? pc.green(`● ${yes}`) : pc.yellow(`○ ${no}`);
+}
+
+export function renderRuntimeStatus(status) {
+  const lines = [
+    `  ${pc.bold(`Agent Sam · ${status.local?.project || 'runtime'}`)}`,
+    `  ${status.ready ? pc.green('Ready for authenticated model + terminal work') : status.local_ready ? pc.green('Local Agent Sam available · connected features need setup') : pc.yellow('Local state needs setup or repair')}`,
+    '',
+    `  account      ${yesNo(status.checks?.account, status.identity?.active_auth?.kind || 'authenticated', 'not authenticated')}`,
+  ];
+  if (status.state_storage) {
+    lines.push(`  state        SQLite · ${status.state_storage.migrated ? 'migrated' : 'not initialized'} · ${status.state_storage.path}`);
+    lines.push(`  actor       ${pc.dim(status.state_storage.actor_runtime || 'none')}`);
+  }
+  if (status.identity?.identity?.email) lines.push(`  identity     ${status.identity.identity.email}`);
+  if (status.identity?.api_key?.valid === false && status.identity?.active_auth?.kind === 'browser_oauth') {
+    lines.push(`  auth note    ${pc.yellow('invalid environment API key ignored; browser OAuth is active')}`);
+  }
+
+  const configuredProviders = status.model_summary?.configured_providers || [];
+  lines.push(`  models       ${yesNo(status.checks?.models, `${status.model_summary?.verified_provider_models || 0} provider-verified`, 'no verified model')}`);
+  lines.push(`  providers    ${configuredProviders.length ? configuredProviders.join(', ') : pc.dim('none configured')}`);
+
+  const terminal = status.terminal || {};
+  lines.push(`  terminal     ${yesNo(status.checks?.terminal, `${terminal.active_connection_count || 0} active remote · local PTY ${terminal.local_pty?.online ? 'online' : 'offline'}`, 'no usable connection')}`);
+  for (const connection of (terminal.connections || []).filter((row) => row.active).slice(0, 6)) {
+    lines.push(`    ${connection.default ? '★' : '•'} ${connection.name || connection.id} · ${connection.kind || 'terminal'} · ${connection.health || 'unknown'}`);
+  }
+  if (terminal.error && !status.offline) lines.push(`  terminal err ${pc.yellow(terminal.error)}`);
+
+  const cloudflare = status.cloudflare || {};
+  if (cloudflare.configured) {
+    const version = cloudflare.version?.number != null ? `v${cloudflare.version.number}` : 'version unknown';
+    lines.push(`  deployment   ${yesNo(status.checks?.cloudflare, `${cloudflare.worker_name} · ${version}`, `${cloudflare.worker_name || 'Worker'} not verified`)}`);
+
+    const hasLive = Array.isArray(cloudflare.bindings?.live) && cloudflare.bindings.live.length > 0;
+    const summary = hasLive
+      ? (cloudflare.bindings.match
+          ? pc.green(`${cloudflare.bindings.live.length} live · declared contract satisfied`)
+          : pc.yellow(`${cloudflare.bindings?.missing?.length || 0} missing`))
+      : pc.dim(`${(cloudflare.bindings?.declared || []).length} declared contract bindings`);
+    lines.push(`  bindings     ${summary}`);
+
+    const liveBindings = cloudflare.bindings?.live || [];
+    const declaredBindings = cloudflare.bindings?.declared || [];
+    const declaredMap = new Map((Array.isArray(declaredBindings) ? declaredBindings : []).map((row) => [row.name, row]));
+
+    const rawResources = (cloudflare.bindings?.resources && cloudflare.bindings.resources.length > 0)
+      ? cloudflare.bindings.resources
+      : (liveBindings.length > 0 ? liveBindings : declaredBindings).filter(
+          (r) => r.type !== 'plain_text' && r.type !== 'json' && r.type !== 'secret_text' && r.type !== 'secret_key'
+        );
+
+    const sortedResources = [...rawResources].sort((a, b) => {
+      if (a.name === 'DB') return -1;
+      if (b.name === 'DB') return 1;
+      return a.name.localeCompare(b.name);
+    });
+
+    for (const b of sortedResources) {
+      const decl = declaredMap.get(b.name) || {};
+      const detail = b.database_name || decl.database_name || b.bucket_name || decl.bucket_name || b.service || decl.service || b.id || decl.id || '';
+      const typeDisplay = b.type === 'r2_bucket' ? 'r2' : b.type;
+      const detailStr = detail ? pc.dim(` (${detail})`) : '';
+      lines.push(`               • ${pc.bold(b.name)} · ${typeDisplay}${detailStr}`);
+    }
+
+    const varCount = cloudflare.bindings?.runtime_variables?.length
+      ?? (liveBindings.length > 0 ? liveBindings : declaredBindings).filter((r) => r.type === 'plain_text' || r.type === 'json').length;
+    const secretCount = cloudflare.bindings?.runtime_secrets?.length
+      ?? (liveBindings.length > 0 ? liveBindings : declaredBindings).filter((r) => r.type === 'secret_text' || r.type === 'secret_key').length;
+    if (varCount > 0 || secretCount > 0) {
+      lines.push(`               • ${pc.dim(`${varCount} vars · ${secretCount} secrets`)}`);
+    }
+
+    if (cloudflare.bindings?.missing?.length) {
+      lines.push(`               ${pc.red(`✗ missing: ${cloudflare.bindings.missing.map((b) => b.name).join(', ')}`)}`);
+    }
+
+    const healthUrl = cloudflare.health?.url || '';
+    lines.push(
+      `  health       ${
+        cloudflare.health?.ok
+          ? pc.green(`HTTP ${cloudflare.health.status}${healthUrl ? ` · ${healthUrl}` : ''}`)
+          : pc.yellow(cloudflare.health?.error || 'not verified')
+      }`,
+    );
+    if (cloudflare.error) lines.push(`  cloud error  ${pc.yellow(cloudflare.error)}`);
+  } else {
+    lines.push(`  deployment   ${pc.dim('not configured for this project')}`);
+  }
+
+  lines.push('');
+  lines.push(`  git          ${status.local?.git ? `${status.local.git.branch || 'detached'} · ${status.local.git.dirty ? pc.yellow('dirty') : pc.green('clean')} · ${String(status.local.git.revision || '').slice(0, 8)}` : pc.dim('not a git repository')}`);
+  lines.push(`  project      ${status.local?.root || ''}`);
+  if (status.offline) lines.push(`  mode         ${pc.dim('offline snapshot; live identity/models/terminal/deployment not verified')}`);
+
+  const plan = buildStatusActionPlan(status);
+  lines.push(formatStatusNextSteps(plan));
+  return lines.join('\n');
+}