@agentforge-io/sdk-server 4.0.18

package/dist/client.d.ts

@@ -0,0 +1,72 @@
+import { AgentsResource } from './resources/agents';
+import { ChatResource } from './resources/chat';
+import { ConnectorsResource } from './resources/connectors';
+import { SecretsResource } from './resources/secrets';
+import { ToolsResource } from './resources/tools';
+export interface AgentForgeClientOptions {
+    /** Platform base URL — e.g. http://localhost:3032 in dev. */
+    baseURL: string;
+    /** ChatToken scoped to a specific agent. */
+    chatToken?: string;
+    /** ak_live_... API key scoped to the tenant. */
+    apiKey?: string;
+    /** Override fetch (for testing or custom transports). */
+    fetch?: typeof fetch;
+    /** Default request timeout in ms. Applied to every HTTP call unless
+     *  overridden per-call (e.g. streaming calls disable it entirely). */
+    timeoutMs?: number;
+}
+export interface RequestOptions {
+    /** Force ak_live_ auth even when the client also has a chatToken. Required
+     *  for tenant-admin surfaces that reject ChatToken auth outright. */
+    forceApiKey?: boolean;
+    /** Extra headers merged in AFTER the resolved auth header — e.g. the HMAC
+     *  signature headers a tool-callback response needs alongside its normal
+     *  ChatToken auth. */
+    headers?: Record<string, string>;
+    /** Pre-serialized body sent as-is (no JSON.stringify). Needed when the
+     *  caller already hashed/signed this EXACT string and re-serializing the
+     *  same object could (in principle) produce a different byte sequence. */
+    rawBody?: string;
+    /** ms before the request aborts. `null` disables the timeout entirely —
+     *  used for chat streaming, where a tool-calling turn can legitimately
+     *  run long. Defaults to the client's `timeoutMs`. */
+    timeoutMs?: number | null;
+}
+export declare class AgentForgeClient {
+    readonly baseURL: string;
+    private readonly chatToken?;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    readonly agents: AgentsResource;
+    readonly chat: ChatResource;
+    readonly connectors: ConnectorsResource;
+    readonly secrets: SecretsResource;
+    readonly tools: ToolsResource;
+    constructor(opts: AgentForgeClientOptions);
+    authHeaders(): Record<string, string>;
+    getApiKey(): string | undefined;
+    getChatToken(): string | undefined;
+    /** Como `getApiKey()`, pero tira si el cliente no fue construido con una
+     *  ak_live_ — usado por resources cuya superficie SIEMPRE requiere apiKey
+     *  (tenant-admin), regardless de si también hay chatToken. */
+    requireApiKey(): string;
+    private resolveAuthHeaders;
+    /**
+     * Primitiva de bajo nivel: hace el fetch, mapea status codes a errores
+     * tipados, y devuelve la `Response` cruda SIN parsear el body — así sirve
+     * tanto para el helper JSON (`request`) como para streaming (`requestStream`)
+     * y para respuestas 204 sin body (`tools.respondToCallback`).
+     */
+    requestRaw(method: string, path: string, opts?: RequestOptions): Promise<Response>;
+    request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    /** Como `request()`, pero fuerza auth ak_live_ — para superficies
+     *  tenant-admin (connector-resources, connectors/oauth/*-for-tenant) que
+     *  rechazan ChatToken aunque el cliente tenga uno configurado también. */
+    requestWithApiKey<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** Abre un stream SSE. Sin timeout (`timeoutMs: null`) — una llamada con
+     *  varias rondas de tool-calling puede tardar más que el default de 30s.
+     *  El caller consume `res.body` como ReadableStream<Uint8Array>. */
+    requestStream(method: string, path: string, body?: unknown): Promise<Response>;
+}

