@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/plugins/delegations/tools.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+export declare const LIST_AGENTS_TOOL = "list_agents";
+export declare const READ_AGENT_TOOL = "read_agent";
+export declare const STOP_AGENT_TOOL = "stop_agent";
+/**
+ * The tools the `delegations` plugin registers, granted to nobody: continuing, listing, reading and
+ * stopping the children a thread started, whichever tool started them. A preset grants them wherever
+ * it grants a start tool.
+ */
+export declare const DELEGATION_TOOLS: readonly ["message_agent", "list_agents", "read_agent", "stop_agent"];
+/**
+ * Validates a `message_agent` call, and is the source of the schema advertised to the model: one
+ * object, whose `kind` says which of the two gestures the call is. `background` and the route fields
+ * belong to `continue`; a steer naming one is refused as invalid arguments.
+ */
+export declare const MessageAgentParameters: z.ZodPreprocess<z.ZodObject<{
+    thread_id: z.ZodString;
+    kind: z.ZodEnum<{
+        continue: "continue";
+        steer: "steer";
+    }>;
+    message: z.ZodString;
+    background: z.ZodDefault<z.ZodBoolean>;
+    provider: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    model: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    thinking_effort: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+        low: "low";
+        high: "high";
+        none: "none";
+        medium: "medium";
+        max: "max";
+    }>>>;
+}, z.core.$strip>, unknown>;
+/**
+ * Messages a child this thread created, whichever start tool made it; `kind` is required and kept
+ * across a re-dispatch, so a correction never becomes a new assignment.
+ *
+ * `continue` opens the child's next task, queued as plain input with the task's `started` row under
+ * an id derived from this call, and the child runs on its own history; blocking, it waits for the
+ * answer, and with `background` it returns a receipt. A fork is not framed as a fork task again.
+ * Refused without a turn when the id names no thread, a thread this one did not create, or a child
+ * that stopped mid-work or still has a task open; a child a run holds is refused busy. A
+ * re-dispatch returns the recorded answer, or the receipt, without judging the route again.
+ *
+ * `steer` queues a correction into the task the call addresses, by row order as `read_agent` and
+ * `stop_agent` do, while that task's own drive runs the child (`ctx.delegations.steer`), and returns
+ * at once; it is refused, naming the outcome, on a task that has ended, and naming the state on one
+ * nothing runs now, a child whose run has not started yet included: the call never waits for a run
+ * to start, since the caller's own run slot may be what that run waits for, and its model tries
+ * again later. A re-dispatch reports what became of the message it sent.
+ */
+export declare const messageAgentTool: import("../../loop/tool.js").Tool;
+/** `list_agents`: this thread's children, however they were started, from the catalog. */
+export declare const listAgentsTool: import("../../loop/tool.js").Tool;
+/**
+ * `read_agent`: each named child's addressed task, its state and, once it settled, its answer or
+ * its failure (a background task's only when its notice does not carry it, or with `full`), or
+ * before that its recent activity; and the child's status now. Waits through `ctx.delegations.read`,
+ * a durable wait that releases the caller's run slot, for any named task to settle, or with
+ * `activity` for any named child to record anything, until nothing can advance them or the time is
+ * up; dispatched again once that wait resolves, it reports where the tasks stand then.
+ */
+export declare const readAgentTool: import("../../loop/tool.js").Tool;
+/**
+ * `stop_agent`: stops the addressed task of a child this thread started, by `ctx.delegations.stop`
+ * with this call's seq, and returns once the stop is durable. A settled task keeps its outcome, and
+ * a late turn its run still runs is cut off; a newer task of the child is never touched. A rerun
+ * repeats its own reply: the `stopped` row names the call that wrote it. The reply also says what
+ * the child is doing now.
+ */
+export declare const stopAgentTool: import("../../loop/tool.js").Tool;

