@agentforge-io/core 2.0.23 → 2.1.0

package/dist/ai/index.d.ts

@@ -2,6 +2,8 @@ export { AGENT_FORGE_CONFIG, AGENT_QUEUE_NAME, CURRENT_USER, } from '../constant
 export type { AgentDefinition, AnthropicConfig, McpServerConfig, AgentForgeConfig, DatabaseConfig, RedisConfig, QueueConfig, } from '../types/config.types';
 export type { AgentResponse, AgentOverrides, StreamChunk, TokenUsage, ToolCallRecord, AgentToolDefinition, AgentJobPayload, AgentJobResult, AnthropicMessage, } from '../types/agent.types';
 export type { SdkHooks, UsageEvent, TurnCompleteEvent, ToolCallEvent, } from '../types/hooks';
+export type { ModelStrategy, ModelTier, EscalateRule, FallbackRule, TurnSignals, ModelSelection, } from '../types/model-strategy';
+export { selectModel, DEFAULT_LONG_CONTEXT_TOKENS, DEFAULT_SHORT_INPUT_TOKENS, } from '../types/model-strategy';
 export { ToolRegistryService, type Logger } from '../services/tool-registry.service';
 export { AgentRunnerService } from '../services/agent-runner.service';
 export { OrchestratorService } from '../services/orchestrator.service';

package/dist/ai/index.js

@@ -8,12 +8,16 @@
 //
 // Files still co-located physically; this is a logical seam.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InMemoryJobQueue = exports.JOB_QUEUE = exports.InMemoryPreparedStreamStore = exports.PREPARED_STREAM_STORE = exports.AgentJobWorker = exports.AgentForbiddenError = exports.AgentService = exports.ConversationNotFoundError = exports.ConversationService = exports.PreparedStreamError = exports.PreparedStreamService = exports.OrchestratorService = exports.AgentRunnerService = exports.ToolRegistryService = exports.CURRENT_USER = exports.AGENT_QUEUE_NAME = exports.AGENT_FORGE_CONFIG = void 0;
+exports.InMemoryJobQueue = exports.JOB_QUEUE = exports.InMemoryPreparedStreamStore = exports.PREPARED_STREAM_STORE = exports.AgentJobWorker = exports.AgentForbiddenError = exports.AgentService = exports.ConversationNotFoundError = exports.ConversationService = exports.PreparedStreamError = exports.PreparedStreamService = exports.OrchestratorService = exports.AgentRunnerService = exports.ToolRegistryService = exports.DEFAULT_SHORT_INPUT_TOKENS = exports.DEFAULT_LONG_CONTEXT_TOKENS = exports.selectModel = exports.CURRENT_USER = exports.AGENT_QUEUE_NAME = exports.AGENT_FORGE_CONFIG = void 0;
 // ─── Constants ─────────────────────────────────────────────────────────────
 var constants_1 = require("../constants");
 Object.defineProperty(exports, "AGENT_FORGE_CONFIG", { enumerable: true, get: function () { return constants_1.AGENT_FORGE_CONFIG; } });
 Object.defineProperty(exports, "AGENT_QUEUE_NAME", { enumerable: true, get: function () { return constants_1.AGENT_QUEUE_NAME; } });
 Object.defineProperty(exports, "CURRENT_USER", { enumerable: true, get: function () { return constants_1.CURRENT_USER; } });
+var model_strategy_1 = require("../types/model-strategy");
+Object.defineProperty(exports, "selectModel", { enumerable: true, get: function () { return model_strategy_1.selectModel; } });
+Object.defineProperty(exports, "DEFAULT_LONG_CONTEXT_TOKENS", { enumerable: true, get: function () { return model_strategy_1.DEFAULT_LONG_CONTEXT_TOKENS; } });
+Object.defineProperty(exports, "DEFAULT_SHORT_INPUT_TOKENS", { enumerable: true, get: function () { return model_strategy_1.DEFAULT_SHORT_INPUT_TOKENS; } });
 // ─── Services ──────────────────────────────────────────────────────────────
 var tool_registry_service_1 = require("../services/tool-registry.service");
 Object.defineProperty(exports, "ToolRegistryService", { enumerable: true, get: function () { return tool_registry_service_1.ToolRegistryService; } });

package/dist/factory.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAgentForge = createAgentForge;
 const in_memory_1 = require("./adapters/rate-limiter/in-memory");
