@leuduan/lagent 0.1.2 → 44.0.0

package/dist/plugins/agentsMd.d.ts

@@ -7,7 +7,6 @@ import { z } from 'zod';
  */
 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>;
@@ -21,9 +20,10 @@ export type Briefing = AgentsMdDiscovery & {
 };
 /**
  * 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
+ * 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 thread id or selector.
+ * 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
@@ -32,24 +32,29 @@ export type Briefing = AgentsMdDiscovery & {
  * 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): void;
+export declare function tellAgentsMd(ctx: Context, briefing: Briefing, threadId: string): Promise<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.
+ * 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 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 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
@@ -69,8 +74,7 @@ export declare function tellAgentsMd(ctx: Context, briefing: Briefing): void;
  * `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<{
+export declare const agentsMdPreset: import("../services/presets/definition.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

@@ -1 +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};
+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

@@ -9,9 +9,9 @@ import { type AskServiceConfig } from './service.js';
  * 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).
+ * The worked example is in the plugin guide (`docs/guides/plugins.md`, Run constraints).
  */
-export declare const ask: Plugin.Object<AskServiceConfig>;
+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">]>;

package/dist/plugins/ask/index.js

@@ -1 +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};
+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

@@ -1,7 +1,7 @@
 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';
+import type { Seq } from '../../records/journal.js';
 declare module '@leuduan/cordis' {
     interface Context {
         /** The questions agents ask the user, and their answers (optional plugin). */
@@ -12,7 +12,7 @@ declare module '@leuduan/cordis' {
 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>;
+    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<{

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

@@ -29,11 +29,14 @@ export declare const COMMAND_TOOLS: readonly ["run_command", "start_command", "r
  * 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
+ * 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>;

package/dist/plugins/commands/index.js

@@ -1 +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};
+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};

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

@@ -82,7 +82,7 @@ export declare class CommandOutput {
     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}. */
+    /** Adds text the command did not print, such as a confinement 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;

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { type ExtensionRecord, type Seq } from '../../models/index.js';
+import { type ExtensionRecord, type Seq } from '../../records/journal.js';
 import type { DeepReadonly } from '../../util/json.js';
 /**
  * What the journal keeps of a background command, so that a lagent process that did not start it
@@ -185,8 +185,8 @@ export declare const commandRow: {
         stop_failed: boolean;
         stop_reason: string | null;
         ended_at: string;
-    }, options: import("../../journal/journal.js").AppendOptions): Promise<import("../../models/index.js").JournalEvent<"ext">>;
-    read(event: import("../../models/index.js").JournalEvent): {
+    }, options: import("../../journal/journal.js").AppendOptions): Promise<import("../../records/journal.js").JournalEvent<"ext">>;
+    read(event: import("../../records/journal.js").JournalEvent): {
         op: "started";
         id: string;
         call_seq: number;
@@ -212,7 +212,7 @@ export declare const commandRow: {
         ended_at: string;
     } | undefined;
     contribution(message: {
-        role?: import("../../models/index.js").InputRole;
+        role?: import("../../records/journal.js").InputRole;
         content: string | readonly import("../../llm/content.js").ContentPartInput[];
     }, value: {
         op: "started";
@@ -240,7 +240,7 @@ export declare const commandRow: {
         ended_at: string;
     }, options?: {
         sourceSeqs?: readonly Seq[];
-    }): import("../../models/index.js").StepContribution;
+    }): import("../../records/journal.js").StepContribution;
     matchesSource(record: DeepReadonly<ExtensionRecord>): boolean;
     rejection(reason: string, value: {
         op: "started";
@@ -271,7 +271,7 @@ export declare const commandRow: {
         reason: string;
         source: ExtensionRecord;
     };
-    readContribution: (event: import("../../models/index.js").JournalEvent) => {
+    readContribution: (event: import("../../records/journal.js").JournalEvent) => {
         op: "started";
         id: string;
         call_seq: number;
@@ -321,7 +321,7 @@ export declare const commandRow: {
         stop_reason: string | null;
         ended_at: string;
     } | undefined;
-    told: import("../../journal/projection.js").PluginProjection<import("../../kit/extension.js").ToldNotices<{
+    told: import("../../journal/projection.js").PluginProjection<import("../../services/extensionEvents.js").ToldNotices<{
         op: "started";
         id: string;
         call_seq: number;
@@ -373,7 +373,7 @@ export declare const commandRow: {
             stop_failed: boolean;
             stop_reason: string | null;
             ended_at: string;
-        }, event: import("../../models/index.js").JournalEvent<"ext">): State;
+        }, event: import("../../records/journal.js").JournalEvent<"ext">): State;
         onFork?: "inherit" | "reset";
     }): import("../../journal/projection.js").PluginProjection<State>;
 };
@@ -438,15 +438,15 @@ export declare const commandNotice: {
         exit_code: number | null;
         exit_signal: string | null;
         summary: string;
-    }, options: import("../../journal/journal.js").AppendOptions): Promise<import("../../models/index.js").JournalEvent<"ext">>;
-    read(event: import("../../models/index.js").JournalEvent): {
+    }, options: import("../../journal/journal.js").AppendOptions): Promise<import("../../records/journal.js").JournalEvent<"ext">>;
+    read(event: import("../../records/journal.js").JournalEvent): {
         id: string;
         exit_code: number | null;
         exit_signal: string | null;
         summary: string;
     } | undefined;
     contribution(message: {
-        role?: import("../../models/index.js").InputRole;
+        role?: import("../../records/journal.js").InputRole;
         content: string | readonly import("../../llm/content.js").ContentPartInput[];
     }, value: {
         id: string;
@@ -455,7 +455,7 @@ export declare const commandNotice: {
         summary: string;
     }, options?: {
         sourceSeqs?: readonly Seq[];
-    }): import("../../models/index.js").StepContribution;
+    }): import("../../records/journal.js").StepContribution;
     matchesSource(record: DeepReadonly<ExtensionRecord>): boolean;
     rejection(reason: string, value: {
         id: string;
@@ -467,7 +467,7 @@ export declare const commandNotice: {
         reason: string;
         source: ExtensionRecord;
     };
-    readContribution: (event: import("../../models/index.js").JournalEvent) => {
+    readContribution: (event: import("../../records/journal.js").JournalEvent) => {
         id: string;
         exit_code: number | null;
         exit_signal: string | null;
@@ -479,7 +479,7 @@ export declare const commandNotice: {
         exit_signal: string | null;
         summary: string;
     } | undefined;
-    told: import("../../journal/projection.js").PluginProjection<import("../../kit/extension.js").ToldNotices<{
+    told: import("../../journal/projection.js").PluginProjection<import("../../services/extensionEvents.js").ToldNotices<{
         id: string;
         exit_code: number | null;
         exit_signal: string | null;
@@ -493,7 +493,7 @@ export declare const commandNotice: {
             exit_code: number | null;
             exit_signal: string | null;
             summary: string;
-        }, event: import("../../models/index.js").JournalEvent<"ext">): State;
+        }, event: import("../../records/journal.js").JournalEvent<"ext">): State;
         onFork?: "inherit" | "reset";
     }): import("../../journal/projection.js").PluginProjection<State>;
 };
@@ -503,18 +503,19 @@ export declare const readCommandNotice: (source: DeepReadonly<ExtensionRecord> |
 export declare const RUN_COMMAND = "run_command";
 /**
  * How a `run_command` call's process group is known to have ended, from its rows alone, on
- * affirmative evidence only: `not-run` while no dispatch attempt of it was allowed, so nothing was
- * launched; once one was, `ended` only when its result carries the tool's own report that the stop
+ * affirmative evidence only: `not-run` while no dispatch attempt of it was allowed, or the runtime
+ * dispatcher records that execution was prevented before entering middleware. Otherwise,
+ * `ended` only when its result carries the tool's own report that the stop
  * succeeded (`stop_failed: false`), `stop-failed` when that report says the stop failed, and
  * `unknown` otherwise: no result yet, a call cut off, or a result written by anything but the tool,
  * such as an error that replaced its report.
  */
 export type ForegroundEnd = 'not-run' | 'ended' | 'stop-failed' | 'unknown';
 /**
- * A thread's `run_command` calls, by the seq of their `tool/call` row, with how each one's process
- * group is known to have ended. A foreground command leaves no record of its own: its call, the
- * dispatch attempt allowed before the tool runs, and its result are the evidence. Resets at a fork's
- * spawn row, as the background records do.
+ * Foreground commands, by their `tool/call` or runtime `execution/requested` row. Authorization
+ * marks a possibly started group; only the executor's result establishes cleanup, or the runtime
+ * dispatcher's unstarted outcome establishes that nothing ran. Resets at a
+ * fork's spawn row, as the background records do.
  */
 export declare const foregroundCommands: import("../../journal/projection.js").PluginProjection<Map<number, ForegroundEnd>>;
 /**
@@ -530,6 +531,10 @@ declare const UnendedCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"foreground">;
     call_seq: z.ZodNumber;
     stop_failed: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"runtime">;
+    request_seq: z.ZodNumber;
+    stop_failed: z.ZodBoolean;
 }, z.core.$strict>], "kind">;
 export type UnendedCommand = z.output<typeof UnendedCommandSchema>;
 /**
@@ -537,7 +542,7 @@ export type UnendedCommand = z.output<typeof UnendedCommandSchema>;
  * thread while the commands plugin is mounted. A thread whose records cannot be read reads
  * `unavailable`, which nothing reads as "none".
  */
-export declare const commandsContribution: import("../../services/contributions.js").ContributionDefinition<({
+export declare const commandsContribution: import("../../services/catalogContributions.js").ContributionDefinition<({
     kind: "background";
     id: string;
     stop_failed: boolean;
@@ -545,5 +550,9 @@ export declare const commandsContribution: import("../../services/contributions.
     kind: "foreground";
     call_seq: number;
     stop_failed: boolean;
+} | {
+    kind: "runtime";
+    request_seq: number;
+    stop_failed: boolean;
 })[]>;
 export {};

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

@@ -1,8 +1,8 @@
 import { Service, type Context } from '@leuduan/cordis';
 import { z } from 'zod';
-import type { SpawnResult, SpawnedCommand } from '../../sys/spawn.js';
-import type { Seq } from '../../models/index.js';
-import type { Launched, LaunchProvenance } from '../../services/launches.js';
+import { type SpawnResult, type SpawnedCommand } from '../../sys/spawn.js';
+import type { Seq } from '../../records/journal.js';
+import { type ConfinementOperation, type Launched, type LaunchProvenance } from '../../services/confinement/service.js';
 import { CommandOutput } from './output.js';
 import { type CommandEnded, type CommandRecord, type CommandStarted } from './record.js';
 declare module '@leuduan/cordis' {
@@ -66,7 +66,7 @@ export type CommandInfo = {
     readonly stopReason: string | null;
     readonly stopFailed: boolean;
     readonly logPath: string;
-    /** What the launch handler selected for it, from the live launch or the start row; `null` for a plain launch. */
+    /** What the confinement handler selected for it, from the live launch or the start row; `null` for a plain launch. */
     readonly launch: LaunchProvenance | null;
 };
 /**
@@ -90,8 +90,9 @@ export type CommandWork = {
  * still starts or runs, or whose end row is on its way, is draining; any other is unresolved. A
  * `run_command` call has ended once its result carries the tool's own report that the stop
  * succeeded, and never ran while no dispatch of it was allowed; one launched without that report is
- * draining while the service is mounted and the thread's run is running here, which is the run
- * serving it or one that may still write its result, and unresolved otherwise. A stop that failed,
+ * draining only while its current-turn dispatch is unanswered and running here. A settled result
+ * lacking cleanup evidence, or an earlier turn's abandoned dispatch, is unresolved even while a
+ * later turn is running. A stop that failed,
  * and records that cannot be read, are unresolved. Synchronous, so a write may decide on it.
  */
 export declare function commandWork(ctx: Context, threadId: string, options: {
@@ -103,8 +104,10 @@ export type StartRequest = {
     readonly callSeq: Seq;
     readonly command: string;
     readonly cwd: string;
-    /** The thread's working directory, which a launch handler treats as the root it protects. */
+    /** The thread's working directory, which a confinement handler treats as the root it protects. */
     readonly threadCwd: string;
+    /** The call's confinement operation: its one snapshot admits the launch. The command outlives the call; the operation's file access does not. */
+    readonly operation: ConfinementOperation;
     readonly notify: 'exit' | null;
 };
 /** A background command and everything the tools report about it. */
@@ -126,9 +129,9 @@ export declare class BackgroundCommand {
     constructor(id: string, threadId: string, command: string, cwd: string, output: CommandOutput, process: SpawnedCommand, 
     /** `exit`: a natural exit wakes the thread that started it with a notice. */
     notify: 'exit' | null, 
-    /** What the launch handler selected for it. */
+    /** What the confinement handler selected for it. */
     launch: LaunchProvenance | null, 
-    /** The launch handler's report on the command, which joins its output once it ended. */
+    /** The confinement handler's report on the command, which joins its output once it ended. */
     diagnostics: Promise<string | null>, onEnd: (command: BackgroundCommand) => void);
     get running(): boolean;
     get logPath(): string;
@@ -196,9 +199,12 @@ export declare class CommandsService extends Service<CommandsConfigInput> {
     private readonly operations;
     private readonly lifetime;
     constructor(ctx: Context, config: CommandsConfigInput);
+    /** Where command `id` of `threadId` logs, for a caller whose scope does not inject `threadDirs`. */
+    logPathFor(threadId: string, id: string): string;
     /**
-     * Launches one command of either kind through `ctx.launches`: the one place a command starts, so
-     * the shutdown that stops them all sees every one. Refused once shut down. `options.signal` owns
+     * Launches one command of either kind under the calling tool's confinement operation, so what the
+     * call did with files and this launch share one snapshot: the one place a command starts, so the
+     * shutdown that stops them all sees every one. Refused once shut down. `options.signal` owns
      * the command, and shutdown stops it too.
      */
     launch(request: {
@@ -206,6 +212,7 @@ export declare class CommandsService extends Service<CommandsConfigInput> {
         workdir: string;
         threadId: string;
         threadCwd: string;
+        operation: ConfinementOperation;
     }, options: {
         signal: AbortSignal;
         timeoutMs?: number;

package/dist/plugins/commands/{background.d.ts → tools.d.ts}

@@ -6,3 +6,5 @@ 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;
+/** `run_command`: one shell command, run to completion under `config`. */
+export declare const runCommandTool: (config: CommandsConfig) => Tool;

package/dist/plugins/compaction/checkpoint.d.ts

@@ -1,4 +1,5 @@
-import { type ContentPart } from '../../llm/index.js';
+import { type Context } from '@leuduan/cordis';
+import { type ContentPart } from '../../llm/content.js';
 /**
  * The texts the strategy writes: the instruction its summary call ends on, and the checkpoint that
  * stands in for a span. Everything here but the summary is written by code, so the pointers in it
@@ -89,3 +90,5 @@ export declare const widestInstruction: (options: {
     readonly cap: number;
     readonly focus: string | null;
 }) => string;
+/** Whether the thread's agent has both recall tools granted now, so a stand-in or a footer may point at them. */
+export declare function recallGranted(ctx: Context, agentName: string): boolean;

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

@@ -126,8 +126,8 @@ export type StrategyOptions<Strategy> = {
  * What a host may pass to `thread.compact({ options })` for this strategy: nothing, or what the
  * summary should pay particular attention to, as a person typing `/compact <focus>` would say it.
  */
-export declare const CompactRequestOptionsSchema: z.ZodNullable<z.ZodObject<{
+export declare const SummarizeRequestOptionsSchema: z.ZodNullable<z.ZodObject<{
     focus: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>>;
-/** The `options` a host passes to `thread.compact()` for this strategy; see `CompactRequestOptionsSchema`. */
-export type CompactRequestOptions = z.input<typeof CompactRequestOptionsSchema>;
+/** The `options` a host passes to `thread.compact()` for this strategy; see `SummarizeRequestOptionsSchema`. */
+export type SummarizeRequestOptions = z.input<typeof SummarizeRequestOptionsSchema>;

package/dist/plugins/compaction/estimate.d.ts

@@ -1,5 +1,9 @@
-import type { ContentPart, ConversationMessage, PromptBlock, ToolSpec } from '../../llm/index.js';
+import { type Context } from '@leuduan/cordis';
+import { type PromptBlock } from '../../llm/prompt.js';
+import { type ConversationMessage, type ToolSpec } from '../../llm/primitives.js';
+import type { ContentPart } from '../../llm/content.js';
 import type { DeepReadonly } from '../../util/json.js';
+import type { SurfacePrepareInput } from '../../loop/index.js';
 /**
  * A character-based estimate of what a request costs in tokens, for a strategy that budgets the
  * surface: four characters to a token, with a little framing per part and per message, as DeepSeek
@@ -27,3 +31,7 @@ export declare function estimateHead(head: {
     readonly systemPrompt: readonly PromptBlock[];
     readonly tools: readonly ToolSpec[];
 }): number;
+/** What the next request sends ahead of its messages: the recorded prompt and the tools the agent has now. */
+export declare function estimateThreadHead(ctx: Context, threadId: string, agentName: string): number;
+/** The input a step claims, which the request sends after the surface. */
+export declare const estimateClaimed: (prepare: SurfacePrepareInput) => number;

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

@@ -1,2 +1,87 @@
-export type { CompactionConfig, CompactRequestOptions, PruneStrategyConfig, SummarizeStrategyConfig } from './config.js';
-export { compaction } from './preset.js';
+/**
+ * The compaction plugin, a `thread` preset with two placements, which keeps a thread's surface
+ * within its route's window by the strategy its configuration names. Mounted on the root for an
+ * agent selector, `mountPreset(root, compactionPreset, config, { agents })`, it serves every thread whose
+ * agent `agents` selects: each matching activation gets its own strategy, provided in the thread's
+ * scope, until the mount is disposed. Installed on one thread through the presets service, it
+ * serves that thread, recorded so a reopen and a fork keep it.
+ *
+ * Both strategies act on three triggers: **pressure**, before every model step whose request is
+ * estimated above `threshold` of the window (a route whose provider declares no window is never
+ * compacted for pressure, which is reported once per route); **overflow**, when the provider
+ * refuses a step's request as too long, after which the step is asked again if anything was
+ * replaced; and **request**, `thread.compact()`, whatever the pressure.
+ *
+ * - **`summarize`**, the default. It replaces one span, after the pinned opening and between direct
+ *   developer inputs, with one `user` checkpoint: notes a summary call wrote from the surface
+ *   through the span, the person's latest input copied from its row when the span held it, and a
+ *   footer naming the messages replaced. It measures from the last usage the provider reported on
+ *   the same provider and model plus an estimate of what came since, calibrates its estimates by
+ *   an overflow, and recovers once per overflow sequence: a new turn or a completed reply allows
+ *   another. Three unusable summaries in a row stop pressure compaction until its next
+ *   checkpoint or a change of the thread's configuration; the count is recorded, so a reopen and a
+ *   fork keep it. On request, `options` may say what the summary should `focus` on.
+ * - **`prune`**. It rewrites old tool results in place, keeping each one's role and call id, to a
+ *   one-line stand-in, `[tool result pruned: <tool>, <n> characters and <k> attachments; message
+ *   <number>]`, the attachments named only when it had some, followed by where to read it back when
+ *   the agent has both `historyRecall` tools; no model is called. A result is pruned when it is an
+ *   original, never a stand-in, outside the `keepRecent` most recent tool results, and estimated at
+ *   `minTokens` or more, images and files included; every such result goes in one atomic group.
+ *   Pressure is estimated by characters, uncalibrated. Nothing eligible is `skipped`, reported once
+ *   per activation, trigger, route and latest replacement on pressure and overflow. It takes no
+ *   request options and ignores any.
+ *
+ * Plugins whose notices a replacement took away tell them again at the next model step.
+ *
+ * Disposing a root mount stops new dispatches on the threads it serves, live ones included; a
+ * dispatch already in flight finishes, and may still record its replacement. A mount added later
+ * reaches activations from then on, not threads already live: they get it at their next activation.
+ *
+ * A thread runs one strategy, and a second on it, from another mount of this plugin or any other
+ * strategy that claims its thread, is refused when the thread activates, naming the one already
+ * there. To choose per agent, mount this on the root more than once with disjoint selectors and the
+ * strategy each should run; to choose per thread, mount none on the root and install it on each
+ * thread instead.
+ *
+ * ```ts
+ * await mountPreset(root, compactionPreset, {}, { agents: ['main'] }) // summarize, with every default
+ * await mountPreset(root, compactionPreset, { strategy: { kind: 'prune', keepRecent: 4 } }, { agents: ['worker'] })
+ * ```
+ */
+export declare const compactionPreset: import("../../services/presets/definition.js").Preset<import("zod").ZodObject<{
+    threshold: import("zod").ZodDefault<import("zod").ZodNumber>;
+    strategy: import("zod").ZodPrefault<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"summarize">;
+        target: import("zod").ZodDefault<import("zod").ZodNumber>;
+        tail: import("zod").ZodDefault<import("zod").ZodNumber>;
+        opening: import("zod").ZodDefault<import("zod").ZodNumber>;
+        summaryCap: import("zod").ZodDefault<import("zod").ZodNumber>;
+        summaryFloor: import("zod").ZodDefault<import("zod").ZodNumber>;
+        reasoningAllowance: import("zod").ZodDefault<import("zod").ZodNumber>;
+        replyReserve: import("zod").ZodDefault<import("zod").ZodNumber>;
+        checkpointRatio: import("zod").ZodDefault<import("zod").ZodNumber>;
+        copiedInputChars: import("zod").ZodDefault<import("zod").ZodNumber>;
+        boundaryQuoteChars: import("zod").ZodDefault<import("zod").ZodNumber>;
+        breaker: import("zod").ZodDefault<import("zod").ZodNumber>;
+        withoutWindow: import("zod").ZodDefault<import("zod").ZodObject<{
+            tailTokens: import("zod").ZodDefault<import("zod").ZodNumber>;
+            openingTokens: import("zod").ZodDefault<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strict>>;
+        summarizer: import("zod").ZodDefault<import("zod").ZodObject<{
+            provider: import("zod").ZodOptional<import("zod").ZodString>;
+            model: import("zod").ZodOptional<import("zod").ZodString>;
+            thinkingEffort: import("zod").ZodDefault<import("zod").ZodEnum<{
+                low: "low";
+                high: "high";
+                none: "none";
+                medium: "medium";
+                max: "max";
+            }>>;
+        }, import("zod/v4/core").$strict>>;
+    }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"prune">;
+        keepRecent: import("zod").ZodDefault<import("zod").ZodNumber>;
+        minTokens: import("zod").ZodDefault<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>], "kind">>;
+}, import("zod/v4/core").$strict>>;
+export type { CompactionConfig, SummarizeRequestOptions, PruneStrategyConfig, SummarizeStrategyConfig, } from './config.js';