@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

package/src/utils/childAgentContext.ts

@@ -1,259 +0,0 @@
-/**
- * Child-agent context preparation utilities.
- *
- * When a parent agent invokes a child agent — via handoff, sequence edge,
- * or scoped subgraph — the child cannot just receive `state.messages`
- * verbatim. The parent's conversation contains tool_use/tool_result blocks
- * that are (a) often incompatible with the child's tool registry, and
- * (b) actively harmful to the child's ability to reason cleanly about its
- * own task (noise → schema confusion → malformed tool_use).
- *
- * This module provides the two canonical strategies, extracted from
- * `MultiAgentGraph` so they can be unit-tested in isolation and reused by
- * future sub-agent orchestrators:
- *
- *   1. `prepareHandoffMessages` — "cleaned parent history"
- *      Used when the child still needs the orchestrator's context (it's
- *      the handoff target). Drops orphaned tool_use, compacts paired
- *      tool_use/tool_result into text summaries, and guarantees the tail
- *      is a HumanMessage so Bedrock/VertexAI won't reject the conversation
- *      with "assistant message prefill" errors.
- *
- *   2. `prepareIsolatedChildMessages` — "fresh session"
- *      Used for downstream sequence-node children inside a scoped subgraph.
- *      The child sees only the original user request plus a synthetic
- *      HumanMessage summarizing the upstream agent's final text output and
- *      directing the child to act. Raw upstream tool_use/tool_result blocks
- *      are discarded.
- *
- * Both helpers are pure functions over message arrays — no I/O, no
- * LangGraph coupling — so they can be exercised by unit tests with
- * synthetic message fixtures.
- */
-
-import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
-import type { AIMessageChunk, BaseMessage } from '@langchain/core/messages';
-
-/* -------------------------------------------------------------------------- */
-/*  Prompt template constants (kept outside the functions for reuse/tuning)   */
-/* -------------------------------------------------------------------------- */
-
-/**
- * Prefix injected in front of a trailing AIMessage when we flip it to a
- * HumanMessage to satisfy provider "last message must be user" rules.
- */
-export const HANDOFF_TAIL_CONTEXT_PREFIX = '[Context from orchestrator]: ';
-
-/**
- * Directive task-framing wrapper for downstream scoped-subgraph children.
- *
- * Design notes — each line is load-bearing:
- *  - "Prior step output" names the upstream role without leaking the
- *    agent's internal id.
- *  - "You MUST now perform..." replaces ambiguity with obligation.
- *  - "system instructions" references the agent's stored system prompt
- *    as the source of task definition — so operators can tune behavior
- *    via data, not code.
- *  - The tool-first clause prevents small/fast models from stalling on a
- *    text-only acknowledgement when a tool action is expected.
- */
-export function buildIsolatedChildPrompt(upstreamText: string): string {
-  return (
-    '## Prior step output\n\n' +
-    upstreamText +
-    '\n\n---\n\n' +
-    '## Your task\n\n' +
-    'The previous step in this workflow has completed. You MUST now ' +
-    'perform your own task as defined in your system instructions, ' +
-    "using the prior step's output as input where relevant.\n\n" +
-    'If your task requires calling a tool, call it directly — do not ' +
-    'ask for clarification and do not produce a text-only response when ' +
-    'a tool action is expected.'
-  );
-}
-
-/* -------------------------------------------------------------------------- */
-/*  Internal helpers                                                          */
-/* -------------------------------------------------------------------------- */
-
-/**
- * Extract concatenated text content from an AI message's content field.
- * Handles both the string shape (OpenAI/plain) and the array-of-blocks
- * shape (Anthropic/Bedrock).
- */
-function extractAIText(msg: AIMessage | AIMessageChunk): string {
-  const content = msg.content;
-  if (typeof content === 'string') return content;
-  if (!Array.isArray(content)) return '';
-  return (content as Array<{ type?: string; text?: string }>)
-    .filter((b) => b.type === 'text' && typeof b.text === 'string')
-    .map((b) => b.text ?? '')
-    .join('\n');
-}
-
-/* -------------------------------------------------------------------------- */
-/*  Strategy 1: cleaned parent history (handoff target / root subgraph)       */
-/* -------------------------------------------------------------------------- */
-
-/**
- * Prepare messages for a handoff child agent.
- *
- * Handles two problems that break Bedrock/Anthropic conversations:
- *
- * 1. **Orphaned tool_use**: The parent's AI message contains a `tool_use`
- *    block for the handoff tool itself, with no matching `tool_result`.
- *    Providers (Bedrock/Anthropic) reject this.
- *
- * 2. **Paired tool_use/tool_result in history**: The child may not have
- *    the same tools as the parent. Bedrock requires `toolConfig` when any
- *    tool_use/tool_result blocks exist in the history. Compacting these
- *    into text summaries avoids the requirement and reduces context bloat.
- *
- * Also ensures the tail is a HumanMessage — some providers reject a
- * conversation that ends with an assistant message.
- *
- * @param messages - Current state messages from the parent
- * @returns A sanitized copy, safe to pass to any provider as the child's
- *          input regardless of which tools the child has registered.
- */
-export function prepareHandoffMessages(messages: BaseMessage[]): BaseMessage[] {
-  if (messages.length === 0) return messages;
-
-  /** Collect tool_result IDs so we know which tool_use blocks are paired */
-  const pairedToolCallIds = new Set<string>();
-  for (const msg of messages) {
-    if (msg.getType() === 'tool') {
-      const tm = msg as ToolMessage;
-      if (tm.tool_call_id) pairedToolCallIds.add(tm.tool_call_id);
-    }
-  }
-
-  /**
-   * Pass 1: Drop all ToolMessages (paired ones are compacted in pass 2),
-   * rewrite AI messages with tool_calls into plain-text summaries, leave
-   * other messages untouched.
-   */
-  const cleaned: BaseMessage[] = [];
-  for (const msg of messages) {
-    if (msg.getType() === 'tool') continue;
-
-    if (msg.getType() !== 'ai') {
-      cleaned.push(msg);
-      continue;
-    }
-
-    const aiMsg = msg as AIMessage | AIMessageChunk;
-    const toolCalls = aiMsg.tool_calls ?? [];
-    if (toolCalls.length === 0) {
-      cleaned.push(msg);
-      continue;
-    }
-
-    const textContent = extractAIText(aiMsg);
-
-    const toolSummaries: string[] = [];
-    for (const tc of toolCalls) {
-      if (tc.id != null && pairedToolCallIds.has(tc.id)) {
-        const toolResult = messages.find(
-          (m) =>
-            m.getType() === 'tool' && (m as ToolMessage).tool_call_id === tc.id
-        ) as ToolMessage | undefined;
-        const resultContent = toolResult
-          ? typeof toolResult.content === 'string'
-            ? toolResult.content.slice(0, 500)
-            : '[complex result]'
-          : '[no result]';
-        toolSummaries.push(`[Tool "${tc.name}": ${resultContent}]`);
-      }
-      // Orphaned tool_use blocks (no matching result) are silently dropped.
-    }
-
-    const parts = [textContent, ...toolSummaries].filter(Boolean);
-    if (parts.length > 0) {
-      cleaned.push(
-        new AIMessage({ content: parts.join('\n\n'), id: aiMsg.id })
-      );
-    }
-  }
-
-  /**
-   * Ensure messages end with a HumanMessage. After stripping tool artifacts
-   * the tail may be an AIMessage, which Bedrock/VertexAI reject. Convert it
-   * to a HumanMessage preserving whatever text content was present, or drop
-   * it entirely if empty.
-   */
-  if (cleaned.length > 0 && cleaned[cleaned.length - 1].getType() === 'ai') {
-    const lastAI = cleaned[cleaned.length - 1];
-    const content = typeof lastAI.content === 'string' ? lastAI.content : '';
-    if (content.trim()) {
-      cleaned[cleaned.length - 1] = new HumanMessage(
-        `${HANDOFF_TAIL_CONTEXT_PREFIX}${content}`
-      );
-    } else {
-      cleaned.pop();
-    }
-  }
-
-  return cleaned;
-}
-
-/* -------------------------------------------------------------------------- */
-/*  Strategy 2: isolated fresh session (downstream scoped-subgraph child)     */
-/* -------------------------------------------------------------------------- */
-
-/**
- * Build an ISOLATED message context for a downstream scoped-subgraph node.
- *
- * Unlike `prepareHandoffMessages` (which cleans up tool_use artifacts but
- * preserves most of the parent history), this helper produces a fresh
- * minimal context containing only:
- *
- *   1. The original user request (first HumanMessage in the history)
- *   2. A synthetic HumanMessage summarizing the upstream agent's final
- *      text output and directing the downstream agent to act on it
- *
- * Tool_use / tool_result blocks from the upstream agent are discarded —
- * the downstream agent shouldn't reason about how the upstream agent did
- * its work, only about the result.
- *
- * This "fresh subagent session" pattern is the primary defense against
- * schema confusion / malformed tool_use JSON that occurs when downstream
- * models see a noisy upstream conversation.
- *
- * Defensive fallback: if the messages array contains neither a user
- * message nor a non-empty upstream AI message, return the input unchanged
- * so the caller still has something to invoke on. This only matters for
- * malformed state fixtures in tests.
- */
-export function prepareIsolatedChildMessages(
-  messages: BaseMessage[]
-): BaseMessage[] {
-  if (messages.length === 0) return messages;
-
-  /** First HumanMessage is the original user request */
-  const originalUser = messages.find((m) => m.getType() === 'human');
-
-  /** Most recent AIMessage with non-empty text content */
-  let upstreamText = '';
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i];
-    if (msg.getType() !== 'ai') continue;
-    const text = extractAIText(msg as AIMessage | AIMessageChunk);
-    if (text.trim()) {
-      upstreamText = text;
-      break;
-    }
-  }
-
-  const result: BaseMessage[] = [];
-  if (originalUser) result.push(originalUser);
-
-  if (upstreamText.trim()) {
-    result.push(new HumanMessage(buildIsolatedChildPrompt(upstreamText)));
-  } else if (result.length === 0) {
-    /** Defensive: nothing to isolate — fall back to raw messages */
-    return messages;
-  }
-
-  return result;
-}