package/dist/client.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentForgeClient = void 0;
+// AgentForgeClient — punto de entrada del SDK.
+//
+// Uso:
+//   const af = new AgentForgeClient({
+//     baseURL: 'http://localhost:3032',
+//     chatToken: process.env.AGENTFORGE_CHAT_TOKEN,
+//   });
+//   const agent = await af.agents.me();
+//
+// Auth: la app cliente elige UNO de dos modos:
+//   - `chatToken`: scoped a un agent específico (recomendado para apps
+//     que consumen UN agent del tenant). Header X-Chat-Token.
+//   - `apiKey`: ak_live_... scoped al tenant (futuro v2).
+//
+// Si ambos están presentes, chatToken gana (es el más específico) — EXCEPTO
+// en superficies tenant-admin (connectors resource picker, OAuth
+// authorize-for-tenant) que el server rechaza explícitamente si el caller
+// solo tiene ChatToken. Esas pasan `{ forceApiKey: true }` a `request()`.
+const errors_1 = require("./errors");
+const agents_1 = require("./resources/agents");
+const chat_1 = require("./resources/chat");
+const connectors_1 = require("./resources/connectors");
+const secrets_1 = require("./resources/secrets");
+const tools_1 = require("./resources/tools");
+class AgentForgeClient {
+    constructor(opts) {
+        if (!opts.baseURL) {
+            throw new Error('AgentForgeClient: baseURL is required');
+        }
+        if (!opts.chatToken && !opts.apiKey) {
+            throw new Error('AgentForgeClient: either chatToken or apiKey is required');
+        }
+        this.baseURL = opts.baseURL.replace(/\/$/, '');
+        this.chatToken = opts.chatToken;
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.timeoutMs = opts.timeoutMs ?? 30000;
+        this.agents = new agents_1.AgentsResource(this);
+        this.chat = new chat_1.ChatResource(this);
+        this.connectors = new connectors_1.ConnectorsResource(this);
+        this.secrets = new secrets_1.SecretsResource(this);
+        this.tools = new tools_1.ToolsResource(this);
+    }
+    // Auth headers derivados del modo. ChatToken gana si ambos están presentes.
+    authHeaders() {
+        if (this.chatToken)
+            return { 'X-Chat-Token': this.chatToken };
+        if (this.apiKey)
+            return { Authorization: `Bearer ${this.apiKey}` };
+        return {};
+    }
+    // Expone el modo auth para que resources puedan tomar decisiones (ej. chat
+    // proxy necesita la ak_live_ explícita en x-api-key — no ChatToken).
+    getApiKey() {
+        return this.apiKey;
+    }
+    getChatToken() {
+        return this.chatToken;
+    }
+    /** Como `getApiKey()`, pero tira si el cliente no fue construido con una
+     *  ak_live_ — usado por resources cuya superficie SIEMPRE requiere apiKey
+     *  (tenant-admin), regardless de si también hay chatToken. */
+    requireApiKey() {
+        if (!this.apiKey) {
+            throw new Error('AgentForgeClient: this call requires an ak_live_ apiKey (tenant-wide), ' +
+                'but the client was constructed without one.');
+        }
+        return this.apiKey;
+    }
+    resolveAuthHeaders(opts) {
+        if (opts?.forceApiKey)
+            return { Authorization: `Bearer ${this.requireApiKey()}` };
+        return this.authHeaders();
+    }
+    /**
+     * Primitiva de bajo nivel: hace el fetch, mapea status codes a errores
+     * tipados, y devuelve la `Response` cruda SIN parsear el body — así sirve
+     * tanto para el helper JSON (`request`) como para streaming (`requestStream`)
+     * y para respuestas 204 sin body (`tools.respondToCallback`).
+     */
+    async requestRaw(method, path, opts) {
+        const url = `${this.baseURL}${path.startsWith('/') ? path : '/' + path}`;
+        const controller = new AbortController();
+        const timeoutMs = opts?.timeoutMs === null ? undefined : (opts?.timeoutMs ?? this.timeoutMs);
+        const timeout = timeoutMs !== undefined ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method,
+                headers: {
+                    ...(opts?.rawBody !== undefined ? { 'content-type': 'application/json' } : {}),
+                    accept: 'application/json',
+                    ...this.resolveAuthHeaders(opts),
+                    ...(opts?.headers ?? {}),
+                },
+                body: opts?.rawBody,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const e = err;
+            throw new errors_1.AgentForgeNetworkError(`Network call ${method} ${path} failed: ${e.message}`, e);
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
+        if (res.status === 401 || res.status === 403) {
+            const bodyText = await res.text();
+            throw new errors_1.AgentForgeAuthError(res.status, `${method} ${path} → ${res.status}`, bodyText);
+        }
+        if (res.status === 404) {
+            const bodyText = await res.text();
+            throw new errors_1.AgentForgeNotFoundError(`${method} ${path} → 404`, bodyText);
+        }
+        if (!res.ok) {
+            const bodyText = await res.text();
+            throw new errors_1.AgentForgeError(res.status, `${method} ${path} → ${res.status}`, bodyText);
+        }
+        return res;
+    }
+    // Request tipado. Maneja 4xx con errores específicos, 5xx genérico, network como AgentForgeNetworkError.
+    async request(method, path, body, opts) {
+        const res = await this.requestRaw(method, path, {
+            ...opts,
+            rawBody: body === undefined ? undefined : JSON.stringify(body),
+        });
+        // Algunos endpoints (POST sin body de respuesta) pueden ser 204.
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    /** Como `request()`, pero fuerza auth ak_live_ — para superficies
+     *  tenant-admin (connector-resources, connectors/oauth/*-for-tenant) que
+     *  rechazan ChatToken aunque el cliente tenga uno configurado también. */
+    async requestWithApiKey(method, path, body) {
+        return this.request(method, path, body, { forceApiKey: true });
+    }
+    /** Abre un stream SSE. Sin timeout (`timeoutMs: null`) — una llamada con
+     *  varias rondas de tool-calling puede tardar más que el default de 30s.
+     *  El caller consume `res.body` como ReadableStream<Uint8Array>. */
+    async requestStream(method, path, body) {
+        return this.requestRaw(method, path, {
+            rawBody: body === undefined ? undefined : JSON.stringify(body),
+            headers: { accept: 'text/event-stream' },
+            timeoutMs: null,
+        });
+    }
+}
+exports.AgentForgeClient = AgentForgeClient;

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class AgentForgeError extends Error {
+    readonly status: number;
+    readonly body?: string;
+    constructor(status: number, message: string, body?: string);
+}
+export declare class AgentForgeAuthError extends AgentForgeError {
+    constructor(status: 401 | 403, message: string, body?: string);
+}
+export declare class AgentForgeNotFoundError extends AgentForgeError {
+    constructor(message: string, body?: string);
+}
+export declare class AgentForgeNetworkError extends Error {
+    readonly cause: Error;
+    constructor(message: string, cause: Error);
+}

package/dist/errors.js

@@ -0,0 +1,36 @@
+"use strict";
+// Errores tipados que el SDK lanza. Las apps cliente pueden hacer
+// `instanceof AgentForgeAuthError` para distinguir 401/403 de otros fallos.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentForgeNetworkError = exports.AgentForgeNotFoundError = exports.AgentForgeAuthError = exports.AgentForgeError = void 0;
+class AgentForgeError extends Error {
+    constructor(status, message, body) {
+        super(message);
+        this.name = 'AgentForgeError';
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.AgentForgeError = AgentForgeError;
+class AgentForgeAuthError extends AgentForgeError {
+    constructor(status, message, body) {
+        super(status, message, body);
+        this.name = 'AgentForgeAuthError';
+    }
+}
+exports.AgentForgeAuthError = AgentForgeAuthError;
+class AgentForgeNotFoundError extends AgentForgeError {
+    constructor(message, body) {
+        super(404, message, body);
+        this.name = 'AgentForgeNotFoundError';
+    }
+}
+exports.AgentForgeNotFoundError = AgentForgeNotFoundError;
+class AgentForgeNetworkError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'AgentForgeNetworkError';
+        this.cause = cause;
+    }
+}
+exports.AgentForgeNetworkError = AgentForgeNetworkError;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+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, ApprovalCopyBundle, ChatStreamChunk, ChatStreamEvent, ChatTokenRecord, ConnectorDefaultsResult, ConnectorDefaultsSource, ConnectorResourceItem, ConnectorStatus, ConnectorToolInfo, ConversationHistory, ConversationStatus, CreateAgentInput, CreateClickupTaskInput, CreateClickupTaskResult, ExternalToolSummary, IssueChatTokenInput, ListAgentsResult, ListConnectorResourcesResult, McpServerConfig, MessageRecord, MessageRole, RegisterToolInput, RegisterToolsInput, RegisterToolsResult, ToolCallbackPayload, ToolCallRecord, ToolPermission, ToolPermissionMode, TokenUsage, TenantSecretEntry, UpdateAgentInput, } from './types';
+export { AgentsResource } from './resources/agents';
+export { ChatResource } from './resources/chat';
+export type { AnthropicClientOptions, StreamMessageInput } from './resources/chat';
+export { ConnectorsResource } from './resources/connectors';
+export type { InboxChannelView } from './resources/connectors';
+export { SecretsResource } from './resources/secrets';
+export { ToolsResource } from './resources/tools';
+export type { RespondToCallbackInput, VerifyCallbackInput } from './resources/tools';

