@tacitai/mcp-server 0.1.1 → 0.3.0

package/dist/tools/agents.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Agent tools — Claude CLI wrappers around the Agent Factory MCP surface.
+ *
+ * All 6 tools dispatch through POST /agents/mcp/tools/call on the Axum API,
+ * which provides governance parity (feature gate, fingerprint dedup, hash-bound
+ * approval checks) with the web UI.
+ *
+ * Routes (Axum):
+ *   GET  /agents/mcp/tools       — tool discovery (not used here; we define our own defs)
+ *   POST /agents/mcp/tools/call  — authenticated dispatch by tool name
+ */
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TacitClient } from '../client.js';
+export interface ToolRequest {
+    execute(): Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+}
+export declare const agentListInputSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+}, {
+    limit?: number | undefined;
+}>;
+export type AgentListInput = z.infer<typeof agentListInputSchema>;
+export declare const AGENT_LIST_TOOL_DEF: {
+    name: "tacit_agent_list";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function buildAgentListRequest(client: TacitClient, input: AgentListInput): ToolRequest;
+export declare function handleAgentList(args: unknown): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare const agentDelegateInputSchema: z.ZodObject<{
+    agent_id: z.ZodString;
+    task: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    target_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    program_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    dossier_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    agent_id: string;
+    task: string;
+    program_ids?: string[] | undefined;
+    kind?: string | undefined;
+    target_ids?: string[] | undefined;
+    dossier_ids?: string[] | undefined;
+}, {
+    agent_id: string;
+    task: string;
+    program_ids?: string[] | undefined;
+    kind?: string | undefined;
+    target_ids?: string[] | undefined;
+    dossier_ids?: string[] | undefined;
+}>;
+export type AgentDelegateInput = z.infer<typeof agentDelegateInputSchema>;
+export declare const AGENT_DELEGATE_TOOL_DEF: {
+    name: "tacit_agent_delegate";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            agent_id: {
+                type: string;
+                description: string;
+            };
+            task: {
+                type: string;
+                description: string;
+            };
+            kind: {
+                type: string;
+                description: string;
+            };
+            target_ids: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            program_ids: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            dossier_ids: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function buildAgentDelegateRequest(client: TacitClient, input: AgentDelegateInput): ToolRequest;
+export declare function handleAgentDelegate(args: unknown): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare const agentThreadInputSchema: z.ZodObject<{
+    agent_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    agent_id: string;
+}, {
+    agent_id: string;
+}>;
+export type AgentThreadInput = z.infer<typeof agentThreadInputSchema>;
+export declare const AGENT_THREAD_TOOL_DEF: {
+    name: "tacit_agent_thread";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            agent_id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function buildAgentThreadRequest(client: TacitClient, input: AgentThreadInput): ToolRequest;
+export declare function handleAgentThread(args: unknown): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare const agentApprovalsInputSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+    status?: string | undefined;
+}, {
+    limit?: number | undefined;
+    status?: string | undefined;
+}>;
+export type AgentApprovalsInput = z.infer<typeof agentApprovalsInputSchema>;
+export declare const AGENT_APPROVALS_TOOL_DEF: {
+    name: "tacit_agent_approvals";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            status: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function buildAgentApprovalsRequest(client: TacitClient, input: AgentApprovalsInput): ToolRequest;
+export declare function handleAgentApprovals(args: unknown): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare const agentDecideInputSchema: z.ZodObject<{
+    approval_id: z.ZodString;
+    decision: z.ZodEnum<["approve", "deny"]>;
+    note: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    approval_id: string;
+    decision: "approve" | "deny";
+    note?: string | undefined;
+}, {
+    approval_id: string;
+    decision: "approve" | "deny";
+    note?: string | undefined;
+}>;
+export type AgentDecideInput = z.infer<typeof agentDecideInputSchema>;
+export declare const AGENT_DECIDE_TOOL_DEF: {
+    name: "tacit_agent_decide";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            approval_id: {
+                type: string;
+                description: string;
+            };
+            decision: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            note: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function buildAgentDecideRequest(client: TacitClient, input: AgentDecideInput): ToolRequest;
+export declare function handleAgentDecide(args: unknown): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare const agentTimelineInputSchema: z.ZodObject<{
+    agent_id: z.ZodString;
+    run_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    agent_id: string;
+    run_id: string;
+}, {
+    agent_id: string;
+    run_id: string;
+}>;
+export type AgentTimelineInput = z.infer<typeof agentTimelineInputSchema>;
+export declare const AGENT_TIMELINE_TOOL_DEF: {
+    name: "tacit_agent_timeline";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            agent_id: {
+                type: string;
+                description: string;
+            };
+            run_id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function buildAgentTimelineRequest(client: TacitClient, input: AgentTimelineInput): ToolRequest;
+export declare function handleAgentTimeline(args: unknown): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare function registerAgentTools(server: McpServer, getClientFn: () => Promise<TacitClient>): void;

package/dist/tools/agents.js

@@ -0,0 +1,335 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Agent tools — Claude CLI wrappers around the Agent Factory MCP surface.
+ *
+ * All 6 tools dispatch through POST /agents/mcp/tools/call on the Axum API,
+ * which provides governance parity (feature gate, fingerprint dedup, hash-bound
+ * approval checks) with the web UI.
+ *
+ * Routes (Axum):
+ *   GET  /agents/mcp/tools       — tool discovery (not used here; we define our own defs)
+ *   POST /agents/mcp/tools/call  — authenticated dispatch by tool name
+ */
+import { z } from 'zod';
+import { getClient, TacitApiError, TokenExpiredError } from '../client.js';
+function apiErrorResult(err, toolName) {
+    if (err instanceof TokenExpiredError) {
+        return {
+            content: [{ type: 'text', text: err.message }],
+            isError: true,
+        };
+    }
+    if (err instanceof TacitApiError) {
+        return { content: [{ type: 'text', text: `API error ${err.statusCode} on ${toolName}: ${err.body}` }], isError: true };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+}
+async function callAgentTool(client, name, args) {
+    return client.post('/api/v1/agents/mcp/tools/call', { name, arguments: args });
+}
+// ─── tacit_agent_list ────────────────────────────────────────────────────────
+export const agentListInputSchema = z.object({
+    limit: z.number().int().positive().optional().describe('Maximum agents to return (default 25, max 100)'),
+});
+export const AGENT_LIST_TOOL_DEF = {
+    name: 'tacit_agent_list',
+    description: 'List business agents in the workspace. Returns agent id, name, archetype, status, and policy summary.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: { type: 'number', description: 'Maximum agents to return (default 25, max 100)' },
+        },
+        required: [],
+    },
+};
+export function buildAgentListRequest(client, input) {
+    return {
+        async execute() {
+            try {
+                const args = {};
+                if (input.limit !== undefined)
+                    args['limit'] = input.limit;
+                const result = await callAgentTool(client, 'tacit.agents.list', args);
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (err) {
+                return apiErrorResult(err, 'tacit_agent_list');
+            }
+        },
+    };
+}
+export async function handleAgentList(args) {
+    const parsed = agentListInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
+    }
+    return buildAgentListRequest(getClient(), parsed.data).execute();
+}
+// ─── tacit_agent_delegate ────────────────────────────────────────────────────
+export const agentDelegateInputSchema = z.object({
+    agent_id: z.string().min(1).describe('UUID of the agent to delegate to'),
+    task: z.string().min(1).describe('Task description to delegate'),
+    kind: z.string().optional().describe('Task kind (default: "task")'),
+    target_ids: z.array(z.string()).optional().describe('Target entity UUIDs for the task'),
+    program_ids: z.array(z.string()).optional().describe('Program UUIDs to scope the task'),
+    dossier_ids: z.array(z.string()).optional().describe('Dossier UUIDs to scope the task'),
+});
+export const AGENT_DELEGATE_TOOL_DEF = {
+    name: 'tacit_agent_delegate',
+    description: 'Delegate a task to a business agent. The task is fingerprint-deduped and dispatched to the run engine. ' +
+        'Returns assignment_id, run_id, and status. Duplicate tasks return status "duplicate" with the existing assignment.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agent_id: { type: 'string', description: 'UUID of the agent to delegate to' },
+            task: { type: 'string', description: 'Task description to delegate' },
+            kind: { type: 'string', description: 'Task kind (default: "task")' },
+            target_ids: { type: 'array', items: { type: 'string' }, description: 'Target entity UUIDs' },
+            program_ids: { type: 'array', items: { type: 'string' }, description: 'Program UUIDs to scope the task' },
+            dossier_ids: { type: 'array', items: { type: 'string' }, description: 'Dossier UUIDs to scope the task' },
+        },
+        required: ['agent_id', 'task'],
+    },
+};
+export function buildAgentDelegateRequest(client, input) {
+    return {
+        async execute() {
+            try {
+                const spec = { task: input.task };
+                if (input.kind)
+                    spec['kind'] = input.kind;
+                if (input.target_ids)
+                    spec['target_ids'] = input.target_ids;
+                if (input.program_ids)
+                    spec['program_ids'] = input.program_ids;
+                if (input.dossier_ids)
+                    spec['dossier_ids'] = input.dossier_ids;
+                const result = await callAgentTool(client, 'tacit.agents.delegate', {
+                    agent_id: input.agent_id,
+                    spec,
+                });
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (err) {
+                return apiErrorResult(err, 'tacit_agent_delegate');
+            }
+        },
+    };
+}
+export async function handleAgentDelegate(args) {
+    const parsed = agentDelegateInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
+    }
+    return buildAgentDelegateRequest(getClient(), parsed.data).execute();
+}
+// ─── tacit_agent_thread ──────────────────────────────────────────────────────
+export const agentThreadInputSchema = z.object({
+    agent_id: z.string().min(1).describe('UUID of the agent whose thread to retrieve'),
+});
+export const AGENT_THREAD_TOOL_DEF = {
+    name: 'tacit_agent_thread',
+    description: 'Get the workspace-scope conversation thread and recent messages for an agent. Creates the thread lazily if it does not exist.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agent_id: { type: 'string', description: 'UUID of the agent' },
+        },
+        required: ['agent_id'],
+    },
+};
+export function buildAgentThreadRequest(client, input) {
+    return {
+        async execute() {
+            try {
+                const result = await callAgentTool(client, 'tacit.agents.thread', { agent_id: input.agent_id });
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (err) {
+                return apiErrorResult(err, 'tacit_agent_thread');
+            }
+        },
+    };
+}
+export async function handleAgentThread(args) {
+    const parsed = agentThreadInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
+    }
+    return buildAgentThreadRequest(getClient(), parsed.data).execute();
+}
+// ─── tacit_agent_approvals ───────────────────────────────────────────────────
+export const agentApprovalsInputSchema = z.object({
+    status: z.string().optional().describe('Filter by status (e.g. "pending", "approved", "denied")'),
+    limit: z.number().int().positive().optional().describe('Maximum approvals to return (default 25, max 100)'),
+});
+export const AGENT_APPROVALS_TOOL_DEF = {
+    name: 'tacit_agent_approvals',
+    description: 'List pending or decided approvals in the workspace. Use status "pending" to see items awaiting human decision.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            status: { type: 'string', description: 'Filter by status (e.g. "pending", "approved", "denied")' },
+            limit: { type: 'number', description: 'Maximum approvals to return (default 25, max 100)' },
+        },
+        required: [],
+    },
+};
+export function buildAgentApprovalsRequest(client, input) {
+    return {
+        async execute() {
+            try {
+                const args = {};
+                if (input.status)
+                    args['status'] = input.status;
+                if (input.limit !== undefined)
+                    args['limit'] = input.limit;
+                const result = await callAgentTool(client, 'tacit.agents.approvals', args);
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (err) {
+                return apiErrorResult(err, 'tacit_agent_approvals');
+            }
+        },
+    };
+}
+export async function handleAgentApprovals(args) {
+    const parsed = agentApprovalsInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
+    }
+    return buildAgentApprovalsRequest(getClient(), parsed.data).execute();
+}
+// ─── tacit_agent_decide ──────────────────────────────────────────────────────
+export const agentDecideInputSchema = z.object({
+    approval_id: z.string().min(1).describe('UUID of the approval to decide'),
+    decision: z.enum(['approve', 'deny']).describe('Decision: "approve" or "deny"'),
+    note: z.string().optional().describe('Optional note explaining the decision'),
+});
+export const AGENT_DECIDE_TOOL_DEF = {
+    name: 'tacit_agent_decide',
+    description: 'Approve or deny a pending approval. The decision is hash-bound to the approval\'s action payload for integrity.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            approval_id: { type: 'string', description: 'UUID of the approval to decide' },
+            decision: { type: 'string', enum: ['approve', 'deny'], description: 'Decision: "approve" or "deny"' },
+            note: { type: 'string', description: 'Optional note explaining the decision' },
+        },
+        required: ['approval_id', 'decision'],
+    },
+};
+export function buildAgentDecideRequest(client, input) {
+    return {
+        async execute() {
+            try {
+                const args = {
+                    approval_id: input.approval_id,
+                    decision: input.decision,
+                };
+                if (input.note)
+                    args['note'] = input.note;
+                const result = await callAgentTool(client, 'tacit.agents.decide', args);
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (err) {
+                return apiErrorResult(err, 'tacit_agent_decide');
+            }
+        },
+    };
+}
+export async function handleAgentDecide(args) {
+    const parsed = agentDecideInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
+    }
+    return buildAgentDecideRequest(getClient(), parsed.data).execute();
+}
+// ─── tacit_agent_timeline ────────────────────────────────────────────────────
+export const agentTimelineInputSchema = z.object({
+    agent_id: z.string().min(1).describe('UUID of the agent'),
+    run_id: z.string().min(1).describe('UUID of the agent run to get the timeline for'),
+});
+export const AGENT_TIMELINE_TOOL_DEF = {
+    name: 'tacit_agent_timeline',
+    description: 'Get the Chronicle-backed provenance event timeline for an agent run. Shows all events (assignment, tool calls, approvals, completions) in chronological order.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agent_id: { type: 'string', description: 'UUID of the agent' },
+            run_id: { type: 'string', description: 'UUID of the agent run' },
+        },
+        required: ['agent_id', 'run_id'],
+    },
+};
+export function buildAgentTimelineRequest(client, input) {
+    return {
+        async execute() {
+            try {
+                const result = await callAgentTool(client, 'tacit.agents.timeline', {
+                    agent_id: input.agent_id,
+                    run_id: input.run_id,
+                });
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (err) {
+                return apiErrorResult(err, 'tacit_agent_timeline');
+            }
+        },
+    };
+}
+export async function handleAgentTimeline(args) {
+    const parsed = agentTimelineInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
+    }
+    return buildAgentTimelineRequest(getClient(), parsed.data).execute();
+}
+export function registerAgentTools(server, getClientFn) {
+    server.tool('tacit_agent_list', 'List business agents in the workspace.', {
+        limit: z.number().int().positive().optional().describe('Maximum agents to return'),
+    }, async (args) => {
+        const client = await getClientFn();
+        return buildAgentListRequest(client, args).execute();
+    });
+    server.tool('tacit_agent_delegate', 'Delegate a task to a business agent.', {
+        agent_id: z.string().min(1).describe('UUID of the agent to delegate to'),
+        task: z.string().min(1).describe('Task description to delegate'),
+        kind: z.string().optional().describe('Task kind'),
+        target_ids: z.array(z.string()).optional().describe('Target entity UUIDs'),
+        program_ids: z.array(z.string()).optional().describe('Program UUIDs'),
+        dossier_ids: z.array(z.string()).optional().describe('Dossier UUIDs'),
+    }, async (args) => {
+        const client = await getClientFn();
+        return buildAgentDelegateRequest(client, args).execute();
+    });
+    server.tool('tacit_agent_thread', 'Get the conversation thread for an agent.', {
+        agent_id: z.string().min(1).describe('UUID of the agent'),
+    }, async (args) => {
+        const client = await getClientFn();
+        return buildAgentThreadRequest(client, args).execute();
+    });
+    server.tool('tacit_agent_approvals', 'List pending or decided approvals in the workspace.', {
+        status: z.string().optional().describe('Filter by status'),
+        limit: z.number().int().positive().optional().describe('Maximum approvals to return'),
+    }, async (args) => {
+        const client = await getClientFn();
+        return buildAgentApprovalsRequest(client, args).execute();
+    });
+    server.tool('tacit_agent_decide', 'Approve or deny a pending approval.', {
+        approval_id: z.string().min(1).describe('UUID of the approval to decide'),
+        decision: z.enum(['approve', 'deny']).describe('Decision'),
+        note: z.string().optional().describe('Optional note'),
+    }, async (args) => {
+        const client = await getClientFn();
+        return buildAgentDecideRequest(client, args).execute();
+    });
+    server.tool('tacit_agent_timeline', 'Get Chronicle-backed provenance timeline for an agent run.', {
+        agent_id: z.string().min(1).describe('UUID of the agent'),
+        run_id: z.string().min(1).describe('UUID of the agent run'),
+    }, async (args) => {
+        const client = await getClientFn();
+        return buildAgentTimelineRequest(client, args).execute();
+    });
+}