@deftai/directive-core 0.96.0 → 0.97.0

package/dist/delivery-attempt/material-delta.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Material-progress evaluation for delivery-attempt circuit breaker (#3143).
+ *
+ * Material progress = verifiable state change that can resolve or advance
+ * beyond the current failure. New revision ids, worker swaps, compaction,
+ * and analysis restatement alone are not material progress.
+ */
+import type { FailureInfo, MaterialDeltaClaim, MaterialDeltaKind } from "./types.js";
+export interface MaterialProgressResult {
+    readonly isMaterial: boolean;
+    readonly classification: MaterialDeltaKind | "none";
+    readonly relevantClaims: readonly MaterialDeltaClaim[];
+    readonly reason: string;
+}
+/**
+ * Whether claimed deltas address the current failure (or advance stage).
+ *
+ * Source-bound evidence: claims whose sourceRevision does not match the
+ * evaluated revision are ignored (cannot treat intermediate evidence as
+ * valid for a later revision).
+ */
+export declare function evaluateMaterialProgress(options: {
+    readonly claims: readonly MaterialDeltaClaim[] | null | undefined;
+    readonly failure: FailureInfo | null | undefined;
+    readonly evaluatedRevision: string;
+    /**
+     * When true (default), evidence/external claims must match evaluatedRevision.
+     * Code/config/stage claims may apply if addresses match even when revision
+     * changed (the new revision *is* the delta carrier).
+     */
+    readonly enforceSourceBoundEvidence?: boolean;
+}): MaterialProgressResult;
+/**
+ * Whether a new revision alone constitutes material progress.
+ * Issue contract: creating a new revision identifier is NOT material progress.
+ */
+export declare function isRevisionChangeMaterial(_previousRevision: string | null, _nextRevision: string): boolean;
+//# sourceMappingURL=material-delta.d.ts.map

package/dist/delivery-attempt/material-delta.js

@@ -0,0 +1,126 @@
+/**
+ * Material-progress evaluation for delivery-attempt circuit breaker (#3143).
+ *
+ * Material progress = verifiable state change that can resolve or advance
+ * beyond the current failure. New revision ids, worker swaps, compaction,
+ * and analysis restatement alone are not material progress.
+ */
+/** Kinds that can count as progress when they address the failing invariant. */
+const PROGRESS_KINDS = new Set([
+    "code",
+    "configuration",
+    "evidence",
+    "external-state",
+    "stage",
+]);
+/**
+ * Whether claimed deltas address the current failure (or advance stage).
+ *
+ * Source-bound evidence: claims whose sourceRevision does not match the
+ * evaluated revision are ignored (cannot treat intermediate evidence as
+ * valid for a later revision).
+ */
+export function evaluateMaterialProgress(options) {
+    const claims = options.claims ?? [];
+    const enforceBound = options.enforceSourceBoundEvidence !== false;
+    const failure = options.failure ?? null;
+    const rev = options.evaluatedRevision;
+    if (claims.length === 0) {
+        return {
+            isMaterial: false,
+            classification: "none",
+            relevantClaims: [],
+            reason: "no material delta claims",
+        };
+    }
+    const relevant = [];
+    for (const claim of claims) {
+        if (claim.kind === "none" || claim.kind === "unrelated") {
+            continue;
+        }
+        if (!PROGRESS_KINDS.has(claim.kind)) {
+            continue;
+        }
+        // Source-bound evidence: intermediate revision evidence is invalid for later rev.
+        if (enforceBound &&
+            (claim.kind === "evidence" || claim.kind === "external-state") &&
+            claim.sourceRevision !== rev) {
+            continue;
+        }
+        if (claimAddressesFailure(claim, failure)) {
+            relevant.push(claim);
+        }
+    }
+    if (relevant.length === 0) {
+        const onlyUnrelated = claims.every((c) => c.kind === "unrelated" || c.kind === "none");
+        return {
+            isMaterial: false,
+            classification: onlyUnrelated ? "unrelated" : "none",
+            relevantClaims: [],
+            reason: onlyUnrelated
+                ? "revision churn / unrelated delta does not address failing invariant"
+                : "claimed deltas do not address the failing invariant or are source-bound mismatched",
+        };
+    }
+    // Prefer strongest classification for observability.
+    const order = [
+        "stage",
+        "code",
+        "configuration",
+        "evidence",
+        "external-state",
+    ];
+    const first = relevant[0];
+    let classification = first !== undefined ? first.kind : "none";
+    for (const k of order) {
+        if (relevant.some((c) => c.kind === k)) {
+            classification = k;
+            break;
+        }
+    }
+    return {
+        isMaterial: true,
+        classification,
+        relevantClaims: relevant,
+        reason: `relevant ${classification} delta addressing failure invariant`,
+    };
+}
+function claimAddressesFailure(claim, failure) {
+    // Stage advancement is always material progress when claimed.
+    if (claim.kind === "stage") {
+        return true;
+    }
+    // No prior failure → any progress-kind claim is material (first recovery path).
+    if (failure === null) {
+        return claim.addresses.length > 0 || PROGRESS_KINDS.has(claim.kind);
+    }
+    if (claim.addresses.length === 0) {
+        // Empty addresses: only treat stage as auto-relevant (handled above).
+        // Code/config without addresses is not trusted as material for a known failure.
+        return false;
+    }
+    const targets = new Set([failure.resourceClass ?? "", failure.stage, failure.code ?? "", failure.fingerprint]
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0));
+    for (const a of claim.addresses) {
+        const key = a.trim().toLowerCase();
+        if (key.length === 0)
+            continue;
+        if (targets.has(key))
+            return true;
+        // Prefix / substring match for component classes (e.g. "auth" matches "auth.permission").
+        for (const t of targets) {
+            if (t.includes(key) || key.includes(t))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Whether a new revision alone constitutes material progress.
+ * Issue contract: creating a new revision identifier is NOT material progress.
+ */
+export function isRevisionChangeMaterial(_previousRevision, _nextRevision) {
+    return false;
+}
+//# sourceMappingURL=material-delta.js.map

package/dist/delivery-attempt/types.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Delivery-attempt ledger and pre-dispatch circuit breaker (#3143).
+ *
+ * Durable attempt state for autonomous delivery / operational-acceptance
+ * loops. Enforcement is mechanical — not prompt-only dual-stop defaults (#2442).
+ */
+/** Schema version for on-disk unit ledgers. */
+export declare const DELIVERY_ATTEMPT_SCHEMA_VERSION: 1;
+/** Default ledger directory under project root. */
+export declare const DELIVERY_ATTEMPT_DIR = ".deft/delivery-attempts";
+export declare const ATTEMPT_STATUSES: readonly ["queued", "running", "succeeded", "failed", "cancelled", "blocked"];
+export type AttemptStatus = (typeof ATTEMPT_STATUSES)[number];
+export declare const ATTEMPT_TRIGGERS: readonly ["automatic", "manual", "retry", "resume", "override"];
+export type AttemptTrigger = (typeof ATTEMPT_TRIGGERS)[number];
+export declare const RETRYABILITY: readonly ["transient", "deterministic", "unknown"];
+export type Retryability = (typeof RETRYABILITY)[number];
+export declare const MATERIAL_DELTA_KINDS: readonly ["code", "configuration", "evidence", "external-state", "stage", "none", "unrelated"];
+export type MaterialDeltaKind = (typeof MATERIAL_DELTA_KINDS)[number];
+/** Pre-dispatch decision codes from issue #3143 expected behavior. */
+export declare const PRE_DISPATCH_DECISIONS: readonly ["ALLOW_FIRST_ATTEMPT", "ALLOW_TRANSIENT_RETRY", "ALLOW_MATERIAL_PROGRESS", "ALLOW_OVERRIDE", "ALLOW_RESUME", "DENY_DUPLICATE_ACTIVE", "BLOCK_NON_RETRYABLE", "BLOCK_NO_MATERIAL_PROGRESS", "BLOCK_REPEATED_UNKNOWN", "BLOCK_ATTEMPT_BUDGET", "BLOCK_ELAPSED_BUDGET", "BLOCK_TOOL_OR_TOKEN_BUDGET"];
+export type PreDispatchDecision = (typeof PRE_DISPATCH_DECISIONS)[number];
+export declare function isAllowDecision(decision: PreDispatchDecision): boolean;
+export declare function isBlockDecision(decision: PreDispatchDecision): boolean;
+export declare function isDenyDecision(decision: PreDispatchDecision): boolean;
+/** Normalized failure identity (no secrets / raw logs). */
+export interface FailureInfo {
+    readonly stage: string;
+    readonly code: string | null;
+    /** Stable redacted digest of stage + code + normalized message class. */
+    readonly fingerprint: string;
+    readonly retryability: Retryability;
+    /** Optional invariant / resource class implicated by the failure. */
+    readonly resourceClass?: string | null;
+}
+/** One material-delta claim attached to an attempt or revision. */
+export interface MaterialDeltaClaim {
+    readonly kind: MaterialDeltaKind;
+    /**
+     * Resource / component classes the delta addresses (matched against
+     * failure.resourceClass or fingerprint stages for relevance).
+     */
+    readonly addresses: readonly string[];
+    /** Source revision the delta was observed for (source-bound evidence). */
+    readonly sourceRevision: string;
+    readonly note?: string | null;
+}
+/** Single attempt row in a unit ledger. */
+export interface DeliveryAttemptRecord {
+    readonly attemptId: string;
+    readonly sourceRevision: string;
+    readonly trigger: AttemptTrigger;
+    readonly status: AttemptStatus;
+    readonly failure: FailureInfo | null;
+    readonly materialDelta: readonly MaterialDeltaClaim[];
+    readonly startedAt: string;
+    readonly endedAt: string | null;
+    readonly elapsedSeconds: number;
+    readonly toolCallCount: number;
+    /** Host token usage when exposed; null when telemetry unavailable. */
+    readonly hostTokenCount: number | null;
+    readonly workerId: string | null;
+    /** External run id for interrupted-run reconciliation. */
+    readonly externalRunId: string | null;
+}
+/** Audited operator override — does not erase history. */
+export interface OperatorOverride {
+    readonly overrideId: string;
+    readonly actor: string;
+    readonly rationale: string;
+    readonly recordedAt: string;
+    /** Bounded: permits this many additional automatic attempts. */
+    readonly allowedAttempts: number;
+    readonly expiresAt: string | null;
+    readonly remainingAttempts: number;
+}
+/** Resume condition that re-enables automatic dispatch. */
+export interface ResumeCondition {
+    readonly kind: "material-delta" | "external-state" | "operator-override" | "monitor-wake";
+    readonly description: string;
+    readonly satisfied: boolean;
+}
+/**
+ * Durable unit ledger keyed by scopeId + targetId + workflowId.
+ * Survives worker replacement, session restart, compaction, and new revisions.
+ */
+export interface DeliveryUnitLedger {
+    readonly schemaVersion: typeof DELIVERY_ATTEMPT_SCHEMA_VERSION;
+    readonly scopeId: string;
+    readonly targetId: string;
+    readonly workflowId: string;
+    readonly phaseId: string;
+    readonly attempts: readonly DeliveryAttemptRecord[];
+    /** Aggregate failed dispatch count in this delivery/acceptance phase. */
+    readonly failedAttemptCount: number;
+    /** Per-fingerprint identical-failure counts (carry across revisions). */
+    readonly sameFailureCounts: Readonly<Record<string, number>>;
+    /** Cumulative elapsed seconds across attempts in this phase. */
+    readonly totalElapsedSeconds: number;
+    readonly totalToolCallCount: number;
+    readonly totalHostTokenCount: number | null;
+    readonly lastFailure: FailureInfo | null;
+    readonly lastMaterialDelta: readonly MaterialDeltaClaim[];
+    readonly lastSourceRevision: string | null;
+    readonly blockedDecision: PreDispatchDecision | null;
+    readonly resumeCondition: ResumeCondition | null;
+    readonly override: OperatorOverride | null;
+    readonly updatedAt: string;
+}
+/** Conservative autonomous-delivery defaults from issue #3143. */
+export interface DeliveryBudgetPolicy {
+    /** Max queued+running attempts per unit (default 1). */
+    readonly maxActiveAttempts: number;
+    /** Max automatic retries after a transient failure (default 1). */
+    readonly maxTransientRetries: number;
+    /**
+     * Identical unknown failures without material progress that block
+     * (default 2 → second identical unknown blocks).
+     */
+    readonly maxUnknownWithoutProgress: number;
+    /** Failed dispatches in one phase before BLOCK_ATTEMPT_BUDGET (default 3). */
+    readonly maxFailedAttempts: number;
+    /** Hard wall-clock budget in seconds (default 3600). */
+    readonly maxElapsedSeconds: number;
+    /** Hard tool-call budget (default 500). */
+    readonly maxToolCalls: number;
+    /**
+     * Host token budget when telemetry is available; null = do not enforce
+     * token budget (elapsed/tool-call still apply).
+     */
+    readonly maxHostTokens: number | null;
+    /**
+     * When true, deterministic failures never get automatic retry without
+     * relevant material delta (default true).
+     */
+    readonly blockDeterministicWithoutDelta: boolean;
+}
+export declare const DEFAULT_DELIVERY_BUDGET_POLICY: DeliveryBudgetPolicy;
+/** Input for a pre-dispatch evaluation. */
+export interface PreDispatchInput {
+    readonly scopeId: string;
+    readonly targetId: string;
+    readonly workflowId: string;
+    readonly phaseId?: string;
+    readonly sourceRevision: string;
+    readonly trigger: AttemptTrigger;
+    /** Optional predicted / prior failure class for same-fingerprint checks. */
+    readonly anticipatedFailure?: FailureInfo | null;
+    /** Material delta claimed for this dispatch relative to last failure. */
+    readonly materialDelta?: readonly MaterialDeltaClaim[];
+    /** Current cumulative usage when re-entering after a partial run. */
+    readonly usage?: {
+        readonly elapsedSeconds?: number;
+        readonly toolCallCount?: number;
+        readonly hostTokenCount?: number | null;
+    };
+    readonly policy?: Partial<DeliveryBudgetPolicy>;
+    /** ISO now override for tests. */
+    readonly now?: string;
+}
+/** Structured decision event for observability (#3143 Observability). */
+export interface PreDispatchDecisionEvent {
+    readonly decision: "allow" | "deny" | "block" | "escalate";
+    readonly reasonCode: PreDispatchDecision;
+    readonly retryability: Retryability | null;
+    readonly failureFingerprint: string | null;
+    readonly attemptCount: number;
+    readonly failedAttemptCount: number;
+    readonly sameFailureCount: number;
+    readonly materialDeltaClassification: MaterialDeltaKind | "none";
+    readonly resumeCondition: ResumeCondition | null;
+    readonly overrideId: string | null;
+    readonly scopeId: string;
+    readonly targetId: string;
+    readonly workflowId: string;
+    readonly sourceRevision: string;
+}
+export interface PreDispatchResult {
+    readonly decision: PreDispatchDecision;
+    readonly allowed: boolean;
+    readonly reason: string;
+    readonly event: PreDispatchDecisionEvent;
+    readonly handoff: TerminalHandoff | null;
+    /** Suggested next attempt id when allowed (caller may override). */
+    readonly nextAttemptId: string | null;
+}
+/** Terminal handoff contract when the circuit breaker blocks. */
+export interface TerminalHandoff {
+    readonly schemaVersion: 1;
+    readonly scopeId: string;
+    readonly targetId: string;
+    readonly workflowId: string;
+    readonly lastSourceRevision: string | null;
+    readonly failure: FailureInfo | null;
+    readonly totalAttempts: number;
+    readonly failedAttemptCount: number;
+    readonly sameFailureCount: number;
+    readonly elapsedSeconds: number;
+    readonly toolCallCount: number;
+    readonly hostTokenCount: number | null;
+    readonly lastMaterialDelta: readonly MaterialDeltaClaim[];
+    readonly denyReason: PreDispatchDecision;
+    readonly nextSafeAction: string;
+    readonly resumeCondition: ResumeCondition;
+    readonly overridePermitted: boolean;
+    readonly recordedAt: string;
+}
+export declare function deliveryUnitKey(scopeId: string, targetId: string, workflowId: string): string;
+export declare function utcIso(now?: Date | string): string;
+export declare function mergePolicy(partial?: Partial<DeliveryBudgetPolicy>): DeliveryBudgetPolicy;
+//# sourceMappingURL=types.d.ts.map

package/dist/delivery-attempt/types.js

@@ -0,0 +1,77 @@
+/**
+ * Delivery-attempt ledger and pre-dispatch circuit breaker (#3143).
+ *
+ * Durable attempt state for autonomous delivery / operational-acceptance
+ * loops. Enforcement is mechanical — not prompt-only dual-stop defaults (#2442).
+ */
+/** Schema version for on-disk unit ledgers. */
+export const DELIVERY_ATTEMPT_SCHEMA_VERSION = 1;
+/** Default ledger directory under project root. */
+export const DELIVERY_ATTEMPT_DIR = ".deft/delivery-attempts";
+export const ATTEMPT_STATUSES = [
+    "queued",
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "blocked",
+];
+export const ATTEMPT_TRIGGERS = ["automatic", "manual", "retry", "resume", "override"];
+export const RETRYABILITY = ["transient", "deterministic", "unknown"];
+export const MATERIAL_DELTA_KINDS = [
+    "code",
+    "configuration",
+    "evidence",
+    "external-state",
+    "stage",
+    "none",
+    "unrelated",
+];
+/** Pre-dispatch decision codes from issue #3143 expected behavior. */
+export const PRE_DISPATCH_DECISIONS = [
+    "ALLOW_FIRST_ATTEMPT",
+    "ALLOW_TRANSIENT_RETRY",
+    "ALLOW_MATERIAL_PROGRESS",
+    "ALLOW_OVERRIDE",
+    "ALLOW_RESUME",
+    "DENY_DUPLICATE_ACTIVE",
+    "BLOCK_NON_RETRYABLE",
+    "BLOCK_NO_MATERIAL_PROGRESS",
+    "BLOCK_REPEATED_UNKNOWN",
+    "BLOCK_ATTEMPT_BUDGET",
+    "BLOCK_ELAPSED_BUDGET",
+    "BLOCK_TOOL_OR_TOKEN_BUDGET",
+];
+export function isAllowDecision(decision) {
+    return decision.startsWith("ALLOW_");
+}
+export function isBlockDecision(decision) {
+    return decision.startsWith("BLOCK_");
+}
+export function isDenyDecision(decision) {
+    return decision.startsWith("DENY_");
+}
+export const DEFAULT_DELIVERY_BUDGET_POLICY = {
+    maxActiveAttempts: 1,
+    maxTransientRetries: 1,
+    maxUnknownWithoutProgress: 2,
+    maxFailedAttempts: 3,
+    maxElapsedSeconds: 3600,
+    maxToolCalls: 500,
+    maxHostTokens: null,
+    blockDeterministicWithoutDelta: true,
+};
+export function deliveryUnitKey(scopeId, targetId, workflowId) {
+    return `${scopeId}\u001f${targetId}\u001f${workflowId}`;
+}
+export function utcIso(now) {
+    if (typeof now === "string" && now.length > 0) {
+        return now.endsWith("Z") ? now.replace(/\.\d{3}Z$/, "Z") : now;
+    }
+    const dt = now instanceof Date ? now : new Date();
+    return dt.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function mergePolicy(partial) {
+    return { ...DEFAULT_DELIVERY_BUDGET_POLICY, ...partial };
+}
+//# sourceMappingURL=types.js.map

package/dist/doctor/index.d.ts

@@ -9,6 +9,7 @@ export * from "./manifest.js";
 export * from "./npm-registry.js";
 export * from "./openclaw-l2-adapter.js";
 export * from "./openclaw-skills.js";
+export * from "./openclaw-soft-rebind.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";

package/dist/doctor/index.js

@@ -9,6 +9,7 @@ export * from "./manifest.js";
 export * from "./npm-registry.js";
 export * from "./openclaw-l2-adapter.js";
 export * from "./openclaw-skills.js";
+export * from "./openclaw-soft-rebind.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";

package/dist/doctor/main.js

@@ -25,6 +25,7 @@ import { parseInstallRootFromAgentsMd } from "./manifest.js";
 import { runNpmRegistryMirrorCheck } from "./npm-registry.js";
 import { runOpenClawL2AdapterCheck } from "./openclaw-l2-adapter.js";
 import { runOpenClawSkillPinsCheck } from "./openclaw-skills.js";
+import { runOpenClawSoftRebindCheck } from "./openclaw-soft-rebind.js";
 import { createPlainSink } from "./output.js";
 import { readTextSafe, resolveFrameworkRootForProject, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
 import { runPayloadStalenessCheck } from "./payload-staleness.js";
@@ -416,6 +417,17 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
+    sink.info("Checking OpenClaw soft AGENTS re-bind skill...");
+    runOpenClawSoftRebindCheck(sink, addFinding, {
+        projectRoot,
+        fixMode,
+        jsonMode,
+        allAgents: flags.openclawAllAgents,
+        seams,
+    });
+    if (!jsonMode) {
+        sink.blank();
+    }
     sink.info("Checking OpenClaw L2 product-command skills...");
     runOpenClawL2AdapterCheck(sink, addFinding, {
         projectRoot,

package/dist/doctor/openclaw-soft-rebind.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Doctor check + --fix wire for OpenClaw soft AGENTS re-bind skill (#3171).
+ *
+ * Complements always-pins (#3001/#3008) and L2 product commands (#3064). This
+ * skill is the required durable soft post-amnesia surface for OpenClaw — not
+ * claimed via file-host PreCompact hooks alone.
+ */
+import { assessOpenClawSoftRebindSkill, depositOpenClawSoftRebindSkill, type OpenClawSoftRebindDepositResult } from "../session/openclaw-soft-rebind-deposit.js";
+import type { OutputSink } from "./output.js";
+import type { DoctorSeams, Finding } from "./types.js";
+/** Stable doctor check id for JSON findings. */
+export declare const OPENCLAW_SOFT_REBIND_CHECK = "openclaw-soft-agents-rebind";
+export interface RunOpenClawSoftRebindOptions {
+    readonly projectRoot: string;
+    readonly fixMode: boolean;
+    readonly jsonMode: boolean;
+    readonly allAgents: boolean;
+    readonly seams?: DoctorSeams;
+}
+/**
+ * Doctor check: OpenClaw soft AGENTS re-bind skill present and current.
+ * No-ops when OpenClaw is not detected. Fix mode deposits managed skill.
+ */
+export declare function runOpenClawSoftRebindCheck(sink: OutputSink, addFinding: (finding: Finding) => void, options: RunOpenClawSoftRebindOptions): OpenClawSoftRebindDepositResult | null;
+export { assessOpenClawSoftRebindSkill, depositOpenClawSoftRebindSkill };
+//# sourceMappingURL=openclaw-soft-rebind.d.ts.map