@sema-agent/core/dist/core/runner/persisted-path-rows.d.ts

Stateless, task-oriented AI agent core

/**
 * The person's persisted PATH rows as a leg's read face takes them at prepare (the gate's rule lanes read the same store
 * per call).
 */
import { type EffectivePermissionRules, type PermissionRuleStoreProvider } from "../permission-rule-provider.js";
import type { PathRuleDenyRow } from "../../tools/fs/read-deny.js";
import type { RunnerDeps } from "../runner-deps.js";
/** The person's persisted PATH rows a leg's read face takes at prepare ({@link persistedPathRowsOf}). */
export interface PersistedPathRows {
    /** Every live `Read(//dir/**)` allow row's directory (lexical, absolute): a standing yes to reads under it. */
    readonly readDirectories: readonly string[];
    /** Every live face-keyed path DENY row (`Read(...)`, `Edit(...)`), as a deny-table row resolved at the task's bases. */
    readonly denyRows: readonly PathRuleDenyRow[];
}
/**
 * The person's persisted PATH rows, read ONCE at prepare from the same store query the gate's lanes read per call: a
 * `Read(//dir/**)` allow row is a READ DIRECTORY of the run (the Bash read station, Read / Grep / Glob — one set), and a
 * `Read(...)` / `Edit(...)` deny row joins the run's read / write deny tables (every read face, the shell's file commands
 * and traversals). One read, two directions, so a person's allow row never reaches further than their deny rows: a
 * directory it admits still refuses the paths a deny row names. A row the store gains mid-run applies from the next
 * prepare; the in-flight grant (`readRootGrant`) is the mid-run door. The store not armed, or the anonymous floor ⇒ no
 * rows. A read that failed (or did not answer in time) ⇒ no rows, and a partition the read could not read ⇒ none of ITS
 * rows (the partition that was read contributes its own): what could not be read is skipped for this run's tables — its
 * directories widen nothing and its deny rows judge nothing here — disclosed on the trace and announced to the person
 * (`onUnread`); the next prepare reads again, as it would for a row the store gained mid-run. A deny row whose
 * pattern needs a base the task cannot supply (`~/` with no declared home) is left to the per-call lane and disclosed.
 */
export declare function persistedPathRowsOf(cfg: {
    provider: PermissionRuleStoreProvider | undefined;
    localOwnerDeclared: boolean;
    principal: string | undefined;
    sessionId: string;
    root: string;
    home: string | undefined;
    onDisclosure: (message: string) => void;
    /** The person is told the store (or the named sources of it) was skipped ({@link ruleStoreUnreadableNotice}). */
    onUnread: (at: "prepare", sources?: EffectivePermissionRules["unreadableSources"]) => void;
    /** The run's cut: a read that has not answered by then (or by the gate's await bound) reads as unreadable. */
    signal?: AbortSignal;
}): Promise<PersistedPathRows>;
/**
 * The run's ONE `permission.rule_store_unavailable` notice (audience user): the person's rules — the whole store, or the
 * sources of it whose partition could not be read — were skipped; minted by whichever read found it first (the prepare
 * read of the path rows, or a call's own read on the rule lane), once per run however many reads fail after it (the
 * prepare sentence says a later call may be judged without them too). The trace keeps every read's line.
 */
export declare function ruleStoreUnreadableNotice(onNotice: RunnerDeps["onNotice"], ids: {
    readonly sessionId: string;
    readonly runId: string;
}): (at: "prepare" | "call", sources?: EffectivePermissionRules["unreadableSources"]) => void;
/** {@link persistedPathRowsOf} for one task's prepare: only where a read face mounts (hands), disclosed on the run's trace,
 *  cut by the run's own signals. `undefined` = nothing to read, returned synchronously: a run with no person's store (or
 *  no hands) gains no suspension point on its prepare. */
export declare function persistedPathRowsOfTask(t: {
    deps: Pick<RunnerDeps, "permissionRuleStore" | "localOwnerRules" | "tracer">;
    principal: string | undefined;
    sessionId: string;
    root: string;
    home: string | undefined;
    taskId: string;
    handsEnabled: boolean;
    signals: readonly AbortSignal[];
    onUnread: (at: "prepare", sources?: EffectivePermissionRules["unreadableSources"]) => void;
}): Promise<PersistedPathRows> | undefined;