@leuduan/lagent 0.0.0-stage → 44.0.0

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/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/MHC6VPB4.js";import"../../chunks/CANPZYTH.js";import"../../chunks/VYMT4TXD.js";import"../../chunks/MNJ4SRF7.js";import"../../chunks/JFZZXVWD.js";import"../../chunks/N6IXG2VL.js";import"../../chunks/6DRCKZ2C.js";import"../../chunks/7LI64H5X.js";import"../../chunks/3UMZMPWW.js";import"../../chunks/34KW6VNQ.js";import"../../chunks/KUZCL2SH.js";import"../../chunks/CQEVREBT.js";import"../../chunks/HK6ZSONF.js";import"../../chunks/7VAPNE3L.js";import"../../chunks/EPYQ5M3B.js";import"../../chunks/5IRF47YB.js";import"../../chunks/OL5A6ITQ.js";import"../../chunks/JFX2MXBA.js";import"../../chunks/S34ZA2R6.js";import"../../chunks/6FRNHMCV.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 subAgents};

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

@@ -0,0 +1,67 @@
+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;
+/** 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/threadDirs.d.ts

@@ -0,0 +1,36 @@
+import { Service, type Context, type Plugin } from '@leuduan/cordis';
+declare module '@leuduan/cordis' {
+    interface Context {
+        /** Each thread's own directory under the application data directory (optional plugin). */
+        threadDirs: ThreadDirsService;
+    }
+}
+export type ThreadDirsConfig = {
+    /** Absolute application data directory; thread directories live under `<dataDir>/threads`. Required. */
+    dataDir: string;
+};
+/**
+ * Where each thread keeps files of its own: `<dataDir>/threads/<thread-id>/`, a scratch space.
+ * Harness-written files go in named subdirectories such as `tool-outputs/` and `commands/`. Mount
+ * it on the root with `root.plugin(threadDirs, { dataDir })`; a plugin that keeps files here
+ * injects `threadDirs`, so it waits, unmounted, until a host that has a file system mounts this.
+ *
+ * The path is derived from the data directory and thread id, but absolute paths are also recorded
+ * in prompts and tool results. Keep the data directory at the same location when reopening a
+ * durable journal. Plugins can use the id supplied by their activation hook to find the directory.
+ *
+ * Nothing here limits who may read or write the directories: what the model's tools and commands
+ * may reach is the confinement policy's. A host whose data directory holds what commands must not
+ * change, such as its journal, lists it in the sandbox's `filesystem.denyWrite`.
+ */
+declare class ThreadDirsService extends Service<ThreadDirsConfig> {
+    readonly dataDir: string;
+    readonly root: string;
+    constructor(ctx: Context, config: ThreadDirsConfig);
+    /** The directory of `threadId`, without touching the filesystem. */
+    dirFor(threadId: string): string;
+    /** The directory of `threadId`, created if missing. */
+    ensure(threadId: string): string;
+}
+export declare const threadDirs: Plugin.Constructor<ThreadDirsConfig>;
+export type { ThreadDirsService };

package/dist/plugins/threadDirs.js

@@ -0,0 +1 @@
+import{a}from"../chunks/W57RW55W.js";import"../chunks/VYMT4TXD.js";export{a as threadDirs};

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

@@ -0,0 +1,61 @@
+import type { Plugin } from '@leuduan/cordis';
+import { type Modes } from '../../services/modes.js';
+import { type AgentSelector } from '../../services/agents.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/ASSQZH3F.js";import"../../chunks/DDZ7YF26.js";import"../../chunks/6FRNHMCV.js";import"../../chunks/CUK7CGC7.js";import"../../chunks/BPRCULZH.js";import"../../chunks/DDANMY45.js";import"../../chunks/BBCW2FZK.js";import"../../chunks/MMNNZCBO.js";import"../../chunks/G44LG6VL.js";import"../../chunks/D4PQP5MA.js";export{b as SAFE_WRITES_TOOLS,a as toolPolicy};

package/dist/plugins/truncateToolOutput.d.ts

