agentic-engineering-harness 0.8.10 → 0.8.11

package/dist/releases/release-1791006063459-16409-661eedf2/operations/mcp.d.ts

@@ -0,0 +1,535 @@
+import { type OperationDigest } from "./digest.js";
+import { type OperationRecordV2 } from "./state.js";
+export interface OperationMcpRequest {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+export type ContextAgentIdentitySource = "argument" | "environment" | "lead-state";
+export interface ContextAgentIdentity {
+    agentId: string;
+    source: ContextAgentIdentitySource;
+}
+export type OperationStatusDetail = "compact" | "full";
+export interface OperationToolErrorV1 {
+    version: 1;
+    code: string;
+    category: "INPUT_CONTRACT" | "CHAIN_LINEAGE" | "OWNER_BOUNDARY" | "AUTHORITY" | "CONTROLLER_STATE" | "CAPACITY" | "NOT_FOUND" | "INTERNAL";
+    path?: string;
+    operationCreated: boolean;
+    recoverable: boolean;
+    retryDisposition: "CORRECT_INPUT" | "CONTINUE_LINKED_OPERATION" | "WAIT_FOR_CAPACITY" | "RETRY_AFTER_CONTROLLER_RECOVERY" | "ESCALATE_TO_OWNER" | "DO_NOT_RETRY";
+    requiresHuman: boolean;
+    relatedOperationId?: string;
+    relationship: "NONE" | "CURRENT_OPERATION" | "CONTINUATION_RELEVANT" | "BOUND_OTHER_LEAD" | "OWNER_ATTENTION" | "HISTORICAL_UNRELATED";
+    nextActions: string[];
+    skillRef: string;
+}
+export declare const operationMcpTools: readonly [{
+    readonly name: "aeh_operation_start_audit";
+    readonly description: "Start a detached supervised AEH AUDIT. Supply the original request and operationIntent.version=1 with requestedOutcome plus optional constraints/continuation; this tool fixes the route and controller-owned effects. Returns a compact digest; do not poll healthy progress.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly request: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 50000;
+                readonly pattern: "\\S";
+            };
+            readonly operationIntent: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["version", "requestedOutcome"];
+                readonly properties: {
+                    readonly version: {
+                        readonly const: 1;
+                    };
+                    readonly requestedOutcome: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 2000;
+                        readonly pattern: "\\S";
+                    };
+                    readonly continuation: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["operationId"];
+                        readonly properties: {
+                            readonly operationId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 200;
+                                readonly pattern: "^[A-Za-z0-9._-]+$";
+                            };
+                            readonly findingIds: {
+                                readonly type: "array";
+                                readonly maxItems: 100;
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly maxLength: 200;
+                                    readonly pattern: "\\S";
+                                };
+                            };
+                            readonly taskId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 200;
+                                readonly pattern: "\\S";
+                            };
+                        };
+                    };
+                    readonly constraints: {
+                        readonly type: "array";
+                        readonly maxItems: 32;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 500;
+                            readonly pattern: "\\S";
+                        };
+                    };
+                };
+            };
+            readonly files: {
+                readonly type: "array";
+                readonly maxItems: 100;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 500;
+                    readonly pattern: "\\S";
+                };
+            };
+            readonly domains: {
+                readonly type: "array";
+                readonly maxItems: 64;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 500;
+                    readonly pattern: "\\S";
+                };
+            };
+            readonly risk: {
+                readonly type: "string";
+                readonly enum: readonly ["low", "medium", "high"];
+            };
+            readonly reviewers: {
+                readonly type: "array";
+                readonly maxItems: 32;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 200;
+                    readonly pattern: "\\S";
+                };
+            };
+        };
+        readonly required: readonly ["request", "operationIntent"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_operation_start_run";
+    readonly description: "Start detached supervised execution of an already prepared/sealed AEH task. Supply taskId and version 1 operationIntent with requestedOutcome plus optional constraints/continuation; route effects and trusted user-turn identity are controller-derived. Do not poll healthy progress.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly taskId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "^[A-Za-z0-9._-]+$";
+            };
+            readonly operationIntent: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["version", "requestedOutcome"];
+                readonly properties: {
+                    readonly version: {
+                        readonly const: 1;
+                    };
+                    readonly requestedOutcome: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 2000;
+                        readonly pattern: "\\S";
+                    };
+                    readonly continuation: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["operationId"];
+                        readonly properties: {
+                            readonly operationId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 200;
+                                readonly pattern: "^[A-Za-z0-9._-]+$";
+                            };
+                            readonly findingIds: {
+                                readonly type: "array";
+                                readonly maxItems: 100;
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly maxLength: 200;
+                                    readonly pattern: "\\S";
+                                };
+                            };
+                            readonly taskId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 200;
+                                readonly pattern: "\\S";
+                            };
+                        };
+                    };
+                    readonly constraints: {
+                        readonly type: "array";
+                        readonly maxItems: 32;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 500;
+                            readonly pattern: "\\S";
+                        };
+                    };
+                };
+            };
+            readonly profile: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "\\S";
+            };
+            readonly priority: {
+                readonly type: "integer";
+                readonly minimum: 0;
+                readonly maximum: 100;
+            };
+        };
+        readonly required: readonly ["taskId", "operationIntent"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_operation_start_change";
+    readonly description: "Start a durable CHANGE. Supply the original request and version 1 operationIntent with requestedOutcome plus optional constraints/continuation. Preserve commit/push/PR intent in the request; route effects and delivery authority are controller-owned. Returns a compact digest.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly request: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 50000;
+                readonly pattern: "\\S";
+            };
+            readonly operationIntent: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["version", "requestedOutcome"];
+                readonly properties: {
+                    readonly version: {
+                        readonly const: 1;
+                    };
+                    readonly requestedOutcome: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 2000;
+                        readonly pattern: "\\S";
+                    };
+                    readonly continuation: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["operationId"];
+                        readonly properties: {
+                            readonly operationId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 200;
+                                readonly pattern: "^[A-Za-z0-9._-]+$";
+                            };
+                            readonly findingIds: {
+                                readonly type: "array";
+                                readonly maxItems: 100;
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly maxLength: 200;
+                                    readonly pattern: "\\S";
+                                };
+                            };
+                            readonly taskId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 200;
+                                readonly pattern: "\\S";
+                            };
+                        };
+                    };
+                    readonly constraints: {
+                        readonly type: "array";
+                        readonly maxItems: 32;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 500;
+                            readonly pattern: "\\S";
+                        };
+                    };
+                };
+            };
+            readonly title: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "\\S";
+            };
+            readonly taskId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "^[A-Za-z0-9._-]+$";
+            };
+            readonly files: {
+                readonly type: "array";
+                readonly maxItems: 100;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 500;
+                    readonly pattern: "\\S";
+                };
+            };
+            readonly domains: {
+                readonly type: "array";
+                readonly maxItems: 64;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 500;
+                    readonly pattern: "\\S";
+                };
+            };
+            readonly acceptance: {
+                readonly type: "array";
+                readonly maxItems: 64;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 500;
+                    readonly pattern: "\\S";
+                };
+            };
+            readonly risk: {
+                readonly type: "string";
+                readonly enum: readonly ["low", "medium", "high"];
+            };
+            readonly profile: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "\\S";
+            };
+            readonly priority: {
+                readonly type: "integer";
+                readonly minimum: 0;
+                readonly maximum: 100;
+            };
+        };
+        readonly required: readonly ["request", "operationIntent"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_informational_context";
+    readonly description: "Answer a purely informational repository question with bounded read-only repository context. This never creates an operation, TaskContract, audit report, reviewer, or delivery artifact.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly request: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 50000;
+                readonly pattern: "\\S";
+            };
+        };
+        readonly required: readonly ["request"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_informational_evidence";
+    readonly description: "Retrieve one explicitly referenced repository evidence range for an informational answer. New refs carry file identity and may add &read=<start>-<end> for a later bounded range. This is lazy, read-only, and operation-free; the compact informational context must be used first.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly evidenceRef: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 2000;
+                readonly pattern: "^repo://.+#sha256=[a-f0-9]{64}(?:&file-sha256=[a-f0-9]{64})?(?:&range=\\d+-\\d+)?(?:&read=\\d+-\\d+)?$";
+            };
+            readonly maxTokens: {
+                readonly type: "integer";
+                readonly minimum: 1;
+            };
+        };
+        readonly required: readonly ["evidenceRef"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_operation_digest";
+    readonly description: "Read a compact, read-only operation digest: status, phase, revision, participant counts, supervisor state, attention and result references. Use this for normal lead inspection instead of the full OperationRecord.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly operationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "^[A-Za-z0-9._-]+$";
+            };
+        };
+        readonly required: readonly ["operationId"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_operation_status";
+    readonly description: "Read operation status without acknowledging it. Default detail=compact returns the same bounded digest as aeh_operation_digest. Use detail=full only for exceptional diagnostics or one-time terminal result inspection; it returns the authoritative OperationRecord.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly operationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "^[A-Za-z0-9._-]+$";
+            };
+            readonly detail: {
+                readonly type: "string";
+                readonly enum: readonly ["compact", "full"];
+            };
+        };
+        readonly required: readonly ["operationId"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_operation_recover_participant";
+    readonly description: "As the bound Lead, continue or resume one participant or request a controller-owned rotation/replan/split/reassignment under the frozen Owner policy. Requires an exact binding digest and current durable activity evidence; it cannot widen policy or exceed an Owner hard boundary.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["operationId", "participantId", "executionBindingDigest", "action", "evidenceIds", "reason"];
+        readonly properties: {
+            readonly operationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "^[A-Za-z0-9._-]+$";
+            };
+            readonly participantId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "^[A-Za-z0-9._-]+$";
+            };
+            readonly executionBindingDigest: {
+                readonly type: "string";
+                readonly minLength: 64;
+                readonly maxLength: 64;
+                readonly pattern: "^[a-f0-9]{64}$";
+            };
+            readonly action: {
+                readonly enum: readonly ["CONTINUE", "RESUME_SAME_SESSION", "RETRY_PARTICIPANT", "ROTATE_SESSION", "REPLAN", "SPLIT_WORK", "REASSIGN", "FAIL"];
+            };
+            readonly evidenceIds: {
+                readonly type: "array";
+                readonly minItems: 1;
+                readonly maxItems: 12;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 500;
+                    readonly pattern: "\\S";
+                };
+            };
+            readonly reason: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 2000;
+                readonly pattern: "\\S";
+            };
+        };
+    };
+}, {
+    readonly name: "aeh_operation_ack";
+    readonly description: "Acknowledge exactly one current durable operation revision as the bound interactive lead without reading the full OperationRecord. Use after consuming a blocked/terminal continuation event; never use as a progress poll.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly operationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "^[A-Za-z0-9._-]+$";
+            };
+            readonly revision: {
+                readonly type: "integer";
+                readonly minimum: 1;
+            };
+        };
+        readonly required: readonly ["operationId", "revision"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_operation_portfolio";
+    readonly description: "Read the compact project operation portfolio used by the thin lead to manage multiple concurrent supervised operations without multiplexing child timelines.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_operation_cancel";
+    readonly description: "Cancel an AEH operation and return its compact terminal digest. The detached liveness monitor owns eventual lead continuation/recovery.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly operationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "^[A-Za-z0-9._-]+$";
+            };
+        };
+        readonly required: readonly ["operationId"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "aeh_context_status";
+    readonly description: "Read the managed lead's canonical Paseo AgentSnapshot context usage. No agentId is required for a normal managed lead; durable lead-session identity is used when the MCP host does not propagate PASEO_AGENT_ID.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly agentId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly pattern: "\\S";
+            };
+        };
+        readonly additionalProperties: false;
+    };
+}];
+export declare function serveOperationMcp(): Promise<void>;
+export declare function handleOperationMcpRequest(request: OperationMcpRequest): Promise<Record<string, unknown>>;
+export declare function readOperationDigest(root: string, operationId: string): Promise<OperationDigest>;
+export declare function readOperationStatus(root: string, operationId: string, detail?: OperationStatusDetail): Promise<OperationDigest | OperationRecordV2>;
+export declare function acknowledgeOperationRevision(root: string, operationId: string, revision: number, env?: NodeJS.ProcessEnv): Promise<{
+    operationId: string;
+    acknowledgedRevision: number;
+    currentRevision: number;
+    currentRevisionAcknowledged: boolean;
+}>;
+export declare function resolveContextAgentIdentity(root: string, explicitAgentId?: string, env?: NodeJS.ProcessEnv): Promise<ContextAgentIdentity>;
+export declare function operationToolResult(value: unknown, text?: string): Record<string, unknown>;