@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/models/wire/primitives.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import type { ContentPart } from '../../llm/index.js';
+export declare const ToolResultPayloadSchema: z.ZodObject<{
+    output: z.ZodString;
+    content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        detail: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            low: "low";
+            high: "high";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>], "type">>>;
+    is_error: z.ZodDefault<z.ZodBoolean>;
+    notes: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    concludes_turn: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+export type ToolResultPayload = z.infer<typeof ToolResultPayloadSchema>;
+/** A payload as a tool writes one: `is_error`, `notes` and `metadata` may be left out. */
+export type ToolResultPayloadInput = z.input<typeof ToolResultPayloadSchema>;
+export declare const ToolResultSchema: z.ZodObject<{
+    output: z.ZodString;
+    content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        detail: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            low: "low";
+            high: "high";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>], "type">>>;
+    is_error: z.ZodDefault<z.ZodBoolean>;
+    notes: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    concludes_turn: z.ZodOptional<z.ZodLiteral<true>>;
+    call_id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type ToolResult = z.infer<typeof ToolResultSchema>;
+export declare function toolResultMessageContent(result: ToolResult): ContentPart[];

package/dist/plugin.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The plugin-authoring kit: what a plugin imports beside `@leuduan/cordis`.
+ *
+ * Registering a tool, an agent or a prompt contribution; granting a tool; defining, mounting and
+ * validating the configuration of a preset (`definePreset`, `mountPreset`, `parsePresetConfig`), and
+ * handing one down to the children a thread's calls create (`handDown`);
+ * defining a durable `ext` event, writing it beside a send or a creation (`WriteRows`), and reading what a thread was
+ * told; defining a set of durable modes (`defineModes`); adding a typed value to every thread's catalog entry (`defineContribution`); claiming a thread for one plugin, refusing a mount in a thread's scope (`requireUnscoped`)
+ * and refusing a missing root service (`requireService`); running a process, reading paths and git as
+ * the shipped tools do (`sys/`);
+ * the contracts a tool and a step hook implement; and the `ctx.*` service types every plugin reads.
+ * A value lives on one door: the application API is the root entry point, the model contracts are
+ * `@leuduan/lagent/llm`, the serialized shapes (`JournalEvent`, `Seq`, `ToolResult`, `stepContribution`,
+ * `toJsonSchema`) are `@leuduan/lagent/models`.
+ */
+export * from './context.js';
+export { defineTool, errorResult, provideTool } from './kit/tool.js';
+export type { JsonSchemaParameters, ToolDefinition, ToolReply } from './kit/tool.js';
+export { grantTool } from './kit/grants.js';
+export { drainBeforeUnload } from './kit/drain.js';
+export { defineModes } from './kit/modes.js';
+export type { Modes, ModesDefinition } from './kit/modes.js';
+export { AgentSelectorSchema, isScopedAgentName, requireUnscoped, selects } from './kit/scope.js';
+export { requireService } from './kit/service.js';
+export type { AgentSelector } from './kit/scope.js';
+export { registerAgent } from './services/agents.js';
+export { definePreset, mountPreset, parsePresetConfig } from './services/preset.js';
+export type { Preset, PresetInstallation, PresetMountOptions, PresetPlace, PresetPlacement, PresetSelection, } from './services/preset.js';
+export { handDown } from './services/presets.js';
+export type { HandDown } from './services/presets.js';
+export type { AgentDefinition, AgentDefinitionInput } from './models/index.js';
+export { contributePrompt } from './services/prompts.js';
+export { defineContribution } from './services/contributions.js';
+export type { ContributionDefinition, ContributionReading } from './services/contributions.js';
+export type { PromptContribution, PromptRenderInput, PromptSlot } from './services/prompts.js';
+export { ExtensionVersionError, defineExtensionEvent, latestNotice, latestVisible, tellOnStep, } from './kit/extension.js';
+export type { NoticeEvent, StepNotice, ToldNotice, ToldNotices } from './kit/extension.js';
+export { ProjectionFailedError, projection } from './journal/index.js';
+export type { AppendOptions, Committed, PluginJournal, PluginProjection, Transaction } from './journal/index.js';
+export type { CallerChain, OriginBreak, OriginOpening, Origins, RequiredOwner, RequiredOwners, } from './journal/index.js';
+export type { BirthSpec, ForkOpening, FreshOpening, Refusal, RowsResult, RowsWrite, WriteRows } from './loop/index.js';
+export { isWaitRequest, lastAssistantMessage, waitFor } from './loop/index.js';
+export { provideStrategy } from './kit/strategy.js';
+export type { AuxiliaryCall, AuxiliaryReply, InvocationContext, ModelRequestDraft, ModelStep, SentModelRequest, SentRequest, ReplacementInput, StopVerdict, AuxiliaryAnswer, FinalPlan, SurfacePlan, SurfacePrepareInput, SurfaceStrategy, Tool, ToolAuthorizationRequest, ToolDenial, ToolEntry, ToolExecutionMode, ToolInvocation, ToolOutcome, ToolPolicyDecision, TurnStop, WaitRequest, ResolvedWait, } from './loop/index.js';
+export { stableStringify } from './util/json.js';
+export { claimThread } from './kit/claim.js';
+export { systemClock, timerQueue } from './kit/timers.js';
+export type { Clock, TimerQueue } from './kit/timers.js';
+export { pathBoundary } from './sys/paths.js';
+export type { BoundaryScope, PathAccess, PathBoundary } from './sys/paths.js';
+export { runToCompletion, spawnCommand } from './sys/spawn.js';
+export type { AppendEntry } from './journal/index.js';
+export type { SpawnEnvironment, SpawnOptions, SpawnResult, SpawnStdio, SpawnedCommand, SpawnedGroup, SpawnedPipes, StopCause, } from './sys/spawn.js';

