@agentforge-io/core 2.0.15 → 2.0.17

package/dist/domain/connector.d.ts

@@ -28,11 +28,45 @@ export interface ConnectorToolFactory {
     definition: Omit<AgentToolDefinition, 'execute'>;
     build: (ctx: ConnectorToolContext) => AgentToolDefinition['execute'];
 }
+/**
+ * UI hints for connectors that authenticate via a user-pasted API key
+ * instead of the OAuth2 dance (Granola — and any future provider whose
+ * vendor doesn't ship OAuth for third-party apps).
+ *
+ * The runtime never reads these fields itself; they exist so the host's
+ * directory UI can render a sensible "Paste your key" panel without
+ * hard-coding per-provider copy. `expectedPrefix` is also used by the
+ * registry as a cheap sanity check before persisting — a key that doesn't
+ * start with `grn_` is almost certainly a paste mistake.
+ */
+export interface ApiKeyAuthConfig {
+    /** URL to the provider's docs page that explains where the user generates
+     *  the API key (e.g. Granola's Settings → Connectors → API keys). Shown
+     *  as a "Where do I get this?" link in the UI. */
+    instructionsUrl?: string;
+    /** Placeholder text shown inside the input field. */
+    placeholder?: string;
+    /** If set, the registry rejects keys that don't start with this prefix —
+     *  Granola's keys are `grn_…`, so a paste that doesn't start that way is
+     *  almost always a wrong copy. Skip the check by leaving this undefined. */
+    expectedPrefix?: string;
+}
 /**
  * Static connector definition. Lives in code (option 1 from the design
  * discussion): one of these per supported provider, registered into the
  * `ConnectorRegistry` at boot. The host wires `clientId` / `clientSecret`
  * from env into the `oauth` config before registering.
+ *
+ * Connectors come in two auth flavors:
+ *
+ *   - **OAuth2** (Google, Slack, Notion, …) — set `oauth`. The registry
+ *     drives the authorize → exchange → refresh dance.
+ *   - **API key** (Granola, …) — set `apiKey`. The user pastes their key
+ *     into the UI; the registry persists it via the same encrypted column
+ *     as an OAuth access token (no refresh, no expiry).
+ *
+ * Exactly one of `oauth` / `apiKey` must be present. The registry throws
+ * on `register()` if both are set or neither is.
  */
 export interface ConnectorDefinition {
     /** Stable slug used in URLs and the DB (`google`, `slack`, …). */
@@ -45,7 +79,10 @@ export interface ConnectorDefinition {
     category?: string;
     /** Optional URL of a logo asset served by the host. */
     iconUrl?: string;
-    oauth: OAuth2ProviderConfig;
+    /** OAuth2 connector config. Exactly one of `oauth` / `apiKey` is set. */
+    oauth?: OAuth2ProviderConfig;
+    /** API-key connector config. Exactly one of `oauth` / `apiKey` is set. */
+    apiKey?: ApiKeyAuthConfig;
     /** Tools this connector contributes to the agent's toolbelt once a user
      *  has authorized. */
     tools: ConnectorToolFactory[];

package/dist/domain/conversation.d.ts

@@ -24,3 +24,25 @@ export interface Message {
 }
 export type NewConversation = Pick<Conversation, 'userId' | 'agentId'> & Partial<Omit<Conversation, 'id' | 'createdAt' | 'updatedAt'>>;
 export type NewMessage = Omit<Message, 'id' | 'createdAt'>;
+/**
+ * Minimal payload for the agent-editor's conversation sidebar. The full
+ * `Conversation + messages[]` is too heavy to ship for 50 rows; this
+ * shape carries the bare minimum the UI needs to render a row and
+ * decide which one to load in full.
+ *
+ * `intent` is the first user message of the conversation, truncated to
+ * 120 chars server-side. `null` when the conversation has no user
+ * message yet (rare but possible mid-create).
+ */
+export interface ConversationListItem {
+    id: string;
+    userId: string;
+    agentId: string;
+    status: ConversationStatus;
+    intent: string | null;
+    messageCount: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    createdAt: Date;
+    updatedAt: Date;
+}

package/dist/repositories/in-memory.d.ts

@@ -1,5 +1,5 @@
 import type { ConversationRepository, MessageRepository } from './index';
-import type { Conversation, NewConversation, Message, NewMessage } from '../domain/conversation';
+import type { Conversation, ConversationListItem, NewConversation, Message, NewMessage } from '../domain/conversation';
 import type { ConversationStatus } from '../types/agent.types';
 export declare class InMemoryConversationRepository implements ConversationRepository {
     private byId;
@@ -11,6 +11,13 @@ export declare class InMemoryConversationRepository implements ConversationRepos
         limit?: number;
         offset?: number;
     }): Promise<Conversation[]>;
+    listForAgent(agentId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: ConversationListItem[];
+        totalCount: number;
+    }>;
     updateStats(id: string, patch: {
         status?: ConversationStatus;
         addInputTokens?: number;

package/dist/repositories/in-memory.js

@@ -41,6 +41,32 @@ class InMemoryConversationRepository {
         const end = opts.limit ? start + opts.limit : undefined;
         return items.slice(start, end);
     }
+    async listForAgent(agentId, opts = {}) {
+        // In-memory variant doesn't have access to the message store —
+        // those live in a sibling repo. We return `intent: null` here; the
+        // TypeORM impl is the one that materializes intent from messages.
+        // Good enough for tests + demos that just want to exercise the
+        // listing contract.
+        const all = Array.from(this.byId.values()).filter((c) => c.agentId === agentId);
+        all.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+        const start = opts.offset ?? 0;
+        const end = opts.limit ? start + opts.limit : undefined;
+        return {
+            items: all.slice(start, end).map((c) => ({
+                id: c.id,
+                userId: c.userId,
+                agentId: c.agentId,
+                status: c.status,
+                intent: null,
+                messageCount: c.messageCount,
+                totalInputTokens: c.totalInputTokens,
+                totalOutputTokens: c.totalOutputTokens,
+                createdAt: c.createdAt,
+                updatedAt: c.updatedAt,
+            })),
+            totalCount: all.length,
+        };
+    }
     async updateStats(id, patch) {
         const c = this.byId.get(id);
         if (!c)

package/dist/repositories/index.d.ts

@@ -1,4 +1,4 @@
-import type { Conversation, NewConversation, Message, NewMessage } from '../domain/conversation';
+import type { Conversation, ConversationListItem, NewConversation, Message, NewMessage } from '../domain/conversation';
 import type { ChatToken, NewChatToken, ChatTokenPatch } from '../domain/chat-token';
 import type { McpServerRecord, NewMcpServerRecord, McpServerRecordPatch } from '../domain/mcp-server';
 import type { ConnectorAuth, NewConnectorAuth, ConnectorAuthPatch } from '../domain/connector-auth';
@@ -22,6 +22,26 @@ export interface ConversationRepository {
         limit?: number;
         offset?: number;
     }): Promise<Conversation[]>;
+    /**
+     * List every conversation an agent has had, regardless of user. Used by
+     * the agent-editor's "Conversations" panel — operators need visibility
+     * into all traffic the agent saw, not just their own.
+     *
+     * Tenant scoping is enforced one layer up (host service), since the SDK
+     * doesn't carry tenant context. Pass `agentId` only after verifying it
+     * belongs to the caller's tenant.
+     *
+     * The optional `intent` field on each item is the first user message's
+     * content, truncated to 120 chars — server-side so the wire payload
+     * stays small (the list is for a sidebar, not for replaying messages).
+     */
+    listForAgent(agentId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: ConversationListItem[];
+        totalCount: number;
+    }>;
     updateStats(id: string, patch: {
         status?: ConversationStatus;
         addInputTokens?: number;

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

@@ -5,7 +5,7 @@ import type { ToolRegistryService } from './tool-registry.service';
 import type { AgentToolDefinition } from '../types';
 export declare class ConnectorError extends Error {
     status: number;
-    code: 'unknown_connector' | 'not_connected' | 'not_configured' | 'invalid_state' | 'token_exchange_failed';
+    code: 'unknown_connector' | 'not_connected' | 'not_configured' | 'invalid_state' | 'token_exchange_failed' | 'invalid_api_key' | 'wrong_auth_kind';
     constructor(code: ConnectorError['code'], message: string);
 }
 /**
@@ -141,6 +141,19 @@ export declare class ConnectorRegistryService {
         connectorId: string;
         userId: string;
     }>;
+    /**
+     * Persist a user-pasted API key as the connector credential for `userId`.
+     * Replaces any existing row (so reconnecting with a fresh key just works).
+     *
+     * The key is treated exactly like an OAuth access token from this point
+     * on: encrypted at rest via the same cipher, never expires (no refresh
+     * dance), and surfaced through `getAccessToken` for tool calls.
+     *
+     * Validation here is intentionally minimal — prefix check + non-empty. A
+     * provider ping ("does this key actually work?") belongs in the
+     * controller, where the per-connector HTTP client lives.
+     */
+    saveApiKey(connectorId: string, userId: string, apiKey: string): Promise<void>;
     listForUser(userId: string): Promise<ConnectorStatus[]>;
     disconnect(userId: string, connectorId: string): Promise<void>;
     /**

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

@@ -70,6 +70,15 @@ class ConnectorRegistryService {
         if (this.defs.has(def.id)) {
             throw new Error(`Connector "${def.id}" already registered`);
         }
+        // Exactly one auth flavor. Catching this at register-time avoids
+        // confusing runtime errors deep inside startAuthorize / saveApiKey when
+        // the wrong branch is taken on a half-built def.
+        const hasOauth = !!def.oauth;
+        const hasApiKey = !!def.apiKey;
+        if (hasOauth === hasApiKey) {
+            throw new Error(`Connector "${def.id}" must declare exactly one of \`oauth\` or \`apiKey\`` +
+                ` (got ${hasOauth ? 'both' : 'neither'}).`);
+        }
         this.defs.set(def.id, def);
     }
     /**
@@ -118,6 +127,14 @@ class ConnectorRegistryService {
     // ─── OAuth flow ──────────────────────────────────────────────────────────
     async startAuthorize(connectorId, userId, redirectUri) {
         const def = this.get(connectorId);
+        if (!def.oauth) {
+            // API-key connectors don't run an OAuth dance. The controller is
+            // expected to route the request to `saveApiKey` instead — surface a
+            // distinct error code so the UI can render the right panel rather
+            // than retrying authorize.
+            throw new ConnectorError('wrong_auth_kind', `Connector "${connectorId}" authenticates with an API key, not OAuth. ` +
+                `Use POST /connectors/oauth/${connectorId}/api-key instead.`);
+        }
         if (!this.configured.has(connectorId)) {
             throw new ConnectorError('not_configured', `Connector "${connectorId}" is not configured — the operator must ` +
                 `set its OAuth credentials before users can connect.`);
@@ -144,6 +161,14 @@ class ConnectorRegistryService {
             throw new ConnectorError('invalid_state', 'OAuth state is unknown or expired');
         }
         const def = this.get(ctx.connectorId);
+        if (!def.oauth) {
+            // Belt + suspenders. `startAuthorize` already gates on this, but if
+            // an operator swapped an OAuth connector for an API-key one between
+            // the authorize redirect and the callback, the state would still be
+            // valid and we'd crash here. Fail loud.
+            throw new ConnectorError('wrong_auth_kind', `Connector "${ctx.connectorId}" no longer uses OAuth — the user must ` +
+                `re-connect using the API key flow.`);
+        }
         let tokens;
         try {
             tokens = await this.deps.oauth.exchangeCode(def.oauth, code, redirectUri, ctx.pkceVerifier);
@@ -154,6 +179,36 @@ class ConnectorRegistryService {
         await this.upsertAuth(ctx.userId, ctx.connectorId, tokens);
         return { connectorId: ctx.connectorId, userId: ctx.userId };
     }
+    // ─── API-key flow ────────────────────────────────────────────────────────
+    /**
+     * Persist a user-pasted API key as the connector credential for `userId`.
+     * Replaces any existing row (so reconnecting with a fresh key just works).
+     *
+     * The key is treated exactly like an OAuth access token from this point
+     * on: encrypted at rest via the same cipher, never expires (no refresh
+     * dance), and surfaced through `getAccessToken` for tool calls.
+     *
+     * Validation here is intentionally minimal — prefix check + non-empty. A
+     * provider ping ("does this key actually work?") belongs in the
+     * controller, where the per-connector HTTP client lives.
+     */
+    async saveApiKey(connectorId, userId, apiKey) {
+        const def = this.get(connectorId);
+        if (!def.apiKey) {
+            throw new ConnectorError('wrong_auth_kind', `Connector "${connectorId}" authenticates with OAuth, not an API key.`);
+        }
+        const trimmed = apiKey.trim();
+        if (!trimmed) {
+            throw new ConnectorError('invalid_api_key', 'API key is empty.');
+        }
+        if (def.apiKey.expectedPrefix && !trimmed.startsWith(def.apiKey.expectedPrefix)) {
+            throw new ConnectorError('invalid_api_key', `API key for "${connectorId}" must start with "${def.apiKey.expectedPrefix}".`);
+        }
+        // Synthesize a TokenSet so upsertAuth can be reused unchanged. No
+        // expiresIn, no refreshToken — same shape as a long-lived OAuth token
+        // (ClickUp, Slack, GitHub, Notion).
+        await this.upsertAuth(userId, connectorId, { accessToken: trimmed });
+    }
     // ─── Per-user listing ────────────────────────────────────────────────────
     async listForUser(userId) {
         const authed = await this.deps.authRepo.listForUser(userId);
@@ -285,6 +340,13 @@ class ConnectorRegistryService {
             throw new ConnectorError('not_connected', `Token for ${a.connectorId} expired and no refresh token is available; user must re-authorize`);
         }
         const def = this.get(a.connectorId);
+        if (!def.oauth) {
+            // Unreachable in practice: api-key connectors never persist a
+            // refresh token, so the earlier `!a.refreshTokenEncrypted` branch
+            // would have caught this. Belt + suspenders for the type checker
+            // and for the case where someone manually inserts a row.
+            throw new ConnectorError('wrong_auth_kind', `Connector "${a.connectorId}" uses API-key auth; cannot refresh.`);
+        }
         const refreshPlain = this.deps.cipher.decrypt(a.refreshTokenEncrypted);
         const fresh = await this.deps.oauth.refresh(def.oauth, refreshPlain);
         const expiresAt = fresh.expiresIn

package/package.json

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