package/src/utils/credentials.ts

@@ -1,157 +0,0 @@
-/**
- * Credential merging utility for capability providers.
- *
- * The host is the source of truth for credential values. It resolves them
- * from env vars, user settings, or active OAuth sessions, then passes a
- * flat CredentialMap to the provider.
- *
- * This utility helps hosts build that map from multiple sources with clear
- * precedence rules. Providers themselves do NOT use this — they just receive
- * the finished map.
- */
-
-import type {
-  AuthConfigEntry,
-  Capability,
-  CredentialMap,
-} from '@/providers/types';
-import { AuthSource } from '@/providers/types';
-
-/**
- * Source of a credential value in the merged result. Useful for logging
- * and debugging which layer won a given authField.
- */
-export enum CredentialOrigin {
-  /** From the caller's process env (typically the CLI). */
-  ENV = 'env',
-  /** From the agent definition's tool_credentials block. */
-  AGENT = 'agent',
-  /** From the user's stored credentials in the host's credential store. */
-  USER = 'user',
-  /** From an active OAuth session forwarded by the host. */
-  SESSION = 'session',
-  /** Injected by the host at runtime for another reason. */
-  RUNTIME = 'runtime',
-}
-
-/** One layer of credentials with its origin. */
-export interface CredentialLayer {
-  origin: CredentialOrigin;
-  values: CredentialMap;
-}
-
-/**
- * Merge credential layers with earlier layers overriding later ones.
- *
- * Typical host flow (in order of precedence):
- *   1. runtime overrides (e.g., test injection)       → RUNTIME
- *   2. active OAuth session tokens                    → SESSION
- *   3. agent-defined tool_credentials                 → AGENT
- *   4. user's stored credentials                      → USER
- *   5. process env                                    → ENV
- *
- * Caller passes layers in precedence order (highest first).
- */
-export function mergeCredentials(...layers: CredentialLayer[]): CredentialMap {
-  const merged: CredentialMap = {};
-  // Iterate reverse so first-declared layer wins on collision.
-  for (let i = layers.length - 1; i >= 0; i--) {
-    const layer = layers[i];
-    for (const [key, value] of Object.entries(layer.values)) {
-      if (value !== undefined && value !== null && value !== '') {
-        merged[key] = value;
-      }
-    }
-  }
-  return merged;
-}
-
-/**
- * Given a set of capabilities, return the union of authField names they
- * require. Useful for hosts that want to pre-resolve credentials before
- * calling createRunnables.
- */
-export function collectRequiredAuthFields(
-  capabilities: Capability[]
-): string[] {
-  const fields = new Set<string>();
-  for (const cap of capabilities) {
-    for (const entry of cap.authConfig) {
-      fields.add(entry.authField);
-    }
-  }
-  return Array.from(fields);
-}
-
-/**
- * Filter out credentials that the provider is expected to resolve itself
- * (source === SERVER). Hosts call this before forwarding — these values
- * live in the provider's own environment and shouldn't be sent.
- *
- * Precedence: entries without `source` default to USER (must be forwarded).
- */
-export function filterForwardableCredentials(
-  credentials: CredentialMap,
-  capabilities: Capability[]
-): CredentialMap {
-  const serverManagedFields = new Set<string>();
-  for (const cap of capabilities) {
-    for (const entry of cap.authConfig) {
-      if (entry.source === AuthSource.SERVER) {
-        serverManagedFields.add(entry.authField);
-      }
-    }
-  }
-  const forwardable: CredentialMap = {};
-  for (const [key, value] of Object.entries(credentials)) {
-    if (!serverManagedFields.has(key)) {
-      forwardable[key] = value;
-    }
-  }
-  return forwardable;
-}
-
-/**
- * Validate that all required credentials for a capability are present in
- * the provided map. Returns the list of missing authFields (empty array
- * if all satisfied). Credentials with `source === SERVER` are excluded
- * from the check since the provider resolves them.
- */
-export function findMissingCredentials(
-  capability: Capability,
-  credentials: CredentialMap
-): string[] {
-  const missing: string[] = [];
-  for (const entry of capability.authConfig) {
-    if (entry.source === AuthSource.SERVER) continue;
-    if (!entry.required) continue;
-    if (!credentials[entry.authField]) {
-      missing.push(entry.authField);
-    }
-  }
-  return missing;
-}
-
-/**
- * Build a CredentialLayer from process env given a list of authField names.
- * Values that aren't set in env are omitted (not set to empty string).
- */
-export function credentialsFromEnv(
-  authFields: readonly string[],
-  env: NodeJS.ProcessEnv = process.env
-): CredentialLayer {
-  const values: CredentialMap = {};
-  for (const field of authFields) {
-    const value = env[field];
-    if (value) values[field] = value;
-  }
-  return { origin: CredentialOrigin.ENV, values };
-}
-
-/**
- * Type guard: check whether an auth config entry should be forwarded by
- * the host (vs resolved by the provider itself).
- */
-export function isForwardable(entry: AuthConfigEntry): boolean {
-  return entry.source !== AuthSource.SERVER;
-}