package/dist/plugin.js

@@ -0,0 +1 @@
+import{a as F}from"./chunks/6ECI2GGV.js";import{a as T}from"./chunks/4XVRUSCQ.js";import{b as x,c as B}from"./chunks/SGGMBSBA.js";import{c as S}from"./chunks/3QCW4WDJ.js";import{b as N,d as R}from"./chunks/J5S4URAW.js";import{a as U}from"./chunks/SL2YLB2F.js";import{b as C}from"./chunks/RK3VP2Q4.js";import"./chunks/74HKUGRR.js";import{a as M}from"./chunks/QMMLQJBS.js";import{a as P}from"./chunks/YIR5MYGU.js";import{a as c,b as u,e as g}from"./chunks/L3N4FIEN.js";import{a as b,b as h}from"./chunks/NAOUTU7A.js";import"./chunks/UKXMCHHT.js";import{b as j}from"./chunks/CDQG7RKA.js";import{a as E}from"./chunks/G6RXC3AL.js";import{b as l,c as d}from"./chunks/DXFXAYDN.js";import{a as v,b as y,c as A,d as q,e as w}from"./chunks/DRYAN665.js";import{a as m,b as f,c as s,d as a}from"./chunks/2OSESBIL.js";import{R as t,ia as i,ja as n,ka as p}from"./chunks/YLNJXQ3Z.js";import"./chunks/DDANMY45.js";import{d as e,h as o,j as r}from"./chunks/37YOGDGY.js";import"./chunks/KESCTXGO.js";import"./chunks/TYTQRLTX.js";import"./chunks/D7E6EWIE.js";export{m as AgentSelectorSchema,v as ExtensionVersionError,r as ProjectionFailedError,F as claimThread,C as contributePrompt,U as defineContribution,y as defineExtensionEvent,j as defineModes,c as definePreset,b as defineTool,P as drainBeforeUnload,p as errorResult,B as grantTool,S as handDown,s as isScopedAgentName,n as isWaitRequest,t as lastAssistantMessage,A as latestNotice,q as latestVisible,u as mountPreset,g as parsePresetConfig,E as pathBoundary,o as projection,T as provideStrategy,h as provideTool,x as registerAgent,M as requireService,a as requireUnscoped,d as runToCompletion,f as selects,l as spawnCommand,e as stableStringify,N as systemClock,w as tellOnStep,R as timerQueue,i as waitFor};

package/dist/plugins/agentsMd.d.ts