@@ -0,0 +1,30 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { ToolResult } from '../records/toolResult.js';
+/** Where full outputs go inside a thread's directory. */
+export declare const TOOL_OUTPUTS_DIR = "tool-outputs";
+/** The least limit that holds the longest gap marker and a character each of head and tail. */
+export declare const MIN_TOOL_OUTPUT_LENGTH: number;
+export declare const TruncateToolOutputConfigSchema: z.ZodObject<{
+    maxToolOutputLength: z.ZodDefault<z.ZodNumber>;
+    spill: z.ZodBoolean;
+}, z.core.$strip>;
+export type TruncateToolOutputConfig = z.input<typeof TruncateToolOutputConfigSchema>;
+/**
+ * Caps tool output at a character limit, keeping its head and its tail around a marker that says how
+ * much of the middle was cut. With `spill: true` it also writes the full text to the thread's own
+ * directory (`<thread dir>/tool-outputs/`), where file tools can read it back when available, and
+ * names the path; it then injects `threadDirs` and stays pending until `threadDirs` is
+ * mounted. With `spill: false` the cut text is gone and no directory is needed, as on a host with
+ * no file system. Characters are UTF-16 code units, as `string.length` counts them, and no cut
+ * splits a surrogate pair. A tool may opt out by setting `no_truncation: true` in its result
+ * metadata. Because this wraps `lagent/tool/execute`, the journal records exactly what the model
+ * saw. A call that waits has no output to cap.
+ */
+export declare const truncateToolOutput: Plugin.Object<TruncateToolOutputConfig>;
+/**
+ * Truncates `result` to `limit` characters, head and tail with the gap marker between them, writing the
+ * full output into `directory` when it was cut, unless that is `null`. `limit` is at least
+ * {@link MIN_TOOL_OUTPUT_LENGTH}.
+ */
+export declare function applyTruncation(result: ToolResult, limit: number, directory: string | null): Promise<ToolResult>;

package/dist/plugins/truncateToolOutput.js

@@ -0,0 +1,6 @@
+import{W as d}from"../chunks/BPRCULZH.js";import"../chunks/DDANMY45.js";import"../chunks/BBCW2FZK.js";import{c}from"../chunks/MMNNZCBO.js";import"../chunks/G44LG6VL.js";import"../chunks/D4PQP5MA.js";import{randomBytes as T}from"node:crypto";import{mkdir as O,writeFile as $}from"node:fs/promises";import{join as _}from"node:path";import{z as s}from"zod";var x=/[^A-Za-z0-9_.-]+/g,w="tool-outputs",A=String(Number.MAX_SAFE_INTEGER).length,h=t=>`
+[\u2026 ${t} characters omitted \u2026]
+`,m=h("9".repeat(A)).length+2,E=s.object({maxToolOutputLength:s.number().int().min(m,{message:`maxToolOutputLength must hold the gap marker and some head and tail: at least ${m}`}).default(1e4),spill:s.boolean()}),b={name:"lagent:truncate-tool-output",apply(t,a){let{maxToolOutputLength:o,spill:n}=E.parse(a);if(!n){p(t,o,()=>null);return}t.inject(["threadDirs"],e=>p(e,o,l=>_(e.threadDirs.dirFor(l),w)))}};function p(t,a,o){t.on("lagent/tool/execute",async(n,e)=>{let l=await e();return d(l)?l:await M(l,a,o(n.threadId))})}async function M(t,a,o){let n=await S(t,a,o),e=[...t.notes??[]];return n.note!==null&&e.push(n.note),{...t,output:n.output,notes:e.length>0?e:null,metadata:{...t.metadata,truncation:n.metadata}}}async function S(t,a,o){let n=t.output;if(t.metadata.no_truncation===!0)return{output:n,note:null,metadata:{was_truncated:!1,limit:a,original_length:n.length,returned_length:n.length,no_truncation:!0}};if(n.length<=a)return{output:n,note:null,metadata:{was_truncated:!1,limit:a,original_length:n.length,returned_length:n.length}};let e=o===null?null:await F(n,t,o),l=n.split(`
+`).length,{head:u,tail:r}=I(n,a),i=n.length-u.length-r.length,g=`${u}${h(String(i))}${r}`;return{output:g,note:`Output truncated to its first ${u.length} and last ${r.length} of ${n.length} characters (${l} lines).`+(e===null?"":` The full output is written to ${e}.`),metadata:{was_truncated:!0,limit:a,original_length:n.length,returned_length:g.length,omitted_length:i,...e===null?{}:{full_output_path:e}}}}function I(t,a){let o=a-h(String(t.length)).length,n=Math.ceil(o/2),e=o-n,l=n,u=t.lastIndexOf(`
+`,l-1);u>=Math.floor(n/2)?l=u+1:l=c(t,l,"end");let r=t.length-e,i=t.indexOf(`
+`,r);return i!==-1&&i+1<=r+Math.floor(e/2)?r=i+1:r=c(t,r,"start"),{head:t.slice(0,l),tail:t.slice(r)}}async function F(t,a,o){let n=`${f(a.name||"tool")}-${f(a.call_id||"call")}-`,e=_(o,`${n}${T(6).toString("hex")}.txt`);return await O(o,{recursive:!0,mode:448}),await $(e,t,{encoding:"utf8",flag:"wx",mode:384}),e}var f=t=>t.replace(x,"-").slice(0,L).replace(/^[.-]+|[.-]+$/g,"")||"value",L=40;export{m as MIN_TOOL_OUTPUT_LENGTH,w as TOOL_OUTPUTS_DIR,E as TruncateToolOutputConfigSchema,M as applyTruncation,b as truncateToolOutput};

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

