@aiconnect/agentjobs-mcp 1.1.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,19 +417,27 @@ export function formatJobSummary(job) {
         return JSON.stringify(job, null, 2);
     }
 }
-/**
- * Formata a resposta para a lista de jobs.
- * @param jobs - Um array de jobs.
- * @param pagination - O objeto de paginação.
- * @returns Uma string formatada com a lista de resumos de jobs.
- */
-export function formatJobList(jobs, pagination) {
-    if (!jobs || jobs.length === 0) {
-        return "No jobs found for the given criteria.";
+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)}`);
+    }
+    const safeJobs = jobs || [];
+    const { count, limit, total } = meta;
+    const hasMore = (offset + count) < total;
+    const nextOffset = hasMore ? offset + limit : null;
+    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)`;
     }
-    const jobSummaries = jobs.map(job => formatJobSummary(job)).join('\n\n');
-    const paginationSummary = `Page: ${Math.floor((pagination.offset || 0) / (pagination.limit || 20)) + 1} | Total Jobs: ${pagination.total}`;
-    return `Found ${jobs.length} jobs.\n\n${jobSummaries}\n\n${paginationSummary}`;
+    if (safeJobs.length === 0) {
+        return `Found 0 jobs.\n\n${footer}`;
+    }
+    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
 const jobTypeSchema = z.object({
@@ -454,21 +665,81 @@ export function formatJobTypeSummary(jobType) {
         return JSON.stringify(jobType, null, 2);
     }
 }
-export function formatJobStats(stats, filters) {
+const DATE_FILTER_KEYS = [
+    'scheduled_at_gte',
+    'scheduled_at_lte',
+    'created_at_gte',
+    'created_at_lte',
+];
+const renderDateRange = (label, gte, lte) => {
+    if (gte === undefined && lte === undefined)
+        return null;
+    const left = gte !== undefined ? String(gte) : '(open)';
+    const right = lte !== undefined ? String(lte) : '(open)';
+    return `${label}: ${left} → ${right}`;
+};
+const CONTEXT_LABEL_WIDTH = 16; // "Server version: " == 16 chars
+const JOB_TYPE_ID_WIDTH = 22;
+const JOB_TYPE_EMOJI_WIDTH = 4;
+function padLabel(label) {
+    return (label + ':').padEnd(CONTEXT_LABEL_WIDTH, ' ');
+}
+function formatJobTypeLine(jt) {
+    const id = jt.id.padEnd(JOB_TYPE_ID_WIDTH, ' ');
+    const emoji = (jt.emoji ?? '').padEnd(JOB_TYPE_EMOJI_WIDTH, ' ');
+    const description = jt.description ? ` — ${jt.description}` : '';
+    return `  - ${id} ${emoji} ${jt.name}${description}`;
+}
+export function formatContext(input) {
+    const { localConfig, jobTypes, total, jobTypesError } = input;
+    const contextSection = [
+        'Context:',
+        `  ${padLabel('Org ID')} ${localConfig.org_id}`,
+        `  ${padLabel('Timezone')} ${localConfig.timezone}`,
+        `  ${padLabel('API URL')} ${localConfig.api_url}`,
+        `  ${padLabel('Server version')} ${localConfig.server_version}`
+    ].join('\n');
+    let jobsSection;
+    if (jobTypesError !== undefined) {
+        jobsSection = `Job types: unavailable (error: ${jobTypesError})`;
+    }
+    else if (jobTypes === undefined) {
+        jobsSection = 'Job types: unavailable (error: unknown)';
+    }
+    else {
+        const totalCount = typeof total === 'number' ? total : jobTypes.length;
+        if (totalCount === 0) {
+            jobsSection = 'Job types available (0):\n  (no job types registered for this org)';
+        }
+        else {
+            const lines = jobTypes.map(formatJobTypeLine);
+            let trailing = '';
+            if (totalCount > jobTypes.length) {
+                const missing = totalCount - jobTypes.length;
+                trailing = `\n  … and ${missing} more job types not shown`;
+            }
+            jobsSection = `Job types available (${totalCount}):\n${lines.join('\n')}${trailing}`;
+        }
+    }
+    return `${contextSection}\n\n${jobsSection}`;
+}
+export function formatJobStats(stats, appliedFilters = {}) {
     const { waiting = 0, running = 0, completed = 0, failed = 0, canceled = 0, scheduled = 0, } = stats.status;
     const totalJobs = waiting + running + completed + failed + canceled + scheduled;
     const successRate = totalJobs > 0 ? ((completed / (totalJobs - waiting - scheduled - running)) * 100).toFixed(1) : "0.0";
     const completionRate = (completed + failed) > 0 ? (completed / (completed + failed) * 100).toFixed(1) : "0.0";
     const activeJobs = running + waiting + scheduled;
-    let period = "All time";
-    if (filters) {
-        if (filters.scheduled_at_gte || filters.scheduled_at_lte) {
-            const startDate = filters.scheduled_at_gte ? new Date(filters.scheduled_at_gte).toLocaleDateString() : "";
-            const endDate = filters.scheduled_at_lte ? new Date(filters.scheduled_at_lte).toLocaleDateString() : "";
-            period = `${startDate} to ${endDate}`;
-        }
-    }
-    const org = filters?.org_id ? `Organization: ${filters.org_id}` : "";
+    const filters = appliedFilters || {};
+    const scheduledLine = renderDateRange('Scheduled', filters.scheduled_at_gte, filters.scheduled_at_lte);
+    const createdLine = renderDateRange('Created', filters.created_at_gte, filters.created_at_lte);
+    const hasAnyDateFilter = DATE_FILTER_KEYS.some((k) => filters[k] !== undefined);
+    const periodFallback = hasAnyDateFilter ? null : 'Period: All time';
+    const dateLines = [scheduledLine, createdLine, periodFallback].filter((l) => l !== null);
+    const dateFilterSet = new Set(DATE_FILTER_KEYS);
+    const otherFilterEntries = Object.entries(filters).filter(([k, v]) => !dateFilterSet.has(k) && v !== undefined && v !== null && v !== '');
+    const filtersSection = otherFilterEntries.length
+        ? `Filters:\n${otherFilterEntries.map(([k, v]) => `- ${k}: ${v}`).join('\n')}\n\n`
+        : '';
     const percentage = (value) => {
         if (totalJobs === 0)
             return "0.0";
@@ -478,10 +749,9 @@ export function formatJobStats(stats, filters) {
 Job Statistics Report
 ====================
 
-Period: ${period}
-${org}
+${dateLines.join('\n')}
 
-Status Breakdown:
+${filtersSection}Status Breakdown:
 ✓ Completed:  ${completed} jobs (${percentage(completed)}%)
 ⏳ Running:     ${running} jobs (${percentage(running)}%)
 ⏰ Scheduled:  ${scheduled} jobs (${percentage(scheduled)}%)

package/build/utils/schemas.js

@@ -1,20 +1,32 @@
 import { z } from 'zod';
 /**
- * A flexible Zod schema for validating ISO 8601 date-time strings.
+ * Factory that returns a fresh Zod schema validating ISO 8601 date-time strings.
  *
- * This schema accepts any string that can be successfully parsed by the `Date` constructor,
- * which includes formats with 'Z' (UTC) and timezone offsets (e.g., '+01:00').
- * It refines a base string schema, providing a more specific error message if the
- * date-time string is invalid.
+ * Accepts any string parseable by `new Date(value)` (full ISO 8601 with `Z` or
+ * timezone offset, and date-only forms like `2024-07-23`).
+ *
+ * IMPORTANT — why this is a factory and not a singleton: when the MCP SDK
+ * serializes a tool's input shape to JSON Schema (via `zod-to-json-schema`),
+ * reusing the same Zod *instance* across multiple fields causes the serializer
+ * to emit `$ref` from sibling fields back to the first one. Many clients/LLMs
+ * then treat those fields as `any` and send `null`, which the server rejects.
+ * Returning a new instance per call guarantees inline definitions per field.
+ *
+ * Convention for this project: every reusable Zod schema referenced by more
+ * than one tool field MUST be exported as a factory (`() => z.something(...)`),
+ * never as a singleton `const`.
  */
-export const flexibleDateTimeSchema = z.string().refine((value) => {
-    // Try to parse the date string.
-    // The Date constructor is quite flexible with ISO 8601 formats.
+export const flexibleDateTimeSchema = () => z.string().refine((value) => {
     const date = new Date(value);
-    // Check if the parsed date is valid.
-    // `isNaN(date.getTime())` is a reliable way to check for invalid dates.
     return !isNaN(date.getTime());
 }, {
-    // Custom error message for invalid date-time strings.
     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/build/utils/version.js

@@ -0,0 +1,12 @@
+import fs from 'fs';
+function readVersion() {
+    try {
+        const raw = fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf-8');
+        const pkg = JSON.parse(raw);
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export const mcpServerVersion = readVersion();

package/docs/agent-jobs-api.md

@@ -239,6 +239,47 @@ Cancels a job by changing its status to CANCELED.
 - 404: Job not found
 - 409: Conflict (job is already in a terminal state)
 
+### List Job Types (`agent-jobs-type`)
+
+Lists agent job types registered for an organization. Used by `get_job_type` and `get_context` in this MCP.
+
+#### Path em uso pelas tools deste MCP hoje
+
+```http
+GET /organizations/:org_id/agent-jobs-type
+GET /organizations/:org_id/agent-jobs-type/:job_type_id
+```
+
+(Sem prefixo `/services/`.) **Toda tool nova neste repo deve usar este caminho** até a unificação descrita abaixo, para manter consistência com `get_job_type`.
+
+#### Path canônico upstream
+
+```http
+GET /services/organizations/:org_id/agent-jobs-type
+GET /services/organizations/:org_id/agent-jobs-type/:job_type_id
+```
+
+Este é o caminho documentado upstream pelo AI Connect API. O backend serve a mesma controller em ambos os mounts (legacy + atual). Uma migração futura para o caminho canônico deve ser feita em **change separado abrangendo todas as tools afetadas**: `get_job_type`, `list_jobs`, `create_job`, `get_jobs_stats` e `get_context`.
+
+#### Query parameters suportados
+
+- `enrich=emoji` — adiciona o campo `emoji` no payload (cache server-side de 1h por job_type).
+- `include=schema` — inclui `params_schema` completo de cada job type (não usado por `get_context`; pesado).
+- `limit` — número máximo de itens por página. `get_context` fixa em `100`.
+- `offset` — paginação numérica.
+- `sort` — formato `field:direction`, ex: `name:asc` (default usado por `get_context`).
+
+#### Response shape
+
+```json
+{
+  "data": [
+    { "id": "string", "name": "string", "description": "string?", "emoji": "string?" }
+  ],
+  "meta": { "total": 0, "limit": 100, "offset": 0 }
+}
+```
+
 ## Job Status Values
 
 Jobs can have the following status values:
@@ -334,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.1.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",
@@ -61,7 +61,8 @@
     "eslint": "^9.14.0",
     "typescript-eslint": "^8.12.2",
     "typescript": "^5.7.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod-to-json-schema": "^3.23.0"
   },
   "engines": {
     "node": ">=18.0.0"