@illuma-ai/agents 1.5.1 → 2.1.1

package/src/tools/subagent/types.test.ts

@@ -1,70 +0,0 @@
-import { describe, it, expect } from '@jest/globals';
-import {
-  MANIFEST_PREFIX,
-  formatFileManifest,
-  formatManifestEntry,
-} from './types';
-
-/**
- * Unit tests for the shared subagent file-passing types module.
- *
- * The manifest format is contractual: the supervisor's LLM is taught to look
- * for `MANIFEST_PREFIX` in its context and pass `file_id` strings into the
- * `subagent` tool's `file_ids` arg. Regressions here silently break selective
- * file passing — assert format strictly.
- */
-describe('formatManifestEntry', () => {
-  it('formats minimal entry (file_id + name only)', () => {
-    expect(
-      formatManifestEntry({ file_id: 'f_1', name: 'data.csv' })
-    ).toBe('- file_id: f_1, name: data.csv');
-  });
-
-  it('includes type when present', () => {
-    expect(
-      formatManifestEntry({
-        file_id: 'f_2',
-        name: 'chart.png',
-        type: 'image/png',
-      })
-    ).toBe('- file_id: f_2, name: chart.png, type: image/png');
-  });
-
-  it('formats bytes as B / KB / MB', () => {
-    expect(
-      formatManifestEntry({ file_id: 'f_3', name: 'a', size: 512 })
-    ).toContain('size: 512B');
-    expect(
-      formatManifestEntry({ file_id: 'f_4', name: 'a', size: 12_000 })
-    ).toContain('size: 12KB');
-    expect(
-      formatManifestEntry({
-        file_id: 'f_5',
-        name: 'a',
-        size: 5 * 1024 * 1024,
-      })
-    ).toContain('size: 5.0MB');
-  });
-});
-
-describe('formatFileManifest', () => {
-  it('returns null for empty input', () => {
-    expect(formatFileManifest([])).toBeNull();
-  });
-
-  it('begins with MANIFEST_PREFIX header', () => {
-    const out = formatFileManifest([
-      { file_id: 'f_1', name: 'data.csv' },
-    ]);
-    expect(out).not.toBeNull();
-    expect(out!.startsWith(MANIFEST_PREFIX)).toBe(true);
-  });
-
-  it('joins entries on newlines below header', () => {
-    const out = formatFileManifest([
-      { file_id: 'f_1', name: 'a' },
-      { file_id: 'f_2', name: 'b' },
-    ]);
-    expect(out).toBe(`${MANIFEST_PREFIX}\n- file_id: f_1, name: a\n- file_id: f_2, name: b`);
-  });
-});

package/src/tools/subagent/types.ts

