@deftai/directive-core 0.100.0 → 0.101.0

package/dist/session/deposit-sha.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Deposit fingerprint for orientation fast-path (#3286).
+ *
+ * Covers all refresh inputs named by the dual-path Now AC: payload, templates,
+ * and engine version. When this fingerprint is unchanged, agents:refresh and
+ * verify:cache-fresh may print a one-line sha-match no-op.
+ */
+export declare const DEPOSIT_SHA_HEX_LEN = 12;
+/** Canonical one-line no-op message for deposit-sha fast-path (#3286). */
+export declare const DEPOSIT_SHA_MATCH_NOOP = "unchanged - sha match";
+export interface DepositShaInputs {
+    readonly engineVersion: string;
+    readonly payloadVersion: string;
+    readonly templatesHash: string;
+}
+export interface ComputeDepositShaOptions {
+    readonly projectRoot?: string;
+    readonly frameworkRoot?: string;
+    /** Inject inputs for hermetic tests (skips filesystem/version probes). */
+    readonly inputs?: Partial<DepositShaInputs>;
+    /** Override engine version probe. */
+    readonly readEngineVersion?: () => string;
+    /** Override payload version probe. */
+    readonly readPayloadVersion?: (projectRoot: string, frameworkRoot: string) => string;
+    /** Override templates hash probe. */
+    readonly readTemplatesHash?: (frameworkRoot: string) => string;
+}
+/**
+ * Hash templates that feed agents:refresh (agents-entry + related entry points).
+ * Missing templates yield a stable "missing" sentinel so the fingerprint still
+ * changes when templates appear or disappear.
+ */
+export declare function hashDepositTemplates(frameworkRoot: string): string;
+/**
+ * Resolve payload / content version for the deposit fingerprint.
+ * Prefer live generation token, then VERSION files under framework root.
+ */
+export declare function resolveDepositPayloadVersion(projectRoot: string, frameworkRoot: string): string;
+/** Resolve the three deposit-sha inputs (payload, templates, engine). */
+export declare function resolveDepositShaInputs(options?: ComputeDepositShaOptions): DepositShaInputs;
+/**
+ * Compute the 12-hex deposit fingerprint covering payload + templates + engine.
+ */
+export declare function computeDepositSha(options?: ComputeDepositShaOptions): string;
+/** True when two deposit fingerprints match (case-insensitive, trimmed). */
+export declare function depositShaMatches(a: string | null | undefined, b: string | null | undefined): boolean;
+/** One-line status for orientation / CLI stdout. */
+export declare function formatDepositShaMatchLine(surface: string): string;
+//# sourceMappingURL=deposit-sha.d.ts.map

package/dist/session/deposit-sha.js

@@ -0,0 +1,121 @@
+/**
+ * Deposit fingerprint for orientation fast-path (#3286).
+ *
+ * Covers all refresh inputs named by the dual-path Now AC: payload, templates,
+ * and engine version. When this fingerprint is unchanged, agents:refresh and
+ * verify:cache-fresh may print a one-line sha-match no-op.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { contentRoot } from "../content-root.js";
+import { readCorePackageVersion } from "../engine-version.js";
+import { readLiveGeneration } from "../freshness/generation.js";
+import { frameworkRoot as resolveAgentsFrameworkRoot } from "../platform/agents-md.js";
+export const DEPOSIT_SHA_HEX_LEN = 12;
+/** Canonical one-line no-op message for deposit-sha fast-path (#3286). */
+export const DEPOSIT_SHA_MATCH_NOOP = "unchanged - sha match";
+function sha12(material) {
+    return createHash("sha256").update(material, "utf8").digest("hex").slice(0, DEPOSIT_SHA_HEX_LEN);
+}
+function hashText(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+ * Hash templates that feed agents:refresh (agents-entry + related entry points).
+ * Missing templates yield a stable "missing" sentinel so the fingerprint still
+ * changes when templates appear or disappear.
+ */
+export function hashDepositTemplates(frameworkRoot) {
+    const root = contentRoot(frameworkRoot);
+    const candidates = [
+        join(root, "templates", "agents-entry.md"),
+        join(root, "templates", "agent-prompt-preamble.md"),
+    ];
+    const parts = [];
+    for (const path of candidates) {
+        try {
+            if (!existsSync(path)) {
+                parts.push(`${path}:missing`);
+                continue;
+            }
+            parts.push(`${path}:${hashText(readFileSync(path, "utf8"))}`);
+        }
+        catch {
+            parts.push(`${path}:unreadable`);
+        }
+    }
+    return sha12(parts.join("\n"));
+}
+/**
+ * Resolve payload / content version for the deposit fingerprint.
+ * Prefer live generation token, then VERSION files under framework root.
+ */
+export function resolveDepositPayloadVersion(projectRoot, frameworkRoot) {
+    try {
+        const live = readLiveGeneration(projectRoot);
+        if (live?.contentVersion) {
+            return live.contentVersion;
+        }
+    }
+    catch {
+        // fall through
+    }
+    for (const cand of [
+        join(frameworkRoot, "VERSION"),
+        join(frameworkRoot, "scripts", "VERSION"),
+        join(projectRoot, ".deft-version"),
+    ]) {
+        try {
+            if (existsSync(cand)) {
+                const v = readFileSync(cand, "utf8").trim();
+                if (v.length > 0)
+                    return v;
+            }
+        }
+        catch {
+            // continue
+        }
+    }
+    return "unknown-payload";
+}
+/** Resolve the three deposit-sha inputs (payload, templates, engine). */
+export function resolveDepositShaInputs(options = {}) {
+    const frameworkRoot = resolveAgentsFrameworkRoot({
+        frameworkRoot: options.frameworkRoot,
+    });
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const engineVersion = options.inputs?.engineVersion ?? (options.readEngineVersion ?? readCorePackageVersion)();
+    const payloadVersion = options.inputs?.payloadVersion ??
+        (options.readPayloadVersion ?? resolveDepositPayloadVersion)(projectRoot, frameworkRoot);
+    const templatesHash = options.inputs?.templatesHash ??
+        (options.readTemplatesHash ?? hashDepositTemplates)(frameworkRoot);
+    return { engineVersion, payloadVersion, templatesHash };
+}
+/**
+ * Compute the 12-hex deposit fingerprint covering payload + templates + engine.
+ */
+export function computeDepositSha(options = {}) {
+    const inputs = resolveDepositShaInputs(options);
+    const material = [
+        `engine=${inputs.engineVersion}`,
+        `payload=${inputs.payloadVersion}`,
+        `templates=${inputs.templatesHash}`,
+    ].join("\n");
+    return sha12(material);
+}
+/** True when two deposit fingerprints match (case-insensitive, trimmed). */
+export function depositShaMatches(a, b) {
+    if (a == null || b == null)
+        return false;
+    const left = a.trim().toLowerCase();
+    const right = b.trim().toLowerCase();
+    if (left.length === 0 || right.length === 0)
+        return false;
+    return left === right;
+}
+/** One-line status for orientation / CLI stdout. */
+export function formatDepositShaMatchLine(surface) {
+    return `${surface}: ${DEPOSIT_SHA_MATCH_NOOP}`;
+}
+//# sourceMappingURL=deposit-sha.js.map

package/dist/session/effort-budget.d.ts

@@ -80,6 +80,12 @@ export interface RecommendVerificationDepthInput {
     readonly deepenReserveTurns?: number;
     /** Reserve for a fix after a deeper finding (cost units). Default null (ignore). */
     readonly deepenReserveBudget?: number | null;
+    /**
+     * Minimum remaining fraction of max turns/cost required to deepen after AC bank
+     * (#3285). Default 0.2 (20%). Set null to skip the surplus fraction gate and
+     * use only the absolute reserve.
+     */
+    readonly surplusThreshold?: number | null;
 }
 /**
  * Parse host effort-budget descriptor from env JSON (#1461 / #3266 production wire).

package/dist/session/effort-budget.js

@@ -253,6 +253,8 @@ export function recommendVerificationDepth(input) {
     }
     const reserveTurns = input.deepenReserveTurns ?? 3;
     const reserveBudget = input.deepenReserveBudget ?? null;
+    // #3285: default 20% surplus of max remaining after bank; null disables.
+    const surplusThreshold = input.surplusThreshold === undefined ? 0.2 : input.surplusThreshold;
     const turnsOk = budget.remainingTurns === null || budget.remainingTurns >= reserveTurns;
     const costOk = reserveBudget === null ||
         budget.remainingBudget === null ||
@@ -262,10 +264,26 @@ export function recommendVerificationDepth(input) {
     if (budget.kind === "hard-flag") {
         return "stated-then-deepen";
     }
-    if (turnsOk && costOk) {
-        return "stated-then-deepen";
+    if (!(turnsOk && costOk)) {
+        return "stated-only";
+    }
+    // Surplus fraction gate (#3285): remaining/max must meet threshold on every
+    // known max+remaining axis. When max is unknown, absolute reserve alone applies.
+    if (surplusThreshold !== null) {
+        if (budget.remainingTurns !== null &&
+            budget.maxTurns !== null &&
+            budget.maxTurns > 0 &&
+            budget.remainingTurns / budget.maxTurns < surplusThreshold) {
+            return "stated-only";
+        }
+        if (budget.remainingBudget !== null &&
+            budget.maxBudget !== null &&
+            budget.maxBudget > 0 &&
+            budget.remainingBudget / budget.maxBudget < surplusThreshold) {
+            return "stated-only";
+        }
     }
-    return "stated-only";
+    return "stated-then-deepen";
 }
 /**
  * Operator-visible note when self-imposed deepening is skipped for budget (#1006).

package/dist/session/index.d.ts

@@ -1,10 +1,14 @@
+export * from "./ac-pass-banking.js";
 export * from "./active-cli.js";
 export * from "./compact-ritual.js";
 export * from "./coverage-check-resume-nudge.js";
+export * from "./deposit-sha.js";
 export * from "./effort-budget.js";
 export * from "./git.js";
 export * from "./json.js";
 export * from "./openclaw-soft-rebind-deposit.js";
+export * from "./orientation-compression.js";
+export * from "./orientation-state.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
 export * from "./resume-conditions.js";
@@ -13,5 +17,6 @@ export * from "./session-ready.js";
 export * from "./session-start.js";
 export * from "./session-start-hook.js";
 export * from "./time.js";
+export * from "./toolchain-preflight.js";
 export * from "./verify-session-ritual.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/session/index.js

@@ -1,10 +1,14 @@
+export * from "./ac-pass-banking.js";
 export * from "./active-cli.js";
 export * from "./compact-ritual.js";
 export * from "./coverage-check-resume-nudge.js";
+export * from "./deposit-sha.js";
 export * from "./effort-budget.js";
 export * from "./git.js";
 export * from "./json.js";
 export * from "./openclaw-soft-rebind-deposit.js";
+export * from "./orientation-compression.js";
+export * from "./orientation-state.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
 export * from "./resume-conditions.js";
@@ -13,5 +17,6 @@ export * from "./session-ready.js";
 export * from "./session-start.js";
 export * from "./session-start-hook.js";
 export * from "./time.js";
+export * from "./toolchain-preflight.js";
 export * from "./verify-session-ritual.js";
 //# sourceMappingURL=index.js.map

package/dist/session/orientation-compression.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Orientation compression Now path (#3286 / dual-path #2899).
+ *
+ * Composes doctor + toolchain preflight into session:start as inline sections
+ * with per-section status lines; offers deposit-sha fast-paths for
+ * agents:refresh and verify:cache-fresh; formats compact (opt-in) vs verbose
+ * (default). Does NOT implement unified `deft orient` (Later remains open).
+ */
+import type { DoctorSeams } from "../doctor/types.js";
+import { applyAgentsRefresh } from "../platform/agents-md.js";
+import { type EvaluateOptions, evaluate as evaluateCacheFresh } from "../preflight-cache/evaluate.js";
+import { type ComputeDepositShaOptions } from "./deposit-sha.js";
+import { type OrientationState } from "./orientation-state.js";
+import { type ToolchainPreflightOptions, type ToolchainPreflightResult } from "./toolchain-preflight.js";
+/** Env opt-in for compact orientation output (#3286). Verbose remains default. */
+export declare const ENV_SESSION_COMPACT = "DEFT_SESSION_COMPACT";
+/** Dual-path Later graduation status — Now ships without closing Later (#2899). */
+export declare const ORIENTATION_LATER_STATUS: "open";
+export declare const ORIENTATION_LATER_COMMAND = "deft orient";
+export declare const ORIENTATION_GRADUATION_TRIGGER: string;
+export type OrientationSectionName = "doctor" | "preflight" | "agents_refresh" | "cache_fresh";
+export type OrientationSectionStatus = "ok" | "dirty" | "degraded" | "error" | "skipped" | "sha_match";
+export interface OrientationSectionResult {
+    readonly name: OrientationSectionName;
+    readonly status: OrientationSectionStatus;
+    readonly ok: boolean;
+    readonly exitCode: number;
+    readonly lines: readonly string[];
+    readonly shaMatch: boolean;
+    readonly depositSha?: string;
+    readonly durationMs: number;
+    readonly detail?: Record<string, unknown>;
+}
+export interface OrientationBundle {
+    readonly depositSha: string;
+    readonly compact: boolean;
+    readonly sections: readonly OrientationSectionResult[];
+    readonly lines: readonly string[];
+    /** Count of orientation surfaces touched this session (for run-summary #3282 trigger). */
+    readonly orientationCallCount: number;
+    readonly later: {
+        readonly status: typeof ORIENTATION_LATER_STATUS;
+        readonly command: typeof ORIENTATION_LATER_COMMAND;
+        readonly trigger: typeof ORIENTATION_GRADUATION_TRIGGER;
+    };
+    readonly preflight: ToolchainPreflightResult | null;
+    readonly state: OrientationState;
+}
+export interface RunOrientationOptions {
+    readonly projectRoot: string;
+    readonly frameworkRoot?: string;
+    readonly compact?: boolean;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly now?: Date;
+    readonly depositShaOptions?: ComputeDepositShaOptions;
+    readonly toolchainPreflight?: ToolchainPreflightResult | null;
+    readonly toolchainPreflightOptions?: ToolchainPreflightOptions;
+    /** Skip doctor (tests) or inject structured result. */
+    readonly doctorSection?: OrientationSectionResult | null;
+    readonly doctorSeams?: DoctorSeams;
+    /** Skip agents:refresh or inject. */
+    readonly agentsRefreshSection?: OrientationSectionResult | null;
+    /** Skip cache_fresh or inject. */
+    readonly cacheFreshSection?: OrientationSectionResult | null;
+    readonly cacheFreshOptions?: EvaluateOptions;
+    /** When true (default), persist orientation-state for next-session fast-path. */
+    readonly persistState?: boolean;
+    /** Disable individual sections (tests / re-arm). */
+    readonly includeDoctor?: boolean;
+    readonly includePreflight?: boolean;
+    readonly includeAgentsRefresh?: boolean;
+    readonly includeCacheFresh?: boolean;
+}
+/** Resolve compact flag: explicit option wins, else DEFT_SESSION_COMPACT. */
+export declare function resolveSessionCompact(options?: Pick<RunOrientationOptions, "compact" | "env">): boolean;
+/** Compact machine lines (one per section). Verbose default keeps prose. */
+export declare function formatOrientationCompactLines(sections: readonly OrientationSectionResult[]): string[];
+export declare function formatOrientationVerboseLines(sections: readonly OrientationSectionResult[]): string[];
+/**
+ * Doctor orientation section — throttle status when clean/recent; otherwise
+ * run doctor and surface a per-section status line (#3286 compose).
+ */
+export declare function runDoctorOrientationSection(projectRoot: string, options?: {
+    now?: Date;
+    seams?: DoctorSeams;
+    doctorRunner?: (args: readonly string[], seams?: DoctorSeams) => number;
+}): OrientationSectionResult;
+export declare function runPreflightOrientationSection(projectRoot: string, options?: {
+    frameworkRoot?: string;
+    result?: ToolchainPreflightResult | null;
+    preflightOptions?: ToolchainPreflightOptions;
+}): {
+    section: OrientationSectionResult | null;
+    preflight: ToolchainPreflightResult | null;
+};
+/**
+ * agents:refresh orientation section (#3286).
+ * Always plans against live AGENTS.md so local managed-section edits are
+ * detected (deposit fingerprint alone is insufficient). Content-current →
+ * one-line sha-match phrasing; deposit-sha is recorded for orientation telemetry.
+ */
+export declare function runAgentsRefreshOrientationSection(projectRoot: string, options: {
+    depositSha: string;
+    prior?: OrientationState | null;
+    now?: Date;
+    apply?: typeof applyAgentsRefresh;
+}): OrientationSectionResult;
+/**
+ * verify:cache-fresh orientation section (#3286).
+ * Always runs the live evaluate (age + drift). Deposit fingerprint is recorded
+ * for orientation telemetry only — it must not suppress triage-cache freshness.
+ * When evaluate is already clean, surface a one-line sha-match-style no-op only
+ * if the message is the canonical deposit phrase (not used for shortcuts).
+ */
+export declare function runCacheFreshOrientationSection(projectRoot: string, options: {
+    depositSha: string;
+    prior?: OrientationState | null;
+    now?: Date;
+    evaluateOptions?: EvaluateOptions;
+    evaluateFn?: typeof evaluateCacheFresh;
+}): OrientationSectionResult;
+/**
+ * Run the composed orientation sections for a mutation cold session:start.
+ */
+export declare function runOrientationCompression(options: RunOrientationOptions): OrientationBundle;
+export { computeDepositSha, DEPOSIT_SHA_MATCH_NOOP, depositShaMatches, formatDepositShaMatchLine, } from "./deposit-sha.js";
+//# sourceMappingURL=orientation-compression.d.ts.map