package/dist/plugins/delegations/waitContracts.d.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import type { ResolvedWait } from '../../loop/index.js';
+import type { TaskRef } from './record.js';
+import type { DelegationOutcome } from './request.js';
+export declare const TaskWaitSchema: z.ZodObject<{
+    task_id: z.ZodString;
+    child_id: z.ZodString;
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"task">;
+}, z.core.$strict>;
+export type TaskWait = z.output<typeof TaskWaitSchema>;
+export declare const ReadWaitSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"read">;
+    tasks: z.ZodArray<z.ZodObject<{
+        task_id: z.ZodString;
+        child_id: z.ZodString;
+    }, z.core.$strict>>;
+    until: z.ZodEnum<{
+        settled: "settled";
+        activity: "activity";
+    }>;
+    since: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strict>;
+export type ReadWait = z.output<typeof ReadWaitSchema>;
+/**
+ * What a delegating call waits on, as its `wait/declared` row records it, versioned by delegations:
+ * a blocking call waits on its `task`; `read_agent` on the first of its named tasks to settle, or
+ * with `until: 'activity'` to record anything after `since` (each child's `through_seq` as the call
+ * looked), until its deadline.
+ */
+export declare const DelegationWaitSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    task_id: z.ZodString;
+    child_id: z.ZodString;
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"task">;
+}, z.core.$strict>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"read">;
+    tasks: z.ZodArray<z.ZodObject<{
+        task_id: z.ZodString;
+        child_id: z.ZodString;
+    }, z.core.$strict>>;
+    until: z.ZodEnum<{
+        settled: "settled";
+        activity: "activity";
+    }>;
+    since: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strict>], "kind">;
+export type DelegationWait = z.output<typeof DelegationWaitSchema>;
+/**
+ * A blocking call's value: the answer chosen as its task's serving run settled, not handed on to a
+ * successor, or was held for a cancellation or a failure; and that run's state then. A later change
+ * of the task's state cannot change an answer recorded.
+ */
+export declare const TaskValueSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"task">;
+    outcome: z.ZodObject<{
+        status: z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+        }>;
+        output: z.ZodString;
+    }, z.core.$strict>;
+    run_id: z.ZodString;
+    state: z.ZodEnum<{
+        settled: "settled";
+        held: "held";
+    }>;
+    reason: z.ZodString;
+    error_text: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type TaskValue = z.output<typeof TaskValueSchema>;
+/**
+ * Why a `read_agent` wait returned: a named task ended (`settled`); a named child recorded anything,
+ * with `until: 'activity'`; nothing can advance a named open task (`no_progress`); or the deadline.
+ */
+export declare const ReadWhySchema: z.ZodEnum<{
+    timeout: "timeout";
+    settled: "settled";
+    activity: "activity";
+    no_progress: "no_progress";
+}>;
+export type ReadWhy = z.output<typeof ReadWhySchema>;
+export declare const ReadValueSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"read">;
+    why: z.ZodEnum<{
+        timeout: "timeout";
+        settled: "settled";
+        activity: "activity";
+        no_progress: "no_progress";
+    }>;
+}, z.core.$strict>;
+/** A blocking call's dependency. */
+export declare const taskWait: (task: TaskRef) => TaskWait;
+/** A blocking call's value. */
+export declare const taskValue: (outcome: DelegationOutcome, run: {
+    readonly runId: string;
+    readonly state: "settled" | "held";
+    readonly reason: string;
+    readonly errorText: string | null;
+}) => TaskValue;
+/** The children a wait names: a blocking call's task's, or each a read names. */
+export declare const waitedOn: (wait: DelegationWait) => string[];
+/** The tasks a read wait names, as task references. */
+export declare const readTasks: (wait: ReadWait) => TaskRef[];
+/** A blocking call's recorded answer, from the wait it resolved; throws on a payload of another version or kind. */
+export declare function taskAnswer(wait: ResolvedWait): {
+    readonly childId: string;
+    readonly outcome: DelegationOutcome;
+};
+/** A `read_agent` call's resolved wait: the tasks it named, and why it returned. */
+export declare function readAnswer(wait: ResolvedWait): {
+    readonly tasks: TaskRef[];
+    readonly why: ReadWhy;
+};

