@agentforge-io/core 2.1.1 → 2.2.0

package/dist/domain/connector-auth.d.ts

@@ -1,19 +1,46 @@
 /**
- * Per-user OAuth credentials for a connector (Google, Notion, Slack, etc.).
+ * OAuth credentials for a connector (Google, Notion, Slack, etc.).
+ *
+ * Two scopes coexist on the same row family, distinguished by whether
+ * `tenantId` is set:
+ *
+ *   • **User-scoped** (`tenantId` undefined): legacy / personal. One
+ *     row per (userId, connectorId). Used by assist agents bound to
+ *     the platform admin's identity (Prompt Assist, Onboarding
+ *     Assist, etc.) and by personal-agent setups.
+ *   • **Tenant-scoped** (`tenantId` set): workspace-owned grant. One
+ *     row per (tenantId, connectorId). Visible agents in a workspace
+ *     use this scope; any workspace admin/manager — or a platform
+ *     admin — can connect/disconnect on behalf of the workspace.
+ *     Survives admin handoffs and personnel changes.
+ *
+ * The runtime resolves which scope to read inside
+ * `ConnectorRegistry.toolsForTenant` (preferred for non-assist agents)
+ * and `toolsForUser` (fallback for assist + legacy paths). See
+ * `CONNECTOR_TENANT_AUTHS_SDD.md` in the platform repo for the full
+ * precedence story.
  *
  * `accessTokenEncrypted` and `refreshTokenEncrypted` are AES-GCM blobs —
  * exactly the same format as `af_platform_secrets`. The service layer
  * encrypts on write and decrypts on read using MASTER_KEY; the repo never
  * sees plaintext. That keeps "leak the DB row" from leaking the token.
- *
- * Scope of identity: the row is unique per (userId, connectorId). Today
- * that's the dashboard user (JWT subject). When we wire chat-session-scoped
- * connectors later, we add a separate row family with a different identity.
  */
 export interface ConnectorAuth {
     id: string;
-    /** Dashboard user (JWT sub). One row per (userId, connectorId). */
+    /** Dashboard user (JWT sub). For tenant-scoped rows this still records
+     *  who completed the OAuth dance (same value as `connectedByUserId`
+     *  most of the time), so we never lose human attribution. */
     userId: string;
+    /** Workspace this grant belongs to. `undefined` for legacy user-scoped
+     *  rows (assist agents, personal-agent path). Set for every grant
+     *  created through the tenant-aware OAuth flow. */
+    tenantId?: string;
+    /** Audit field — the user who clicked Connect for a tenant-scoped
+     *  grant. Distinct from `userId` because future migrations may null
+     *  out `userId` on tenant rows once the legacy path is fully retired;
+     *  we keep this column dedicated to the human-attribution use case
+     *  ("Connected by [Admin Name]" in the UI). */
+    connectedByUserId?: string;
     /** Stable connector id from the registry (e.g. "google", "notion"). */
     connectorId: string;
     /** Account label shown in the UI — e.g. "alice@acme.com". Pulled from
@@ -38,5 +65,17 @@ export interface ConnectorAuth {
     createdAt: Date;
     updatedAt: Date;
 }
-export type NewConnectorAuth = Pick<ConnectorAuth, 'id' | 'userId' | 'connectorId' | 'accessTokenEncrypted'> & Partial<Omit<ConnectorAuth, 'id' | 'userId' | 'connectorId' | 'accessTokenEncrypted' | 'createdAt' | 'updatedAt'>>;
-export type ConnectorAuthPatch = Partial<Omit<ConnectorAuth, 'id' | 'userId' | 'connectorId' | 'createdAt' | 'updatedAt'>>;
+export type NewConnectorAuth = Pick<ConnectorAuth, 'id' | 'userId' | 'connectorId' | 'accessTokenEncrypted'> & Partial<Omit<ConnectorAuth, 'id' | 'userId' | 'connectorId' | 'accessTokenEncrypted' | 'createdAt' | 'updatedAt'>> & {
+    /** Optional at create time — set for tenant-scoped grants. */
+    tenantId?: string;
+    /** Optional audit value — typically equal to `userId` for newly
+     *  created tenant-scoped rows. */
+    connectedByUserId?: string;
+};
+export type ConnectorAuthPatch = Partial<Omit<ConnectorAuth, 'id' | 'userId' | 'connectorId' | 'createdAt' | 'updatedAt'>> & {
+    /** Allowed in a patch so an operator UI can move a legacy
+     *  user-scoped grant into a workspace ("share with this workspace")
+     *  without re-doing the OAuth dance. */
+    tenantId?: string | null;
+    connectedByUserId?: string | null;
+};