@@ -0,0 +1,26 @@
+import { Context, Service, type Plugin } from '@leuduan/cordis';
+import { UsageSnapshot } from './tracker.js';
+export { UsageSnapshot } from './tracker.js';
+export type { UsageSnapshotInit } from './tracker.js';
+declare module '@leuduan/cordis' {
+    interface Context {
+        /** Model usage totals per thread (optional plugin). */
+        usage: UsageService;
+    }
+}
+/**
+ * Model usage as a fold over each thread's journal. The engine itself counts nothing — without
+ * this service mounted, nobody is keeping score. There is no journal-wide total: a thread's spend
+ * is a function of its own rows, and a sum over several threads is the host's, over the threads it
+ * shows, as a caller-chain rollup is, by joining threads on `origin`.
+ */
+declare class UsageService extends Service {
+    static inject: string[];
+    constructor(ctx: Context);
+    /** Everything one thread has spent so far. */
+    thread(threadId: string): UsageSnapshot;
+    /** What one thread's most recent completed turn spent. */
+    lastTurn(threadId: string): UsageSnapshot;
+}
+export declare const usage: Plugin.Constructor<undefined>;
+export type { UsageService };

package/dist/plugins/usage/index.js

@@ -0,0 +1 @@
+import{h as _}from"../../chunks/BBCW2FZK.js";import"../../chunks/MMNNZCBO.js";import"../../chunks/G44LG6VL.js";import"../../chunks/D4PQP5MA.js";import{Service as a}from"@leuduan/cordis";var n=class e{request_count;input_tokens;output_tokens;cache_read_input_tokens;cache_write_input_tokens;reasoning_output_tokens;constructor(t={}){this.request_count=t.request_count??0,this.input_tokens=t.input_tokens??0,this.output_tokens=t.output_tokens??0,this.cache_read_input_tokens=t.cache_read_input_tokens??0,this.cache_write_input_tokens=t.cache_write_input_tokens??0,this.reasoning_output_tokens=t.reasoning_output_tokens??0,Object.freeze(this)}get totalTokens(){return this.input_tokens+this.output_tokens}get cacheMissInputTokens(){return this.input_tokens-this.cache_read_input_tokens}delta(t){return new e({request_count:this.request_count-t.request_count,input_tokens:this.input_tokens-t.input_tokens,output_tokens:this.output_tokens-t.output_tokens,cache_read_input_tokens:this.cache_read_input_tokens-t.cache_read_input_tokens,cache_write_input_tokens:this.cache_write_input_tokens-t.cache_write_input_tokens,reasoning_output_tokens:this.reasoning_output_tokens-t.reasoning_output_tokens})}plus(t){return new e({request_count:this.request_count+t.request_count,input_tokens:this.input_tokens+t.input_tokens,output_tokens:this.output_tokens+t.output_tokens,cache_read_input_tokens:this.cache_read_input_tokens+t.cache_read_input_tokens,cache_write_input_tokens:this.cache_write_input_tokens+t.cache_write_input_tokens,reasoning_output_tokens:this.reasoning_output_tokens+t.reasoning_output_tokens})}toJSON(){return{request_count:this.request_count,input_tokens:this.input_tokens,output_tokens:this.output_tokens,cache_read_input_tokens:this.cache_read_input_tokens,cache_write_input_tokens:this.cache_write_input_tokens,reasoning_output_tokens:this.reasoning_output_tokens}}},s=()=>({request_count:0,input_tokens:0,output_tokens:0,cache_read_input_tokens:0,cache_write_input_tokens:0,reasoning_output_tokens:0}),r=(e,t)=>{t&&(e.input_tokens+=t.input_tokens,e.output_tokens+=t.output_tokens,e.cache_read_input_tokens+=t.cache_read_input_tokens,e.cache_write_input_tokens+=t.cache_write_input_tokens,e.reasoning_output_tokens+=t.reasoning_output_tokens)};function i(e,t){switch(t.type){case"llm/request":case"auxiliary/request":e.request_count+=1;return;case"assistant/message":r(e,t.data.response.message.usage);return;case"auxiliary/result":r(e,t.data.usage);return;default:return}}var c=()=>({totals:s(),baseline:s(),lastTurn:s()}),o=_({key:"lagent:usage:thread",onFork:"reset",init:c,apply(e,t){return i(e.totals,t),t.type==="turn/start"?e.baseline={...e.totals}:t.type==="turn/end"&&(e.lastTurn=new n(e.totals).delta(new n(e.baseline)).toJSON()),e}}),u=class extends a{static inject=["journal"];constructor(t){super(t,"usage"),t.effect(()=>t.journal.register(o))}thread(t){return new n(this.ctx.journal.state(o,t).totals)}lastTurn(t){return new n(this.ctx.journal.state(o,t).lastTurn)}},g=u;export{n as UsageSnapshot,g as usage};

