@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/loop/strategy.d.ts

@@ -0,0 +1,80 @@
+import type { Context } from '@leuduan/cordis';
+import type { ExtensionRecord, QueuedInput, ReplacementTrigger } from '../records/journal.js';
+import type { JsonValue } from '../util/json.js';
+import type { ModelRoute } from '../llm/provider.js';
+import type { AuxiliaryCall, AuxiliaryReply } from './auxiliary.js';
+import type { ReplacementInput } from '../state/index.js';
+/** What a strategy is told about one request to prepare the surface. */
+export type SurfacePrepareInput = {
+    readonly threadId: string;
+    /** The turn and step it runs in; both `null` for a request between turns. */
+    readonly turn: number | null;
+    readonly step: number | null;
+    /** The route the turn recorded, or for a request between turns, the thread's route. */
+    readonly route: ModelRoute;
+    /**
+     * `pressure` on every due model step, `overflow` inside a step whose request the provider refused
+     * as longer than the window, `request` when a caller asked through `thread.compact()`.
+     */
+    readonly trigger: ReplacementTrigger;
+    /**
+     * Input queued for this step, which the step records after the replacement unless it was
+     * withdrawn meanwhile. Empty on `overflow`, whose input is already recorded, and on `request`.
+     */
+    readonly queued: readonly QueuedInput[];
+    /** On `request`, the options the caller gave, opaque to the engine; otherwise `null`. */
+    readonly options: JsonValue | null;
+    /** The turn's signal, or on `request` the caller's. */
+    readonly signal: AbortSignal;
+};
+/**
+ * How a request to prepare the surface ends, as a strategy decides it: nothing to do, a failure,
+ * or replacements the engine records as one atomic group. A failure may name facts the strategy
+ * wants recorded with it, as `ext` rows on the thread, such as an unusable reply it counts.
+ */
+export type FinalPlan = {
+    readonly kind: 'skip';
+    readonly reason: string;
+} | {
+    readonly kind: 'fail';
+    readonly reason: string;
+    readonly facts?: readonly ExtensionRecord[];
+} | {
+    readonly kind: 'replace';
+    readonly replacements: readonly ReplacementInput[];
+    readonly reason?: string;
+};
+/** What came of the one model call a plan asked for. */
+export type AuxiliaryAnswer = {
+    readonly reply: AuxiliaryReply;
+} | {
+    readonly failure: unknown;
+};
+/**
+ * What a strategy returns for a request: a final plan, or one model call beside the conversation
+ * (`ask`) whose answer `finish` turns into the final plan. At most one call per request. (Not
+ * `then`: a plan with one would be awaited as a promise.)
+ */
+export type SurfacePlan = FinalPlan | {
+    readonly kind: 'ask';
+    readonly call: AuxiliaryCall;
+    finish(answer: AuxiliaryAnswer): FinalPlan | Promise<FinalPlan>;
+};
+/**
+ * A thread's one way to replace part of its surface. It reads what it needs and returns a plan;
+ * the engine makes the model call it asks for, records the replacement or the facts, and derives
+ * how the request ended from what committed. It holds no binding that outlives the request.
+ */
+export interface SurfaceStrategy {
+    /** How a refusal and a report name it, such as `compaction (summarize)`. */
+    readonly name: string;
+    plan(input: SurfacePrepareInput): SurfacePlan | Promise<SurfacePlan>;
+}
+/**
+ * Makes `strategy` the one that prepares `threadId`'s surface, for as long as the calling plugin's
+ * fiber lives. A thread runs one strategy: a second, from another mount or installation, throws, so
+ * the plugin that came later fails, and with it the activation, rather than running beside the first.
+ */
+export declare function registerSurfaceStrategy(ctx: Context, threadId: string, strategy: SurfaceStrategy): void;
+/** The strategy that prepares `threadId`'s surface, if any. */
+export declare function strategyOf(ctx: Context, threadId: string): SurfaceStrategy | undefined;

package/dist/loop/surfacePrepare.d.ts

