@sema-agent/core/dist/tools/fs/read-deny-home.d.ts

Stateless, task-oriented AI agent core

import type { ExecutionEnv } from "../../internal/harness-types.js";
import { type PathFamily } from "./safety.js";
import { type ReadDenyMatcher } from "./read-deny.js";
/** The one bound every probe of an AUXILIARY home shares within one placement (see the module head): long enough for a
 *  local directory's canonical spelling, its chain of identities and its rows' heads, short enough that a hung home
 *  costs a placement seconds, not the gate's bound. */
export declare const AUXILIARY_HOME_PROBE_MS = 2000;
/** {@link declaredReadDenyHomesAnswered}'s anchor list. */
export declare function declaredReadDenyHomes(env: Pick<ExecutionEnv, "homeDir">): string[];
/** The declared home and the account home ({@link declaredReadDenyHomes}) and, where the environment's canonical
 *  spelling of one differs (a home reached through a symlink), that spelling too: the faces judge canonical keys beside
 *  the spelled views, so a row placed only at the spelled home would never meet a canonical key. A home the
 *  environment cannot resolve keeps its spelling — the account home's probe waits at most {@link AUXILIARY_HOME_PROBE_MS}.
 *  `[]` — the rows hold their run at every location — where the environment declares no home, where the account lookup
 *  gave no answer, or where the declared home's own probe did not answer (ask again later). */
export declare function readDenyHomesOf(env: Pick<ExecutionEnv, "homeDir" | "canonicalPath">, signal?: AbortSignal): Promise<string[]>;
/**
 * Where the home-anchored rows of a table LEAD beyond the home's own spellings, keyed by the row's pattern — the
 * `linked` argument of `compileReadDeny`. For each row, its LITERAL HEAD (`readDenyRunHead`: the run's segments before
 * the first one carrying `*`) is spelled under each home and resolved the way the read faces mint their keys
 * (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined); a location that differs from every
 * home's own spelling of the head is where one of the head's segments is a link, and the row is placed there too.
 *  · a head that resolves to its own spelling under a home adds nothing (the row is already placed there);
 *  · a head under a spelling that is no directory (a segment of it is a file, a symlink to a file, a device node or a
 *    socket — the environment answers `not_directory` for the head) has nothing below it: an answer that adds nothing;
 *  · any other head that cannot be resolved (an unanswered or refused probe — a directory the probe may not enter — a
 *    probe that throws) adds nothing, and the answer is not WHOLE (`whole: false`): the row stays placed at the home's
 *    spellings until the mount places again;
 *  · a row whose head is empty (`~/.sema.*`) has no location to resolve and adds nothing;
 *  · the heads are resolved together, so one placement waits at most one probe bound — or, with `deadline` (an absolute
 *    time), each head until then: a head still unresolved at the deadline is a head that did not answer;
 *  · read per placement — a link created afterwards is followed from the next placement on.
 */
export declare function readDenyHomeLinksOf(env: ExecutionEnv, entries: readonly {
    readonly pattern: string;
    readonly caseSensitive?: boolean;
}[], homes: readonly string[], signal?: AbortSignal, deadline?: number): Promise<{
    readonly linked: Map<string, string[]>;
    readonly whole: boolean;
}>;
/** Where an absolute location LEADS in one environment — resolved the way the read and write faces mint their keys
 *  (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined). `undefined` when the environment
 *  does not answer (a refused or failed probe, one that throws). The one resolution a deny row's placement reads: a
 *  home-anchored row's head ({@link readDenyHomeLinksOf}) and a rule row's head ({@link whereItsAnsweredPrefixLeads}). */