@@ -1,115 +0,0 @@
-/**
- * Shared types for the subagent file-passing pipeline.
- *
- * Single source of truth for:
- *   - the `file_ids` shape carried on the `subagent` tool's input schema
- *   - the manifest line format the host renders into the supervisor's
- *     trailing user-message channel (cache-stable, never the system block)
- *   - the resolver hook signature host applications implement to map
- *     parent-side `file_id`s into the child's `tool_resources` + first
- *     HumanMessage context blocks
- *
- * Keeping these in one place lets the lib, the host, and tests all
- * reference the SAME constants — drift would silently break selective
- * file passing (parent claims a file is available, child gets `null`).
- */
-
-/**
- * One entry in the parent's file manifest. The host serializes an array of
- * these into a short newline-delimited block that lives in the supervisor's
- * trailing user-message channel — see `MANIFEST_PREFIX` /
- * `formatFileManifest` for the canonical line format.
- */
-export interface SubagentFileManifestEntry {
-  /** Stable file ID. Parent's LLM passes this back via `subagent({ file_ids })`. */
-  file_id: string;
-  /** Display name, used in the manifest line. */
-  name: string;
-  /** MIME type. Optional — only included in the manifest when present. */
-  type?: string;
-  /** Size in bytes. Optional — formatted for human readability when present. */
-  size?: number;
-}
-
-/** Header line that begins every parent file manifest block. */
-export const MANIFEST_PREFIX = 'Files available for delegation:';
-
-/**
- * Format a single manifest entry as a `- key: value, key: value, ...` line.
- * Pure function — keeps the format consistent across host injection paths
- * and test assertions.
- */
-export function formatManifestEntry(entry: SubagentFileManifestEntry): string {
-  const parts: string[] = [`file_id: ${entry.file_id}`, `name: ${entry.name}`];
-  if (entry.type) {
-    parts.push(`type: ${entry.type}`);
-  }
-  if (typeof entry.size === 'number' && Number.isFinite(entry.size)) {
-    parts.push(`size: ${formatBytes(entry.size)}`);
-  }
-  return `- ${parts.join(', ')}`;
-}
-
-/**
- * Format a full manifest block for injection below the cache breakpoint.
- * Returns `null` for empty input so callers can `if (block) push(block)`.
- */
-export function formatFileManifest(
-  entries: readonly SubagentFileManifestEntry[]
-): string | null {
-  if (!entries || entries.length === 0) return null;
-  const lines = entries.map(formatManifestEntry);
-  return [MANIFEST_PREFIX, ...lines].join('\n');
-}
-
-/** Human-readable byte formatter used by the manifest. */
-function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes}B`;
-  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)}KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-
-/**
- * Result of resolving parent-side `file_ids` for a child subagent invocation.
- * Each field is shaped to slot directly into the child's runtime:
- *   - `toolResources` is merged into the child's `agentInputs.tool_resources`
- *     so file_search / execute_code tools see the file
- *   - `messageContextBlocks` is prepended to the child's first HumanMessage
- *     (alongside the supervisor's task description) so the child sees image
- *     blocks for vision models and a short text reference for everything else
- */
-export interface ResolvedSubagentFiles {
-  /**
-   * Augmented tool_resources object merged into the child's `agentInputs`.
-   * Shape matches `AgentToolResources` from the host (kept untyped here to
-   * avoid pulling host types into the lib).
-   */
-  toolResources?: Record<string, unknown>;
-  /**
-   * Files the resolver successfully looked up. Forwarded verbatim into the
-   * child's first message metadata for downstream attachment rendering.
-   */
-  attachments?: Array<Record<string, unknown>>;
-  /**
-   * LangChain `HumanMessage.content` blocks (text or image_url) that should
-   * be prepended to the child's first message. Empty array for the common
-   * case where files are referenced only via tool_resources.
-   */
-  messageContextBlocks?: Array<Record<string, unknown>>;
-}
-
-/**
- * Hook the host injects to resolve parent-side `file_id`s into child runtime
- * context. Called once per `subagent` tool invocation that includes
- * `file_ids`. Must be cheap on the empty-array path — the lib calls it for
- * every subagent dispatch.
- *
- * @param fileIds - ID strings the supervisor's LLM picked from the manifest.
- * @param childAgentId - ID assigned to the child for this invocation.
- * @returns Resolved file context for the child, or `undefined` when nothing
- *   could be resolved (treated as a soft no-op — the child still runs).
- */
-export type ResolveSubagentFiles = (
-  fileIds: string[],
-  childAgentId: string
-) => Promise<ResolvedSubagentFiles | undefined>;

package/src/types/agent-cache.ts

@@ -1,74 +0,0 @@
-/**
- * Agent system-message prompt-cache types.
- * ==========================================
- *
- * `@illuma-ai/agents` exposes a generic primitive — `system_cache_blocks` —
- * for composing a system message that gets explicit cache markers
- * (cachePoint on Bedrock, cache_control on Anthropic) at consumer-defined
- * boundaries. The library encodes each entry into the right wire format
- * for the active provider; consumers decide what content to put in each
- * block.
- *
- * Why this is generic rather than tier-named
- * ------------------------------------------------
- * Earlier iterations exposed `platform_instructions` and `cache_ttl:
- * { platform, agent }` — vocabulary borrowed from a specific consumer's
- * multi-tenant chat-platform mental model. That leaked one consumer's
- * domain into the library and made it confusing for other consumers
- * (CLI tools, desktop apps, gateways) which have no notion of
- * "platforms" or "agents".
- *
- * The current shape lets every consumer define their own cache-tier
- * organization without the library knowing or caring.
- *
- * Cache key composition
- * ---------------------
- * Both Anthropic and Bedrock hash the message bytes leading up to each
- * cache marker. So entry N's cache key is the concatenation of bytes
- * 0..N. Stable content (universal rules, framework docs) goes earlier;
- * volatile content (per-agent identity, per-tool docs) goes later. The
- * earlier entries get cross-tenant cache hits; the later entries get
- * narrower hits.
- *
- * Provider budget
- * ---------------
- * Bedrock's Converse API supports up to 4 cachePoint blocks per request.
- * The default tools-array cache strategy (see `IllumaBedrockConverse`)
- * uses up to 2 of those. So at most 2 entries should appear in
- * `system_cache_blocks` to leave budget for the trailing
- * `instructions` block. The library throws on more than 2.
- *
- * Anthropic supports up to 4 cache breakpoints per request workspace-wide;
- * the same constraint applies to keep tools + system within budget.
- */
-
-/** Provider TTL hint applied to a cachePoint / cache_control marker. */
-export type AgentCacheTTL = '5m' | '1h';
-
-/**
- * One cacheable system content block. Each entry produces a text block
- * followed by a provider-specific cache marker in the assembled system
- * message. Entries are emitted in array order — earlier = more stable
- * = wider cache key.
- */
-export interface SystemCacheBlock {
-  /**
-   * Text payload. Caller is responsible for keeping this byte-stable
-   * across requests that should share a cache entry. ANY change to
-   * these bytes invalidates every cache key that includes this entry.
-   */
-  text: string;
-  /**
-   * Optional TTL hint for the cache marker. Defaults to '5m' when
-   * omitted. '1h' costs more to write (2× base vs 1.25×) but survives
-   * longer idle, which is the right tradeoff for low-traffic blocks.
-   */
-  ttl?: AgentCacheTTL;
-}
-
-/**
- * Maximum number of `system_cache_blocks` entries the library accepts.
- * Higher than this would exceed Bedrock's 4-cachePoint budget once the
- * tools array and trailing `instructions` block are counted.
- */
-export const MAX_SYSTEM_CACHE_BLOCKS = 2;