@@ -0,0 +1,30 @@
+import type { QueuedInput, ReplacementTrigger } from '../records/journal.js';
+import type { JsonValue } from '../util/json.js';
+import { type ModelRoute } from '../llm/provider.js';
+import type { SurfacePrepareOutcome } from './hooks.js';
+import type { Lease, LoopRuntime } from './runtime.js';
+/** One request to prepare the surface, as the loop or `thread.compact()` starts it. */
+export type SurfacePrepareDispatch = {
+    readonly threadId: string;
+    readonly agentName: string;
+    readonly turn: number | null;
+    readonly step: number | null;
+    readonly route: ModelRoute;
+    readonly trigger: ReplacementTrigger;
+    readonly queued: readonly QueuedInput[];
+    readonly options: JsonValue | null;
+    readonly signal: AbortSignal;
+    /** The lease the caller holds; checked before the engine records anything for the plan. */
+    readonly lease: Lease;
+};
+/** How a request settled, and the error that ended it when the strategy threw. */
+export type SurfacePrepareSettled = {
+    readonly outcome: SurfacePrepareOutcome;
+    readonly error: unknown;
+};
+/**
+ * Asks the thread's strategy for a plan and carries it out: the one model call it asks for, then the
+ * replacement or the facts its final plan names, all recorded by the engine. Never throws for the
+ * strategy: what a failure means is the trigger's policy, which the caller applies.
+ */
+export declare function runSurfacePrepare(runtime: LoopRuntime, dispatch: SurfacePrepareDispatch): Promise<SurfacePrepareSettled>;

package/dist/loop/tool.d.ts

@@ -0,0 +1,106 @@
+import type { Context } from '@leuduan/cordis';
+import type { InterruptionPolicy, Seq, ThreadEnvironment } from '../records/journal.js';
+import type { JsonValue } from '../util/json.js';
+import type { ToolResult } from '../records/toolResult.js';
+import type { ReadonlyJsonValue } from '../util/json.js';
+import type { ModelRoute } from '../llm/provider.js';
+import type { ParsedToolCall, ToolCall, ToolSpec } from '../llm/primitives.js';
+/** An error result answering the dispatched call. */
+export declare const errorResult: (call: ToolCall, output: string) => ToolResult;
+/**
+ * How a tool's calls may overlap. `exclusive` forms a barrier: it starts only once the calls before
+ * it have settled, and nothing starts beside it.
+ */
+export type ToolExecutionMode = 'parallel' | 'exclusive';
+/**
+ * A call that suspends instead of answering now: it waits on a dependency outside this loop, a
+ * delegated thread's answer or a person's reply, which the constraint owner named `owner` alone
+ * interprets and resolves (`OwnerHandle.resolveWait`). Core records the declaration, the
+ * thread is held `wait` without a run slot, and once the owner records a value the call is
+ * dispatched again with `InvocationContext.wait`, where the tool returns its ordinary result from
+ * it. A cancel answers a waiting call instead. `dependency` is a JSON object the owner versions;
+ * `deadlineAt` (epoch milliseconds, or `null`) is the owner's to act on; `reason` says why in words.
+ */
+export type WaitRequest = {
+    readonly kind: 'wait';
+    readonly owner: string;
+    readonly dependency: {
+        readonly [key: string]: JsonValue;
+    };
+    readonly deadlineAt: number | null;
+    readonly reason: string;
+};
+export type ToolOutcome = ToolResult | WaitRequest;
+/** Suspends the call on `owner`'s dependency; see {@link WaitRequest}. */
+export declare const waitFor: (request: Omit<WaitRequest, "kind">) => WaitRequest;
+export declare const isWaitRequest: (outcome: object) => outcome is WaitRequest;
+/** A dispatch of a suspended call whose wait resolved: what it waited on, and the value it resolved with. */
+export type ResolvedWait = {
+    readonly dependency: {
+        readonly [key: string]: ReadonlyJsonValue;
+    };
+    readonly value: {
+        readonly [key: string]: ReadonlyJsonValue;
+    };
+};
+/**
+ * What a tool implements. `defineTool` in `services/tools.ts` builds one, with validation and timing; this
+ * is the contract underneath it.
+ */
+export interface Tool {
+    readonly name: string;
+    /**
+     * Whether a call may run beside the others of its response. `parallel` for a tool whose calls do
+     * not depend on each other's effects, `exclusive` for one that changes state: an exclusive call
+     * runs alone, after every call before it and before any after it. A barrier within one response's
+     * batch only: it does not isolate threads that share a workspace, nor a process a call left
+     * running. Every tool says which; there is no default.
+     */
+    readonly executionMode: ToolExecutionMode;
+    /**
+     * What a re-dispatch may do with a call of this tool that may have begun when its turn was
+     * interrupted. Every tool says which; there is no default. `rerun` for a tool that is read-only or
+     * idempotent under the call's identity (`InvocationContext.threadId` and `callSeq`); `report` for
+     * anything whose second execution would be a second effect in the world.
+     */
+    readonly onInterrupted: InterruptionPolicy;
+    buildSpec(): ToolSpec;
+    /** Never throws: validation and execution failures become `is_error` results. */
+    invoke(call: ParsedToolCall, context: InvocationContext): Promise<ToolOutcome>;
+}
+/**
+ * What a tool is handed. `ctx` is the live thread context, with its scoped tool layer,
+ * `ctx.threads`, and the services plugins provide, such as `ctx.delegations` and `ctx.ask`.
+ */
+export interface InvocationContext {
+    readonly ctx: Context;
+    /** Aborts when this turn is cancelled or the root closes. */
+    readonly signal: AbortSignal;
+    readonly agentName: string;
+    readonly threadId: string;
+    readonly callId: string;
+    /**
+     * The `tool/call` or runtime `execution/requested` row this invocation serves. The durable
+     * identity of the dispatch: unique in the journal, where a provider's `callId` may not be.
+     */
+    readonly callSeq: Seq;
+    /**
+     * The `llm/request` row that produced this call: exactly what the model was sent when it asked.
+     * Where a tool that forks this thread cuts, so the fork shares that request's cached prefix.
+     * `null` for runtime completion preparation, which has no model request.
+     */
+    readonly requestSeq: Seq | null;
+    /** Where this thread's work happens. */
+    readonly environment: ThreadEnvironment;
+    /**
+     * The route of the turn running the call, as its `turn/start` recorded it: the one its result is
+     * sent on next, and the route a new sub-agent the call starts inherits. `ctx.llm.capacity(route)`
+     * says what that result may carry.
+     */
+    readonly route: ModelRoute;
+    /**
+     * `null` on a first dispatch; on a dispatch of a call whose wait resolved, what it waited on and
+     * the value it resolved with, from which the tool returns its result without doing the work again.
+     */
+    readonly wait: ResolvedWait | null;
+}

