@agentforge-io/core 2.0.4 → 2.0.6

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

@@ -0,0 +1,21 @@
+import type { AgentToolDefinition } from '../types/agent.types';
+/**
+ * `current_time` — built-in tool every agent gets for free.
+ *
+ * Models can't read the system clock. Without this, "what's today's
+ * 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.
+ *
+ * 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.
+ *
+ * Output is a compact JSON object — easier for the model to quote
+ * specific pieces (just the weekday, just the ISO) than a natural-
+ * language string would be.
+ */
+export declare const CURRENT_TIME_TOOL_NAME = "current_time";
+export declare function currentTimeTool(): AgentToolDefinition;

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

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_TIME_TOOL_NAME = void 0;
+exports.currentTimeTool = currentTimeTool;
+/**
+ * `current_time` — built-in tool every agent gets for free.
+ *
+ * Models can't read the system clock. Without this, "what's today's
+ * 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.
+ *
+ * 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.
+ *
+ * Output is a compact JSON object — easier for the model to quote
+ * specific pieces (just the weekday, just the ISO) than a natural-
+ * language string would be.
+ */
+exports.CURRENT_TIME_TOOL_NAME = 'current_time';
+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.',
+        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.',
+                },
+            },
+            additionalProperties: false,
+        },
+        execute: async (input, context) => {
+            const requested = typeof input.timezone === 'string' && input.timezone.trim()
+                ? input.timezone.trim()
+                : undefined;
+            const fallback = context.agent?.timezone || 'UTC';
+            const tz = requested ?? fallback;
+            const now = new Date();
+            let iso;
+            let weekday;
+            let resolvedTz = tz;
+            try {
+                // Use Intl to format the offset in the target tz, then assemble an
+                // ISO 8601 string that includes the offset. `toISOString()` is UTC
+                // only, which would defeat the purpose.
+                iso = formatIsoInTimezone(now, tz);
+                weekday = new Intl.DateTimeFormat('en-US', {
+                    weekday: 'long',
+                    timeZone: tz,
+                }).format(now);
+            }
+            catch {
+                // Invalid IANA string — fall back to UTC rather than failing the
+                // tool call (which would surface as a confusing model error).
+                resolvedTz = 'UTC';
+                iso = now.toISOString();
+                weekday = new Intl.DateTimeFormat('en-US', { weekday: 'long' }).format(now);
+            }
+            return JSON.stringify({
+                iso,
+                timezone: resolvedTz,
+                weekday,
+                epochMs: now.getTime(),
+                ...(requested && requested !== resolvedTz
+                    ? { requestedTimezone: requested, note: 'invalid_timezone_fell_back_to_utc' }
+                    : {}),
+            });
+        },
+    };
+}
+/**
+ * Build an ISO 8601 string that reflects the local wall-clock in `tz`.
+ *
+ * `Date#toISOString()` always emits UTC ("…Z"), so we hand-compose the
+ * parts via Intl. The shape is `YYYY-MM-DDTHH:mm:ss±HH:MM`, the form the
+ * model is most likely to have seen in training data.
+ */
+function formatIsoInTimezone(date, tz) {
+    // Throws on invalid tz — surfaced as a try/catch in the caller.
+    const dtf = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    });
+    const parts = Object.fromEntries(dtf.formatToParts(date).map((p) => [p.type, p.value]));
+    const offset = formatOffset(date, tz);
+    // `hour` reports "24" at midnight on some engines — normalize.
+    const hour = parts.hour === '24' ? '00' : parts.hour;
+    return `${parts.year}-${parts.month}-${parts.day}T${hour}:${parts.minute}:${parts.second}${offset}`;
+}
+function formatOffset(date, tz) {
+    // Compute the offset by formatting the same instant in UTC vs target tz
+    // and taking the delta. Cheaper than parsing Intl's `shortOffset` token,
+    // and avoids engine-specific formatting quirks.
+    const tzParts = partsToUtcMs(date, tz);
+    const utcParts = partsToUtcMs(date, 'UTC');
+    const diffMin = Math.round((tzParts - utcParts) / 60000);
+    const sign = diffMin >= 0 ? '+' : '-';
+    const abs = Math.abs(diffMin);
+    const hh = String(Math.floor(abs / 60)).padStart(2, '0');
+    const mm = String(abs % 60).padStart(2, '0');
+    return `${sign}${hh}:${mm}`;
+}
+function partsToUtcMs(date, tz) {
+    const dtf = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    });
+    const p = Object.fromEntries(dtf.formatToParts(date).map((pp) => [pp.type, pp.value]));
+    const hour = p.hour === '24' ? '00' : p.hour;
+    return Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), Number(hour), Number(p.minute), Number(p.second));
+}

