plugin-paperclip-personal-openia-adapter 0.1.3 → 0.1.5

package/README.md

@@ -21,13 +21,14 @@ npm i plugin-paperclip-personal-openia-adapter
 | `baseUrl` | Base URL of the OpenAI gateway   | `https://api.openai.com/v1`  | Base endpoint address (e.g., https://example.com/v1) |
 | `apiKey`  | API Key                          | –                            | Access key for the gateway (secret field) |
 | `model`   | Model name                       | `gpt-4o`                     | Identifier of the model to be used |
+| `promptTemplate` | Prompt template | – | Optional. Supports `{{agent.name}}`, `{{agent.id}}`, `{{context.prompt}}`, `{{context.task}}`, and `{{context}}`. |
 
 ## How it works
 
-1. Paperclip calls the `handleChat` function with the user's messages.
-2. The adapter constructs a **POST** request to `${baseUrl}/chat/completions`.
+1. Paperclip calls the adapter's `execute()` with the agent and wake context.
+2. The adapter sends that context to `${baseUrl}/chat/completions` as an OpenAI-compatible chat request.
 3. The request includes the header `Authorization: Bearer <apiKey>`.
-4. The response returns the content of `choices[0].message.content`.
+4. The response content is returned as the Paperclip run summary and stdout log.
 5. In case of error, friendly messages are generated without mentioning specific providers.
 
 ---
@@ -49,13 +50,14 @@ npm i plugin-paperclip-personal-openia-adapter
 | `baseUrl`  | Base URL do gateway OpenAI | `https://api.openai.com/v1` | Endereço base do endpoint (ex.: https://example.com/v1) |
 | `apiKey`   | API Key              | –                           | Chave de acesso ao gateway (campo secreto)          |
 | `model`    | Nome do Modelo       | `gpt-4o`                    | Identificador do modelo a ser usado                 |
+| `promptTemplate` | Template do prompt | – | Opcional. Aceita `{{agent.name}}`, `{{agent.id}}`, `{{context.prompt}}`, `{{context.task}}` e `{{context}}`. |
 
 ## Como funciona
 
-1. O Paperclip chama a função `handleChat` passando as mensagens do usuário.
-2. O adapter monta a requisição **POST** para `${baseUrl}/chat/completions`.
+1. O Paperclip chama `execute()` com o agente e o contexto do heartbeat.
+2. O adapter envia esse contexto para `${baseUrl}/chat/completions` usando o formato OpenAI-compatible.
 3. A requisição inclui o cabeçalho `Authorization: Bearer <apiKey>`.
-4. A resposta é retornada como o conteúdo de `choices[0].message.content`.
+4. O conteúdo da resposta é devolvido como resumo da execução e log stdout do Paperclip.
 5. Em caso de erro, mensagens amigáveis são geradas sem citar provedores específicos.
 
 ---

package/dist/index.d.ts

@@ -5,13 +5,17 @@
  * OpenAI‑compatible endpoint, therefore error messages refer only to the
  * generic gateway and not to a specific provider such as "9route".
  */
-import { Adapter, ConfigField } from '@paperclip/sdk';
+import type { ConfigField, ServerAdapterModule } from './paperclip-types.js';
 /** ------------------------------------------------------------
  * 1️⃣ CONFIGURATION SCHEMA (UI displayed in Paperclip)
  * ------------------------------------------------------------ */
 export declare const configSchema: ConfigField[];
-/** ------------------------------------------------------------
- * 3️⃣ EXPORT ADAPTER FUNCTION
- * ------------------------------------------------------------ */
-export declare function createServerAdapter(): Adapter;
+export declare const type = "openai_compatible_personal";
+export declare const label = "OpenAI-compatible (personal)";
+export declare const models: {
+    id: string;
+    label: string;
+}[];
+export declare const agentConfigurationDoc = "# OpenAI-compatible (personal)\n\nCalls an OpenAI-compatible chat completions endpoint for each Paperclip run.\n\nConfigure baseUrl, apiKey, and model in the adapter configuration. The adapter sends the Paperclip wake context as the user message and returns the model response as the run summary. This adapter does not provide tools or directly modify Paperclip tasks.";
+export declare function createServerAdapter(): ServerAdapterModule;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,OAAO,EAIP,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAExB;;kEAEkE;AAClE,eAAO,MAAM,YAAY,EAAE,WAAW,EAyBrC,CAAC;AAyDF;;kEAEkE;AAClE,wBAAgB,mBAAmB,IAAI,OAAO,CAM7C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAKV,WAAW,EACX,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B;;kEAEkE;AAClE,eAAO,MAAM,YAAY,EAAE,WAAW,EAgCrC,CAAC;AAEF,eAAO,MAAM,IAAI,+BAA+B,CAAC;AACjD,eAAO,MAAM,KAAK,iCAAiC,CAAC;AACpD,eAAO,MAAM,MAAM;;;GAA+D,CAAC;AACnF,eAAO,MAAM,qBAAqB,qXAAqX,CAAC;AAmJxZ,wBAAgB,mBAAmB,IAAI,mBAAmB,CAEzD"}

package/dist/index.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * External Adapter – OpenAI compatible (e.g., 9route)
  *
@@ -6,17 +5,11 @@
  * OpenAI‑compatible endpoint, therefore error messages refer only to the
  * generic gateway and not to a specific provider such as "9route".
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.configSchema = void 0;
-exports.createServerAdapter = createServerAdapter;
-const axios_1 = __importDefault(require("axios"));
+import axios from 'axios';
 /** ------------------------------------------------------------
  * 1️⃣ CONFIGURATION SCHEMA (UI displayed in Paperclip)
  * ------------------------------------------------------------ */
-exports.configSchema = [
+export const configSchema = [
     {
         key: 'baseUrl',
         type: 'string',
@@ -41,64 +34,144 @@ exports.configSchema = [
         placeholder: 'gpt-4o',
         description: 'Identificador do modelo a ser usado.',
     },
+    {
+        key: 'promptTemplate',
+        type: 'string',
+        label: 'Template do prompt',
+        placeholder: 'Atenda esta solicitação: {{context.prompt}}',
+        description: 'Opcional. Use {{agent.name}}, {{agent.id}}, {{context.prompt}}, {{context.task}} ou {{context}}.',
+    },
 ];
-/** ------------------------------------------------------------
- * 2️⃣ CHAT REQUEST HANDLER
- * ------------------------------------------------------------ */
-async function handleChat(config, request) {
-    // Ensure the base URL does not end with a slash before appending the path
-    const url = `${config.baseUrl?.replace(/\/+$/, '')}/chat/completions`;
-    const payload = {
-        model: config.model ?? 'gpt-4o',
-        messages: request.messages,
-        temperature: request.options?.temperature ?? 0.7,
-        top_p: request.options?.top_p ?? 1,
-    };
+export const type = 'openai_compatible_personal';
+export const label = 'OpenAI-compatible (personal)';
+export const models = [{ id: 'gpt-4o', label: 'Gateway model (default: gpt-4o)' }];
+export const agentConfigurationDoc = `# OpenAI-compatible (personal)\n\nCalls an OpenAI-compatible chat completions endpoint for each Paperclip run.\n\nConfigure baseUrl, apiKey, and model in the adapter configuration. The adapter sends the Paperclip wake context as the user message and returns the model response as the run summary. This adapter does not provide tools or directly modify Paperclip tasks.`;
+function readConfig(config) {
+    return config;
+}
+function getConnection(config) {
+    const baseUrl = typeof config.baseUrl === 'string' ? config.baseUrl.trim().replace(/\/+$/, '') : '';
+    const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : '';
+    const model = typeof config.model === 'string' && config.model.trim() ? config.model.trim() : 'gpt-4o';
+    if (!baseUrl)
+        throw new Error('Informe a Base URL do gateway OpenAI-compatible.');
+    if (!apiKey)
+        throw new Error('Informe a API Key do gateway.');
     try {
-        const resp = await axios_1.default.post(url, payload, {
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${config.apiKey}`,
-            },
-            timeout: 30_000,
+        new URL(baseUrl);
+    }
+    catch {
+        throw new Error('A Base URL precisa ser uma URL válida, incluindo https:// ou http://.');
+    }
+    return { baseUrl, apiKey, model };
+}
+function friendlyError(err) {
+    if (!axios.isAxiosError(err))
+        return err instanceof Error ? err.message : 'Erro desconhecido ao executar o adapter.';
+    const axiosErr = err;
+    const status = axiosErr.response?.status;
+    if (status === 401 || status === 403)
+        return `Credenciais inválidas ou sem permissão (${status}).`;
+    if (status === 404)
+        return 'Endpoint não encontrado (404). Confira a Base URL do gateway.';
+    if (status && status >= 500)
+        return `Erro interno do gateway (${status}).`;
+    return axiosErr.response?.data?.error?.message ?? axiosErr.message ?? 'Erro ao comunicar com o gateway OpenAI-compatible.';
+}
+function getPrompt(ctx) {
+    const wakeContext = ctx.context ?? {};
+    const prompt = wakeContext.prompt;
+    const task = wakeContext.task;
+    const taskText = typeof task === 'string' ? task : task ? JSON.stringify(task, null, 2) : '';
+    const fallback = typeof prompt === 'string' && prompt.trim()
+        ? prompt.trim()
+        : taskText || JSON.stringify(wakeContext, null, 2);
+    const template = ctx.config.promptTemplate;
+    if (typeof template !== 'string' || !template.trim())
+        return fallback;
+    return template
+        .split('{{agent.id}}').join(ctx.agent.id)
+        .split('{{agent.name}}').join(ctx.agent.name)
+        .split('{{context.prompt}}').join(typeof prompt === 'string' ? prompt : '')
+        .split('{{context.task}}').join(taskText)
+        .split('{{context}}').join(JSON.stringify(wakeContext, null, 2));
+}
+async function callGateway(config, messages) {
+    const { baseUrl, apiKey, model } = getConnection(config);
+    const response = await axios.post(`${baseUrl}/chat/completions`, {
+        model,
+        messages,
+        temperature: typeof config.temperature === 'number' ? config.temperature : 0.7,
+        top_p: typeof config.top_p === 'number' ? config.top_p : 1,
+    }, {
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+        timeout: 120000,
+    });
+    const content = response.data?.choices?.[0]?.message?.content;
+    if (typeof content !== 'string' || !content.trim()) {
+        throw new Error('Resposta inesperada do gateway: choices[0].message.content está ausente ou vazia.');
+    }
+    return { content, response: response.data, requestedModel: model };
+}
+async function execute(ctx) {
+    const config = readConfig(ctx.config);
+    const prompt = getPrompt(ctx);
+    const messages = [
+        {
+            role: 'system',
+            content: `Você é o agente ${ctx.agent.name} do Paperclip. Responda ao contexto da execução de forma útil e objetiva.`,
+        },
+        { role: 'user', content: prompt },
+    ];
+    try {
+        const result = await callGateway(config, messages);
+        await ctx.onLog('stdout', `${result.content}\n`);
+        return {
+            exitCode: 0,
+            signal: null,
+            timedOut: false,
+            summary: result.content,
+            model: result.response.model ?? result.requestedModel,
+            provider: 'openai-compatible',
+            usage: result.response.usage ? {
+                inputTokens: result.response.usage.prompt_tokens ?? 0,
+                outputTokens: result.response.usage.completion_tokens ?? 0,
+            } : undefined,
+        };
+    }
+    catch (err) {
+        const message = friendlyError(err);
+        await ctx.onLog('stderr', `${message}\n`);
+        return { exitCode: 1, signal: null, timedOut: false, errorMessage: message, model: config.model };
+    }
+}
+async function testEnvironment(ctx) {
+    const config = readConfig(ctx.config);
+    const testedAt = new Date().toISOString();
+    try {
+        const { baseUrl, apiKey, model } = getConnection(config);
+        await axios.get(`${baseUrl}/models`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+            timeout: 15000,
         });
-        const choice = resp.data?.choices?.[0];
-        if (!choice?.message?.content) {
-            throw new Error('Resposta inesperada da API OpenAI‑compatible.');
-        }
-        return { content: choice.message.content };
+        return {
+            adapterType: ctx.adapterType,
+            status: 'pass',
+            checks: [{ level: 'info', code: 'gateway_reachable', message: `Gateway acessível; modelo configurado: ${model}.` }],
+            testedAt,
+        };
     }
     catch (err) {
-        // -------- Friendly generic error handling --------
-        if (axios_1.default.isAxiosError(err)) {
-            const axiosErr = err;
-            const status = axiosErr.response?.status;
-            const data = axiosErr.response?.data;
-            let friendlyMsg = 'Erro ao comunicar com o gateway OpenAI‑compatible.';
-            if (status === 401)
-                friendlyMsg = 'Credenciais inválidas (401).';
-            else if (status === 404)
-                friendlyMsg = 'Endpoint não encontrado (404).';
-            else if (status && status >= 500)
-                friendlyMsg = 'Erro interno do servidor (5xx).';
-            else if (data && typeof data === 'object' && 'error' in data) {
-                // OpenAI‑style error payload
-                friendlyMsg = `Gateway error: ${data.error?.message ?? friendlyMsg}`;
-            }
-            throw new Error(friendlyMsg);
-        }
-        // Non‑HTTP errors
-        throw err;
+        const message = friendlyError(err);
+        return {
+            adapterType: ctx.adapterType,
+            status: 'fail',
+            checks: [{ level: 'error', code: 'gateway_check_failed', message, hint: 'Confira a Base URL, a API Key e se o gateway oferece GET /models.' }],
+            testedAt,
+        };
     }
 }
-/** ------------------------------------------------------------
- * 3️⃣ EXPORT ADAPTER FUNCTION
- * ------------------------------------------------------------ */
-function createServerAdapter() {
-    return {
-        name: 'OpenAI‑compatible Adapter (personal)',
-        configSchema: exports.configSchema,
-        handleChat,
-    };
+export function createServerAdapter() {
+    return { type, label, models, agentConfigurationDoc, configSchema, execute, testEnvironment };
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/paperclip-types.d.ts

@@ -0,0 +1,66 @@
+export interface ConfigField {
+    key: string;
+    type: string;
+    label: string;
+    default?: unknown;
+    placeholder?: string;
+    description?: string;
+    secret?: boolean;
+}
+export interface AdapterExecutionContext {
+    runId: string;
+    agent: {
+        id: string;
+        companyId: string;
+        name: string;
+        adapterConfig: unknown;
+    };
+    runtime: {
+        sessionId: string | null;
+        sessionParams: Record<string, unknown> | null;
+    };
+    config: Record<string, unknown>;
+    context: Record<string, any>;
+    onLog: (stream: 'stdout' | 'stderr', chunk: string) => Promise<void>;
+}
+export interface AdapterExecutionResult {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    errorMessage?: string | null;
+    summary?: string | null;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    provider?: string | null;
+    model?: string | null;
+}
+export interface AdapterEnvironmentTestContext {
+    adapterType: string;
+    config: Record<string, unknown>;
+}
+export interface AdapterEnvironmentTestResult {
+    adapterType: string;
+    status: 'pass' | 'warn' | 'fail';
+    checks: Array<{
+        level: 'info' | 'warn' | 'error';
+        code: string;
+        message: string;
+        hint?: string;
+    }>;
+    testedAt: string;
+}
+export interface ServerAdapterModule {
+    type: string;
+    label?: string;
+    models: Array<{
+        id: string;
+        label: string;
+    }>;
+    agentConfigurationDoc: string;
+    configSchema: ConfigField[];
+    execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
+    testEnvironment(ctx: AdapterEnvironmentTestContext): Promise<AdapterEnvironmentTestResult>;
+}
+//# sourceMappingURL=paperclip-types.d.ts.map

package/dist/paperclip-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-types.d.ts","sourceRoot":"","sources":["../src/paperclip-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/E,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;IACrF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,MAAM,EAAE,KAAK,CAAC;QACZ,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,OAAO,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACvE,eAAe,CAAC,GAAG,EAAE,6BAA6B,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;CAC5F"}

package/dist/paperclip-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=paperclip-types.js.map

package/dist/paperclip-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-types.js","sourceRoot":"","sources":["../src/paperclip-types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-paperclip-personal-openia-adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "External adapter for Paperclip AI that connects to an OpenAI‑compatible gateway (e.g., 9route).",
   "keywords": [
     "paperclip",
@@ -19,8 +19,16 @@
   "homepage": "https://github.com/GlebsonS4ntos/plugin-paperclip-personal-openia-adapter#readme",
   "author": "Glebson Santos <glebsonsantos@outlook.pt>",
   "license": "MIT",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "files": [
     "dist",
     "src",
@@ -34,16 +42,7 @@
   "dependencies": {
     "axios": "^1.7.2"
   },
-  "peerDependencies": {
-    "@paperclip/sdk": "^1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@paperclip/sdk": {
-      "optional": true
-    }
-  },
   "devDependencies": {
-    "@paperclip/sdk": "file:./sdk",
     "typescript": "^5.5.4",
     "rimraf": "^5.0.5"
   }

package/src/index.ts

@@ -7,13 +7,14 @@
  */
 
 import axios, { AxiosError } from 'axios';
-import {
-  Adapter,
-  AdapterConfig,
-  ChatRequest,
-  ChatResponse,
+import type {
+  AdapterEnvironmentTestContext,
+  AdapterEnvironmentTestResult,
+  AdapterExecutionContext,
+  AdapterExecutionResult,
   ConfigField,
-} from '@paperclip/sdk';
+  ServerAdapterModule,
+} from './paperclip-types.js';
 
 /** ------------------------------------------------------------
  * 1️⃣ CONFIGURATION SCHEMA (UI displayed in Paperclip)
@@ -43,70 +44,165 @@ export const configSchema: ConfigField[] = [
     placeholder: 'gpt-4o',
     description: 'Identificador do modelo a ser usado.',
   },
+  {
+    key: 'promptTemplate',
+    type: 'string',
+    label: 'Template do prompt',
+    placeholder: 'Atenda esta solicitação: {{context.prompt}}',
+    description: 'Opcional. Use {{agent.name}}, {{agent.id}}, {{context.prompt}}, {{context.task}} ou {{context}}.',
+  },
 ];
 
-/** ------------------------------------------------------------
- * 2️⃣ CHAT REQUEST HANDLER
- * ------------------------------------------------------------ */
-async function handleChat(
-  config: AdapterConfig,
-  request: ChatRequest
-): Promise<ChatResponse> {
-  // Ensure the base URL does not end with a slash before appending the path
-  const url = `${config.baseUrl?.replace(/\/+$/, '')}/chat/completions`;
-
-  const payload = {
-    model: config.model ?? 'gpt-4o',
-    messages: request.messages,
-    temperature: request.options?.temperature ?? 0.7,
-    top_p: request.options?.top_p ?? 1,
-  };
+export const type = 'openai_compatible_personal';
+export const label = 'OpenAI-compatible (personal)';
+export const models = [{ id: 'gpt-4o', label: 'Gateway model (default: gpt-4o)' }];
+export const agentConfigurationDoc = `# OpenAI-compatible (personal)\n\nCalls an OpenAI-compatible chat completions endpoint for each Paperclip run.\n\nConfigure baseUrl, apiKey, and model in the adapter configuration. The adapter sends the Paperclip wake context as the user message and returns the model response as the run summary. This adapter does not provide tools or directly modify Paperclip tasks.`;
 
+interface GatewayConfig {
+  baseUrl?: unknown;
+  apiKey?: unknown;
+  model?: unknown;
+  temperature?: unknown;
+  top_p?: unknown;
+  promptTemplate?: unknown;
+}
+
+interface GatewayChatResponse {
+  choices?: Array<{ message?: { content?: unknown } }>;
+  model?: string;
+  usage?: { prompt_tokens?: number; completion_tokens?: number };
+}
+
+function readConfig(config: Record<string, unknown>): GatewayConfig {
+  return config as GatewayConfig;
+}
+
+function getConnection(config: GatewayConfig): { baseUrl: string; apiKey: string; model: string } {
+  const baseUrl = typeof config.baseUrl === 'string' ? config.baseUrl.trim().replace(/\/+$/, '') : '';
+  const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : '';
+  const model = typeof config.model === 'string' && config.model.trim() ? config.model.trim() : 'gpt-4o';
+
+  if (!baseUrl) throw new Error('Informe a Base URL do gateway OpenAI-compatible.');
+  if (!apiKey) throw new Error('Informe a API Key do gateway.');
   try {
-    const resp = await axios.post(url, payload, {
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${config.apiKey}`,
-      },
-      timeout: 30_000,
-    });
+    new URL(baseUrl);
+  } catch {
+    throw new Error('A Base URL precisa ser uma URL válida, incluindo https:// ou http://.');
+  }
+
+  return { baseUrl, apiKey, model };
+}
+
+function friendlyError(err: unknown): string {
+  if (!axios.isAxiosError(err)) return err instanceof Error ? err.message : 'Erro desconhecido ao executar o adapter.';
+
+  const axiosErr = err as AxiosError<{ error?: { message?: string } }>;
+  const status = axiosErr.response?.status;
+  if (status === 401 || status === 403) return `Credenciais inválidas ou sem permissão (${status}).`;
+  if (status === 404) return 'Endpoint não encontrado (404). Confira a Base URL do gateway.';
+  if (status && status >= 500) return `Erro interno do gateway (${status}).`;
+  return axiosErr.response?.data?.error?.message ?? axiosErr.message ?? 'Erro ao comunicar com o gateway OpenAI-compatible.';
+}
 
-    const choice = resp.data?.choices?.[0];
-    if (!choice?.message?.content) {
-      throw new Error('Resposta inesperada da API OpenAI‑compatible.');
-    }
+function getPrompt(ctx: AdapterExecutionContext): string {
+  const wakeContext = ctx.context ?? {};
+  const prompt = wakeContext.prompt;
+  const task = wakeContext.task;
+  const taskText = typeof task === 'string' ? task : task ? JSON.stringify(task, null, 2) : '';
+  const fallback = typeof prompt === 'string' && prompt.trim()
+    ? prompt.trim()
+    : taskText || JSON.stringify(wakeContext, null, 2);
 
-    return { content: choice.message.content } as ChatResponse;
+  const template = ctx.config.promptTemplate;
+  if (typeof template !== 'string' || !template.trim()) return fallback;
+
+  return template
+    .split('{{agent.id}}').join(ctx.agent.id)
+    .split('{{agent.name}}').join(ctx.agent.name)
+    .split('{{context.prompt}}').join(typeof prompt === 'string' ? prompt : '')
+    .split('{{context.task}}').join(taskText)
+    .split('{{context}}').join(JSON.stringify(wakeContext, null, 2));
+}
+
+async function callGateway(config: GatewayConfig, messages: Array<{ role: string; content: string }>) {
+  const { baseUrl, apiKey, model } = getConnection(config);
+  const response = await axios.post<GatewayChatResponse>(`${baseUrl}/chat/completions`, {
+    model,
+    messages,
+    temperature: typeof config.temperature === 'number' ? config.temperature : 0.7,
+    top_p: typeof config.top_p === 'number' ? config.top_p : 1,
+  }, {
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+    timeout: 120_000,
+  });
+
+  const content = response.data?.choices?.[0]?.message?.content;
+  if (typeof content !== 'string' || !content.trim()) {
+    throw new Error('Resposta inesperada do gateway: choices[0].message.content está ausente ou vazia.');
+  }
+
+  return { content, response: response.data, requestedModel: model };
+}
+
+async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+  const config = readConfig(ctx.config);
+  const prompt = getPrompt(ctx);
+  const messages = [
+    {
+      role: 'system',
+      content: `Você é o agente ${ctx.agent.name} do Paperclip. Responda ao contexto da execução de forma útil e objetiva.`,
+    },
+    { role: 'user', content: prompt },
+  ];
+
+  try {
+    const result = await callGateway(config, messages);
+    await ctx.onLog('stdout', `${result.content}\n`);
+    return {
+      exitCode: 0,
+      signal: null,
+      timedOut: false,
+      summary: result.content,
+      model: result.response.model ?? result.requestedModel,
+      provider: 'openai-compatible',
+      usage: result.response.usage ? {
+        inputTokens: result.response.usage.prompt_tokens ?? 0,
+        outputTokens: result.response.usage.completion_tokens ?? 0,
+      } : undefined,
+    };
   } catch (err) {
-    // -------- Friendly generic error handling --------
-    if (axios.isAxiosError(err)) {
-      const axiosErr = err as AxiosError;
-      const status = axiosErr.response?.status;
-      const data = axiosErr.response?.data;
-
-      let friendlyMsg = 'Erro ao comunicar com o gateway OpenAI‑compatible.';
-      if (status === 401) friendlyMsg = 'Credenciais inválidas (401).';
-      else if (status === 404) friendlyMsg = 'Endpoint não encontrado (404).';
-      else if (status && status >= 500) friendlyMsg = 'Erro interno do servidor (5xx).';
-      else if (data && typeof data === 'object' && 'error' in data) {
-        // OpenAI‑style error payload
-        friendlyMsg = `Gateway error: ${(data as any).error?.message ?? friendlyMsg}`;
-      }
-
-      throw new Error(friendlyMsg);
-    }
-    // Non‑HTTP errors
-    throw err;
+    const message = friendlyError(err);
+    await ctx.onLog('stderr', `${message}\n`);
+    return { exitCode: 1, signal: null, timedOut: false, errorMessage: message, model: config.model as string | undefined };
   }
 }
 
-/** ------------------------------------------------------------
- * 3️⃣ EXPORT ADAPTER FUNCTION
- * ------------------------------------------------------------ */
-export function createServerAdapter(): Adapter {
-  return {
-    name: 'OpenAI‑compatible Adapter (personal)',
-    configSchema,
-    handleChat,
-  };
-}
+async function testEnvironment(ctx: AdapterEnvironmentTestContext): Promise<AdapterEnvironmentTestResult> {
+  const config = readConfig(ctx.config);
+  const testedAt = new Date().toISOString();
+  try {
+    const { baseUrl, apiKey, model } = getConnection(config);
+    await axios.get(`${baseUrl}/models`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      timeout: 15_000,
+    });
+    return {
+      adapterType: ctx.adapterType,
+      status: 'pass',
+      checks: [{ level: 'info', code: 'gateway_reachable', message: `Gateway acessível; modelo configurado: ${model}.` }],
+      testedAt,
+    };
+  } catch (err) {
+    const message = friendlyError(err);
+    return {
+      adapterType: ctx.adapterType,
+      status: 'fail',
+      checks: [{ level: 'error', code: 'gateway_check_failed', message, hint: 'Confira a Base URL, a API Key e se o gateway oferece GET /models.' }],
+      testedAt,
+    };
+  }
+}
+
+export function createServerAdapter(): ServerAdapterModule {
+  return { type, label, models, agentConfigurationDoc, configSchema, execute, testEnvironment };
+}

package/src/paperclip-types.ts

@@ -0,0 +1,56 @@
+export interface ConfigField {
+  key: string;
+  type: string;
+  label: string;
+  default?: unknown;
+  placeholder?: string;
+  description?: string;
+  secret?: boolean;
+}
+
+export interface AdapterExecutionContext {
+  runId: string;
+  agent: { id: string; companyId: string; name: string; adapterConfig: unknown };
+  runtime: { sessionId: string | null; sessionParams: Record<string, unknown> | null };
+  config: Record<string, unknown>;
+  context: Record<string, any>;
+  onLog: (stream: 'stdout' | 'stderr', chunk: string) => Promise<void>;
+}
+
+export interface AdapterExecutionResult {
+  exitCode: number | null;
+  signal: string | null;
+  timedOut: boolean;
+  errorMessage?: string | null;
+  summary?: string | null;
+  usage?: { inputTokens: number; outputTokens: number };
+  provider?: string | null;
+  model?: string | null;
+}
+
+export interface AdapterEnvironmentTestContext {
+  adapterType: string;
+  config: Record<string, unknown>;
+}
+
+export interface AdapterEnvironmentTestResult {
+  adapterType: string;
+  status: 'pass' | 'warn' | 'fail';
+  checks: Array<{
+    level: 'info' | 'warn' | 'error';
+    code: string;
+    message: string;
+    hint?: string;
+  }>;
+  testedAt: string;
+}
+
+export interface ServerAdapterModule {
+  type: string;
+  label?: string;
+  models: Array<{ id: string; label: string }>;
+  agentConfigurationDoc: string;
+  configSchema: ConfigField[];
+  execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
+  testEnvironment(ctx: AdapterEnvironmentTestContext): Promise<AdapterEnvironmentTestResult>;
+}