@leuduan/lagent 0.1.2 → 44.0.0

package/dist/{models/wire → records}/journal.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { type ContentPartInput } from '../../llm/index.js';
-import type { DeepReadonly } from '../../util/json.js';
+import { type ContentPartInput } from '../llm/content.js';
+import type { DeepReadonly } from '../util/json.js';
 declare const seq: z.ZodNumber;
 /** Monotonic position in the journal. Assigned by `append`, never by a caller. */
 export type Seq = z.infer<typeof seq>;
@@ -385,7 +385,6 @@ export type ThreadFork = z.infer<typeof ThreadForkSchema>;
 /** Where a thread's work happens. Engine-read and typed, unlike `metadata`. */
 export declare const ThreadEnvironmentSchema: z.ZodObject<{
     cwd: z.ZodString;
-    read_roots: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type ThreadEnvironment = z.infer<typeof ThreadEnvironmentSchema>;
 /**
@@ -867,6 +866,65 @@ export declare const JOURNAL_EVENT_DATA: {
         turn: z.ZodNumber;
         step: z.ZodNumber;
     }, z.core.$strip>;
+    /** A runtime-owned operation preparing one candidate for acceptance; never a model message. */
+    readonly 'execution/requested': z.ZodObject<{
+        turn: z.ZodNumber;
+        candidate_seq: z.ZodNumber;
+        owner: z.ZodString;
+        key: z.ZodString;
+        operation: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    /** Durable before dispatch: an allowed execution without a result may already have taken effect. */
+    readonly 'execution/authorization': z.ZodObject<{
+        turn: z.ZodNumber;
+        request_seq: z.ZodNumber;
+        decision: z.ZodEnum<{
+            allow: "allow";
+            confirm: "confirm";
+            deny: "deny";
+        }>;
+        confirmed_by: z.ZodNullable<z.ZodEnum<{
+            user: "user";
+            policy: "policy";
+        }>>;
+        reasons: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    readonly 'execution/result': z.ZodObject<{
+        request_seq: z.ZodNumber;
+        result: z.ZodObject<{
+            output: z.ZodString;
+            content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"image">;
+                url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                detail: z.ZodDefault<z.ZodEnum<{
+                    auto: "auto";
+                    low: "low";
+                    high: "high";
+                }>>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"file">;
+                file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>], "type">>>;
+            is_error: z.ZodDefault<z.ZodBoolean>;
+            notes: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            concludes_turn: z.ZodOptional<z.ZodLiteral<true>>;
+            call_id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
     /**
      * A dispatched call suspended: its tool waits on a dependency `owner`, a registered constraint
      * owner, alone interprets and resolves. The call stays unanswered and is not dispatched again until
@@ -892,6 +950,7 @@ export declare const JOURNAL_EVENT_DATA: {
         value: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
     }, z.core.$strip>;
     readonly 'confirm/requested': z.ZodObject<{
+        step: z.ZodNumber;
         request_id: z.ZodString;
         tool_call: z.ZodObject<{
             call_id: z.ZodString;
@@ -899,8 +958,14 @@ export declare const JOURNAL_EVENT_DATA: {
             arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$loose>;
         reason: z.ZodString;
+        target: z.ZodObject<{
+            kind: z.ZodEnum<{
+                model: "model";
+                runtime: "runtime";
+            }>;
+            seq: z.ZodNumber;
+        }, z.core.$strict>;
         turn: z.ZodNumber;
-        step: z.ZodNumber;
     }, z.core.$strip>;
     readonly 'confirm/resolved': z.ZodObject<{
         request_id: z.ZodString;
@@ -932,7 +997,6 @@ export declare const JOURNAL_EVENT_DATA: {
         }, z.core.$strip>>>;
         environment: z.ZodObject<{
             cwd: z.ZodString;
-            read_roots: z.ZodArray<z.ZodString>;
         }, z.core.$strip>;
         installations: z.ZodDefault<z.ZodArray<z.ZodObject<{
             installation_id: z.ZodString;
@@ -1254,7 +1318,7 @@ export type JournalEvent<K extends JournalEventType = JournalEventType> = {
 /** Runtime validation for a stored row. Narrow with {@link JournalEvent}, not with `z.infer`. */
 export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     seq: z.ZodNumber;
-    type: z.ZodLiteral<"error" | "ext" | "turn/start" | "turn/end" | "step/start" | "step/end" | "input/message" | "llm/request" | "assistant/message" | "assistant/attempt" | "auxiliary/request" | "auxiliary/result" | "tool/call" | "tool/authorization" | "tool/result" | "wait/declared" | "wait/resolved" | "confirm/requested" | "confirm/resolved" | "thread/spawned" | "installation/applied" | "installation/removed" | "thread/prompt" | "thread/tools" | "run/requested" | "run/cause" | "run/settled" | "thread/cancel" | "inbox/spliced" | "surface/replaced">;
+    type: z.ZodLiteral<"error" | "ext" | "turn/start" | "turn/end" | "step/start" | "step/end" | "input/message" | "llm/request" | "assistant/message" | "assistant/attempt" | "auxiliary/request" | "auxiliary/result" | "tool/call" | "tool/authorization" | "tool/result" | "execution/requested" | "execution/authorization" | "execution/result" | "wait/declared" | "wait/resolved" | "confirm/requested" | "confirm/resolved" | "thread/spawned" | "installation/applied" | "installation/removed" | "thread/prompt" | "thread/tools" | "run/requested" | "run/cause" | "run/settled" | "thread/cancel" | "inbox/spliced" | "surface/replaced">;
     timestamp: z.ZodDefault<z.ZodISODateTime>;
     thread_id: z.ZodString;
     data: z.ZodObject<{
@@ -1729,6 +1793,60 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strip>;
         turn: z.ZodNumber;
         step: z.ZodNumber;
+    }, z.core.$strip> | z.ZodObject<{
+        turn: z.ZodNumber;
+        candidate_seq: z.ZodNumber;
+        owner: z.ZodString;
+        key: z.ZodString;
+        operation: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>;
+    }, z.core.$strip> | z.ZodObject<{
+        turn: z.ZodNumber;
+        request_seq: z.ZodNumber;
+        decision: z.ZodEnum<{
+            allow: "allow";
+            confirm: "confirm";
+            deny: "deny";
+        }>;
+        confirmed_by: z.ZodNullable<z.ZodEnum<{
+            user: "user";
+            policy: "policy";
+        }>>;
+        reasons: z.ZodArray<z.ZodString>;
+    }, z.core.$strip> | z.ZodObject<{
+        request_seq: z.ZodNumber;
+        result: z.ZodObject<{
+            output: z.ZodString;
+            content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"image">;
+                url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                detail: z.ZodDefault<z.ZodEnum<{
+                    auto: "auto";
+                    low: "low";
+                    high: "high";
+                }>>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"file">;
+                file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>], "type">>>;
+            is_error: z.ZodDefault<z.ZodBoolean>;
+            notes: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            concludes_turn: z.ZodOptional<z.ZodLiteral<true>>;
+            call_id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
     }, z.core.$strip> | z.ZodObject<{
         call_id: z.ZodString;
         call_seq: z.ZodNumber;
@@ -1742,6 +1860,7 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         call_seq: z.ZodNumber;
         value: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
     }, z.core.$strip> | z.ZodObject<{
+        step: z.ZodNumber;
         request_id: z.ZodString;
         tool_call: z.ZodObject<{
             call_id: z.ZodString;
@@ -1749,8 +1868,14 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$loose>;
         reason: z.ZodString;
+        target: z.ZodObject<{
+            kind: z.ZodEnum<{
+                model: "model";
+                runtime: "runtime";
+            }>;
+            seq: z.ZodNumber;
+        }, z.core.$strict>;
         turn: z.ZodNumber;
-        step: z.ZodNumber;
     }, z.core.$strip> | z.ZodObject<{
         request_id: z.ZodString;
         approved: z.ZodBoolean;
@@ -1775,7 +1900,6 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strip>>>;
         environment: z.ZodObject<{
             cwd: z.ZodString;
-            read_roots: z.ZodArray<z.ZodString>;
         }, z.core.$strip>;
         installations: z.ZodDefault<z.ZodArray<z.ZodObject<{
             installation_id: z.ZodString;
@@ -1929,7 +2053,7 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     source_seqs: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
 }, z.core.$strip>, ...z.ZodObject<{
     seq: z.ZodNumber;
-    type: z.ZodLiteral<"error" | "ext" | "turn/start" | "turn/end" | "step/start" | "step/end" | "input/message" | "llm/request" | "assistant/message" | "assistant/attempt" | "auxiliary/request" | "auxiliary/result" | "tool/call" | "tool/authorization" | "tool/result" | "wait/declared" | "wait/resolved" | "confirm/requested" | "confirm/resolved" | "thread/spawned" | "installation/applied" | "installation/removed" | "thread/prompt" | "thread/tools" | "run/requested" | "run/cause" | "run/settled" | "thread/cancel" | "inbox/spliced" | "surface/replaced">;
+    type: z.ZodLiteral<"error" | "ext" | "turn/start" | "turn/end" | "step/start" | "step/end" | "input/message" | "llm/request" | "assistant/message" | "assistant/attempt" | "auxiliary/request" | "auxiliary/result" | "tool/call" | "tool/authorization" | "tool/result" | "execution/requested" | "execution/authorization" | "execution/result" | "wait/declared" | "wait/resolved" | "confirm/requested" | "confirm/resolved" | "thread/spawned" | "installation/applied" | "installation/removed" | "thread/prompt" | "thread/tools" | "run/requested" | "run/cause" | "run/settled" | "thread/cancel" | "inbox/spliced" | "surface/replaced">;
     timestamp: z.ZodDefault<z.ZodISODateTime>;
     thread_id: z.ZodString;
     data: z.ZodObject<{
@@ -2404,6 +2528,60 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strip>;
         turn: z.ZodNumber;
         step: z.ZodNumber;
+    }, z.core.$strip> | z.ZodObject<{
+        turn: z.ZodNumber;
+        candidate_seq: z.ZodNumber;
+        owner: z.ZodString;
+        key: z.ZodString;
+        operation: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>;
+    }, z.core.$strip> | z.ZodObject<{
+        turn: z.ZodNumber;
+        request_seq: z.ZodNumber;
+        decision: z.ZodEnum<{
+            allow: "allow";
+            confirm: "confirm";
+            deny: "deny";
+        }>;
+        confirmed_by: z.ZodNullable<z.ZodEnum<{
+            user: "user";
+            policy: "policy";
+        }>>;
+        reasons: z.ZodArray<z.ZodString>;
+    }, z.core.$strip> | z.ZodObject<{
+        request_seq: z.ZodNumber;
+        result: z.ZodObject<{
+            output: z.ZodString;
+            content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"image">;
+                url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                detail: z.ZodDefault<z.ZodEnum<{
+                    auto: "auto";
+                    low: "low";
+                    high: "high";
+                }>>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"file">;
+                file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>], "type">>>;
+            is_error: z.ZodDefault<z.ZodBoolean>;
+            notes: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            concludes_turn: z.ZodOptional<z.ZodLiteral<true>>;
+            call_id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
     }, z.core.$strip> | z.ZodObject<{
         call_id: z.ZodString;
         call_seq: z.ZodNumber;
@@ -2417,6 +2595,7 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         call_seq: z.ZodNumber;
         value: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
     }, z.core.$strip> | z.ZodObject<{
+        step: z.ZodNumber;
         request_id: z.ZodString;
         tool_call: z.ZodObject<{
             call_id: z.ZodString;
@@ -2424,8 +2603,14 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$loose>;
         reason: z.ZodString;
+        target: z.ZodObject<{
+            kind: z.ZodEnum<{
+                model: "model";
+                runtime: "runtime";
+            }>;
+            seq: z.ZodNumber;
+        }, z.core.$strict>;
         turn: z.ZodNumber;
-        step: z.ZodNumber;
     }, z.core.$strip> | z.ZodObject<{
         request_id: z.ZodString;
         approved: z.ZodBoolean;
@@ -2450,7 +2635,6 @@ export declare const JournalEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strip>>>;
         environment: z.ZodObject<{
             cwd: z.ZodString;
-            read_roots: z.ZodArray<z.ZodString>;
         }, z.core.$strip>;
         installations: z.ZodDefault<z.ZodArray<z.ZodObject<{
             installation_id: z.ZodString;
@@ -2611,7 +2795,13 @@ export declare const isSurfaceEvent: (event: JournalEvent) => event is JournalEv
 /** One confirmation a thread still waits on, as its summary lists it: enough to find it, not to show it. */
 export declare const ConfirmationDescriptorSchema: z.ZodObject<{
     request_id: z.ZodString;
-    call_seq: z.ZodNullable<z.ZodNumber>;
+    target: z.ZodObject<{
+        kind: z.ZodEnum<{
+            model: "model";
+            runtime: "runtime";
+        }>;
+        seq: z.ZodNumber;
+    }, z.core.$strict>;
     tool_name: z.ZodString;
     reason: z.ZodString;
 }, z.core.$strip>;
@@ -2660,7 +2850,6 @@ export declare const ThreadSummarySchema: z.ZodObject<{
     }, z.core.$strip>>;
     environment: z.ZodObject<{
         cwd: z.ZodString;
-        read_roots: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
     has_work: z.ZodBoolean;
     turn_open: z.ZodBoolean;
@@ -2723,9 +2912,16 @@ export declare const ThreadSummarySchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>;
     queued_input: z.ZodNumber;
+    queued_for_turn: z.ZodNumber;
     unanswered_confirmations: z.ZodArray<z.ZodObject<{
         request_id: z.ZodString;
-        call_seq: z.ZodNullable<z.ZodNumber>;
+        target: z.ZodObject<{
+            kind: z.ZodEnum<{
+                model: "model";
+                runtime: "runtime";
+            }>;
+            seq: z.ZodNumber;
+        }, z.core.$strict>;
         tool_name: z.ZodString;
         reason: z.ZodString;
     }, z.core.$strip>>;

package/dist/{models/wire/primitives.d.ts → records/toolResult.d.ts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { ContentPart } from '../../llm/index.js';
+import type { ContentPart } from '../llm/content.js';
 export declare const ToolResultPayloadSchema: z.ZodObject<{
     output: z.ZodString;
     content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/services/agents.d.ts

@@ -1,5 +1,6 @@
 import { Context, Service, type ScopeKey } from '@leuduan/cordis';
-import type { AgentDefinition, AgentDefinitionInput } from '../models/index.js';
+import { z } from 'zod';
+import { type AgentDefinition, type AgentDefinitionInput } from '../loop/index.js';
 /** A definition and the layer that registered it: `undefined` for the global one. */
 export type AgentResolution = {
     readonly agent: AgentDefinition;
@@ -35,3 +36,27 @@ export declare class AgentsService extends Service {
 }
 /** Registers an agent in the calling plugin's layer for the lifetime of its fiber. */
 export declare const registerAgent: (ctx: Context, agent: AgentDefinitionInput) => (() => void | Promise<void>);
+/**
+ * The agents a plugin's `agents` option selects. Required wherever it appears: which agents a
+ * composition has is the host's to say, so none of the shipped plugins defaults it. `'global'` is
+ * every globally registered agent, those registered later included; `'all'` is every thread's agent,
+ * scoped ones included; a list names agents, global or scoped.
+ */
+export declare const AgentSelectorSchema: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+export type AgentSelector = readonly string[] | 'global' | 'all';
+/**
+ * Whether `selector` selects `agentName`. One meaning wherever a selector appears, whether the plugin
+ * equips (a grant, a prompt section, a notice) or restricts (a mode, a stop check). `'global'` never
+ * selects a scoped agent (`isScopedAgentName`), so a role child gets only what names it or says
+ * `'all'`; a gate that must cover role children says `'all'`.
+ *
+ * Registries are live, so a selector is a predicate evaluated when the plugin acts — granting,
+ * rendering a prompt section, authorizing a call — rather than a list resolved once at mount.
+ */
+export declare const selects: (selector: AgentSelector, agentName: string) => boolean;
+/**
+ * Whether `name` is an agent name for a scoped registration: one containing a dot, such as
+ * `codex.explore`. Global agent names never contain one, so the two kinds cannot collide, and the
+ * agents registry refuses a registration of the wrong kind.
+ */
+export declare const isScopedAgentName: (name: string) => boolean;

package/dist/services/confinement/files.d.ts

@@ -0,0 +1,118 @@
+import { type Stats } from 'node:fs';
+import type { FileAccess, FilePolicy } from './service.js';
+/**
+ * The scoped file facade: how file tools touch the file system. One implementation, owned by the
+ * operation (`ConfinementOperation.files`), which applies the operation's `FilePolicy` to every
+ * path and ends with the operation. With no policy it authorizes everything but keeps the same
+ * lifetime rules, so a tool cannot tell which it has.
+ *
+ * Every check covers the path as requested (absolute and normalized) and the path it resolves to,
+ * resolved natively so it carries the volume's own spelling, and a path is refused when either is.
+ * A file is opened by its resolved path without following a final link, and the handle is verified
+ * (the file opened is the file approved, and the requested path still leads to it) before any byte
+ * is read through it. This narrows the race between check and use to the revalidation window; it does
+ * not close it, and hard links are not detected.
+ *
+ * Changes are primitives on regular files, never a write of a whole file: a file is created exclusively
+ * (never opened for writing over what exists, and never truncated), and committed by `link` or
+ * `rename`, which the caller owns. A directory is never renamed or removed, and nothing is changed
+ * through a link: the target of a change is refused when it is itself a symbolic link, naming where it
+ * leads. Each primitive judges its paths at the moment it runs, so a path swapped after the caller's
+ * own checks is judged as it is then.
+ */
+/** A refusal by the file policy, whose message is for the model. */
+export declare class FileAccessError extends Error {
+    constructor(message: string);
+}
+/** An open file as a tool may use it: reads only, through the handle the facade verified. */
+export type ReadHandle = {
+    /** Up to `length` bytes from `position`; fewer only at the end of the file. */
+    read(position: number, length: number): Promise<Buffer>;
+    /** All of the file from its start. */
+    readAll(): Promise<Buffer>;
+    /** The opened file's own metadata. */
+    stat(): Promise<Stats>;
+    close(): Promise<void>;
+};
+/** A new file as a tool may fill it: writes only, through the handle the facade created. */
+export type WriteHandle = {
+    /** Appends all of `data`. */
+    write(data: Uint8Array): Promise<void>;
+    /** Flushes what was written to the device. */
+    sync(): Promise<void>;
+    /** The created file's own metadata. */
+    stat(): Promise<Stats>;
+    close(): Promise<void>;
+};
+/** Which access a call judges its paths for: a read unless the caller says what it intends. */
+export type PathOptions = {
+    readonly access?: readonly FileAccess[];
+};
+/** One entry of a directory the policy lets through. */
+export type DirEntry = {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly isSymbolicLink: boolean;
+};
+/** A directory's allowed entries, and how many the policy hid. */
+export type DirListing = {
+    readonly entries: readonly DirEntry[];
+    readonly hidden: number;
+};
+/**
+ * What a tool does to files, within one operation. Paths are absolute. Every method rejects with a
+ * {@link FileAccessError} for a path the policy refuses, and with an ordinary error once the
+ * operation has ended or was aborted: a reference that outlives its call is dead.
+ */
+export type FileScope = {
+    /**
+     * Names how this facade judges reads (`FilePolicy.identity`, or `unrestricted` with no policy): taking
+     * it takes the operation's snapshot, so a refused operation rejects here. What a reader that keeps
+     * its result for another thread to use keys it by.
+     */
+    identity(): Promise<string>;
+    /** Opens a file for reading, where links resolve and are checked. Never a raw descriptor. */
+    open(path: string): Promise<ReadHandle>;
+    /** The entries of a directory, with every entry the policy refuses (or a link resolving to one) left out and counted. */
+    readdir(path: string): Promise<DirListing>;
+    /** Metadata of the file a path leads to. */
+    stat(path: string, options?: PathOptions): Promise<Stats>;
+    /** Metadata of a path itself, not of what a final link leads to. */
+    lstat(path: string, options?: PathOptions): Promise<Stats>;
+    /**
+     * The path with every link resolved, as the checks see it; a missing tail stays as named, after the
+     * nearest existing ancestor's real path. `options.access` names what the caller means to do with it.
+     */
+    realpath(path: string, options?: PathOptions): Promise<string>;
+    /**
+     * Creates a new file that must not exist, with `mode` as given, for writing; never replaces or truncates.
+     * A `temporary` file is the caller's scratch: it may be removed with `unlink` even after a cancellation,
+     * and is removed when the operation ends unless the caller has put it elsewhere.
+     */
+    create(path: string, options?: {
+        readonly mode?: number;
+        readonly temporary?: boolean;
+    }): Promise<WriteHandle>;
+    /** Creates a directory and any missing parents. */
+    mkdir(path: string): Promise<void>;
+    /** Hard-links the regular file `existing` as `created`, which must not exist. */
+    link(existing: string, created: string): Promise<void>;
+    /** Renames a regular file over `to`, which is absent or a regular file; a directory is never renamed. */
+    rename(from: string, to: string): Promise<void>;
+    /** Removes a regular file; a directory is never removed. A `temporary` file this operation created goes even after a stop. */
+    unlink(path: string): Promise<void>;
+    /** Sets the mode of a regular file. */
+    chmod(path: string, mode: number): Promise<void>;
+};
+/** What the operation hands its facade. */
+export type FileScopeHost = {
+    /** The operation's policy, which the first call takes; `null` for no path policy. Rejects when the operation is refused. */
+    policy(): Promise<FilePolicy | null>;
+    /** Aborts when the call is cancelled, the operation ends or its handler is released: checked between file system calls. */
+    signal(): AbortSignal;
+};
+/** The facade's lifetime: `end` closes what it opened and kills its methods. */
+export type EndableFileScope = FileScope & {
+    end(): Promise<void>;
+};
+export declare function fileScope(host: FileScopeHost): EndableFileScope;