@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/plugins/store/durableObjectConnection.d.ts

@@ -0,0 +1,27 @@
+import type { SqlConnection, SqlExclusivity, SqlValue } from './sql.js';
+/**
+ * The part of a Durable Object's `ctx.storage` the store uses, typed structurally so this package
+ * takes no dependency on the Workers types. The real object satisfies it as it is.
+ */
+export type DurableObjectStorage = {
+    sql: {
+        exec(query: string, ...bindings: SqlValue[]): {
+            toArray(): unknown[];
+        };
+    };
+    transactionSync<T>(body: () => T): T;
+    sync(): Promise<void>;
+};
+/**
+ * Runs the store's SQL on the object's own SQLite. A transaction's local commit is synchronous, and
+ * its result resolves only after `sync()` confirms the write is durable. A `sync()` rejection is the
+ * transaction's failure and rolls nothing back: the local commit completed and may have persisted.
+ */
+export declare function durableObjectConnection(storage: DurableObjectStorage): SqlConnection;
+/**
+ * The one writer of a storage. Wrappers over the same storage share the entry, so a second
+ * acquisition is refused whichever wrapper makes it; the platform runs one instance of an object,
+ * but that instance can still hold two stores over one `ctx.storage`. Release clears only the
+ * entry this acquisition made, so a stale release never clears a replacement's.
+ */
+export declare function durableObjectExclusivity(storage: object, identity: string): SqlExclusivity;

package/dist/plugins/store/memory.d.ts

