@sema-agent/core/dist/core/path-identity.d.ts

Stateless, task-oriented AI agent core

import type { ExecutionEnv } from "../internal/harness-types.js";
import { type PathFamily } from "../tools/fs/safety.js";
/**
 * What the reader learned of a leaf symlink chain: the hops (`ok` — `[]` only when the environment was asked and
 * answered that there are none), or that no hop could be read (`ok: false`). `asked` separates a fact about the
 * environment (it was asked and could not answer) from a chain nobody asked about (no `canonicalChain` declared, or a
 * spelling it does not walk).
 */
export type ChainHopsReading = {
    readonly ok: true;
    readonly hops: readonly string[];
} | {
    readonly ok: false;
    readonly cause: string;
    readonly asked: boolean;
};
/**
 * The leaf symlink chain of `path` — the ONE place where a chain read becomes "read" or "not read". The spelling is
 * anchored as the canonicalizer anchors it (`baseCwd`). A refused namespace spelling and a win-form UNC spelling are
 * not walked (the reference CLI's variant set stops at a network spelling); the share is recognized by the throat's
 * own `isUncSpelling`. Each caller holds its own posture on `ok: false`: a path guard (deny side) lets a view that
 * cannot answer not vote ({@link chainHopsOrNone}), an allow admits nothing it could not see.
 */
export declare function symlinkChainHops(env: ExecutionEnv, path: string, signal: AbortSignal | undefined, family: PathFamily, baseCwd?: string): Promise<ChainHopsReading>;
/** A path guard's reading of a chain: the hops, or none — a view that cannot answer does not vote (its absence law). */
export declare function chainHopsOrNone(reading: ChainHopsReading): readonly string[];