package/dist/repositories/index.d.ts

@@ -77,11 +77,22 @@ export interface McpServerRepository {
 }
 export interface ConnectorAuthRepository {
     create(record: NewConnectorAuth): Promise<ConnectorAuth>;
-    /** Hot path — every tool call resolves the user's token here. */
+    /** Hot path for legacy user-scoped grants — assist agents resolve
+     *  their tokens here. Returns only rows where `tenantId IS NULL`. */
     findByUserAndConnector(userId: string, connectorId: string): Promise<ConnectorAuth | null>;
-    /** All connectors a user has authorized — for the Directory UI. */
+    /** All connectors a user has authorized for personal use. Returns
+     *  only rows where `tenantId IS NULL`. */
     listForUser(userId: string): Promise<ConnectorAuth[]>;
+    /** Hot path for workspace-scoped grants — the public chat / agent
+     *  playground resolves the workspace's tokens here. Returns only
+     *  rows where `tenantId = <tenantId>`. */
+    findByTenantAndConnector(tenantId: string, connectorId: string): Promise<ConnectorAuth | null>;
+    /** All connectors a workspace has authorized — for the
+     *  workspace-scoped Connectors page. Returns only rows where
+     *  `tenantId = <tenantId>`. */
+    listForTenant(tenantId: string): Promise<ConnectorAuth[]>;
     update(id: string, patch: ConnectorAuthPatch): Promise<void>;
-    /** Hard delete on revoke. The user can re-auth fresh if they want back in. */
+    /** Hard delete on revoke. The user / workspace can re-auth fresh
+     *  if they want back in. */
     delete(id: string): Promise<void>;
 }

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

@@ -1,5 +1,5 @@
 import type { AgentDefinition, McpServerConfig } from '../types/config.types';
-import type { AgentResponse, AgentOverrides, StreamChunk } from '../types/agent.types';
+import type { AgentResponse, AgentOverrides, AgentToolDefinition, StreamChunk } from '../types/agent.types';
 import type { SdkHooks } from '../types/hooks';
 import type { AgentRunnerService } from './agent-runner.service';
 import type { ConversationService } from './conversation.service';
