@agentforge-io/core 3.0.0 → 3.3.0

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/domain/connector-auth.d.ts

@@ -62,6 +62,18 @@ export interface ConnectorAuth {
     /** Soft toggle. UI revoke flips this to false and the runtime stops
      *  resolving the token for tool calls. */
     isActive: boolean;
+    /**
+     * Per-installation context captured at authorize-time. Carries the
+     * data the tool runtime + refresh path need that is NOT in the token
+     * itself: today only `shop` (for Shopify, where the API base is
+     * `https://{shop}.myshopify.com/admin/api/...`).
+     *
+     * Free-form JSONB so future per-installation providers (Atlassian
+     * Cloud `cloudId`, Intercom region, etc.) can stamp their own keys
+     * without another schema bump. Connectors are responsible for
+     * documenting which keys they read.
+     */
+    metadata?: Record<string, unknown>;
     createdAt: Date;
     updatedAt: Date;
 }

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/connector-registry.service.d.ts

@@ -5,7 +5,7 @@ import type { ToolRegistryService } from './tool-registry.service';
 import type { AgentToolDefinition } from '../types';
 export declare class ConnectorError extends Error {
     status: number;
-    code: 'unknown_connector' | 'not_connected' | 'not_configured' | 'invalid_state' | 'token_exchange_failed' | 'invalid_api_key' | 'wrong_auth_kind';
+    code: 'unknown_connector' | 'not_connected' | 'not_configured' | 'invalid_state' | 'token_exchange_failed' | 'invalid_api_key' | 'wrong_auth_kind' | 'missing_installation_context';
     constructor(code: ConnectorError['code'], message: string);
 }
 /**
@@ -35,6 +35,18 @@ export interface AuthorizeState {
      * persisted row and in the UI as "Connected by [Admin Name]".
      */
     tenantId?: string;