package/dist/loop/toolCalls.d.ts

@@ -0,0 +1,35 @@
+import type { ThreadEnvironment } from '../records/journal.js';
+import type { ToolCall } from '../llm/primitives.js';
+import type { ModelRoute } from '../llm/provider.js';
+import type { LoopRuntime } from './runtime.js';
+export type ExecuteToolCallsOptions = {
+    runtime: LoopRuntime;
+    threadId: string;
+    agentName: string;
+    environment: ThreadEnvironment;
+    /** The turn's route, handed to each call. */
+    route: ModelRoute;
+    turn: number;
+    step: number;
+    calls: readonly ToolCall[];
+    signal: AbortSignal;
+};
+/**
+ * Runs one step's tool calls.
+ *
+ * Dispatch overlaps inside a bounded pool, but results are appended in **model order**: the journal
+ * is what the next request is built from, so the order calls happen to settle in must not be able
+ * to reorder the conversation. A call that suspends leaves a hole: its group goes on, since its calls
+ * were declared independent, but no later group starts, and its result comes in a later turn, after
+ * its siblings'. Providers pair results by call id, so the conversation stays valid.
+ *
+ * Every result is appended only while its call is still unanswered, checked inside its write: a
+ * cancel answers a suspended call in its own write, perhaps while that call runs again.
+ *
+ * Returns nothing: what happened is in the journal. A call held for the user left a
+ * `confirm/requested`, a call whose tool suspended left a `wait/declared`, a call that ended the turn
+ * left it on its result, and a call that was never answered is simply missing a `tool/result`. The
+ * decider reads all of them from there, so there is no outcome to hand back and no chance of the two
+ * disagreeing.
+ */
+export declare function executeToolCalls(options: ExecuteToolCallsOptions): Promise<void>;