package/dist/index.js

@@ -0,0 +1,53 @@
+"use strict";
+// AgentForge server-side SDK — public exports.
+//
+// Uso típico (ScrappyDoc en M8):
+//   import {
+//     AgentForgeClient,
+//     AgentForgeAuthError,
+//     type AgentMe,
+//   } from '@agentforge-io/sdk-server';
+//
+//   const af = new AgentForgeClient({
+//     baseURL: process.env.AGENTFORGE_API_URL!,
+//     chatToken: process.env.AGENTFORGE_CHAT_TOKEN,
+//     apiKey: process.env.AGENTFORGE_API_KEY,
+//   });
+//
+//   const agent = await af.agents.me();
+//   await af.agents.registerTools({ tools: [...] });
+//   const anthropic = await af.chat.createAnthropicClient();
+//
+//   // Chat agent-aware con tool-calling + connectors:
+//   for await (const ev of af.chat.streamMessage({ content: 'hola' })) { ... }
+//
+//   // Picker de recursos de connectors (ak_live_ tenant-wide):
+//   const { items } = await af.connectors.listConnected();
+//
+//   // Tool 'remote': verificar callback entrante + responder resultado.
+//   const payload = af.tools.verifyCallback({ rawBody, signatureHeader, secretPlaintext });
+//   await af.tools.respondToCallback({ resultUrl: payload.resultUrl, tenantId: payload.tenantId, secret, result });
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolsResource = exports.SecretsResource = exports.ConnectorsResource = exports.ChatResource = exports.AgentsResource = exports.verifyToolCallbackSignature = exports.signToolCallbackPayload = exports.ToolCallbackSignatureError = exports.TOOL_CALLBACK_HEADERS = exports.AgentForgeNetworkError = exports.AgentForgeNotFoundError = exports.AgentForgeAuthError = exports.AgentForgeError = exports.AgentForgeClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "AgentForgeClient", { enumerable: true, get: function () { return client_1.AgentForgeClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AgentForgeError", { enumerable: true, get: function () { return errors_1.AgentForgeError; } });
+Object.defineProperty(exports, "AgentForgeAuthError", { enumerable: true, get: function () { return errors_1.AgentForgeAuthError; } });
+Object.defineProperty(exports, "AgentForgeNotFoundError", { enumerable: true, get: function () { return errors_1.AgentForgeNotFoundError; } });
+Object.defineProperty(exports, "AgentForgeNetworkError", { enumerable: true, get: function () { return errors_1.AgentForgeNetworkError; } });
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "TOOL_CALLBACK_HEADERS", { enumerable: true, get: function () { return webhooks_1.TOOL_CALLBACK_HEADERS; } });
+Object.defineProperty(exports, "ToolCallbackSignatureError", { enumerable: true, get: function () { return webhooks_1.ToolCallbackSignatureError; } });
+Object.defineProperty(exports, "signToolCallbackPayload", { enumerable: true, get: function () { return webhooks_1.signToolCallbackPayload; } });
+Object.defineProperty(exports, "verifyToolCallbackSignature", { enumerable: true, get: function () { return webhooks_1.verifyToolCallbackSignature; } });
+var agents_1 = require("./resources/agents");
+Object.defineProperty(exports, "AgentsResource", { enumerable: true, get: function () { return agents_1.AgentsResource; } });
+var chat_1 = require("./resources/chat");
+Object.defineProperty(exports, "ChatResource", { enumerable: true, get: function () { return chat_1.ChatResource; } });
+var connectors_1 = require("./resources/connectors");
+Object.defineProperty(exports, "ConnectorsResource", { enumerable: true, get: function () { return connectors_1.ConnectorsResource; } });
+var secrets_1 = require("./resources/secrets");
+Object.defineProperty(exports, "SecretsResource", { enumerable: true, get: function () { return secrets_1.SecretsResource; } });
+var tools_1 = require("./resources/tools");
+Object.defineProperty(exports, "ToolsResource", { enumerable: true, get: function () { return tools_1.ToolsResource; } });

package/dist/resources/agents.d.ts

@@ -0,0 +1,88 @@
+import type { AgentForgeClient } from '../client';
+import type { AgentMe, AgentSummary, ChatTokenRecord, CreateAgentInput, IssueChatTokenInput, ListAgentsResult, RegisterToolsInput, RegisterToolsResult, UpdateAgentInput } from '../types';
+export declare class AgentsResource {
+    private readonly client;
+    constructor(client: AgentForgeClient);
+    /**
+     * Devuelve la configuración del agente al que está scoped el ChatToken/key.
+     *
+     * Para ChatToken: el agent al que fue emitido.
+     * Para ak_live_ agent-scoped: el agent_id de la api key.
+     * Para ak_live_ tenant-wide: 403 (no aplica a /agents/me).
+     *
+     * @example
+     *   const agent = await af.agents.me();
+     *   const prompt = agent.systemPrompt;
+     */
+    me(): Promise<AgentMe>;
+    /**
+     * Declara el set completo de tools custom para el agente.
+     *
+     * Política **last-writer-wins**: las tools del set anterior que no estén
+     * en el nuevo set quedan inactive (preservadas para auditoría). Para
+     * "borrar todas" pasa `{ tools: [] }`.
+     *
+     * El platform NO ejecuta estas tools — la app cliente las corre in-process.
+     * El platform solo persiste la declaración para visibilidad y auditoría.
+     *
+     * @example
+     *   await af.agents.registerTools({
+     *     tools: [{
+     *       name: 'lookup_sop',
+     *       description: 'Busca en SOPs aprobados',
+     *       inputSchema: { type: 'object', properties: { ... }, required: [...] },
+     *     }],
+     *   });
+     */
+    registerTools(input: RegisterToolsInput): Promise<RegisterToolsResult>;
+    /**
+     * Lista los agents del tenant del ak_live_.
+     *
+     * @example
+     *   const { items, total } = await af.agents.list({ limit: 100 });
+     */
+    list(opts?: {
+        limit?: number;
+    }): Promise<ListAgentsResult>;
+    /**
+     * Crea un agent en el tenant del ak_live_.
+     *
+     * `slug` debe ser único por tenant (el server responde 409 si choca).
+     */
+    create(input: CreateAgentInput): Promise<AgentSummary>;
+    /**
+     * Devuelve un agent por id. 404 si no existe o no pertenece al tenant.
+     */
+    get(agentId: string): Promise<AgentSummary>;
+    /**
+     * Actualización parcial. Solo los campos definidos en `patch` se modifican.
+     */
+    update(agentId: string, patch: UpdateAgentInput): Promise<AgentSummary>;
+    /**
+     * Emite un ChatToken nuevo para `agentId`. El token recién emitido es la
+     * credencial que el widget chat (o el SDK del cliente) usa como
+     * `X-Chat-Token` para hablar con la plataforma.
+     *
+     * `allowedOrigins` vacío = acepta cualquier Origin. En producción siempre
+     * pasa la lista explícita de dominios donde se embebe el widget.
+     *
+     * @example
+     *   const t = await af.agents.issueChatToken('agent_123', {
+     *     name: 'Production homepage',
+     *     allowedOrigins: ['https://app.example.com'],
+     *   });
+     *   // t.token → guardar como ChatToken del widget.
+     */
+    issueChatToken(agentId: string, input?: IssueChatTokenInput): Promise<ChatTokenRecord>;
+    /**
+     * Lista todos los ChatTokens activos del agent.
+     */
+    listChatTokens(agentId: string): Promise<{
+        items: ChatTokenRecord[];
+    }>;
+    /**
+     * Desactiva un ChatToken por su valor opaco. El widget que lo tenga
+     * cacheado empezará a recibir 401 en el siguiente request.
+     */
+    revokeChatToken(agentId: string, token: string): Promise<void>;
+}

package/dist/resources/agents.js

@@ -0,0 +1,119 @@
+"use strict";
+// agents resource — wrappers sobre los endpoints /api/v1/agents*.
+//
+// Dos superficies coexisten:
+//   - "self" (`me()`, `registerTools()`): auth con ChatToken o ak_live_
+//     agent-scoped. El SDK resuelve el agent del token y solo expone esa
+//     identidad. Usado por apps que ya saben qué agent representan.
+//   - "admin" (`list()`, `create()`, `update()`, `get()`, `issueChatToken()`):
+//     auth con ak_live_ tenant-wide. Permite a apps server-side gestionar
+//     todos los agents del tenant. Aquí ChatToken NO funciona — el endpoint
+//     responde 401/403 si el cliente solo tiene ChatToken.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentsResource = void 0;
+class AgentsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Devuelve la configuración del agente al que está scoped el ChatToken/key.
+     *
+     * Para ChatToken: el agent al que fue emitido.
+     * Para ak_live_ agent-scoped: el agent_id de la api key.
+     * Para ak_live_ tenant-wide: 403 (no aplica a /agents/me).
+     *
+     * @example
+     *   const agent = await af.agents.me();
+     *   const prompt = agent.systemPrompt;
+     */
+    async me() {
+        return this.client.request('GET', '/api/v1/agents/me');
+    }
+    /**
+     * Declara el set completo de tools custom para el agente.
+     *
+     * Política **last-writer-wins**: las tools del set anterior que no estén
+     * en el nuevo set quedan inactive (preservadas para auditoría). Para
+     * "borrar todas" pasa `{ tools: [] }`.
+     *
+     * El platform NO ejecuta estas tools — la app cliente las corre in-process.
+     * El platform solo persiste la declaración para visibilidad y auditoría.
+     *
+     * @example
+     *   await af.agents.registerTools({
+     *     tools: [{
+     *       name: 'lookup_sop',
+     *       description: 'Busca en SOPs aprobados',
+     *       inputSchema: { type: 'object', properties: { ... }, required: [...] },
+     *     }],
+     *   });
+     */
+    async registerTools(input) {
+        return this.client.request('POST', '/api/v1/agents/me/tools', input);
+    }
+    // ────────────────────────────────────────────────────────────────────────
+    // Admin (requiere ak_live_ tenant-wide).
+    // ────────────────────────────────────────────────────────────────────────
+    /**
+     * Lista los agents del tenant del ak_live_.
+     *
+     * @example
+     *   const { items, total } = await af.agents.list({ limit: 100 });
+     */
+    async list(opts) {
+        const qs = opts?.limit !== undefined ? `?limit=${encodeURIComponent(opts.limit)}` : '';
+        return this.client.request('GET', `/api/v1/agents${qs}`);
+    }
+    /**
+     * Crea un agent en el tenant del ak_live_.
+     *
+     * `slug` debe ser único por tenant (el server responde 409 si choca).
+     */
+    async create(input) {
+        return this.client.request('POST', '/api/v1/agents', input);
+    }
+    /**
+     * Devuelve un agent por id. 404 si no existe o no pertenece al tenant.
+     */
+    async get(agentId) {
+        return this.client.request('GET', `/api/v1/agents/${encodeURIComponent(agentId)}`);
+    }
+    /**
+     * Actualización parcial. Solo los campos definidos en `patch` se modifican.
+     */
+    async update(agentId, patch) {
+        return this.client.request('PATCH', `/api/v1/agents/${encodeURIComponent(agentId)}`, patch);
+    }
+    /**
+     * Emite un ChatToken nuevo para `agentId`. El token recién emitido es la
+     * credencial que el widget chat (o el SDK del cliente) usa como
+     * `X-Chat-Token` para hablar con la plataforma.
+     *
+     * `allowedOrigins` vacío = acepta cualquier Origin. En producción siempre
+     * pasa la lista explícita de dominios donde se embebe el widget.
+     *
+     * @example
+     *   const t = await af.agents.issueChatToken('agent_123', {
+     *     name: 'Production homepage',
+     *     allowedOrigins: ['https://app.example.com'],
+     *   });
+     *   // t.token → guardar como ChatToken del widget.
+     */
+    async issueChatToken(agentId, input) {
+        return this.client.request('POST', `/api/v1/agents/${encodeURIComponent(agentId)}/chat-tokens`, input ?? {});
+    }
+    /**
+     * Lista todos los ChatTokens activos del agent.
+     */
+    async listChatTokens(agentId) {
+        return this.client.request('GET', `/api/v1/agents/${encodeURIComponent(agentId)}/chat-tokens`);
+    }
+    /**
+     * Desactiva un ChatToken por su valor opaco. El widget que lo tenga
+     * cacheado empezará a recibir 401 en el siguiente request.
+     */
+    async revokeChatToken(agentId, token) {
+        await this.client.request('DELETE', `/api/v1/agents/${encodeURIComponent(agentId)}/chat-tokens/${encodeURIComponent(token)}`);
+    }
+}
+exports.AgentsResource = AgentsResource;

