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

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

@@ -0,0 +1,70 @@
+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

@@ -0,0 +1,115 @@
+/**
+ * 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>;