package/dist/plugin.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The plugin-authoring door: 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`); reading paths and git as the shipped tools
+ * do (`sys/`). A tool touches files and starts processes through `InvocationContext.operation`, so the
+ * confinement policy judges them; the raw process launches (`spawnCommand`, `runToCompletion`) are on
+ * the root door, for the host's own processes;
+ * 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/records`.
+ */
+export * from './context.js';
+export { defineTool, errorResult, grantTool, registerTool } from './services/tools.js';
+export type { JsonSchemaParameters, ToolDefinition, ToolReply } from './services/tools.js';
+export { claimThread, drainBeforeUnload, requireService, requireUnscoped } from './services/plugins.js';
+export { defineModes } from './services/modes.js';
+export type { Modes, ModesDefinition } from './services/modes.js';
+export { AgentSelectorSchema, isScopedAgentName, registerAgent, selects } from './services/agents.js';
+export type { AgentSelector } from './services/agents.js';
+export { definePreset, mountPreset, parsePresetConfig } from './services/presets/definition.js';
+export type { Preset, PresetInstallation, PresetMountOptions, PresetPlace, PresetPlacement, PresetSelection, } from './services/presets/definition.js';
+export { handDown } from './services/presets/installations.js';
+export type { HandDown } from './services/presets/installations.js';
+export type { AgentDefinition, AgentDefinitionInput } from './loop/index.js';
+export { contributePrompt } from './services/prompts.js';
+export { defineContribution } from './services/catalogContributions.js';
+export type { ContributionDefinition, ContributionReading } from './services/catalogContributions.js';
+export type { PromptContribution, PromptRenderInput, PromptSlot } from './services/prompts.js';
+export { ExtensionVersionError, defineExtensionEvent, latestNotice, latestVisible, tellOnStep, } from './services/extensionEvents.js';
+export type { NoticeEvent, StepNotice, ToldNotice, ToldNotices } from './services/extensionEvents.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 './state/index.js';
+export { isWaitRequest, waitFor } from './loop/index.js';
+export { lastAssistantMessage } from './state/index.js';
+export { registerSurfaceStrategy } from './loop/index.js';
+export type { AuxiliaryCall, AuxiliaryReply, CompletionRequest, InvocationContext, ModelRequestDraft, ModelStep, SentModelRequest, SentRequest, StopVerdict, AuxiliaryAnswer, FinalPlan, SurfacePlan, SurfacePrepareInput, SurfaceStrategy, Tool, ToolAuthorizationRequest, ToolDenial, ToolEntry, ToolExecutionMode, ToolInvocation, ToolOutcome, ToolPolicyDecision, TurnStop, WaitRequest, ResolvedWait, } from './loop/index.js';
+export type { ReplacementInput } from './state/index.js';
+export { stableStringify } from './util/json.js';
+export { systemClock, timerQueue } from './util/timers.js';
+export type { Clock, TimerQueue } from './util/timers.js';
+export type { AppendEntry } from './journal/index.js';
+export type { SpawnEnvironment } from './sys/spawn.js';

package/dist/plugin.js

@@ -0,0 +1 @@
+import{b as N}from"./chunks/DDZ7YF26.js";import{b as t}from"./chunks/KUZCL2SH.js";import{c as P}from"./chunks/CQEVREBT.js";import{b as w,d as F}from"./chunks/HK6ZSONF.js";import{a as M}from"./chunks/7VAPNE3L.js";import{b}from"./chunks/EPYQ5M3B.js";import"./chunks/5IRF47YB.js";import{a as u,b as S,e as E}from"./chunks/OL5A6ITQ.js";import{b as A,c as T,e as h}from"./chunks/JFX2MXBA.js";import{a as l,b as c,c as d,d as g}from"./chunks/S34ZA2R6.js";import{a as q,b as y,c as C,d as j,e as v}from"./chunks/6FRNHMCV.js";import{b as m,c as p,d as a,e as x}from"./chunks/CUK7CGC7.js";import{U as i,V as n,W as s,Y as f}from"./chunks/BPRCULZH.js";import"./chunks/FJLU4UH3.js";import"./chunks/DDANMY45.js";import{c as e,h as r,j as o}from"./chunks/BBCW2FZK.js";import"./chunks/MMNNZCBO.js";import"./chunks/G44LG6VL.js";import"./chunks/D4PQP5MA.js";export{p as AgentSelectorSchema,q as ExtensionVersionError,o as ProjectionFailedError,l as claimThread,b as contributePrompt,M as defineContribution,y as defineExtensionEvent,N as defineModes,u as definePreset,A as defineTool,c as drainBeforeUnload,i as errorResult,h as grantTool,P as handDown,x as isScopedAgentName,s as isWaitRequest,t as lastAssistantMessage,C as latestNotice,j as latestVisible,S as mountPreset,E as parsePresetConfig,r as projection,m as registerAgent,f as registerSurfaceStrategy,T as registerTool,d as requireService,g as requireUnscoped,a as selects,e as stableStringify,w as systemClock,v as tellOnStep,F as timerQueue,n as waitFor};

