@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; the grant judges by the store-isolation rule ({@link rootAdmittingArtifactStore}). */
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 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;
}
/** 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 {};