agentic-engineering-harness 0.8.9 → 0.8.11

package/dist/releases/release-1791006089460-16553-1e312464/core/types.d.ts

@@ -0,0 +1,641 @@
+import type { AssuranceLevel, ImplementationRoute, RouteEvidence } from "../architecture/contracts.js";
+import type { CandidateRevisionV1 } from "../operations/v2Contracts.js";
+import type { CandidateWorkspaceIdentityEvidenceV1 } from "../candidates/identity.js";
+import type { GitHubDeliveryActionV1 } from "../security/actionKinds.js";
+export type CheckStatus = "PASS" | "FAIL" | "SKIP" | "WARN";
+export type ReviewSeverity = "critical" | "high" | "medium" | "low" | "note";
+export type TaskRisk = "low" | "medium" | "high";
+export type PaseoSessionPolicy = "fresh-on-start" | "reuse-compatible" | "resume-explicit";
+export type ValidatorAdapter = "command" | "gherkin" | "bdd" | "test-execution" | "integration-environment" | "contract-test" | "graphify" | "opengrep" | "trivy" | "playwright" | "openapi" | "pact" | "mutation" | "property" | string;
+export interface ValidationCommand {
+    id: string;
+    command: string;
+    required?: boolean;
+    timeoutSeconds?: number;
+    workingDirectory?: string;
+}
+export interface ValidatorSpec {
+    id: string;
+    adapter: ValidatorAdapter;
+    command?: string;
+    required?: boolean;
+    timeoutSeconds?: number;
+    workingDirectory?: string;
+    options?: Record<string, unknown>;
+}
+export type ValidationCapability = "unit-test" | "integration-test" | "bdd" | "contract-test" | "browser-test" | "static-security" | "dependency-security" | "architecture" | "policy" | string;
+export interface ValidationProviderSpec {
+    id: string;
+    capability: ValidationCapability;
+    provider: string;
+    command?: string;
+    required?: boolean;
+    timeoutSeconds?: number;
+    workingDirectory?: string;
+    options?: Record<string, unknown>;
+}
+export interface UsageMetrics {
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    reasoningOutputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+}
+export type ContextMode = "observe" | "enforce";
+export type ContextRole = "explorer" | "planner" | "spec-manager" | "implementer" | "reviewer" | "operation-supervisor" | string;
+export interface ContextBudgetConfig {
+    inputTokens?: number;
+    maxTokens?: number;
+    reserved?: {
+        instructions?: number;
+        normative?: number;
+        evidence?: number;
+        response?: number;
+    };
+}
+export interface ContextConfiguration {
+    mode?: ContextMode;
+    budgets?: {
+        default?: ContextBudgetConfig;
+        agents?: Record<string, ContextBudgetConfig>;
+        phases?: Record<string, ContextBudgetConfig>;
+    };
+    informational?: {
+        targetTokens?: number;
+        softLimitTokens?: number;
+        exceptionalTokens?: number;
+        maxSources?: number;
+        sourceSummaryTokens?: number;
+        maxInitialBytesPerSource?: number;
+        maxInitialBytesTotal?: number;
+    };
+    repositoryMap?: {
+        enabled?: boolean;
+        tokenBudget?: number;
+        maxGraphHops?: number;
+    };
+    semanticRetrieval?: {
+        provider?: "serena" | string;
+        required?: boolean;
+        editing?: boolean;
+    };
+    compression?: {
+        provider?: "headroom" | string;
+        required?: boolean;
+        minTokens?: number;
+        reversible?: boolean;
+        command?: string;
+    };
+    retrieval?: {
+        maxRequestsPerTurn?: number;
+        maxTokensPerRequest?: number;
+        maxTotalTokensPerTurn?: number;
+    };
+    outputPolicy?: {
+        enabled?: boolean;
+        modes?: Record<string, "terse" | "compact" | "normal">;
+    };
+}
+export interface RunMetrics {
+    firstPassSuccess: boolean;
+    repairCount: number;
+    humanInterventions: number;
+    durationMs: number;
+    usage: UsageMetrics;
+}
+export interface ReviewEscalationStage {
+    name: string;
+    action?: "remediate" | "diagnose" | "replan";
+    role?: import("../participants/index.js").CanonicalRole;
+    model?: string;
+}
+export interface McpServerConfig {
+    description?: string;
+    type: "local" | "remote";
+    command?: string[];
+    url?: string;
+    environment?: Record<string, string>;
+    headers?: Record<string, string>;
+    oauth?: boolean;
+    enabled?: boolean;
+    timeoutMs?: number;
+    codemode?: boolean;
+    /** AEH-enforced projection for servers that support a narrower tool surface. */
+    toolPolicy?: {
+        allow?: string[];
+        deny?: string[];
+    };
+}
+export interface OrganizationPolicySource {
+    name: string;
+    path?: string;
+    url?: string;
+    sha256?: string;
+    required?: boolean;
+    publicKey?: string;
+    signature?: string;
+}
+export interface HarnessProjectConfig {
+    version: 1;
+    project: {
+        name: string;
+    };
+    agents?: {
+        configPath?: string;
+        generatedPath?: string;
+        activeProfile?: string;
+        required?: boolean;
+        findingsDir?: string;
+    };
+    controlPlane?: {
+        snapshotDir?: string;
+        include?: string[];
+        required?: boolean;
+    };
+    workflow?: {
+        issueIntake?: {
+            enabled?: boolean;
+            snapshotDir?: string;
+            verifyDriftOnRun?: boolean;
+            requireOpen?: boolean;
+            plannerAgent?: string;
+            autoHandoff?: boolean;
+        };
+        planning?: {
+            enabled?: boolean;
+            plannerAgent?: string;
+            worktreeIsolation?: boolean;
+            barrierValidation?: boolean;
+            maxWaveConcurrency?: number;
+            distributed?: boolean;
+        };
+        reviews?: {
+            enabled?: boolean;
+            directReview?: boolean;
+            leadAcceptance?: boolean;
+            leadAcceptanceDirect?: boolean;
+            /** @deprecated Accepted for old project files but ignored by the convergence engine. */
+            maxRemediationRounds?: number;
+            /** @deprecated Accepted for old project files but superseded by finalQualityGate. */
+            blockingSeverities?: ReviewSeverity[];
+            quality?: {
+                severityPoints?: Partial<Record<ReviewSeverity, number>>;
+            };
+            convergence?: {
+                minimumDebtPointImprovement?: number;
+                stagnationWindow?: number;
+                cycleDetection?: boolean;
+                regressionDetection?: boolean;
+            };
+            finalQualityGate?: {
+                maxBySeverity?: Partial<Record<ReviewSeverity, number>>;
+                maxDebtPoints?: number;
+            };
+            /** Bounded remediation execution budget; exhausting it terminalizes SYSTEM_FAILURE. */
+            escalation?: {
+                stages?: ReviewEscalationStage[];
+                criticalStartStage?: number;
+                replanResumeStage?: number;
+                maxRounds?: number;
+            };
+        };
+    };
+    orchestration?: {
+        provider: "paseo" | "podman" | "none" | string;
+        required?: boolean;
+        worker?: {
+            provider?: string;
+            model?: string;
+            maxRepairAttempts?: number;
+            titlePrefix?: string;
+        };
+        operations?: {
+            /** Scope of explicit Owner boundaries. Failed task chains remain chain-scoped in either mode. */
+            ownerBoundaryScope?: "CHAIN_SCOPED_BOUNDARY" | "PROJECT_OR_OWNER_GLOBAL_BOUNDARY";
+            supervision?: {
+                initializationTimeoutSeconds?: number;
+                turnTimeoutSeconds?: number;
+                context?: {
+                    handoffThreshold?: number;
+                    hardHandoffThreshold?: number;
+                };
+            };
+            liveness?: {
+                hardDeadlineMs?: number;
+                progressLeaseMs?: number;
+                stallWindowMs?: number;
+                providerTurnDeadlineMs?: number;
+                defaultToolDeadlineMs?: number;
+                maxNoProgressRenewals?: number;
+                maxParticipantRestarts?: number;
+                maxLocalRetriesPerFailure?: number;
+                softBudgetThreshold?: number;
+                toolDeadlinesMs?: Record<string, number>;
+            };
+            economicEnvelope?: {
+                initialProviderTurns?: number;
+                supervisorProviderTurns?: number;
+                hardProviderTurns?: number;
+                maxLocalRetries?: number;
+                maxParticipantRestarts?: number;
+                softThreshold?: number;
+                hardToolCalls?: number;
+                hardTotalTokens?: number;
+                hardCostUsd?: number;
+            };
+        };
+        interactive?: {
+            autoSetup?: boolean;
+            webUi?: boolean;
+            leadAgent?: string;
+            /** @deprecated Prefer sessionPolicy. */
+            reuseSession?: boolean;
+            sessionPolicy?: PaseoSessionPolicy;
+            usePaseoTools?: boolean;
+            context?: {
+                pressureThreshold?: number;
+                handoffThreshold?: number;
+                hardHandoffThreshold?: number;
+            };
+            stateDir?: string;
+            title?: string;
+        };
+    };
+    toolchain?: {
+        configPath?: string;
+        lockPath?: string;
+        statePath?: string;
+        generatedMisePath?: string;
+    };
+    mcp?: {
+        servers?: Record<string, McpServerConfig>;
+        benchmark?: {
+            enabled?: boolean;
+            resultsDir?: string;
+            repetitions?: number;
+        };
+        packs?: Record<string, {
+            servers: string[];
+            enabled?: boolean;
+        }>;
+    };
+    delivery?: {
+        stateDir?: string;
+        github?: {
+            enabled?: boolean;
+            allowedActions?: GitHubDeliveryActionV1[];
+            tokenEnv?: string;
+            repository?: string;
+            apiBaseUrl?: string;
+            assignTokenOwner?: boolean;
+            labels?: string[];
+            branchPattern?: string;
+            finalizeOnAcceptance?: boolean;
+            pullRequestDraft?: boolean;
+            pullRequests?: boolean;
+        };
+        paseo?: {
+            enabled?: boolean;
+            createWorkspace?: boolean;
+            autoUseWorkspace?: boolean;
+            worktreeSlugPattern?: string;
+        };
+    };
+    memory?: {
+        provider: "engram" | "none" | string;
+        required?: boolean;
+        benchmark?: {
+            casesDir?: string;
+            resultsDir?: string;
+            providers?: Array<{
+                name: string;
+                command: string;
+                timeoutSeconds?: number;
+            }>;
+        };
+    };
+    codeIntelligence?: {
+        provider: "graphify" | "none" | string;
+        required?: boolean;
+        graphPath?: string;
+        snapshotDir?: string;
+        codeOnly?: boolean;
+        refreshCommand?: string;
+        scheduling?: {
+            useEdges?: boolean;
+            maxGraphHops?: number;
+            maxSharedNodes?: number;
+            centralityConflictThreshold?: number;
+        };
+    };
+    context?: ContextConfiguration;
+    evidence?: {
+        enabled?: boolean;
+        outputDir?: string;
+        requireComplete?: boolean;
+    };
+    organization?: {
+        policyBundles?: {
+            cacheDir?: string;
+            required?: boolean;
+            sources?: OrganizationPolicySource[];
+        };
+    };
+    distributed?: {
+        enabled?: boolean;
+        provider?: "filesystem" | "http" | string;
+        queueDir?: string;
+        endpoint?: string;
+        tokenEnv?: string;
+        pollIntervalMs?: number;
+        leaseSeconds?: number;
+        workerId?: string;
+    };
+    sdd?: {
+        specsDir?: string;
+        contractsDir?: string;
+        reportsDir?: string;
+        repairsDir?: string;
+        runsDir?: string;
+        authoring?: {
+            provider?: "openspec" | "native" | string;
+            schema?: string;
+            managerAgent?: string;
+        };
+    };
+    validation?: {
+        baseRef?: string;
+        commands?: ValidationCommand[];
+        validators?: ValidatorSpec[];
+        providers?: ValidationProviderSpec[];
+        frozenPaths?: string[];
+        requireSeal?: boolean;
+        opa?: {
+            enabled?: boolean;
+            policyDirs?: string[];
+        };
+    };
+    security?: {
+        sandbox?: {
+            provider?: "podman" | "docker" | "none" | string;
+            required?: boolean;
+            image?: string;
+            imageDigest?: string;
+            network?: boolean;
+            extraArgs?: string[];
+            readOnlyRoot?: boolean;
+            ephemeralHome?: boolean;
+            noNewPrivileges?: boolean;
+            capDropAll?: boolean;
+            pidsLimit?: number;
+            memory?: string;
+            cpus?: number;
+            tmpfs?: string[];
+            forceForRisks?: TaskRisk[];
+            environmentAllowlist?: string[];
+            credentialEnvAllowlist?: string[];
+        };
+        isolation?: {
+            required?: boolean;
+            provider?: "bwrap" | string;
+            network?: boolean;
+            environmentAllowlist?: string[];
+        };
+        tools?: string[];
+    };
+    telemetry?: {
+        enabled?: boolean;
+        required?: boolean;
+        localEventsFile?: string;
+        localMetricsFile?: string;
+        exporter?: "none" | "otlp-http-json" | string;
+        endpoint?: string;
+        headers?: Record<string, string>;
+        serviceName?: string;
+    };
+    evals?: {
+        corpusDir?: string;
+        resultsDir?: string;
+        workspacesDir?: string;
+        defaultRuns?: number;
+        confidenceLevel?: number;
+        fullStack?: {
+            enabled?: boolean;
+            required?: boolean;
+            strictSupplyChain?: boolean;
+        };
+    };
+    certification?: {
+        enabled?: boolean;
+        policyPath?: string;
+        provider?: string;
+        fixtureRoot?: string;
+        requireSandbox?: boolean;
+        maxAttempts?: number;
+        maxDurationMs?: number;
+        maxCostUsd?: number;
+        maxTotalTokens?: number;
+    };
+    provenance?: {
+        outputDir?: string;
+        artifact?: string;
+        buildType?: string;
+        required?: boolean;
+        sbom?: {
+            required?: boolean;
+            command?: string;
+        };
+        signing?: {
+            required?: boolean;
+            key?: string;
+        };
+        verification?: {
+            required?: boolean;
+            publicKey?: string;
+        };
+    };
+}
+export interface TaskRequirement {
+    id: string;
+    description?: string;
+    validator?: string;
+    validators?: string[];
+    capabilities?: ValidationCapability[];
+}
+export interface TaskIssueMetadata {
+    provider: "github";
+    repository: string;
+    number: number;
+    url: string;
+    state: string;
+    fetchedAt: string;
+    updatedAt: string;
+    contentSha256: string;
+    snapshotPath: string;
+}
+export interface TaskAuthoringMetadata {
+    provider: string;
+    change: string;
+    sourceSha256: string;
+}
+export interface TaskContract {
+    version: 1;
+    task: {
+        id: string;
+        title: string;
+    };
+    source?: {
+        proposal?: string;
+        spec?: string;
+        design?: string;
+        tasks?: string;
+        acceptance?: string;
+        issue?: string;
+    };
+    authoring?: TaskAuthoringMetadata;
+    issue?: TaskIssueMetadata;
+    git?: {
+        baseRef?: string;
+        originatingBranch?: string;
+    };
+    scope?: {
+        allowed?: string[];
+        forbidden?: string[];
+        frozen?: string[];
+    };
+    routing?: {
+        intent?: string;
+        domains?: string[];
+        risk?: TaskRisk;
+        profile?: string;
+        route?: ImplementationRoute;
+        assurance?: AssuranceLevel;
+        routeEvidence?: RouteEvidence[];
+    };
+    requirements?: TaskRequirement[];
+    constraints?: {
+        breakingApiChanges?: boolean;
+        newDependencies?: boolean;
+        schemaChanges?: boolean;
+        maxFilesChanged?: number;
+        maxLinesAdded?: number;
+        maxLinesDeleted?: number;
+    };
+    impact?: {
+        forbiddenEdges?: string[];
+        forbiddenNodes?: string[];
+        allowedCommunities?: string[];
+    };
+    repair?: {
+        maxAttempts?: number;
+    };
+    verification?: {
+        commands?: ValidationCommand[];
+        validators?: ValidatorSpec[];
+        capabilities?: ValidationCapability[];
+    };
+}
+export interface ValidationCheck {
+    id: string;
+    category: string;
+    status: CheckStatus;
+    message: string;
+    durationMs?: number;
+    details?: Record<string, unknown>;
+}
+export interface ValidationFinding {
+    fingerprint: string;
+    tool: string;
+    kind: string;
+    rule?: string;
+    severity?: string;
+    file?: string;
+    line?: number;
+    endLine?: number;
+    column?: number;
+    endColumn?: number;
+    message?: string;
+    category?: string;
+    cwe?: string[];
+    package?: string;
+    installedVersion?: string;
+    fixedVersion?: string;
+    target?: string;
+    artifact?: string;
+    durationMs?: number;
+    status?: string;
+    details?: Record<string, unknown>;
+}
+export interface ValidationReport {
+    version: 1;
+    taskId: string;
+    status: "PASS" | "FAIL";
+    startedAt: string;
+    finishedAt: string;
+    checks: ValidationCheck[];
+    changedFiles: string[];
+    findings?: ValidationFinding[];
+    candidate?: CandidateRevisionV1;
+    candidateWorkspaceIdentity?: CandidateWorkspaceIdentityEvidenceV1;
+    metadata: {
+        project: string;
+        baseRef: string;
+    };
+}
+export interface RequirementTrace {
+    id: string;
+    proposal: boolean;
+    spec: boolean;
+    design: boolean;
+    acceptance: boolean;
+    tasks: boolean;
+    contract: boolean;
+    validators: string[];
+}
+export interface RepairPacket {
+    version: 1;
+    taskId: string;
+    attempt: number;
+    createdAt: string;
+    failureType?: string;
+    failedAgent?: string;
+    recoveryAction?: string;
+    failures: Array<{
+        id: string;
+        category: string;
+        message: string;
+        details?: Record<string, unknown>;
+    }>;
+}
+export interface WorkerSession {
+    id?: string;
+    provider: string;
+    model?: string;
+    logicalAgent?: string;
+    nativeAgent?: string;
+    runtime?: string;
+    profile?: string;
+    transport?: string;
+    workspaceId?: string;
+    title?: string;
+    operationId?: string;
+    operationKind?: string;
+    operationRevision?: number;
+    supervisorGeneration?: number;
+    phase?: string;
+    status?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    metrics?: UsageMetrics;
+    /** Sanitized provider telemetry carried until the observation-only efficiency writer persists it. */
+    efficiencyTelemetry?: import("../telemetry/efficiency.js").ProviderTelemetryEvidenceV2;
+    participantId?: string;
+    capabilityLeases?: import("../security/authorityV2.js").CapabilityLeaseV1[];
+    executionBinding?: import("../architecture/executionIdentity.js").ExecutionBindingV3;
+    /** Inert Paseo structured-result channel installed before its actual session is bound. */
+    structuredResultChannelId?: string;
+}