@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/services/taskforceAgentMcpBridge.js

@@ -0,0 +1,527 @@
+import { createHash } from 'node:crypto';
+import { TaskforceRuleError } from '../core/Taskforce.js';
+import { createTaskforceMcpServer } from '../mcp/runtime.js';
+import { MCP_MANAGED_AGENT_DEFAULT_PROFILE, getManagedAgentMcpRuntimeProfile, getManagedAgentMcpToolProfileMembership, getManagedAgentMcpToolScopes, } from '../mcp/toolProfiles.js';
+import { MCP_TOOL_REGISTRY } from '../mcp/toolRegistry.js';
+import { serializeCanonicalJson } from '../shared/taskforceAgentDefinition.js';
+export const MANAGED_AGENT_LIST_TASKS_DEFAULT_LIMIT = 25;
+export const MANAGED_AGENT_LIST_TASKS_MAX_LIMIT = 50;
+export const MANAGED_AGENT_TOOL_RESULT_MAX_BYTES = 24 * 1024;
+export const MANAGED_AGENT_TOOL_RESULT_MESSAGE_MAX_BYTES = 28 * 1024;
+const MANAGED_AGENT_TASK_ROW_MAX_BYTES = 4 * 1024;
+export function hashTaskforceAgentMcpToolContract(tools) {
+    const contract = tools
+        .map((tool) => ({
+        name: tool.name,
+        description: tool.description || '',
+        inputSchema: tool.inputSchema || {},
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    return createHash('sha256')
+        .update(serializeCanonicalJson(contract))
+        .digest('hex');
+}
+export function isTaskforceAgentMutationToolName(name) {
+    const normalizedName = String(name || '').trim();
+    return Boolean(MCP_TOOL_REGISTRY[normalizedName]?.mutating);
+}
+export function taskforceAgentMutationCallKey(name, argumentsValue) {
+    const normalizedName = String(name || '').trim();
+    if (!isTaskforceAgentMutationToolName(normalizedName))
+        return null;
+    return `${normalizedName}:${serializeCanonicalJson(argumentsValue || {})}`;
+}
+const TASK_SCOPED_MUTATION_TOOL_NAMES = new Set([
+    'add_comment',
+    'add_task_checklist_item',
+    'replace_task_checklist',
+    'complete_workflow_step',
+]);
+const MANAGED_AGENT_CAPABILITY_TOOLS = Object.freeze({
+    tasks: [
+        'add_comment',
+        'add_task_checklist_item',
+        'complete_workflow_step',
+        'get_schedule_board',
+        'get_stats',
+        'get_task',
+        'get_task_attachments',
+        'get_task_checklist',
+        'get_task_workflow',
+        'list_task_relationships',
+        'list_tasks',
+        'replace_task_checklist',
+        'search_tasks',
+    ],
+    planning: [
+        'add_initiative_comment',
+        'add_workstream_comment',
+        'get_initiative',
+        'get_workstream',
+        'list_initiatives',
+        'list_workstreams',
+    ],
+    documents: [
+        'get_document',
+        'get_document_reviews',
+        'search_documents',
+    ],
+    images: [
+        'get_image',
+        'get_image_annotations',
+        'search_images',
+    ],
+    workspace: [
+        'get_config',
+        'get_current_profile',
+        'list_assignees',
+    ],
+});
+export class TaskforceAgentToolPolicyResolutionError extends Error {
+    code = 'TASKFORCE_AGENT_TOOL_POLICY_UNRESOLVED';
+    statusCode = 409;
+    constructor(message) {
+        super(message);
+        this.name = 'TaskforceAgentToolPolicyResolutionError';
+    }
+}
+export function resolveManagedAgentMcpToolNames(toolPolicy, profile = MCP_MANAGED_AGENT_DEFAULT_PROFILE) {
+    const baseline = new Set(getManagedAgentMcpToolProfileMembership(profile));
+    if (!toolPolicy)
+        return Array.from(baseline).sort((left, right) => left.localeCompare(right));
+    if (toolPolicy.basePolicyRef.id !== MCP_MANAGED_AGENT_DEFAULT_PROFILE) {
+        throw new TaskforceAgentToolPolicyResolutionError(`Managed MCP base policy ${toolPolicy.basePolicyRef.id} is unavailable.`);
+    }
+    const resolveCapability = (capability) => {
+        const tools = MANAGED_AGENT_CAPABILITY_TOOLS[capability];
+        if (!tools) {
+            throw new TaskforceAgentToolPolicyResolutionError(`Managed MCP capability ${capability} is unavailable.`);
+        }
+        return tools;
+    };
+    const requestedCapabilities = toolPolicy.requestedCapabilities || [];
+    const effective = requestedCapabilities.length > 0
+        ? new Set(requestedCapabilities.flatMap((capability) => resolveCapability(capability))
+            .filter((toolName) => baseline.has(toolName)))
+        : new Set(baseline);
+    for (const capability of toolPolicy.disabledCapabilities || []) {
+        for (const toolName of resolveCapability(capability))
+            effective.delete(toolName);
+    }
+    for (const override of toolPolicy.toolOverrides || []) {
+        const toolName = override.toolName;
+        if (!baseline.has(toolName)) {
+            throw new TaskforceAgentToolPolicyResolutionError(`Managed MCP tool ${override.toolName} is outside the managed baseline.`);
+        }
+        if (override.enabled)
+            effective.add(toolName);
+        else
+            effective.delete(toolName);
+    }
+    return Array.from(effective).sort((left, right) => left.localeCompare(right));
+}
+function getRuntimeHandler(runtime, method) {
+    const handler = runtime.server._requestHandlers?.get(method);
+    if (typeof handler !== 'function') {
+        throw new Error(`Taskforce MCP ${method} handler is unavailable.`);
+    }
+    return handler;
+}
+async function listRuntimeTools(runtime) {
+    const handler = getRuntimeHandler(runtime, 'tools/list');
+    const result = await handler({
+        jsonrpc: '2.0',
+        id: 'taskforce-agent-tools-list',
+        method: 'tools/list',
+        params: {},
+    }, {});
+    return Array.isArray(result?.tools) ? result.tools : [];
+}
+function compactText(value, maxLength) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim();
+    return text.length > maxLength ? `${text.slice(0, maxLength - 1).trim()}...` : text;
+}
+function describeToolSchema(schema) {
+    const properties = schema?.properties && typeof schema.properties === 'object' ? schema.properties : {};
+    const required = Array.isArray(schema?.required)
+        ? schema.required.map((item) => String(item)).filter(Boolean)
+        : [];
+    const propertyNames = Object.keys(properties).slice(0, 8);
+    if (propertyNames.length === 0)
+        return required.length > 0 ? `required: ${required.join(', ')}` : 'no arguments';
+    const args = propertyNames.map((name) => {
+        const description = compactText(properties[name]?.description, 80);
+        return description ? `${name}: ${description}` : name;
+    });
+    return `${args.join('; ')}${required.length > 0 ? `; required: ${required.join(', ')}` : ''}`;
+}
+function normalizeTaskReferenceForComparison(value) {
+    return String(value || '').trim().toLowerCase();
+}
+function taskReferenceForToolCall(call) {
+    return String(call.arguments.taskId || call.arguments.id || '').trim();
+}
+function buildTaskScopeFailure(call, message) {
+    return {
+        name: call.name,
+        arguments: call.arguments,
+        ok: false,
+        text: message,
+    };
+}
+export function validateTaskforceAgentToolCallScope(call, allowedMutationTaskId) {
+    if (!TASK_SCOPED_MUTATION_TOOL_NAMES.has(call.name))
+        return null;
+    const allowedTaskId = String(allowedMutationTaskId || '').trim();
+    if (!allowedTaskId)
+        return null;
+    const requestedTaskId = taskReferenceForToolCall(call);
+    if (!requestedTaskId) {
+        return buildTaskScopeFailure(call, `Taskforce refused ${call.name}: this task-scoped run may only mutate ${allowedTaskId}.`);
+    }
+    if (normalizeTaskReferenceForComparison(requestedTaskId) !==
+        normalizeTaskReferenceForComparison(allowedTaskId)) {
+        return buildTaskScopeFailure(call, `Taskforce refused ${call.name}: this task-scoped run may only mutate ${allowedTaskId}, not ${requestedTaskId}.`);
+    }
+    return null;
+}
+function buildToolInstructions(baseSystem, tools, allowedMutationTaskId, readOnly = false) {
+    const toolLines = tools.map((tool) => (`- ${tool.name}: ${compactText(tool.description, 180)} Args: ${describeToolSchema(tool.inputSchema)}`));
+    const taskScope = String(allowedMutationTaskId || '').trim();
+    const canCompleteWorkflow = tools.some((tool) => tool.name === 'complete_workflow_step');
+    return [
+        baseSystem,
+        '',
+        'Taskforce project tools are attached invisibly by the server. Use them when the user asks about current Taskforce tasks, initiatives, workstreams, documents, images, annotations, config, stats, or specific reference labels such as T-123, IN-123, WS-123, D-123, or I-123.',
+        readOnly
+            ? 'This run is read-only. Use Taskforce tools only to inspect data; no Taskforce writes are available.'
+            : canCompleteWorkflow
+                ? 'Allowed writes: task comments, checklist changes, and completion of the current owned workflow step. Use complete_workflow_step only after finishing that step.'
+                : 'Allowed writes: task comments and checklist changes.',
+        ...(canCompleteWorkflow && !readOnly ? [
+            'For workflow-step work, call get_task_workflow before acting. If requiresCommentEvidence is true, call add_comment and pass its returned comment.id to complete_workflow_step as evidenceCommentId. After all required work succeeds, call complete_workflow_step before answering. A comment or other task mutation does not complete the workflow step.',
+        ] : []),
+        ...(taskScope ? [`This run is task-scoped to ${taskScope}. Mutating Taskforce tools must target only this task.`] : []),
+        'To use a Taskforce tool, respond with only one JSON object and no prose:',
+        '{"tool":"get_task","arguments":{"id":"T-123"}}',
+        'After the server returns a tool result, answer the user normally unless another Taskforce tool is required; if another tool is required, respond with only one more tool-call JSON object.',
+        'Do not mention MCP setup or credentials.',
+        'Available Taskforce tools:',
+        ...toolLines,
+    ].join('\n');
+}
+function parseJsonObjectCandidate(text) {
+    const trimmed = text.trim();
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+    const candidates = [
+        trimmed,
+        fenced?.[1]?.trim(),
+        trimmed.match(/\{[\s\S]*\}/)?.[0]?.trim(),
+    ].filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return null;
+}
+function parseProviderToolCallCandidates(text) {
+    const candidates = [];
+    const direct = parseJsonObjectCandidate(text);
+    if (direct)
+        candidates.push(direct);
+    const wrappedCalls = text.matchAll(/<function_calls?>\s*([\s\S]*?)\s*<\/function_calls?>/gi);
+    for (const match of wrappedCalls) {
+        try {
+            const parsed = JSON.parse(match[1]);
+            if (Array.isArray(parsed)) {
+                candidates.push(...parsed);
+            }
+            else {
+                candidates.push(parsed);
+            }
+        }
+        catch {
+            // Ignore malformed provider wrappers and preserve the normal text response.
+        }
+    }
+    return candidates;
+}
+export function parseTaskforceAgentMcpToolCall(text, availableToolNamesInput) {
+    const availableToolNames = Array.isArray(availableToolNamesInput)
+        ? new Set(availableToolNamesInput)
+        : availableToolNamesInput;
+    for (const parsed of parseProviderToolCallCandidates(text)) {
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            continue;
+        const record = parsed;
+        const nested = record.taskforceToolCall || record.toolCall;
+        const call = nested && typeof nested === 'object' ? nested : record;
+        const name = String(call.name || call.tool || '').trim();
+        if (!name || !availableToolNames.has(name))
+            continue;
+        const args = call.arguments ?? call.args ?? {};
+        return {
+            name,
+            arguments: args && typeof args === 'object' && !Array.isArray(args) ? args : {},
+        };
+    }
+    return null;
+}
+function extractToolResultText(result) {
+    const content = Array.isArray(result?.content) ? result.content : [];
+    const text = content
+        .map((entry) => typeof entry?.text === 'string' ? entry.text : '')
+        .filter(Boolean)
+        .join('\n\n')
+        .trim();
+    return text || JSON.stringify(result ?? {}, null, 2);
+}
+function utf8ByteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+export function normalizeManagedAgentMcpToolCall(call) {
+    if (call.name !== 'list_tasks')
+        return call;
+    const args = { ...call.arguments };
+    const hasExplicitStatusIntent = Object.prototype.hasOwnProperty.call(args, 'status')
+        || Object.prototype.hasOwnProperty.call(args, 'openOnly');
+    if (!hasExplicitStatusIntent)
+        args.openOnly = true;
+    const parsedLimit = args.limit === undefined
+        ? MANAGED_AGENT_LIST_TASKS_DEFAULT_LIMIT
+        : Number(args.limit);
+    if (Number.isFinite(parsedLimit) && parsedLimit >= 0) {
+        args.limit = parsedLimit === 0
+            ? MANAGED_AGENT_LIST_TASKS_MAX_LIMIT
+            : Math.min(MANAGED_AGENT_LIST_TASKS_MAX_LIMIT, Math.max(1, Math.floor(parsedLimit)));
+    }
+    if (args.offset === undefined)
+        args.offset = 0;
+    args.format = 'json';
+    return { name: call.name, arguments: args };
+}
+function oversizedManagedAgentToolResult(toolName, originalBytes) {
+    return {
+        rejected: true,
+        text: JSON.stringify({
+            success: false,
+            code: 'TASKFORCE_AGENT_TOOL_RESULT_TOO_LARGE',
+            message: `Taskforce tool ${toolName} returned too much data for a managed agent prompt.`,
+            originalBytes,
+            maxBytes: MANAGED_AGENT_TOOL_RESULT_MAX_BYTES,
+            retryHint: 'Retry with narrower filters, a smaller limit, or a bounded detail read.',
+        }),
+    };
+}
+function compactManagedAgentTaskRow(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    if (utf8ByteLength(JSON.stringify(value)) <= MANAGED_AGENT_TASK_ROW_MAX_BYTES)
+        return value;
+    const task = value;
+    const text = (field, maxLength = 200) => {
+        const candidate = task[field];
+        return candidate == null ? null : compactText(candidate, maxLength);
+    };
+    return {
+        id: text('id'),
+        referenceNumber: task.referenceNumber ?? null,
+        localReferenceNumber: task.localReferenceNumber ?? null,
+        referenceLabel: text('referenceLabel'),
+        title: text('title', 512),
+        status: text('status', 40),
+        priority: task.priority ?? null,
+        complexity: task.complexity ?? null,
+        type: text('type', 80),
+        category: text('category', 80),
+        createdAt: text('createdAt', 40),
+        updatedAt: text('updatedAt', 40),
+        completedAt: text('completedAt', 40),
+        canceledReason: text('canceledReason', 512),
+        isArchived: task.isArchived === true,
+        scheduledDate: text('scheduledDate', 40),
+        dueDate: text('dueDate', 40),
+        scheduledWeekKey: text('scheduledWeekKey', 40),
+        orderInDay: task.orderInDay ?? null,
+        workstreamId: text('workstreamId'),
+        createdBy: text('createdBy'),
+        assignee: text('assignee'),
+        rowTruncated: true,
+    };
+}
+export function boundManagedAgentMcpToolResult(toolName, text) {
+    const originalBytes = utf8ByteLength(text);
+    if (toolName !== 'list_tasks') {
+        return originalBytes <= MANAGED_AGENT_TOOL_RESULT_MAX_BYTES
+            ? { text, rejected: false }
+            : oversizedManagedAgentToolResult(toolName, originalBytes);
+    }
+    let parsed;
+    try {
+        const candidate = JSON.parse(text);
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+            return originalBytes <= MANAGED_AGENT_TOOL_RESULT_MAX_BYTES
+                ? { text, rejected: false }
+                : oversizedManagedAgentToolResult(toolName, originalBytes);
+        }
+        parsed = candidate;
+    }
+    catch {
+        return originalBytes <= MANAGED_AGENT_TOOL_RESULT_MAX_BYTES
+            ? { text, rejected: false }
+            : oversizedManagedAgentToolResult(toolName, originalBytes);
+    }
+    const sourceTasksRaw = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+    const sourceTasks = sourceTasksRaw.map(compactManagedAgentTaskRow);
+    const truncatedRows = sourceTasks.reduce((count, task) => (task && typeof task === 'object' && task.rowTruncated === true
+        ? count + 1
+        : count), 0);
+    const tasks = sourceTasks.slice();
+    const sourcePagination = parsed.pagination && typeof parsed.pagination === 'object'
+        ? parsed.pagination
+        : {};
+    const offset = Number.isFinite(Number(sourcePagination.offset))
+        ? Math.max(0, Math.floor(Number(sourcePagination.offset)))
+        : 0;
+    const sourceHasMore = sourcePagination.hasMore === true;
+    const buildPayload = () => {
+        const omittedTasks = sourceTasks.length - tasks.length;
+        const hasMore = sourceHasMore || omittedTasks > 0;
+        return {
+            ...parsed,
+            tasks,
+            pagination: {
+                ...sourcePagination,
+                offset,
+                returned: tasks.length,
+                hasMore,
+                nextOffset: hasMore ? offset + tasks.length : null,
+            },
+            ...(omittedTasks > 0 || truncatedRows > 0 ? {
+                truncation: {
+                    reason: 'managed-agent-result-byte-limit',
+                    maxBytes: MANAGED_AGENT_TOOL_RESULT_MAX_BYTES,
+                    originalBytes,
+                    omittedTasks,
+                    truncatedRows,
+                },
+            } : {}),
+        };
+    };
+    let boundedText = JSON.stringify(buildPayload());
+    while (tasks.length > 0 && utf8ByteLength(boundedText) > MANAGED_AGENT_TOOL_RESULT_MAX_BYTES) {
+        tasks.pop();
+        boundedText = JSON.stringify(buildPayload());
+    }
+    return utf8ByteLength(boundedText) <= MANAGED_AGENT_TOOL_RESULT_MAX_BYTES
+        ? { text: boundedText, rejected: false }
+        : oversizedManagedAgentToolResult(toolName, originalBytes);
+}
+function buildManagedAgentToolResultMessage(result, workflowReminder) {
+    const message = [
+        `Taskforce tool ${result.name} ${result.ok ? 'returned' : 'failed'}:`,
+        result.text,
+        '',
+        workflowReminder,
+        'Use this Taskforce tool result to answer the user. If another Taskforce tool is required, emit exactly one more tool-call JSON object; otherwise answer normally.',
+    ].filter(Boolean).join('\n');
+    if (utf8ByteLength(message) <= MANAGED_AGENT_TOOL_RESULT_MESSAGE_MAX_BYTES)
+        return message;
+    return [
+        `Taskforce tool ${result.name} failed:`,
+        oversizedManagedAgentToolResult(result.name, utf8ByteLength(result.text)).text,
+        '',
+        'Use a narrower Taskforce read before answering the user.',
+    ].join('\n');
+}
+export async function prepareTaskforceAgentMcpBridge(input) {
+    if (!input.core)
+        return null;
+    if (input.runtimeMode !== 'cloud') {
+        throw new TaskforceRuleError('Taskforce Agent execution requires the authenticated cloud model gateway.', 409, 'TASKFORCE_AGENT_CLOUD_RUNTIME_REQUIRED');
+    }
+    const managedToolProfile = input.toolProfile || MCP_MANAGED_AGENT_DEFAULT_PROFILE;
+    const managedToolNames = new Set(resolveManagedAgentMcpToolNames(input.toolPolicy, managedToolProfile));
+    if (input.readOnly) {
+        for (const toolName of managedToolNames) {
+            if (MCP_TOOL_REGISTRY[toolName].mutating)
+                managedToolNames.delete(toolName);
+        }
+    }
+    if (!input.agentProfileId)
+        managedToolNames.delete('complete_workflow_step');
+    const runtime = createTaskforceMcpServer({
+        core: input.core,
+        workspaceId: input.workspaceId,
+        runtimeMode: input.runtimeMode,
+        toolProfile: getManagedAgentMcpRuntimeProfile(managedToolProfile),
+        logStartup: false,
+        auth: {
+            scopes: getManagedAgentMcpToolScopes(managedToolProfile),
+            userId: input.actorUserId || null,
+            aiProfileId: input.agentProfileId || null,
+            actorType: input.actorUserId ? 'user' : 'token',
+            aiProfileName: input.agentName || 'Taskforce Agent',
+            aiProfileProvider: input.providerKey || 'taskforce_hq',
+            aiProfileModel: input.modelKey || null,
+            aiProfileSurfaceType: 'agent',
+        },
+    });
+    const tools = (await listRuntimeTools(runtime))
+        .filter((tool) => managedToolNames.has(tool.name))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    if (tools.length === 0)
+        return null;
+    const availableToolNames = new Set(tools.map((tool) => tool.name));
+    const callTool = getRuntimeHandler(runtime, 'tools/call');
+    return {
+        system: buildToolInstructions(input.system, tools, input.allowedMutationTaskId, input.readOnly),
+        availableToolNames: Array.from(availableToolNames),
+        toolContractHash: hashTaskforceAgentMcpToolContract(tools),
+        parseToolCall: (text) => parseTaskforceAgentMcpToolCall(text, availableToolNames),
+        executeToolCall: async (call) => {
+            if (!availableToolNames.has(call.name)) {
+                return buildTaskScopeFailure(call, `Taskforce refused ${call.name}: this tool is not enabled for this agent.`);
+            }
+            const scopeFailure = validateTaskforceAgentToolCallScope(call, input.allowedMutationTaskId);
+            if (scopeFailure)
+                return scopeFailure;
+            const effectiveCall = normalizeManagedAgentMcpToolCall(call);
+            const result = await callTool({
+                jsonrpc: '2.0',
+                id: `taskforce-agent-tool-${effectiveCall.name}`,
+                method: 'tools/call',
+                params: {
+                    name: effectiveCall.name,
+                    arguments: effectiveCall.arguments,
+                },
+            }, {});
+            const bounded = boundManagedAgentMcpToolResult(effectiveCall.name, extractToolResultText(result));
+            return {
+                name: effectiveCall.name,
+                arguments: effectiveCall.arguments,
+                ok: result?.isError !== true && !bounded.rejected,
+                text: bounded.text,
+            };
+        },
+        buildToolResultMessage: (result) => {
+            const workflowReminder = availableToolNames.has('complete_workflow_step')
+                && (result.name !== 'complete_workflow_step' || !result.ok)
+                ? 'If this work fulfills a workflow step, do not claim completion yet. Use get_task_workflow if needed; when comment evidence is required, add the comment and pass its returned id to complete_workflow_step.'
+                : '';
+            return buildManagedAgentToolResultMessage(result, workflowReminder);
+        },
+    };
+}
+export function serializeTaskforceAgentMcpToolResult(result) {
+    return {
+        name: result.name,
+        arguments: result.arguments,
+        ok: result.ok,
+        text: result.text,
+    };
+}

package/dist/shared/agentRoleDefinition.d.ts

@@ -0,0 +1,34 @@
+export declare const AGENT_ROLE_SCHEMA_VERSION: 1;
+export type AgentRoleLifecycleStatus = 'active' | 'retired';
+export interface AgentRoleDefinitionV1 {
+    schemaVersion: typeof AGENT_ROLE_SCHEMA_VERSION;
+    name: string;
+    shortDescription: string;
+    purpose: string;
+    responsibilities: string[];
+    expectedOutputs: string[];
+    workingGuidance?: string;
+    recommendations: {
+        skillRefs: string[];
+        capabilityGroups: string[];
+    };
+}
+export interface AgentRoleDefinitionIssue {
+    code: string;
+    path: string;
+    message: string;
+}
+export interface AgentRoleDefinitionInspection {
+    definition: AgentRoleDefinitionV1 | null;
+    issues: AgentRoleDefinitionIssue[];
+}
+export declare function inspectAgentRoleDefinition(value: unknown): AgentRoleDefinitionInspection;
+export declare class AgentRoleDefinitionValidationError extends Error {
+    readonly issues: AgentRoleDefinitionIssue[];
+    readonly code = "AGENT_ROLE_DEFINITION_INVALID";
+    readonly statusCode = 400;
+    constructor(issues: AgentRoleDefinitionIssue[]);
+}
+export declare function normalizeAgentRoleDefinition(value: unknown): AgentRoleDefinitionV1;
+export declare function serializeCanonicalAgentRoleDefinition(value: AgentRoleDefinitionV1): string;
+export declare function compileAgentRolePromptContent(definition: AgentRoleDefinitionV1): string;