@@ -0,0 +1,76 @@
+import { type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+/**
+ * Where a thread's instructions are found and how much of them it is told: the agents-md preset's
+ * whole configuration, and the plugin form's besides its selector. All depend on the host, so none
+ * has a default here.
+ */
+export declare const AgentsMdDiscoverySchema: z.ZodObject<{
+    fileNames: z.ZodArray<z.ZodString>;
+    rootMarkers: z.ZodArray<z.ZodString>;
+    maxBytes: z.ZodNumber;
+}, z.core.$strict>;
+export type AgentsMdDiscovery = z.output<typeof AgentsMdDiscoverySchema>;
+/** The preset's id, which `codexPreset` hands down. */
+export declare const AGENTS_MD_PRESET = "agents-md";
+/** The installation id the preset hands itself down under, so a child holds one and passes it on. */
+export declare const AGENTS_MD_INSTALLATION = "agents-md";
+/** Where instructions are found, and who tells them, as a refusal of a second briefing names it. */
+export type Briefing = AgentsMdDiscovery & {
+    readonly holder: string;
+};
+/**
+ * Tells the thread whose scope the calling plugin is mounted in its instructions, for as long as
+ * that plugin lives; the plugin injects `journal` and `threadDirs`. The one implementation behind
+ * both forms, and what `codexPreset` mounts on its own thread. Only that thread's steps reach a
+ * listener in its scope, so the briefing needs no thread id or selector.
+ *
+ * It claims the thread's scope first, so a second briefing on the thread is refused, naming
+ * `holder`'s, and tells the thread at the first model step at which no notice found with the same
+ * discovery settings is the latest recorded: the files, or that none was found, as one recorded
+ * notice with those settings. Every later step under the same settings works from that record, so
+ * the files are never read again for them, a reopen or a retried call repeats nothing, and a fork
+ * inherits what its source was told; a briefing with other settings, such as an installation that
+ * replaced the first, finds and tells the files anew.
+ */
+export declare function tellAgentsMd(ctx: Context, briefing: Briefing): void;
+/**
+ * Tells a thread the instructions files from its project root down to its `cwd`, once, as a
+ * conversation message: on the first model step at which nothing of the kind is recorded for the
+ * thread, it finds the project root, the nearest directory at or above the `cwd` holding one of
+ * `rootMarkers` without leaving what the thread may read (its `cwd` and read roots), else the `cwd`
+ * itself; in each directory from there down to the `cwd` it reads the first of `fileNames` that
+ * exists and is not empty, root first, at most `maxBytes` of them all; and it records what it told,
+ * "none found" included, with those settings. A thread is never told twice under the same settings:
+ * every later step, a reopened journal and a retried call work from that record, and edits made
+ * while the thread lives are not told; the agent can read the files with its tools, since every
+ * file told is inside what it may read. A conversation already under way is told at its next step,
+ * and so is one whose briefing now has other settings than its latest notice recorded.
+ *
+ * The notice states how the files apply: each governs its directory's tree, the deeper wins on a
+ * conflict, direct instructions beat any file, and files below the `cwd` are the agent's to look
+ * for when it works there.
+ *
+ * The notice is recorded text, so once a replacement takes it off the surface it is told again as
+ * recorded: a copy of the notice row's content, under the same source, never a fresh read of the
+ * file, so a compaction is not the moment an edit gets told.
+ *
+ * Not a prompt section: `rebuildPrompt()` would pick up an edited file and change the thread's
+ * instructions with nothing in history saying when. A file that cannot be read is logged and
+ * skipped rather than failing the step, since an optional file must not block a thread.
+ *
+ * A thread has one briefing: a second, from another mount or installation, is refused when the
+ * thread activates, naming the first.
+ *
+ * Two placements. Installed on a thread, it tells that thread and hands itself down with the same
+ * settings under {@link AGENTS_MD_INSTALLATION}, so a child is born with it, and its children in
+ * turn; register it at startup, where a reopened child restores it whether or not its parent is
+ * live. Mounted on the root for an agent selector,
+ * `mountPreset(root, agentsMdPreset, discovery, { agents })`, it tells each activation whose agent
+ * the selector picks, and hands nothing down. Its configuration is only the discovery settings.
+ */
+export declare const agentsMdPreset: import("../services/preset.js").Preset<z.ZodObject<{
+    fileNames: z.ZodArray<z.ZodString>;
+    rootMarkers: z.ZodArray<z.ZodString>;
+    maxBytes: z.ZodNumber;
+}, z.core.$strict>>;

package/dist/plugins/agentsMd.js

@@ -0,0 +1 @@
+import{a,b,c,d,e}from"../chunks/P5ZHHOOM.js";import"../chunks/6ECI2GGV.js";import"../chunks/OVZFGILJ.js";import"../chunks/3QCW4WDJ.js";import"../chunks/74HKUGRR.js";import"../chunks/L3N4FIEN.js";import"../chunks/PUSUPTAT.js";import"../chunks/G6RXC3AL.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{c as AGENTS_MD_INSTALLATION,b as AGENTS_MD_PRESET,a as AgentsMdDiscoverySchema,e as agentsMdPreset,d as tellAgentsMd};

package/dist/plugins/ask/askQuestion.d.ts

@@ -0,0 +1,9 @@
+import type { Tool } from '../../loop/index.js';
+/**
+ * Asks the user a question through the ask service (`ctx.ask`): the call suspends on a durable wait,
+ * its run gives up its slot, and the call runs again once the question resolves. It is then
+ * answered with the person's answer, or, past the host's deadline, told to go on without it, which
+ * is no error and conveys no approval. A cancel answers the call itself, so it never runs again.
+ * Offered as `name`, `ask_question` unless the plugin renames it.
+ */
+export declare const askQuestionTool: (name: string) => Tool;

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

@@ -0,0 +1,26 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type AskServiceConfig } from './service.js';
+/**
+ * The questions agents ask the user, through the `ctx.ask` service it mounts: each is a durable wait
+ * the host lists with `open(threadId)` and answers with `answer({ threadId, callSeq }, text)`, which
+ * survives a reload and a restart. Its configuration is required: `deadlineMs`, how long a question
+ * waits before the agent is told to go on without it (`null` for no deadline), and the `clock` it is
+ * kept on.
+ *
+ * Root-only, mounted once by the application, before the presets that mount {@link askQuestion}.
+ * The worked example is in the plugin guide (`docs/plugins.md`, Run constraints).
+ */
+export declare const ask: Plugin.Object<AskServiceConfig>;
+declare const AskQuestionConfigSchema: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    agents: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+}, z.core.$strip>;
+export type AskQuestionConfig = z.input<typeof AskQuestionConfigSchema>;
+/**
+ * Lets agents ask the user questions: the `ask_question` tool, for the agents `agents` selects.
+ * Mounted where a preset grants it; refuses to mount without the {@link ask} service.
+ */
+export declare const askQuestion: Plugin.Object<AskQuestionConfig>;
+export { ASK_OWNER, QuestionAnsweredError, QuestionClosedError } from './service.js';
+export type { AskService, AskServiceConfig, OpenQuestion } from './service.js';

