@cuylabs/agent-core 0.4.0 → 0.6.0

package/dist/chunk-6TDTQJ4P.js

@@ -0,0 +1,116 @@
+// src/models/resolver.ts
+function parseKey(input) {
+  const [engineId, ...rest] = input.split("/");
+  if (!engineId || rest.length === 0) return null;
+  return { engineId, modelId: rest.join("/") };
+}
+function mergeSettings(base, override) {
+  return {
+    apiKey: override?.apiKey ?? base?.apiKey,
+    baseUrl: override?.baseUrl ?? base?.baseUrl,
+    headers: {
+      ...base?.headers ?? {},
+      ...override?.headers ?? {}
+    },
+    extra: {
+      ...base?.extra ?? {},
+      ...override?.extra ?? {}
+    }
+  };
+}
+function settingsKey(settings, adapter, engineId) {
+  return JSON.stringify({
+    engineId,
+    adapter,
+    apiKey: settings.apiKey ?? "",
+    baseUrl: settings.baseUrl ?? "",
+    headers: settings.headers ?? {},
+    extra: settings.extra ?? {}
+  });
+}
+function buildOptions(settings) {
+  const opts = { ...settings.extra ?? {} };
+  if (settings.apiKey) opts.apiKey = settings.apiKey;
+  if (settings.baseUrl) opts.baseURL = settings.baseUrl;
+  if (settings.headers && Object.keys(settings.headers).length > 0) opts.headers = settings.headers;
+  return opts;
+}
+async function createFactory(adapter, settings) {
+  const asModel = (m) => m;
+  const opts = buildOptions(settings);
+  switch (adapter) {
+    case "openai": {
+      const { createOpenAI } = await import("@ai-sdk/openai").catch(() => {
+        throw new Error(
+          `Provider "@ai-sdk/openai" is required for the "openai" adapter. Install it with: pnpm add @ai-sdk/openai`
+        );
+      });
+      const provider = createOpenAI(opts);
+      return (modelId) => provider.languageModel(modelId);
+    }
+    case "anthropic": {
+      const { createAnthropic } = await import("@ai-sdk/anthropic").catch(() => {
+        throw new Error(
+          `Provider "@ai-sdk/anthropic" is required for the "anthropic" adapter. Install it with: pnpm add @ai-sdk/anthropic`
+        );
+      });
+      const provider = createAnthropic(opts);
+      return (modelId) => provider.languageModel(modelId);
+    }
+    case "google": {
+      const { createGoogleGenerativeAI } = await import("@ai-sdk/google").catch(() => {
+        throw new Error(
+          `Provider "@ai-sdk/google" is required for the "google" adapter. Install it with: pnpm add @ai-sdk/google`
+        );
+      });
+      const provider = createGoogleGenerativeAI(opts);
+      return (modelId) => asModel(provider.languageModel(modelId));
+    }
+    case "openai-compatible": {
+      const { createOpenAICompatible } = await import("@ai-sdk/openai-compatible").catch(() => {
+        throw new Error(
+          `Provider "@ai-sdk/openai-compatible" is required for the "openai-compatible" adapter. Install it with: pnpm add @ai-sdk/openai-compatible`
+        );
+      });
+      const provider = createOpenAICompatible({
+        name: opts.name ?? "custom",
+        baseURL: opts.baseURL ?? "",
+        ...opts.apiKey ? { apiKey: opts.apiKey } : {},
+        ...opts.headers ? { headers: opts.headers } : {}
+      });
+      return (modelId) => provider.languageModel(modelId);
+    }
+    default:
+      throw new Error(`No factory registered for adapter: ${adapter}`);
+  }
+}
+function createResolver(directory) {
+  const factoryCache = /* @__PURE__ */ new Map();
+  return async (key) => {
+    const parsed = parseKey(key);
+    const entry = parsed ? void 0 : directory.entries?.[key];
+    const engineId = parsed?.engineId ?? entry?.engine;
+    const modelId = parsed?.modelId ?? entry?.id;
+    if (!engineId || !modelId) {
+      throw new Error(`Unknown model reference: ${key}`);
+    }
+    const engine = directory.engines[engineId];
+    if (!engine) {
+      throw new Error(`Unknown engine: ${engineId}`);
+    }
+    const settings = mergeSettings(engine.settings, entry?.settings);
+    if (engine.build) {
+      return engine.build(modelId, settings);
+    }
+    const cacheKey = settingsKey(settings, engine.adapter, engineId);
+    const cached = factoryCache.get(cacheKey);
+    if (cached) return cached(modelId);
+    const factory = await createFactory(engine.adapter, settings);
+    factoryCache.set(cacheKey, factory);
+    return factory(modelId);
+  };
+}
+
+export {
+  createResolver
+};