@@ -22,9 +55,29 @@ function createAgentForge(opts) {
     // ─── Tool registry + runner + orchestrator ───────────────────────────────
     const toolRegistry = new tool_registry_service_1.ToolRegistryService({ logger, initialTools: tools });
     const runner = new agent_runner_service_1.AgentRunnerService(config.anthropic, toolRegistry, { logger });
+    // Bridge the host-supplied AgentResolver into the orchestrator's
+    // dynamic-lookup hook. The orchestrator only needs `AgentDefinition`,
+    // so we wrap the resolver's record-shaped result with the same
+    // `toAgentDefinition` adapter the AgentService uses internally.
+    // When no resolver is wired the orchestrator only sees the static
+    // `config.agents` map — preserving legacy behaviour.
+    const orchestratorResolver = adapters.agentResolver
+        ? async (id) => {
+            const rec = await adapters.agentResolver.findById(id);
+            if (!rec || !rec.isActive)
+                return null;
+            // `toAgentDefinition` is the internal adapter — exposing it
+            // via the agent.service module keeps it private to the SDK.
+            // We dynamically require it here to dodge a circular import
+            // between factory.ts and agent.service.ts.
+            const { toAgentDefinition } = await Promise.resolve().then(() => __importStar(require('./services/agent.service')));
+            return toAgentDefinition(rec);
+        }
+        : undefined;
     const orchestrator = new orchestrator_service_1.OrchestratorService(config.anthropic, runner, {
         agents: config.agents ?? [],
         logger,
+        resolveAgent: orchestratorResolver,
     });
     // ─── Prepared-stream store + service ─────────────────────────────────────
     const preparedStreamStore = adapters.preparedStreamStore ?? new in_memory_prepared_stream_store_1.InMemoryPreparedStreamStore();
@@ -33,7 +86,9 @@ function createAgentForge(opts) {
     const rateLimiter = adapters.rateLimiter ?? new in_memory_1.InMemoryRateLimiter();
     // ─── Conversations + agents ──────────────────────────────────────────────
     const conversations = new conversation_service_1.ConversationService(repositories.conversations, repositories.messages);
-    const agents = new agent_service_1.AgentService(config.agents ?? [], runner, conversations, adapters.agentResolver, hooks);
+    const agents = new agent_service_1.AgentService(config.agents ?? [], runner, conversations, adapters.agentResolver, hooks, undefined, // connectorRegistry — wired by Nest binding when present
+    undefined, // copywriter — same
+    orchestrator);
     // ─── Background-job worker + queue (in-memory default) ───────────────────
     const agentJobWorker = new agent_job_worker_1.AgentJobWorker(orchestrator, conversations, {
         logger,

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export { JOB_QUEUE, type JobQueue, type JobStatus, type JobState, type JobContex
 export { InMemoryJobQueue, type InMemoryJobQueueOptions, } from './adapters/job-queue/in-memory';
 export * from './services';
 export type { AgentResolver, AgentRecord, AgentResolveParams, } from './services/agent.service';
+export { toAgentDefinition } from './services/agent.service';
 export { createAgentForge, type CreateAgentForgeOptions, type AgentForgeContainer, type AgentForgeRepositories, type AgentForgeAdapters, } from './factory';

package/dist/index.js

@@ -27,7 +27,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAgentForge = exports.InMemoryJobQueue = exports.JOB_QUEUE = exports.RedisRateLimiter = exports.InMemoryRateLimiter = exports.RATE_LIMITER = exports.PREPARED_STREAM_STORE = exports.CURRENT_USER = exports.AGENT_QUEUE_NAME = exports.AGENT_FORGE_CONFIG = void 0;
+exports.createAgentForge = exports.toAgentDefinition = exports.InMemoryJobQueue = exports.JOB_QUEUE = exports.RedisRateLimiter = exports.InMemoryRateLimiter = exports.RATE_LIMITER = exports.PREPARED_STREAM_STORE = exports.CURRENT_USER = exports.AGENT_QUEUE_NAME = exports.AGENT_FORGE_CONFIG = void 0;
 // ─── Constants ──────────────────────────────────────────────────────────────
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "AGENT_FORGE_CONFIG", { enumerable: true, get: function () { return constants_1.AGENT_FORGE_CONFIG; } });
@@ -54,6 +54,12 @@ var in_memory_2 = require("./adapters/job-queue/in-memory");
 Object.defineProperty(exports, "InMemoryJobQueue", { enumerable: true, get: function () { return in_memory_2.InMemoryJobQueue; } });
 // ─── Services (framework-free) ──────────────────────────────────────────────
 __exportStar(require("./services"), exports);
+// `toAgentDefinition` is the adapter from the host's `AgentRecord` shape
+// to the SDK's runtime `AgentDefinition`. Exposed so the Nest binding
+// can bridge an `AgentResolver` into the orchestrator's dynamic-lookup
+// hook for Team flows.
+var agent_service_1 = require("./services/agent.service");
+Object.defineProperty(exports, "toAgentDefinition", { enumerable: true, get: function () { return agent_service_1.toAgentDefinition; } });
 // ─── Container factory ──────────────────────────────────────────────────────
 var factory_1 = require("./factory");
 Object.defineProperty(exports, "createAgentForge", { enumerable: true, get: function () { return factory_1.createAgentForge; } });

package/dist/services/agent-runner.service.js

@@ -7,6 +7,7 @@ exports.AgentRunnerService = void 0;
 const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
 const crypto_1 = require("crypto");
 const tool_approval_gate_1 = require("./tool-approval-gate");
+const model_strategy_1 = require("../types/model-strategy");
 const noopLogger = {
     log: () => { }, warn: () => { }, debug: () => { }, error: () => { },
 };
@@ -29,25 +30,64 @@ class AgentRunnerService {
     // ─── Run (non-streaming) ──────────────────────────────────────────────────
     async run(agent, messages, context, overrides) {
         const messageId = (0, crypto_1.randomUUID)();
-        const model = overrides?.model ?? agent.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
+        const runnerDefault = this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
+        const baseModel = overrides?.model ?? agent.model ?? runnerDefault;
         const maxTokens = overrides?.maxTokens ?? agent.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
-        const temperature = overrides?.temperature ?? agent.temperature ?? 1;
+        // Anthropic's newer models (Sonnet 4.6+, Haiku 4.5+) reject
+        // `temperature` when tools are present — they auto-tune sampling for
+        // tool use. Only forward it when the operator/caller declared one
+        // explicitly; never inject a default. Old models that required it
+        // accept its absence too (they fall back to their own internal
+        // default of 1.0).
+        const temperature = overrides?.temperature ?? agent.temperature;
         const { tools, extras } = this.buildToolList(agent, overrides);
         const systemPrompt = this.buildSystemPrompt(agent, tools, overrides);
         const toolCalls = [];
         let currentMessages = [...messages];
+        // Pre-compute the signals the model router reads. `hasTools` and
+        // `hasApprovalTool` are constant across the agentic loop (we
+        // don't add tools mid-conversation); `estimatedInputTokens`
+        // starts from a word-count heuristic and gets replaced by the
+        // real `usage.input_tokens` once we have a response.
+        const turnSignals = {
+            hasTools: !!tools && tools.length > 0,
+            hasApprovalTool: hasApprovalGatedTool(agent),
+            estimatedInputTokens: estimateInputTokens(systemPrompt, currentMessages),
+        };
         let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let finalContent = '';
         let stopReason = 'end_turn';
+        // Last model id the router chose. Surfaced on the response so
+        // callers (and the conversation/usage logs) record what
+        // actually ran, not what the agent's `model` field says.
+        let lastModel = baseModel;
         while (true) {
+            // Per-turn model selection. When overrides force a model we
+            // honour it (manual `agent.runMessage({ overrides: { model }})`
+            // beats the strategy). Otherwise the strategy decides; absent
+            // strategy → behave exactly like before this feature landed.
+            const selection = overrides?.model
+                ? { model: overrides.model, reason: 'forced' }
+                : (0, model_strategy_1.selectModel)(agent.modelStrategy, turnSignals, baseModel);
+            const model = selection.model;
+            lastModel = model;
+            if (this.logger && selection.reason !== 'default' && selection.reason !== 'forced') {
+                this.logger.debug(`[modelRouter] agent=${agent.id} ${selection.reason}=${selection.trigger} → ${model}`);
+            }
             const response = await this.client.messages.create({
                 model,
                 max_tokens: maxTokens,
-                temperature,
+                // Only include temperature when explicitly declared — newer
+                // models 400 on `temperature` when tools are present.
+                ...(typeof temperature === 'number' ? { temperature } : {}),
                 system: systemPrompt,
                 messages: currentMessages,
                 tools: tools,
             });
+            // Update the signal for the NEXT iteration of the loop — the
+            // tool-result feedback we're about to add can balloon the
+            // context past the long-context threshold.
+            turnSignals.estimatedInputTokens = response.usage.input_tokens;
             totalUsage = {
                 inputTokens: totalUsage.inputTokens + response.usage.input_tokens,
                 outputTokens: totalUsage.outputTokens + response.usage.output_tokens,
@@ -117,7 +157,7 @@ class AgentRunnerService {
             role: 'assistant',
             toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
             usage: totalUsage,
-            model,
+            model: lastModel,
             stopReason,
             createdAt: new Date(),
         };
@@ -125,18 +165,38 @@ class AgentRunnerService {
     // ─── Run (streaming) ──────────────────────────────────────────────────────
     async *stream(agent, messages, context, overrides) {
         const messageId = (0, crypto_1.randomUUID)();
-        const model = overrides?.model ?? agent.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
+        const runnerDefault = this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
+        const baseModel = overrides?.model ?? agent.model ?? runnerDefault;
         const maxTokens = overrides?.maxTokens ?? agent.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
-        const temperature = overrides?.temperature ?? agent.temperature ?? 1;
+        // Anthropic's newer models (Sonnet 4.6+, Haiku 4.5+) reject
+        // `temperature` when tools are present — they auto-tune sampling for
+        // tool use. Only forward it when the operator/caller declared one
+        // explicitly; never inject a default. Old models that required it
+        // accept its absence too (they fall back to their own internal
+        // default of 1.0).
+        const temperature = overrides?.temperature ?? agent.temperature;
         const { tools, extras } = this.buildToolList(agent, overrides);
         const systemPrompt = this.buildSystemPrompt(agent, tools, overrides);
         let currentMessages = [...messages];
         let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        // See `run()` above for the rationale on these signals.
+        const turnSignals = {
+            hasTools: !!tools && tools.length > 0,
+            hasApprovalTool: hasApprovalGatedTool(agent),
+            estimatedInputTokens: estimateInputTokens(systemPrompt, currentMessages),
+        };
         while (true) {
+            const selection = overrides?.model
+                ? { model: overrides.model, reason: 'forced' }
+                : (0, model_strategy_1.selectModel)(agent.modelStrategy, turnSignals, baseModel);
+            const model = selection.model;
+            if (this.logger && selection.reason !== 'default' && selection.reason !== 'forced') {
+                this.logger.debug(`[modelRouter] agent=${agent.id} ${selection.reason}=${selection.trigger} → ${model}`);
+            }
             const stream = this.client.messages.stream({
                 model,
                 max_tokens: maxTokens,
-                temperature,
+                ...(typeof temperature === 'number' ? { temperature } : {}),
                 system: systemPrompt,
                 messages: currentMessages,
                 tools: tools,
@@ -168,6 +228,12 @@ class AgentRunnerService {
                 }
             }
             const finalMessage = await stream.finalMessage();
+            // Refresh the input-token signal so the next iteration of the
+            // tool loop has the post-tool-result context length, not the
+            // initial estimate.
+            if (typeof finalMessage.usage?.input_tokens === 'number') {
+                turnSignals.estimatedInputTokens = finalMessage.usage.input_tokens;
+            }
             if (finalMessage.stop_reason === 'tool_use') {
                 currentMessages = [...currentMessages, { role: 'assistant', content: finalMessage.content }];
                 const toolResults = [];
@@ -311,3 +377,47 @@ class AgentRunnerService {
     }
 }
 exports.AgentRunnerService = AgentRunnerService;
+/** Cheap word-based token estimate for the first turn — Anthropic
+ *  reports real `usage.input_tokens` from the response onwards, so
+ *  this only needs to be accurate enough to fire `longContext` /
+ *  `shortInput` rules on the FIRST request before any usage is back.
+ *  Rough rule of thumb (verified against Anthropic's tokenizer on
+ *  English prose): ~0.75 tokens per whitespace-split word. */
+function estimateInputTokens(systemPrompt, messages) {
+    let words = systemPrompt.trim().split(/\s+/).filter(Boolean).length;
+    for (const m of messages) {
+        if (typeof m.content === 'string') {
+            words += m.content.trim().split(/\s+/).filter(Boolean).length;
+            continue;
+        }
+        if (Array.isArray(m.content)) {
+            for (const block of m.content) {
+                if (block &&
+                    typeof block === 'object' &&
+                    'type' in block &&
+                    block.type === 'text' &&
+                    typeof block.text === 'string') {
+                    words += block.text
+                        .trim()
+                        .split(/\s+/)
+                        .filter(Boolean).length;
+                }
+            }
+        }
+    }
+    return Math.ceil(words / 0.75);
+}
+/** True when at least one declared tool requires human approval at
+ *  runtime. Read off `agent.tools` only — `extraTools` (per-call
+ *  connector tools attached at request time) follow the host's own
+ *  per-tenant policy and aren't visible to this scope. */
+function hasApprovalGatedTool(agent) {
+    const tools = agent.tools;
+    if (!tools)
+        return false;
+    for (const t of tools) {
+        if (typeof t === 'object' && t && t.mode === 'approval')
+            return true;
+    }
+    return false;
+}

package/dist/services/agent.service.d.ts

@@ -115,6 +115,11 @@ export declare class AgentService {
      *  meta-only render on the client when unwired or when generation
      *  fails. */
     private readonly copywriter?;
+    /** When wired, agents flagged `canOrchestrate=true` route through
+     *  the orchestrator's `stream()` instead of the bare runner so the
+     *  `delegate_to_*` synthetic tools fire. Standalone agents always
+     *  go straight to the runner. */
+    private readonly orchestrator?;
     constructor(agents: AgentDefinition[], runner: AgentRunnerService, conversations: ConversationService, 
     /** When wired, agents created via the admin UI are looked up here first;
      *  the hardcoded `agents` array remains a fallback for legacy installs. */
@@ -130,7 +135,12 @@ export declare class AgentService {
      *  microcopy shown in the in-chat approval bubble. Falls back to a
      *  meta-only render on the client when unwired or when generation
      *  fails. */
-    copywriter?: ApprovalCopywriterService | undefined);
+    copywriter?: ApprovalCopywriterService | undefined, 
+    /** When wired, agents flagged `canOrchestrate=true` route through
+     *  the orchestrator's `stream()` instead of the bare runner so the
+     *  `delegate_to_*` synthetic tools fire. Standalone agents always
+     *  go straight to the runner. */
+    orchestrator?: import("./orchestrator.service").OrchestratorService | undefined);
     /**
      * Look up the human-friendly connector name + tool description for a
      * given tool slug. Powers the friendly copy in `awaiting_approval` /
@@ -227,3 +237,13 @@ export declare class AgentService {
         chunk: StreamChunk;
     }>;
 }
+/**
+ * Map a persisted `AgentRecord` to the runtime `AgentDefinition` the runner
+ * expects. The `context` column (plain-text knowledge) is prepended to the
+ * system prompt — the cheapest path before RAG is implemented.
+ *
+ * Extra host fields (`appearance`, `slug`) are passed through as opaque
+ * properties so callers like `PublicChatController` can surface them to the
+ * widget. The runner ignores anything it doesn't recognize.
+ */
+export declare function toAgentDefinition(record: AgentRecord): AgentDefinition;

package/dist/services/agent.service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentService = exports.AgentForbiddenError = void 0;
+exports.toAgentDefinition = toAgentDefinition;
 const tool_approval_gate_1 = require("./tool-approval-gate");
 class AgentForbiddenError extends Error {
     constructor(reason) {
@@ -26,7 +27,12 @@ class AgentService {
      *  microcopy shown in the in-chat approval bubble. Falls back to a
      *  meta-only render on the client when unwired or when generation
      *  fails. */
-    copywriter) {
+    copywriter, 
+    /** When wired, agents flagged `canOrchestrate=true` route through
+     *  the orchestrator's `stream()` instead of the bare runner so the
+     *  `delegate_to_*` synthetic tools fire. Standalone agents always
+     *  go straight to the runner. */
+    orchestrator) {
         this.agents = agents;
         this.runner = runner;
         this.conversations = conversations;
@@ -34,6 +40,7 @@ class AgentService {
         this.hooks = hooks;
         this.connectorRegistry = connectorRegistry;
         this.copywriter = copywriter;
+        this.orchestrator = orchestrator;
     }
     /**
      * Look up the human-friendly connector name + tool description for a
@@ -212,7 +219,12 @@ class AgentService {
         // caller's userId, which is the historical personal-agent path.
         const resolvedExtras = await this.resolveExtraTools(agent.connectorOwnerUserId ?? params.userId);
         const filter = params.overrides?.extraToolsFilter;
-        const extraTools = filter && resolvedExtras ? filter(resolvedExtras) : resolvedExtras;
+        const fromConnectors = filter && resolvedExtras ? filter(resolvedExtras) : resolvedExtras;
+        // Merge connector tools with whatever the caller passed in
+        // `overrides.extraTools` (e.g. the remote-tool wrappers from
+        // ChatStreamController). Caller wins on name collisions so an
+        // explicit override always trumps an inherited connector tool.
+        const extraTools = mergeExtraTools(params.overrides?.extraTools, fromConnectors);
         const response = await this.runner.run(agent, messages, {
             userId: params.userId,
             conversationId: params.conversationId,
@@ -278,15 +290,33 @@ class AgentService {
         // toolbelt regardless of which visitor session is streaming.
         const resolvedExtras = await this.resolveExtraTools(agent.connectorOwnerUserId ?? params.userId);
         const filter = params.overrides?.extraToolsFilter;
-        const extraTools = filter && resolvedExtras ? filter(resolvedExtras) : resolvedExtras;
+        const fromConnectors = filter && resolvedExtras ? filter(resolvedExtras) : resolvedExtras;
+        const extraTools = mergeExtraTools(params.overrides?.extraTools, fromConnectors);
         try {
-            for await (const chunk of this.runner.stream(agent, messages, {
-                userId: params.userId,
-                conversationId: params.conversationId,
-                agentId: conv.agentId,
-                messageId: 'streaming',
-                agent: { timezone: agent.timezone },
-            }, { ...(params.overrides ?? {}), extraTools })) {
+            // Team orchestrators route through OrchestratorService.stream()
+            // so the synthetic `delegate_to_*` tools the orchestrator was
+            // built with can fire. Standalone agents (or any orchestrator
+            // without an SDK that wired the service) go straight to the
+            // runner — the legacy path stays untouched for them.
+            const useOrchestrator = this.orchestrator &&
+                agent.canOrchestrate &&
+                (agent.subAgents?.length ?? 0) > 0;
+            const stream = useOrchestrator
+                ? this.orchestrator.stream(agent.id, messages, {
+                    userId: params.userId,
+                    conversationId: params.conversationId,
+                    agentId: conv.agentId,
+                    messageId: 'streaming',
+                    agent: { timezone: agent.timezone },
+                })
+                : this.runner.stream(agent, messages, {
+                    userId: params.userId,
+                    conversationId: params.conversationId,
+                    agentId: conv.agentId,
+                    messageId: 'streaming',
+                    agent: { timezone: agent.timezone },
+                }, { ...(params.overrides ?? {}), extraTools });
+            for await (const chunk of stream) {
                 if (chunk.type === 'text_delta')
                     fullContent += chunk.delta;
                 if (chunk.type === 'usage')
@@ -505,7 +535,44 @@ function toAgentDefinition(record) {
         // from the host's resolver to the SDK and every agent reads as
         // `undefined` (i.e. public).
         visibility: record.visibility,
+        // Team orchestrators need these to drive the delegation tool list
+        // the runner injects at run time. Standalone agents won't have
+        // them; the orchestrator service treats absence as "not an
+        // orchestrator" and falls through to the runner directly.
+        ...(extra.canOrchestrate !== undefined
+            ? { canOrchestrate: extra.canOrchestrate }
+            : {}),
+        ...(Array.isArray(extra.subAgents)
+            ? { subAgents: extra.subAgents }
+            : {}),
         ...(record.slug !== undefined ? { slug: record.slug } : {}),
         ...(extra.appearance !== undefined ? { appearance: extra.appearance } : {}),
     };
 }
+/**
+ * Merge two `extraTools` arrays so an explicit caller-provided list
+ * (e.g. remote-tool wrappers from a chat-stream controller) doesn't get
+ * shadowed by an `undefined` result from the connector resolver.
+ *
+ * Caller wins on name collisions — the caller passed the tool
+ * deliberately and knows the host context; an inherited connector tool
+ * with the same name is almost certainly stale or coincidental.
+ *
+ * Returns `undefined` (not `[]`) when both inputs are empty so the
+ * runner's "if (!extras?.length) skip overrides" path keeps working.
+ */
+function mergeExtraTools(caller, connectors) {
+    if (!caller?.length && !connectors?.length)
+        return undefined;
+    if (!caller?.length)
+        return connectors;
+    if (!connectors?.length)
+        return caller;
+    const callerNames = new Set(caller.map((t) => t.name));
+    const merged = [...caller];
+    for (const t of connectors) {
+        if (!callerNames.has(t.name))
+            merged.push(t);
+    }
+    return merged;
+}

package/dist/services/orchestrator.service.d.ts

@@ -1,4 +1,4 @@
-import type { AgentResponse, AnthropicMessage, SubAgentDelegation, ToolExecutionContext } from '../types/agent.types';
+import type { AgentResponse, AnthropicMessage, StreamChunk, SubAgentDelegation, ToolExecutionContext } from '../types/agent.types';
 import type { AgentDefinition, AnthropicConfig } from '../types/config.types';
 import type { AgentRunnerService } from './agent-runner.service';
 import type { Logger } from './tool-registry.service';
@@ -13,6 +13,19 @@ export declare class OrchestratorError extends Error {
 export interface OrchestratorServiceOptions {
     agents: AgentDefinition[];
     logger?: Logger;
+    /**
+     * Optional dynamic resolver. When the orchestrator references a
+     * sub-agent that wasn't in the constructor's `agents[]` (typical for
+     * Team orchestrators whose members live in the database and change
+     * per-tenant), the service calls this to load it on demand. Returning
+     * `null` is treated as "member is gone" — the orchestrator emits an
+     * apology delegation_result and continues.
+     *
+     * The framework-free SDK doesn't know about the host's persistence,
+     * so this hook is the seam where the platform wires
+     * `AgentConfigService` + `toAgentDefinition` adapter in.
+     */
+    resolveAgent?(agentId: string): Promise<AgentDefinition | null> | AgentDefinition | null;
 }
 /**
  * Multi-agent workflows. Orchestrator agents can delegate tasks to specialized
@@ -29,7 +42,18 @@ export declare class OrchestratorService {
     private readonly agentsMap;
     private readonly client;
     private readonly logger;
+    private readonly resolveAgentHook?;
     constructor(anthropicConfig: AnthropicConfig, runner: AgentRunnerService, opts: OrchestratorServiceOptions);
+    /**
+     * Lookup with dynamic-resolver fallback. Hits the static map first
+     * (built from the constructor's `agents` list — covers the bootstrap
+     * use case), then falls back to the host-supplied `resolveAgent`
+     * hook (used by Team orchestrators whose members are loaded from
+     * the database per-tenant). Resolved agents are cached in the map
+     * for the lifetime of the service to avoid re-fetching across a
+     * multi-turn conversation.
+     */
+    private resolveAgentDynamic;
     /**
      * Run an agent. Orchestrators automatically get delegation tools injected.
      * Non-orchestrator agents fall straight through to the runner.
@@ -37,6 +61,21 @@ export declare class OrchestratorService {
     run(agentId: string, messages: AnthropicMessage[], context: ToolExecutionContext): Promise<AgentResponse & {
         delegations?: SubAgentDelegation[];
     }>;
+    /**
+     * Streaming variant. Orchestrators emit `delegation_start` /
+     * `delegation_result` chunks around each sub-agent invocation; the
+     * sub-agent's own chunks are forwarded byte-by-byte with their
+     * `actingAgentId` set so the client renders the member's avatar /
+     * name on the right bubble. Non-orchestrator agents short-circuit
+     * to the runner's stream.
+     *
+     * Implementation note: we drive the same Anthropic agentic loop as
+     * `runOrchestratorLoop` (no shortcut — the orchestrator's reasoning
+     * about WHO to delegate to is still a non-streamed messages.create
+     * call). The streaming part is the SUB-AGENT'S response, which is
+     * the part the visitor actually cares about seeing in real time.
+     */
+    stream(agentId: string, messages: AnthropicMessage[], context: ToolExecutionContext): AsyncGenerator<StreamChunk>;
     private runOrchestratorLoop;
     private buildDelegationTools;
     private getAgent;