export declare function whereItLeads(env: ExecutionEnv, at: string, family?: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
/** {@link whereItLeads} with a floor: where the environment does not answer for `at` (a probe that fails), the longest
 *  prefix it does answer for is resolved and the rest rejoined — a rule row's head below a base that resolves is never
 *  placed narrower than that base's own canonical spelling. The whole walk waits at most one bounded-await deadline.
 *  `undefined` when no prefix answers in time. */
export declare function whereItsAnsweredPrefixLeads(env: ExecutionEnv, at: string, family?: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
/** The environment surface a home view reads. */
export type HomeViewEnv = Pick<ExecutionEnv, "homeDir" | "canonicalPath" | "fileIdentity">;
/**
 * The HOME VIEWS of one placement — the one reader every face that judges a deny row by location uses (the structured
 * read and write tools' target judgment, the shell station's establishment, the search walker, the ripgrep leg's output
 * check and its scope choice). A judge carries the source its placement made ({@link HomeViewsCarrier}); a judgment
 * takes one {@link HomeViews} from it ({@link homeViewsOf}).
 *
 * The view of a path is the path itself when it IS a directory on a home's chain (each home's canonical spelling and
 * each of its ancestors, matched by {@link ExecutionEnv.fileIdentity}) — that directory's canonical spelling — and
 * otherwise its parent's view with its own name rejoined. One identity keeps ONE spelling, and a row is placed at a
 * HOME's spelling: a directory that IS a home (its own identity answered) keeps the home's own spelling over an
 * ancestor's (a declared home below a mount of the account home meets the account home's identity at an ancestor); a
 * home whose own identity did not answer has no directory to claim. Homes in order: the declared home, then the
 * auxiliary homes. The homes are the placement's:
 *  · the DECLARED home (`env.homeDir`, no lookup) is always among them — whatever the account lookup answered — and its
 *    chain is read by the first judgment that asks, kept once every level answered, and asked again by the next
 *    judgment otherwise (a home that does not exist yet is read once it does);
 *  · each AUXILIARY home's chain is the one its placement read, once ({@link AUXILIARY_HOME_PROBE_MS}); a chain that did
 *    not answer stays unanswered for that placement.
 */
export interface HomeViewSource {
    /** The home views of one judgment (a tool call, a command's establishment, one search): a view per directory is read
     *  once and shared by every path below it. */
    views(signal?: AbortSignal): HomeViews;
}
/** A judgment's views. `of` answers the view only where it differs from the path as spelled; `undefined` otherwise, and
 *  wherever it cannot be read: no `fileIdentity` seat, no home, a level of the path whose identity fails (the path is
 *  judged as spelled, never wider). A level that does not exist (a write's missing tail) takes its parent's view.
 *  `leaf: "file"` skips the path's own identity (a file is never a directory on the chain). */
export interface HomeViews {
    of(path: string, opts?: {
        readonly leaf?: "file";
    }): Promise<string | undefined>;
}
/** A judge that carries the home views of the placement its rows were compiled at. */
export interface HomeViewsCarrier {
    readonly homeViews?: HomeViewSource;
}
/** A read deny judge with its placement's home views. */
export type PlacedReadDenyMatcher = ReadDenyMatcher & {
    readonly homeViews: HomeViewSource;
};
/** The views of the placement that returned `homes` — the very list object, as the engine hands it on (the Runner's
 *  tool band). `undefined` for any other list: a copy, or a host's own. A mount that was handed the engine's placement
 *  and cannot find its views has lost it: an engine defect, which the mount names ({@link sayPlacementLost}) and answers
 *  by holding its home-anchored rows at every location — never by reading the homes a second time. */
export declare function placementViewsOf(homes: readonly string[]): HomeViewSource | undefined;
/** The line a mount says when the engine handed it a home list that is not its placement's (an engine defect, said every
 *  time: no latch). */
export declare function sayPlacementLost(): void;
/** The home views over a home list fixed now — a mount that places nothing itself (a toolkit handed its placement, or
 *  one whose table has no home-anchored row) and the public shell judgment (the `readDenyHomes` its boundary's rows were
 *  compiled under): the declared home, and every entry of `homes` that is not the declared home as an auxiliary home,
 *  read once, at once. */
export declare function homeViewsAt(env: HomeViewEnv, homes: readonly string[]): HomeViewSource;
/** The home views of one judgment, off the judge it judges with: the views of the judge's placement. A judge that
 *  carries none (one built outside a mount) reads the declared home alone. */
export declare function homeViewsOf(env: HomeViewEnv, judge: HomeViewsCarrier | undefined, signal?: AbortSignal): HomeViews;
/** A judge with the home views `source` gives it. */
export declare function carryHomeViews<T extends object>(judge: T, source: HomeViewSource): T & {
    readonly homeViews: HomeViewSource;
};
/** One mount's read-deny judge with its home-anchored rows placed, and the home views of that placement:
 *  · the HOME SET — `homes` when the mount carries a list (the account is not asked and no home is added), else the
 *    declared home and the account lookup's answer ({@link declaredReadDenyHomes}); every home of the set is anchored at
 *    its spelling and, where the environment answered one, its canonical spelling — one rule for both forms;
 *  · the DECLARED home's canonical spelling under the tree's gate bound, and its rows' heads ({@link readDenyHomeLinksOf}):
 *    a declared home, or a head under it, that did not answer leaves the placement not WHOLE — and an account lookup
 *    with no answer, or a declared home that did not answer, places nothing: the rows are held anywhere (`compile([])`)
 *    rather than at a spelling that may miss the home's canonical one;
 *  · each AUXILIARY home (see the module head) read once under {@link AUXILIARY_HOME_PROBE_MS} — its spellings, its
 *    chain, its rows' heads — at the same time; whatever of it did not answer costs that home alone and never `whole`.
 *  `compile` is the mount's own compile; the rows' patterns are read off its compile at no home. */
export declare function placeReadDenyAtHome(env: ExecutionEnv, compile: (homes: readonly string[], linked?: ReadonlyMap<string, readonly string[]>) => ReadDenyMatcher, homes?: readonly string[], signal?: AbortSignal): Promise<{
    readonly matcher: PlacedReadDenyMatcher;
    readonly homes: readonly string[];
    readonly linked: ReadonlyMap<string, readonly string[]>;
    readonly whole: boolean;
}>;
/**
 * A judge for a mount that is built before its placement settles (the hands band is built synchronously): the table as
 * `unplaced` compiles it — home-anchored rows held anywhere, the rule for a row that cannot be placed — until a
 * placement settles, then the placed table. `place` starts at once; `ready()` settles when the latest placement has
 * (either way) and, while no placement has come back WHOLE (a failed one, or one with a head that did not answer),
 * places again first — an unanswered lookup is never kept as the answer. A failed placement leaves the table it
 * replaced (the rows held anywhere, or an earlier placement), never unplaced-and-narrow. The mount holds its read faces
 * until `ready()`. The judge's home views are the latest settled placement's: a judgment that asks for one waits for the
 * placement in flight (it never starts one).
 */
export declare function readDenyPlacedLater(unplaced: PlacedReadDenyMatcher, place: () => Promise<{
    readonly matcher: PlacedReadDenyMatcher;
    readonly whole: boolean;
}>): {
    readonly matcher: PlacedReadDenyMatcher;
    readonly ready: () => Promise<void>;
};