package/dist/plugins/ask/index.js

@@ -0,0 +1 @@
+import{a,b,c,d,e}from"../../chunks/UCTEU62F.js";import"../../chunks/C5LYCXJG.js";import"../../chunks/J5S4URAW.js";import"../../chunks/QMMLQJBS.js";import"../../chunks/YIR5MYGU.js";import"../../chunks/NAOUTU7A.js";import"../../chunks/UKXMCHHT.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 ASK_OWNER,b as QuestionAnsweredError,c as QuestionClosedError,d as ask,e as askQuestion};

package/dist/plugins/ask/service.d.ts

@@ -0,0 +1,125 @@
+import { Service, type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type InvocationContext, type ResolvedWait, type WaitRequest } from '../../loop/index.js';
+import type { Seq } from '../../models/index.js';
+declare module '@leuduan/cordis' {
+    interface Context {
+        /** The questions agents ask the user, and their answers (optional plugin). */
+        ask: AskService;
+    }
+}
+/** The owner a question's wait names. */
+export declare const ASK_OWNER = "lagent:ask";
+export declare const AskServiceConfigSchema: z.ZodObject<{
+    deadlineMs: z.ZodNullable<z.ZodNumber>;
+    clock: z.ZodCustom<import("../../kit/timers.js").Clock, import("../../kit/timers.js").Clock>;
+}, z.core.$strict>;
+export type AskServiceConfig = z.input<typeof AskServiceConfigSchema>;
+declare const AskOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strict>;
+/** One predefined answer. The user may always reply freely instead. */
+export type AskOption = z.output<typeof AskOptionSchema>;
+/** How a question resolved, versioned by ask: the person's answer, or its deadline passing. */
+declare const QuestionValueSchema: z.ZodUnion<readonly [z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    answer: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    timeout: z.ZodLiteral<true>;
+}, z.core.$strict>]>;
+export type QuestionValue = z.output<typeof QuestionValueSchema>;
+/** A question waiting for its answer, from the asking thread's rows. */
+export type OpenQuestion = {
+    readonly threadId: string;
+    /** The asking call's `tool/call` row: the question's identity. */
+    readonly callSeq: Seq;
+    readonly question: string;
+    readonly options: readonly AskOption[] | null;
+    readonly agent: string;
+    readonly deadlineAt: number | null;
+};
+/** An answer to a question that already has one, recorded first: a person's answer, or its timeout. */
+export declare class QuestionAnsweredError extends Error {
+    readonly threadId: string;
+    readonly callSeq: Seq;
+    readonly recorded: QuestionValue;
+    constructor(threadId: string, callSeq: Seq, recorded: QuestionValue);
+}
+/** An answer to a question that is not open: its call was answered without one, or it was never asked. */
+export declare class QuestionClosedError extends Error {
+    readonly threadId: string;
+    readonly callSeq: Seq;
+    constructor(threadId: string, callSeq: Seq);
+}
+/** What a resolved question's call is answered with: what it asked, and how it resolved. */
+export declare function questionAnswer(wait: ResolvedWait): {
+    readonly question: string;
+    readonly value: QuestionValue;
+};
+/**
+ * The questions agents ask the user. A question is a durable wait under {@link ASK_OWNER}: the
+ * asking call suspends, its run gives up its slot and the thread is held `wait` until the answer, the
+ * deadline or a cancel, across restarts too. Core owns the suspension and the redispatch; this owns
+ * the question's content, its deadline and answer-once.
+ *
+ * Deadlines are kept on one timer queue: armed as a question is declared, and at startup from the
+ * catalog, where one that passed while the process was down times out in the repair. A recorded
+ * deadline is honoured whatever `deadlineMs` says now. At the chain limit a question is asked with
+ * no deadline, since a timeout opens a reactive turn.
+ */
+export declare class AskService extends Service<AskServiceConfig> {
+    static inject: string[];
+    readonly config: z.output<typeof AskServiceConfigSchema>;
+    private readonly deadlines;
+    private handle;
+    /** Timeouts being written, which shutdown lets land. */
+    private readonly timingOut;
+    /** Timeouts whose write failed, by question: each is tried again, later. */
+    private readonly retries;
+    private closing;
+    constructor(ctx: Context, config: AskServiceConfig);
+    /** The wait a call asks `question` with, under the configured deadline. */
+    ask(context: InvocationContext, question: {
+        readonly question: string;
+        readonly options: AskOption[] | null;
+    }): WaitRequest;
+    /**
+     * The thread's open questions, in the order they were asked, from its rows. Synchronous, by a
+     * caller that holds the thread, as `ctx.threads.view` is; the catalog's `waits` under
+     * {@link ASK_OWNER} say which threads have one.
+     */
+    open(threadId: string): OpenQuestion[];
+    /**
+     * Answers the question of call `callSeq` on `threadId`, as a person: resolves once the answer is
+     * durable, and the asking call runs again with it. Refuses with {@link QuestionAnsweredError} when
+     * an answer or the deadline came first, and with {@link QuestionClosedError} when the question is
+     * not open.
+     */
+    answer(question: {
+        readonly threadId: string;
+        readonly callSeq: Seq;
+    }, text: string): Promise<void>;
+    private registration;
+    /** A question declared arms its deadline; one resolved, or whose call was answered, disarms it. */
+    private onRow;
+    private disarm;
+    private arm;
+    /**
+     * Closes a question at its deadline, unless an answer or a cancel came first. A write that fails is
+     * reported and tried again later, so the deadline is not lost with it.
+     */
+    private timeout;
+    /**
+     * The startup repair, from the catalog: every open question's deadline armed, and one that passed
+     * while the process was down timed out now. Resolves once those writes have landed, so the startup
+     * policy judges their causes. A timeout whose write failed is reported and tried again later, as at
+     * runtime, rather than failing the repair: a failed repair stays failed, and the retry recovers.
+     */
+    private repair;
+    /** Stops closing questions at their deadlines, which the next startup does, and lets those under way land. */
+    private shutdown;
+}
+export {};

