agentic-engineering-harness 0.10.6 → 0.11.0

package/dist/releases/release-1791192277957-18102-9ef5d8fa/candidates/repairScope.d.ts

@@ -0,0 +1,277 @@
+import type { HarnessProjectConfig, TaskContract, ValidationCheck, WorkerSession } from "../core/types.js";
+import { type ProductChoiceRequestContentV1 } from "../operations/state.js";
+import { HumanDecisionLedgerV2, type DecisionChoiceV1, type HumanDecisionBindingV2, type HumanDecisionV2 } from "../security/humanDecision.js";
+/**
+ * Out-of-scope-blocker → bounded-replan channel.
+ *
+ * Mechanism classification (decision-mechanism invariant):
+ * - Blocker parsing/validation, amendment bounding, contract amendment,
+ *   reseal and forbidden-scope filtering are DETERMINISTIC.
+ * - Scope-amendment authority is HUMAN via the canonical HumanDecisionLedgerV2
+ *   product-choice channel (suspendOperationForProductChoice +
+ *   productChoiceForRequest with binding + consumeExact). A caller-supplied
+ *   `{approved, decidedBy}` string alone NEVER authorizes an amendment; only a
+ *   ledger-consumed CHOOSE decision with a matching operation/candidate/policy/
+ *   epoch binding for the exact blocker paths authorizes
+ *   applyRepairScopeAmendment. The deterministic controller applies the
+ *   amendment, persists it, reseals, and retries exactly once.
+ * - No model output selects tools, grants capability, or bypasses gates.
+ */
+export declare const REPAIR_SCOPE_BLOCKER_VERSION: 1;
+export declare const MAX_REPAIR_SCOPE_BLOCKER_FILES_V1 = 8;
+export declare const MAX_REPAIR_SCOPE_AMENDMENTS_PER_TASK_V1 = 1;
+/**
+ * Amendable scope denials: dependency manifests that a ledger-approved
+ * amendment may exempt for a single retry. Everything else in the
+ * default-deny protected set is HARD-protected (never exemptible).
+ */
+export declare const REPAIR_AMENDABLE_MANIFEST_PATHS: readonly ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"];
+/**
+ * DETERMINISTIC hard-protected paths (never exemptible): frozen TaskContract,
+ * seal, validators, acceptance/spec files, and policy paths. A blocker
+ * intersecting any of these is rejected as BLOCKED citing non-exemptible
+ * with no suspend/approve path. Dependency manifests (see
+ * REPAIR_AMENDABLE_MANIFEST_PATHS) are the amendable subset of the
+ * default-deny set.
+ */
+export declare function repairHardProtectedPaths(config: HarnessProjectConfig, contract: TaskContract): string[];
+/**
+ * DETERMINISTIC hard-protection gate: returns the subset of `paths` that
+ * intersect HARD-protected patterns (exact or `/**` variants). Empty means
+ * amendable (or already allowed); non-empty means non-exemptible.
+ */
+export declare function findRepairHardProtectedViolations(paths: readonly string[], config: HarnessProjectConfig, contract: TaskContract): string[];
+/**
+ * DETERMINISTIC BLOCKED check for non-exemptible paths. Cites the exact
+ * hard-protected files and states there is no suspend/approve path.
+ */
+export declare function repairScopeNonExemptibleValidationCheck(blocker: RepairScopeBlockerReceiptV1, hardPaths: readonly string[]): ValidationCheck;
+export interface RepairScopeNeededFileV1 {
+    path: string;
+    reason: string;
+}
+export interface RepairScopeBlockerReceiptV1 {
+    version: 1;
+    /** Deterministic mechanism marker: the receipt is controller-validated, never model authority. */
+    mechanism: "DETERMINISTIC";
+    operationId: string;
+    taskId: string;
+    workUnitId: string;
+    participantId?: string;
+    declaredAt: string;
+    filesNeededOutsideScope: RepairScopeNeededFileV1[];
+    digest: string;
+}
+export interface RepairScopeAmendmentV1 {
+    version: 1;
+    /** Deterministic mechanism marker: the controller applied a ledger-consumed human approval, never model authority. */
+    mechanism: "DETERMINISTIC";
+    operationId: string;
+    taskId: string;
+    blockerDigest: string;
+    exemptedPaths: string[];
+    decidedBy: "lead" | "human";
+    decisionReason: string;
+    decidedAt: string;
+    /** Ledger provenance: the exact consumed HumanDecision that authorized this amendment. */
+    decisionId: string;
+    requestId: string;
+    decidedActor: string;
+    amendedScope: string[];
+    contractPath: string;
+    sealPath: string;
+    amendmentPath: string;
+    amendmentDigest: string;
+}
+/**
+ * Canonical repair-scope product-choice IDs. The scope-amendment question is a
+ * product choice over the exact blocker-declared paths: approve exactly those
+ * paths (bounded amendment + reseal + single retry) or deny (BLOCKED stands).
+ * Exact paths only; no wildcards, no expansion.
+ */
+export declare const REPAIR_SCOPE_APPROVE_CHOICE_ID: "approve-exact-paths";
+export declare const REPAIR_SCOPE_DENY_CHOICE_ID: "deny-scope-expansion";
+/**
+ * Ledger-gated authorization for a scope amendment. A caller-supplied
+ * approved/decidedBy string alone is never sufficient; only this
+ * ledger-consumed decision with a matching binding authorizes
+ * applyRepairScopeAmendment.
+ */
+export interface RepairScopeLedgerAuthorizationV1 {
+    /** The ledger-consumed CHOOSE decision (kind CHOOSE, PRODUCT_CHOICE purpose). */
+    decision: HumanDecisionV2;
+    /** The current operation/candidate/policy/epoch binding the decision was consumed under. */
+    binding: HumanDecisionBindingV2;
+    /** The suspend-created product-choice request ID the decision answers. */
+    requestId: string;
+}
+export declare function isSafeRepairScopePath(value: string): boolean;
+export declare function normalizeRepairScopePath(value: string): string;
+/**
+ * DETERMINISTIC parse of the Repairer `repair-result` no-mutation report.
+ * Returns the declared needed files when stdout/stderr carries a schema-valid
+ * `repair-result` payload with a non-empty `filesNeededOutsideScope`, else
+ * undefined. Never throws for absent/invalid markers; the caller decides the
+ * typed outcome. Model content, deterministic validation.
+ */
+export declare function parseRepairScopeBlockerFromSession(session: Pick<WorkerSession, "stdout" | "stderr">): RepairScopeNeededFileV1[] | undefined;
+export declare function repairScopeBlockerDigest(blocker: Omit<RepairScopeBlockerReceiptV1, "digest">): string;
+export declare function createRepairScopeBlockerReceipt(input: {
+    operationId: string;
+    taskId: string;
+    workUnitId: string;
+    participantId?: string;
+    declaredAt?: string;
+    filesNeededOutsideScope: RepairScopeNeededFileV1[];
+}): RepairScopeBlockerReceiptV1;
+export declare function assertRepairScopeBlockerReceipt(value: unknown): asserts value is RepairScopeBlockerReceiptV1;
+/**
+ * DETERMINISTIC projection of a blocker receipt into a validation check.
+ * Status is FAIL (fail-closed) with the needed files cited; the controller
+ * treats this as the BLOCKED outcome until a lead-approved amendment reseals.
+ */
+export declare function repairScopeBlockerValidationCheck(blocker: RepairScopeBlockerReceiptV1): ValidationCheck;
+export declare function repairScopeBlockerReceiptPath(root: string, config: HarnessProjectConfig, taskId: string): string;
+export declare function writeRepairScopeBlockerReceipt(root: string, config: HarnessProjectConfig, blocker: RepairScopeBlockerReceiptV1): Promise<string>;
+export declare function repairScopeAmendmentPath(root: string, taskId: string, index?: number): string;
+export declare function listRepairScopeAmendments(root: string, _config: HarnessProjectConfig, taskId: string): Promise<RepairScopeAmendmentV1[]>;
+export declare function assertRepairScopeAmendment(value: unknown): asserts value is RepairScopeAmendmentV1;
+/**
+ * DETERMINISTIC controller-owned bounded replan gate (ledger-gated).
+ *
+ * - Max 1 amendment per task (fail-closed when exhausted).
+ * - ONLY a ledger-consumed HumanDecisionV2 (kind CHOOSE, PRODUCT_CHOICE purpose,
+ *   choiceId `approve-exact-paths`, matching operation/candidate/policy/epoch
+ *   binding, one-time consumeExact receipt) authorizes an amendment. A
+ *   caller-supplied `{approved, decidedBy}` string alone NEVER authorizes; that
+ *   self-label path was deleted. A deny choice returns BLOCKED (fail closed,
+ *   citing the blocker); any missing/invalid/stale provenance throws fail-closed.
+ * - The amendment adds exactly the blocker-declared paths to the TaskContract
+ *   scope allowlist, persists the amended contract YAML, persists a durable
+ *   amendment artifact (seal trail citing the exact ledger decision), and
+ *   deterministically reseals via `sealTask`. No auto-allow, no silent
+ *   expansion, no model authority. Exact paths only.
+ */
+export declare function applyRepairScopeAmendment(input: {
+    root: string;
+    config: HarnessProjectConfig;
+    contract: TaskContract;
+    blocker: RepairScopeBlockerReceiptV1;
+    authorization: RepairScopeLedgerAuthorizationV1;
+    ledger: HumanDecisionLedgerV2;
+}): Promise<{
+    status: "AMENDED";
+    contract: TaskContract;
+    amendment: RepairScopeAmendmentV1;
+} | {
+    status: "BLOCKED";
+    blocker: RepairScopeBlockerReceiptV1;
+    check: ValidationCheck;
+}>;
+/**
+ * DETERMINISTIC repair-scope product choices over the exact blocker paths.
+ * approve-exact-paths authorizes the bounded amendment (exact paths only);
+ * deny-scope-expansion leaves BLOCKED standing. No wildcards, no expansion.
+ */
+export declare function repairScopeProductChoices(blocker: RepairScopeBlockerReceiptV1): DecisionChoiceV1[];
+/**
+ * DETERMINISTIC product-choice request content for a repair-scope blocker.
+ * Exact files + per-file reasons are cited as choices/evidence; the blocker
+ * receipt artifact is the authoritative evidence.
+ */
+export declare function repairScopeProductChoiceContent(blocker: RepairScopeBlockerReceiptV1, evidence: {
+    artifact: string;
+    sha256: string;
+    description: string;
+}): ProductChoiceRequestContentV1;
+export interface RepairScopeSuspendedChoiceV1 {
+    requestId: string;
+    decisionRequest: unknown;
+}
+/**
+ * Suspend the operation for a repair-scope product choice (canonical
+ * HUMAN_REQUIRED channel). The exact blocker files + reasons become the
+ * bounded approve/deny choices with the durable blocker receipt as
+ * authoritative evidence. Fail-closed: suspend errors propagate (caller maps
+ * to BLOCKED citing the blocker).
+ */
+export declare function suspendRepairScopeForProductChoice(input: {
+    controlRoot: string;
+    operationId: string;
+    config: HarnessProjectConfig;
+    blocker: RepairScopeBlockerReceiptV1;
+    contract?: TaskContract;
+}): Promise<RepairScopeSuspendedChoiceV1>;
+export interface RepairScopeChoiceSelectionV1 {
+    requestId: string;
+    decisionId: string;
+    choiceId: string;
+    choice: DecisionChoiceV1;
+    reason: string;
+    decision: HumanDecisionV2;
+    binding: HumanDecisionBindingV2;
+}
+/**
+ * Await the ledger-consumed repair-scope product choice (canonical
+ * productChoiceForRequest + consumeExact pattern). On success the exact choice
+ * is atomically consumed and the operation continuation is marked consumed.
+ * On timeout the operation remains WAITING (human may still decide within
+ * expiry); the caller maps timeout to BLOCKED citing the blocker (fail closed).
+ * Operation-terminal or binding-stale conditions throw fail-closed.
+ */
+export declare function awaitRepairScopeProductChoice(input: {
+    controlRoot: string;
+    operationId: string;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<RepairScopeChoiceSelectionV1>;
+/**
+ * High-level repair-scope blocker resolution for the run.ts validation-repair
+ * loop (the single production amendment path; max 1/task preserved).
+ *
+ * - When an amendment already exists: BLOCKED without a second suspension.
+ * - Otherwise suspends for the bounded approve/deny product choice, awaits the
+ *   ledger-consumed decision, applies the amendment + reseal on approve
+ *   (single retry owned by the caller), and resumes/completes the continuation.
+ * - On deny: resumes/completes and returns BLOCKED citing the blocker.
+ * - On timeout/expiry/terminal/stale (await throws): the operation remains
+ *   WAITING when unanswered (human may still decide within expiry); the caller
+ *   maps to BLOCKED citing the blocker (fail closed, no amendment, no retry).
+ * - No unbounded loops: at most one suspension + one amendment per call, and
+ *   apply enforces max 1/task.
+ */
+export declare function resolveRepairScopeBlockerViaProductChoice(input: {
+    root: string;
+    controlRoot: string;
+    operationId: string;
+    config: HarnessProjectConfig;
+    contract: TaskContract;
+    blocker: RepairScopeBlockerReceiptV1;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<{
+    status: "AMENDED";
+    contract: TaskContract;
+    amendment: RepairScopeAmendmentV1;
+    selection: RepairScopeChoiceSelectionV1;
+} | {
+    status: "BLOCKED";
+    blocker: RepairScopeBlockerReceiptV1;
+    check: ValidationCheck;
+    choiceId?: string;
+}>;
+/**
+ * DETERMINISTIC forbidden-scope projection for an amended retry.
+ * Removes exactly the amendment-exempted paths (plus their `/**` variants)
+ * from the effective forbidden list. The default-deny source
+ * (`repairProtectedPaths`) is unchanged; this only applies the durable
+ * lead-approved exemption for the single retry. All other protected paths
+ * remain denied and silent expansion still throws in the assembler.
+ *
+ * HARD-protection defense: when `hardProtected` is provided, any exempted
+ * path intersecting it throws fail-closed (never exemptible). Callers with
+ * config+contract should pass `repairHardProtectedPaths(config, contract)`;
+ * the amendment-apply and blocker-resolve gates already enforce this before
+ * filtering.
+ */
+export declare function filterForbiddenScopeForAmendment(forbiddenScope: readonly string[], amendment: RepairScopeAmendmentV1, hardProtected?: readonly string[]): string[];