@aiconnect/agentjobs-mcp 1.2.0 → 1.3.0

package/build/utils/formatters.js

@@ -47,6 +47,37 @@ const jobConfigSchema = z.object({
     failure_cooldown_minutes: z.number().optional(),
     start_prompt: z.string().optional(),
 }).passthrough();
+const activitySourceSchema = z.object({
+    type: z.enum(['dispatch', 'process_module', 'direct']),
+    reference_id: z.string().optional(),
+    execution_id: z.string().optional(),
+    job_id: z.string().optional(),
+    chat_id: z.string().optional(),
+    agent_job_type_id: z.string().optional(),
+    channel_code: z.string().optional(),
+}).passthrough();
+// Required-by-contract (per `job-activities-query` spec): every activity entry
+// rendered by the formatter MUST surface id, created_at, status, activity_type_code,
+// source.type, consumed_credits, allocated_credits. Records missing any of these
+// fail the parse and fall back to "[unparseable activity]" so upstream audit-data
+// corruption is surfaced rather than silently rendered as `unknown`/`n/a`.
+const activitySchema = z.object({
+    id: z.string().min(1),
+    org_id: z.string().optional(),
+    activity_type_code: z.string().min(1),
+    status: z.enum(['submitted', 'completed', 'canceled']),
+    allocated_credits: z.number(),
+    consumed_credits: z.number(),
+    credits_rule_id: z.number().optional(),
+    payloads: z.object({
+        input: z.any().optional(),
+        output: z.any().optional(),
+    }).passthrough().optional(),
+    processed_at: isoOrMs.nullable().optional(),
+    created_at: z.union([z.string(), z.number()]),
+    updated_at: isoOrMs,
+    source: activitySourceSchema,
+}).passthrough();
 const jobDetailsSchema = z.object({
     job_id: z.string(),
     job_type_id: z.string(),
@@ -66,6 +97,13 @@ const jobDetailsSchema = z.object({
     channel_data: channelDataSchema.optional().default({}),
     job_config: jobConfigSchema.optional().default({}),
     params: z.record(z.any()).optional().default({}),
+    activities_count: z.number().optional(),
+    // Activities are intentionally validated as `unknown[]` here (not as
+    // `z.array(activitySchema)`): per-entry parsing happens inside
+    // `formatActivityEntry`, so a single malformed record degrades to
+    // "[unparseable activity]" without making the whole job document fall back
+    // to the raw-JSON branch in formatJobDetails.
+    Activities: z.array(z.unknown()).optional(),
 }).passthrough();
 const bool = (v) => (v === true ? 'yes' : v === false ? 'no' : 'n/a');
 const safe = (v, fallback = 'n/a') => v === undefined || v === null || v === '' ? fallback : String(v);
@@ -75,7 +113,134 @@ const truncate = (s, max = 300) => {
     return s.length > max ? `${s.slice(0, max)}…` : s;
 };
 const fmtList = (arr) => (arr && arr.length ? arr.join(', ') : 'n/a');
-export function formatJobDetails(job) {
+const ACTIVITY_OUTPUT_MAX = 200;
+function isBinaryValue(value) {
+    if (value === null || value === undefined || typeof value !== 'object')
+        return false;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))
+        return true;
+    if (value instanceof ArrayBuffer)
+        return true;
+    if (typeof ArrayBuffer.isView === 'function' && ArrayBuffer.isView(value))
+        return true;
+    return false;
+}
+function containsBinary(value, seen = new WeakSet()) {
+    if (isBinaryValue(value))
+        return true;
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const v of value) {
+            if (containsBinary(v, seen))
+                return true;
+        }
+        return false;
+    }
+    for (const v of Object.values(value)) {
+        if (containsBinary(v, seen))
+            return true;
+    }
+    return false;
+}
+function safeStringifyOutput(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (containsBinary(value))
+        return '[non-serializable]';
+    try {
+        const text = JSON.stringify(value);
+        return text === undefined ? '[non-serializable]' : text;
+    }
+    catch {
+        return '[non-serializable]';
+    }
+}
+/**
+ * Collapses newlines/CR/tabs into escaped literals and clamps the result so it
+ * always fits in a single visual line of the activity output. Used by every
+ * code path that injects user-controlled activity content into the rendered
+ * line — both the normal `payloads.output` branch and the malformed-entry
+ * fallback — so a bad record cannot visually corrupt the surrounding entries.
+ */
+function sanitizeForActivityLine(value, max = ACTIVITY_OUTPUT_MAX) {
+    const escaped = value
+        .replace(/\r\n/g, '\\n')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\n')
+        .replace(/\t/g, '\\t');
+    return escaped.length > max ? `${escaped.slice(0, max)}…` : escaped;
+}
+function formatActivitySource(source) {
+    if (!source || typeof source !== 'object')
+        return 'unknown';
+    const type = source.type ?? 'unknown';
+    const extras = [];
+    if (source.reference_id)
+        extras.push(`ref: ${source.reference_id}`);
+    if (source.execution_id)
+        extras.push(`exec: ${source.execution_id}`);
+    if (source.chat_id)
+        extras.push(`chat: ${source.chat_id}`);
+    if (source.agent_job_type_id)
+        extras.push(`type: ${source.agent_job_type_id}`);
+    if (source.channel_code)
+        extras.push(`channel: ${source.channel_code}`);
+    return extras.length ? `${type} (${extras.join(', ')})` : String(type);
+}
+export function formatActivityEntry(activity) {
+    let a;
+    try {
+        a = activitySchema.parse(activity);
+    }
+    catch {
+        const raw = safeStringifyOutput(activity);
+        return `- [unparseable activity] ${sanitizeForActivityLine(raw)}`;
+    }
+    const createdIso = toIso(a.created_at) ?? 'n/a';
+    const status = a.status ?? 'unknown';
+    const typeCode = a.activity_type_code ?? 'unknown';
+    const sourceLine = formatActivitySource(a.source);
+    const consumed = a.consumed_credits ?? 0;
+    const allocated = a.allocated_credits ?? 0;
+    const lines = [
+        `- ${createdIso} [${status}] ${typeCode} via ${sourceLine}`,
+        `  credits: ${consumed}/${allocated}  id: ${a.id}`,
+    ];
+    const output = a.payloads?.output;
+    if (output !== undefined && output !== null && output !== '') {
+        const stringified = safeStringifyOutput(output);
+        if (stringified !== '') {
+            lines.push(`  output: ${sanitizeForActivityLine(stringified)}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function formatJobActivitiesList(jobId, activities, meta, offset = 0) {
+    if (!meta || typeof meta.count !== 'number' || typeof meta.limit !== 'number' || typeof meta.total !== 'number') {
+        throw new Error('formatJobActivitiesList: meta is required with numeric `count`, `limit`, and `total`. ' +
+            `Received: ${JSON.stringify(meta)}`);
+    }
+    const safeActivities = activities || [];
+    const { count, total } = meta;
+    const hasMore = (offset + count) < total;
+    // Advance by the number of rows actually returned, not by `limit`. If the
+    // backend ships a short non-terminal page (count < limit), advancing by
+    // `limit` would tell the caller to skip unseen rows.
+    const nextOffset = hasMore ? offset + count : null;
+    const footer = `Returned: ${count} | Total matching: ${total} | Has more: ${hasMore} | Next offset: ${nextOffset === null ? 'null' : nextOffset}`;
+    if (safeActivities.length === 0) {
+        return `No activities found for job ${jobId}.\n\n${footer}`;
+    }
+    const entries = safeActivities.map(formatActivityEntry).join('\n');
+    return `Activities for job ${jobId} (showing ${count}):\n\n${entries}\n\n${footer}`;
+}
+export function formatJobDetails(job, meta) {
     try {
         const j = jobDetailsSchema.parse(job);
         // Derivados
@@ -120,6 +285,27 @@ export function formatJobDetails(job) {
             }
         })();
         const startPrompt = j.job_config?.start_prompt ? truncate(j.job_config.start_prompt, 500) : undefined;
+        // Fail-closed: the only signal that the caller actually requested the
+        // overlay is `meta.activities_meta` (a field the backend returns ONLY for
+        // ?include=activities). Without that signal we omit the Activities block
+        // entirely — even if `j.Activities` happens to be populated in the payload —
+        // to keep flag-off output byte-identical to the legacy formatter.
+        let activitiesBlock = '';
+        const overlayRequested = meta?.activities_meta !== undefined;
+        if (overlayRequested) {
+            if (Array.isArray(j.Activities) && j.Activities.length > 0) {
+                const entries = j.Activities.map(formatActivityEntry).join('\n');
+                const total = meta?.activities_meta?.count;
+                const limit = meta?.activities_meta?.limit;
+                const truncationLine = (typeof total === 'number' && typeof limit === 'number' && total > limit)
+                    ? `\n(showing ${j.Activities.length} of ${total} activities — use get_job_activities for full pagination)`
+                    : '';
+                activitiesBlock = `\n\nActivities:\n${entries}${truncationLine}`;
+            }
+            else {
+                activitiesBlock = `\n\nActivities:\n  - (no activities recorded for this job)`;
+            }
+        }
         return (`Job Details
 ===========
 
@@ -172,7 +358,7 @@ Result / Tags / Log:
 - Result: ${safe(j.result)}
 - Tags: ${fmtList(tagsList)}
 - Execution Log (last 5):
-${lastLogs.length ? lastLogs.join('\n') : '  - n/a'}
+${lastLogs.length ? lastLogs.join('\n') : '  - n/a'}${activitiesBlock}
 `).trim();
     }
     catch (e) {
@@ -190,15 +376,32 @@ const jobSchema = z.object({
     job_status: z.string(),
     result: z.string().nullable(),
     job_type_id: z.string(),
+    activities_count: z.number().optional(),
+    Activities: z.array(z.any()).optional(),
 }).passthrough(); // .passthrough() permite outros campos não definidos no schema.
 /**
  * Formata um resumo de um job, com os campos principais.
- * @param job - O objeto do job.
- * @returns Uma string formatada com o resumo do job.
  */
-export function formatJobSummary(job) {
+export function formatJobSummary(job, options = {}) {
     try {
         const parsedJob = jobSchema.parse(job);
+        const overlayConsidered = options.includeActivities === true && Array.isArray(parsedJob.Activities);
+        const overlayLen = overlayConsidered ? parsedJob.Activities.length : undefined;
+        const totalCount = typeof parsedJob.activities_count === 'number' ? parsedJob.activities_count : undefined;
+        let activitiesLine = '';
+        if (totalCount !== undefined && overlayLen !== undefined && overlayLen !== totalCount) {
+            // Surface any divergence between the canonical total and the overlay size,
+            // not just the truncation direction (overlay < total). A backend bug that
+            // returns more overlay entries than the canonical count is also a real
+            // mismatch the caller should see.
+            activitiesLine = `\n- Activities: ${totalCount} (overlay: ${overlayLen})`;
+        }
+        else if (totalCount !== undefined) {
+            activitiesLine = `\n- Activities: ${totalCount}`;
+        }
+        else if (overlayLen !== undefined) {
+            activitiesLine = `\n- Activities: ${overlayLen}`;
+        }
         return `
 - Job ID: ${parsedJob.job_id}
 - Status: ${parsedJob.job_status}
@@ -206,7 +409,7 @@ export function formatJobSummary(job) {
 - Channel: ${parsedJob.channel_code}
 - Scheduled At: ${parsedJob.scheduled_at}
 - Updated At: ${parsedJob.updated_at}
-- Result: ${parsedJob.result || 'N/A'}
+- Result: ${parsedJob.result || 'N/A'}${activitiesLine}
     `.trim();
     }
     catch {
@@ -214,21 +417,7 @@ export function formatJobSummary(job) {
         return JSON.stringify(job, null, 2);
     }
 }
-/**
- * Formata a resposta para a lista de jobs.
- *
- * `meta` é obrigatório e os três campos (`count`, `limit`, `total`) precisam
- * ser numéricos — confirmado empiricamente que o backend sempre os retorna em
- * `/services/agent-jobs`. Falha explícita aqui é preferível a inventar um
- * footer com valores inferidos, pois isso recriaria a ambiguidade
- * "page count vs total" que esta tool deveria eliminar.
- *
- * @param jobs - Um array de jobs.
- * @param meta - O objeto `meta` retornado pelo backend.
- * @param offset - O `offset` que a tool enviou na requisição (default 0).
- * @returns Uma string formatada com a lista de resumos de jobs.
- */
-export function formatJobList(jobs, meta, offset = 0) {
+export function formatJobList(jobs, meta, offset = 0, options = {}) {
     if (!meta || typeof meta.count !== 'number' || typeof meta.limit !== 'number' || typeof meta.total !== 'number') {
         throw new Error('formatJobList: meta is required with numeric `count`, `limit`, and `total`. ' +
             `Received: ${JSON.stringify(meta)}`);
@@ -237,11 +426,17 @@ export function formatJobList(jobs, meta, offset = 0) {
     const { count, limit, total } = meta;
     const hasMore = (offset + count) < total;
     const nextOffset = hasMore ? offset + limit : null;
-    const footer = `Returned: ${count} | Total matching: ${total} | Has more: ${hasMore} | Next offset: ${nextOffset === null ? 'null' : nextOffset}`;
+    let footer = `Returned: ${count} | Total matching: ${total} | Has more: ${hasMore} | Next offset: ${nextOffset === null ? 'null' : nextOffset}`;
+    if (options.includeActivities === true && meta.activities_truncated === true) {
+        const returned = typeof meta.activities_total_returned === 'number' ? meta.activities_total_returned : '?';
+        const available = typeof meta.activities_total_available === 'number' ? meta.activities_total_available : '?';
+        footer += `\nActivities truncated: yes (returned ${returned} of ${available} available)`;
+    }
     if (safeJobs.length === 0) {
         return `Found 0 jobs.\n\n${footer}`;
     }
-    const jobSummaries = safeJobs.map(job => formatJobSummary(job)).join('\n\n');
+    const summaryOpts = { includeActivities: options.includeActivities === true };
+    const jobSummaries = safeJobs.map(job => formatJobSummary(job, summaryOpts)).join('\n\n');
     return `Found ${safeJobs.length} jobs.\n\n${jobSummaries}\n\n${footer}`;
 }
 // Schema for job type details

package/build/utils/schemas.js

@@ -22,3 +22,11 @@ export const flexibleDateTimeSchema = () => z.string().refine((value) => {
 }, {
     message: "Invalid date-time string. Please use a valid ISO 8601 format.",
 });
+/**
+ * Enum factories for activity record fields. Returned as factories for the
+ * same reason as `flexibleDateTimeSchema` — singletons would cause `$ref`
+ * collisions in the serialized JSON Schema across sibling tool fields.
+ */
+export const activityStatusSchema = () => z.enum(['submitted', 'completed', 'canceled']);
+export const activitySourceTypeSchema = () => z.enum(['dispatch', 'process_module', 'direct']);
+export const activitiesSortSchema = () => z.enum(['created_at', '-created_at']);

package/docs/agent-jobs-api.md

@@ -375,3 +375,118 @@ curl -X DELETE https://api.example.com/services/agent-jobs/job123 \
     "reason": "No longer needed"
   }'
 ```
+
+## Activities
+
+Cada agent job acumula uma trilha de auditoria de **activities** (registros de operações como `ai_completion`, chamadas de ferramentas e logs internos). A trilha pode ser consultada por dois caminhos: o endpoint dedicado `/services/activities` (paginação real, recomendado para investigação) ou o overlay `?include=activities` em `/services/agent-jobs/:id` e `/services/agent-jobs` (conveniência, com caps server-side).
+
+### `ActivityRecord` schema
+
+```ts
+{
+  id: string;                  // UUID v4
+  org_id: string;
+  activity_type_code: string;  // código aberto (ex.: "ai_completion")
+  status: 'submitted' | 'completed' | 'canceled';
+  allocated_credits: number;
+  consumed_credits: number;
+  credits_rule_id: number;     // 0..3
+  payloads?: { input?: any; output?: any };
+  processed_at?: string;       // ISO 8601, opcional
+  created_at: string;
+  updated_at: string;
+  source: {
+    type: 'dispatch' | 'process_module' | 'direct';
+    reference_id?: string;
+    execution_id?: string;
+    job_id?: string;
+    chat_id?: string;
+    agent_job_type_id?: string;
+    channel_code?: string;
+  };
+}
+```
+
+O contador `activities_count` é mantido server-side no próprio documento do agent job (incrementado a cada activity criada com `source.job_id`). Está disponível em qualquer resposta de job, sem necessidade de `?include=activities`.
+
+### Endpoint dedicado: `GET /services/activities`
+
+Recomendado para consulta paginada da trilha de um job específico. Sem caps de truncamento; suporta filtros server-side adicionais.
+
+**Query params:**
+- `job_id` (string, recomendado) — filtra activities do job indicado.
+- `org_id` (string, opcional) — escopo de organização.
+- `status` (`submitted | completed | canceled`, opcional)
+- `activity_type_code` (string, opcional) — código aberto.
+- `source_type` (`dispatch | process_module | direct`, opcional) — filtra pelo `source.type`.
+- `limit` (int, default 50)
+- `offset` (int, default 0)
+- `sort` (string, default `-created_at`)
+
+**Resposta:**
+```json
+{
+  "data": [ "ActivityRecord", "..." ],
+  "meta": { "count": 50, "limit": 50, "total": 1234, "offset": 0 }
+}
+```
+
+**Exemplo:**
+```bash
+curl -X GET "https://api.example.com/services/activities?job_id=job_abc&status=completed&limit=100" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### Overlay: `?include=activities` em `/services/agent-jobs/:id`
+
+Anexa as activities mais recentes ao detalhe do job. Útil para combinar contexto do job com trilha em uma única round-trip.
+
+**Query params adicionais:**
+- `include=activities` (obrigatório para ativar)
+- `include_limit` (int 1–100, default 50) — máximo de activities anexadas.
+- `include_sort` (`created_at | -created_at`, default `-created_at`)
+
+**Resposta:**
+```json
+{
+  "data": {
+    "job_id": "...",
+    "status": "completed",
+    "activities_count": 1234,
+    "Activities": [ "ActivityRecord", "..." ]
+  },
+  "meta": {
+    "activities_meta": { "count": 1234, "limit": 50 }
+  }
+}
+```
+
+`Activities` vem em **PascalCase** por convenção do serializador da API. Quando `meta.activities_meta.count > meta.activities_meta.limit`, a lista foi truncada — use o endpoint dedicado para acessar o restante.
+
+### Overlay: `?include=activities` em `/services/agent-jobs` (lista)
+
+Anexa activities a cada job da listagem.
+
+**Query params adicionais:**
+- `include=activities` (obrigatório)
+- `activities_limit_per_job` (int 1–100, default 15)
+- `activities_total_limit` (int 1–3000, default 500) — cap global agregado.
+- `activities_sort` (`created_at | -created_at`, default `-created_at`)
+
+**Resposta:**
+```json
+{
+  "data": [ { "Activities": [] } ],
+  "meta": {
+    "activities_total_returned": 45,
+    "activities_total_available": 120,
+    "activities_truncated": true
+  }
+}
+```
+
+### Comportamento sensível
+
+- **Fail-closed**: se a busca de activities falhar internamente quando `include=activities` está ativo, a request **inteira** falha (status 4xx/5xx). Garante integridade da trilha — nunca retorna o job sem as activities solicitadas. Em caso de erro, refaça a request sem `include=activities` ou use o endpoint dedicado.
+- **Cache bypass**: requests com `?include=activities` em `/services/agent-jobs` ignoram o cache server-side, garantindo dados sempre frescos para uso operacional/auditoria.
+- **Activities count sempre disponível**: `activities_count` no objeto do job é mantido independentemente de `include=activities`, então é consultável diretamente em qualquer resposta de job.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiconnect/agentjobs-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP (Model Context Protocol) server for managing Agent Jobs in the AI Connect platform. Developed by AI Connect - Advanced AI automation and integration solutions.",
   "type": "module",
   "main": "build/index.js",

package/build/config.test.js

@@ -1,22 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-describe('config.defaultTimezone', () => {
-    beforeEach(() => {
-        vi.resetModules();
-    });
-    afterEach(() => {
-        vi.unstubAllEnvs();
-        vi.resetModules();
-    });
-    it('reflects DEFAULT_TIMEZONE when set', async () => {
-        vi.stubEnv('DEFAULT_TIMEZONE', 'America/Sao_Paulo');
-        const { config } = await import('./config.js');
-        expect(config.defaultTimezone).toBe('America/Sao_Paulo');
-        expect(config.DEFAULT_TIMEZONE).toBe('America/Sao_Paulo');
-    });
-    it('falls back to UTC when DEFAULT_TIMEZONE is unset', async () => {
-        vi.stubEnv('DEFAULT_TIMEZONE', '');
-        const { config } = await import('./config.js');
-        expect(config.defaultTimezone).toBe('UTC');
-        expect(config.DEFAULT_TIMEZONE).toBe('UTC');
-    });
-});