+    /**
+     * Per-installation domain captured at authorize-time and propagated
+     * to the token-exchange step. Only used by providers whose OAuth URLs
+     * are per-shop (Shopify); for the other connectors this stays
+     * undefined and `OAuth2Service.resolveEndpoints` falls back to the
+     * static URLs.
+     *
+     * Persisted on the resulting `ConnectorAuth.metadata.shop` so the
+     * connector's tool runtime + the refresh path can reconstruct the
+     * per-shop API base without round-tripping to the user.
+     */
+    shop?: string;
 }
 /**
  * Pluggable storage for the short-lived state map. Defaults to an
@@ -137,6 +149,7 @@ export declare class ConnectorRegistryService {
     get(connectorId: string): ConnectorDefinition;
     startAuthorize(connectorId: string, userId: string, redirectUri: string, opts?: {
         tenantId?: string;
+        shop?: string;
     }): Promise<{
         url: string;
     }>;
@@ -220,6 +233,7 @@ export declare class ConnectorRegistryService {
         userId: string;
         connectedByUserId?: string;
         accountLabel?: string;
+        metadata?: Record<string, unknown>;
     }): Promise<void>;
     /**
      * Encrypt tokens and compute `expiresAt`. Shared by both the

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

@@ -139,13 +139,23 @@ class ConnectorRegistryService {
             throw new ConnectorError('not_configured', `Connector "${connectorId}" is not configured — the operator must ` +
                 `set its OAuth credentials before users can connect.`);
         }
-        const { url, state, pkceVerifier } = this.deps.oauth.buildAuthorizeUrl(def.oauth, redirectUri);
+        // Per-installation providers (Shopify) require a `shop` so the
+        // service can pick the right per-shop authorize URL. Fail loud
+        // here rather than at the provider — the alternative is a generic
+        // "invalid_client" round-trip with no breadcrumb.
+        if (def.oauth.resolveEndpoints && !opts?.shop) {
+            throw new ConnectorError('missing_installation_context', `Connector "${connectorId}" requires a per-installation domain ` +
+                `(e.g. shop) in startAuthorize opts. The connector defines ` +
+                `resolveEndpoints but no shop was provided.`);
+        }
+        const { url, state, pkceVerifier } = this.deps.oauth.buildAuthorizeUrl(def.oauth, redirectUri, opts?.shop ? { shop: opts.shop } : undefined);
         await this.stateStore.set(state, {
             userId,
             connectorId,
             pkceVerifier,
             createdAt: Date.now(),
             tenantId: opts?.tenantId,
+            shop: opts?.shop,
         });
         return { url };
     }
@@ -172,7 +182,7 @@ class ConnectorRegistryService {
         }
         let tokens;
         try {
-            tokens = await this.deps.oauth.exchangeCode(def.oauth, code, redirectUri, ctx.pkceVerifier);
+            tokens = await this.deps.oauth.exchangeCode(def.oauth, code, redirectUri, ctx.pkceVerifier, ctx.shop ? { shop: ctx.shop } : undefined);
         }
         catch (e) {
             throw new ConnectorError('token_exchange_failed', e.message);
@@ -183,11 +193,16 @@ class ConnectorRegistryService {
         // user-scoped grants in the personal lane (one row per
         // `(userId, connectorId)`). Both branches share the cipher + token
         // shape via `buildAuthFields`.
+        //
+        // For per-installation providers (Shopify) we also stamp
+        // `metadata.shop` so the tool runtime + refresh path can
+        // reconstruct the per-shop API base without a round-trip.
+        const metadata = ctx.shop ? { shop: ctx.shop } : undefined;
         if (ctx.tenantId) {
-            await this.upsertAuthForTenant(ctx.tenantId, ctx.connectorId, tokens, { userId: ctx.userId });
+            await this.upsertAuthForTenant(ctx.tenantId, ctx.connectorId, tokens, { userId: ctx.userId, metadata });
         }
         else {
-            await this.upsertAuth(ctx.userId, ctx.connectorId, tokens);
+            await this.upsertAuth(ctx.userId, ctx.connectorId, tokens, { metadata });
         }
         return {
             connectorId: ctx.connectorId,
@@ -332,13 +347,14 @@ class ConnectorRegistryService {
         return tools;
     }
     // ─── Internals ───────────────────────────────────────────────────────────
-    async upsertAuth(userId, connectorId, tokens) {
+    async upsertAuth(userId, connectorId, tokens, opts) {
         const existing = await this.deps.authRepo.findByUserAndConnector(userId, connectorId);
         const fields = this.buildAuthFields(tokens);
         if (existing) {
             await this.deps.authRepo.update(existing.id, {
                 ...fields,
                 isActive: true,
+                ...(opts?.metadata ? { metadata: opts.metadata } : {}),
             });
         }
         else {
@@ -352,6 +368,7 @@ class ConnectorRegistryService {
                 // satisfies the contract.
                 accessTokenEncrypted: fields.accessTokenEncrypted,
                 isActive: true,
+                metadata: opts?.metadata,
             });
         }
     }
@@ -378,6 +395,7 @@ class ConnectorRegistryService {
                 // reflects who last attached the integration.
                 connectedByUserId,
                 ...(opts.accountLabel ? { accountLabel: opts.accountLabel } : {}),
+                ...(opts.metadata ? { metadata: opts.metadata } : {}),
             });
         }
         else {
@@ -391,6 +409,7 @@ class ConnectorRegistryService {
                 accessTokenEncrypted: fields.accessTokenEncrypted,
                 accountLabel: opts.accountLabel,
                 isActive: true,
+                metadata: opts.metadata,
             });
         }
     }

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

@@ -54,6 +54,42 @@ export interface OAuth2ProviderConfig {
      * every existing connector relies on it.
      */
     tokenAuth?: 'body' | 'basic';