package/dist/plugins/agentsMd.d.ts

@@ -0,0 +1,80 @@
+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>;
+    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 `confinement`. 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 selector; `threadId` is the thread it is
+ * mounted for.
+ *
+ * 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.
+ *
+ * The files are read through the thread's confinement operation, as its own file tools would read
+ * them, and read ahead: the returned promise settles once they were, so a setup that awaits it
+ * leaves the thread ready with its instructions prepared, and the step, which cannot wait, only tells
+ * what was prepared. What a step finds unprepared, because the confinement changed since the read
+ * (`ConfinementService.epoch`), is dropped and prepared again for a later step, never read by the
+ * step itself and never told from before the change. An operation the handler refuses (a sandbox
+ * that cannot say what the conversation may read) tells nothing, records nothing, and says so in the log.
+ */
+export declare function tellAgentsMd(ctx: Context, briefing: Briefing, threadId: string): Promise<void>;
+/**
+ * Tells a thread the instructions file in its `cwd`, once, as a conversation message: on the first
+ * model step at which nothing of the kind is recorded for the thread, it reads the first of
+ * `fileNames` in the `cwd` that exists and is not empty, at most `maxBytes` of it, and records what
+ * it told, "none found" included, with those settings. Only the `cwd` is looked in: no directory
+ * above it, whatever marks a repository there. 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 file with its tools,
+ * since a 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 file applies: it governs the `cwd`'s tree, direct instructions beat
+ * it, 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/presets/definition.js").Preset<z.ZodObject<{
+    fileNames: 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/EMRB4KCN.js";import"../chunks/PUSUPTAT.js";import"../chunks/CQEVREBT.js";import"../chunks/5IRF47YB.js";import"../chunks/OL5A6ITQ.js";import"../chunks/S34ZA2R6.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{c as AGENTS_MD_INSTALLATION,b as AGENTS_MD_PRESET,a as AgentsMdDiscoverySchema,e as agentsMdPreset,d as tellAgentsMd};

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/guides/plugins.md`, Run constraints).
+ */
+export declare const ask: Plugin.Constructor<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/RCIHV3KG.js";import"../../chunks/MNJ4SRF7.js";import"../../chunks/HK6ZSONF.js";import"../../chunks/JFX2MXBA.js";import"../../chunks/S34ZA2R6.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 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 '../../records/journal.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("../../util/timers.js").Clock, import("../../util/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/ask/tools.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/commands/index.d.ts

@@ -0,0 +1,43 @@
+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.confinement`, with the thread they serve,
+ * so a host that registers a confinement 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.
+ *
+ * Each command's log is kept in its thread's directory, so the plugin injects `threadDirs`: on a root
+ * without `threadDirs` mounted it stays pending, mounting nothing, until one is.
+ *
+ * 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/JFZZXVWD.js";import"../../chunks/N6IXG2VL.js";import"../../chunks/6DRCKZ2C.js";import"../../chunks/7LI64H5X.js";import"../../chunks/3UMZMPWW.js";import"../../chunks/7VAPNE3L.js";import"../../chunks/EPYQ5M3B.js";import"../../chunks/5IRF47YB.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{e as COMMAND_TOOLS,b as commandRecords,a as commandRow,d as commandWork,f as commands,c as readCommandNotice};