@agentforge-io/core 2.3.1 → 3.0.1

package/dist/builtins/current-time.tool.d.ts

@@ -6,12 +6,15 @@ import type { AgentToolDefinition } from '../types/agent.types';
  * date?" / "what time is it in Bogotá?" answers drift to either the
  * training cutoff (months off) or the host server's UTC, neither of
  * which match the user's expectations. This tool anchors every time
- * question to the agent's configured IANA timezone.
+ * question to the right IANA timezone via a fallback chain:
  *
- * Input is optional: when no `timezone` argument is supplied we fall
- * back to `context.agent.timezone` (set by the runner from the
- * AgentDefinition), and finally to `"UTC"` so the call still succeeds
- * on agents with no tz configured.
+ *   1. The explicit `timezone` argument if the model passed one.
+ *   2. `context.agent.timezone` — set by the runner from the agent
+ *      record (per-agent override).
+ *   3. `context.tenant.timezone` — set by the host's TenantResolver,
+ *      so the workspace default covers every agent that hasn't been
+ *      individually configured.
+ *   4. `"UTC"` as a last-resort floor so the call always succeeds.
  *
  * Output is a compact JSON object — easier for the model to quote
  * specific pieces (just the weekday, just the ISO) than a natural-

package/dist/builtins/current-time.tool.js

@@ -9,12 +9,15 @@ exports.currentTimeTool = currentTimeTool;
  * date?" / "what time is it in Bogotá?" answers drift to either the
  * training cutoff (months off) or the host server's UTC, neither of
  * which match the user's expectations. This tool anchors every time
- * question to the agent's configured IANA timezone.
+ * question to the right IANA timezone via a fallback chain:
  *
- * Input is optional: when no `timezone` argument is supplied we fall
- * back to `context.agent.timezone` (set by the runner from the
- * AgentDefinition), and finally to `"UTC"` so the call still succeeds
- * on agents with no tz configured.
+ *   1. The explicit `timezone` argument if the model passed one.
+ *   2. `context.agent.timezone` — set by the runner from the agent
+ *      record (per-agent override).
+ *   3. `context.tenant.timezone` — set by the host's TenantResolver,
+ *      so the workspace default covers every agent that hasn't been
+ *      individually configured.
+ *   4. `"UTC"` as a last-resort floor so the call always succeeds.
  *
  * Output is a compact JSON object — easier for the model to quote
  * specific pieces (just the weekday, just the ISO) than a natural-
