@agentforge-io/sdk-server 4.6.0 → 4.6.1

package/dist/index.d.ts

@@ -2,19 +2,19 @@ export { AgentForgeClient } from './client';
 export type { AgentForgeClientOptions, RequestOptions } from './client';
 export { AgentForgeError, AgentForgeAuthError, AgentForgeNotFoundError, AgentForgeNetworkError, } from './errors';
 export { TOOL_CALLBACK_HEADERS, ToolCallbackSignatureError, signToolCallbackPayload, verifyToolCallbackSignature, } from './webhooks';
-export type { AgentMe, AgentSummary, AppUserConnectorStatus, ApprovalCopyBundle, ChannelContext, ChatStreamChunk, ChatStreamEvent, ChatTokenRecord, ConnectorDefaultsResult, ConnectorDefaultsSource, ConnectorResourceItem, ConnectorStatus, ConnectorToolInfo, ConversationHistory, ConversationStatus, CreateAgentInput, CreateClickupTaskInput, CreateClickupTaskResult, ExternalToolSummary, IssueChatTokenInput, ListAgentsResult, ListConnectorResourcesResult, McpServerConfig, MessageRecord, MessageRole, PublicAppBranding, AppSelf, AppSelfConnector, AppSelfConnectors, RegisterToolInput, RegisterToolsInput, RegisterToolsResult, ToolCallbackPayload, ToolCallRecord, ToolPermission, ToolPermissionMode, TokenUsage, TenantSecretEntry, UpdateAgentInput, } from './types';
+export type { AgentMe, AgentSummary, AppUserConnectorStatus, ApprovalCopyBundle, ChannelContext, ChatStreamChunk, ChatStreamEvent, ChatTokenRecord, ConnectorDefaultsResult, ConnectorDefaultsSource, ConnectorResourceItem, ConnectorStatus, ConnectorToolInfo, ConversationHistory, ConversationStatus, CreateAgentInput, CreateClickupTaskInput, CreateClickupTaskResult, ExternalToolSummary, IssueChatTokenInput, ListAgentsResult, ListConnectorResourcesResult, McpServerConfig, MessageRecord, MessageRole, PublicAppBranding, AppSelf, AppSelfConnector, AppSelfConnectors, AppSelfConnectorTools, AppSelfConnectorToolsResponse, RegisterToolInput, RegisterToolsInput, RegisterToolsResult, ToolCallbackPayload, ToolCallRecord, ToolPermission, ToolPermissionMode, TokenUsage, TenantSecretEntry, UpdateAgentInput, InboxThreadMode, InboxMessageDirection, InboxMessageSource, InboxMessageType, InboxThreadCustomerProfileView, InboxThreadView, InboxMessageView, SupportKpiTotals, SupportKpiResponse, AgentAttentionLogRow, } from './types';
 export { AgentsResource } from './resources/agents';
 export { AnalyticsResource } from './resources/analytics';
-export type { AgentAttentionLogRow, SupportAnalyticsQuery, SupportKpiResponse, SupportKpiTotals, } from './resources/analytics';
+export type { GetSupportKpisInput, GetAgentAttentionLogInput, } from './resources/analytics';
 export { AppsResource } from './resources/apps';
 export { ChatResource } from './resources/chat';
 export type { AnthropicClientOptions, StreamMessageInput } from './resources/chat';
 export { ConnectorsResource } from './resources/connectors';
 export type { InboxChannelView } from './resources/connectors';
 export { InboxResource } from './resources/inbox';
-export type { InboxMessageView, InboxThreadCustomerProfileView, InboxThreadMode, InboxThreadView, } from './resources/inbox';
+export type { ListThreadsOptions, SendMessageInput, AssignThreadInput, UnassignThreadInput, SetThreadModeInput, CloseThreadInput, } from './resources/inbox';
 export { ProvisioningResource } from './resources/provisioning';
-export type { ProvisionedTenant, ProvisionedApp, } from './resources/provisioning';
+export type { ProvisionedTenant, ProvisionedApp, ProvisionedTeam, } from './resources/provisioning';
 export { SecretsResource } from './resources/secrets';
 export { ToolsResource } from './resources/tools';
 export type { RespondToCallbackInput, VerifyCallbackInput } from './resources/tools';

package/dist/resources/analytics.d.ts

@@ -1,72 +1,39 @@
 import type { AgentForgeClient } from '../client';