package/dist/chunk-7MUFEN4K.js

@@ -0,0 +1,559 @@
+import {
+  Tool
+} from "./chunk-P6YF7USR.js";
+
+// src/sub-agent/types.ts
+var DEFAULT_MAX_CONCURRENT = 6;
+var DEFAULT_MAX_SPAWN_DEPTH = 2;
+var DEFAULT_SESSION_TITLE_PREFIX = "Sub-agent";
+
+// src/sub-agent/tracker.ts
+var SubAgentTracker = class {
+  /** Active sub-agent handles by ID */
+  handles = /* @__PURE__ */ new Map();
+  /** Maximum concurrent sub-agents */
+  maxConcurrent;
+  /** Maximum nesting depth */
+  maxDepth;
+  /** Current depth in the spawn hierarchy */
+  currentDepth;
+  constructor(config) {
+    this.maxConcurrent = config?.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    this.maxDepth = config?.maxDepth ?? DEFAULT_MAX_SPAWN_DEPTH;
+    this.currentDepth = config?.currentDepth ?? 0;
+  }
+  // ==========================================================================
+  // Slot Management
+  // ==========================================================================
+  /** Number of currently active (running) sub-agents */
+  get activeCount() {
+    let count = 0;
+    for (const handle of this.handles.values()) {
+      if (handle.status.state === "running") count++;
+    }
+    return count;
+  }
+  /** Total tracked handles (including completed) */
+  get totalCount() {
+    return this.handles.size;
+  }
+  /**
+   * Check if a new sub-agent can be spawned.
+   * Returns an error message if not, undefined if OK.
+   */
+  canSpawn() {
+    if (this.currentDepth >= this.maxDepth) {
+      return `Sub-agent depth limit reached (current: ${this.currentDepth}, max: ${this.maxDepth}). Complete the task yourself instead of delegating further.`;
+    }
+    if (this.activeCount >= this.maxConcurrent) {
+      return `Maximum concurrent sub-agents reached (${this.maxConcurrent}). Wait for an existing sub-agent to complete before spawning a new one.`;
+    }
+    return void 0;
+  }
+  /** Whether the current depth allows further spawning */
+  get canNest() {
+    return this.currentDepth + 1 < this.maxDepth;
+  }
+  // ==========================================================================
+  // Handle Management
+  // ==========================================================================
+  /** Register a new sub-agent handle */
+  register(handle) {
+    this.handles.set(handle.id, handle);
+  }
+  /** Get a handle by ID */
+  get(id) {
+    return this.handles.get(id);
+  }
+  /** Update a handle's status */
+  updateStatus(id, status) {
+    const handle = this.handles.get(id);
+    if (handle) {
+      handle.status = status;
+    }
+  }
+  /** Get all handles */
+  list() {
+    return Array.from(this.handles.values());
+  }
+  /** Get all running handles */
+  running() {
+    return this.list().filter((h) => h.status.state === "running");
+  }
+  /** Get all completed handles */
+  completed() {
+    return this.list().filter((h) => h.status.state === "completed");
+  }
+  /**
+   * Cancel a running sub-agent.
+   * Signals the abort controller and updates status.
+   */
+  cancel(id) {
+    const handle = this.handles.get(id);
+    if (!handle || handle.status.state !== "running") return false;
+    handle.abort.abort();
+    handle.status = { state: "cancelled" };
+    return true;
+  }
+  /**
+   * Cancel all running sub-agents.
+   */
+  cancelAll() {
+    for (const handle of this.handles.values()) {
+      if (handle.status.state === "running") {
+        handle.abort.abort();
+        handle.status = { state: "cancelled" };
+      }
+    }
+  }
+  /**
+   * Wait for a specific sub-agent to complete.
+   * Returns the result or throws if not found.
+   */
+  async wait(id, timeoutMs) {
+    const handle = this.handles.get(id);
+    if (!handle) {
+      throw new Error(`Sub-agent not found: "${id}"`);
+    }
+    if (handle.status.state === "completed") {
+      return {
+        response: handle.status.response,
+        sessionId: handle.sessionId,
+        usage: handle.status.usage,
+        toolCalls: []
+      };
+    }
+    if (handle.status.state !== "running") {
+      throw new Error(
+        `Sub-agent "${id}" is in state "${handle.status.state}" and cannot be waited on.`
+      );
+    }
+    if (timeoutMs !== void 0 && timeoutMs > 0) {
+      const timeout = new Promise(
+        (_, reject) => setTimeout(
+          () => reject(new Error(`Timed out waiting for sub-agent "${id}" after ${timeoutMs}ms`)),
+          timeoutMs
+        )
+      );
+      return Promise.race([handle.promise, timeout]);
+    }
+    return handle.promise;
+  }
+  /**
+   * Wait for any one of the given sub-agents to complete.
+   * Returns the first result.
+   */
+  async waitAny(ids, timeoutMs) {
+    const handles = ids.map((id) => this.handles.get(id)).filter((h) => h !== void 0);
+    if (handles.length === 0) {
+      throw new Error(`No sub-agents found for IDs: ${ids.join(", ")}`);
+    }
+    for (const handle of handles) {
+      if (handle.status.state === "completed") {
+        return {
+          id: handle.id,
+          result: {
+            response: handle.status.response,
+            sessionId: handle.sessionId,
+            usage: handle.status.usage,
+            toolCalls: []
+          }
+        };
+      }
+    }
+    const races = handles.filter((h) => h.status.state === "running").map(
+      (h) => h.promise.then((result) => ({ id: h.id, result }))
+    );
+    if (races.length === 0) {
+      throw new Error("No running sub-agents to wait on.");
+    }
+    if (timeoutMs !== void 0 && timeoutMs > 0) {
+      const timeout = new Promise(
+        (resolve) => setTimeout(() => resolve({ timedOut: true }), timeoutMs)
+      );
+      return Promise.race([...races, timeout]);
+    }
+    return Promise.race(races);
+  }
+  /**
+   * Create a child tracker configuration for a nested sub-agent.
+   * Increments the depth counter.
+   */
+  childConfig() {
+    return {
+      maxConcurrent: this.maxConcurrent,
+      maxDepth: this.maxDepth,
+      currentDepth: this.currentDepth + 1
+    };
+  }
+};
+
+// src/sub-agent/tool-factories.ts
+import { z } from "zod";
+
+// src/sub-agent/results.ts
+function formatUsageLine(result) {
+  return result.usage ? `
+Tokens: ${result.usage.inputTokens} in / ${result.usage.outputTokens} out` : "";
+}
+function formatToolCallsLine(result) {
+  return result.toolCalls.length > 0 ? `
+Tool calls: ${result.toolCalls.map((tool) => tool.name).join(", ")}` : "";
+}
+function formatInvalidAgentTypeResult(agentType, validNames) {
+  return {
+    title: "Invalid agent type",
+    output: `Unknown agent type "${agentType}".
+
+Available types: ${validNames.join(", ")}`,
+    metadata: {}
+  };
+}
+function formatSpawnBlockedResult(message) {
+  return {
+    title: "Cannot spawn sub-agent",
+    output: message,
+    metadata: {}
+  };
+}
+function formatSyncSubAgentResult(profileName, result) {
+  return {
+    title: `${profileName} completed`,
+    output: `<agent_result agent="${profileName}" session="${result.sessionId}">
+` + result.response + `
+</agent_result>` + formatUsageLine(result) + formatToolCallsLine(result),
+    metadata: {
+      sessionId: result.sessionId,
+      profile: profileName,
+      toolCalls: result.toolCalls.length
+    }
+  };
+}
+function formatSyncSubAgentErrorResult(profileName, error) {
+  return {
+    title: `${profileName} failed`,
+    output: `Sub-agent "${profileName}" encountered an error:
+` + (error instanceof Error ? error.message : String(error)) + `
+
+Consider handling the task directly.`,
+    metadata: { profile: profileName, error: true }
+  };
+}
+function formatAsyncSpawnedResult(agentId, profileName, sessionId) {
+  return {
+    title: `Spawned ${profileName}`,
+    output: `Sub-agent spawned successfully.
+
+Agent ID: ${agentId}
+Type: ${profileName}
+Session: ${sessionId}
+
+Use \`wait_agent\` with this ID to collect the result when ready.`,
+    metadata: {
+      agentId,
+      profile: profileName,
+      sessionId
+    }
+  };
+}
+function formatWaitResult(agentId, result, tracker) {
+  const handle = tracker.get(agentId);
+  const profileName = handle?.name ?? "agent";
+  const stillRunning = tracker.running().filter((candidate) => candidate.id !== agentId);
+  const runningNote = stillRunning.length > 0 ? `
+
+Still running: ${stillRunning.map((candidate) => `${candidate.id} (${candidate.name})`).join(", ")}` : "";
+  return {
+    title: `${profileName} completed`,
+    output: `<agent_result agent="${profileName}" id="${agentId}" session="${result.sessionId}">
+` + result.response + `
+</agent_result>` + formatUsageLine(result) + formatToolCallsLine(result) + runningNote,
+    metadata: {
+      agentId,
+      profile: profileName,
+      sessionId: result.sessionId,
+      toolCalls: result.toolCalls.length
+    }
+  };
+}
+function formatWaitTimeoutResult(timeoutMs, runningIds) {
+  return {
+    title: "Wait timed out",
+    output: `Timed out after ${timeoutMs}ms. Still running: ${runningIds.join(", ")}.
+
+Call \`wait_agent\` again to continue waiting, or \`close_agent\` to cancel.`,
+    metadata: { timedOut: true }
+  };
+}
+function formatWaitErrorResult(error) {
+  return {
+    title: "Wait failed",
+    output: error instanceof Error ? error.message : String(error),
+    metadata: { error: true }
+  };
+}
+function formatMissingAgentsResult(ids) {
+  return {
+    title: "Agent(s) not found",
+    output: `Unknown agent IDs: ${ids.join(", ")}`,
+    metadata: {}
+  };
+}
+function formatCloseMissingAgentResult(agentId) {
+  return {
+    title: "Agent not found",
+    output: `No sub-agent with ID "${agentId}".`,
+    metadata: {}
+  };
+}
+function formatCloseAlreadyResolvedResult(agentId, state) {
+  return {
+    title: `Agent already ${state}`,
+    output: `Sub-agent "${agentId}" is already ${state}. ` + (state === "completed" ? "Use `wait_agent` to retrieve its result." : "No action taken."),
+    metadata: { state }
+  };
+}
+function formatCancelledAgentResult(agentId, profileName) {
+  return {
+    title: `Cancelled ${profileName}`,
+    output: `Sub-agent "${agentId}" (${profileName}) has been cancelled.`,
+    metadata: {
+      agentId,
+      profile: profileName
+    }
+  };
+}
+
+// src/sub-agent/execution.ts
+var agentCounter = 0;
+function generateAgentId(profileName) {
+  return `${profileName}-${++agentCounter}-${Date.now().toString(36)}`;
+}
+function toCompletedResult(result) {
+  return {
+    response: result.response,
+    sessionId: result.sessionId,
+    usage: {
+      inputTokens: result.usage?.inputTokens ?? 0,
+      outputTokens: result.usage?.outputTokens ?? 0,
+      totalTokens: result.usage?.totalTokens ?? 0
+    },
+    toolCalls: result.toolCalls
+  };
+}
+function buildChildAgent(parent, profile) {
+  const forkOptions = {};
+  if (profile.preset) {
+    forkOptions.preset = profile.preset;
+  }
+  if (profile.systemPrompt) {
+    forkOptions.systemPrompt = profile.systemPrompt;
+  }
+  if (profile.model) {
+    forkOptions.model = profile.model;
+  }
+  if (profile.maxSteps) {
+    forkOptions.maxSteps = profile.maxSteps;
+  }
+  if (profile.additionalMiddleware) {
+    forkOptions.additionalMiddleware = profile.additionalMiddleware;
+  }
+  const child = parent.fork(forkOptions);
+  if (profile.additionalTools && profile.additionalTools.length > 0) {
+    return parent.fork({
+      ...forkOptions,
+      tools: [...child.getTools(), ...profile.additionalTools]
+    });
+  }
+  return child;
+}
+async function runSyncSubAgent(child, profile, task, title, context) {
+  try {
+    const result = await child.run({
+      parentSessionId: context.sessionId,
+      message: task,
+      title,
+      abort: context.abort
+    });
+    return formatSyncSubAgentResult(profile.name, toCompletedResult(result));
+  } catch (error) {
+    return formatSyncSubAgentErrorResult(profile.name, error);
+  }
+}
+async function runAsyncSubAgent(child, profile, task, title, context, tracker) {
+  const id = generateAgentId(profile.name);
+  const sessionId = context.sessionId ? `${context.sessionId}:sub:${id}` : `sub:${id}`;
+  const abortController = new AbortController();
+  if (context.abort) {
+    context.abort.addEventListener("abort", () => abortController.abort(), {
+      once: true
+    });
+  }
+  const promise = child.run({
+    parentSessionId: context.sessionId,
+    message: task,
+    title,
+    abort: abortController.signal
+  }).then((result) => {
+    const completed = toCompletedResult(result);
+    tracker.updateStatus(id, {
+      state: "completed",
+      response: result.response,
+      usage: completed.usage
+    });
+    return completed;
+  }).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    tracker.updateStatus(id, { state: "errored", error: message });
+    throw error;
+  });
+  const handle = {
+    id,
+    name: profile.name,
+    sessionId,
+    status: { state: "running" },
+    promise,
+    abort: abortController
+  };
+  tracker.register(handle);
+  return formatAsyncSpawnedResult(id, profile.name, sessionId);
+}
+
+// src/sub-agent/tool-factories.ts
+function getProfileNames(profiles) {
+  return profiles.map((profile) => profile.name);
+}
+function findProfile(profiles, agentType) {
+  return profiles.find((profile) => profile.name === agentType);
+}
+function buildInvokeDescription(profiles, isAsync) {
+  const profileList = profiles.map((profile) => `  - "${profile.name}": ${profile.description}`).join("\n");
+  const modeNote = isAsync ? "Returns an agent ID immediately. Use `wait_agent` to collect the result." : "Blocks until the sub-agent completes and returns the result directly.";
+  return `Delegate a focused task to a specialized sub-agent.
+
+Available agent types:
+${profileList}
+
+${modeNote}
+
+Guidelines:
+- Use sub-agents for well-scoped, independent tasks
+- Provide clear, self-contained instructions \u2014 the sub-agent has a fresh context
+- Include any relevant file paths, function names, or context the sub-agent needs
+- Mention the working directory structure if known (e.g. "code is in packages/agent-core/src")
+- For parallel work, invoke multiple agents before waiting for results
+- Sub-agents will retry on errors and explore alternatives \u2014 they are resilient`;
+}
+function createInvokeAgentTool(parent, config, tracker) {
+  const isAsync = config.async ?? false;
+  const titlePrefix = config.sessionTitlePrefix ?? DEFAULT_SESSION_TITLE_PREFIX;
+  const validNames = getProfileNames(config.profiles);
+  return Tool.define("invoke_agent", () => ({
+    description: buildInvokeDescription(config.profiles, isAsync),
+    parameters: z.object({
+      agent_type: z.string().describe(
+        `The type of specialized agent to use. Must be one of: ${validNames.join(", ")}`
+      ),
+      task: z.string().describe(
+        "A detailed, self-contained description of the task. Include all context the sub-agent needs."
+      ),
+      title: z.string().optional().describe("Short title for tracking (3-5 words)")
+    }),
+    execute: async (params, ctx) => {
+      const profile = findProfile(config.profiles, params.agent_type);
+      if (!profile) {
+        return formatInvalidAgentTypeResult(params.agent_type, validNames);
+      }
+      const spawnError = tracker.canSpawn();
+      if (spawnError) {
+        return formatSpawnBlockedResult(spawnError);
+      }
+      const child = buildChildAgent(parent, profile);
+      const title = params.title ?? `${titlePrefix}: ${profile.name}`;
+      const executionContext = { sessionId: ctx.sessionID, abort: ctx.abort };
+      return isAsync ? runAsyncSubAgent(
+        child,
+        profile,
+        params.task,
+        title,
+        executionContext,
+        tracker
+      ) : runSyncSubAgent(child, profile, params.task, title, executionContext);
+    }
+  }));
+}
+function createWaitAgentTool(tracker) {
+  return Tool.define("wait_agent", {
+    description: "Wait for one or more sub-agents to complete and return their results. When multiple IDs are provided, returns whichever finishes first. Use a timeout to avoid blocking indefinitely.",
+    parameters: z.object({
+      ids: z.array(z.string()).min(1).describe("Agent IDs to wait on (from invoke_agent)"),
+      timeout_ms: z.number().optional().describe("Timeout in milliseconds (default: 60000, max: 600000)")
+    }),
+    execute: async (params) => {
+      const timeoutMs = Math.min(params.timeout_ms ?? 6e4, 6e5);
+      const missing = params.ids.filter((id) => !tracker.get(id));
+      if (missing.length > 0) {
+        return formatMissingAgentsResult(missing);
+      }
+      try {
+        if (params.ids.length === 1) {
+          const result = await tracker.wait(params.ids[0], timeoutMs);
+          return formatWaitResult(params.ids[0], result, tracker);
+        }
+        const outcome = await tracker.waitAny(params.ids, timeoutMs);
+        if ("timedOut" in outcome) {
+          const runningIds = params.ids.map((id) => tracker.get(id)).filter((handle) => handle?.status.state === "running").map((handle) => handle.id);
+          return formatWaitTimeoutResult(timeoutMs, runningIds);
+        }
+        return formatWaitResult(outcome.id, outcome.result, tracker);
+      } catch (error) {
+        return formatWaitErrorResult(error);
+      }
+    }
+  });
+}
+function createCloseAgentTool(tracker) {
+  return Tool.define("close_agent", {
+    description: "Cancel a running sub-agent. Use when the result is no longer needed or the sub-agent is taking too long.",
+    parameters: z.object({
+      id: z.string().describe("Agent ID to cancel (from invoke_agent)")
+    }),
+    execute: async (params) => {
+      const handle = tracker.get(params.id);
+      if (!handle) {
+        return formatCloseMissingAgentResult(params.id);
+      }
+      if (handle.status.state !== "running") {
+        return formatCloseAlreadyResolvedResult(params.id, handle.status.state);
+      }
+      tracker.cancel(params.id);
+      return formatCancelledAgentResult(params.id, handle.name);
+    }
+  });
+}
+
+// src/sub-agent/tools.ts
+function createSubAgentTools(parent, config) {
+  if (config.profiles.length === 0) {
+    return [];
+  }
+  const currentDepth = config.currentDepth ?? 0;
+  const maxDepth = config.maxDepth ?? DEFAULT_MAX_SPAWN_DEPTH;
+  if (currentDepth >= maxDepth) {
+    return [];
+  }
+  const tracker = new SubAgentTracker(config);
+  const tools = [createInvokeAgentTool(parent, config, tracker)];
+  if (config.async) {
+    tools.push(createWaitAgentTool(tracker), createCloseAgentTool(tracker));
+  }
+  return tools;
+}
+
+export {
+  DEFAULT_MAX_CONCURRENT,
+  DEFAULT_MAX_SPAWN_DEPTH,
+  DEFAULT_SESSION_TITLE_PREFIX,
+  SubAgentTracker,
+  createSubAgentTools
+};