package/dist/plugins/commands/background.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from '../../loop/index.js';
+import { type CommandsConfig } from './service.js';
+export declare const startCommandTool: Tool;
+/** `read_command_output`, reading within `config`'s output budget and wait cap. */
+export declare const readCommandOutputTool: (config: CommandsConfig) => Tool;
+export declare const listCommandsTool: Tool;
+/** `stop_command`, reporting within `config`'s output budget. */
+export declare const stopCommandTool: (config: CommandsConfig) => Tool;

package/dist/plugins/commands/foreground.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from '../../loop/index.js';
+import { type CommandsConfig } from './service.js';
+/** `run_command`: one shell command, run to completion under `config`. */
+export declare const runCommandTool: (config: CommandsConfig) => Tool;

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

@@ -0,0 +1,40 @@
+import type { Plugin } from '@leuduan/cordis';
+import { type CommandsConfigInput } from './service.js';
+export { commandRecords, commandRow, readCommandNotice } from './record.js';
+export type { CommandEnded, CommandNotice, CommandRecord, CommandStarted } from './record.js';
+export { commandWork } from './service.js';
+export type { CommandInfo, CommandsConfigInput, CommandsService, CommandWork } from './service.js';
+/** The tools `commands` registers, by name: the foreground one, then the four for background commands. */
+export declare const COMMAND_TOOLS: readonly ["run_command", "start_command", "read_command_output", "list_commands", "stop_command"];
+/**
+ * Shell commands: `run_command`, and background commands through `start_command`,
+ * `read_command_output`, `list_commands` and `stop_command`. Every command runs in a process group
+ * of its own (`sys/spawn`), so a timeout, a cancellation or a stop reaches everything it started,
+ * and nothing it started outlives lagent.
+ *
+ * All five tools are always registered; which agent may call which is a grant. An application that
+ * wants no background execution grants none of the four. A tool that starts a process must be held
+ * for confirmation wherever it is granted: `SAFE_WRITES_TOOLS` lists `run_command` and
+ * `start_command`.
+ *
+ * A background command started with `notify: "exit"` on a conversation with no caller wakes it with
+ * a notice when it exits on its own (`commandNotice`, which a host reads with `readCommandNotice`).
+ *
+ * Whether a thread's command work, or its subtree's, has ended has one answer, `commandWork`, from
+ * the threads' rows and what this process runs: a cleanup or a quiescence check reads it rather
+ * than the records. It holds whether or not this plugin is mounted: without it nothing drains, and
+ * a thread neither loaded nor carrying the plugin's catalog entry is unresolved.
+ *
+ * Every agent that may call `run_command` or `start_command` is told, in its prompt, what `/bin/sh`
+ * is on this system, read once at mount.
+ *
+ * Every command runs with exactly the `environment` the host configures, which nothing defaults:
+ * lagent passes on none of its own. Commands launch through `ctx.launches`, with the thread they serve,
+ * so a host that registers a launch handler, such as an OS sandbox, confines every `run_command` and
+ * `start_command` without this plugin knowing it. What the handler lets the model do is the
+ * handler's to tell, as a notice.
+ *
+ * Root-only: the background commands live on the `ctx.commands` service this mounts.
+ */
+export declare const commands: Plugin.Object<CommandsConfigInput>;
+export type { BackgroundCommand, CommandLookup, CommandsConfig, RecordedCommand, RecordedStatus } from './service.js';