package/dist/plugins/usage/tracker.d.ts

@@ -0,0 +1,34 @@
+import type { JournalEvent } from '../../records/journal.js';
+export type UsageSnapshotInit = Partial<{
+    request_count: number;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens: number;
+    cache_write_input_tokens: number;
+    reasoning_output_tokens: number;
+}>;
+export declare class UsageSnapshot {
+    readonly request_count: number;
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly cache_read_input_tokens: number;
+    readonly cache_write_input_tokens: number;
+    readonly reasoning_output_tokens: number;
+    constructor(init?: UsageSnapshotInit);
+    get totalTokens(): number;
+    get cacheMissInputTokens(): number;
+    delta(previous: UsageSnapshot): UsageSnapshot;
+    /** This and `other` together: how a host sums the threads it shows, since nothing rolls up for it. */
+    plus(other: UsageSnapshot): UsageSnapshot;
+    toJSON(): Required<UsageSnapshotInit>;
+}
+/** A thread's usage counters as plain data: what the usage fold keeps, and what a snapshot is built from. */
+export type UsageCounters = Required<UsageSnapshotInit>;
+export declare const emptyCounters: () => UsageCounters;
+/**
+ * Counts model requests and aggregates token usage from `llm/request` and `assistant/message`, and
+ * from the auxiliary calls plugins make beside the conversation, `auxiliary/request` and
+ * `auxiliary/result`: a summary that was discarded was still paid for, so every result counts,
+ * whatever became of its text. Mutates `counters`; a fold reducer's state is its own to change.
+ */
+export declare function countEvent(counters: UsageCounters, event: JournalEvent): void;

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

@@ -0,0 +1,27 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+export declare const VerifyConfigSchema: z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodString;
+}, z.core.$strict>;
+export type VerifyConfig = z.input<typeof VerifyConfigSchema>;
+/**
+ * A thread's configured automatic completion check. Runtime execution is the only proof;
+ * ordinary model commands remain diagnostics. Requirements and gates share the verify service,
+ * which plans execution at the pure stop boundary and core dispatches before final judgment.
+ * Relevant command and delegated work must settle first. Commands obey current grants,
+ * confirmation and sandbox policy, and must establish their intended postcondition on success.
+ */
+export declare const verifyPreset: import("../../services/presets/definition.js").Preset<z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodString;
+}, z.core.$strict>>;
+/**
+ * The `ctx.verify` service ({@link VerifyService}), the one judge of verification on every thread:
+ * the gates {@link verifyPreset} mounts, and the requirements an owner records for an assignment
+ * with `owed(...)`, whose threads require {@link VERIFY_OWNER}. Root-only, mounted once by the
+ * application, before anything mounts the preset.
+ */
+export declare const verify: Plugin.Object<undefined>;
+export { VERIFY_PRESET, VERIFY_REPAIRS } from './record.js';
+export { VERIFY_OWNER, type OwedVerification, type VerifyService } from './service.js';

package/dist/plugins/verify/index.js

