ai-foreman 1.7.6 → 1.7.7

package/dist/sessionIdentity.js

@@ -0,0 +1,132 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+/** Resolve symlinks for an existing location and otherwise return an absolute normalized path. */
+export function canonicalSessionPath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync.native(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/**
+ * Stable for one Git worktree lifetime. The token lives in that worktree's
+ * administrative Git directory (not in the checked-out tree), so normal edits
+ * and commits do not change it while removal/recreation cannot inherit it.
+ */
+export function captureWorkspaceIdentity(cwd) {
+    try {
+        const canonicalCwd = canonicalSessionPath(cwd);
+        const gitDir = canonicalSessionPath(execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+            cwd: canonicalCwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+        }).trim());
+        const marker = join(gitDir, "rafi-workspace-id-v1");
+        let token;
+        try {
+            token = readFileSync(marker, "utf8").trim();
+            if (!/^[0-9a-f-]{36}$/i.test(token))
+                throw new Error("invalid Rafi worktree identity marker");
+        }
+        catch {
+            const candidate = randomUUID();
+            try {
+                writeFileSync(marker, `${candidate}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+            }
+            catch { /* another host process may have initialized the same worktree */ }
+            token = readFileSync(marker, "utf8").trim();
+            if (!/^[0-9a-f-]{36}$/i.test(token))
+                return undefined;
+        }
+        return createHash("sha256").update(`${canonicalCwd}\0${gitDir}\0${token}`).digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createProviderSessionRef(input) {
+    if (!input.sessionId.trim())
+        throw new Error("provider session ID must not be empty");
+    const generation = input.generation ?? 0;
+    if (!Number.isSafeInteger(generation) || generation < 0)
+        throw new Error("provider session generation must be a non-negative safe integer");
+    const cwd = canonicalSessionPath(input.cwd);
+    const workspaceIdentity = input.workspaceIdentity ?? captureWorkspaceIdentity(cwd);
+    return {
+        version: 1,
+        provider: input.provider,
+        sessionId: input.sessionId,
+        role: input.role ?? (input.stream === "qa" ? "qa" : "builder"),
+        stream: input.stream ?? input.role ?? "builder",
+        generation,
+        cwd,
+        configRoot: canonicalSessionPath(input.configRoot),
+        ...(workspaceIdentity ? { workspaceIdentity } : {}),
+        ...(input.ticketId ? { ticketId: input.ticketId } : {}),
+        ...(input.deliveryUnitId ? { deliveryUnitId: input.deliveryUnitId } : {}),
+        source: input.source ?? "observed",
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        ...(input.validatedAt ? { validatedAt: input.validatedAt } : {}),
+    };
+}
+/** Identity used by accounting, compaction, settings acknowledgements, and mutation leases. */
+export function providerSessionKey(ref) {
+    const cwd = canonicalSessionPath(ref.cwd);
+    const payload = [ref.provider, ref.sessionId, ref.role, cwd, ref.workspaceIdentity ?? "unscoped"].join("\0");
+    return `psv1_${createHash("sha256").update(payload).digest("hex")}`;
+}
+export function validateProviderSessionScope(ref, requested, now = new Date()) {
+    const checkedAt = now.toISOString();
+    const unavailable = (reason, detail, observedCwd) => ({
+        version: 1, status: reason === "legacy-unscoped" ? "unknown" : "unavailable", checkedAt, reason, detail,
+        ...(observedCwd ? { observedCwd } : {}), sessionRef: ref,
+    });
+    if (ref.provider !== requested.provider)
+        return unavailable("provider-mismatch", `stored provider ${ref.provider} does not match requested provider ${requested.provider}`);
+    if (requested.role && ref.role !== requested.role)
+        return unavailable("role-mismatch", `stored role ${ref.role} does not match requested role ${requested.role}`);
+    if (requested.stream && ref.stream !== requested.stream)
+        return unavailable("stream-mismatch", `stored stream ${ref.stream} does not match requested stream ${requested.stream}`);
+    if (!existsSync(ref.cwd) || !existsSync(requested.cwd))
+        return unavailable("not-found", "the recorded provider working directory no longer exists");
+    const storedCwd = canonicalSessionPath(ref.cwd);
+    const requestedCwd = canonicalSessionPath(requested.cwd);
+    if (storedCwd !== requestedCwd)
+        return unavailable("cwd-mismatch", `stored cwd ${storedCwd} does not match requested cwd ${requestedCwd}`, requestedCwd);
+    const storedRoot = canonicalSessionPath(ref.configRoot);
+    const requestedRoot = canonicalSessionPath(requested.configRoot);
+    if (storedRoot !== requestedRoot)
+        return unavailable("config-root-mismatch", `stored Rafi config root ${storedRoot} does not match requested root ${requestedRoot}`, requestedCwd);
+    const actualIdentity = requested.workspaceIdentity ?? captureWorkspaceIdentity(requestedCwd);
+    if (ref.workspaceIdentity && actualIdentity !== ref.workspaceIdentity) {
+        return unavailable("workspace-mismatch", "the directory at the recorded path is not the original worktree", requestedCwd);
+    }
+    if (!ref.workspaceIdentity || !actualIdentity) {
+        return unavailable("legacy-unscoped", "the stored session has no verifiable worktree identity", requestedCwd);
+    }
+    if (ref.ticketId && requested.ticketId && ref.ticketId !== requested.ticketId)
+        return unavailable("workspace-mismatch", `stored ticket ${ref.ticketId} does not match requested ticket ${requested.ticketId}`, requestedCwd);
+    if (ref.deliveryUnitId && requested.deliveryUnitId && ref.deliveryUnitId !== requested.deliveryUnitId)
+        return unavailable("workspace-mismatch", `stored delivery unit ${ref.deliveryUnitId} does not match requested unit ${requested.deliveryUnitId}`, requestedCwd);
+    const validated = { ...ref, cwd: storedCwd, configRoot: storedRoot, workspaceIdentity: actualIdentity, validatedAt: checkedAt };
+    return { version: 1, status: "available", checkedAt, observedCwd: requestedCwd, sessionRef: validated };
+}
+export function latestSessionBinding(bindings, role, sessionId) {
+    return [...(bindings ?? [])]
+        .filter((ref) => ref.role === role && (!sessionId || ref.sessionId === sessionId))
+        .sort((a, b) => a.generation - b.generation || a.createdAt.localeCompare(b.createdAt))
+        .at(-1);
+}
+export function resolveUniqueSessionBinding(bindings, sessionId) {
+    const byKey = new Map((bindings ?? []).filter((ref) => ref.sessionId === sessionId).map((ref) => [providerSessionKey(ref), ref]));
+    if (byKey.size > 1)
+        throw new Error(`provider session ID ${sessionId} is ambiguous across recorded locations`);
+    return [...byKey.values()][0];
+}
+export function upsertSessionBinding(bindings, ref) {
+    const key = providerSessionKey(ref);
+    return [...(bindings ?? []).filter((candidate) => providerSessionKey(candidate) !== key), ref]
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.generation - b.generation);
+}

package/dist/sessionLifecycle.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigurableAgentRole, ResolvedAgentSettings, WorkflowIssue } from "rafi-spec";
+import type { ConfigurableAgentRole, ContextSample, ProviderSessionRefV1, ResolvedAgentSettings, SessionAvailabilityV1, SessionStrategy, WorkflowIssue } from "rafi-spec";
 import type { BuilderAdapter, ContextUsage } from "./adapters/types.js";
 export interface SessionTransition {
     kind: "initial" | "compacted" | "fresh" | "missing" | "compaction-retry" | "compaction-fallback" | "settings-attempt" | "settings-continued" | "settings-fallback";
@@ -15,23 +15,122 @@ export interface SessionBoundary {
 export interface RoleSessionControllerOptions {
     role: ConfigurableAgentRole;
     settings: ResolvedAgentSettings;
-    create: (settings: ResolvedAgentSettings, resumeSessionId?: string) => Promise<BuilderAdapter>;
+    create: (settings: ResolvedAgentSettings, resumeSessionId?: string, resumeSessionRef?: ProviderSessionRefV1) => Promise<BuilderAdapter>;
     report?: (transition: SessionTransition) => void;
     now?: () => Date;
     initialSessionId?: string;
+    initialSessionRef?: ProviderSessionRefV1;
+    /** Publish/validate cumulative state and return the accepted fresh successor. */
+    handoff?: (input: {
+        predecessor: BuilderAdapter;
+        durableHandoff: string;
+        reason: string;
+        settings: ResolvedAgentSettings;
+    }) => Promise<BuilderAdapter>;
+}
+export declare class RoleSessionValidationError extends Error {
+    readonly role: ConfigurableAgentRole;
+    readonly availability: SessionAvailabilityV1;
+    constructor(role: ConfigurableAgentRole, availability: SessionAvailabilityV1);
 }
 /** One lifecycle implementation shared by interviews, builds, QA, and recovery. */
 export declare class RoleSessionController {
     private readonly options;
     private adapter?;
     private workSessions;
+    private thresholdController?;
     constructor(options: RoleSessionControllerOptions);
-    next(_durableHandoff: string, nextSettings?: ResolvedAgentSettings): Promise<SessionBoundary>;
+    /**
+     * Production facade: the role owner authorizes scoped adapters and validated
+     * successors while the threshold controller remains delegated policy and
+     * accounting. Compatibility callers may still construct the threshold
+     * controller directly.
+     */
+    static managed(options: ThresholdCompactionOptions): RoleSessionController;
+    atSafeBoundary(adapter: BuilderAdapter, frozenAction: string): Promise<ContextBoundaryResult>;
+    atWorkSessionBoundary(adapter: BuilderAdapter, frozenAction: string, strategy?: SessionStrategy): Promise<ContextBoundaryResult>;
+    effectiveSettings(): ResolvedAgentSettings;
+    effectiveThreshold(): number;
+    next(durableHandoff: string, nextSettings?: ResolvedAgentSettings): Promise<SessionBoundary>;
     current(): BuilderAdapter | undefined;
     count(): number;
     usage(): Promise<ContextUsage | undefined>;
     close(): Promise<void>;
+    private moveFresh;
+    private adoptManagedAdapter;
+    private captureManagedIdentity;
+    private acceptManagedTransition;
     private boundary;
     private emit;
     private issue;
 }
+export declare class ContextCapabilityError extends Error {
+    readonly runId: string;
+    readonly role: "builder" | "qa";
+    constructor(runId: string, role: "builder" | "qa", message: string);
+}
+export interface ThresholdCompactionOptions {
+    projectDir: string;
+    runId: string;
+    role: "builder" | "qa";
+    initialSettings: ResolvedAgentSettings;
+    /** Read durable settings at every safe boundary. A newer revision wins. */
+    readSettings?: () => ResolvedAgentSettings;
+    /** Apply provider/model controls before a newer durable revision is acknowledged. */
+    settingsBoundary?: (input: {
+        adapter: BuilderAdapter;
+        current: ResolvedAgentSettings;
+        next: ResolvedAgentSettings;
+        frozenAction: string;
+    }) => Promise<BuilderAdapter>;
+    settingsAdopted?: (settings: ResolvedAgentSettings, adapter: BuilderAdapter) => void;
+    handoff?: (input: {
+        reason: string;
+        adapter: BuilderAdapter;
+        sample: ContextSample;
+        settings: ResolvedAgentSettings;
+        compactionCount: number;
+        frozenAction: string;
+    }) => Promise<BuilderAdapter>;
+    report?: (event: {
+        kind: string;
+        detail: string;
+        sample?: ContextSample;
+    }) => void;
+    contextRetries?: number;
+    historicalCountUncertain?: boolean;
+    now?: () => Date;
+}
+export interface ContextBoundaryResult {
+    adapter: BuilderAdapter;
+    action: "continued" | "compacted" | "handed-off" | "below-threshold";
+    sample: ContextSample;
+    effectiveThreshold: number;
+    compactionCount: number;
+}
+/** Threshold-triggered native compaction at host-owned safe boundaries. */
+export declare class ThresholdCompactionController {
+    private readonly options;
+    private settings;
+    private armed;
+    private crossing;
+    private readonly seenSessions;
+    private runOnlyThreshold?;
+    private bootstrapScheduled;
+    private bootstrapRecoveryDepth;
+    private historicalCountUncertain;
+    constructor(options: ThresholdCompactionOptions);
+    atSafeBoundary(adapter: BuilderAdapter, frozenAction: string): Promise<ContextBoundaryResult>;
+    /** Apply the configured ordinary work-session boundary without bypassing handoff or compaction accounting. */
+    atWorkSessionBoundary(adapter: BuilderAdapter, frozenAction: string, strategy?: SessionStrategy): Promise<ContextBoundaryResult>;
+    effectiveSettings(): ResolvedAgentSettings;
+    effectiveThreshold(): number;
+    private compactSession;
+    private performHandoff;
+    private adoptSettings;
+    private measure;
+    private compactionCount;
+    private handoffGeneration;
+    private threshold;
+    private now;
+}