package/dist/resources/chat.d.ts

@@ -0,0 +1,55 @@
+import type { AgentForgeClient } from '../client';
+import type { ChatStreamEvent, ConversationHistory } from '../types';
+export interface AnthropicClientOptions {
+    /** Override de la versión Anthropic. Default: '2023-06-01'. */
+    anthropicVersion?: string;
+}
+export interface StreamMessageInput {
+    content: string;
+    /** Si se omite, el server crea una conversación nueva. */
+    conversationId?: string;
+}
+export declare class ChatResource {
+    private readonly client;
+    constructor(client: AgentForgeClient);
+    /**
+     * Devuelve una instancia de `Anthropic` (de @anthropic-ai/sdk) preconfigurada
+     * para hablar contra el proxy del platform.
+     *
+     * **Pre-req:** la app cliente tiene `@anthropic-ai/sdk` como dep regular y
+     * el `AgentForgeClient` se construyó con `apiKey` (ak_live_) además del
+     * chatToken.
+     *
+     * @example
+     *   const anthropic = await af.chat.createAnthropicClient();
+     *   const msg = await anthropic.messages.create({ ... });
+     */
+    createAnthropicClient(opts?: AnthropicClientOptions): Promise<any>;
+    /**
+     * Chat streaming AGENT-AWARE — `POST /api/v1/chat/messages/stream`. Auth:
+     * ChatToken (scoped al agent). Resuelve connectors del tenant + tools
+     * 'remote' registradas del agent automáticamente; el caller solo manda
+     * `content`.
+     *
+     * Yieldea `ChatStreamEvent` tipados en vez de frames SSE crudos — ver
+     * el tipo para el detalle de cada `kind`.
+     *
+     * @example
+     *   let conversationId: string | undefined;
+     *   for await (const ev of af.chat.streamMessage({ content: 'hola' })) {
+     *     if (ev.kind === 'conversation') conversationId = ev.conversationId;
+     *     else if (ev.kind === 'chunk' && ev.chunk.type === 'text_delta') {
+     *       process.stdout.write(ev.chunk.delta);
+     *     }
+     *   }
+     */
+    streamMessage(input: StreamMessageInput): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * Historial completo de una conversación — `GET
+     * /api/v1/chat/conversations/:id/messages`. Útil para "resumir" un chat
+     * tras un refresh de página cuando el `conversationId` se guardó (ej. en
+     * la URL). Tira `AgentForgeNotFoundError` si la conversación no existe o
+     * no pertenece al ChatToken que llama.
+     */
+    getHistory(conversationId: string): Promise<ConversationHistory>;
+}