package/dist/plugins/delegations/waitResolver.d.ts

@@ -0,0 +1,116 @@
+import type { Context } from '@leuduan/cordis';
+import { type Clock } from '../../util/timers.js';
+import type { JournalEvent } from '../../records/journal.js';
+import type { OwnerHandle } from '../../services/threads/index.js';
+import type { NoticeDelivery } from './notices.js';
+import { type ReadWait, type ReadWhy } from './waitContracts.js';
+/**
+ * Why a read wait returns now, or `null` while it waits: a named task ended (`settled`); with
+ * `activity`, a named child recorded a row after the read looked; nothing can advance a named open
+ * task (`no_progress`): none of their children runs, waits to run, or is held for something that
+ * passes, such as an approval, a wait of its own, the startup policy, a missing owner or a
+ * constraint. Read from the catalog and the owner, synchronously.
+ */
+export declare function readCondition(ctx: Context, wait: ReadWait): ReadWhy | null;
+/** What the resolver is handed by the service that mounts it. */
+export type WaitResolverOptions = {
+    /** The clock `read_agent`'s deadlines and the retries of failed decisions are kept on. */
+    readonly clock: Clock;
+    /** Resolves once the task state can be served: no decision is taken before. */
+    readonly ready: Promise<void>;
+    /** Whose notices a read that finds a task ended waits to be durable. */
+    readonly notices: NoticeDelivery;
+    /** The task constraint's registration, which resolves the waits; `undefined` while not registered. */
+    readonly constraint: () => OwnerHandle | undefined;
+};
+/**
+ * Every delegation wait, from its `wait/declared` row to its call's answer: the one owner of when a
+ * blocking call's or a `read_agent` call's wait resolves, and with what. A blocking call's wait
+ * resolves once its task's serving run settles, not handed on to a successor, or is held for a
+ * person's cancellation or a failure, with the answer chosen then; a read's once a named task ended,
+ * after that task's notice is durable, a named child recorded anything, nothing can advance them, or
+ * its deadline. The condition is read again inside the resolving write, which declines when it no
+ * longer holds.
+ *
+ * Its index is kept by rows alone, never by reading core's wait state: a declaration under
+ * delegations is booked, its resolution stops its deadline and its decisions, and its call's answer
+ * forgets it; any row or run event of a child a wait names decides that wait again. One decision at
+ * a time per wait: a trigger meanwhile is handed the one under way, and decides again after it. A
+ * decision that fails, reading or writing, is reported and taken again later, so a wait nothing else
+ * would trigger again is not lost with it. Its task's child is told whenever a blocking call starts
+ * or stops being its task's authority: as the wait is declared, and as the call is answered.
+ *
+ * The repair books every wait the catalog shows suspended on delegations, and decides at once those
+ * satisfied while the process was down; the drain stops deciding at shutdown, leaving what is due to
+ * the next startup's repair.
+ */
+export declare class WaitResolver {
+    /** Every delegation wait whose call is not answered yet, by caller and call. */
+    private readonly waits;
+    /** The unresolved waits by each child they name. */
+    private readonly waitsOn;
+    /** The decision under way for each wait, and the waits to decide again once it is done. */
+    private readonly checking;
+    private readonly recheck;
+    /** Decisions that failed, by wait: each is taken again later (`retryLater`). */
+    private readonly retries;
+    /** `read_agent`'s deadlines. */
+    private readonly deadlines;
+    private closing;
+    private readonly ctx;
+    private readonly options;
+    constructor(ctx: Context, options: WaitResolverOptions);
+    /**
+     * What a row does to the resolver: a declaration naming delegations is booked; a resolution stops
+     * deciding its wait, and a result of a booked call forgets it, telling a blocking call's task's
+     * child, whose authority the call was; any row of a child a wait names decides that wait again, so
+     * `until: 'activity'` sees the row and a task that ended is seen at once.
+     */
+    onRow(event: JournalEvent): void;
+    /** Decides again every unresolved wait naming `threadId`, after a run event of it. */
+    onRunEvent(threadId: string): void;
+    /**
+     * The startup repair of delegation waits: every caller the catalog shows suspended on delegations
+     * is read, its waits booked, and the unresolved ones decided, so a read's deadline that passed
+     * meanwhile times out and a wait whose child finished while the process was down resolves now.
+     * Resolves once those writes have landed, so the startup policy judges their causes.
+     */
+    repair(): Promise<void>;
+    /** Stops deciding, so the next startup's repair decides what is due; resolves once each decision under way has landed. */
+    drain(): Promise<void>;
+    /**
+     * Books a declared delegation wait: indexed by its caller's call and, until it resolves, by each
+     * child it names, a read's deadline armed, and its condition checked at once, since the child may
+     * have finished first. Its task's child is told: the call waiting is now its task's authority. A
+     * wait the repair finds resolved is only kept until its call is answered.
+     */
+    private book;
+    /** Stops deciding a wait whose value is recorded: its call waits only to be dispatched again. */
+    private resolved;
+    /** Forgets a wait whose call was answered, resolved or not; a blocking call's task's child is told. */
+    private answered;
+    private stopDeciding;
+    /** Checks every unresolved wait naming `childId`, after a row or a run event of it. */
+    private checkWaitsOn;
+    /** Resolves the wait under `key` if its condition holds, one decision at a time; see the class. */
+    private check;
+    /** One decision of `check`. */
+    private resolveIfDue;
+    /** Takes a failed decision again later, while its wait is still decided. */
+    private retryLater;
+    /**
+     * Where a blocking task's serving run stands once it lets its call's wait resolve, or `null` while
+     * the call keeps waiting: settled, not handed on to a successor (the task fold follows the run
+     * while the task is open, so a settled serving run is the last); or held for a person's
+     * cancellation or a failure. It keeps waiting through every hold that passes, an approval or a
+     * startup decline included. Read at the owner's published boundary, never from a raw row.
+     */
+    private taskRun;
+    /**
+     * What a blocking call is told once its task's serving run lets its wait resolve: the task's
+     * outcome once it settled; otherwise why the task did not end, which the call's result then ends
+     * it for: a person's cancel of the child, a failure it is held on, or a run that settled with the
+     * task still open.
+     */
+    private taskOutcome;
+}