+    /**
+     * Optional URL resolver for providers whose OAuth endpoints depend on
+     * per-installation context. Shopify is the canonical case: the
+     * authorize URL is `https://{shop}.myshopify.com/admin/oauth/authorize`
+     * and the token URL is `https://{shop}.myshopify.com/admin/oauth/access_token`
+     * — neither can be a static string.
+     *
+     * When set, the service calls this hook at authorize-time AND
+     * token-exchange/refresh-time, using the returned URLs INSTEAD of
+     * `authorizeUrl` / `tokenUrl`. The static fields stay required (used
+     * as the fallback when no `builderCtx` is passed) so existing call
+     * sites don't crash.
+     *
+     * The returned shape is `{ authorizeUrl, tokenUrl }` — same two fields
+     * — because Shopify (and similar providers) move both endpoints to
+     * the same per-shop domain. Returning both keeps the resolver atomic:
+     * we never get into a state where the authorize URL points at shop A
+     * and the token URL points at shop B.
+     */
+    resolveEndpoints?: (ctx: OAuthBuilderContext) => {
+        authorizeUrl: string;
+        tokenUrl: string;
+    };
+}
+/**
+ * Context handed to `OAuth2ProviderConfig.resolveEndpoints` when the
+ * provider's URLs are per-installation. Optional fields so providers
+ * can subscribe to whatever they need; today only `shop` is used (by
+ * Shopify), but we leave room for future regional providers (Atlassian
+ * Cloud, Google Workspace EU, etc.) without another minor bump.
+ */
+export interface OAuthBuilderContext {
+    /** Per-installation domain. For Shopify: `tienda.myshopify.com`. */
+    shop?: string;
+    /** Optional region hint for providers with regional endpoints. */
+    region?: string;
 }
 export interface AuthorizeUrlResult {
     url: string;
@@ -84,9 +120,19 @@ interface OAuth2ServiceDeps {
 export declare class OAuth2Service {
     private readonly fetchImpl;
     constructor(deps?: OAuth2ServiceDeps);
-    buildAuthorizeUrl(cfg: OAuth2ProviderConfig, redirectUri: string): AuthorizeUrlResult;
-    exchangeCode(cfg: OAuth2ProviderConfig, code: string, redirectUri: string, pkceVerifier?: string): Promise<TokenSet>;
-    refresh(cfg: OAuth2ProviderConfig, refreshToken: string): Promise<TokenSet>;
+    buildAuthorizeUrl(cfg: OAuth2ProviderConfig, redirectUri: string, builderCtx?: OAuthBuilderContext): AuthorizeUrlResult;
+    exchangeCode(cfg: OAuth2ProviderConfig, code: string, redirectUri: string, pkceVerifier?: string, builderCtx?: OAuthBuilderContext): Promise<TokenSet>;
+    refresh(cfg: OAuth2ProviderConfig, refreshToken: string, builderCtx?: OAuthBuilderContext): Promise<TokenSet>;
+    /**
+     * Resolve the actual (authorizeUrl, tokenUrl) pair for a given call.
+     * When the provider declares `resolveEndpoints`, the resolver is
+     * invoked with the per-call context (e.g. `{ shop }` for Shopify);
+     * otherwise we fall back to the static fields. This is the single
+     * choke point so authorize / exchange / refresh stay in sync — there
+     * is no path where authorize uses the per-shop URL but refresh
+     * accidentally hits the static one.
+     */
+    private resolveEndpoints;
     private postToken;
 }
 export {};

package/dist/services/oauth2.service.js

@@ -12,7 +12,8 @@ class OAuth2Service {
     constructor(deps = {}) {
         this.fetchImpl = deps.fetchImpl ?? fetch;
     }
-    buildAuthorizeUrl(cfg, redirectUri) {
+    buildAuthorizeUrl(cfg, redirectUri, builderCtx) {
+        const resolved = this.resolveEndpoints(cfg, builderCtx);
         const state = (0, crypto_1.randomBytes)(16).toString('hex');
         const usePkce = cfg.usePkce !== false;
         const params = {
@@ -30,12 +31,12 @@ class OAuth2Service {
             params.code_challenge = challenge;
             params.code_challenge_method = 'S256';
         }
-        const url = new URL(cfg.authorizeUrl);
+        const url = new URL(resolved.authorizeUrl);
         for (const [k, v] of Object.entries(params))
             url.searchParams.set(k, v);
         return { url: url.toString(), state, pkceVerifier };
     }
-    async exchangeCode(cfg, code, redirectUri, pkceVerifier) {
+    async exchangeCode(cfg, code, redirectUri, pkceVerifier, builderCtx) {
         const body = new URLSearchParams({
             grant_type: 'authorization_code',
             code,
@@ -51,9 +52,9 @@ class OAuth2Service {
         }
         if (pkceVerifier)
             body.set('code_verifier', pkceVerifier);
-        return this.postToken(cfg, body);
+        return this.postToken(cfg, body, builderCtx);
     }
-    async refresh(cfg, refreshToken) {
+    async refresh(cfg, refreshToken, builderCtx) {
         const body = new URLSearchParams({
             grant_type: 'refresh_token',
             refresh_token: refreshToken,
@@ -62,9 +63,25 @@ class OAuth2Service {
             body.set('client_id', cfg.clientId);
             body.set('client_secret', cfg.clientSecret);
         }
-        return this.postToken(cfg, body);
+        return this.postToken(cfg, body, builderCtx);
     }
-    async postToken(cfg, body) {
+    /**
+     * Resolve the actual (authorizeUrl, tokenUrl) pair for a given call.
+     * When the provider declares `resolveEndpoints`, the resolver is
+     * invoked with the per-call context (e.g. `{ shop }` for Shopify);
+     * otherwise we fall back to the static fields. This is the single
+     * choke point so authorize / exchange / refresh stay in sync — there
+     * is no path where authorize uses the per-shop URL but refresh
+     * accidentally hits the static one.
+     */
+    resolveEndpoints(cfg, builderCtx) {
+        if (cfg.resolveEndpoints) {
+            return cfg.resolveEndpoints(builderCtx ?? {});
+        }
+        return { authorizeUrl: cfg.authorizeUrl, tokenUrl: cfg.tokenUrl };
+    }
+    async postToken(cfg, body, builderCtx) {
+        const resolved = this.resolveEndpoints(cfg, builderCtx);
         const headers = {
             'content-type': 'application/x-www-form-urlencoded',
             accept: 'application/json',
@@ -76,14 +93,14 @@ class OAuth2Service {
             const credentials = Buffer.from(`${cfg.clientId}:${cfg.clientSecret}`).toString('base64');
             headers.authorization = `Basic ${credentials}`;
         }
-        const res = await this.fetchImpl(cfg.tokenUrl, {
+        const res = await this.fetchImpl(resolved.tokenUrl, {
             method: 'POST',
             headers,
             body: body.toString(),
         });
         if (!res.ok) {
             const text = await res.text().catch(() => '');
-            throw new Error(`OAuth2 token endpoint ${cfg.tokenUrl} returned ${res.status}: ${text}`);
+            throw new Error(`OAuth2 token endpoint ${resolved.tokenUrl} returned ${res.status}: ${text}`);
         }
         const json = (await res.json());
         const tokens = cfg.tokenExtractor
@@ -95,7 +112,7 @@ class OAuth2Service {
         // here with a descriptive error so the connector author knows their
         // extractor (or the default) missed the token.
         if (!tokens.accessToken) {
-            throw new Error(`OAuth2 token endpoint ${cfg.tokenUrl} returned a response without an access token. ` +
+            throw new Error(`OAuth2 token endpoint ${resolved.tokenUrl} returned a response without an access token. ` +
                 'If the provider uses a non-standard envelope, supply `tokenExtractor` on the ConnectorDefinition.');
         }
         return tokens;

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": "3.0.0",
-  "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 \u2014 not here.",
+  "version": "3.3.0",
+  "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",
@@ -33,4 +33,4 @@
     "tsx": "^4.19.0",
     "typescript": "^5.0.0"
   }
-}
+}