package/dist/builtins/index.d.ts

@@ -0,0 +1 @@
+export { currentTimeTool, CURRENT_TIME_TOOL_NAME } from './current-time.tool';

package/dist/builtins/index.js

@@ -0,0 +1,10 @@
+"use strict";
+// Built-in tools — always available to every agent regardless of the
+// `agent.tools[]` whitelist. The runner registers these alongside the
+// host-supplied catalog at boot time. UIs can still show them in the
+// picker (read-only) so users understand the agent can call them.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_TIME_TOOL_NAME = exports.currentTimeTool = void 0;
+var current_time_tool_1 = require("./current-time.tool");
+Object.defineProperty(exports, "currentTimeTool", { enumerable: true, get: function () { return current_time_tool_1.currentTimeTool; } });
+Object.defineProperty(exports, "CURRENT_TIME_TOOL_NAME", { enumerable: true, get: function () { return current_time_tool_1.CURRENT_TIME_TOOL_NAME; } });

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

@@ -17,6 +17,27 @@ export declare class AgentRunnerService {
     });
     run(agent: AgentDefinition, messages: AnthropicMessage[], context: ToolExecutionContext, overrides?: AgentOverrides): Promise<AgentResponse>;
     stream(agent: AgentDefinition, messages: AnthropicMessage[], context: ToolExecutionContext, overrides?: AgentOverrides): AsyncGenerator<StreamChunk>;
