@leuduan/lagent 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,314 @@
+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 { CommandOutput } from './output.js';
+import { type CommandEnded, type CommandRecord, type CommandStarted } from './record.js';
+declare module '@leuduan/cordis' {
+    interface Context {
+        /** Background commands, owned by the thread that started them (optional plugin). */
+        commands: CommandsService;
+    }
+    interface Events {
+        /**
+         * A background command was started and is now in the live set `ctx.commands.list` reads: a host
+         * showing running commands refreshes on it, since the start row is written before the command
+         * is listed. Its end needs no counterpart: the end row is written once it no longer runs.
+         */
+        'lagent/commands/started'(threadId: string, commandId: string): void;
+    }
+}
+export declare const CommandsConfigSchema: z.ZodObject<{
+    environment: z.ZodRecord<z.ZodString, z.ZodString>;
+    defaultTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    maxTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    killGraceSeconds: z.ZodDefault<z.ZodNumber>;
+    maxOutputChars: z.ZodDefault<z.ZodNumber>;
+    maxLogBytes: z.ZodDefault<z.ZodNumber>;
+    maxBackgroundCommands: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type CommandsConfig = z.output<typeof CommandsConfigSchema>;
+export type CommandsConfigInput = z.input<typeof CommandsConfigSchema>;
+/** Where a thread's command logs go inside its directory. */
+export declare const COMMANDS_DIR = "commands";
+/** The `workdir` parameter of both command tools; its description steers models away from a `cd` prefix. */
+export declare const WorkdirParameter: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+/** A command's id: the `tool/call` row that started it, unique in the journal and across restarts. */
+export declare const commandId: (callSeq: Seq) => string;
+/** Where command `id` of `threadId` logs: `<thread dir>/commands/<id>.log`. */
+export declare const commandLogPath: (ctx: Context, threadId: string, id: string) => string;
+/** The segment a log rotates into: `<id>.1.log`, the output before the current segment. */
+export declare const olderLogPath: (logPath: string) => string;
+/**
+ * What this process can say about a recorded command it does not run: `exited`, when the end row
+ * says so and the stop did not fail; otherwise `orphaned`: started by a previous process and not
+ * owned here, with no claim about its process group. The reaper makes such a group almost always
+ * gone, but not while a stop is still in its grace period, nor after one that failed.
+ */
+export type RecordedStatus = {
+    readonly kind: 'exited' | 'orphaned';
+    readonly detail: string;
+};
+/** What a host sees of a background command. */
+export type CommandInfo = {
+    readonly id: string;
+    readonly threadId: string;
+    readonly command: string;
+    readonly cwd: string;
+    /** `orphaned`: recorded by another lagent process, and whether it still runs is not known to have ended. */
+    readonly status: 'running' | 'exited' | 'orphaned';
+    readonly startedAt: number;
+    readonly durationMs: number;
+    readonly exitCode: number | null;
+    readonly exitSignal: NodeJS.Signals | null;
+    /** Why lagent stopped it, when it did. */
+    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. */
+    readonly launch: LaunchProvenance | null;
+};
+/**
+ * What stands between a thread's command work and its end, each item saying why: `draining`, work
+ * this process runs and is ending, whose end it will record; `unresolved`, work whose end nothing
+ * establishes: a stop that failed, a command no process here saw end, records that cannot be read.
+ * Both empty: every command it started is known to have ended.
+ */
+export type CommandWork = {
+    readonly draining: readonly string[];
+    readonly unresolved: readonly string[];
+};
+/**
+ * Whether the command work of `threadId`, and with `descendants` of every thread under it, is known
+ * to have ended: the one answer a cleanup or a quiescence check reads before it certifies a thread
+ * quiet, whether or not the commands plugin is mounted. On affirmative evidence only, from each
+ * thread's rows: its folds when it is loaded, else its catalog entry, which the plugin contributes
+ * while mounted; an entry without it is unresolved, never read as none.
+ *
+ * A background command has ended once its end row says its stop succeeded; one the mounted service
+ * 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,
+ * 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: {
+    readonly descendants: boolean;
+}): CommandWork;
+/** What starts a background command: whose call, what to run, where, and whether its exit notifies. */
+export type StartRequest = {
+    readonly threadId: string;
+    readonly callSeq: Seq;
+    readonly command: string;
+    readonly cwd: string;
+    /** The thread's working directory, which a launch handler treats as the root it protects. */
+    readonly threadCwd: string;
+    readonly notify: 'exit' | null;
+};
+/** A background command and everything the tools report about it. */
+export declare class BackgroundCommand {
+    result: SpawnResult | null;
+    endedAt: number | null;
+    /** Why lagent stopped it; the first reason wins. */
+    stopReason: string | null;
+    readonly ended: Promise<void>;
+    readonly startedAt: number;
+    readonly id: string;
+    readonly threadId: string;
+    readonly command: string;
+    readonly cwd: string;
+    readonly output: CommandOutput;
+    readonly process: SpawnedCommand;
+    readonly notify: 'exit' | null;
+    readonly launch: LaunchProvenance | null;
+    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. */
+    launch: LaunchProvenance | null, 
+    /** The launch 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;
+    get durationMs(): number;
+    info(): CommandInfo;
+}
+/**
+ * A command the journal records and this process does not run: started by a previous lagent
+ * process, or by this one and since forgotten. This process cannot read its output as it arrives
+ * or stop it; it can say what the rows record, and read whatever log it left.
+ */
+export declare class RecordedCommand {
+    readonly threadId: string;
+    readonly record: CommandRecord;
+    readonly logPaths: readonly string[];
+    readonly status: RecordedStatus;
+    readonly ownedHere: boolean;
+    constructor(threadId: string, record: CommandRecord, 
+    /** The current log segment, then the older one when it exists. */
+    logPaths: readonly string[], status: RecordedStatus, 
+    /** Started by this service instance, and since dropped from what it tracks. */
+    ownedHere: boolean);
+    get id(): string;
+    get started(): CommandStarted;
+    get ended(): CommandEnded | null;
+    /** Whether its end is not vouched for: no end row, or one whose stop failed. Such commands are listed. */
+    get orphaned(): boolean;
+    /** The one status line every tool result about it opens with. */
+    statusLine(): string;
+    info(): CommandInfo;
+}
+/** What `lookup` found: the caller's command, one the journal records, or why there is none to act on. */
+export type CommandLookup = {
+    command: BackgroundCommand;
+} | {
+    recorded: RecordedCommand;
+} | {
+    error: string;
+};
+/**
+ * The background commands of this process. A command belongs to the thread that started it, and
+ * only that thread's tools may read or stop it; that is an access rule, not a lifetime. The
+ * command, its log writer and its read cursor live here, on the root, so releasing or reinstalling
+ * a thread's activation leaves them untouched.
+ *
+ * A command runs until it exits, is stopped, the root is disposed, or — for a delegated thread —
+ * its turn ends any way but `blocked`, since its caller may never follow up and cannot see the
+ * command. Cancelling a turn does not stop one: outliving the turn is the point.
+ *
+ * Commands are process-local, and the journal records their starts and ends: a reopened root
+ * starts with none of its own, and lists the ones whose end no process vouched for — started by a
+ * previous process and never seen to end, or ended by a stop that failed — as not owned here
+ * (`record.ts`).
+ */
+export declare class CommandsService extends Service<CommandsConfigInput> {
+    static inject: string[];
+    readonly config: CommandsConfig;
+    /** This instance's identity in start rows: per root, so a root reopened in one process owns none of its predecessor's commands. */
+    readonly instanceId: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly commands;
+    private readonly starting;
+    /** End rows and exit notices on their way to the journal; shutdown waits for them while the journal is still open. */
+    private readonly writes;
+    /** Every launch, foreground or background, from its preparation until its command and report settled. */
+    private readonly operations;
+    private readonly lifetime;
+    constructor(ctx: Context, config: CommandsConfigInput);
+    /**
+     * 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
+     * the command, and shutdown stops it too.
+     */
+    launch(request: {
+        command: string;
+        workdir: string;
+        threadId: string;
+        threadCwd: string;
+    }, options: {
+        signal: AbortSignal;
+        timeoutMs?: number;
+        beforeRelease?: (pgid: number, launch: LaunchProvenance | null) => Promise<void>;
+    }): Promise<Launched>;
+    /**
+     * Starts a background command for `threadId`, or finds the one this dispatch already started:
+     * a call re-dispatched in the same process keeps its id and gets its command back.
+     */
+    start(request: StartRequest): Promise<{
+        command: BackgroundCommand;
+        reused: boolean;
+    }>;
+    /** `threadId`'s command `id`, live or recorded, or a message saying why there is none to act on. */
+    lookup(threadId: string, id: string): CommandLookup;
+    /**
+     * One thread's background commands, oldest first: the ones this process runs or ran, and the
+     * recorded ones whose end no process vouched for.
+     */
+    list(filter: {
+        threadId: string;
+    }): CommandInfo[];
+    /**
+     * The background commands this process holds for `threadId`, by id: `starting` while its launch
+     * is under way, its start row perhaps not yet written; `running`; `ended` once it exited, its end
+     * row written or on its way. What {@link commandWork} reads of this process.
+     */
+    live(threadId: string): ReadonlyMap<string, 'starting' | 'running' | 'ended'>;
+    /**
+     * Stops command `id` this process runs, within the bound of `sys/spawn`, recording why; resolves
+     * with its final state once it has ended. A tool looks the command up first, for its caller's thread.
+     */
+    stop(id: string, reason?: string): Promise<CommandInfo>;
+    /** Stops every running background command, or one thread's, in parallel. */
+    stopAll(filter?: {
+        threadId?: string;
+    }, reason?: string): Promise<void>;
+    /**
+     * Blocks until `command` exits, until the wait elapses or `signal` aborts, or with
+     * `until: 'output'`, until half a second after new output first arrives, so a burst of lines
+     * comes back as one result. Unread output already waiting ends an `output` wait at once.
+     */
+    wait(command: BackgroundCommand, options: {
+        waitMs: number;
+        until: 'output' | 'exit';
+        signal: AbortSignal;
+    }): Promise<void>;
+    private spawn;
+    private forThread;
+    /**
+     * The recorded commands of `threadId` another instance started and whose end no process vouched
+     * for. This instance's own records are never listed from the journal: one it runs is live, and
+     * one it does not run has an end row, written when it ended or when its start was never released.
+     */
+    private orphans;
+    private recorded;
+    /**
+     * What the rows let this process say. An end row whose stop succeeded is the answer; anything
+     * else was started by a previous process and is not owned here, and nothing is claimed about its
+     * process group.
+     */
+    private recordedStatus;
+    /**
+     * Writes the end row; a journal that refuses is reported, never thrown into the command's settling.
+     * The write is tracked until it lands, so shutdown can wait for it.
+     */
+    private recordEnd;
+    /**
+     * Tracks a write until it lands, so shutdown can wait for it; a journal that refuses is reported,
+     * never thrown into the command's settling.
+     */
+    private track;
+    /**
+     * Tells the thread that started a notifying command that it exited, with one `send` whose group
+     * carries the end row: a developer-role notice under `cmdexit_<id>`, a reactive cause that runs an
+     * idle thread and releases none of its holds. It joins the next model step, after the start's own
+     * result: a run's that holds the thread, or the turn that resumes the thread's parked calls. A send
+     * the thread refuses writes nothing, and the command is listed as an orphan at the next start, as
+     * one whose end row failed is.
+     */
+    private notifyEnd;
+    /**
+     * Records the end, through the exit notice for a notifying command that exited on its own, then
+     * keeps a bounded number of each thread's ended commands; a dropped id answers from its record.
+     */
+    private onEnd;
+    /**
+     * Root disposal: no launch is admitted, every group stops in parallel
+     * within the same bound as one stop, foreground and background alike, and launches still being
+     * prepared are abandoned. Starts still at their gate settle first, so each either lands and is
+     * stopped or is recorded as never released, and nothing ends after the journal has closed.
+     * Idempotent.
+     */
+    private shutdown;
+    private markShutdown;
+}
+/**
+ * The last `maxChars` characters of a command's log, read from `paths` newest segment first, for a
+ * command this process cannot read live; with the bytes left out before them and the segments that
+ * were read. `null` when no segment exists.
+ */
+export declare function readLogTail(paths: readonly string[], maxChars: number): Promise<{
+    text: string;
+    omittedBytes: number;
+    read: string[];
+} | null>;

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

@@ -0,0 +1,25 @@
+import { type SpawnEnvironment } from '../../sys/spawn.js';
+/** The tools whose `command` runs through `/bin/sh -c`. */
+export declare const SHELL_TOOLS: Set<string>;
+/**
+ * What `/bin/sh` is here, read once at mount, in the environment commands run with: see
+ * {@link shellDescription}.
+ */
+export declare function describeShell(environment: SpawnEnvironment): Promise<string>;
+/**
+ * The `$BASH_VERSION` the probe printed on its marked line; `null` when it failed, printed no such
+ * line, or the shell is not bash.
+ */
+export declare function bashVersionOf(probe: {
+    exitCode: number | null;
+    output: string;
+}): string | null;
+/**
+ * The prompt line for a `/bin/sh` resolving to `target`: the program it links to, such as dash, and
+ * bash's version when it is bash, as macOS's `/bin/sh` is without being a link. Dash reports no
+ * version.
+ */
+export declare function shellDescription({ target, bashVersion }: {
+    target: string;
+    bashVersion: string | null;
+}): string;

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

@@ -0,0 +1,91 @@
+import { type ContentPart } from '../../llm/index.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
+ * are exact and no model-written text speaks with more than a note's authority.
+ */
+/** A message before a span, named in the instruction by its role and the start of its text. */
+export type Boundary = {
+    readonly role: string;
+    readonly text: string;
+};
+/**
+ * The instruction after the surface prefix. It names the span by the message just before it, the
+ * last of the pinned opening or the direct developer input the segment follows, by its role and a
+ * bounded quote, since nothing can be inserted into the prefix without breaking it; with no such
+ * message the whole prefix is the span. It asks for the state as of the cut, since the summarizer
+ * never sees the retained tail, in the checkpoint's structured sections.
+ */
+export declare function renderInstruction(options: {
+    readonly boundary: Boundary | null;
+    readonly quoteChars: number;
+    /** Whether the span holds an earlier checkpoint, which the new one merges rather than copies. */
+    readonly merges: boolean;
+    readonly cap: number;
+    /** What a person asked the summary to pay particular attention to. */
+    readonly focus: string | null;
+}): string;
+/**
+ * A bounded quote of a message's text, to name it in the instruction: whitespace, control
+ * characters and lone surrogates, which the quoting would write as six characters, flattened to
+ * single spaces, cut at `limit` characters with an ellipsis, and quoted as
+ * a JSON string. The quoting at most doubles a character, so `2 * limit + 3` characters bound it.
+ */
+export declare const quote: (text: string, limit: number) => string;
+/** The person's latest input as a checkpoint copies it: whole, or its beginning and where to find the rest. */
+export type CopiedInput = {
+    readonly text: string;
+    /** Its history number, which names it in full. */
+    readonly number: number;
+    /** Its whole length in characters, when the copy is cut. */
+    readonly cutFrom: number | null;
+    /** Parts that are not text, which are not copied. */
+    readonly attachments: number;
+};
+/**
+ * Copies an input from its original row: whole up to `limit` characters, beyond that its first
+ * half and its history number. Never from a checkpoint's text, so two compactions hand the model
+ * the same words rather than a summary of a summary.
+ */
+export declare function copyInput(content: readonly ContentPart[], number: number, limit: number): CopiedInput;
+/** The messages a checkpoint stands for, by history number, through every earlier replacement. */
+export type ReplacedRange = {
+    readonly first: number;
+    readonly last: number;
+    readonly count: number;
+};
+/**
+ * The checkpoint: a code-written preamble, the model's summary, the person's latest input when
+ * the span held it, and a code-written footer naming the replaced messages. One `user` message
+ * framed as historical notes that introduce no instructions: a summary is model-written and may be
+ * wrong, so it must not speak as the harness.
+ *
+ * `recall` is the footer's line on how to read the replaced messages back (`renderRecall`, owned by the recall plugin),
+ * which a strategy passes only when the thread's agent has both of the recall plugin's tools granted, and
+ * `null` otherwise.
+ */
+export declare function renderCheckpoint(parts: {
+    readonly summary: string;
+    readonly copied: CopiedInput | null;
+    readonly replaced: ReplacedRange;
+    readonly recall: string | null;
+}): string;
+/** The copied input as the checkpoint carries it, marked as the person's own words. */
+export declare function renderCopiedInput(copied: CopiedInput): string;
+/** Text the checkpoint did not write, kept from ending one of its sections early or opening another. */
+export declare const neutralize: (text: string) => string;
+/**
+ * The checkpoint with an empty summary and the widest footer, two different seven-digit numbers,
+ * and the longest recall line whether or not the agent has the recall tools: what its code-written
+ * framing comes to at most, for budgets.
+ */
+export declare const EMPTY_CHECKPOINT: string;
+/**
+ * The longest instruction a summary call may end on, for budgets: the boundary quoted at its limit
+ * and truncated, of characters the quoting doubles, asking to merge an earlier checkpoint.
+ */
+export declare const widestInstruction: (options: {
+    readonly quoteChars: number;
+    readonly cap: number;
+    readonly focus: string | null;
+}) => string;

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

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+/**
+ * The route the summary call runs on, merged over the turn's route as a turn's selection is over
+ * the thread's: the turn's provider and model unless they are named. Naming another provider or
+ * model is the host's choice and depends on what it has registered, so none is assumed; it forgoes
+ * the cached prefix a summary call on the turn's model reads.
+ *
+ * `thinkingEffort` is a ceiling, `low` by default: the call runs at the lower of it and the turn's
+ * effort, so a turn at `none` summarizes at `none`, with no reasoning allowance, and a turn whose
+ * effort is left to its provider leaves the summary's there too. Effort sits outside the cached
+ * prefix, and a long span at `high` costs more than any allowance.
+ */
+export declare const SummarizerSchema: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    thinkingEffort: z.ZodDefault<z.ZodEnum<{
+        low: "low";
+        high: "high";
+        none: "none";
+        medium: "medium";
+        max: "max";
+    }>>;
+}, z.core.$strict>;
+/**
+ * The `summarize` strategy's budgets: it replaces a span with a checkpoint a summary call wrote.
+ * Fractions are of the route's declared window; token counts are tokens.
+ */
+export declare const SummarizeStrategySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"summarize">;
+    target: z.ZodDefault<z.ZodNumber>;
+    tail: z.ZodDefault<z.ZodNumber>;
+    opening: z.ZodDefault<z.ZodNumber>;
+    summaryCap: z.ZodDefault<z.ZodNumber>;
+    summaryFloor: z.ZodDefault<z.ZodNumber>;
+    reasoningAllowance: z.ZodDefault<z.ZodNumber>;
+    replyReserve: z.ZodDefault<z.ZodNumber>;
+    checkpointRatio: z.ZodDefault<z.ZodNumber>;
+    copiedInputChars: z.ZodDefault<z.ZodNumber>;
+    boundaryQuoteChars: z.ZodDefault<z.ZodNumber>;
+    breaker: z.ZodDefault<z.ZodNumber>;
+    withoutWindow: z.ZodDefault<z.ZodObject<{
+        tailTokens: z.ZodDefault<z.ZodNumber>;
+        openingTokens: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    summarizer: z.ZodDefault<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        thinkingEffort: z.ZodDefault<z.ZodEnum<{
+            low: "low";
+            high: "high";
+            none: "none";
+            medium: "medium";
+            max: "max";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * The `prune` strategy's settings: it rewrites old tool results to a one-line stand-in and calls
+ * no model.
+ */
+export declare const PruneStrategySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"prune">;
+    keepRecent: z.ZodDefault<z.ZodNumber>;
+    minTokens: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * The compaction plugin's configuration, all of it JSON so a preset can record it: when pressure
+ * acts, and the strategy, `summarize` with its defaults unless another is chosen. Whose threads is
+ * where it is placed: installed on one, or mounted on the root for an agent selector.
+ */
+export declare const CompactionConfigSchema: z.ZodObject<{
+    threshold: z.ZodDefault<z.ZodNumber>;
+    strategy: z.ZodPrefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"summarize">;
+        target: z.ZodDefault<z.ZodNumber>;
+        tail: z.ZodDefault<z.ZodNumber>;
+        opening: z.ZodDefault<z.ZodNumber>;
+        summaryCap: z.ZodDefault<z.ZodNumber>;
+        summaryFloor: z.ZodDefault<z.ZodNumber>;
+        reasoningAllowance: z.ZodDefault<z.ZodNumber>;
+        replyReserve: z.ZodDefault<z.ZodNumber>;
+        checkpointRatio: z.ZodDefault<z.ZodNumber>;
+        copiedInputChars: z.ZodDefault<z.ZodNumber>;
+        boundaryQuoteChars: z.ZodDefault<z.ZodNumber>;
+        breaker: z.ZodDefault<z.ZodNumber>;
+        withoutWindow: z.ZodDefault<z.ZodObject<{
+            tailTokens: z.ZodDefault<z.ZodNumber>;
+            openingTokens: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        summarizer: z.ZodDefault<z.ZodObject<{
+            provider: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            thinkingEffort: z.ZodDefault<z.ZodEnum<{
+                low: "low";
+                high: "high";
+                none: "none";
+                medium: "medium";
+                max: "max";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"prune">;
+        keepRecent: z.ZodDefault<z.ZodNumber>;
+        minTokens: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>;
+/** The configuration as a host writes it: everything optional with its default. */
+export type CompactionConfig = z.input<typeof CompactionConfigSchema>;
+/** The configuration with every default applied, as the preset reads it. */
+export type ResolvedCompactionConfig = z.output<typeof CompactionConfigSchema>;
+/** The `summarize` branch with its defaults applied. */
+export type SummarizeStrategyConfig = z.output<typeof SummarizeStrategySchema>;
+/** The `prune` branch with its defaults applied. */
+export type PruneStrategyConfig = z.output<typeof PruneStrategySchema>;
+/**
+ * What a strategy's per-thread plugin is mounted with: its thread, the thread's agent, and the
+ * configuration's shared `threshold` beside the strategy's own branch, as the configuration has them.
+ */
+export type StrategyOptions<Strategy> = {
+    readonly threadId: string;
+    readonly agentName: string;
+    readonly threshold: number;
+    readonly strategy: 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<{
+    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>;

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

@@ -0,0 +1,29 @@
+import type { ContentPart, ConversationMessage, PromptBlock, ToolSpec } from '../../llm/index.js';
+import type { DeepReadonly } from '../../util/json.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
+ * Harness prices content. It is an estimate and never a measurement: a strategy measures with the
+ * usage a provider reported where it has one, estimates what came since, and calibrates the
+ * estimate when a provider refuses a request as too long. Images, CJK text and other content whose
+ * characters say little about its tokens are exactly what that calibration exists for.
+ */
+export declare const CHARS_PER_TOKEN = 4;
+/** Tokens for `text`. */
+export declare const estimateText: (text: string) => number;
+/** Tokens for a content list, each part with its framing. */
+export declare function estimateContent(parts: readonly ContentPart[]): number;
+/**
+ * Tokens for one message as a request carries it: its content, the reasoning it replays as text,
+ * and the tool calls it asked for. Provider state replayed in its place is not priced, since it is
+ * opaque; a usage anchor measures it.
+ */
+export declare function estimateMessage(message: DeepReadonly<ConversationMessage>): number;
+/**
+ * Tokens for everything a request sends ahead of its messages: the system prompt, guidance blocks
+ * included, and the tool definitions it advertises.
+ */
+export declare function estimateHead(head: {
+    readonly systemPrompt: readonly PromptBlock[];
+    readonly tools: readonly ToolSpec[];
+}): number;

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

@@ -0,0 +1,2 @@
+export type { CompactionConfig, CompactRequestOptions, PruneStrategyConfig, SummarizeStrategyConfig } from './config.js';
+export { compaction } from './preset.js';