@@ -25,18 +28,27 @@ function currentTimeTool() {
     return {
         name: exports.CURRENT_TIME_TOOL_NAME,
         alwaysOn: true,
-        description: "Get the current date and time. Use this any time the user asks " +
-            'about "now", "today", "the current date", a deadline relative to ' +
-            "today, or anything else that depends on knowing the real-world " +
-            "wall-clock. The result is anchored to the agent's configured " +
-            'timezone unless the caller passes an explicit `timezone` argument.',
+        description: 'Look up the current wall-clock date and time silently, for use in ' +
+            'your own reasoning. Call this whenever an answer depends on knowing ' +
+            'the real-world moment — greetings keyed to time of day, deadlines ' +
+            'relative to "today", business-hours decisions, scheduling, or any ' +
+            'user phrasing like "now", "today", "this week". ' +
+            "The result is anchored to the agent's configured timezone (or the " +
+            'workspace default) unless the caller supplies an explicit ' +
+            '`timezone` argument. ' +
+            'IMPORTANT: do NOT recite the timestamp back to the user verbatim ' +
+            'unless they explicitly asked what time or date it is. Use the value ' +
+            'to inform your reply (e.g. choose "Good evening" vs "Good morning", ' +
+            'pick the right greeting, compute "in 3 days"); quoting the raw ' +
+            'clock reading in every message reads as robotic.',
         inputSchema: {
             type: 'object',
             properties: {
                 timezone: {
                     type: 'string',
                     description: 'Optional IANA timezone (e.g. "America/Bogota", "Europe/Madrid", ' +
-                        '"Asia/Tokyo"). Defaults to the agent\'s configured timezone.',
+                        '"Asia/Tokyo"). Defaults to the agent\'s configured timezone, ' +
+                        "then the tenant's default timezone, then UTC.",
                 },
             },
             additionalProperties: false,
@@ -45,7 +57,7 @@ function currentTimeTool() {
             const requested = typeof input.timezone === 'string' && input.timezone.trim()
                 ? input.timezone.trim()
                 : undefined;
-            const fallback = context.agent?.timezone || 'UTC';
+            const fallback = context.agent?.timezone || context.tenant?.timezone || 'UTC';
             const tz = requested ?? fallback;
             const now = new Date();
             let iso;

package/dist/index.d.ts

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

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

@@ -76,6 +76,31 @@ export interface AgentResolver {
     findByIdForTenant(id: string, tenantId: string): Promise<AgentRecord | null>;
     findById(id: string): Promise<AgentRecord | null>;
 }
+/**
+ * Tenant-level context the SDK passes to tools. The host owns tenant
+ * records; the SDK doesn't query them directly. Implement this
+ * interface in the host and register it via
+ * `AgentService.setTenantResolver(...)` so the runner can populate
+ * `ToolExecutionContext.tenant` for tools like `current_time` that
+ * need a workspace-wide default (e.g. timezone) when the agent itself
+ * has none configured.
+ *
+ * Returning `null` means "no tenant context available" — tools fall
+ * through to their own defaults (UTC for `current_time`). Returning a
+ * partial object is fine; the SDK only reads the fields tools ask for.
+ */
+export interface TenantResolver {
+    findById(tenantId: string): Promise<TenantContext | null>;
+}
+/** Minimal tenant-level context the SDK forwards to tools today. Add
+ *  fields here as new tools start consuming tenant settings; keep them
+ *  optional to preserve compatibility with hosts that don't populate
+ *  every field. */
+export interface TenantContext {
+    /** IANA timezone (e.g. `"America/Bogota"`). Used by `current_time`
+     *  as the workspace default when the agent has none. */
+    timezone?: string;
+}
 export interface AgentNotFoundError extends Error {
     status: 404;
 }
@@ -141,6 +166,23 @@ export declare class AgentService {
      *  `delegate_to_*` synthetic tools fire. Standalone agents always
      *  go straight to the runner. */
     orchestrator?: import("./orchestrator.service").OrchestratorService | undefined);
+    /** Optional host-supplied tenant resolver. When wired, every
+     *  streamMessage / sendMessage attaches `tenant: { timezone }` (and
+     *  whatever else TenantContext grows) to the ToolExecutionContext so
+     *  tools like `current_time` can fall back to the workspace default.
+     *  Left undefined for SDK consumers without a tenant model. */
+    private tenantResolver?;
+    /** Register the host's tenant resolver. Called once at module init
+     *  (after construction so we don't bloat the positional constructor
+     *  arg list for every SDK consumer). Idempotent — calling twice
+     *  overwrites the previous resolver. */
+    setTenantResolver(resolver: TenantResolver): void;
+    /** Load the tenant context (currently just timezone) for an agent
+     *  record. Returns `undefined` when the agent has no tenantId, no
+     *  resolver is wired, or the lookup throws / returns null — in every
+     *  one of those cases the tool falls back to its own defaults so a
+     *  resolver outage never breaks the turn. */
+    private loadTenantContext;
     /** Public re-export of `resolveExtraTools` keyed by agentId. The
      *  orchestrator uses this via `setExtraToolsResolver` to hydrate
      *  sub-agents' connector tools at delegation time. We synthesize a

package/dist/services/agent.service.js

@@ -64,6 +64,33 @@ class AgentService {
             return this.resolveExtraToolsForAgent(agentId, userId);
         });
     }
+    /** Register the host's tenant resolver. Called once at module init
+     *  (after construction so we don't bloat the positional constructor
+     *  arg list for every SDK consumer). Idempotent — calling twice
+     *  overwrites the previous resolver. */
+    setTenantResolver(resolver) {
+        this.tenantResolver = resolver;
+    }
+    /** Load the tenant context (currently just timezone) for an agent
+     *  record. Returns `undefined` when the agent has no tenantId, no
+     *  resolver is wired, or the lookup throws / returns null — in every
+     *  one of those cases the tool falls back to its own defaults so a
+     *  resolver outage never breaks the turn. */
+    async loadTenantContext(agent) {
+        if (!this.tenantResolver || !agent.tenantId)
+            return undefined;
+        try {
+            const ctx = await this.tenantResolver.findById(agent.tenantId);
+            if (!ctx)
+                return undefined;
+            return { timezone: ctx.timezone };
+        }
+        catch {
+            // Resolver outage shouldn't break the turn — the tool's own
+            // fallback (agent.timezone → UTC) still produces a sane answer.
+            return undefined;
+        }
+    }
     /** Public re-export of `resolveExtraTools` keyed by agentId. The
      *  orchestrator uses this via `setExtraToolsResolver` to hydrate
      *  sub-agents' connector tools at delegation time. We synthesize a
@@ -313,12 +340,14 @@ class AgentService {
         // ChatStreamController). Caller wins on name collisions so an
         // explicit override always trumps an inherited connector tool.
         const extraTools = mergeExtraTools(params.overrides?.extraTools, fromConnectors);
+        const tenant = await this.loadTenantContext(agent);
         const response = await this.runner.run(agent, messages, {
             userId: params.userId,
             conversationId: params.conversationId,
             agentId: conv.agentId,
             messageId: 'sync',
             agent: { timezone: agent.timezone },
+            ...(tenant ? { tenant } : {}),
         }, { ...(params.overrides ?? {}), extraTools });
         await this.conversations.addMessage({
             conversationId: params.conversationId,
@@ -379,6 +408,7 @@ class AgentService {
         const filter = params.overrides?.extraToolsFilter;
         const fromConnectors = filter && resolvedExtras ? filter(resolvedExtras) : resolvedExtras;
         const extraTools = mergeExtraTools(params.overrides?.extraTools, fromConnectors);
+        const tenant = await this.loadTenantContext(agent);
         // Hoisted accumulators so the post-loop persistence (after the
         // try) can see the final list. Defined here, populated inside
         // the for-await loop below.
@@ -400,6 +430,7 @@ class AgentService {
                     agentId: conv.agentId,
                     messageId: 'streaming',
                     agent: { timezone: agent.timezone },
+                    ...(tenant ? { tenant } : {}),
                 })
                 : this.runner.stream(agent, messages, {
                     userId: params.userId,
@@ -407,6 +438,7 @@ class AgentService {
                     agentId: conv.agentId,
                     messageId: 'streaming',
                     agent: { timezone: agent.timezone },
+                    ...(tenant ? { tenant } : {}),
                 }, { ...(params.overrides ?? {}), extraTools });
             // Accumulate tool_use / tool_result chunks during streaming so
             // we can persist them on the assistant message row (line ~700).

package/dist/services/orchestrator.service.js

@@ -142,6 +142,11 @@ class OrchestratorService {
             return;
         }
         this.logger.debug(`Streaming orchestrator "${agentId}" with subagents: ${agent.subAgents.join(', ')}`);
+        // Pre-resolve all sub-agents so `buildDelegationTools` sees their
+        // name/description/slug — without this, the agentsMap only has the
+        // orchestrator and the tool-name builder falls back to the UUID
+        // form, defeating the slug→name match the model relies on.
+        await Promise.all(agent.subAgents.map((id) => this.resolveAgentDynamic(id)));
         const delegationTools = this.buildDelegationTools(agent);
         const model = agent.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
         const maxTokens = agent.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
@@ -213,8 +218,14 @@ class OrchestratorService {
                 if (block.type !== 'tool_use')
                     continue;
                 const delegateTool = delegationTools.find((t) => t.name === block.name);
-                if (!delegateTool)
+                if (!delegateTool) {
+                    // The model called a tool name we didn't expose. Log loudly
+                    // so we can spot drift between the prompt's slug references
+                    // and the actual tool surface.
+                    this.logger.warn(`Orchestrator "${agent.id}" called unknown tool "${block.name}". ` +
+                        `Available tools: ${delegationTools.map((t) => t.name).join(', ')}`);
                     continue;
+                }
                 const { task } = block.input;
                 const { subAgentId } = delegateTool;
                 const subAgent = await this.resolveAgentDynamic(subAgentId);
@@ -333,6 +344,9 @@ class OrchestratorService {
     }
     async runOrchestratorLoop(orchestrator, messages, context) {
         const delegations = [];
+        // Pre-resolve subagents so buildDelegationTools sees their
+        // slug/name/description (same fix as the stream path).
+        await Promise.all((orchestrator.subAgents ?? []).map((id) => this.resolveAgentDynamic(id)));
         const delegationTools = this.buildDelegationTools(orchestrator);
         const model = orchestrator.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
         const maxTokens = orchestrator.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
@@ -439,13 +453,43 @@ class OrchestratorService {
     }
     // ─── Helpers ───────────────────────────────────────────────────────────────
     buildDelegationTools(orchestrator) {
+        // First pass: collect the slug/uuid-name candidates so we can
+        // detect collisions across the team. Anthropic requires `tool.name`
+        // to be unique within a single request; two subagents with the
+        // same slug (rare but legal at the platform layer in different
+        // tenant scopes) must not collapse into one tool.
+        const namesUsed = new Set();
         return (orchestrator.subAgents ?? []).map((subAgentId) => {
             const sub = this.agentsMap.get(subAgentId);
+            const subSlug = sub?.slug;
+            // Tool name strategy: prefer `delegate_to_<slug>` because the model
+            // already SEES `@<slug>` in its system prompt; matching it to the
+            // tool name eliminates the two-namespace gap that caused
+            // wrong-tool calls. Fall back to a sanitized UUID-derived name
+            // when no slug is available or when the slug name is already
+            // taken by an earlier subagent in this build pass.
+            const slugName = subSlug
+                ? `delegate_to_${subSlug.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 50)}`
+                : null;
+            const uuidName = `delegate_to_${subAgentId.replace(/[^a-zA-Z0-9]/g, '_')}`;
+            let name;
+            if (slugName && !namesUsed.has(slugName)) {
+                name = slugName;
+            }
+            else {
+                name = uuidName;
+            }
+            namesUsed.add(name);
+            // Description still calls out the slug explicitly — belt and
+            // suspenders against models that pattern-match on text more
+            // than on tool names.
             const description = sub
-                ? `Delegate a task to the "${sub.name}" specialist agent. ${sub.description ?? ''}`
+                ? `Delegate a task to the "${sub.name}" specialist agent` +
+                    (subSlug ? ` (mention slug: @${subSlug})` : '') +
+                    `. ${sub.description ?? ''}`
                 : `Delegate a task to subagent "${subAgentId}"`;
             return {
-                name: `delegate_to_${subAgentId.replace(/[^a-zA-Z0-9]/g, '_')}`,
+                name,
                 description,
                 subAgentId,
                 inputSchema: {

package/dist/types/agent.types.d.ts

@@ -147,6 +147,17 @@ export interface ToolExecutionContext {
     agent?: {
         timezone?: string;
     };
+    /**
+     * Tenant-level configuration the tool may consult as a fallback when
+     * the agent itself does not specify a value. `current_time` walks the
+     * chain `agent.timezone → tenant.timezone → 'UTC'` so a workspace
+     * default covers every agent that hasn't been individually configured.
+     * Populated by the host's `TenantResolver` hook on AgentService;
+     * absent when no resolver is wired (legacy SDK consumers).
+     */
+    tenant?: {
+        timezone?: string;
+    };
 }
 export type AnthropicMessage = Anthropic.MessageParam;
 export type AnthropicTool = Anthropic.Tool;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentforge-io/core",
-  "version": "2.3.1",
-  "description": "Framework-free AI runtime SDK. Owns: agent loop (pluggable LLM provider — Anthropic by default, LangChain-backed providers as drop-ins), conversations, tools, streaming, agent-job queue, SdkHooks. Identity, billing, infra (email/uploads/secrets) live in the host's modules — not here.",
+  "version": "3.0.1",
+  "description": "Framework-free AI runtime SDK. Owns: agent loop (Anthropic), conversations, tools, streaming, agent-job queue, SdkHooks. Identity, billing, infra (email/uploads/secrets) live in the host's modules — not here.",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",