package/src/utils/httpClient.ts

@@ -1,92 +0,0 @@
-/**
- * HTTP client utility for capability providers.
- *
- * Wraps axios with proxy support, default headers, and consistent retry
- * behavior so every provider doesn't reinvent the wheel. Used by
- * ToolsServerCapabilityProvider and (future) any HTTP-backed provider.
- *
- * Proxy resolution follows the existing pattern in this codebase:
- * the PROXY env var is read and an HttpsProxyAgent is attached if present.
- */
-
-import axios, { type AxiosInstance, type AxiosRequestConfig } from 'axios';
-import { HttpsProxyAgent } from 'https-proxy-agent';
-
-/** Configuration for creating an HTTP client. */
-export interface HttpClientConfig {
-  /** Base URL prepended to all requests. */
-  baseURL: string;
-  /** Optional API key — if present, sent as `x-api-key` header. */
-  apiKey?: string;
-  /** Custom header map merged into every request. */
-  headers?: Record<string, string>;
-  /** Request timeout in milliseconds. Defaults to 30_000. */
-  timeoutMs?: number;
-  /**
-   * Override for the PROXY env var. Useful for tests. If undefined,
-   * falls back to process.env.PROXY.
-   */
-  proxy?: string | null;
-}
-
-/**
- * Build an axios instance configured per HttpClientConfig.
- *
- * The returned instance should be retained (not recreated per request) so
- * keepalive connections can be reused.
- */
-export function createHttpClient(config: HttpClientConfig): AxiosInstance {
-  const { baseURL, apiKey, headers = {}, timeoutMs = 30_000, proxy } = config;
-
-  const resolvedProxy = proxy === undefined ? process.env.PROXY : proxy;
-
-  const defaultHeaders: Record<string, string> = {
-    'content-type': 'application/json',
-    ...headers,
-  };
-  if (apiKey) {
-    defaultHeaders['x-api-key'] = apiKey;
-  }
-
-  const axiosConfig: AxiosRequestConfig = {
-    baseURL,
-    timeout: timeoutMs,
-    headers: defaultHeaders,
-    // Don't throw on non-2xx — callers handle status codes explicitly.
-    validateStatus: () => true,
-  };
-
-  if (resolvedProxy) {
-    // axios respects `httpsAgent` for outbound proxying
-    axiosConfig.httpsAgent = new HttpsProxyAgent(resolvedProxy);
-    axiosConfig.httpAgent = new HttpsProxyAgent(resolvedProxy);
-    // Disable axios's built-in proxy logic in favor of the agent.
-    axiosConfig.proxy = false;
-  }
-
-  return axios.create(axiosConfig);
-}
-
-/**
- * Thin wrapper around an axios response that throws with a structured error
- * on non-2xx status codes. Providers use this to get uniform error surface.
- */
-export class HttpError extends Error {
-  readonly status: number;
-  readonly body: unknown;
-  readonly url: string;
-  constructor(status: number, url: string, body: unknown) {
-    super(`HTTP ${status} on ${url}`);
-    this.name = 'HttpError';
-    this.status = status;
-    this.url = url;
-    this.body = body;
-  }
-}
-
-/** Assert that an axios response is a 2xx; throw HttpError otherwise. */
-export function assertOk(status: number, url: string, body: unknown): void {
-  if (status < 200 || status >= 300) {
-    throw new HttpError(status, url, body);
-  }
-}

