@better-fs-tools/read 0.0.0-tegami-trusted-publish-setup → 0.2.0

package/dist/contract/result.d.ts

@@ -0,0 +1,153 @@
+import type { Note, ToolError } from "./base.ts";
+import type { ReadInput, ReadRequest } from "./input.ts";
+import type { ReadPhase } from "./messages.ts";
+export interface TextPart {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface MediaPart {
+    readonly type: "media";
+    readonly mediaType: string;
+    readonly data: Uint8Array;
+    readonly name?: string;
+}
+export type ContentPart = TextPart | MediaPart;
+/**
+ * One variant for each status. `status` narrows the union: only the "error"
+ * variant has `error`, and it is never null there.
+ */
+export type ReadReport = ReadOk | ReadMedia | ReadUnsupported | ReadFailure;
+/** The outcome plus the formatter's model-facing content. */
+export type ReadResult = ReadReport & {
+    readonly content: readonly ContentPart[];
+};
+export interface ReadOk {
+    readonly tool: "read";
+    readonly status: "ok";
+    readonly request: ReadRequest;
+    readonly file: FileInfo;
+    readonly classification: ClassificationInfo;
+    /** Set when a converter produced the text. */
+    readonly conversion: ConversionInfo | null;
+    readonly view: ReadView;
+    readonly truncation: ReadTruncation;
+    readonly continuation: ReadContinuation;
+    readonly totals: ReadTotals;
+    readonly observation: ReadObservation | null;
+    readonly notes: readonly ReadNote[];
+}
+export interface ReadMedia {
+    readonly tool: "read";
+    readonly status: "media";
+    readonly request: ReadRequest;
+    readonly file: FileInfo;
+    readonly classification: ClassificationInfo;
+    readonly conversion: ConversionInfo;
+    readonly parts: readonly ContentPart[];
+    readonly observation: ReadObservation | null;
+    readonly notes: readonly ReadNote[];
+}
+export interface ReadUnsupported {
+    readonly tool: "read";
+    readonly status: "unsupported";
+    /** Open vocabulary: classifier codes, converter refusal codes, "TOO_LARGE". */
+    readonly code: string;
+    readonly request: ReadRequest;
+    readonly file: FileInfo;
+    readonly classification: ClassificationInfo;
+    readonly notes: readonly ReadNote[];
+}
+export interface ReadFailure {
+    readonly tool: "read";
+    readonly status: "error";
+    readonly error: ReadError;
+    readonly request: ReadRequest | null;
+    readonly file: FileInfo | null;
+    readonly notes: readonly ReadNote[];
+}
+/** The error of a failed read. Same shape as the write and shell errors. */
+export type ReadError = ToolError<ReadErrorCode, ReadPhase>;
+/** UPPER_SNAKE, like every tool's error codes. The error note's code is the kebab-case form. */
+export type ReadErrorCode = "INVALID_INPUT" | "NOT_FOUND" | "NOT_A_FILE" | "DANGEROUS_PATH" | "OUTSIDE_ALLOWED_ROOTS" | "PERMISSION_DENIED" | "DENIED" | "TOO_LARGE" | "CHANGED_DURING_READ" | "ABORTED" | "UNSUPPORTED_BACKEND" | "EXTENSION_FAILED" | "IO_ERROR";
+export interface FileInfo {
+    /** The path in the model's input, before any resolver. */
+    readonly requestedPath: string;
+    readonly resolvedPath: string;
+    readonly displayPath: string;
+    /** `fs.id` of the backend that served the read. */
+    readonly backend: string;
+    readonly size: number | null;
+    readonly mtimeMs: number | null;
+    /** `null` unless `fs.capabilities.identity`. */
+    readonly identity: string | null;
+    readonly mimeType: string | null;
+    /** The requested path when a resolver changed it, else null. */
+    readonly resolvedFrom: string | null;
+    /** `info.version` from the backend, or null. Kept when `capabilities.identity` is false. */
+    readonly version: string | null;
+}
+export interface ClassificationInfo {
+    readonly kind: "text" | "unsupported" | "directory";
+    /** Classifier id, or "fs" for a directory. */
+    readonly classifier: string;
+    /** Unsupported code from the classifier. null for text and directories. */
+    readonly code: string | null;
+    readonly mimeType: string | null;
+    readonly confidence: Confidence;
+    readonly reasons: readonly string[];
+}
+export interface ConversionInfo {
+    readonly converter: string;
+    /** Media type of the converted output. */
+    readonly mimeType: string | null;
+}
+export type Confidence = "high" | "medium" | "low";
+export interface ReadView {
+    readonly lines: readonly ReadLine[];
+    readonly startLine: number;
+    /** startLine - 1 when the view is empty. */
+    readonly endLine: number;
+    /** UTF-8 bytes of source text in the view, before any gutter. */
+    readonly bytes: number;
+    readonly partial: boolean;
+}
+export interface ReadLine {
+    readonly number: number;
+    /** Source text, clamped to limits.maxCharsPerLine. No gutter, no marker. */
+    readonly text: string;
+    readonly clamped: boolean;
+    /** Length of the source line in characters when clamped, else null. */
+    readonly sourceChars: number | null;
+}
+export type TruncationReason = "lines" | "bytes" | "budget" | "line-length" | "scan-limit";
+export interface ReadTruncation {
+    readonly truncated: boolean;
+    readonly reasons: readonly TruncationReason[];
+    readonly primary: TruncationReason | null;
+}
+export interface ReadContinuation {
+    readonly available: boolean;
+    /** The exact next canonical call. */
+    readonly next: ReadInput | null;
+}
+export interface ReadTotals {
+    /** null when the scan limit stopped counting. */
+    readonly lines: number | null;
+    readonly exact: boolean;
+    readonly bytes: number;
+}
+export interface ReadNote extends Note {
+    /** A concrete canonical retry. */
+    readonly retry?: ReadInput;
+}
+export interface ReadObservation {
+    readonly id: string;
+    readonly statId: string;
+    /** Hash of the source bytes. null when the scan stopped before EOF. */
+    readonly contentId: string | null;
+    /** Hash of what the model saw. Recomputed after a hook edits the view. */
+    readonly viewId: string;
+    readonly observedAt: string;
+    /** True when offset is 1, nothing was truncated or clamped, and no hook edited the view. */
+    readonly wholeFileVisible: boolean;
+}

package/dist/contract/state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Session state for read observations. A store is a cache: a failed store call
+ * never fails a read.
+ */
+export interface ReadStateStore {
+    get(key: string): Promise<ReadRecord | null>;
+    put(key: string, record: ReadRecord): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * What the read tool stores after a read with an observation, and what a write
+ * tool stores after a commit. Never holds `host`.
+ */
+export interface ReadRecord {
+    readonly schema: 2;
+    /** "write" when a write tool stored it after a commit. */
+    readonly origin: "read" | "write";
+    readonly observationId: string;
+    readonly resolvedPath: string;
+    readonly identity: string | null;
+    /** The backend change token. null when the backend gave none. */
+    readonly version: string | null;
+    /** Digest.id that made contentId and viewId. A record with another digest counts as absent. */
+    readonly digest: string;
+    readonly contentId: string | null;
+    /** For a write record: equal to contentId. */
+    readonly viewId: string;
+    readonly observedAt: string;
+    readonly wholeFileVisible: boolean;
+    readonly totalsExact: boolean;
+    /** The read range. null for a write record. */
+    readonly request: {
+        readonly offset: number;
+        readonly limit: number;
+    } | null;
+}

package/dist/converters/directory-listing.d.ts

@@ -0,0 +1,13 @@
+import type { DirectoryConverter } from "../contract/extensions.ts";
+export interface DirectoryListingOptions {
+    /** Add "/" after directory names. Default false. */
+    trailingSlash?: boolean;
+    /** Default "name". "type-then-name" puts directories first, then files, then others. */
+    sort?: "name" | "type-then-name";
+}
+/**
+ * Lists a directory, one entry per line, so offset, limit, and continuation
+ * page over entries. The listing holds at most limits.maxDirectoryEntries
+ * entries; a cut listing has a note.
+ */
+export declare function directoryListing(options?: DirectoryListingOptions): DirectoryConverter<unknown>;

package/dist/converters/directory-listing.js

@@ -0,0 +1,63 @@
+const TYPE_ORDER = {
+    directory: 0,
+    file: 1,
+    other: 2,
+};
+/**
+ * Lists a directory, one entry per line, so offset, limit, and continuation
+ * page over entries. The listing holds at most limits.maxDirectoryEntries
+ * entries; a cut listing has a note.
+ */
+export function directoryListing(options = {}) {
+    const trailingSlash = options.trailingSlash ?? false;
+    const sort = options.sort ?? "name";
+    if (typeof trailingSlash !== "boolean") {
+        throw new TypeError("directoryListing trailingSlash must be a boolean");
+    }
+    if (sort !== "name" && sort !== "type-then-name") {
+        throw new TypeError('directoryListing sort must be "name" or "type-then-name"');
+    }
+    return Object.freeze({
+        id: "directory-listing",
+        target: "directory",
+        async convert(input, ctx) {
+            const path = input.target?.displayPath ?? input.path;
+            const listed = await input.list();
+            // The read tool reports a failed listing itself; this refusal is never shown.
+            if (!listed.ok) {
+                return {
+                    kind: "refuse",
+                    code: "LIST_FAILED",
+                    note: { code: "list-failed", severity: "warning", message: `${path} was not listed.` },
+                };
+            }
+            const entries = [...listed.entries].sort(sort === "name" ? byName : byTypeThenName);
+            const notes = [];
+            if (listed.truncated) {
+                const limit = ctx.limits.maxDirectoryEntries;
+                notes.push({
+                    code: "directory-truncated",
+                    severity: "warning",
+                    message: `The listing of ${path} stopped at ${limit} entries; the directory has more.`,
+                    data: { maxDirectoryEntries: limit },
+                });
+            }
+            else if (entries.length === 0) {
+                notes.push({ code: "empty-directory", severity: "info", message: `${path} is empty.` });
+            }
+            const lines = entries.map((entry) => {
+                const name = /[\r\n]/u.test(entry.name) ? JSON.stringify(entry.name) : entry.name;
+                return trailingSlash && entry.type === "directory" ? `${name}/` : name;
+            });
+            return { kind: "text", text: lines.join("\n"), mimeType: "text/plain", notes };
+        },
+    });
+}
+function byName(a, b) {
+    if (a.name === b.name)
+        return 0;
+    return a.name < b.name ? -1 : 1;
+}
+function byTypeThenName(a, b) {
+    return TYPE_ORDER[a.type] - TYPE_ORDER[b.type] || byName(a, b);
+}

package/dist/converters/image.d.ts

@@ -0,0 +1,7 @@
+import type { FileConverter, ReadHookContext } from "../contract/extensions.ts";
+export interface ImageConverterOptions<THost = unknown> {
+    /** Resize or re-encode before the image goes to the model. The media type stays the same. */
+    transform?: (bytes: Uint8Array, mediaType: string, ctx: ReadHookContext<THost>) => Promise<Uint8Array>;
+}
+/** Converts an image (classification code "IMAGE") into one media part, capped by limits.maxMediaBytes. */
+export declare function imageConverter<THost = unknown>(options?: ImageConverterOptions<THost>): FileConverter<THost>;

package/dist/converters/image.js

@@ -0,0 +1,25 @@
+import { posixPaths } from "@better-fs-tools/fs";
+import { collect, isUnsupportedWithCode } from "./shared.js";
+/** Converts an image (classification code "IMAGE") into one media part, capped by limits.maxMediaBytes. */
+export function imageConverter(options = {}) {
+    const { transform } = options;
+    if (transform !== undefined && typeof transform !== "function") {
+        throw new TypeError("imageConverter transform must be a function");
+    }
+    return Object.freeze({
+        id: "image",
+        target: "file",
+        accepts: (match) => isUnsupportedWithCode(match.classification, "IMAGE"),
+        async convert(input, ctx) {
+            const mediaType = input.classification.mimeType ?? input.info.mimeType ?? "application/octet-stream";
+            const bytes = await collect(input.bytes());
+            const data = transform === undefined ? bytes : await transform(bytes, mediaType, ctx);
+            return {
+                kind: "media",
+                parts: [
+                    { type: "media", mediaType, data, name: posixPaths.basename(input.info.displayPath) },
+                ],
+            };
+        },
+    });
+}

package/dist/converters/index.d.ts

@@ -0,0 +1,8 @@
+export { directoryListing } from "./directory-listing.ts";
+export type { DirectoryListingOptions } from "./directory-listing.ts";
+export { imageConverter } from "./image.ts";
+export type { ImageConverterOptions } from "./image.ts";
+export { notebookConverter } from "./notebook.ts";
+export type { NotebookConverterOptions } from "./notebook.ts";
+export { textConverter } from "./text.ts";
+export type { TextConverterOptions } from "./text.ts";

package/dist/converters/index.js

@@ -0,0 +1,4 @@
+export { directoryListing } from "./directory-listing.js";
+export { imageConverter } from "./image.js";
+export { notebookConverter } from "./notebook.js";
+export { textConverter } from "./text.js";

package/dist/converters/notebook.d.ts

@@ -0,0 +1,12 @@
+import type { FileConverter } from "../contract/extensions.ts";
+export interface NotebookConverterOptions {
+    /** Render cell outputs after each code cell. Default true. */
+    outputs?: boolean;
+}
+/**
+ * Accepts classification code "NOTEBOOK". Renders cells as text: a
+ * `[cell N: type]` line, the source, and for code cells the text outputs.
+ * Rich outputs are named, not shown. A file that is not notebook JSON is
+ * refused with code "INVALID_NOTEBOOK".
+ */
+export declare function notebookConverter(options?: NotebookConverterOptions): FileConverter<unknown>;

package/dist/converters/notebook.js

@@ -0,0 +1,106 @@
+import { isRecord } from "../core/input.js";
+import { collect, isUnsupportedWithCode } from "./shared.js";
+/**
+ * Accepts classification code "NOTEBOOK". Renders cells as text: a
+ * `[cell N: type]` line, the source, and for code cells the text outputs.
+ * Rich outputs are named, not shown. A file that is not notebook JSON is
+ * refused with code "INVALID_NOTEBOOK".
+ */
+export function notebookConverter(options = {}) {
+    const outputs = options.outputs ?? true;
+    if (typeof outputs !== "boolean")
+        throw new TypeError("notebookConverter outputs must be a boolean");
+    return Object.freeze({
+        id: "notebook",
+        target: "file",
+        accepts: (match) => isUnsupportedWithCode(match.classification, "NOTEBOOK"),
+        async convert(input) {
+            const cells = parseCells(await collect(input.bytes()));
+            if (cells === null) {
+                return { kind: "refuse", code: "INVALID_NOTEBOOK", note: invalid(input.info.displayPath) };
+            }
+            const blocks = cells.map((cell, index) => renderCell(cell, index + 1, outputs));
+            return { kind: "text", text: blocks.join("\n\n"), mimeType: "text/plain" };
+        },
+    });
+}
+function parseCells(bytes) {
+    let notebook;
+    try {
+        notebook = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(notebook) || !Array.isArray(notebook.cells))
+        return null;
+    const cells = [];
+    for (const cell of notebook.cells) {
+        if (!isRecord(cell) || typeof cell.cell_type !== "string")
+            return null;
+        const source = jupyterText(cell.source);
+        if (source === null)
+            return null;
+        cells.push({
+            type: cell.cell_type,
+            source,
+            outputs: Array.isArray(cell.outputs) ? cell.outputs : [],
+        });
+    }
+    return cells;
+}
+function renderCell(cell, number, outputs) {
+    const lines = [`[cell ${number}: ${cell.type}]`];
+    if (cell.source !== "")
+        lines.push(trimEnd(cell.source));
+    if (outputs && cell.type === "code") {
+        for (const output of cell.outputs) {
+            const text = renderOutput(output);
+            if (text !== null)
+                lines.push("[output]", trimEnd(text));
+        }
+    }
+    return lines.join("\n");
+}
+function renderOutput(output) {
+    if (!isRecord(output))
+        return null;
+    switch (output.output_type) {
+        case "stream":
+            return jupyterText(output.text);
+        case "execute_result":
+        case "display_data": {
+            if (!isRecord(output.data))
+                return null;
+            const plain = output.data["text/plain"] === undefined ? null : jupyterText(output.data["text/plain"]);
+            if (plain !== null)
+                return plain;
+            const types = Object.keys(output.data);
+            return types.length === 0 ? null : `[${types.join(", ")} output not shown]`;
+        }
+        case "error":
+            return `${String(output.ename ?? "Error")}: ${String(output.evalue ?? "")}`;
+        default:
+            return null;
+    }
+}
+function jupyterText(value) {
+    if (value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) && value.every((part) => typeof part === "string")) {
+        return value.join("");
+    }
+    return null;
+}
+function trimEnd(text) {
+    return text.replace(/(?:\r?\n)+$/u, "");
+}
+function invalid(path) {
+    return {
+        code: "invalid-notebook",
+        severity: "warning",
+        message: `${path} looks like a Jupyter notebook but is not valid notebook JSON.`,
+    };
+}

package/dist/converters/shared.d.ts

@@ -0,0 +1,5 @@
+export declare function collect(source: AsyncIterable<Uint8Array>): Promise<Uint8Array>;
+export declare function isUnsupportedWithCode(classification: {
+    kind: string;
+    code?: string;
+}, code: string): boolean;

package/dist/converters/shared.js

@@ -0,0 +1,18 @@
+export async function collect(source) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of source) {
+        chunks.push(chunk);
+        total += chunk.byteLength;
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+export function isUnsupportedWithCode(classification, code) {
+    return classification.kind === "unsupported" && classification.code === code;
+}

package/dist/converters/text.d.ts

@@ -0,0 +1,12 @@
+import type { ConverterMatch, FileConverter, ReadHookContext } from "../contract/extensions.ts";
+export interface TextConverterOptions<THost = unknown> {
+    id: string;
+    /** Sync. The only place the converter may decline. */
+    accepts: (match: ConverterMatch) => boolean;
+    /** Media type of the text. */
+    mimeType: string | null;
+    /** Turns the source bytes into text. The text may arrive in chunks. */
+    run: (source: AsyncIterable<Uint8Array>, ctx: ReadHookContext<THost>) => AsyncIterable<string>;
+}
+/** Builds a text converter from a stream function, for example a pdftotext process in the host. */
+export declare function textConverter<THost = unknown>(options: TextConverterOptions<THost>): FileConverter<THost>;

package/dist/converters/text.js

@@ -0,0 +1,24 @@
+/** Builds a text converter from a stream function, for example a pdftotext process in the host. */
+export function textConverter(options) {
+    if (options === null || typeof options !== "object") {
+        throw new TypeError("textConverter options must be an object");
+    }
+    const { id, accepts, mimeType, run } = options;
+    if (typeof id !== "string" || id === "")
+        throw new TypeError("textConverter id must be a string");
+    if (typeof accepts !== "function")
+        throw new TypeError("textConverter accepts must be a function");
+    if (typeof run !== "function")
+        throw new TypeError("textConverter run must be a function");
+    if (mimeType !== null && typeof mimeType !== "string") {
+        throw new TypeError("textConverter mimeType must be a string or null");
+    }
+    return Object.freeze({
+        id,
+        target: "file",
+        accepts: (match) => accepts(match),
+        async convert(input, ctx) {
+            return { kind: "text", text: run(input.bytes(), ctx), mimeType };
+        },
+    });
+}

package/dist/core/authorize.d.ts

@@ -0,0 +1,8 @@
+import type { ListOutcome } from "@better-fs-tools/fs";
+import type { ReadAuthorizer } from "../contract/extensions.ts";
+import type { ReadRequest } from "../contract/input.ts";
+import type { FileInfo } from "../contract/result.ts";
+import type { CallScope } from "./call-scope.ts";
+export declare function authorizeRead<THost>(authorizer: ReadAuthorizer<THost> | null, request: ReadRequest, file: FileInfo, scope: CallScope<THost>): Promise<void>;
+/** null when the listing may go ahead. An authorizer failure is held on the scope, not thrown. */
+export declare function authorizeList<THost>(authorizer: ReadAuthorizer<THost> | null, request: ReadRequest, dir: string, display: string, scope: CallScope<THost>): Promise<ListOutcome | null>;

package/dist/core/authorize.js

@@ -0,0 +1,76 @@
+import { AbortReadError, raceAbort } from "./cursor.js";
+import { extensionId } from "./extension-error.js";
+import { isRecord } from "./input.js";
+import { ReadStop, denied, isNote } from "./outcomes.js";
+export async function authorizeRead(authorizer, request, file, scope) {
+    if (authorizer === null)
+        return;
+    scope.enter("authorize");
+    const target = Object.freeze({
+        action: "read",
+        requestedPath: request.path,
+        resolvedPath: file.resolvedPath,
+        displayPath: file.displayPath,
+        size: file.size,
+        mtimeMs: file.mtimeMs,
+    });
+    const result = await runAuthorizer(authorizer, target, scope);
+    if (!result.allow)
+        throw new ReadStop(denied(scope.deps.messages, request, result.note));
+}
+/** null when the listing may go ahead. An authorizer failure is held on the scope, not thrown. */
+export async function authorizeList(authorizer, request, dir, display, scope) {
+    if (authorizer === null)
+        return null;
+    const target = Object.freeze({
+        action: "list",
+        requestedPath: request.path,
+        resolvedPath: dir,
+        displayPath: display,
+        size: null,
+        mtimeMs: null,
+    });
+    try {
+        const result = await runAuthorizer(authorizer, target, scope);
+        if (result.allow)
+            return null;
+        return { ok: false, error: { reason: "denied", detail: "refused by the authorizer" } };
+    }
+    catch (error) {
+        if (error instanceof AbortReadError)
+            return { ok: false, error: { reason: "aborted" } };
+        if (!(error instanceof ReadStop))
+            throw error;
+        scope.hold(error);
+        return { ok: false, error: { reason: "io", detail: "the authorizer failed" } };
+    }
+}
+async function runAuthorizer(authorizer, target, scope) {
+    let decision;
+    try {
+        decision = await raceAbort(() => authorizer.authorize(target, scope.hookContext()), scope.signal);
+    }
+    catch (error) {
+        scope.checkAbort();
+        throw scope.extensionFailure("authorize", extensionId(authorizer, error));
+    }
+    scope.checkAbort();
+    const malformed = () => scope.extensionFailure("authorize", extensionId(authorizer));
+    if (!isRecord(decision))
+        throw malformed();
+    if (decision.allow === true) {
+        const { notes } = decision;
+        if (notes === undefined)
+            return { allow: true };
+        if (!Array.isArray(notes) || !notes.every(isNote))
+            throw malformed();
+        scope.allowNotes.push(...notes);
+        return { allow: true };
+    }
+    if (decision.allow !== false)
+        throw malformed();
+    const { note } = decision;
+    if (note !== undefined && !isNote(note))
+        throw malformed();
+    return { allow: false, note: note ?? null };
+}

package/dist/core/budget.d.ts

@@ -0,0 +1,7 @@
+import type { CallScope } from "./call-scope.ts";
+export interface ScanBudget {
+    readonly max: number;
+    measure(text: string): number;
+}
+/** The host view budget, with a throwing or invalid measure failing the read as EXTENSION_FAILED. */
+export declare function scanBudget<THost>(scope: CallScope<THost>): ScanBudget | null;

package/dist/core/budget.js

@@ -0,0 +1,23 @@
+import { extensionId } from "./extension-error.js";
+/** The host view budget, with a throwing or invalid measure failing the read as EXTENSION_FAILED. */
+export function scanBudget(scope) {
+    const { budget } = scope.deps;
+    if (budget === null)
+        return null;
+    return {
+        max: budget.max,
+        measure(text) {
+            let cost;
+            try {
+                cost = budget.measure(text);
+            }
+            catch (error) {
+                throw scope.extensionFailure("budget", extensionId(budget, error));
+            }
+            if (typeof cost !== "number" || !Number.isFinite(cost) || cost < 0) {
+                throw scope.extensionFailure("budget", extensionId(budget));
+            }
+            return cost;
+        },
+    };
+}

package/dist/core/call-scope.d.ts

@@ -0,0 +1,36 @@
+import type { FileSystem, ListOutcome } from "@better-fs-tools/fs";
+import type { ReadContext } from "../contract/context.ts";
+import type { ReadDependencies } from "../contract/deps.ts";
+import type { ReadHookContext } from "../contract/extensions.ts";
+import type { ReadRequest } from "../contract/input.ts";
+import type { ReadPhase } from "../contract/messages.ts";
+import type { ReadNote } from "../contract/result.ts";
+import type { ReadStateStore } from "../contract/state.ts";
+import { ReadStop } from "./outcomes.ts";
+/** `resolver`: the resolver's `ctx.list`. `open`: suggestions on a miss, or a directory converter. */
+export type ListingSlot = "resolver" | "open";
+export declare class CallScope<THost> {
+    readonly deps: ReadDependencies<THost>;
+    private readonly request;
+    readonly call: ReadContext<THost>;
+    phase: ReadPhase;
+    readonly allowNotes: ReadNote[];
+    private heldFailure;
+    private resolvedFs;
+    private resolvedState;
+    private hook;
+    private readonly listed;
+    constructor(deps: ReadDependencies<THost>, request: ReadRequest, call: ReadContext<THost>);
+    get signal(): AbortSignal | undefined;
+    enter(phase: ReadPhase): void;
+    checkAbort(): void;
+    fileSystem(): FileSystem;
+    stateStore(): ReadStateStore | null;
+    hookContext(): ReadHookContext<THost>;
+    /** One bounded, authorized listing per slot. Never throws: every failure is an error outcome. */
+    list(slot: ListingSlot, dir: string, displayPath?: string): Promise<ListOutcome>;
+    /** Keeps a listing failure out of reach of host code that might catch and ignore it. */
+    hold(stop: ReadStop): void;
+    throwHeld(): void;
+    extensionFailure(extension: string, id?: string | null): ReadStop;
+}