agentic-engineering-harness 0.8.10 → 0.8.12

package/dist/releases/release-1791018659724-16485-1a39cf54/agents/outputContracts.d.ts

@@ -0,0 +1,397 @@
+import { z } from "zod";
+declare const workUnitOutputSchema: z.ZodObject<{
+    id: z.ZodString;
+    objective: z.ZodString;
+    scope: z.ZodArray<z.ZodString>;
+    dependencies: z.ZodArray<z.ZodString>;
+    requirementRefs: z.ZodArray<z.ZodString>;
+    acceptanceRefs: z.ZodArray<z.ZodString>;
+    competencies: z.ZodArray<z.ZodString>;
+    riskTags: z.ZodArray<z.ZodString>;
+    changeKinds: z.ZodArray<z.ZodEnum<{
+        source: "source";
+        test: "test";
+        schema: "schema";
+        config: "config";
+        docs: "docs";
+        dependency: "dependency";
+        infrastructure: "infrastructure";
+        security: "security";
+    }>>;
+    risk: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+        critical: "critical";
+    }>;
+    resourceClaims: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        resource: z.ZodString;
+        mode: z.ZodEnum<{
+            SHARED_READ: "SHARED_READ";
+            EXCLUSIVE_WRITE: "EXCLUSIVE_WRITE";
+            ORDERED_SEQUENCE: "ORDERED_SEQUENCE";
+        }>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const plannerOutputSchema: z.ZodObject<{
+    workUnits: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        objective: z.ZodString;
+        scope: z.ZodArray<z.ZodString>;
+        dependencies: z.ZodArray<z.ZodString>;
+        requirementRefs: z.ZodArray<z.ZodString>;
+        acceptanceRefs: z.ZodArray<z.ZodString>;
+        competencies: z.ZodArray<z.ZodString>;
+        riskTags: z.ZodArray<z.ZodString>;
+        changeKinds: z.ZodArray<z.ZodEnum<{
+            source: "source";
+            test: "test";
+            schema: "schema";
+            config: "config";
+            docs: "docs";
+            dependency: "dependency";
+            infrastructure: "infrastructure";
+            security: "security";
+        }>>;
+        risk: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+            critical: "critical";
+        }>;
+        resourceClaims: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            resource: z.ZodString;
+            mode: z.ZodEnum<{
+                SHARED_READ: "SHARED_READ";
+                EXCLUSIVE_WRITE: "EXCLUSIVE_WRITE";
+                ORDERED_SEQUENCE: "ORDERED_SEQUENCE";
+            }>;
+            order: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    affectedAreas: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    reviewDimensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    validationRequirements: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        id: z.ZodString;
+        property: z.ZodString;
+        kind: z.ZodEnum<{
+            architecture: "architecture";
+            command: "command";
+            "unit-test": "unit-test";
+            "integration-test": "integration-test";
+            bdd: "bdd";
+            "contract-test": "contract-test";
+            "browser-test": "browser-test";
+            "static-security": "static-security";
+            "dependency-security": "dependency-security";
+            policy: "policy";
+            "visual-test": "visual-test";
+        }>;
+        scope: z.ZodArray<z.ZodString>;
+        evidenceNeeded: z.ZodArray<z.ZodString>;
+        requirementRefs: z.ZodArray<z.ZodString>;
+        acceptanceRefs: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    outOfScopeImprovements: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    formalizationNeed: z.ZodOptional<z.ZodEnum<{
+        NONE: "NONE";
+        REQUIRED: "REQUIRED";
+        RECOMMENDED: "RECOMMENDED";
+    }>>;
+    formalizationReason: z.ZodOptional<z.ZodEnum<{
+        OTHER: "OTHER";
+        PRODUCT_UNCERTAINTY: "PRODUCT_UNCERTAINTY";
+        ARCHITECTURE_UNCERTAINTY: "ARCHITECTURE_UNCERTAINTY";
+        REQUIREMENT_CONTRADICTION: "REQUIREMENT_CONTRADICTION";
+        CROSS_COMPONENT_DESIGN: "CROSS_COMPONENT_DESIGN";
+    }>>;
+    formalizationEvidenceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const knowledgePackOutputSchema: z.ZodObject<{
+    pack: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        cacheKey: z.ZodString;
+        topic: z.ZodString;
+        claims: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            statement: z.ZodString;
+            competency: z.ZodString;
+            confidence: z.ZodEnum<{
+                high: "high";
+                medium: "medium";
+                low: "low";
+            }>;
+        }, z.core.$strict>>;
+        sources: z.ZodArray<z.ZodObject<{
+            uri: z.ZodString;
+            kind: z.ZodEnum<{
+                unknown: "unknown";
+                official: "official";
+                repository: "repository";
+                "public-code": "public-code";
+            }>;
+            version: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        retrievedAt: z.ZodString;
+        packDigest: z.ZodString;
+    }, z.core.$strict>;
+    skillCandidate: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        id: z.ZodString;
+        competency: z.ZodString;
+        procedure: z.ZodArray<z.ZodString>;
+        sourcePackDigest: z.ZodString;
+        procedureEvidence: z.ZodArray<z.ZodObject<{
+            stepIndex: z.ZodNumber;
+            claimIds: z.ZodArray<z.ZodString>;
+            sourceUris: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type KnowledgePackOutput = z.infer<typeof knowledgePackOutputSchema>;
+export declare const explorerOutputSchema: z.ZodObject<{
+    summary: z.ZodString;
+    relevantFiles: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        symbols: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            BLOCKED: "BLOCKED";
+            PARTIAL: "PARTIAL";
+            CONFIRMED: "CONFIRMED";
+            NOT_REPRODUCED: "NOT_REPRODUCED";
+        }>;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    moduleBoundaries: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tests: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    dependencies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    risks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    openQuestions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const specAuthoringOutputSchema: z.ZodObject<{
+    change: z.ZodString;
+    status: z.ZodEnum<{
+        BLOCKED: "BLOCKED";
+        READY: "READY";
+    }>;
+    artifacts: z.ZodObject<{
+        proposal: z.ZodOptional<z.ZodString>;
+        design: z.ZodOptional<z.ZodString>;
+        tasks: z.ZodOptional<z.ZodString>;
+        specs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            capability: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    requirements: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    unresolvedDecisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    decisionRequests: z.ZodArray<z.ZodObject<{
+        issue: z.ZodString;
+        whatTried: z.ZodArray<z.ZodString>;
+        whyUnresolvable: z.ZodString;
+        choices: z.ZodArray<z.ZodObject<{
+            choiceId: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodString;
+            consequences: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        workThatCanContinue: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    validationReady: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const implementerOutputSchema: z.ZodObject<{
+    filesChanged: z.ZodArray<z.ZodString>;
+    behaviorImplemented: z.ZodArray<z.ZodString>;
+    decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    assumptions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    risks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    validationCommands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    followUp: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    contractSync: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const findingSchema: z.ZodObject<{
+    id: z.ZodString;
+    severity: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+        critical: "critical";
+        note: "note";
+    }>;
+    category: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        startLine: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    evidence: z.ZodString;
+    impact: z.ZodString;
+    recommendedFix: z.ZodString;
+    requiredCompetencies: z.ZodArray<z.ZodString>;
+    reviewDimensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    exceptionType: z.ZodOptional<z.ZodEnum<{
+        IMPLEMENTATION_DEFECT: "IMPLEMENTATION_DEFECT";
+        SPEC_CONTRADICTION: "SPEC_CONTRADICTION";
+        REQUIRES_PRODUCT_DECISION: "REQUIRES_PRODUCT_DECISION";
+        BLOCKED_EXTERNAL: "BLOCKED_EXTERNAL";
+        SYSTEM_FAILURE: "SYSTEM_FAILURE";
+    }>>;
+}, z.core.$strip>;
+export declare const reviewerOutputSchema: z.ZodObject<{
+    verdict: z.ZodEnum<{
+        FAIL: "FAIL";
+        PASS: "PASS";
+        PASS_WITH_WARNINGS: "PASS_WITH_WARNINGS";
+    }>;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+            critical: "critical";
+            note: "note";
+        }>;
+        category: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            startLine: z.ZodOptional<z.ZodNumber>;
+            endLine: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        evidence: z.ZodString;
+        impact: z.ZodString;
+        recommendedFix: z.ZodString;
+        requiredCompetencies: z.ZodArray<z.ZodString>;
+        reviewDimensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exceptionType: z.ZodOptional<z.ZodEnum<{
+            IMPLEMENTATION_DEFECT: "IMPLEMENTATION_DEFECT";
+            SPEC_CONTRADICTION: "SPEC_CONTRADICTION";
+            REQUIRES_PRODUCT_DECISION: "REQUIRES_PRODUCT_DECISION";
+            BLOCKED_EXTERNAL: "BLOCKED_EXTERNAL";
+            SYSTEM_FAILURE: "SYSTEM_FAILURE";
+        }>>;
+    }, z.core.$strip>>;
+    finalizationSafety: z.ZodEnum<{
+        BLOCKED: "BLOCKED";
+        SAFE: "SAFE";
+        RISK_KNOWN: "RISK_KNOWN";
+    }>;
+    confidence: z.ZodOptional<z.ZodString>;
+    followUp: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const validatorOutputSchema: z.ZodObject<{
+    verdict: z.ZodEnum<{
+        FAIL: "FAIL";
+        PASS: "PASS";
+        WARN: "WARN";
+    }>;
+    checks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            FAIL: "FAIL";
+            PASS: "PASS";
+            WARN: "WARN";
+            SKIP: "SKIP";
+        }>;
+        evidence: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const recoveryOutputSchema: z.ZodObject<{
+    failureType: z.ZodEnum<{
+        PATCH_CONTEXT_MISMATCH: "PATCH_CONTEXT_MISMATCH";
+        TOOL_FAILURE: "TOOL_FAILURE";
+        MISSING_CONTEXT: "MISSING_CONTEXT";
+        WRONG_AGENT: "WRONG_AGENT";
+        VALIDATION_FAILURE: "VALIDATION_FAILURE";
+        REVIEW_FAILURE: "REVIEW_FAILURE";
+        AMBIGUOUS_OUTPUT: "AMBIGUOUS_OUTPUT";
+        CONFLICTING_RESULTS: "CONFLICTING_RESULTS";
+    }>;
+    rationale: z.ZodString;
+    nextAction: z.ZodString;
+}, z.core.$strip>;
+export declare const orchestratorOutputSchema: z.ZodObject<{
+    summary: z.ZodString;
+    delegatedAgents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    validationStatus: z.ZodOptional<z.ZodString>;
+    unresolved: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    finalizationSafe: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const supervisorOutputSchema: z.ZodObject<{
+    summary: z.ZodString;
+    consolidatedFindings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+            critical: "critical";
+            note: "note";
+        }>;
+        category: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            startLine: z.ZodOptional<z.ZodNumber>;
+            endLine: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        evidence: z.ZodString;
+        impact: z.ZodString;
+        recommendedFix: z.ZodString;
+        requiredCompetencies: z.ZodArray<z.ZodString>;
+        reviewDimensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exceptionType: z.ZodOptional<z.ZodEnum<{
+            IMPLEMENTATION_DEFECT: "IMPLEMENTATION_DEFECT";
+            SPEC_CONTRADICTION: "SPEC_CONTRADICTION";
+            REQUIRES_PRODUCT_DECISION: "REQUIRES_PRODUCT_DECISION";
+            BLOCKED_EXTERNAL: "BLOCKED_EXTERNAL";
+            SYSTEM_FAILURE: "SYSTEM_FAILURE";
+        }>>;
+    }, z.core.$strip>>>;
+    sourceFindingIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    conflicts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        summary: z.ZodString;
+        sources: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    missingEvidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    unresolved: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    roadmap: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        phase: z.ZodString;
+        priority: z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+        }>;
+        actions: z.ZodArray<z.ZodString>;
+        findingIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    finalizationSafety: z.ZodEnum<{
+        BLOCKED: "BLOCKED";
+        SAFE: "SAFE";
+        RISK_KNOWN: "RISK_KNOWN";
+    }>;
+}, z.core.$strip>;
+export type WorkUnitOutput = z.infer<typeof workUnitOutputSchema>;
+export type PlannerOutput = z.infer<typeof plannerOutputSchema>;
+export type ExplorerOutput = z.infer<typeof explorerOutputSchema>;
+export type SpecAuthoringOutput = z.infer<typeof specAuthoringOutputSchema>;
+export type NormalizedFinding = z.infer<typeof findingSchema>;
+export type ReviewerOutput = z.infer<typeof reviewerOutputSchema>;
+export type SupervisorOutput = z.infer<typeof supervisorOutputSchema>;
+export declare function validateAgentOutput(contractName: string, value: unknown): {
+    ok: boolean;
+    value?: unknown;
+    issues: string[];
+};
+export declare function knownOutputContracts(): string[];
+export declare function outputJsonSchema(contractName: string): Record<string, unknown> | undefined;
+export {};

package/dist/releases/release-1791018659724-16485-1a39cf54/audit/intentDecision.d.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+export declare const semanticIntentValues: readonly ["informational", "audit", "change", "run", "status", "cancel"];
+export type SemanticIntent = (typeof semanticIntentValues)[number];
+export declare const intentDecisionSourceValues: readonly ["lead-semantic", "explicit-cli", "heuristic-fallback"];
+export type IntentDecisionSource = (typeof intentDecisionSourceValues)[number];
+export declare const intentDecisionResolutionValues: readonly ["resolved", "ambiguous", "unresolved-reference"];
+export type IntentDecisionResolution = (typeof intentDecisionResolutionValues)[number];
+/** The managed Lead supplies meaning and constraints; the tool name supplies the route,
+ * while trusted runtime metadata supplies the user-turn identity. */
+export declare const leadOperationIntentV1Schema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    requestedOutcome: z.ZodString;
+    continuation: z.ZodOptional<z.ZodObject<{
+        operationId: z.ZodString;
+        findingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        taskId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type LeadOperationIntentV1 = z.infer<typeof leadOperationIntentV1Schema>;
+/** Provider-facing JSON Schema kept beside the deterministic Zod contract. */
+export declare const leadOperationIntentV1JsonSchema: {
+    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";
+            };
+        };
+    };
+};
+export declare const intentDecisionV1Schema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    source: z.ZodEnum<{
+        "lead-semantic": "lead-semantic";
+        "explicit-cli": "explicit-cli";
+        "heuristic-fallback": "heuristic-fallback";
+    }>;
+    userTurnId: z.ZodOptional<z.ZodString>;
+    intent: z.ZodEnum<{
+        status: "status";
+        audit: "audit";
+        informational: "informational";
+        change: "change";
+        run: "run";
+        cancel: "cancel";
+    }>;
+    requestedOutcome: z.ZodString;
+    effects: z.ZodObject<{
+        evaluate: z.ZodBoolean;
+        mutateRepository: z.ZodBoolean;
+        executePreparedTask: z.ZodBoolean;
+        deliver: z.ZodBoolean;
+    }, z.core.$strict>;
+    continuation: z.ZodOptional<z.ZodObject<{
+        operationId: z.ZodOptional<z.ZodString>;
+        findingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        taskId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    resolution: z.ZodDefault<z.ZodEnum<{
+        resolved: "resolved";
+        ambiguous: "ambiguous";
+        "unresolved-reference": "unresolved-reference";
+    }>>;
+}, z.core.$strict>;
+export type IntentDecisionV1 = z.infer<typeof intentDecisionV1Schema>;
+export type IntentDecisionRoute = SemanticIntent;
+export interface IntentDecisionValidationSuccess {
+    ok: true;
+    value: IntentDecisionV1;
+}
+export interface IntentDecisionValidationFailure {
+    ok: false;
+    issues: string[];
+}
+export type IntentDecisionValidation = IntentDecisionValidationSuccess | IntentDecisionValidationFailure;
+export declare class InvalidIntentDecisionError extends Error {
+    readonly code = "INVALID_INTENT_DECISION";
+    constructor(message: string);
+}
+/**
+ * Validate only the lead's typed semantic decision. This function deliberately
+ * does not accept a human request and never performs natural-language parsing.
+ */
+export declare function validateIntentDecision(value: unknown): IntentDecisionValidation;
+export declare function parseIntentDecision(value: unknown): IntentDecisionV1;
+export declare function assertIntentDecisionForRoute(value: unknown, route: IntentDecisionRoute): IntentDecisionV1;
+export declare function createIntentDecision(intent: IntentDecisionRoute, requestedOutcome: string, source: IntentDecisionSource, options?: Partial<Pick<IntentDecisionV1, "userTurnId" | "continuation" | "constraints" | "confidence" | "resolution" | "effects">>): IntentDecisionV1;
+/** Build an internal semantic decision from the route-specific MCP tool and bounded Lead intent. */
+export declare function intentDecisionFromLeadOperationIntent(route: Extract<IntentDecisionRoute, "audit" | "change" | "run">, value: unknown, trustedUserTurnId?: string): IntentDecisionV1;
+export declare function defaultEffects(intent: IntentDecisionRoute): IntentDecisionV1["effects"];