package/dist/plugins/diagnostics/digest.d.ts

@@ -0,0 +1,14 @@
+import type { ConversationMessage } from '../../llm/primitives.js';
+import { type DeepReadonly } from '../../util/json.js';
+import type { SentModelRequest } from '../../loop/index.js';
+/** Enough of a fingerprint to tell one value from another across restarts. */
+export declare const digestOf: (text: string) => string;
+/**
+ * A digest of everything a request sends ahead of its messages: the prompt,
+ * the tools and every option, the model included. Correlation, the ids and the purpose, is left
+ * out, so two threads sending the same head get the same digest — which is what a fork's prefix
+ * check compares.
+ */
+export declare function headDigest(request: SentModelRequest): string;
+/** A digest of a message list; a prefix of it digests the same as the same messages sent alone. */
+export declare const messagesDigest: (messages: readonly DeepReadonly<ConversationMessage>[]) => string;

package/dist/plugins/diagnostics/index.d.ts

@@ -0,0 +1,68 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { PluginJournal } from '../../journal/index.js';
+import type { RowRef } from '../../state/index.js';
+/**
+ * How a fork's first request compares with its source's request at the cut: whether it sent the
+ * same head and route, and extended the same messages. `unavailable` when there is nothing to
+ * compare with: the fork was cut before its source asked the model, or that request was never
+ * measured. Measured, not enforced: nothing sent is altered.
+ */
+export declare const PrefixCheckSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        unavailable: "unavailable";
+        matched: "matched";
+        mismatched: "mismatched";
+    }>;
+    differs: z.ZodArray<z.ZodEnum<{
+        route: "route";
+        head: "head";
+        messages: "messages";
+    }>>;
+    replaced: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export type PrefixCheck = z.infer<typeof PrefixCheckSchema>;
+declare const MeasuresSchema: z.ZodObject<{
+    purpose: z.ZodEnum<{
+        step: "step";
+        auxiliary: "auxiliary";
+    }>;
+    system_prompt_chars: z.ZodNumber;
+    system_prompt_digest: z.ZodString;
+    head_digest: z.ZodString;
+    messages_digest: z.ZodString;
+    prefix_check: z.ZodNullable<z.ZodObject<{
+        status: z.ZodEnum<{
+            unavailable: "unavailable";
+            matched: "matched";
+            mismatched: "mismatched";
+        }>;
+        differs: z.ZodArray<z.ZodEnum<{
+            route: "route";
+            head: "head";
+            messages: "messages";
+        }>>;
+        replaced: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** What the plugin measured of one request. */
+export type RequestMeasures = z.output<typeof MeasuresSchema>;
+/**
+ * Measures every model request a thread sends, through `lagent/llm/sent`, and records it as an `ext`
+ * row citing the request row: the prompt's size and digest, a digest of the head, one of the
+ * messages, and on a fork's first model step how it compares with its source's request at the cut,
+ * which tells whether it can reuse the source's cached prefix. A mismatch with no replacement since
+ * the reference is reported. Mount it on the untagged application context.
+ *
+ * ```ts
+ * await root.plugin(diagnostics)
+ * ```
+ */
+export declare const diagnostics: Plugin.Object<undefined>;
+/**
+ * What was measured of the request recorded at `row`, or `undefined` when it was not: the plugin
+ * was not mounted then, or the request row is not loaded. Found on the request's own thread, by
+ * the citation, wherever it lies, since a fork cut at a request row is cut before its measures.
+ */
+export declare function requestMeasures(journal: Pick<PluginJournal, 'rowsAfter'>, row: RowRef): RequestMeasures | undefined;
+export {};

package/dist/plugins/diagnostics/index.js

@@ -0,0 +1 @@
+import{d as y}from"../../chunks/S34ZA2R6.js";import{b as q}from"../../chunks/6FRNHMCV.js";import"../../chunks/CUK7CGC7.js";import"../../chunks/BPRCULZH.js";import"../../chunks/DDANMY45.js";import{c}from"../../chunks/BBCW2FZK.js";import"../../chunks/MMNNZCBO.js";import"../../chunks/G44LG6VL.js";import{A as _}from"../../chunks/D4PQP5MA.js";import{z as r}from"zod";import{createHash as I}from"node:crypto";var m=e=>I("sha256").update(e).digest("hex").slice(0,12);function b(e){let{messages:s,agentName:t,threadId:a,llmCallId:o,purpose:n,...u}=e;return m(c(u))}var f=e=>m(c(e));var S=r.strictObject({status:r.enum(["matched","mismatched","unavailable"]),differs:r.array(r.enum(["head","route","messages"])),replaced:r.number().int().positive().nullable()}),j=r.strictObject({purpose:r.enum(["step","auxiliary"]),system_prompt_chars:r.number().int().nonnegative(),system_prompt_digest:r.string(),head_digest:r.string(),messages_digest:r.string(),prefix_check:S.nullable()}),x=q({plugin:"lagent:diagnostics",kind:"request",version:1,schema:j}),L={name:"lagent:diagnostics",inject:["journal"],apply(e){y(e,"diagnostics"),e.on("lagent/llm/sent",async({request:s,row:t})=>{let a=_(s.systemPrompt),o=b(s),n=t.type==="llm/request"?E(e.journal,t,o,s.messages):null;await x.append(e.journal,{purpose:s.purpose,system_prompt_chars:a.length,system_prompt_digest:m(a),head_digest:o,messages_digest:f(s.messages),prefix_check:n},{threadId:t.thread_id,sourceSeqs:[t.seq]}),n?.status==="mismatched"&&n.replaced===null&&e.reportError(new Error(`Thread ${t.thread_id}: a fork's first request differs from its source's in ${n.differs.join(", ")}`))})}};function D(e,s){for(let t of e.rowsAfter(s.threadId,s.seq)){if(!t.source_seqs.includes(s.seq))continue;let a=x.read(t);if(a!==void 0)return a}}function E(e,s,t,a){let o=e.rows(s.thread_id),n=o[0];if(n?.type!=="thread/spawned"||n.data.fork===null||o.some(i=>i.type==="llm/request"&&i.seq!==s.seq))return null;let{thread_id:u,seq:v}=n.data.fork,d=e.lineage(u,v).findLast(i=>i.type==="llm/request");if(d===void 0||d.type!=="llm/request")return k;let p=D(e,{threadId:d.thread_id,seq:d.seq});if(p===void 0)return k;let l=[];t!==p.head_digest&&l.push("head"),c(s.data.route)!==c(d.data.route)&&l.push("route");let g=d.data.message_count,h=null;return(a.length<g||f(a.slice(0,g))!==p.messages_digest)&&(l.push("messages"),h=e.lineage(s.thread_id).find(i=>i.type==="surface/replaced"&&i.seq>d.seq&&i.seq<s.seq)?.seq??null),{status:l.length===0?"matched":"mismatched",differs:l,replaced:h}}var k={status:"unavailable",differs:[],replaced:null};export{S as PrefixCheckSchema,L as diagnostics,D as requestMeasures};

package/dist/plugins/fileTools/config.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/**
+ * What the file tools are configured with, all of it the host's choice: the spawn environment and
+ * the trusted `rg` the search tools run (`rg: null` for none).
+ */
+export declare const FileToolsConfigSchema: z.ZodObject<{
+    environment: z.ZodRecord<z.ZodString, z.ZodString>;
+    rg: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FileToolsConfig = z.input<typeof FileToolsConfigSchema>;

package/dist/plugins/fileTools/editFiles.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import type { InvocationContext } from '../../loop/index.js';
+import type { ToolResultPayload } from '../../records/toolResult.js';
+import type { FileAccess } from '../../services/confinement/service.js';
+import { type UnifiedDiff } from '../../util/diff.js';
+/** The largest file `edit_files` reads, which bounds the memory one call takes. */
+export declare const MAX_EDIT_FILE_BYTES: number;
+declare const OperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"create">;
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"update">;
+    path: z.ZodString;
+    hunks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        old_text: z.ZodString;
+        new_text: z.ZodString;
+    }, z.core.$strict>>>;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"delete">;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"move">;
+    path: z.ZodString;
+    to: z.ZodString;
+    hunks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        old_text: z.ZodString;
+        new_text: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>], "op">;
+type Operation = z.infer<typeof OperationSchema>;
+/**
+ * The one tool that changes files: creates, updates, deletes and moves, any number in one call.
+ *
+ * Everything is checked before anything is written: every path is judged by the call's file policy
+ * (read and write for what is changed or moved, write for what is created or moved to) and kept out
+ * of every git directory, every file read, every hunk located, and the operations checked against
+ * each other. Each file is then written to a temporary sibling and renamed over its target, or
+ * hard-linked into place when it must not replace anything, so no reader sees half of it; a
+ * filesystem without hard links gets no new file. The call touches files only through its
+ * operation's facade, which judges every step again as it happens, and never opens an existing file
+ * for writing. There is no transaction across files: when one
+ * fails to commit, or the call is cancelled, the call stops there, before its next filesystem
+ * change, and its result says which files were committed and which were not.
+ *
+ * Calls are serialized per file across every thread of the process: each holds its files' locks
+ * from reading them to the last rename, and re-checks each file just before replacing it, so a
+ * change by anything else in between fails that file instead of being overwritten.
+ */
+export declare const editFilesTool: import("../../loop/tool.js").Tool;
+/** A path an operation names: as named, as shown, and where it really is. */
+type Target = {
+    readonly named: string;
+    /** Resolved against the cwd, symbolic links kept. */
+    readonly absolute: string;
+    /** As results show it. */
+    readonly display: string;
+    /** With its symbolic links resolved: what is read, written, compared and locked. */
+    readonly real: string;
+    /** What the policy was asked to allow for it, and is asked again when it is committed. */
+    readonly access: readonly FileAccess[];
+};
+/** What a file was when it was read, to tell whether it changed before it is replaced. */
+type Snapshot = {
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly hash: string;
+    readonly mode: number;
+    /** Which file it was: a file replaced by another with the same content is not the one that was read. */
+    readonly dev: number;
+    readonly ino: number;
+};
+type Planned = {
+    readonly kind: 'created';
+    readonly target: Target;
+    readonly bytes: Buffer;
+    readonly lines: number;
+} | {
+    readonly kind: 'updated';
+    readonly target: Target;
+    readonly snapshot: Snapshot;
+    readonly bytes: Buffer;
+    readonly diff: UnifiedDiff;
+    /** The hunks that matched loosely, each as the result words it. */
+    readonly looseHunks: readonly string[];
+} | {
+    readonly kind: 'deleted';
+    readonly target: Target;
+    readonly snapshot: Snapshot;
+    readonly lines: number | null;
+} | {
+    readonly kind: 'moved';
+    readonly target: Target;
+    readonly to: Target;
+    readonly snapshot: Snapshot;
+    readonly bytes: Buffer;
+    readonly diff: UnifiedDiff | null;
+    readonly looseHunks: readonly string[];
+};
+/** One file's outcome, as `metadata.files` records it. */
+export type EditedFile = {
+    readonly path: string;
+    readonly kind: Planned['kind'];
+    /** A move's destination. */
+    readonly to?: string;
+    readonly added: number;
+    readonly removed: number;
+    /** `destination_only`: a move whose destination was written and whose source could not be removed. */
+    readonly status: 'committed' | 'not_committed' | 'destination_only';
+};
+/**
+ * Applies `operations` for a call: the whole of `edit_files` but its parameter parsing. See
+ * {@link editFilesTool}.
+ */
+export declare function applyFileOperations(operations: readonly Operation[], context: InvocationContext): Promise<ToolResultPayload>;
+export {};

package/dist/plugins/fileTools/fsRead.d.ts

@@ -0,0 +1,17 @@
+/** The most lines one read returns. */
+export declare const MAX_LINES_PER_READ = 2000;
+/** The most bytes of a file's lines one read returns, line numbers aside. */
+export declare const MAX_PAGE_BYTES: number;
+/** A longer line is cut to this many characters, and the cut is stated. */
+export declare const MAX_LINE_CHARS = 2000;
+/**
+ * The largest image `read_file` answers with as an image: low, as the `mcp` plugin's default is,
+ * because an image stays in the conversation and every later request sends it again.
+ */
+export declare const MAX_IMAGE_BYTES: number;
+export declare const readFileTool: import("../../loop/tool.js").Tool;
+/** The image type a file's first bytes declare, for the formats a model reads. */
+export declare function imageMediaType(head: Buffer): string | null;
+/** Directories that only ever hold build output, dependencies or version control. */
+export declare const SKIPPED_DIRECTORIES: ReadonlySet<string>;
+export declare const listDirTool: import("../../loop/tool.js").Tool;

package/dist/plugins/fileTools/gitDiscovery.d.ts

@@ -0,0 +1,9 @@
+import type { FileScope } from '../../services/confinement/files.js';
+import type { RepositoryLocation } from '../../sys/git.js';
+/**
+ * The repository containing `path`: the nearest directory at or above it holding a `.git` entry, as
+ * `findRepository` finds it, with every file read through `files`. A path the policy refuses to be
+ * read rejects with its `FileAccessError`, since whether it is git's own cannot then be told; a file
+ * system error counts as not there.
+ */
+export declare function findRepositoryThrough(files: FileScope, path: string): Promise<RepositoryLocation | null>;

package/dist/plugins/fileTools/index.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from '@leuduan/cordis';
+import { type FileToolsConfig } from './config.js';
+export type { FileToolsConfig } from './config.js';
+/** The file tools that read the workspace without changing it. */
+export declare const READ_ONLY_TOOLS: readonly ["read_file", "list_dir", "rg_search", "rg_files"];
+/** The file tools that run `rg`, provided only where the host has it (`rg` in the configuration). */
+export declare const RG_TOOLS: readonly string[];
+/**
+ * Registers `read_file`, `list_dir`, `rg_search`, `rg_files` and `edit_files` for the life of the
+ * plugin. A tool reaches files through `InvocationContext.operation`, so the confinement policy
+ * judges every path; the host names the spawn environment and the trusted `rg` the search tools
+ * run, and there is no default for either.
+ *
+ * Ungranted: `agents` choose which of them each agent sees. The web tools ship as `webTools`, the
+ * shell commands as `commands`, which owns their processes, and `ask_question` as the `lagent:ask`
+ * plugin, since it needs a host that can reach the user.
+ */
+export declare const fileTools: Plugin.Object<FileToolsConfig>;

package/dist/plugins/fileTools/index.js

@@ -0,0 +1 @@
+import{a,b,c}from"../../chunks/IAAEP6VL.js";import"../../chunks/VYMT4TXD.js";import"../../chunks/N6IXG2VL.js";import"../../chunks/6DRCKZ2C.js";import"../../chunks/7LI64H5X.js";import"../../chunks/3UMZMPWW.js";import"../../chunks/34KW6VNQ.js";import"../../chunks/JFX2MXBA.js";import"../../chunks/CUK7CGC7.js";import"../../chunks/BPRCULZH.js";import"../../chunks/FJLU4UH3.js";import"../../chunks/DDANMY45.js";import"../../chunks/BBCW2FZK.js";import"../../chunks/MMNNZCBO.js";import"../../chunks/G44LG6VL.js";import"../../chunks/D4PQP5MA.js";export{a as READ_ONLY_TOOLS,b as RG_TOOLS,c as fileTools};

package/dist/plugins/fileTools/ripgrep.d.ts

@@ -0,0 +1,20 @@
+import type { Tool } from '../../loop/index.js';
+import { type SpawnEnvironment } from '../../sys/spawn.js';
+/**
+ * What both search tools run: the trusted `rg`, in the host's spawn environment, and how long one
+ * search's `rg` may run before what it found so far is returned as partial.
+ */
+export type SearchProgram = {
+    rg: string;
+    environment: SpawnEnvironment;
+    timeoutMs: number;
+};
+/** The most matches one search returns. */
+export declare const MAX_RG_RESULTS = 200;
+/** `rg_search`, running the trusted `rg` in the host's environment; its name and description say so. */
+export declare const rgSearchTool: (program: SearchProgram) => Tool;
+/**
+ * `rg_files`: `rg --files` lists what the search admits, and the pattern is matched against each
+ * listed path, relative to the search directory, so a pattern never lets an ignored file in.
+ */
+export declare const rgFilesTool: (program: SearchProgram) => Tool;