package/dist/plugins/commands/index.js

@@ -0,0 +1 @@
+import{a,b,c,d,e,f}from"../../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/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{e as COMMAND_TOOLS,b as commandRecords,a as commandRow,d as commandWork,f as commands,c as readCommandNotice};

package/dist/plugins/commands/output.d.ts

@@ -0,0 +1,115 @@
+import type { Readable } from 'node:stream';
+import type { SpawnResult } from '../../sys/spawn.js';
+/**
+ * A command's log, capped at `maxBytes` in two segments: `<id>.log`, the current one, and after a
+ * rotation `<id>.1.log`, the one before it. When the current segment reaches half the cap it
+ * replaces the older one, so the latest output is always kept.
+ *
+ * Written through one stream at a time and never awaited by a call: `write` returning `false` asks
+ * the caller to pause its source until `whenWritable()`, which also waits for every rotated
+ * segment to finish flushing. A failed write is reported once, and later output is dropped rather
+ * than held.
+ */
+export declare class CommandLog {
+    readonly path: string;
+    readonly olderPath: string;
+    /** Logical bytes accepted since the command started. */
+    written: number;
+    /** Logical bytes no longer on disk. */
+    rotatedOut: number;
+    private stream;
+    /** Rotated streams that have not closed yet. */
+    private readonly flushing;
+    private segmentBytes;
+    private olderBytes;
+    private opened;
+    private failed;
+    private readonly maxBytes;
+    private readonly onError;
+    constructor(path: string, maxBytes: number, onError: (error: unknown) => void);
+    get rotated(): boolean;
+    /** Where the output is, and what rotation or a failed write removed from it. */
+    describe(): string;
+    /** `false` when the source should pause until {@link whenWritable}. */
+    write(chunk: Buffer): boolean;
+    whenWritable(): Promise<void>;
+    end(): void;
+    private needsDrain;
+    /**
+     * The file is opened synchronously and the stream writes to its descriptor, so a rename during a
+     * rotation never races an open, and writes still pending land in the segment they belong to.
+     * A re-dispatched command appends to its log after a separator line.
+     */
+    private open;
+    private rotate;
+    private fail;
+}
+export type CommandOutputOptions = {
+    /** Characters held for a result's head and for its tail; also the most one result shows. */
+    capacityChars: number;
+    openLog: () => CommandLog;
+    /** A background command logs from the start; a foreground one only once its output overflows. */
+    logFromStart: boolean;
+};
+/**
+ * One command's output: one pipe, in exact order, through one decoder, so a character split across
+ * chunks survives. Memory is bounded by a head and a tail of `capacityChars` each, plus one write
+ * buffer of the log; the log has the rest.
+ *
+ * Reads are relative to a mark. A foreground command's mark stays at the start; a background
+ * command's moves to the end of each read, so the next read shows only newer output.
+ */
+export declare class CommandOutput {
+    private readonly decoder;
+    private log;
+    /** Raw output held until the log opens, so the log starts from the first byte. */
+    private pending;
+    private totalChars;
+    private markChars;
+    /** The first `capacityChars` since the mark, and whether that is everything since it. */
+    private sinceMark;
+    private sinceMarkComplete;
+    /** At least the last `capacityChars`, at most twice that. */
+    private recent;
+    private readonly listeners;
+    private finished;
+    private readonly options;
+    constructor(options: CommandOutputOptions);
+    /** The log's path once it exists. */
+    get logPath(): string | undefined;
+    get logDescription(): string | undefined;
+    get isFinished(): boolean;
+    get hasUnread(): boolean;
+    /** Reads `source` to its end, pausing it while the log's buffer is full. */
+    attach(source: Readable): void;
+    /** Adds text the command did not print, such as a launch handler's report; before {@link finish}. */
+    note(text: string): void;
+    /** Flushes the decoder and ends the log. Call once the command has settled. */
+    finish(): void;
+    /** Called on new output and on `finish`, after which `finished` holds; returns the unsubscribe function. */
+    onChange(listener: () => void): () => void;
+    /**
+     * Renders the output since the mark and then `trailer`, within `budget` characters. The trailer
+     * is laid out first and its length reserved, so no cut can remove it. What does not fit is cut
+     * from the middle, one part head to four parts tail, around the marker `omission` renders.
+     * `advance` moves the mark to the end, so what was skipped is not shown again.
+     */
+    render(options: {
+        budget: number;
+        trailer: readonly string[];
+        empty: string;
+        omission: (omittedChars: number, log: CommandLog) => string;
+        advance: boolean;
+    }): string;
+    private push;
+    private append;
+    private ensureLog;
+    private notify;
+}
+export declare const capitalize: (text: string) => string;
+/** A duration as a person reads it: `850ms`, `12.4s`, `3m 12s`, `2h 5m`. */
+export declare function formatDuration(ms: number): string;
+/** How the command's leader ended: its exit code, its signal, or that it never exited. */
+export declare function describeExit(result: SpawnResult): string;
+/** The marker for a stop that could not be confirmed. */
+export declare const stopFailedMarker: (graceSeconds: number) => string;