package/dist/releases/release-1791018659724-16485-1a39cf54/audit/intentDecision.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+export const semanticIntentValues = ["informational", "audit", "change", "run", "status", "cancel"];
+export const intentDecisionSourceValues = ["lead-semantic", "explicit-cli", "heuristic-fallback"];
+export const intentDecisionResolutionValues = ["resolved", "ambiguous", "unresolved-reference"];
+/** The managed Lead supplies meaning and constraints; the tool name supplies the route,
+ * while trusted runtime metadata supplies the user-turn identity. */
+export const leadOperationIntentV1Schema = z.object({
+    version: z.literal(1),
+    requestedOutcome: z.string().trim().min(1).max(2_000),
+    continuation: z.object({
+        operationId: z.string().trim().min(1).max(200).regex(/^[A-Za-z0-9._-]+$/),
+        findingIds: z.array(z.string().trim().min(1).max(200)).max(100).optional(),
+        taskId: z.string().trim().min(1).max(200).optional()
+    }).strict().optional(),
+    constraints: z.array(z.string().trim().min(1).max(500)).max(32).optional()
+}).strict();
+/** Provider-facing JSON Schema kept beside the deterministic Zod contract. */
+export const leadOperationIntentV1JsonSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["version", "requestedOutcome"],
+    properties: {
+        version: { const: 1 },
+        requestedOutcome: { type: "string", minLength: 1, maxLength: 2_000, pattern: "\\S" },
+        continuation: {
+            type: "object",
+            additionalProperties: false,
+            required: ["operationId"],
+            properties: {
+                operationId: { type: "string", minLength: 1, maxLength: 200, pattern: "^[A-Za-z0-9._-]+$" },
+                findingIds: { type: "array", maxItems: 100, items: { type: "string", minLength: 1, maxLength: 200, pattern: "\\S" } },
+                taskId: { type: "string", minLength: 1, maxLength: 200, pattern: "\\S" }
+            }
+        },
+        constraints: { type: "array", maxItems: 32, items: { type: "string", minLength: 1, maxLength: 500, pattern: "\\S" } }
+    }
+};
+const effectsSchema = z.object({
+    evaluate: z.boolean(),
+    mutateRepository: z.boolean(),
+    executePreparedTask: z.boolean(),
+    deliver: z.boolean()
+}).strict();
+const continuationSchema = z.object({
+    operationId: z.string().min(1).max(200).optional(),
+    findingIds: z.array(z.string().min(1).max(200)).max(100).optional(),
+    taskId: z.string().min(1).max(200).optional()
+}).strict();
+export const intentDecisionV1Schema = z.object({
+    version: z.literal(1),
+    source: z.enum(intentDecisionSourceValues),
+    userTurnId: z.string().min(1).max(200).optional(),
+    intent: z.enum(semanticIntentValues),
+    requestedOutcome: z.string().trim().min(1).max(2_000),
+    effects: effectsSchema,
+    continuation: continuationSchema.optional(),
+    constraints: z.array(z.string().trim().min(1).max(500)).max(32).optional(),
+    confidence: z.number().min(0).max(1).optional(),
+    resolution: z.enum(intentDecisionResolutionValues).default("resolved")
+}).strict();
+export class InvalidIntentDecisionError extends Error {
+    code = "INVALID_INTENT_DECISION";
+    constructor(message) {
+        super(`${"INVALID_INTENT_DECISION"}: ${message}`);
+        this.name = "InvalidIntentDecisionError";
+    }
+}
+/**
+ * Validate only the lead's typed semantic decision. This function deliberately
+ * does not accept a human request and never performs natural-language parsing.
+ */
+export function validateIntentDecision(value) {
+    const parsed = intentDecisionV1Schema.safeParse(value);
+    if (!parsed.success)
+        return { ok: false, issues: parsed.error.issues.map((issue) => `${issue.path.join(".") || "decision"}: ${issue.message}`) };
+    const issues = decisionInvariantIssues(parsed.data);
+    return issues.length ? { ok: false, issues } : { ok: true, value: parsed.data };
+}
+export function parseIntentDecision(value) {
+    const result = validateIntentDecision(value);
+    if (!result.ok)
+        throw new InvalidIntentDecisionError(result.issues.join("; "));
+    return result.value;
+}
+export function assertIntentDecisionForRoute(value, route) {
+    const decision = parseIntentDecision(value);
+    if (decision.intent !== route)
+        throw new InvalidIntentDecisionError(`route ${route} does not match intent ${decision.intent}`);
+    if (decision.resolution !== "resolved" && (route === "change" || route === "run"))
+        throw new InvalidIntentDecisionError(`${route} requires a resolved referent`);
+    return decision;
+}
+export function createIntentDecision(intent, requestedOutcome, source, options = {}) {
+    return parseIntentDecision({
+        version: 1,
+        source,
+        intent,
+        requestedOutcome,
+        effects: options.effects ?? defaultEffects(intent),
+        userTurnId: options.userTurnId,
+        continuation: options.continuation,
+        constraints: options.constraints,
+        confidence: options.confidence,
+        resolution: options.resolution ?? "resolved"
+    });
+}
+/** Build an internal semantic decision from the route-specific MCP tool and bounded Lead intent. */
+export function intentDecisionFromLeadOperationIntent(route, value, trustedUserTurnId) {
+    const parsed = leadOperationIntentV1Schema.safeParse(value);
+    if (!parsed.success) {
+        throw new InvalidIntentDecisionError(parsed.error.issues.map((issue) => `${issue.path.join(".") || "operationIntent"}: ${issue.message}`).join("; "));
+    }
+    return createIntentDecision(route, parsed.data.requestedOutcome, "lead-semantic", {
+        ...(trustedUserTurnId ? { userTurnId: trustedUserTurnId } : {}),
+        ...(parsed.data.continuation ? { continuation: parsed.data.continuation } : {}),
+        ...(parsed.data.constraints ? { constraints: parsed.data.constraints } : {})
+    });
+}
+export function defaultEffects(intent) {
+    switch (intent) {
+        case "informational": return { evaluate: false, mutateRepository: false, executePreparedTask: false, deliver: false };
+        case "audit": return { evaluate: true, mutateRepository: false, executePreparedTask: false, deliver: false };
+        case "change": return { evaluate: false, mutateRepository: true, executePreparedTask: false, deliver: false };
+        case "run": return { evaluate: false, mutateRepository: false, executePreparedTask: true, deliver: false };
+        case "status":
+        case "cancel": return { evaluate: false, mutateRepository: false, executePreparedTask: false, deliver: false };
+    }
+}
+function decisionInvariantIssues(decision) {
+    const issues = [];
+    if (JSON.stringify(decision.effects) !== JSON.stringify(defaultEffects(decision.intent))) {
+        if (decision.effects.deliver)
+            issues.push("effects.deliver must remain false; delivery is controller-owned");
+        issues.push(`${decision.intent} effects must exactly match the deterministic route contract`);
+    }
+    return issues;
+}
+//# sourceMappingURL=intentDecision.js.map