@@ -0,0 +1,6 @@
+import{t as K,w as W,x as U}from"../../chunks/CANPZYTH.js";import"../../chunks/VYMT4TXD.js";import"../../chunks/MNJ4SRF7.js";import{a as C,d as J}from"../../chunks/JFZZXVWD.js";import"../../chunks/N6IXG2VL.js";import"../../chunks/6DRCKZ2C.js";import"../../chunks/7LI64H5X.js";import"../../chunks/3UMZMPWW.js";import"../../chunks/34KW6VNQ.js";import"../../chunks/KUZCL2SH.js";import"../../chunks/CQEVREBT.js";import"../../chunks/HK6ZSONF.js";import{a as N}from"../../chunks/7VAPNE3L.js";import"../../chunks/EPYQ5M3B.js";import"../../chunks/5IRF47YB.js";import{a as M}from"../../chunks/OL5A6ITQ.js";import"../../chunks/JFX2MXBA.js";import{c as P,d as T}from"../../chunks/S34ZA2R6.js";import{b as g,e as Y}from"../../chunks/6FRNHMCV.js";import"../../chunks/CUK7CGC7.js";import{s as v}from"../../chunks/BPRCULZH.js";import"../../chunks/FJLU4UH3.js";import"../../chunks/DDANMY45.js";import{h as F}from"../../chunks/BBCW2FZK.js";import{a as V}from"../../chunks/MMNNZCBO.js";import"../../chunks/G44LG6VL.js";import"../../chunks/D4PQP5MA.js";import{isAbsolute as pe,resolve as ge}from"node:path";import{z as O}from"zod";import{isAbsolute as ae,resolve as oe}from"node:path";import{z as u}from"zod";var w="verify",k=2,j=u.strictObject({command:u.string(),cwd:u.string()}),B=g({plugin:"lagent:verify",kind:"notice",version:2,schema:j}),$=g({plugin:"lagent:verify",kind:"repair",version:1,schema:j}),D=g({plugin:"lagent:verify",kind:"rejected",version:2,schema:u.strictObject({...j.shape,cause:u.enum(["denied","unverified","execution"])})}),se=u.strictObject({owner:u.string().min(1),assignment:u.string().min(1),generation:u.number().int().nonnegative(),input:u.string().min(1),command:u.string().trim().min(1),cwd:u.string().refine(ae,"An absolute path")}),q=g({plugin:"lagent:verify",kind:"requirement",version:1,schema:se});function I(n){let e=q.parse(n);return{...e,cwd:oe(e.cwd)}}import{resolve as S}from"node:path";import{Service as ue}from"@leuduan/cordis";import{z as me}from"zod";import{resolve as ce}from"node:path";import{z as G}from"zod";var m=(n,e)=>JSON.stringify([n,e]),f=(n,e)=>n===null?e:e===null?n:Math.max(n,e),y=F({key:"lagent:verify:facts",init:()=>({calls:new Map,changedAt:null,personAt:null,repairs:new Map,attempts:new Map}),apply(n,e){switch(e.type){case"assistant/message":for(let t of e.data.response.message.tool_calls)t.arguments!==null&&(t.name==="edit_files"||t.name==="run_command")&&n.calls.set(t.call_id,null);break;case"tool/authorization":n.calls.has(e.data.call_id)&&e.data.decision==="allow"&&(n.calls.set(e.data.call_id,e.seq),n.changedAt=e.seq);break;case"tool/result":{n.calls.get(e.data.result.call_id)!=null&&(n.changedAt=e.seq),n.calls.delete(e.data.result.call_id);break}case"execution/requested":{let{owner:t,operation:r,candidate_seq:i,key:a}=e.data;if(t!=="lagent:verify"&&(r.name==="run_command"||r.name==="edit_files")&&n.calls.set(`runtime_${e.seq}`,null),t!=="lagent:verify"||r.name!=="run_command")break;let{command:o,workdir:c}=r.arguments;if(typeof o!="string"||typeof c!="string")break;n.attempts.set(e.seq,{seq:e.seq,candidate:i,key:a,verification:{command:o,cwd:ce(c)},authorizedAt:null,resultAt:null,result:null});break}case"execution/authorization":{let t=`runtime_${e.data.request_seq}`;n.calls.has(t)&&e.data.decision==="allow"&&(n.calls.set(t,e.seq),n.changedAt=e.seq);let r=n.attempts.get(e.data.request_seq);r!==void 0&&e.data.decision==="allow"&&(r.authorizedAt=e.seq);break}case"execution/result":{let t=`runtime_${e.data.request_seq}`;n.calls.get(t)!=null&&(n.changedAt=e.seq),n.calls.delete(t);let r=n.attempts.get(e.data.request_seq);r!==void 0&&(r.resultAt=e.seq,r.result=e.data.result);break}case"ext":C.read(e)!==void 0&&(n.changedAt=e.seq);break;case"input/message":if(e.data.source===null)n.personAt=e.seq,n.repairs.clear();else{let t=$.readContribution(e);if(t!==void 0){let r=m(t.command,t.cwd);n.repairs.set(r,[...n.repairs.get(r)??[],e.seq])}}break}return n}});function de(n){let e=n.changedAt;for(let t of n.attempts.values())t.authorizedAt!==null&&(e=f(e,f(t.authorizedAt,t.resultAt)));return e}var A=N({key:"verify",version:2,schema:G.strictObject({changed_at:G.number().int().positive().nullable()}),applies:()=>!0,compute:(n,e)=>({changed_at:de(n.state(y,e))})});function R(n,e){let t=new Set([e]);for(let r of n.origins.subtree(e,{self:!0})){let{origin:i,thread_id:a}=r;i===null||i.cause.kind==="assignment"||!t.has(i.caller_thread_id)||t.add(a)}return t}function H(n,e){let t=null;for(let r of R(n,e)){if(r===e)continue;let i=A.read(n,r);if(i.status!=="available")return{unreadable:`agent ${r}: ${i.status==="unavailable"?i.reason:"its changes are not recorded"}`};t=f(t,i.value.changed_at)}return{at:t}}var L=n=>JSON.stringify([n.owner,n.assignment,n.generation]),Q=q.projection({key:"requirements",init:()=>new Map,onFork:"reset",apply(n,e,t){let r=L(e);return n.has(r)||n.set(r,{value:e,seq:t.seq}),n}});function X(n,e,t,r){let i=t?void 0:n.state(Q,e).get(L(r));return i===void 0?[q.entry(r,{threadId:e})]:JSON.stringify(i.value)===JSON.stringify(r)?[]:{refuse:{message:`Verification for assignment ${r.assignment} is already owed on ${e}, differently`}}}function E(n,e){let t=n.state(Q,e);if(t.size===0)return null;let{inputs:r}=n.state(v,e),i=K(n,e),a=null;for(let{value:o,seq:c}of t.values()){let d=r.get(o.input)?.claimedAt??null;if(d===null)continue;let l=Math.max(c,d);i!==null&&i>l||(a===null||a.at<l)&&(a={verification:{command:o.command,cwd:o.cwd},at:l})}return a}import{resolve as Z}from"node:path";var le=(n,e)=>JSON.stringify([n.command,n.cwd,e]);function ee(n,e){let{metadata:t}=n;return!n.is_error&&t.exit_code===0&&t.timed_out===!1&&t.aborted===!1&&t.stop_failed===!1&&typeof t.cwd=="string"&&Z(t.cwd)===e}function x(n,e,t,r){let i=m(e.command,e.cwd),a=f(n.changedAt,r),o=null;for(let d of n.attempts.values())d.authorizedAt!==null&&(m(d.verification.command,d.verification.cwd)===i&&d.result!==null&&ee(d.result,e.cwd)?o=f(o,d.authorizedAt):a=f(a,f(d.authorizedAt,d.resultAt)));let c=f(a,t);return{mutatedAt:a,provenAt:o,fresh:c===null||o!==null&&o>c,repairs:(n.repairs.get(i)??[]).filter(d=>t===null||d>t).length}}function te(n,e,t,r,i){let a=`\`${e.command}\` (in ${e.cwd})`,o=(h,ie="unverified")=>D.rejection(h,{...e,cause:ie});if("unreadable"in r)return o(`Delegated changes cannot be read (${r.unreadable}), so ${a} cannot be verified.`);let c=x(n,e,t,r.at);if(c.fresh)return;let d=le(e,t),l=[...n.attempts.values()].find(h=>h.candidate===i&&h.key===d);if(l===void 0||l.result===null&&l.authorizedAt===null)return{decision:"prepare",request:{owner:"lagent:verify",key:d,operation:{name:"run_command",arguments:{command:e.command,workdir:e.cwd}}}};let s=l.result;if(s===null)return o(`Runtime verification ${a} may have started but its result is unknown. Reconcile its command and cleanup before an explicit retry.`,"execution");if(s.metadata.not_dispatched===!0)return o(`Runtime verification ${a} was not dispatched; no process was started. It was not replayed automatically. Submit a new candidate to verify again.
+${s.output}`,"execution");if(s.metadata.runtime_denied===!0)return o(`Runtime verification ${a} was denied: ${s.output}`,"denied");if(typeof s.metadata.cwd=="string"&&Z(s.metadata.cwd)!==e.cwd)return o(`Runtime verification ran in ${s.metadata.cwd}, rather than the pinned directory ${e.cwd}.`,"execution");if(s.metadata.aborted===!0&&s.metadata.stop_failed===!1){let h=s.metadata.not_started===!0?"was cancelled before execution; no process was started.":"was interrupted; process cleanup completed, but file changes were not rolled back.";return o(`Runtime verification ${a} ${h} It was not replayed automatically. Submit a new candidate to verify again.
+${s.output}`,"execution")}if(s.metadata.stop_failed!==!1||s.metadata.aborted===!0||typeof s.metadata.exit_code!="number"&&s.metadata.timed_out!==!0)return o(`Runtime verification ${a} has no usable completed result or cleanup evidence: ${s.output}`,"execution");let p=ee(s,e.cwd),re=p?`Its proof became stale after recorded activity at row ${c.mutatedAt??t}.`:`It failed (exit ${s.metadata.exit_code}${s.metadata.timed_out===!0?", timed out":""}).`,z=`Runtime verification ${a}: ${re}
+${s.output}`;return c.repairs>=k?o(`${z}
+The ${k} repair continuations are spent; this candidate is rejected.`):{decision:"continue",message:$.contribution({content:`${z}
+${p?"Wait for the invalidating work to settle, inspect any changes, and submit again; the command itself succeeded.":"Fix the reported problem and submit again."} Verification runs automatically; ordinary command calls do not satisfy it.`},e)}}function fe(n){if(n.kind==="send")return null;if(n.kind==="create"){let{origin:i,spec:a}=n.opening;return{origin:i,requires:a.requires,installations:a.installations}}let{origin:e,requires:t,inherits:r}=n.opening;return{origin:e,requires:t,installations:r.installations}}var b="lagent:verify",ne=g({plugin:b,kind:"eligibility",version:1,schema:me.strictObject({})}),_=class extends ue{static inject=["threads","journal","commands"];gates=new Map;constructor(e){super(e,"verify"),e.effect(()=>e.threads.registerOwner({owner:b}).dispose),e.effect(()=>e.journal.register(y)),A.register(e),e.on("lagent/turn/stop",t=>this.judge(t))}gate(e,t){let r=m(t.command,S(t.cwd)),i=E(this.ctx.journal,e);if(i!==null&&m(i.verification.command,i.verification.cwd)!==r)throw new Error(`Thread ${e} owes a different pinned assignment verification`);if([...this.gates.get(e)?.values()??[]].some(c=>m(c.command,c.cwd)!==r))throw new Error(`Thread ${e} already has a different verification gate`);let a=Symbol("verify gate"),o=this.gates.get(e);return o===void 0&&this.gates.set(e,o=new Map),o.set(a,{command:t.command,cwd:S(t.cwd)}),()=>{o.delete(a),o.size===0&&this.gates.get(e)===o&&this.gates.delete(e)}}owed(e){let{inputId:t,...r}=e,i=I({...r,input:t}),a=m(i.command,i.cwd);return o=>{let{threadId:c}=o,d=fe(o);if(!this.required(c,d))return{refuse:{message:`Thread ${c} owes verification, so it must require ${b}`}};let l=this.inPlace(c,d).find(s=>m(s.command,s.cwd)!==a);return l!==void 0?{refuse:{message:`Thread ${c} verifies with \`${l.command}\` (in ${l.cwd}), not the \`${i.command}\` (in ${i.cwd}) this assignment pins`}}:X(this.ctx.journal,c,d!==null,i)}}judge({threadId:e,observe:t,answer:r}){t(()=>this.observed(e,r.seq));let{judged:i,delegated:a}=this.reading(e);if(i.size===0)return;let o=this.ctx.journal.state(y,e),c=[...i.values()].map(({verification:s,armedAt:p})=>te(o,s,p,a,r.seq)),d=c.find(s=>s?.decision==="reject");if(d!==void 0)return d;if([...i.values()].some(({verification:s,armedAt:p})=>"unreadable"in a?!0:p!==null||x(o,s,p,a.at).mutatedAt!==null)){let s=this.work(e);if(s.unresolved.length>0)return ne.rejection(`Verification cannot proceed while work is unresolved: ${s.unresolved.join("; ")}`,{});if(s.draining.length>0)return{decision:"continue",message:ne.contribution({content:`Before automatic verification, wait for relevant commands and agents to settle, or stop them: ${s.draining.join("; ")}`},{})}}return c.find(s=>s!==void 0)}observed(e,t){let{judged:r,delegated:i}=this.reading(e),a=this.ctx.journal.state(y,e);return JSON.stringify([[...r].map(([o,{verification:c,armedAt:d}])=>[o,d,"unreadable"in i?null:x(a,c,d,i.at)]),i,r.size===0?null:this.work(e),[...a.attempts.values()].filter(o=>o.candidate===t&&o.resultAt!==null).map(o=>[o.key,o.resultAt])])}work(e){let t=R(this.ctx.journal,e),r=[],i=[];for(let a of t){let o=J(this.ctx,a,{descendants:!1});r.push(...o.draining),i.push(...o.unresolved);for(let c of W(this.ctx.journal,a))r.push(`thread ${a}: ${c.targets.length} agent stops are pending`)}for(let a of U(this.ctx.journal,e))t.has(a.childId)&&(a.state==="unavailable"?i.push(`agent ${a.childId}: ${a.error}`):(a.state==="open"||a.draining||a.cleanupPending)&&r.push(`agent ${a.childId} has not settled`));return{draining:r,unresolved:i}}reading(e){let t=new Map,r=E(this.ctx.journal,e);for(let i of this.gates.get(e)?.values()??[])t.set(m(i.command,i.cwd),{verification:i,armedAt:null});return r!==null&&t.set(m(r.verification.command,r.verification.cwd),{verification:r.verification,armedAt:r.at}),{judged:t,delegated:t.size===0?{at:null}:H(this.ctx.journal,e)}}inPlace(e,t){return[...(t===null?[...this.ctx.journal.state(v,e).installations.current.values()].map(({presetId:a,config:o})=>({presetId:a,config:o})):t.installations.map(({preset_id:a,config:o})=>({presetId:a,config:o}))).flatMap(({presetId:a,config:o})=>{if(a!==w)return[];let{command:c,cwd:d}=o;return[{command:c,cwd:S(d)}]}),...this.gates.get(e)?.values()??[]]}required(e,t){let{owners:r}=this.ctx.journal.origins.requiredOwners(t??e);return r.some(({owner:i})=>i===b)}};var he=O.strictObject({command:O.string().trim().min(1),cwd:O.string().refine(pe,"An absolute path: resolve it against the thread's cwd before installing")}),et=M({id:w,placement:"thread",schema:he,inject:["journal","verify"],setup(n,e,t){let r=P(n,"verify","verifyPreset"),i={command:e.command,cwd:ge(e.cwd)},a=`\`${i.command}\` (in ${i.cwd})`;Y(n,{event:B,rank:1,current:()=>i,render:()=>V("verification",`Verification runs automatically with ${a} when you submit or finish after changes. Test as useful while working, settle your commands and agents, then submit. Address runtime failure feedback; ordinary command calls do not satisfy verification.`)}),n.effect(()=>r.gate(t.thread.id,i))}}),tt={name:"lagent:verify",inject:["threads","journal","commands"],async apply(n){T(n,"verify"),await n.plugin(_)}};export{b as VERIFY_OWNER,w as VERIFY_PRESET,k as VERIFY_REPAIRS,he as VerifyConfigSchema,tt as verify,et as verifyPreset};

package/dist/plugins/verify/judgement.d.ts

@@ -0,0 +1,16 @@
+import type { StopVerdict } from '../../loop/index.js';
+import type { Seq } from '../../records/journal.js';
+import type { ToolResult } from '../../records/toolResult.js';
+import type { ReadonlyState } from '../../util/foldState.js';
+import { type Verification } from './record.js';
+import { type VerifyFacts, type DelegatedChange } from './state.js';
+export declare const attemptKey: (verification: Verification, armedAt: Seq | null) => string;
+export declare function passed(result: ReadonlyState<ToolResult>, cwd: string): boolean;
+export declare function judgment(facts: ReadonlyState<VerifyFacts>, verification: Verification, armedAt: Seq | null, delegatedAt: Seq | null): {
+    mutatedAt: number | null;
+    provenAt: number | null;
+    fresh: boolean;
+    repairs: number;
+};
+/** A pure completion plan, or bounded feedback from this candidate's one durable attempt. */
+export declare function verdict(facts: ReadonlyState<VerifyFacts>, verification: Verification, armedAt: Seq | null, delegated: DelegatedChange, candidateSeq: Seq): StopVerdict | undefined;