@@ -0,0 +1,29 @@
+import type { JournalEvent, Seq, ThreadSummary } from '../../models/index.js';
+import { JournalStore, type AppendOutcome, type Attempt, type ThreadIndexEntry, type WriterLease } from '../../journal/index.js';
+/**
+ * In-memory backing, keeping serialized rows so it exercises the same round trip as SQLite. Its
+ * writer lease is exclusive within the process, which is as far as its rows reach.
+ */
+export declare class MemoryJournalStore extends JournalStore {
+    private readonly rows;
+    /** Each row's thread and seq, so a read need not parse every row. */
+    private readonly index;
+    private readonly threadIndex;
+    private readonly catalog;
+    private readonly attempts;
+    /** The acquisition the writer record names; `undefined` while nobody holds the lease. */
+    private writer;
+    get size(): number;
+    acquireWriter(): Promise<WriterLease>;
+    protected doOpen(): Promise<void>;
+    protected doClose(): Promise<void>;
+    protected doHead(): Promise<Seq>;
+    protected doAppend(attempt: Attempt, digest: string): Promise<AppendOutcome>;
+    protected doRead(threadId: string): Promise<JournalEvent[]>;
+    protected doRowAt(seq: Seq): Promise<JournalEvent | undefined>;
+    protected doThreads(): Promise<ThreadIndexEntry[]>;
+    protected doSummaries(): Promise<ThreadSummary[]>;
+    protected doPutSummaries(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    protected doReplaceCatalog(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    private headSeq;
+}

package/dist/plugins/store/sql.d.ts

@@ -0,0 +1,59 @@
+import type { JournalEvent, Seq, ThreadSummary } from '../../models/index.js';
+import { JournalStore, type AppendOutcome, type Attempt, type ThreadIndexEntry, type WriterLease } from '../../journal/index.js';
+export type SqlValue = string | number | null;
+/** A synchronous SQLite connection: what the two stores differ in, except exclusivity. */
+export type SqlConnection = {
+    /** Statements without parameters or results; may hold several (the schema). */
+    exec(sql: string): void;
+    run(sql: string, ...params: SqlValue[]): void;
+    all<Row>(sql: string, ...params: SqlValue[]): Row[];
+    /** Runs `body` as one write transaction, rolled back when it throws; resolves once the commit is durable. */
+    transaction<T>(body: () => T): Promise<T>;
+    /** Releases this adapter's resources; never the host's storage. */
+    close(): void;
+};
+/** The exclusivity a store's platform grants, taken before anything is read: an OS lock, an in-process registry. */
+export type SqlExclusivity = {
+    readonly identity: string;
+    release(): void;
+};
+/**
+ * The journal store over a synchronous SQLite connection: the schema and its version stamp, the
+ * writer record, every append, summary and catalog check, and row parsing. A subclass supplies the
+ * connection and the exclusivity its platform grants; nothing else differs between stores.
+ */
+export declare abstract class SqlJournalStore extends JournalStore {
+    private db;
+    /** The acquisition this store holds, recorded in `writer` once the database is open. */
+    private acquisition;
+    private readonly location;
+    /** `location` names the journal in errors, such as `IncompatibleJournalError`. */
+    protected constructor(location: string);
+    /** Opens the connection `doOpen` uses; the store closes it in `doClose`. */
+    protected abstract connect(): SqlConnection;
+    /** Takes the platform's exclusivity for `acquireWriter`, or rejects with `JournalBusyError`. */
+    protected abstract exclusive(): Promise<SqlExclusivity>;
+    acquireWriter(): Promise<WriterLease>;
+    /**
+     * Inside a transaction: refuses unless `writer` is the acquisition this store holds and the writer
+     * record names it. The held acquisition alone fences a released lease whose record could not be
+     * cleared; the record alone fences another process that took the journal over.
+     */
+    private requireWriter;
+    /** Names this store's acquisition in the writer record, which every append checks. */
+    private recordWriter;
+    protected doOpen(): Promise<void>;
+    protected doClose(): Promise<void>;
+    private requireDb;
+    protected doHead(): Promise<Seq>;
+    private headOf;
+    protected doAppend(attempt: Attempt, digest: string): Promise<AppendOutcome>;
+    protected doRead(threadId: string): Promise<JournalEvent[]>;
+    protected doRowAt(seq: Seq): Promise<JournalEvent | undefined>;
+    protected doThreads(): Promise<ThreadIndexEntry[]>;
+    protected doSummaries(): Promise<ThreadSummary[]>;
+    protected doPutSummaries(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    protected doReplaceCatalog(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    private writeSummaries;
+    private rows;
+}

package/dist/plugins/store/sqlite.d.ts

@@ -0,0 +1,31 @@
+import { SqlJournalStore, type SqlConnection, type SqlExclusivity } from './sql.js';
+/** What `SqliteJournalStore` needs from the host, with no default for either. */
+export type SqliteJournalStoreOptions = {
+    /**
+     * The directory the writer-lock files live in, an absolute path. Every process that opens this
+     * journal must be given the same one, or two writers are not refused; one beside the journal is
+     * the natural choice.
+     */
+    readonly lockDirectory: string;
+    /**
+     * How long, in total, an append or a catalog write waits for another connection's write lock, a
+     * shell or a backup say, before it fails with `StoreBusyError`. `0` does not wait.
+     */
+    readonly busyTimeoutMs: number;
+};
+/**
+ * SQLite-backed journal at `<directory>/journal.db`: the rows in `events`, the thread index in
+ * `threads` and the attempt record in `attempts`, written in one transaction per group; the catalog
+ * in `summaries`, written after; the writer record in `writer`; the format stamp in `meta`. The
+ * writer lease is an operating system lock, so a process that dies releases it; the record holds the
+ * acquisition id every append checks. Construct one and pass it to `core` as `store`.
+ */
+export declare class SqliteJournalStore extends SqlJournalStore {
+    private readonly lockDirectory;
+    private readonly busyTimeoutMs;
+    readonly directory: string;
+    constructor(directory: string, options: SqliteJournalStoreOptions);
+    get databasePath(): string;
+    protected connect(): SqlConnection;
+    protected exclusive(): Promise<SqlExclusivity>;
+}

package/dist/plugins/store/sqlite.js

@@ -0,0 +1 @@
+import{a as m}from"../../chunks/AP6Q4EPT.js";import{l as u,m as h}from"../../chunks/37YOGDGY.js";import"../../chunks/KESCTXGO.js";import"../../chunks/TYTQRLTX.js";import"../../chunks/D7E6EWIE.js";import{closeSync as d,mkdirSync as c,openSync as w,realpathSync as f,statSync as p}from"node:fs";import{isAbsolute as M,join as n}from"node:path";import{DatabaseSync as y}from"node:sqlite";var b=class extends m{lockDirectory;busyTimeoutMs;directory;constructor(t,e){super(n(t,"journal.db")),this.directory=t;let{lockDirectory:r,busyTimeoutMs:s}=e;if(!M(r))throw new TypeError(`lockDirectory must be an absolute path: ${r}`);if(!Number.isFinite(s)||s<0)throw new TypeError(`busyTimeoutMs must be a finite number of milliseconds, zero or more: ${s}`);this.lockDirectory=r,this.busyTimeoutMs=s}get databasePath(){return n(this.directory,"journal.db")}connect(){return c(this.directory,{recursive:!0}),new a(this.databasePath,this.busyTimeoutMs)}async exclusive(){c(this.directory,{recursive:!0}),d(w(this.databasePath,"a",384));let t=f(this.databasePath),{dev:e,ino:r}=p(t,{bigint:!0});c(this.lockDirectory,{recursive:!0,mode:448});let s=new y(n(this.lockDirectory,`${e}-${r}.db`));try{s.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE")}catch(i){throw s.close(),l(i)?new u(t):i}return{identity:`sqlite:${e}:${r}`,release:()=>s.close()}}},a=class{db;path;busyTimeoutMs;statements=new Map;writes=Promise.resolve();constructor(t,e){this.path=t,this.busyTimeoutMs=e,this.db=new y(t);try{this.db.exec("PRAGMA journal_mode=WAL")}catch(r){throw this.db.close(),r}}exec(t){this.db.exec(t)}run(t,...e){this.statement(t).run(...e)}all(t,...e){return this.statement(t).all(...e)}transaction(t){let e=()=>this.write(t),r=this.writes.then(e,e);return this.writes=r.catch(()=>{}),r}close(){this.statements.clear(),this.db.close()}statement(t){let e=this.statements.get(t);return e===void 0&&(e=this.db.prepare(t),this.statements.set(t,e)),e}async write(t){await this.beginWrite();try{let e=t();return this.db.exec("COMMIT"),e}catch(e){throw this.rollback(),e}}async beginWrite(){let t=Date.now();for(let e=5;;e=Math.min(e*2,100))try{this.db.exec("BEGIN IMMEDIATE");return}catch(r){if(!l(r))throw r;let s=Date.now()-t;if(s>=this.busyTimeoutMs)throw new h(this.path,s);await new Promise(i=>setTimeout(i,Math.min(e,this.busyTimeoutMs-s)))}}rollback(){if(this.db.isTransaction)try{this.db.exec("ROLLBACK")}catch(t){console.error(t)}}},l=o=>{let t=o?.errcode;return typeof t=="number"&&(t&255)===5};export{b as SqliteJournalStore};

package/dist/plugins/subAgents/availableRoutes.d.ts

@@ -0,0 +1,53 @@
+import type { Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { LlmService } from '../../services/llm.js';
+declare const RouteCatalogSchema: z.ZodObject<{
+    providers: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        default_model: z.ZodString;
+        default_thinking_effort: z.ZodNullable<z.ZodEnum<{
+            low: "low";
+            high: "high";
+            none: "none";
+            medium: "medium";
+            max: "max";
+        }>>;
+        models: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            description: z.ZodNullable<z.ZodString>;
+            thinking_efforts: z.ZodNullable<z.ZodArray<z.ZodEnum<{
+                low: "low";
+                high: "high";
+                none: "none";
+                medium: "medium";
+                max: "max";
+            }>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The routes a sub-agent call can name, as its caller is told them. */
+export type RouteCatalog = z.output<typeof RouteCatalogSchema>;
+/**
+ * Every registered provider, in name order, each with its declared models and its default model
+ * first when the list does not name it. Registering a provider is what offers it, so nothing is
+ * filtered. Deterministic, so two catalogs compare equal exactly when a caller would be told the
+ * same thing.
+ */
+export declare function routeCatalog(llm: LlmService): RouteCatalog;
+/** The whole list, which replaces any list the model can still see (`replaces`). */
+export declare function renderAvailableRoutes(catalog: RouteCatalog, options: {
+    replaces: boolean;
+}): string;
+/**
+ * Tells the agents `isCaller` selects the routes a sub-agent call can name, at the next model step
+ * already due whenever the catalog differs from the latest notice the model can still see: on its
+ * first step, when a provider comes or goes, and after a replacement took the notice off the
+ * surface. The whole list is told again, never a diff, so the latest visible notice is the catalog.
+ *
+ * Installed by `subAgents` in the scope it grants in, selecting the agents those grants reach, so it
+ * reaches exactly the threads they do. It describes; nothing the tool accepts depends on it. A
+ * thread that two mounts both tell gets the notice once, since identical contributions to one step
+ * are recorded once (`ModelStep.contribute`).
+ */
+export declare function tellAvailableRoutes(ctx: Context, isCaller: (agentName: string) => boolean): void;
+export {};

package/dist/plugins/subAgents/fork.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import type { Tool } from '../../loop/index.js';
+import type { EndpointDescription } from './tool.js';
+/** Validates a fork endpoint's call, and is the source of the schema advertised to the model. */
+export declare const ForkParameters: z.ZodObject<{
+    task: z.ZodString;
+    background: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const formatForkResult: (output: string, isError: boolean) => string;
+/**
+ * What the forked thread is asked to do: the fork framing, naming the tool that forked it so it is
+ * told not to call that again, plus the task itself.
+ */
+export declare const forkTaskPrompt: (task: string, toolName: string) => string;
+/**
+ * A fork endpoint's tool: a child thread that continues this conversation, driven by
+ * `ctx.delegations` like any other delegation.
+ *
+ * The child is cut at the request that produced the call, so it sees exactly what the model saw
+ * when it asked — not the call, and not sibling results committed after it. Several calls on one
+ * reply run concurrently through the tool-call pool, and every sibling shares that request's cached
+ * prefix, the route and the mode included. Its task is queued in the same append that creates it,
+ * framed as a fork task, and its answer comes back as a `fork_result`, or with `background` a receipt
+ * comes back at once. The call takes no route: a fork runs on its source's route, so its siblings
+ * share the prefix.
+ *
+ * The child's id and its task's are derived from the call, so a call re-dispatched after a crash
+ * waits for the task it opened instead of duplicating it, and one whose task already settled
+ * returns its recorded output without running twice. Like every start tool, the result names the child's `thread_id`; `message_agent`
+ * continues it, with the message as plain input.
+ */
+export declare const forkTool: ({ toolName, description }: EndpointDescription) => Tool;

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

@@ -0,0 +1,67 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+/**
+ * One way callers delegate: a tool under `toolName`, granted to `callers` and described to them
+ * here, whose calls start children on the target. The endpoint is how callers see the target; the
+ * target is what a child runs on, so renaming or rewording the tool never redefines a child.
+ */
+declare const EndpointSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    callers: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+    description: z.ZodString;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"agent">;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        basePrompt: z.ZodString;
+        tools: z.ZodArray<z.ZodString>;
+        kind: z.ZodLiteral<"role">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"fork">;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type EndpointInput = z.input<typeof EndpointSchema>;
+declare const SubAgentsConfigSchema: z.ZodObject<{
+    endpoints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        toolName: z.ZodString;
+        callers: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+        description: z.ZodString;
+        target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"agent">;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            id: z.ZodString;
+            basePrompt: z.ZodString;
+            tools: z.ZodArray<z.ZodString>;
+            kind: z.ZodLiteral<"role">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"fork">;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type SubAgentsConfig = z.input<typeof SubAgentsConfigSchema>;
+/**
+ * Lets agents start sub-agents and forks, as tools: one endpoint per tool, whose target is a
+ * registered global agent, a role, or a fork of the caller. Mount it once per layer with that
+ * layer's endpoints: a second mount in one layer naming the same tool collides rather than
+ * merging. Mounts in different layers are independent, such as one on the root and the one the
+ * `codex` preset makes per thread for its explorer and its fork.
+ *
+ * The target kind decides what a call takes and what its child is. An agent target must be
+ * registered when this mounts, and must be global wherever this mounts: a child is a sibling of its
+ * caller's scope, so an agent registered in the caller's scope is invisible to the child, which
+ * could never run on it. A role target creates its child with the role recorded as the child's
+ * defining installation of the `role` preset, which `delegations` registers and which defines the
+ * child's agent in the child's own layer. Both take a task, a route and `background`. A fork target
+ * takes a task and `background` only; see {@link forkTool}.
+ *
+ * Every tool only starts: its result names the child's `thread_id`, which `message_agent` (the
+ * `delegations` plugin) continues. Every call delegates through `ctx.delegations`, so the
+ * `delegations` plugin must be mounted first, and this one refuses to mount without it. Every
+ * caller is also told the routes a call can name (see `tellAvailableRoutes`), in the same scope as
+ * its grants, so this configuration is the one list of who can start a sub-agent. Guidance about
+ * coordinating forks belongs to the consumer preset or host.
+ */
+export declare const subAgents: Plugin.Object<SubAgentsConfig | undefined>;
+export {};

package/dist/plugins/subAgents/index.js

@@ -0,0 +1 @@
+import{a}from"../../chunks/IJ2WNMD5.js";import"../../chunks/EGZI4XQX.js";import"../../chunks/UD3VJER6.js";import"../../chunks/SGGMBSBA.js";import"../../chunks/3QCW4WDJ.js";import"../../chunks/C5LYCXJG.js";import"../../chunks/J5S4URAW.js";import"../../chunks/G74AGRAJ.js";import"../../chunks/SL2YLB2F.js";import"../../chunks/JPZFKSWT.js";import"../../chunks/RK3VP2Q4.js";import"../../chunks/74HKUGRR.js";import"../../chunks/QMMLQJBS.js";import"../../chunks/YIR5MYGU.js";import"../../chunks/L3N4FIEN.js";import"../../chunks/NAOUTU7A.js";import"../../chunks/UKXMCHHT.js";import"../../chunks/GQGNVSKB.js";import"../../chunks/DXFXAYDN.js";import"../../chunks/DRYAN665.js";import"../../chunks/2OSESBIL.js";import"../../chunks/YLNJXQ3Z.js";import"../../chunks/DDANMY45.js";import"../../chunks/37YOGDGY.js";import"../../chunks/KESCTXGO.js";import"../../chunks/TYTQRLTX.js";import"../../chunks/D7E6EWIE.js";export{a as subAgents};

package/dist/plugins/subAgents/tool.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { Tool } from '../../loop/index.js';
+import { type DelegationTarget } from '../delegations/index.js';
+/** Parameters an agent accepts when another agent invokes it as a tool. */
+export declare const SubAgentRequestParameters: z.ZodPreprocess<z.ZodObject<{
+    task: 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>;
+/** How an endpoint describes its target to callers. */
+export type EndpointDescription = {
+    readonly toolName: string;
+    readonly description: string;
+};
+/**
+ * Delegation, as a tool.
+ *
+ * One of these is registered per target, a global agent or a role endpoint, so a target is
+ * advertised to the model exactly like any other tool and reaching it is an ordinary grant. The
+ * child is a normal thread: created with this call as its `origin` and its task in the same
+ * write, and driven by `ctx.delegations` until the task settles. The tool only starts: its result
+ * names the child's `thread_id`, whether the child answered or failed, and `message_agent` is how a
+ * later call continues it.
+ *
+ * The child is born on the caller's route with the fields the call names folded over it, and keeps
+ * that route, so a child started on a cheap model stays on it when continued without naming one.
+ */
+export declare const subAgentTool: ({ toolName, description }: EndpointDescription, target: Exclude<DelegationTarget, {
+    kind: "fork";
+}>) => Tool;

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

@@ -0,0 +1,61 @@
+import type { Plugin } from '@leuduan/cordis';
+import { type Modes } from '../../kit/modes.js';
+import { type AgentSelector } from '../../kit/scope.js';
+/** What one mode lets through: `allow` lists the tools it lets be called, every other one denied. */
+export type ModeRules = {
+    /** The only tools a call may name in this mode; without it, every tool. */
+    readonly allow?: readonly string[];
+    /** Why a call `allow` leaves out is denied, told to the model. */
+    readonly denial?: string;
+    /** `'all'` approves every call this mode lets through, satisfying a confirmation. */
+    readonly approve?: 'all';
+};
+/** What a mode notice is rendered against: what the model can still see, and what it was told last. */
+export type ModeTold<Mode extends string> = {
+    readonly seen: Mode | null;
+    readonly last: Mode | null;
+};
+/**
+ * What `toolPolicy` does with a set of durable modes: the rules each mode enforces and what the model
+ * is told on entering one. The state itself, and the host's way to set it, stay with the set.
+ */
+export type ModePolicy<Mode extends string = string> = {
+    /** Durable modes, from {@link defineModes}, whose rules apply in the mode a thread is in. */
+    readonly modes: Modes<Mode>;
+    /** What each of the set's modes lets through; a mode without rules is refused at mount. */
+    readonly rules: Readonly<Record<Mode, ModeRules>>;
+    /**
+     * What the model is told on entering `mode`, as a conversation message at the next model step; `null`
+     * to tell nothing. Asked only when the latest notice the model can still see says another mode.
+     */
+    notice(mode: Mode, told: ModeTold<Mode>): string | null;
+};
+export type ToolPolicyConfig = {
+    /** Whose calls these rules govern, and which threads a mode notice tells; every agent without it. */
+    readonly agents?: AgentSelector;
+    /** Tools held for the user; a predicate for a source whose tools come and go, as MCP's do. */
+    readonly confirm?: readonly string[] | ((tool: string) => boolean);
+    /** Tools approved without asking, satisfying a confirmation; `'all'` approves every call. */
+    readonly approve?: readonly string[] | 'all';
+    /** Tools refused outright. */
+    readonly deny?: readonly string[];
+} & (ModePolicy | {
+    readonly [Key in keyof ModePolicy]?: undefined;
+});
+/**
+ * What needs asking before a tool runs: the one policy plugin. Each rule votes on
+ * `lagent/tool/authorize` on its own, so the engine's table decides between them: a denial wins, an
+ * approval satisfies a confirmation and is recorded `confirmed_by: 'policy'`. Grants say who may
+ * call a tool at all; this says what a call that may be made needs.
+ *
+ * Mount it as many times as a host has rules. On the untagged application context it governs every
+ * thread, delegated ones included; in a thread's scope, that thread only.
+ *
+ * ```ts
+ * await root.plugin(toolPolicy, { confirm: ['run_command', 'edit_files'] })
+ * await root.plugin(toolPolicy, { approve: 'all' }) // auto-accept
+ * ```
+ */
+export declare const toolPolicy: Plugin.Object<ToolPolicyConfig>;
+/** The tools the shipped presets hold for confirmation: everything that writes or executes. */
+export declare const SAFE_WRITES_TOOLS: readonly ["run_command", "start_command", "edit_files"];

package/dist/plugins/toolPolicy/index.js

@@ -0,0 +1 @@
+import{a,b}from"../../chunks/BM3S37EZ.js";import"../../chunks/CDQG7RKA.js";import"../../chunks/DRYAN665.js";import"../../chunks/2OSESBIL.js";import"../../chunks/YLNJXQ3Z.js";import"../../chunks/DDANMY45.js";import"../../chunks/37YOGDGY.js";import"../../chunks/KESCTXGO.js";import"../../chunks/TYTQRLTX.js";import"../../chunks/D7E6EWIE.js";export{b as SAFE_WRITES_TOOLS,a as toolPolicy};

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

@@ -0,0 +1,128 @@
+import type { Stats } from 'node:fs';
+import { z } from 'zod';
+import type { InvocationContext } from '../../loop/index.js';
+import type { ToolResultPayload } from '../../models/index.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 placed inside the write roots
+ * and outside 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. 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;
+/**
+ * The filesystem calls `edit_files` makes, so a test can fail or delay one. Every other caller
+ * passes {@link nodeEditFs}.
+ */
+export type EditFs = {
+    readFile(path: string): Promise<Buffer>;
+    /** Creates `path`, which must not exist. */
+    writeFile(path: string, data: Buffer, options: {
+        mode?: number;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    link(existing: string, created: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    stat(path: string): Promise<Stats>;
+    lstat(path: string): Promise<Stats>;
+    mkdir(path: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+};
+export declare const nodeEditFs: EditFs;
+/** 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 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;
+};
+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, fs: EditFs): Promise<ToolResultPayload>;
+export {};

package/dist/plugins/tools/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/tools/html.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTML to readable plain text in one linear pass, with no DOM and no dependency.
+ *
+ * The text is the page's content region when it marks one — `<main>` or `role="main"`, else its
+ * only top-level `<article>` — and the whole document otherwise. What a reader would not read is
+ * dropped: scripts and styles, navigation, form controls, page banners, footers and sidebars outside
+ * the content, and hidden elements. Paragraphs, list items, table rows and preformatted text keep
+ * their shape.
+ *
+ * The parser is forgiving rather than spec-complete: a close tag pops back to its nearest open
+ * match, a few elements close an open sibling, and an element left open ends with its parent.
+ */
+export type HtmlLink = {
+    text: string;
+    href: string;
+};
+export type HtmlText = {
+    title: string | null;
+    text: string;
+    /** The links in `text`, in document order, with `href` as written. */
+    links: HtmlLink[];
+};
+export declare function htmlToText(html: string): HtmlText;

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

@@ -0,0 +1,59 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { Tool } from '../../loop/index.js';
+/**
+ * What the builtin tools are configured with, all of it the host's choice: the spawn environment and
+ * the trusted programs the search tools run (`rg`, with `rg: null` for none), what `web_fetch`
+ * may reach (`web.privateNetwork`: `refuse` keeps it on the public internet), and the Codex login
+ * `web_search` searches through (`web.search`; with `null` there is no `web_search`).
+ */
+declare const BuiltinToolsConfigSchema: z.ZodObject<{
+    environment: z.ZodRecord<z.ZodString, z.ZodString>;
+    programs: z.ZodObject<{
+        git: z.ZodString;
+        rg: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    web: z.ZodObject<{
+        privateNetwork: z.ZodEnum<{
+            allow: "allow";
+            refuse: "refuse";
+        }>;
+        search: z.ZodNullable<z.ZodObject<{
+            authPath: z.ZodString;
+            refreshTimeoutMs: z.ZodNumber;
+            model: z.ZodString;
+            maxOutputTokens: z.ZodNumber;
+            responseLength: z.ZodEnum<{
+                medium: "medium";
+                short: "short";
+                long: "long";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type BuiltinToolsConfig = z.input<typeof BuiltinToolsConfigSchema>;
+export type { WebSearchConfig } from './web.js';
+/** The builtin tools that read the workspace without changing it. */
+export declare const READ_ONLY_TOOLS: readonly ["read_file", "list_dir", "rg_search", "rg_files"];
+/** The builtin tools that run `rg`, provided only where the host has it (`programs.rg`). */
+export declare const RG_TOOLS: readonly string[];
+/** Builtin tools that fetch and search the web; `web_search` only where the host configures `web.search`. */
+export declare const WEB_TOOLS: readonly ["web_fetch", "web_search"];
+/**
+ * Every tool that ships with the engine. Registration is explicit: no import side effects.
+ *
+ * `ask_question` is deliberately absent — it needs a host that can reach the user, so it ships as
+ * the `lagent:ask` plugin instead of as a builtin that would fail wherever nobody is listening.
+ * Shell commands ship as the `commands` plugin, which owns their processes.
+ *
+ * The search tools, `rg_search` and `rg_files`, run the trusted `rg` and take configuration: the
+ * {@link BuiltinToolsConfig}. Without `rg` (`programs.rg: null`) neither is provided; nothing searches
+ * by another means. Likewise `web_search` searches only through the Codex login `web.search` names.
+ */
+export declare const builtinToolsFor: (config: z.output<typeof BuiltinToolsConfigSchema>) => readonly Tool[];
+/**
+ * Registers every builtin tool for the life of the plugin. The host names the environment and the
+ * trusted programs the search tools run with, what `web_fetch` may reach and what `web_search`
+ * searches through; there is no default for any of them.
+ */
+export declare const builtinTools: Plugin.Object<BuiltinToolsConfig>;