@sema-agent/core/dist/core/runner/read-root-grant.d.ts

Stateless, task-oriented AI agent core

/** The run's IN-FLIGHT read-root grant: the one place a screened grant ({@link ReadRootGrantScreen}) widens this run's
 *  read directories (through the hands phase's {@link GrantReadRoot}, built by {@link readRootGrantOver}), the one
 *  composer of the two notices, and the home of the store-isolation rule both root admission points judge by (the
 *  Artifact phase's mount and the grant) — machinery both phases reach down for. */
import type { ExecutionEnv } from "../../internal/harness.js";
import type { ReadRootGrantCandidate } from "../types.js";
import type { ReadRootGrantScreen } from "../read-root-grant-screen.js";
import { type RunnerDeps } from "../types.js";
/**
 * THE store-isolation rule, one judgment for every root admission point (the Artifact mount over the prepare-time
 * roots, an in-flight read-root grant over the granted root): a root that CONTAINS the local artifact store, lies
 * INSIDE it, or IS it hands the file tools the store's ledger and stored files. Returns the first such root, or
 * undefined.
 *
 * `storePhysical` is the store's physical path on THIS process's filesystem (`physicalPathOfExisting`, resolved
 * once per run by the Artifact phase); a root is the execution env's canonical key. The judgment touches no
 * filesystem — the grant runs after the approver's wait under the call's cut, and a synchronous lookup on a stalled
 * store mount would block the event loop past that cut. The two are compared as identities only when both spell the
 * same family (`within` reads both under the root's family); a root of the other family names a filesystem the store
 * cannot be on, and no claim is made against it.
 */
export declare function rootAdmittingArtifactStore(storePhysical: string, rootsCanonical: readonly string[]): string | undefined;
/** The run's cell holding the local artifact store a granted root must never admit (its physical path, as the
 *  Artifact phase resolved it): minted with the grant by the hands phase, written by the Artifact phase (the one
 *  reader of the hosting seat) once the declaration validates. */
export interface ArtifactStoreRef {
    current: string | undefined;
    /** The person's STANDING read grants — their persisted `Read(//dir/**)` rows, joined to the live read set at prepare —
     *  held to the in-flight grant's store rule by {@link withdrawStandingGrantsAdmitting} once the store is known. */
    standing?: {
        readonly keys: readonly string[];
        readonly readRoots: string[];
    };
}
/** The store rule applied to the standing grants: each one that admits `storePhysical` leaves the live read set (so no
 *  read face reaches the store through it); returns the withdrawn keys, for the caller to announce. */
export declare function withdrawStandingGrantsAdmitting(storePhysical: string, ref: ArtifactStoreRef): string[];
/** Why the run's station applied no grant: the spelling did not resolve (or its lookup was cut), it no longer
 *  resolves to itself (a directory swapped for a link while the card waited), or it would admit the local artifact
 *  store (the store-isolation rule the Artifact phase judges its mount by). */
type GrantRefusal = "unresolvable" | "resolves_elsewhere" | "admits_artifact_store";
/** Widen THIS run's live read roots by one granted candidate: the offered spelling must still be its own canonical
 *  form and must not admit the local artifact store, then one deduplicated push; `root` = the spelling held. Nothing
 *  is pushed once `signal` has fired (a late lookup never widens). */
export type GrantReadRoot = (candidate: ReadRootGrantCandidate, signal: AbortSignal) => Promise<{
    ok: true;
    root: string;
} | {
    ok: false;
    reason: GrantRefusal;
    cause: string;
}>;
/** The hands phase's {@link GrantReadRoot} over the run's live root arrays: the offered spelling must still be its own
 *  canonical form, must not admit the store in `artifactStore` ({@link rootAdmittingArtifactStore}), then ONE
 *  deduplicated push onto `readRoots` (the live read set every read face reads per call); the write roots are only
 *  consulted for the dedup, never widened. */
export declare function readRootGrantOver(seats: {
    env: Pick<ExecutionEnv, "canonicalPath">;
    writeRoots: readonly string[];
    readRoots: string[];
    artifactStore: ArtifactStoreRef;
}): GrantReadRoot;
/** Act on one screened grant: `granted` widens through `grant` (absent on a station that cannot widen — an inherited
 *  ask, a hands-less leg) and is announced; every other outcome changes nothing and is announced too — never silent.
 *  Returns a promise ONLY while a grant is applied, so an answer with no grant costs no extra event-loop turn. */
export declare function settleReadRootGrant(screen: ReadRootGrantScreen | undefined, grant: GrantReadRoot | undefined, at: {
    toolName: string;
    toolCallId: string;
    sessionId: string;
    runId: string;
    taskId?: string;
    onNotice: RunnerDeps["onNotice"];
    signal?: AbortSignal;
}): Promise<void> | undefined;
export {};