-export interface SupportKpiTotals {
-    receivedCount: number;
-    aiResponsesCount: number;
-    humanMessagesCount: number;
-    escalationsCount: number;
-    aiResolvedCount: number;
-    humanHandledCount: number;
-    assignmentsCount: number;
-    avgResolutionMs: number | null;
-    avgFrtMs: number | null;
-    avgTimeToAssignMs: number | null;
-}
-export interface SupportKpiResponse {
-    tenantId: string;
-    from: string;
-    to: string;
-    totals: SupportKpiTotals;
-    byDimension: Array<SupportKpiTotals & {
-        dimensionType: 'agent' | 'operator';
-        dimensionKey: string;
-    }>;
-}
-export interface AgentAttentionLogRow {
-    dimensionType: 'agent' | 'operator';
-    dimensionKey: string;
-    metricDate: string;
-    receivedCount: number;
-    aiResponsesCount: number;
-    humanMessagesCount: number;
-    escalationsCount: number;
-    aiResolvedCount: number;
-    humanHandledCount: number;
-    assignmentsCount: number;
-    avgResolutionMs: number | null;
-    avgFrtMs: number | null;
-    avgTimeToAssignMs: number | null;
+import type { SupportKpiResponse, AgentAttentionLogRow } from '../types';
+export interface GetSupportKpisInput {
+    /** Window start (inclusive). ISO 8601 or Date. */
+    from: string | Date;
+    /** Window end (exclusive). ISO 8601 or Date. */
+    to: string | Date;
+    agentId?: string;
+    operatorUserId?: string;
 }
-export interface SupportAnalyticsQuery {
-    /** ISO date string. Required. */
-    from: string;
-    /** ISO date string. Required. */
-    to: string;
-    /** Narrow to one agent's rows (`byDimension`/`items` filtered to
-     *  `dimensionType: 'agent', dimensionKey: agentId`). */
+export interface GetAgentAttentionLogInput {
+    from: string | Date;
+    to: string | Date;
     agentId?: string;
-    /** Narrow to one operator's rows. */
     operatorUserId?: string;
 }
 export declare class AnalyticsResource {
     private readonly client;
     constructor(client: AgentForgeClient);
     /**
-     * `GET /apps/me/support-kpis` — totals + per-agent/operator breakdown for
-     * the calling App's tenant, over `[from, to]`.
+     * `GET /apps/me/support-kpis` — totals + per-(agent|operator)
+     * breakdown for the App's tenant, in the given window.
      *
      * @example
-     *   const kpis = await af.analytics.getSupportKpis({
-     *     from: '2026-08-01T00:00:00.000Z',
-     *     to: '2026-08-13T00:00:00.000Z',
+     *   const { totals, byDimension } = await af.analytics.getSupportKpis({
+     *     from: '2026-08-01T00:00:00Z',
+     *     to:   '2026-08-08T00:00:00Z',
      *   });
      */
-    getSupportKpis(query: SupportAnalyticsQuery): Promise<SupportKpiResponse>;
+    getSupportKpis(input: GetSupportKpisInput): Promise<SupportKpiResponse>;
     /**
-     * `GET /apps/me/support-attention-log` — daily per-agent/operator rows
-     * over `[from, to]`. Same query params as `getSupportKpis`.
+     * `GET /apps/me/support-attention-log` — per-day rows for
+     * the "atención por agente" table/chart (SD-11).
      */
-    getAgentAttentionLog(query: SupportAnalyticsQuery): Promise<{
+    getAgentAttentionLog(input: GetAgentAttentionLogInput): Promise<{
         items: AgentAttentionLogRow[];
     }>;
-    private toQueryString;
+    private buildQuery;
 }

package/dist/resources/analytics.js

@@ -1,26 +1,14 @@
 "use strict";
-// analytics resource (AGF-SD-3b, AGF-SUPPORT-DESK epic) — wraps
-// `AppSupportAnalyticsController` (`GET /apps/me/support-kpis`,
-// `GET /apps/me/support-attention-log`) on the platform: pre-aggregated
-// support KPIs (received/AI-responses/escalations/resolution-time/etc.)
-// for the calling App's tenant, tenant-wide with optional agent/operator
-// narrowing.
+// analytics resource (AGF-SD-5) — App-scoped read surface for the support
+// KPIs materialized by SD-3 (`af_support_metrics`). Wraps SD-3b's
+// `AppSupportAnalyticsController` (`GET /apps/me/support-*`), which follows
+// the `me/*` precedent of `AppsController`: the `sk_live_` IS the identity,
+// so there is no `:agentId` in the path and no `tenantId` in the query.
 //
-// Auth: `AppSupportAnalyticsController` accepts BOTH `sk_live_` (appSecret)
-// and `ak_live_` (apiKey) via `ApiKeyGuard`. This resource uses plain
-// `this.client.request()` (NOT `requestWithApiKey()` — that helper
-// hardcodes `ak_live_`-only via `forceApiKey: true` and throws early on an
-// appSecret-only client; see `connectors.ts`'s file header for the same
-// gotcha on the App-user scope methods there), so `authHeaders()` can pick
-// either credential for the `Authorization: Bearer` header. `tenantId` is
-// NEVER a param here (SDD §4.5) — the server resolves it exclusively from
-// the credential.
-//
-// `from`/`to` are REQUIRED on both methods — the platform rejects a
-// missing/malformed/inverted/too-wide range with 400 (no implicit default
-// window). This wrapper does no validation of its own; it forwards
-// whatever `Date` the caller passes as an ISO string and lets the server
-// be the single source of truth for what's a valid range.
+// Both methods are single-tenant reads: `tenantId` is resolved from the
+// caller's auth context on the server (never from input), so the SDK
+// signature only takes the query knobs. `agentId`/`operatorUserId` are
+// optional filters within that tenant.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnalyticsResource = void 0;
 class AnalyticsResource {
@@ -28,32 +16,36 @@ class AnalyticsResource {
         this.client = client;
     }
     /**
-     * `GET /apps/me/support-kpis` — totals + per-agent/operator breakdown for
-     * the calling App's tenant, over `[from, to]`.
+     * `GET /apps/me/support-kpis` — totals + per-(agent|operator)
+     * breakdown for the App's tenant, in the given window.
      *
      * @example
-     *   const kpis = await af.analytics.getSupportKpis({
-     *     from: '2026-08-01T00:00:00.000Z',
-     *     to: '2026-08-13T00:00:00.000Z',
+     *   const { totals, byDimension } = await af.analytics.getSupportKpis({
+     *     from: '2026-08-01T00:00:00Z',
+     *     to:   '2026-08-08T00:00:00Z',
      *   });
      */
-    async getSupportKpis(query) {
-        return this.client.request('GET', `/apps/me/support-kpis${this.toQueryString(query)}`);
+    async getSupportKpis(input) {
+        const qs = this.buildQuery(input);
+        return this.client.request('GET', `/apps/me/support-kpis?${qs}`);
     }
     /**
-     * `GET /apps/me/support-attention-log` — daily per-agent/operator rows
-     * over `[from, to]`. Same query params as `getSupportKpis`.
+     * `GET /apps/me/support-attention-log` — per-day rows for
+     * the "atención por agente" table/chart (SD-11).
      */
-    async getAgentAttentionLog(query) {
-        return this.client.request('GET', `/apps/me/support-attention-log${this.toQueryString(query)}`);
+    async getAgentAttentionLog(input) {
+        const qs = this.buildQuery(input);
+        return this.client.request('GET', `/apps/me/support-attention-log?${qs}`);
     }
-    toQueryString(query) {
-        const params = new URLSearchParams({ from: query.from, to: query.to });
-        if (query.agentId)
-            params.set('agentId', query.agentId);
-        if (query.operatorUserId)
-            params.set('operatorUserId', query.operatorUserId);
-        return `?${params.toString()}`;
+    buildQuery(input) {
+        const params = new URLSearchParams();
+        params.set('from', input.from instanceof Date ? input.from.toISOString() : input.from);
+        params.set('to', input.to instanceof Date ? input.to.toISOString() : input.to);
+        if (input.agentId)
+            params.set('agentId', input.agentId);
+        if (input.operatorUserId)
+            params.set('operatorUserId', input.operatorUserId);
+        return params.toString();
     }
 }
 exports.AnalyticsResource = AnalyticsResource;

package/dist/resources/apps.d.ts

@@ -1,5 +1,5 @@
 import type { AgentForgeClient } from '../client';
-import type { PublicAppBranding, AppSelf, AppSelfConnectors } from '../types';
+import type { PublicAppBranding, AppSelf, AppSelfConnectors, AppSelfConnectorToolsResponse } from '../types';
 export declare class AppsResource {
     private readonly client;
     constructor(client: AgentForgeClient);
@@ -41,5 +41,21 @@ export declare class AppsResource {
          * by the App at runtime.
          */
         list: () => Promise<AppSelfConnectors>;
+        /**
+         * `GET /apps/me/connector-tools` (AGF-CTG-1) — flat tool-name catalog
+         * contributed by the connectors ENABLED for the App this client
+         * authenticated AS. App-level granularity ONLY: this is NOT narrowed
+         * per-end-user — that narrowing already happens downstream at runtime
+         * via `toolsForAppUser ∩ agent.tools[]`.
+         *
+         * Use it to build a whitelist of tool names an App may reference (e.g.
+         * the SOP Architect's bootstrap), so a prompt cannot name a connector
+         * tool the App has no connector enabled for.
+         *
+         * @example
+         *   const { toolNames } = await af.apps.connectors.tools();
+         *   const allowed = new Set(toolNames);
+         */
+        tools: () => Promise<AppSelfConnectorToolsResponse>;
     };
 }

package/dist/resources/apps.js

@@ -35,6 +35,24 @@ class AppsResource {
             list: async () => {
                 return this.client.request('GET', '/apps/me/connectors');
             },
+            /**
+             * `GET /apps/me/connector-tools` (AGF-CTG-1) — flat tool-name catalog
+             * contributed by the connectors ENABLED for the App this client
+             * authenticated AS. App-level granularity ONLY: this is NOT narrowed
+             * per-end-user — that narrowing already happens downstream at runtime
+             * via `toolsForAppUser ∩ agent.tools[]`.
+             *
+             * Use it to build a whitelist of tool names an App may reference (e.g.
+             * the SOP Architect's bootstrap), so a prompt cannot name a connector
+             * tool the App has no connector enabled for.
+             *
+             * @example
+             *   const { toolNames } = await af.apps.connectors.tools();
+             *   const allowed = new Set(toolNames);
+             */
+            tools: async () => {
+                return this.client.request('GET', '/apps/me/connector-tools');
+            },
         };
     }
     /**

package/dist/resources/inbox.d.ts

@@ -1,113 +1,71 @@
 import type { AgentForgeClient } from '../client';
-export declare class InboxResource {
-    private readonly client;
-    constructor(client: AgentForgeClient);
-    /**
-     * `GET /connectors/inbox/agents/:agentId/inbox/threads` — threads for this
-     * agent's support inbox. Optional `channelId` narrows to one channel.
-     *
-     * @example
-     *   const { items } = await af.inbox.listThreads(agentId);
-     */
-    listThreads(agentId: string, opts?: {
-        channelId?: string;
-    }): Promise<{
-        items: InboxThreadView[];
-    }>;
-    /**
-     * `GET /connectors/inbox/agents/:agentId/inbox/threads/:threadId` — a
-     * single thread.
-     */
-    getThread(agentId: string, threadId: string): Promise<InboxThreadView>;
-    /**
-     * `GET /connectors/inbox/agents/:agentId/inbox/threads/:threadId/messages`
-     * — full message history for a thread.
-     */
-    listMessages(agentId: string, threadId: string): Promise<{
-        items: InboxMessageView[];
-    }>;
-    /**
-     * `POST .../threads/:threadId/messages` — send a message as the operator.
-     * `pauseAgent` defaults `true` server-side (pass `false` to reply without
-     * taking the thread away from the agent). `operatorId` is the App's own
-     * opaque identifier for the acting human rep — see file header.
-     *
-     * @example
-     *   await af.inbox.sendOperatorMessage(agentId, threadId, {
-     *     text: 'Un momento, reviso tu caso.',
-     *     operatorId: 'scrappydoc-rep-42',
-     *   });
-     */
-    sendOperatorMessage(agentId: string, threadId: string, input: {
-        text: string;
-        pauseAgent?: boolean;
-        operatorId?: string;
-    }): Promise<void>;
-    /**
-     * `POST .../threads/:threadId/assign` — claim a thread for an operator.
-     * `operatorId` is required (the server rejects a missing one with 401).
-     */
-    assignThread(agentId: string, threadId: string, input: {
-        operatorId: string;
-    }): Promise<void>;
-    /**
-     * `DELETE .../threads/:threadId/assign` — release a thread claim
-     * (handback). `operatorId`, when given, must match the current assignee
-     * server-side.
-     */
-    handback(agentId: string, threadId: string, opts?: {
-        operatorId?: string;
-    }): Promise<void>;
-    /**
-     * `POST .../threads/:threadId/mode` — switch a thread between agent/human
-     * mode.
-     */
-    setThreadMode(agentId: string, threadId: string, mode: InboxThreadMode): Promise<void>;
-    /**
-     * `POST .../threads/:threadId/close` — close a human-mode thread.
-     */
-    closeThread(agentId: string, threadId: string, opts?: {
-        notes?: string;
-        operatorId?: string;
-    }): Promise<void>;
+import type { InboxThreadView, InboxMessageView, InboxThreadMode } from '../types';
+export interface ListThreadsOptions {
+    /** Optional filter to threads on a single channel of the agent. */
+    channelId?: string;
 }
-export type InboxThreadMode = 'agent' | 'human';
-export interface InboxThreadCustomerProfileView {
-    id: string;
-    displayName?: string;
-    username?: string;
-    avatarUrl?: string;
-    providerId?: string;
-    tags?: string[];
-    notes?: string;
+export interface SendMessageInput {
+    /** The operator's text. */
+    text: string;
+    /** Default true. Toggle off when the operator wants to chime in
+     *  without taking the thread away from the agent. */
+    pauseAgent?: boolean;
+    /** App-minted operator identity (see file header). */
+    operatorId?: string;
+}
+export interface AssignThreadInput {
+    /** App-minted operator identity — required for assign. Same string
+     *  re-sent proves ownership of a prior claim. */
+    operatorId: string;
+}
+export interface UnassignThreadInput {
+    /** App-minted operator identity — must match the current assignee. */
+    operatorId: string;
 }
-export interface InboxThreadView {
-    id: string;
-    channelId: string;
-    externalId: string;
-    displayName?: string;
+export interface SetThreadModeInput {
     mode: InboxThreadMode;
-    unreadCount: number;
-    lastMessageAt?: string;
-    lastMessagePreview?: string;
-    assignedHumanUserId?: string;
-    closedAt?: string;
-    closeNotes?: string;
-    closedByUserId?: string;
-    customerProfileId?: string;
-    customerProfile?: InboxThreadCustomerProfileView;
-    createdAt: string;
-    updatedAt: string;
 }
-export interface InboxMessageView {
-    id: string;
-    threadId: string;
-    direction: 'inbound' | 'outbound';
-    source: 'customer' | 'agent' | 'operator';
-    type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'location' | 'unsupported';
-    body: string;
-    externalMessageId?: string;
-    payload?: Record<string, unknown>;
-    sentAt: string;
-    recordedAt: string;
+export interface CloseThreadInput {
+    /** Free-text notes the operator leaves on close. Persisted as
+     *  `af_inbox_threads.close_notes` — later consumed by AGF-BRAIN as
+     *  institutional knowledge. */
+    notes?: string;
+    /** App-minted operator identity — recorded on `closed_by_user_id`. */
+    operatorId?: string;
+}
+/**
+ * Agent-scoped inbox operator surface. Every method takes the `agentId`
+ * whose threads the App is operating; the App-ownership boundary is
+ * enforced server-side (404 on mismatch, mirroring
+ * `assertAgentOwnedByApp` in the identity-side controllers).
+ *
+ * @example
+ *   const inbox = af.inbox.forAgent(agentId);
+ *   const { items: threads } = await inbox.listThreads();
+ *   const { items: messages } = await inbox.listMessages(threads[0].id);
+ *   await inbox.sendMessage(threads[0].id, {
+ *     text: 'Hi, jumping in to help',
+ *     operatorId: 'rep_alice',
+ *   });
+ */
+export declare class InboxResource {
+    private readonly client;
+    constructor(client: AgentForgeClient);
+    /** Bind an agent id and return a helper with one method per
+     *  `AppInboxController` route. Avoids threading `agentId` through
+     *  every call. */
+    forAgent(agentId: string): {
+        listThreads: (opts?: ListThreadsOptions) => Promise<{
+            items: InboxThreadView[];
+        }>;
+        getThread: (threadId: string) => Promise<InboxThreadView>;
+        listMessages: (threadId: string) => Promise<{
+            items: InboxMessageView[];
+        }>;
+        sendMessage: (threadId: string, input: SendMessageInput) => Promise<void>;
+        assign: (threadId: string, input: AssignThreadInput) => Promise<void>;
+        unassign: (threadId: string, input: UnassignThreadInput) => Promise<void>;
+        setMode: (threadId: string, input: SetThreadModeInput) => Promise<void>;
+        close: (threadId: string, input?: CloseThreadInput) => Promise<void>;
+    };
 }

package/dist/resources/inbox.js

@@ -1,118 +1,80 @@
 "use strict";
-// inbox resource (AGF-SD-1, AGF-SUPPORT-DESK epic) — wraps
-// `AppInboxController` (`connectors/inbox/agents/:agentId/inbox/*`) on the
-// platform: list/read/reply/assign/handback/mode/close for an agent's
-// support inbox threads, authenticated as an App (`sk_live_`) or an
-// agent-scoped `ak_live_` — never a human dashboard session.
+// inbox resource (AGF-SD-5) — App-scoped operator surface. Wraps the
+// platform's `AppInboxController` (AGF-SD-1, `connectors/inbox/agents/:agentId`),
+// exposing list/read/reply/assign/close for the threads of an agent the
+// calling App owns.
 //
-// Auth: `AppInboxController` accepts BOTH `sk_live_` (appSecret) and
-// `ak_live_` (apiKey) via `ApiKeyGuard` — unlike the tenant-admin-only
-// surfaces `ConnectorsResource` wraps with `requestWithApiKey()` (which
-// hardcodes `ak_live_` and throws early on an appSecret-only client, see
-// that file's header), inbox operator routes are meant to be called by an
-// App itself. So this resource uses plain `this.client.request()`, whose
-// `authHeaders()` picks `apiKey` OR `appSecret` for the `Authorization:
-// Bearer` header (chatToken, if present instead, is rejected server-side
-// with 401 since the route requires `auth.isApiKey`). Every method takes
-// `agentId` explicitly (unlike `af.agents.me()`) because the platform
-// route itself is per-agent and validates ownership server-side
-// (`assertOwnedAgent` — 404, not 403, on a foreign agent).
+// Auth: `ApiKeyGuard` on the server accepts BOTH `ak_live_` and `sk_live_`.
+// The SDK's `authHeaders()` already sends whichever the client was
+// constructed with on the `Authorization: Bearer` header — no per-call
+// wiring needed here.
 //
-// Tenant isolation (SDD §4.5): `tenantId` is NEVER a param here — the
-// server resolves it exclusively from the `ak_live_`/`sk_live_` credential.
+// `operatorId` semantics: SD-1's header comment flags this explicitly — an
+// App has no `af_users.id`, so `operatorId` is whatever stable string the
+// App mints for its own end of the conversation. The SDK exposes it as an
+// optional param on `send()`, `assign()`, `unassign()`, `close()` and
+// passes it through verbatim. The server's assignment guard still enforces
+// "same operatorId re-sent = same claimant".
 //
-// Operator identity: the platform has no concept of an App's own
-// human-support-rep identity. `operatorId` (optional on most write methods)
-// is an opaque string the calling App mints for its own end of the
-// conversation — passed through verbatim as the platform's `actingUserId`/
-// `userId`. See `AppInboxController`'s file header on the platform for the
-// full rationale.
-//
-// NOT covered here (left for a future extension — see file bottom for
-// what's deliberately excluded and why):
-//   - `af.inbox.channels.get`/`update` — no App-scoped single-channel-read
-//     or update route exists on the platform today (`ApiKeyInboxController`
-//     only has list/create/delete). `list`/`create`/`destroy` already live
-//     on `af.connectors.*` (see `connectors.ts`) — not duplicated here.
-//   - operator online/offline status (`PUT teams/:teamId/operator/status`)
-//     — lives on `OperatorStatusController`, gated by the GLOBAL
-//     `JwtAuthGuard` (human dashboard session), not `ApiKeyGuard`. No
-//     `@Public()`, not reachable with `sk_live_`/`ak_live_` at all.
+// NOTE — chip AGF-INBOX-OPERATORID-UUID: SD-1's free-string `operatorId`
+// collides with UUID columns on assign/close (open follow-up on the
+// platform side). Callers passing arbitrary strings should not be
+// surprised by a 500 today; the shape convergence lands separately.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InboxResource = void 0;
+/**
+ * Agent-scoped inbox operator surface. Every method takes the `agentId`
+ * whose threads the App is operating; the App-ownership boundary is
+ * enforced server-side (404 on mismatch, mirroring
+ * `assertAgentOwnedByApp` in the identity-side controllers).
+ *
+ * @example
+ *   const inbox = af.inbox.forAgent(agentId);
+ *   const { items: threads } = await inbox.listThreads();
+ *   const { items: messages } = await inbox.listMessages(threads[0].id);
+ *   await inbox.sendMessage(threads[0].id, {
+ *     text: 'Hi, jumping in to help',
+ *     operatorId: 'rep_alice',
+ *   });
+ */
 class InboxResource {
     constructor(client) {
         this.client = client;
     }
-    /**
-     * `GET /connectors/inbox/agents/:agentId/inbox/threads` — threads for this
-     * agent's support inbox. Optional `channelId` narrows to one channel.
-     *
-     * @example
-     *   const { items } = await af.inbox.listThreads(agentId);
-     */
-    async listThreads(agentId, opts) {
-        const qs = opts?.channelId
-            ? `?channelId=${encodeURIComponent(opts.channelId)}`
-            : '';
-        return this.client.request('GET', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads${qs}`);
-    }
-    /**
-     * `GET /connectors/inbox/agents/:agentId/inbox/threads/:threadId` — a
-     * single thread.
-     */
-    async getThread(agentId, threadId) {
-        return this.client.request('GET', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}`);
-    }
-    /**
-     * `GET /connectors/inbox/agents/:agentId/inbox/threads/:threadId/messages`
-     * — full message history for a thread.
-     */
-    async listMessages(agentId, threadId) {
-        return this.client.request('GET', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/messages`);
-    }
-    /**
-     * `POST .../threads/:threadId/messages` — send a message as the operator.
-     * `pauseAgent` defaults `true` server-side (pass `false` to reply without
-     * taking the thread away from the agent). `operatorId` is the App's own
-     * opaque identifier for the acting human rep — see file header.
-     *
-     * @example
-     *   await af.inbox.sendOperatorMessage(agentId, threadId, {
-     *     text: 'Un momento, reviso tu caso.',
-     *     operatorId: 'scrappydoc-rep-42',
-     *   });
-     */
-    async sendOperatorMessage(agentId, threadId, input) {
-        await this.client.request('POST', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/messages`, input);
-    }
-    /**
-     * `POST .../threads/:threadId/assign` — claim a thread for an operator.
-     * `operatorId` is required (the server rejects a missing one with 401).
-     */
-    async assignThread(agentId, threadId, input) {
-        await this.client.request('POST', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/assign`, input);
-    }
-    /**
-     * `DELETE .../threads/:threadId/assign` — release a thread claim
-     * (handback). `operatorId`, when given, must match the current assignee
-     * server-side.
-     */
-    async handback(agentId, threadId, opts) {
-        await this.client.request('DELETE', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/assign`, opts);
-    }
-    /**
-     * `POST .../threads/:threadId/mode` — switch a thread between agent/human
-     * mode.
-     */
-    async setThreadMode(agentId, threadId, mode) {
-        await this.client.request('POST', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/mode`, { mode });
-    }
-    /**
-     * `POST .../threads/:threadId/close` — close a human-mode thread.
-     */
-    async closeThread(agentId, threadId, opts) {
-        await this.client.request('POST', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/close`, opts);
+    /** Bind an agent id and return a helper with one method per
+     *  `AppInboxController` route. Avoids threading `agentId` through
+     *  every call. */
+    forAgent(agentId) {
+        const base = `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox`;
+        return {
+            listThreads: async (opts = {}) => {
+                const qs = opts.channelId
+                    ? `?channelId=${encodeURIComponent(opts.channelId)}`
+                    : '';
+                return this.client.request('GET', `${base}/threads${qs}`);
+            },
+            getThread: async (threadId) => {
+                return this.client.request('GET', `${base}/threads/${encodeURIComponent(threadId)}`);
+            },
+            listMessages: async (threadId) => {
+                return this.client.request('GET', `${base}/threads/${encodeURIComponent(threadId)}/messages`);
+            },
+            sendMessage: async (threadId, input) => {
+                await this.client.request('POST', `${base}/threads/${encodeURIComponent(threadId)}/messages`, input);
+            },
+            assign: async (threadId, input) => {
+                await this.client.request('POST', `${base}/threads/${encodeURIComponent(threadId)}/assign`, input);
+            },
+            unassign: async (threadId, input) => {
+                await this.client.request('DELETE', `${base}/threads/${encodeURIComponent(threadId)}/assign`, input);
+            },
+            setMode: async (threadId, input) => {
+                await this.client.request('POST', `${base}/threads/${encodeURIComponent(threadId)}/mode`, input);
+            },
+            close: async (threadId, input = {}) => {
+                await this.client.request('POST', `${base}/threads/${encodeURIComponent(threadId)}/close`, input);
+            },
+        };
     }
 }
 exports.InboxResource = InboxResource;

package/dist/resources/provisioning.d.ts

@@ -11,6 +11,14 @@ export interface ProvisionedApp {
     publicKey: string;
     appSecret: string;
 }
+/** `POST /platform/host-teams` result — a team-orchestrator's identity
+ *  (AGF-SD-6a). No secret to reveal here (unlike `tenant()`/`app()`) — a
+ *  team has no credential of its own, it's addressed through the
+ *  tenant's `ak_live_` / App's `sk_live_`. */
+export interface ProvisionedTeam {
+    teamId: string;
+    orchestratorAgentId: string;
+}
 export declare class ProvisioningResource {
     private readonly client;
     constructor(client: AgentForgeClient);
@@ -49,4 +57,27 @@ export declare class ProvisioningResource {
         hostApp: string;
         hostRef?: string;
     }): Promise<ProvisionedApp>;
+    /**
+     * `POST /platform/host-teams` (AGF-SD-6a) — find-or-create a
+     * team-orchestrator for an EXISTING tenant on behalf of a trusted host
+     * app. Idempotent by `(tenantId, hostRef)`: a re-provision returns the
+     * SAME `teamId`/`orchestratorAgentId`, never a duplicate orchestrator.
+     *
+     * @param input.tenantId the tenant the team belongs to (host provisions
+     *                        it first via `tenant()`)
+     * @param input.hostApp   short host id (e.g. "scrappydoc") — recorded
+     *                        for parity with `tenant()`/`app()`, not part of
+     *                        the idempotency key here (a team already lives
+     *                        under one tenant, so `(tenantId, hostRef)`
+     *                        alone is unambiguous)
+     * @param input.hostRef   host reference (e.g. the workspaceId) — the
+     *                        idempotency key together with `tenantId`
+     * @param input.name      display name, only used on first provision
+     */
+    team(input: {
+        tenantId: string;
+        hostApp: string;
+        hostRef: string;
+        name?: string;
+    }): Promise<ProvisionedTeam>;
 }

package/dist/resources/provisioning.js

@@ -51,5 +51,30 @@ class ProvisioningResource {
     async app(input) {
         return this.client.request('POST', '/platform/host-apps', { tenantId: input.tenantId, hostApp: input.hostApp, hostRef: input.hostRef }, { headers: this.headers() });
     }
+    /**
+     * `POST /platform/host-teams` (AGF-SD-6a) — find-or-create a
+     * team-orchestrator for an EXISTING tenant on behalf of a trusted host
+     * app. Idempotent by `(tenantId, hostRef)`: a re-provision returns the
+     * SAME `teamId`/`orchestratorAgentId`, never a duplicate orchestrator.
+     *
+     * @param input.tenantId the tenant the team belongs to (host provisions
+     *                        it first via `tenant()`)
+     * @param input.hostApp   short host id (e.g. "scrappydoc") — recorded
+     *                        for parity with `tenant()`/`app()`, not part of
+     *                        the idempotency key here (a team already lives
+     *                        under one tenant, so `(tenantId, hostRef)`
+     *                        alone is unambiguous)
+     * @param input.hostRef   host reference (e.g. the workspaceId) — the
+     *                        idempotency key together with `tenantId`
+     * @param input.name      display name, only used on first provision
+     */
+    async team(input) {
+        return this.client.request('POST', '/platform/host-teams', {
+            tenantId: input.tenantId,
+            hostApp: input.hostApp,
+            hostRef: input.hostRef,
+            name: input.name,
+        }, { headers: this.headers() });
+    }
 }
 exports.ProvisioningResource = ProvisioningResource;

package/dist/types.d.ts

@@ -84,6 +84,16 @@ export interface AppSelfConnectors {
     mode: 'whitelist' | 'legacy';
     connectors: AppSelfConnector[];
 }
+export interface AppSelfConnectorTools {
+    connectorId: string;
+    toolNames: string[];
+}
+export interface AppSelfConnectorToolsResponse {
+    connectors: AppSelfConnectorTools[];
+    /** Flat, de-duplicated union of every `toolNames` entry above — this is
+     *  what a whitelist consumer actually wants. */
+    toolNames: string[];
+}
 export interface RegisterToolInput {
     name: string;
     description: string;
@@ -488,4 +498,93 @@ export interface TenantSecretEntry {
      *  Ausente si nunca se configuró. */
     updatedAt?: string;
 }
+export type InboxThreadMode = 'agent' | 'human';
+export type InboxMessageDirection = 'inbound' | 'outbound';
+export type InboxMessageSource = 'customer' | 'agent' | 'operator';
+export type InboxMessageType = 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'location' | 'unsupported';
+/** Read-through customer profile snapshot embedded on every thread — saves
+ *  the UI a round-trip per thread. NULL on threads whose customerProfileId
+ *  hasn't been linked yet (very brief window on first inbound). */
+export interface InboxThreadCustomerProfileView {
+    id: string;
+    displayName?: string;
+    /** Provider handle without the leading `@`. */
+    username?: string;
+    avatarUrl?: string;
+    providerId?: string;
+    tags?: string[];
+    notes?: string;
+}
+export interface InboxThreadView {
+    id: string;
+    channelId: string;
+    externalId: string;
+    displayName?: string;
+    mode: InboxThreadMode;
+    unreadCount: number;
+    lastMessageAt?: string;
+    lastMessagePreview?: string;
+    /** Workspace user currently responsible for the thread. */
+    assignedHumanUserId?: string;
+    /** AGF-ASSIGN-P1-CLOSE. ISO timestamp when the human conversation was
+     *  formally closed. Undefined = open / never escalated. */
+    closedAt?: string;
+    closeNotes?: string;
+    closedByUserId?: string;
+    customerProfileId?: string;
+    customerProfile?: InboxThreadCustomerProfileView;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface InboxMessageView {
+    id: string;
+    threadId: string;
+    direction: InboxMessageDirection;
+    source: InboxMessageSource;
+    type: InboxMessageType;
+    body: string;
+    externalMessageId?: string;
+    payload?: Record<string, unknown>;
+    sentAt: string;
+    recordedAt: string;
+}
+export interface SupportKpiTotals {
+    receivedCount: number;
+    aiResponsesCount: number;
+    humanMessagesCount: number;
+    escalationsCount: number;
+    aiResolvedCount: number;
+    humanHandledCount: number;
+    assignmentsCount: number;
+    avgResolutionMs: number | null;
+    avgFrtMs: number | null;
+    avgTimeToAssignMs: number | null;
+}
+export interface SupportKpiResponse {
+    tenantId: string;
+    from: string;
+    to: string;
+    totals: SupportKpiTotals;
+    /** One entry per (dimensionType, dimensionKey) in range. */
+    byDimension: Array<SupportKpiTotals & {
+        dimensionType: 'agent' | 'operator';
+        dimensionKey: string;
+    }>;
+}
+export interface AgentAttentionLogRow {
+    dimensionType: 'agent' | 'operator';
+    dimensionKey: string;
+    /** YYYY-MM-DD */
+    metricDate: string;
+    receivedCount: number;
+    aiResponsesCount: number;
+    humanMessagesCount: number;
+    escalationsCount: number;
+    aiResolvedCount: number;
+    humanHandledCount: number;
+    assignmentsCount: number;
+    avgResolutionMs: number | null;
+    avgFrtMs: number | null;
+    avgTimeToAssignMs: number | null;
+}
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/sdk-server",
-  "version": "4.6.0",
+  "version": "4.6.1",
   "description": "Server-side SDK for backend apps integrating with AgentForge platform. Auth via ChatToken or ak_live_ API key.",
   "license": "MIT",
   "main": "dist/index.js",