@@ -141,6 +141,15 @@ export declare class AgentService {
      *  `delegate_to_*` synthetic tools fire. Standalone agents always
      *  go straight to the runner. */
     orchestrator?: import("./orchestrator.service").OrchestratorService | 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
+     *  minimal `AgentRecord` from the dynamic resolver — the
+     *  `resolveExtraTools` branches need `tenantId`, `slug`, and the
+     *  legacy `connectorOwnerUserId` shim, all of which the resolver
+     *  carries on the record. Standalone (non-resolver) deployments
+     *  fall through to undefined. */
+    resolveExtraToolsForAgent(agentId: string, callerUserId: string): Promise<AgentToolDefinition[] | undefined>;
     /**
      * Look up the human-friendly connector name + tool description for a
      * given tool slug. Powers the friendly copy in `awaiting_approval` /
@@ -155,10 +164,31 @@ export declare class AgentService {
      */
     private describeTool;
     /**
-     * Fetch the connector tools the user has authorized, swallowing failures.
-     * The agent loop must keep working even if a connector's refresh token is
-     * dead — the toolbelt just shrinks. Specific tools may still surface their
+     * Fetch the connector toolbelt for an agent + caller pair. The agent
+     * loop must keep working even if a connector's refresh token is dead
+     * — the toolbelt just shrinks. Specific tools may still surface their
      * own auth errors when actually invoked.
+     *
+     * Precedence (highest priority first):
+     *
+     *   1. **Tenant-scoped grants** — when the agent has a `tenantId`
+     *      AND isn't an assist agent. This is the canonical path for
+     *      visible workspace agents post-refactor; the workspace owns
+     *      the integrations and any admin can manage them.
+     *   2. **`agent.connectorOwnerUserId` shim** — when the host's
+     *      identity adapter populated it (today: `tenant.ownerUserId`).
+     *      Kept so existing prod agents keep working between deploy
+     *      and full backfill / UI cutover. Will be removed after 1-2
+     *      stable releases.
+     *   3. **Caller `userId`** — the assist-agent path. Prompt Assist,
+     *      Onboarding Assist, etc. run as the platform admin; their
+     *      tools come from the admin's personal authorizations.
+     *
+     * Assist agents are detected by slug prefix `system-`. They live
+     * inside the platform admin's tenant and would otherwise match
+     * branch #1, which would silently strip their toolbelt (the platform
+     * admin's tenant has no tenant-scoped connector grants — those live
+     * in actual customer tenants).
      */
     private resolveExtraTools;
     private dispatchUsage;

package/dist/services/agent.service.js

@@ -3,6 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentService = exports.AgentForbiddenError = void 0;
 exports.toAgentDefinition = toAgentDefinition;
 const tool_approval_gate_1 = require("./tool-approval-gate");
+/**
+ * Slug prefix that marks an agent as a platform-internal assist agent
+ * (Prompt Assist, Agent Assist, Skill Assist, Onboarding Assist, etc).
+ * These agents live inside the platform admin's tenant and resolve
+ * their connector toolbelt against the admin's PERSONAL authorizations,
+ * not the tenant's workspace grants — see the precedence in
+ * `resolveExtraTools` for why this matters.
+ */
+const ASSIST_AGENT_SLUG_PREFIX = 'system-';
+function isAssistAgent(agent) {
+    return !!agent.slug && agent.slug.startsWith(ASSIST_AGENT_SLUG_PREFIX);
+}
 class AgentForbiddenError extends Error {
     constructor(reason) {
         super(`Usage limit exceeded: ${reason}`);
@@ -41,6 +53,37 @@ class AgentService {
         this.connectorRegistry = connectorRegistry;
         this.copywriter = copywriter;
         this.orchestrator = orchestrator;
+        // Wire the orchestrator's extraTools hook so when an agent reached
+        // via a delegate_to_* call falls through to the runner, it gets
+        // the same connector toolset it would have on a direct call.
+        // Without this, sub-agents lose their Gmail/ClickUp/MCP tools the
+        // moment they're invoked through an orchestrator — the symptom is
+        // "el agente dice que no tiene la herramienta de ClickUp" while
+        // calling that same agent directly works fine.
+        this.orchestrator?.setExtraToolsResolver(async (agentId, userId) => {
+            return this.resolveExtraToolsForAgent(agentId, userId);
+        });
+    }
+    /** 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
+     *  minimal `AgentRecord` from the dynamic resolver — the
+     *  `resolveExtraTools` branches need `tenantId`, `slug`, and the
+     *  legacy `connectorOwnerUserId` shim, all of which the resolver
+     *  carries on the record. Standalone (non-resolver) deployments
+     *  fall through to undefined. */
+    async resolveExtraToolsForAgent(agentId, callerUserId) {
+        if (!this.resolver)
+            return undefined;
+        try {
+            const rec = await this.resolver.findById(agentId);
+            if (!rec)
+                return undefined;
+            return await this.resolveExtraTools(rec, callerUserId);
+        }
+        catch {
+            return undefined;
+        }
     }
     /**
      * Look up the human-friendly connector name + tool description for a
@@ -75,16 +118,63 @@ class AgentService {
         return undefined;
     }
     /**
-     * Fetch the connector tools the user has authorized, swallowing failures.
-     * The agent loop must keep working even if a connector's refresh token is
-     * dead — the toolbelt just shrinks. Specific tools may still surface their
+     * Fetch the connector toolbelt for an agent + caller pair. The agent
+     * loop must keep working even if a connector's refresh token is dead
+     * — the toolbelt just shrinks. Specific tools may still surface their
      * own auth errors when actually invoked.
+     *
+     * Precedence (highest priority first):
+     *
+     *   1. **Tenant-scoped grants** — when the agent has a `tenantId`
+     *      AND isn't an assist agent. This is the canonical path for
+     *      visible workspace agents post-refactor; the workspace owns
+     *      the integrations and any admin can manage them.
+     *   2. **`agent.connectorOwnerUserId` shim** — when the host's
+     *      identity adapter populated it (today: `tenant.ownerUserId`).
+     *      Kept so existing prod agents keep working between deploy
+     *      and full backfill / UI cutover. Will be removed after 1-2
+     *      stable releases.
+     *   3. **Caller `userId`** — the assist-agent path. Prompt Assist,
+     *      Onboarding Assist, etc. run as the platform admin; their
+     *      tools come from the admin's personal authorizations.
+     *
+     * Assist agents are detected by slug prefix `system-`. They live
+     * inside the platform admin's tenant and would otherwise match
+     * branch #1, which would silently strip their toolbelt (the platform
+     * admin's tenant has no tenant-scoped connector grants — those live
+     * in actual customer tenants).
      */
-    async resolveExtraTools(userId) {
+    async resolveExtraTools(agent, callerUserId) {
         if (!this.connectorRegistry)
             return undefined;
+        // Branch 1: tenant-scoped grants for non-assist agents.
+        if (agent.tenantId && !isAssistAgent(agent)) {
+            try {
+                const tools = await this.connectorRegistry.toolsForTenant(agent.tenantId);
+                if (tools.length)
+                    return tools;
+            }
+            catch {
+                // Fall through to the shim — a stale connector grant
+                // shouldn't strand the agent if the legacy path still
+                // resolves something useful.
+            }
+        }
+        // Branch 2: legacy connectorOwnerUserId shim. Kept for back-compat
+        // with hosts whose identity adapter still populates it.
+        if (agent.connectorOwnerUserId) {
+            try {
+                const tools = await this.connectorRegistry.toolsForUser(agent.connectorOwnerUserId);
+                if (tools.length)
+                    return tools;
+            }
+            catch {
+                // Try the caller next.
+            }
+        }
+        // Branch 3: caller userId (assist agents + personal flows).
         try {
-            const tools = await this.connectorRegistry.toolsForUser(userId);
+            const tools = await this.connectorRegistry.toolsForUser(callerUserId);
             return tools.length ? tools : undefined;
         }
         catch {
@@ -213,11 +303,9 @@ class AgentService {
             role: 'user',
             content: params.content,
         });
-        // Connector tools follow `agent.connectorOwnerUserId` when the
-        // resolved agent declares one (e.g. a public-chat agent reusing the
-        // owner's Gmail authorization); otherwise they fall back to the
-        // caller's userId, which is the historical personal-agent path.
-        const resolvedExtras = await this.resolveExtraTools(agent.connectorOwnerUserId ?? params.userId);
+        // Connector tools follow the agent → tenant → owner → caller
+        // precedence (see resolveExtraTools).
+        const resolvedExtras = await this.resolveExtraTools(agent, params.userId);
         const filter = params.overrides?.extraToolsFilter;
         const fromConnectors = filter && resolvedExtras ? filter(resolvedExtras) : resolvedExtras;
         // Merge connector tools with whatever the caller passed in
@@ -285,10 +373,9 @@ class AgentService {
         });
         let fullContent = '';
         let finalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-        // Same precedence as sendMessage — agent.connectorOwnerUserId takes
-        // priority so a public-chat agent always uses the owner's connector
-        // toolbelt regardless of which visitor session is streaming.
-        const resolvedExtras = await this.resolveExtraTools(agent.connectorOwnerUserId ?? params.userId);
+        // Same precedence as sendMessage — see resolveExtraTools for the
+        // tenant → owner → caller order.
+        const resolvedExtras = await this.resolveExtraTools(agent, params.userId);
         const filter = params.overrides?.extraToolsFilter;
         const fromConnectors = filter && resolvedExtras ? filter(resolvedExtras) : resolvedExtras;
         const extraTools = mergeExtraTools(params.overrides?.extraTools, fromConnectors);

package/dist/services/connector-registry.service.d.ts

@@ -1,6 +1,6 @@
 import type { ConnectorDefinition } from '../domain';
 import type { ConnectorAuthRepository } from '../repositories';
-import type { OAuth2Service } from './oauth2.service';
+import type { OAuth2Service, TokenSet } from './oauth2.service';
 import type { ToolRegistryService } from './tool-registry.service';
 import type { AgentToolDefinition } from '../types';
 export declare class ConnectorError extends Error {
@@ -27,6 +27,14 @@ export interface AuthorizeState {
     connectorId: string;
     pkceVerifier?: string;
     createdAt: number;
+    /**
+     * When set, the OAuth callback writes a tenant-scoped grant
+     * (`af_connector_auths.tenant_id = <tenantId>`) instead of the
+     * legacy user-scoped row. The `userId` field still records WHO
+     * clicked Connect — surfaced as `connected_by_user_id` in the
+     * persisted row and in the UI as "Connected by [Admin Name]".
+     */
+    tenantId?: string;
 }
 /**
  * Pluggable storage for the short-lived state map. Defaults to an
@@ -127,7 +135,9 @@ export declare class ConnectorRegistryService {
     isConfigured(connectorId: string): boolean;
     list(): ConnectorDefinition[];
     get(connectorId: string): ConnectorDefinition;
-    startAuthorize(connectorId: string, userId: string, redirectUri: string): Promise<{
+    startAuthorize(connectorId: string, userId: string, redirectUri: string, opts?: {
+        tenantId?: string;
+    }): Promise<{
         url: string;
     }>;
     /**
@@ -140,6 +150,7 @@ export declare class ConnectorRegistryService {
     completeAuthorize(state: string, code: string, redirectUri: string): Promise<{
         connectorId: string;
         userId: string;
+        tenantId?: string;
     }>;
     /**
      * Persist a user-pasted API key as the connector credential for `userId`.
@@ -180,7 +191,44 @@ export declare class ConnectorRegistryService {
      * cached token is close to expiry.
      */
     toolsForUser(userId: string): Promise<AgentToolDefinition[]>;
+    /**
+     * Workspace-scoped equivalent of `toolsForUser`. Returns the toolbelt
+     * for every connector the WORKSPACE has authorized, regardless of
+     * which admin clicked Connect. This is the path the public chat
+     * widget and the agent playground take — they don't know which
+     * human is on the other end, but they DO know the agent's tenant.
+     *
+     * Tokens still refresh lazily via `getAccessToken`; the only thing
+     * that changes vs. `toolsForUser` is the row source (tenant-scoped
+     * grants instead of user-scoped).
+     */
+    toolsForTenant(tenantId: string): Promise<AgentToolDefinition[]>;
+    private synthesizeTools;
     private upsertAuth;
+    /**
+     * Tenant-scoped upsert. Same shape as `upsertAuth` but writes a
+     * row tagged with `tenantId` + `connectedByUserId`, hitting the
+     * tenant uniqueness lane on `(tenantId, connectorId)`.
+     *
+     * `connectedByUserId` is the audit-grade record of which human
+     * clicked Connect for the workspace; the UI surfaces it as
+     * "Connected by [Admin Name]" so other admins know who attached
+     * each integration. We default it to `userId` if the caller didn't
+     * pass one — they're the same thing in almost every case.
+     */
+    upsertAuthForTenant(tenantId: string, connectorId: string, tokens: TokenSet, opts: {
+        userId: string;
+        connectedByUserId?: string;
+        accountLabel?: string;
+    }): Promise<void>;
+    /**
+     * Encrypt tokens and compute `expiresAt`. Shared by both the
+     * user-scoped and tenant-scoped upsert paths. Pulled into a helper
+     * so a Google quirk ("doesn't return refresh_token on re-consent")
+     * has a single owner — both paths handle the missing-refresh-token
+     * case the same way.
+     */
+    private buildAuthFields;
     private getAccessToken;
 }
 export {};

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

@@ -125,7 +125,7 @@ class ConnectorRegistryService {
         return def;
     }
     // ─── OAuth flow ──────────────────────────────────────────────────────────
-    async startAuthorize(connectorId, userId, redirectUri) {
+    async startAuthorize(connectorId, userId, redirectUri, opts) {
         const def = this.get(connectorId);
         if (!def.oauth) {
             // API-key connectors don't run an OAuth dance. The controller is
@@ -145,6 +145,7 @@ class ConnectorRegistryService {
             connectorId,
             pkceVerifier,
             createdAt: Date.now(),
+            tenantId: opts?.tenantId,
         });
         return { url };
     }
@@ -176,8 +177,23 @@ class ConnectorRegistryService {
         catch (e) {
             throw new ConnectorError('token_exchange_failed', e.message);
         }
-        await this.upsertAuth(ctx.userId, ctx.connectorId, tokens);
-        return { connectorId: ctx.connectorId, userId: ctx.userId };
+        // Choose the persistence scope based on what the authorize step
+        // stashed in the state cookie. Tenant-scoped grants land in the
+        // workspace lane (one row per `(tenantId, connectorId)`), legacy
+        // user-scoped grants in the personal lane (one row per
+        // `(userId, connectorId)`). Both branches share the cipher + token
+        // shape via `buildAuthFields`.
+        if (ctx.tenantId) {
+            await this.upsertAuthForTenant(ctx.tenantId, ctx.connectorId, tokens, { userId: ctx.userId });
+        }
+        else {
+            await this.upsertAuth(ctx.userId, ctx.connectorId, tokens);
+        }
+        return {
+            connectorId: ctx.connectorId,
+            userId: ctx.userId,
+            tenantId: ctx.tenantId,
+        };
     }
     // ─── API-key flow ────────────────────────────────────────────────────────
     /**
@@ -269,21 +285,43 @@ class ConnectorRegistryService {
      */
     async toolsForUser(userId) {
         const authed = await this.deps.authRepo.listForUser(userId);
+        return this.synthesizeTools(authed, userId);
+    }
+    /**
+     * Workspace-scoped equivalent of `toolsForUser`. Returns the toolbelt
+     * for every connector the WORKSPACE has authorized, regardless of
+     * which admin clicked Connect. This is the path the public chat
+     * widget and the agent playground take — they don't know which
+     * human is on the other end, but they DO know the agent's tenant.
+     *
+     * Tokens still refresh lazily via `getAccessToken`; the only thing
+     * that changes vs. `toolsForUser` is the row source (tenant-scoped
+     * grants instead of user-scoped).
+     */
+    async toolsForTenant(tenantId) {
+        const authed = await this.deps.authRepo.listForTenant(tenantId);
+        // Use the tenantId in the ConnectorToolContext slot reserved for
+        // "the human" — keeps the existing context shape but lets
+        // downstream tools see the workspace identity. Tools that don't
+        // care (most) just ignore it.
+        return this.synthesizeTools(authed, `tenant:${tenantId}`);
+    }
+    synthesizeTools(authed, contextUserId) {
         const tools = [];
         for (const a of authed) {
             if (!a.isActive)
                 continue;
             // Skip connectors whose creds were yanked from the secrets vault —
             // we'd 401 inside the refresh step anyway, and the agent gets a
-            // useless tool. The auth row is left intact so the user gets their
-            // toolbelt back the moment the operator re-supplies creds.
+            // useless tool. The auth row is left intact so the user gets
+            // their toolbelt back the moment the operator re-supplies creds.
             if (!this.configured.has(a.connectorId))
                 continue;
             const def = this.defs.get(a.connectorId);
             if (!def)
                 continue;
             const ctx = {
-                userId,
+                userId: contextUserId,
                 connectorId: a.connectorId,
                 getAccessToken: () => this.getAccessToken(a),
             };
@@ -296,21 +334,10 @@ class ConnectorRegistryService {
     // ─── Internals ───────────────────────────────────────────────────────────
     async upsertAuth(userId, connectorId, tokens) {
         const existing = await this.deps.authRepo.findByUserAndConnector(userId, connectorId);
-        const expiresAt = tokens.expiresIn
-            ? new Date(Date.now() + tokens.expiresIn * 1000)
-            : undefined;
-        const accessTokenEncrypted = this.deps.cipher.encrypt(tokens.accessToken);
-        const refreshTokenEncrypted = tokens.refreshToken
-            ? this.deps.cipher.encrypt(tokens.refreshToken)
-            : undefined;
+        const fields = this.buildAuthFields(tokens);
         if (existing) {
             await this.deps.authRepo.update(existing.id, {
-                accessTokenEncrypted,
-                // Some providers (Google) don't return a refresh_token on
-                // re-consent — keep the old one in that case.
-                ...(refreshTokenEncrypted ? { refreshTokenEncrypted } : {}),
-                expiresAt,
-                scope: tokens.scope,
+                ...fields,
                 isActive: true,
             });
         }
@@ -319,14 +346,79 @@ class ConnectorRegistryService {
                 id: (0, crypto_1.randomUUID)(),
                 userId,
                 connectorId,
-                accessTokenEncrypted,
-                refreshTokenEncrypted,
-                expiresAt,
-                scope: tokens.scope,
+                ...fields,
+                // create() requires accessTokenEncrypted as non-optional in
+                // the type — buildAuthFields always sets it, so the spread
+                // satisfies the contract.
+                accessTokenEncrypted: fields.accessTokenEncrypted,
                 isActive: true,
             });
         }
     }
+    /**
+     * Tenant-scoped upsert. Same shape as `upsertAuth` but writes a
+     * row tagged with `tenantId` + `connectedByUserId`, hitting the
+     * tenant uniqueness lane on `(tenantId, connectorId)`.
+     *
+     * `connectedByUserId` is the audit-grade record of which human
+     * clicked Connect for the workspace; the UI surfaces it as
+     * "Connected by [Admin Name]" so other admins know who attached
+     * each integration. We default it to `userId` if the caller didn't
+     * pass one — they're the same thing in almost every case.
+     */
+    async upsertAuthForTenant(tenantId, connectorId, tokens, opts) {
+        const existing = await this.deps.authRepo.findByTenantAndConnector(tenantId, connectorId);
+        const fields = this.buildAuthFields(tokens);
+        const connectedByUserId = opts.connectedByUserId ?? opts.userId;
+        if (existing) {
+            await this.deps.authRepo.update(existing.id, {
+                ...fields,
+                isActive: true,
+                // Refresh the audit field on re-consent so "Connected by"
+                // reflects who last attached the integration.
+                connectedByUserId,
+                ...(opts.accountLabel ? { accountLabel: opts.accountLabel } : {}),
+            });
+        }
+        else {
+            await this.deps.authRepo.create({
+                id: (0, crypto_1.randomUUID)(),
+                userId: opts.userId,
+                tenantId,
+                connectedByUserId,
+                connectorId,
+                ...fields,
+                accessTokenEncrypted: fields.accessTokenEncrypted,
+                accountLabel: opts.accountLabel,
+                isActive: true,
+            });
+        }
+    }
+    /**
+     * Encrypt tokens and compute `expiresAt`. Shared by both the
+     * user-scoped and tenant-scoped upsert paths. Pulled into a helper
+     * so a Google quirk ("doesn't return refresh_token on re-consent")
+     * has a single owner — both paths handle the missing-refresh-token
+     * case the same way.
+     */
+    buildAuthFields(tokens) {
+        const expiresAt = tokens.expiresIn
+            ? new Date(Date.now() + tokens.expiresIn * 1000)
+            : undefined;
+        const accessTokenEncrypted = this.deps.cipher.encrypt(tokens.accessToken);
+        const refreshTokenEncrypted = tokens.refreshToken
+            ? this.deps.cipher.encrypt(tokens.refreshToken)
+            : undefined;
+        return {
+            accessTokenEncrypted,
+            // Some providers (Google) don't return a refresh_token on
+            // re-consent — keep the old one in that case by leaving the
+            // field undefined so update() doesn't null it out.
+            ...(refreshTokenEncrypted ? { refreshTokenEncrypted } : {}),
+            expiresAt,
+            scope: tokens.scope,
+        };
+    }
     async getAccessToken(a) {
         const skewMs = this.refreshSkewSeconds * 1000;
         const stillValid = !a.expiresAt || a.expiresAt.getTime() - Date.now() > skewMs;

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

@@ -1,4 +1,4 @@
-import type { AgentResponse, AnthropicMessage, StreamChunk, SubAgentDelegation, ToolExecutionContext } from '../types/agent.types';
+import type { AgentResponse, AgentToolDefinition, 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';
@@ -26,6 +26,23 @@ export interface OrchestratorServiceOptions {
      * `AgentConfigService` + `toAgentDefinition` adapter in.
      */
     resolveAgent?(agentId: string): Promise<AgentDefinition | null> | AgentDefinition | null;
+    /**
+     * Resolve the connector-derived `extraTools` for a sub-agent given
+     * the caller's userId. The orchestrator forwards these to the inner
+     * runner / recursive stream so connector tools (Gmail, ClickUp,
+     * MCP servers, etc.) work the same when an agent is reached via a
+     * delegation as when it is reached directly.
+     *
+     * Without this hook, a sub-agent invoked through an orchestrator
+     * would lose every connector tool it normally has — same bug a
+     * non-orchestrator agent would hit if its host forgot to pass
+     * `extraTools` into `runner.stream`.
+     *
+     * Returning `undefined` is fine (treated as "no extra tools"); the
+     * orchestrator still works, but the sub-agent runs with the static
+     * tool list only.
+     */
+    resolveExtraTools?(agentId: string, userId: string): Promise<AgentToolDefinition[] | undefined> | AgentToolDefinition[] | undefined;
 }
 /**
  * Multi-agent workflows. Orchestrator agents can delegate tasks to specialized
@@ -43,6 +60,7 @@ export declare class OrchestratorService {
     private readonly client;
     private readonly logger;
     private readonly resolveAgentHook?;
+    private resolveExtraToolsHook?;
     constructor(anthropicConfig: AnthropicConfig, runner: AgentRunnerService, opts: OrchestratorServiceOptions);
     /**
      * Lookup with dynamic-resolver fallback. Hits the static map first
@@ -53,6 +71,17 @@ export declare class OrchestratorService {
      * for the lifetime of the service to avoid re-fetching across a
      * multi-turn conversation.
      */
+    /** Late-bind the extraTools resolver. Used by `AgentService` (which
+     *  owns the connector registry) to expose its per-agent extraTools
+     *  resolution to the orchestrator without a circular constructor
+     *  dependency. Calling this with a no-op resolver is also fine
+     *  (treated the same as never wiring it). */
+    setExtraToolsResolver(hook: OrchestratorServiceOptions['resolveExtraTools']): void;
+    /** Resolve connector-derived extraTools for a sub-agent. Returns
+     *  undefined when no hook is wired or no userId is in context — the
+     *  caller treats both as "no extras", which preserves the legacy
+     *  behaviour for hosts that haven't wired the hook yet. */
+    private resolveSubAgentExtraTools;
     private resolveAgentDynamic;
     /**
      * Run an agent. Orchestrators automatically get delegation tools injected.

package/dist/services/orchestrator.service.js

@@ -40,6 +40,7 @@ class OrchestratorService {
         });
         this.logger = opts.logger ?? noopLogger;
         this.resolveAgentHook = opts.resolveAgent;
+        this.resolveExtraToolsHook = opts.resolveExtraTools;
         for (const agent of opts.agents) {
             this.agentsMap.set(agent.id, agent);
         }
@@ -53,6 +54,35 @@ class OrchestratorService {
      * for the lifetime of the service to avoid re-fetching across a
      * multi-turn conversation.
      */
+    /** Late-bind the extraTools resolver. Used by `AgentService` (which
+     *  owns the connector registry) to expose its per-agent extraTools
+     *  resolution to the orchestrator without a circular constructor
+     *  dependency. Calling this with a no-op resolver is also fine
+     *  (treated the same as never wiring it). */
+    setExtraToolsResolver(hook) {
+        this.resolveExtraToolsHook = hook;
+    }
+    /** Resolve connector-derived extraTools for a sub-agent. Returns
+     *  undefined when no hook is wired or no userId is in context — the
+     *  caller treats both as "no extras", which preserves the legacy
+     *  behaviour for hosts that haven't wired the hook yet. */
+    async resolveSubAgentExtraTools(agentId, context) {
+        if (!this.resolveExtraToolsHook)
+            return undefined;
+        const userId = context.userId;
+        if (!userId)
+            return undefined;
+        try {
+            const tools = await this.resolveExtraToolsHook(agentId, userId);
+            return tools && tools.length > 0 ? tools : undefined;
+        }
+        catch (err) {
+            // A failed connector lookup shouldn't strand the sub-agent — log
+            // and let it run with its static tools only.
+            this.logger.warn(`resolveExtraTools failed for sub-agent "${agentId}": ${err.message}`);
+            return undefined;
+        }
+    }
     async resolveAgentDynamic(agentId) {
         const cached = this.agentsMap.get(agentId);
         if (cached)
@@ -72,7 +102,12 @@ class OrchestratorService {
     async run(agentId, messages, context) {
         const agent = this.getAgent(agentId);
         if (!agent.canOrchestrate || !agent.subAgents?.length) {
-            return this.runner.run(agent, messages, context);
+            // Resolve the agent's connector-derived extraTools and forward
+            // them — otherwise sub-agents invoked through the orchestrator
+            // lose every connector tool they normally have when reached
+            // directly (Gmail, ClickUp, MCP servers, etc.).
+            const extraTools = await this.resolveSubAgentExtraTools(agent.id, context);
+            return this.runner.run(agent, messages, context, extraTools ? { extraTools } : undefined);
         }
         this.logger.debug(`Running orchestrator "${agentId}" with subagents: ${agent.subAgents.join(', ')}`);
         return this.runOrchestratorLoop(agent, messages, context);
@@ -100,7 +135,10 @@ class OrchestratorService {
             // No-op orchestration — fall straight through. The runner's
             // chunks won't carry `actingAgentId`, which is exactly what we
             // want: this conversation is bound to one agent.
-            yield* this.runner.stream(agent, messages, context);
+            // Resolve extraTools so a sub-agent invoked via delegation has
+            // the same connector toolset it would have on a direct call.
+            const extraTools = await this.resolveSubAgentExtraTools(agent.id, context);
+            yield* this.runner.stream(agent, messages, context, extraTools ? { extraTools } : undefined);
             return;
         }
         this.logger.debug(`Streaming orchestrator "${agentId}" with subagents: ${agent.subAgents.join(', ')}`);
@@ -218,7 +256,13 @@ class OrchestratorService {
                     outputTokens: 0,
                     totalTokens: 0,
                 };
-                for await (const chunk of this.runner.stream(subAgent, subMessages, {
+                // Recurse via `this.stream` (NOT `this.runner.stream`) so a
+                // sub-agent that is itself an orchestrator gets ITS delegation
+                // tools synthesized. Standalone sub-agents short-circuit to
+                // the runner inside `this.stream`. Same fix as the non-stream
+                // path above — without it, hierarchical mode silently fell
+                // through to plain runner at depth > 1.
+                for await (const chunk of this.stream(subAgentId, subMessages, {
                     ...context,
                     agentId: subAgentId,
                 })) {
@@ -317,9 +361,16 @@ class OrchestratorService {
                     const { task } = block.input;
                     const { subAgentId } = delegateTool;
                     this.logger.log(`Orchestrator "${orchestrator.id}" → "${subAgentId}": ${task.slice(0, 80)}...`);
-                    const subAgent = this.getAgent(subAgentId);
                     const subMessages = [{ role: 'user', content: task }];
-                    const subResult = await this.runner.run(subAgent, subMessages, {
+                    // Recurse via `this.run` (NOT `this.runner.run`) so a
+                    // sub-agent that is itself an orchestrator gets ITS delegation
+                    // tools synthesized as well. Standalone sub-agents fall
+                    // through to the runner inside `this.run`. Without this, the
+                    // hierarchical mode broke at depth > 1 — an intermediate node
+                    // like ChatAI saw `canOrchestrate=true` in DB but the runtime
+                    // never honoured it because it was being entered through the
+                    // plain runner.
+                    const subResult = await this.run(subAgentId, subMessages, {
                         ...context,
                         agentId: subAgentId,
                     });

package/package.json

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