+    /**
+     * Compose the system prompt for a single Anthropic call:
+     *
+     *   [tool-awareness preamble]   ← only when `tools` is non-empty
+     *   ──────────────────────────
+     *   agent.systemPrompt          ← what the operator wrote
+     *   ──────────────────────────
+     *   overrides.systemPromptSuffix ← optional per-call addendum
+     *
+     * The preamble exists because operator prompts in the wild often pin
+     * the model to a narrow persona ("respond in three sentences", "stick
+     * to product Q&A") which suppresses tool use even when tools are
+     * attached and clearly relevant. The preamble doesn't override the
+     * operator — it's a short, generic reminder that listed tools are
+     * available and should be consulted when the user's question depends
+     * on real-world / current / authoritative information.
+     *
+     * It's only added when tools are present, so prompt-only agents stay
+     * exactly as the operator wrote them.
+     */
+    private buildSystemPrompt;
     /**
      * Merge `agent.tools[]` (resolved via the global registry) with any
      * per-call extras (e.g. the user's connector tools).

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

@@ -30,10 +30,8 @@ class AgentRunnerService {
         const model = overrides?.model ?? agent.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
         const maxTokens = overrides?.maxTokens ?? agent.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
         const temperature = overrides?.temperature ?? agent.temperature ?? 1;
-        const systemPrompt = overrides?.systemPromptSuffix
-            ? `${agent.systemPrompt}\n\n${overrides.systemPromptSuffix}`
-            : agent.systemPrompt;
         const { tools, extras } = this.buildToolList(agent, overrides);
+        const systemPrompt = this.buildSystemPrompt(agent, tools, overrides);
         const toolCalls = [];
         let currentMessages = [...messages];
         let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
@@ -117,10 +115,8 @@ class AgentRunnerService {
         const model = overrides?.model ?? agent.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
         const maxTokens = overrides?.maxTokens ?? agent.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
         const temperature = overrides?.temperature ?? agent.temperature ?? 1;
-        const systemPrompt = overrides?.systemPromptSuffix
-            ? `${agent.systemPrompt}\n\n${overrides.systemPromptSuffix}`
-            : agent.systemPrompt;
         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 };
         while (true) {
@@ -184,6 +180,44 @@ class AgentRunnerService {
         yield { type: 'usage', usage: totalUsage };
         yield { type: 'done', messageId };
     }
+    /**
+     * Compose the system prompt for a single Anthropic call:
+     *
+     *   [tool-awareness preamble]   ← only when `tools` is non-empty
+     *   ──────────────────────────
+     *   agent.systemPrompt          ← what the operator wrote
+     *   ──────────────────────────
+     *   overrides.systemPromptSuffix ← optional per-call addendum
+     *
+     * The preamble exists because operator prompts in the wild often pin
+     * the model to a narrow persona ("respond in three sentences", "stick
+     * to product Q&A") which suppresses tool use even when tools are
+     * attached and clearly relevant. The preamble doesn't override the
+     * operator — it's a short, generic reminder that listed tools are
+     * available and should be consulted when the user's question depends
+     * on real-world / current / authoritative information.
+     *
+     * It's only added when tools are present, so prompt-only agents stay
+     * exactly as the operator wrote them.
+     */
+    buildSystemPrompt(agent, tools, overrides) {
+        const parts = [];
+        if (tools && tools.length > 0) {
+            const names = tools.map((t) => `\`${t.name}\``).join(', ');
+            parts.push('You have the following tools available: ' +
+                names +
+                '. Use them whenever the user’s request depends on information ' +
+                'you can’t reliably produce from memory (current data, time, ' +
+                'account-specific facts, external APIs). Do not refuse to use a ' +
+                'tool because of style or persona instructions further below — ' +
+                'those control your voice, not your capabilities. When a tool is ' +
+                'clearly relevant, call it before composing the final answer.');
+        }
+        parts.push(agent.systemPrompt);
+        if (overrides?.systemPromptSuffix)
+            parts.push(overrides.systemPromptSuffix);
+        return parts.join('\n\n');
+    }
     /**
      * Merge `agent.tools[]` (resolved via the global registry) with any
      * per-call extras (e.g. the user's connector tools).
@@ -206,9 +240,10 @@ class AgentRunnerService {
      * for example. The shadowing only lasts for this call.
      */
     buildToolList(agent, overrides) {
-        const fromRegistry = agent.tools?.length
-            ? this.toolRegistry.getToolsForAgent(agent.id, agent.tools)
-            : [];
+        // Always invoke the registry — even when the agent has no whitelist —
+        // because alwaysOn tools (e.g. `current_time`) get folded in there and
+        // need to reach an agent whose `tools[]` is empty.
+        const fromRegistry = this.toolRegistry.getToolsForAgent(agent.id, agent.tools ?? []);
         const allowed = new Set(agent.tools ?? []);
         const extras = new Map();
         const extrasSchema = [];

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

@@ -41,6 +41,13 @@ export interface AgentRecord {
      * caller's userId, preserving the original behavior.
      */
     connectorOwnerUserId?: string;
+    /**
+     * IANA timezone (e.g. `"America/Bogota"`, `"Europe/Madrid"`). The
+     * built-in `current_time` tool reads this to anchor "what time is it"
+     * answers to the agent owner's locale instead of the host server's UTC.
+     * Defaults to `"UTC"` when unset.
+     */
+    timezone?: string;
 }
 /**
  * Host-supplied resolver for per-tenant agent configurations. The SDK never

package/dist/services/agent.service.js

@@ -167,6 +167,7 @@ class AgentService {
             conversationId: params.conversationId,
             agentId: conv.agentId,
             messageId: 'sync',
+            agent: { timezone: agent.timezone },
         }, { ...(params.overrides ?? {}), extraTools });
         await this.conversations.addMessage({
             conversationId: params.conversationId,
@@ -230,6 +231,7 @@ class AgentService {
             conversationId: params.conversationId,
             agentId: conv.agentId,
             messageId: 'streaming',
+            agent: { timezone: agent.timezone },
         }, { ...(params.overrides ?? {}), extraTools })) {
             if (chunk.type === 'text_delta')
                 fullContent += chunk.delta;
@@ -338,6 +340,7 @@ function toAgentDefinition(record) {
         mcpServers: record.mcpServers,
         metadata: record.metadata,
         connectorOwnerUserId: record.connectorOwnerUserId,
+        timezone: record.timezone,
         ...(record.slug !== undefined ? { slug: record.slug } : {}),
         ...(extra.appearance !== undefined ? { appearance: extra.appearance } : {}),
     };

package/dist/services/tool-registry.service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolRegistryService = void 0;
+const current_time_tool_1 = require("../builtins/current-time.tool");
 const noopLogger = {
     log: () => { },
     warn: () => { },
@@ -16,6 +17,10 @@ class ToolRegistryService {
     constructor(opts = {}) {
         this.tools = new Map();
         this.logger = opts.logger ?? noopLogger;
+        // Built-in essentials registered before host tools so a host can still
+        // override by registering the same name (rare — but the explicit Map
+        // overwrite warning makes the swap visible).
+        this.register((0, current_time_tool_1.currentTimeTool)());
         if (opts.initialTools)
             this.registerMany(opts.initialTools);
     }
@@ -39,7 +44,18 @@ class ToolRegistryService {
         return existed;
     }
     getToolsForAgent(agentId, toolNames) {
-        return toolNames
+        // Always-on tools (e.g. `current_time`) are offered to every agent
+        // regardless of the whitelist — they're runtime essentials the model
+        // needs to answer correctly. Per-agent allowlists still apply.
+        const requested = new Set(toolNames);
+        for (const t of this.tools.values()) {
+            if (!t.alwaysOn)
+                continue;
+            if (t.agents && t.agents.length > 0 && !t.agents.includes(agentId))
+                continue;
+            requested.add(t.name);
+        }
+        return Array.from(requested)
             .filter((name) => {
             const tool = this.tools.get(name);
             if (!tool) {

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

@@ -97,6 +97,14 @@ export interface AgentToolDefinition {
     /** MCP server this tool was discovered from. Set by McpClientService when
      *  wrapping a remote tool; left undefined for built-ins and connector tools. */
     mcpServerName?: string;
+    /**
+     * When true, the tool is offered to every agent regardless of whether the
+     * agent's `tools[]` whitelist mentions it. Used for runtime essentials
+     * like `current_time` that should never silently be off — the model
+     * needs them to answer correctly. UIs can still surface them in the
+     * picker as informational rows.
+     */
+    alwaysOn?: boolean;
     /** Owning tenantId for tenant-scoped tools (MCP servers registered per
      *  tenant). Used by `/tools` to filter results to the caller's tenant so
      *  the catalog doesn't leak another workspace's rows. Built-ins leave
@@ -108,6 +116,15 @@ export interface ToolExecutionContext {
     conversationId: string;
     agentId: string;
     messageId: string;
+    /**
+     * Agent-level configuration the tool may consult — e.g. `current_time`
+     * reads `timezone` to anchor results to the agent owner's locale. Set
+     * by the runner when it dispatches; tools should treat any field as
+     * optional and fall back to sensible defaults.
+     */
+    agent?: {
+        timezone?: string;
+    };
 }
 export type AnthropicMessage = Anthropic.MessageParam;
 export type AnthropicTool = Anthropic.Tool;

package/dist/types/config.types.d.ts

@@ -103,6 +103,12 @@ export interface AgentDefinition {
      * userId, preserving the original behavior.
      */
     connectorOwnerUserId?: string;
+    /**
+     * IANA timezone string (e.g. `"America/Bogota"`). The built-in
+     * `current_time` tool reads this so date/time questions resolve to the
+     * agent owner's locale instead of UTC. Defaults to `"UTC"` when unset.
+     */
+    timezone?: string;
 }
 /**
  * Configuration for an MCP server the runtime should connect to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/core",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "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",