package/src/utils/toolManifest.ts

@@ -1,109 +0,0 @@
-/**
- * Tool manifest cache.
- *
- * Providers fetch a manifest at init and potentially on refresh. This
- * utility provides a minimal TTL cache so repeated fetchManifest() calls
- * don't hammer the backing server.
- *
- * Caching is opt-in — providers that want fresh data every time (e.g.,
- * MCP with dynamic tool lists) can skip this entirely.
- */
-
-import type { Capability, CapabilityFilter } from '@/providers/types';
-
-/** Entry in the manifest cache. */
-interface CacheEntry {
-  expiresAt: number;
-  capabilities: Capability[];
-}
-
-export interface ManifestCacheConfig {
-  /** Time-to-live in milliseconds. 0 disables caching. Defaults to 60_000 (1 min). */
-  ttlMs?: number;
-}
-
-/**
- * Simple in-memory TTL cache for manifests, keyed by a caller-supplied
- * cache key (e.g., the filter hash or a fixed constant for unfiltered).
- *
- * Thread-safety: the cache uses a plain Map. Node's single-threaded event
- * loop makes this safe for typical use. Not safe across workers — each
- * worker keeps its own cache (fine, since manifests are small).
- */
-export class ManifestCache {
-  private readonly ttlMs: number;
-  private readonly store = new Map<string, CacheEntry>();
-
-  constructor(config: ManifestCacheConfig = {}) {
-    this.ttlMs = config.ttlMs ?? 60_000;
-  }
-
-  /** Retrieve cached capabilities, or undefined on miss / expiry. */
-  get(key: string): Capability[] | undefined {
-    const entry = this.store.get(key);
-    if (!entry) return undefined;
-    if (entry.expiresAt < Date.now()) {
-      this.store.delete(key);
-      return undefined;
-    }
-    return entry.capabilities;
-  }
-
-  /** Insert or replace cached capabilities for the given key. */
-  set(key: string, capabilities: Capability[]): void {
-    if (this.ttlMs <= 0) return;
-    this.store.set(key, {
-      expiresAt: Date.now() + this.ttlMs,
-      capabilities,
-    });
-  }
-
-  /** Remove all cached entries. */
-  clear(): void {
-    this.store.clear();
-  }
-
-  /** For tests / diagnostics. */
-  get size(): number {
-    return this.store.size;
-  }
-}
-
-/**
- * Build a deterministic cache key from a CapabilityFilter.
- *
- * Two identical filters always produce the same key. Providers use this
- * so `fetchManifest(filter)` and `fetchManifest(sameFilter)` hit the
- * same cache entry.
- */
-export function filterToCacheKey(filter?: CapabilityFilter): string {
-  if (!filter) return '__all__';
-  const parts: string[] = [];
-  if (filter.kind) parts.push(`kind=${filter.kind}`);
-  if (filter.tags?.length)
-    parts.push(`tags=${[...filter.tags].sort().join(',')}`);
-  if (filter.names?.length)
-    parts.push(`names=${[...filter.names].sort().join(',')}`);
-  return parts.length ? parts.join('|') : '__all__';
-}
-
-/**
- * Apply a CapabilityFilter to a pre-fetched manifest. Used by providers
- * that fetch the full manifest once and filter in memory.
- */
-export function applyFilter(
-  capabilities: Capability[],
-  filter?: CapabilityFilter
-): Capability[] {
-  if (!filter) return capabilities;
-  return capabilities.filter((cap) => {
-    if (filter.kind && cap.kind !== filter.kind) return false;
-    if (filter.names && !filter.names.includes(cap.name)) return false;
-    if (filter.tags?.length) {
-      const capTags = new Set(cap.metadata.tags ?? []);
-      const anyMatch = filter.tags.some((t) => capTags.has(t));
-      if (!anyMatch) return false;
-    }
-    return true;
-  });
-}