@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/compositions/codex.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { type SpawnEnvironmentPolicy } from '../sys/environment.js';
+/**
+ * Codex's policy: variables that look like credentials are dropped, the locale is fixed to UTF-8,
+ * and the {@link NON_INTERACTIVE_ENVIRONMENT} overrides are set.
+ */
+export declare const CODEX_ENVIRONMENT_POLICY: SpawnEnvironmentPolicy;
+/** Tools that create or modify files. */
+export declare const WRITE_TOOLS: readonly ["edit_files"];
+export declare const CodexPresetConfigSchema: z.ZodObject<{
+    explore: z.ZodPrefault<z.ZodObject<{
+        web: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    agentsMd: z.ZodObject<{
+        fileNames: z.ZodArray<z.ZodString>;
+        maxBytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** The explorer's role id, which is also the agent its children run on. */
+export declare const EXPLORE_ROLE_ID = "codex.explore";
+/** The general sub-agent's role id, which `delegate` starts. */
+export declare const GENERAL_ROLE_ID = "codex.general";
+/** The reviewer's role id, which `review` starts. */
+export declare const REVIEW_ROLE_ID = "codex.review";
+/**
+ * Equips a thread's agent for autonomous coding: the workspace tools that read and write, shell
+ * commands, web fetch and search, skills, questions to the user, the route notice, the date and
+ * branch at the start of each turn (`dateAndBranch`, for the agents it equips and not handed down),
+ * one `subAgents` with four endpoints, an `explore` sub-agent that only reads, a `delegate`
+ * sub-agent with a fresh context for a self-contained task, a `fork` of the caller, and a `review`
+ * sub-agent with the general sub-agent's tools and a reviewer's persona (`workerTools`),
+ * `message_agent`, `list_agents`, `read_agent` and `stop_agent` to continue, list, read and stop any
+ * of them, and a coding prompt that replaces the agent's base prompt. A sub-agent's role is frozen
+ * on it, so a reviewer continued with `message_agent` stays a reviewer; nothing but its prompt keeps
+ * it from repairing, and the host's permission policy decides what its calls may do.
+ * It grants the file and web tools, the command tools, `skill` and the `delegations` tools rather than
+ * registering them: it relies on the host registering `fileTools`, `webTools`, `commands`, `skills` and
+ * `delegations` on the root, where its endpoints also find the tools they grant their children, and
+ * mounting the `ask` service there, which `ask_question` asks through and refuses to mount without.
+ * `skills` searches the host's skill roots, which a configuration may not record, so codex refuses
+ * to mount without it. The `subAgents` codex mounts refuses to mount without `delegations`, which
+ * owns every delegation and registers its tools.
+ *
+ * It equips the agent of the thread it is placed on: installed there, mounted from the setup of a
+ * host preset placed there, or chosen by a root mount for an agent selector.
+ *
+ * Workspace instructions (`agentsMd`): it tells its thread. Installed, its own installation or the
+ * host preset's that mounts it, it also hands the `agents-md` preset down with the same settings, so
+ * every sub-agent the thread starts, the explorer included, and their children in turn, are told
+ * too; so it refuses to mount unless `agentsMdPreset` is registered. Selected, it hands nothing
+ * down, since a selection is process policy rather than the thread's recorded choice: a child is
+ * then told only if a root selector reaches its agent.
+ *
+ * Safe per thread: tools, grants, prompt sections and step listeners, all in the thread's own
+ * layer. A thread records its prompt when it first runs, so an installation applied later adds its
+ * tools but not its prompt sections.
+ */
+export declare const codexPreset: import("../services/presets/definition.js").Preset<z.ZodObject<{
+    explore: z.ZodPrefault<z.ZodObject<{
+        web: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    agentsMd: z.ZodObject<{
+        fileNames: z.ZodArray<z.ZodString>;
+        maxBytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>>;

package/dist/compositions/codexPrompts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The prompt text `codexPreset` contributes, its sub-agents' included, adapted from Codex CLI's base
+ * instructions and its model templates. Each block is exported so a consumer can reuse one in an
+ * agent of its own. None assumes how an answer is drawn: a host whose renderer has rules of its own,
+ * such as which diagrams or images it shows, contributes a section saying so.
+ */
+export declare const CODE_ROLE_PROMPT = "You are a coding agent working in the user's workspace. You and the user share its files: with the tools you are given, you read, search and change them and run commands there. Your job is to carry the user's task through to a result they can review.";
+export declare const AUTONOMY_PROMPT = "- Carry the task through to the end within the turn: understand it, make the change, validate it, and report. Do not stop at analysis, a proposal or a half-finished fix.\n- Unless the user asks a question, asks for a plan or a review, or is brainstorming, assume they want the change made, and make it rather than describe it.\n- When you hit a blocker, try to work through it yourself first. Ask the user, with ask_question, only when the answer changes what you would do and you cannot find it out yourself.\n- Do not guess or make up an answer: read the code, run the command, look it up.\n- Messages may arrive while you work. When they conflict, the newest one steers; otherwise honour every request since your last answer, and make sure your final answer responds to the newest.";
+export declare const PREAMBLES_PROMPT = "Before a group of related tool calls, write one short line saying what you are about to do, and after the first, how it follows from what you found; for example \"The loader is in src/config.ts; now checking its callers.\" Group related calls under one line instead of narrating each, and write none before a trivial read. Before a large edit, say what you are changing.";
+export declare const CODEBASE_PROMPT = "- Read the code you are about to change, and let it show you how to change it: follow the repository's existing patterns, helpers and style.\n- Fix the problem at its root cause rather than patching the symptom, and keep the solution as simple as the problem allows. Add an abstraction only when it removes real complexity.\n- Follow the AGENTS.md files you are told for the files you touch. Each governs its directory's tree and the deeper one wins on a conflict; the user's direct instructions beat any of them. Working below your working directory, look for AGENTS.md there too.\n- Keep the change to what the task needs. Do not fix unrelated bugs or failing tests; mention them in your final answer.\n- Update the documentation your change makes wrong.\n- Default to ASCII in files, and add a comment only where the code does not explain itself.\n- Never add copyright or licence headers unless asked. Do not commit or create branches unless asked.";
+export declare const EDITING_PROMPT = "- Make every change to a file with edit_files: creating, updating, moving or deleting it. Never write a file through a command, such as a shell heredoc, `echo >`, `sed -i` or a script; running the project's own formatter or code generator is fine.\n- Read the lines you change before editing them: an edit's old text must match the file as it is now.\n- edit_files answers with the diff it applied. Trust it, and do not re-read the file to check.\n- If an edit is interrupted, or applies only some of its files, re-read the files it named before editing them again.";
+export declare const DIRTY_WORKTREE_PROMPT = "The worktree may hold changes you did not make. Assume they are the user's, and never revert them unless asked.\n- Leave changes unrelated to your task alone.\n- In files you are working on, read the changes carefully and work with them.\n- Never run `git reset --hard`, `git checkout --`, `git restore`, `git clean` or anything else that discards changes unless the user clearly asked for that operation; when the request is ambiguous, ask first.\n- If those changes make your task impossible, ask the user how to proceed.";
+export declare const VALIDATION_PROMPT = "- When the project can be built or tested, use that to check your work. Start with the tests closest to what you changed, then widen as you gain confidence.\n- Let coverage scale with risk: focused for a narrow change, broader when the change touches shared behaviour, contracts between modules, or what users do.\n- Add a test where the codebase has an obvious place for one. Do not add a test suite or a formatter to a repository that has none, and do not write tests that only mirror the implementation.\n- Run the project's formatter and linter on the files you changed when it has them.\n- A failure your change did not cause is not yours to fix: mention it.";
+/** The delegation section: when to hand work to a sub-agent, and how. */
+export declare const DELEGATION_PROMPT = "- Independent tool calls can run in parallel: make every call that does not need another's result in the same response. When a call depends on an earlier one's output, wait for that result first.\n- Hand work to a sub-agent when you do not need to see its steps, so your conversation keeps only its outcome:\n  - explore: find and understand things in the workspace, such as where something is handled, how a module works or what a change would affect. It only reads.\n  - delegate: a self-contained task that needs nothing from this conversation but the task you write, including one that changes files or runs commands, such as updating every call site of a function and making the tests pass, or finding out why a command fails and fixing it.\n  - fork: a task of several steps that needs your context: answering a question by experiment, working out why something fails, checking whether an approach works.\n  - review: a second reading of a change, or of any code, when the user asks for one or a change is large or subtle enough that one helps; never as a routine step. Its findings are evidence: weigh each against the code before acting on it. To get them fixed, delegate the findings with their evidence. Check the repository's status before asking for a review of uncommitted work: an empty change still starts a reviewer.\n- Work directly when one or two calls will do, when you need the raw output yourself (the exact lines you are about to edit, command output you must reason over), when the next step waits on a decision, or when the answer is already in the conversation.\n- Give independent parts separate calls in one response, so they run concurrently. Write each task as an outcome: what to find out or do, and what to return, such as \"the function that validates tokens, with its file and line\" rather than \"look at the auth code\". Explore, delegate and review see only the task you write; a fork sees your conversation too. Either way, name the target (for a review, \"the uncommitted changes\", \"the current work against main\", \"commit abc123\" or the code to read), the outcome you expect, the constraints, and which files you or other sub-agents are changing and which commands share outputs, such as test discovery, a build directory or a server port.\n- Start a review only after the work it reviews has settled, in a later response than the calls that make that work: a waiting call does not stop the others in its response.\n- In a forked task, do the work yourself rather than forking again.";
+export declare const LONG_WORK_PROMPT = "A long task can outgrow your context. The conversation may then be compacted: a checkpoint stands in for the messages it condensed. Compaction does not end the task. Continue from the checkpoint without restarting or redoing finished work, and keep the original objective together with every correction the user made since.";
+/** Added to {@link LONG_WORK_PROMPT} when the agent may call the recall tools. */
+export declare const HISTORY_RECALL_PROMPT = "When you need the exact text of something condensed, such as the user's wording or a command's output, read it back with history_read or find it with history_search rather than reconstructing it.";
+export declare const SAFETY_PROMPT = "- Your file tools and commands work under the confinement the application sets. Do not go looking through the rest of the machine, such as other projects or the home directory, unless the task needs it.\n- Avoid destructive or irreversible commands, such as deleting what you did not create, force-pushing or dropping data, unless the user asked for them.\n- Do not push, publish, deploy or send anything to others unless asked.\n- Do not search for, print or copy out secrets such as credentials, API keys and tokens.";
+export declare const AMBITION_PRECISION_PROMPT = "- For a task with no prior context, where the user is starting something new, be ambitious and show creativity in the implementation.\n- In an existing codebase, do exactly what the user asks with surgical precision. Treat the surrounding code with respect and do not overstep, for example by renaming files or variables unnecessarily, while still being proactive enough to finish the task well.\n- Use judicious initiative to choose the right level of detail and complexity for the user's needs: high-value, creative touches when the scope is vague; surgical, targeted work when it is tightly specified; no gold-plating either way.";
+export declare const FINAL_ANSWER_PROMPT = "- Lead with the outcome, then give what the user needs to trust it and act on it, like a concise teammate handing off work.\n- Size the answer by the change: a sentence or two for a small fix, a short walkthrough grouped by theme for a large one, a plain conversational reply to a casual question. Even a large one keeps to the points that matter, well under fifty lines.\n- Say what you ran to validate the work, and what you did not run and why.\n- Point to code as `path:line`, with the path relative to the working directory and a single line rather than a range.\n- Do not paste before-and-after code or the contents of files you wrote: the user has the files. Never ask them to save or copy anything.\n- Mention the problems you noticed but left alone, and anything you could not do.\n- When there is an obvious next step, such as running the wider test suite, committing, or building the next piece, offer it as a short question rather than doing it unasked.";
+export declare const COMMUNICATION_GUIDANCE_PROMPT = "- Write in English unless the user asks for another language.\n- Be direct and concise, and state the assumptions you made. Leave out flattery, filler and needless apologies.\n- Use plain characters: no emoji unless asked, and no look-alike or invisible Unicode, such as an en dash for a hyphen.";
+/** Markdown conventions any renderer draws; what a particular one adds is its host's to say. */
+export declare const FORMATTING_PROMPT = "- Answer in Markdown, with only as much structure as helps: short paragraphs by default, flat lists for parallel items, and a heading only when a long answer has distinct parts.\n- Put code, commands and multi-line output in fenced code blocks labelled with their language.\n- Wrap file paths, commands, environment variables and code identifiers in backticks.";
+/**
+ * The explorer's base prompt, naming the search tools only when `has` says they are registered: they
+ * are provided only where the host has `rg`.
+ */
+export declare const exploreRolePrompt: (has: (tool: string) => boolean) => string;
+export declare const EXPLORE_TOOL_DESCRIPTION = "Sub-agent that explores the workspace without changing it: codebase exploration, file discovery and code understanding. It reports its findings.";
+export declare const FORK_TOOL_DESCRIPTION = "Fork yourself to execute one sub-task in isolation. The forked thread gets a clone of your current conversation context, executes the task independently, and its result is returned to you. Use this when you want to 'clone yourself' to do a sub-task without polluting your main conversation thread. Call this tool once per task; several calls in one response run concurrently.";
+export declare const FORKING_PROMPT = "Sub-agents inherit your permissions and share your working directory. Give sub-agents that run at the same time disjoint files to write, or let only one of them write; disjoint files still share test discovery, build output and ports, so do not run tests or builds in two of them at once.";
+/** The general sub-agent's opening: one delegated task, and no view of the caller's conversation. */
+export declare const GENERAL_ROLE_OPENING = "You are a sub-agent: another agent handed you one task, which you carry out in the user's workspace with the tools you are given, reading, searching and changing its files and running commands there. You do not see the conversation that led to the task: the task is all you know of it. Your answer goes back to the agent that asked, not to the user.";
+/** What every sub-agent codex starts with tools follows, since it answers an agent and cannot ask the user. */
+export declare const SUB_AGENT_RULES_PROMPT = "- Where these instructions say to ask the user, you cannot: stop there, and put the question in your answer, with what you found and what each answer would change.\n- Before you answer, wait for every background command whose result you rely on, and stop every background command you started.";
+/** How the general sub-agent answers: the whole of what its caller gets back. */
+export declare const SUB_AGENT_ANSWER_PROMPT = "Your answer is all the agent that asked gets back, so make it complete on its own:\n- Lead with the outcome: what you did, or what you found.\n- Point to code as `path:line`, with the path relative to the working directory.\n- Say what you ran to check it, each command exactly, and what it showed.\n- Say what is left undone, what you could not do, and what you are unsure of.";
+/** The reviewer's opening, adapted from Codex CLI's review rubric (\`prompts/templates/review/rubric.md\`). */
+export declare const REVIEW_ROLE_OPENING = "You are a code review sub-agent: another agent asked you for a second reading of code in the user's workspace, a change or code as it stands, and you report the problems you find, with their evidence. You do not see the conversation that led to the task: the task names what to review and anything to focus on. Your answer goes back to the agent that asked, not to the user.";
+/** What the reviewer reads, and how it may gather evidence without repairing anything. */
+export declare const REVIEW_EVIDENCE_PROMPT = "- Read the change with git through run_command: a diff of the uncommitted changes, of the current work against a branch's merge base, or of one commit, with the repository's status and log. Note which commits you compared. Read the code around each change, and the code that depends on it, as far as you need to judge it. When the task names code rather than a change, review that code as it stands.\n- Review and report; do not fix. Run a command only when a finding needs the evidence: an existing test, the type checker, a linter, or a small reproduction. Prefer existing tests.\n- When a check needs a file inside the repository, create a new, uniquely named file with edit_files. Never change a file that existed before you started, the user's untracked files included.\n- Clean up what you created. Just before deleting a temporary file, read it again, and delete it only if it is still exactly what you wrote. Never restore the workspace wholesale, such as with `git checkout`, `git restore`, `git stash` or `git clean`.\n- Running tests writes caches and build output, which is fine: what you keep intact is the user's work.\n- When the target is a commit, or anything but the current work, your commands run on the checkout, not on the reviewed revision. Say which HEAD and which local changes they ran on, and do not claim that a check passing there shows the reviewed revision passes.\n- If files your findings rely on change while you review, check those findings again, or mark them uncertain.";
+/** What the reviewer flags and how it reports, adapted from Codex CLI's review rubric. */
+export declare const REVIEW_RUBRIC_PROMPT = "Flag a problem only when all of these hold:\n- It meaningfully affects the correctness, performance, security or maintainability of the code.\n- It is discrete and actionable: one issue, not a remark about the codebase in general or several issues together.\n- When the task names a change, the change introduced it: problems that were there before are not flagged. When it names code, the problem is in that code.\n- You can show it from the code or from what you ran. Speculating that something may break elsewhere is not enough: name the code that is affected. It must not rest on assumptions about the codebase or the author's intent that you have not stated.\n- It is clearly not a deliberate choice, and the author would fix it if they knew.\n- Fixing it does not demand more rigour than the rest of the codebase shows.\n\nIgnore style, formatting, naming and typos unless they hide a bug or break a rule the repository's AGENTS.md files state. When a rule supports a finding, cite the AGENTS.md file and line it comes from.\n\nReport every finding the author would want to fix, not only the first; when nothing clearly qualifies, report none. For each finding:\n- A short title tagged with its priority: [P0] blocks a release or major use, whatever the inputs; [P1] urgent, for the next cycle; [P2] normal, to fix eventually; [P3] low, nice to have.\n- Its location as `path:line` in the reviewed code, with the path relative to the repository, keeping the range as short as possible.\n- One short paragraph saying why it is a problem and the inputs, scenarios or environments it needs, so its severity is clear, and the evidence: what you read or ran. Claim no more severity than it has, quote no more than three lines of code, and keep the tone matter-of-fact, with no praise.\n\nWhen the task asks for a design assessment, alternatives or improvements, give them after the findings, under a heading of their own, apart from the problems you showed. When it asks for a severity scale or an output format, follow it instead of these.\n\nEnd with:\n- the scope you reviewed, and for a git target the commits you compared;\n- the checks you ran, each command exactly, with its result;\n- every experiment, what it left behind, and where its reproduction is kept, with how to run it;\n- the limits of the review: what you did not read or could not check.\nThen a one-line verdict: whether the reviewed code is correct, meaning existing code and tests will not break and it has no blocking problem. Non-blocking issues such as style do not count against it. \"No qualifying findings\" is not a guarantee of correctness: when you found none, say so plainly, with what you covered.\n\nAnswer in plain text, not JSON. The task may narrow what to look at, and the repository's AGENTS.md files may add rules; both take precedence over these guidelines.";
+/**
+ * The general sub-agent's base prompt: one delegated task, carried out with the workspace, command,
+ * web and skill tools, by codex's own working rules, answered to the agent that asked.
+ */
+export declare const GENERAL_ROLE_PROMPT: string;
+/**
+ * The reviewer's base prompt: the same tools as the general sub-agent, used to gather evidence, never
+ * to repair; none of the blocks that tell an agent to fix, document or add tests.
+ */
+export declare const REVIEW_ROLE_PROMPT: string;
+export declare const DELEGATE_TOOL_DESCRIPTION = "Sub-agent that carries out one self-contained task in the workspace with a fresh context: it reads, changes files, runs commands, and reports what it did and found. It sees only the task you write, not this conversation, so state the target, the outcome you expect and any constraints.";
+export declare const REVIEW_TOOL_DESCRIPTION = "Sub-agent that reviews code in the workspace with a fresh context: a change (the uncommitted changes, the current work against a branch such as main, or one commit) or code as it stands. It may run tests and reproductions to gather evidence, changes nothing of yours, and reports the problems it can show, each tagged [P0] to [P3] at a file and line. Name the target and any focus in the task.";

package/dist/context.d.ts

@@ -0,0 +1,109 @@
+import type { Scoped } from '@leuduan/cordis';
+import type { JournalCommitError, PluginJournal } from './journal/index.js';
+import type { ModelRequestDraft, ModelStep, SentRequest, StopVerdict, ToolAuthorizationRequest, ToolPolicyDecision, ToolInvocation, ToolOutcome, TurnStop } from './loop/index.js';
+import type { StreamingLLMResponse } from './llm/client.js';
+import type { AgentsService } from './services/agents.js';
+import type { LlmService } from './services/llm.js';
+import type { ConfinementOperation, ConfinementService } from './services/confinement/service.js';
+import type { PromptsService } from './services/prompts.js';
+import type { PresetsService } from './services/presets/installations.js';
+import type { Threads } from './services/threads/index.js';
+import type { ToolsService } from './services/tools.js';
+import type { Thread } from './services/threads/index.js';
+declare module './loop/tool.js' {
+    interface InvocationContext {
+        /**
+         * The call's confinement operation: its file access (`files`) and the launches of any process it
+         * starts, under one snapshot taken on first use. Opened for the call and ended with it, so a
+         * reference that outlives the call is dead.
+         */
+        readonly operation: ConfinementOperation;
+    }
+}
+declare module '@leuduan/cordis' {
+    interface Context {
+        /** The journal: the one durable state, and the folds over it; a plugin appends its own `ext` rows. */
+        journal: PluginJournal;
+        /** Global and scope-layered tool registry and grants. */
+        tools: ToolsService;
+        /** Agent-definition registry. */
+        agents: AgentsService;
+        /** Model-provider registry and client construction. */
+        llm: LlmService;
+        /** Prompt contributions, rendered when a thread first runs, and recorded on it. */
+        prompts: PromptsService;
+        /** Starting and finding threads, and what happens to them as a set; one thread is driven through its `Thread`. */
+        threads: Threads;
+        /** Presets a thread can install, their validation, hand-downs and restoration. */
+        presets: PresetsService;
+        /** How model-driven processes launch: plain, or through the one handler a host registers. */
+        confinement: ConfinementService;
+    }
+    interface Events {
+        /**
+         * Configure a live activation through thread.ctx. Independent plugins compose here.
+         * @mode parallel — all listeners settle before readiness; any failure prevents execution.
+         * The signal belongs to the activation, not an individual turn.
+         */
+        'lagent/thread/activate'(this: Scoped, thread: Thread, signal: AbortSignal): void | Promise<void>;
+        /**
+         * The store failed to commit a group after the folds took it. The journal refuses every later
+         * write and reads show what the store holds, and the threads service has already closed
+         * execution admission and stopped every loop. The host must exit, and reopen to continue.
+         * @mode parallel — fired once, on the root; every listener runs, whichever throws.
+         */
+        'lagent/journal/revoked'(error: JournalCommitError): void;
+        /**
+         * Around every tool invocation. The terminal runs `invocation.tool.invoke(...)`.
+         * @mode waterfall
+         */
+        'lagent/tool/execute'(this: Scoped, invocation: ToolInvocation, next: () => Promise<ToolOutcome>): Promise<ToolOutcome>;
+        /**
+         * A model step is about to record its input. Listeners may `step.contribute()` messages, which
+         * enter the conversation ahead of the step's claimed input, in the same atomic journal group, by
+         * ascending `rank` (default 0) and then listener order; an identical contribution, source and
+         * message alike, is recorded once, and at two different ranks it throws.
+         * Fires only once a model step is already due — never for a tool step, and it cannot make one due.
+         * @mode emit — synchronous; listeners must not await. A throwing listener fails the step before
+         * any of its input is recorded.
+         */
+        'lagent/llm/step'(this: Scoped, step: ModelStep): void;
+        /**
+         * A turn's answer — a reply with no tool calls, or a result that concluded the turn — is about
+         * to become the thread's answer. Return `undefined` to accept it, `{ decision: 'continue',
+         * message }` to send the model back in the same turn, or `{ decision: 'reject', reason, source }`
+         * to end the turn `rejected`, or `{ decision: 'prepare', request }` to plan a runtime operation
+         * before final judgment. Rejection wins, then continuation, then preparation. Consulted whatever the
+         * step budget, and again after a crash, abort or failure left the answer unjudged. A check
+         * declares the facts its verdict rests on with `stop.observe(read)`; the judgment is discarded if
+         * one reads differently when it is recorded.
+         * @mode collect — a throwing check, or an invalid verdict, ends the turn `error` and leaves the
+         * answer to be judged on the next run.
+         */
+        'lagent/turn/stop'(this: Scoped, stop: TurnStop): StopVerdict | undefined | Promise<StopVerdict | undefined>;
+        /**
+         * Around every model request. The terminal records `llm/request` and calls the route's client
+         * with the (possibly rewritten) request. `model` and `thinkingEffort` are the turn's route and
+         * read-only, so the route a step was told is the one lagent sends, and so are the correlation
+         * ids, `purpose` and `signal` the journal recorded the call under; a listener that answers
+         * without calling `next()` sends nothing through lagent.
+         * @mode waterfall
+         */
+        'lagent/llm/request'(this: Scoped, request: ModelRequestDraft, next: () => Promise<StreamingLLMResponse>): Promise<StreamingLLMResponse>;
+        /**
+         * A model request as it was sent, after middleware, with the row that
+         * recorded it, before the client has it: model steps and auxiliary calls alike. Read-only;
+         * awaited; a listener that throws is reported, and the request still goes out.
+         * @mode parallel
+         */
+        'lagent/llm/sent'(this: Scoped, sent: SentRequest): void | Promise<void>;
+        /**
+         * Every matching policy contributes `deny`, `confirm` or `approve`, or no opinion. Deny wins
+         * over everything, and `{ decision: 'deny', reason }` tells the model why; `confirm` holds the
+         * call for the user unless the user already approved it or a policy approves it. A throwing
+         * policy prevents execution. Re-evaluated when a confirmed call resumes.
+         * @mode collect
+         */
+        'lagent/tool/authorize'(this: Scoped, request: ToolAuthorizationRequest): ToolPolicyDecision | undefined | Promise<ToolPolicyDecision | undefined>;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The application-facing API: mount the core on a root, compose providers, tools, agents and
+ * presets, and drive threads through `ctx.threads`.
+ *
+ * The package has a few doors and nothing else: this one for applications, `@leuduan/lagent/plugin`
+ * for plugin authors, `@leuduan/lagent/llm` for the model and provider contracts,
+ * `@leuduan/lagent/providers` for the shipped providers, `@leuduan/lagent/stores/sqlite` for the SQLite store
+ * (which needs `node:sqlite`), `@leuduan/lagent/records` for the serialized shapes, one
+ * `@leuduan/lagent/plugins/<name>` per shipped plugin, and `@leuduan/lagent/testing` for test doubles. A
+ * value lives on one door: this one holds what an application constructs (the core, the memory
+ * store), catches (the errors), composes from `compositions/` or runs as a host-owned process
+ * (`spawnCommand`, `runToCompletion`: servers and probes the host starts, never a tool's work); a shipped plugin's exports, its presets
+ * included, are on its own door. The core's services are reached as `ctx.<name>`, so their classes
+ * are exported as types only. Keep this
+ * entry point small enough that an embedder can understand it without first learning the engine
+ * internals.
+ */
+export * from './context.js';
+export { core } from './services/core.js';
+export type { CoreConfig } from './services/core.js';
+export type { AgentResolution, AgentsService } from './services/agents.js';
+export type { ToolsService } from './services/tools.js';
+export { registerProvider } from './services/llm.js';
+export type { LlmService, RetryPolicy } from './services/llm.js';
+export type { PromptsService } from './services/prompts.js';
+export { registerPreset } from './services/presets/installations.js';
+export type { ConfigurationPlan, InitialInstallationInput, InstallationInput, PresetsService, } from './services/presets/installations.js';
+export { UNCONFINED_LAUNCH } from './services/confinement/service.js';
+export { FileAccessError } from './services/confinement/files.js';
+export type { DirEntry, DirListing, FileScope, PathOptions, ReadHandle, WriteHandle, } from './services/confinement/files.js';
+export type { ConfinementHandle, ConfinementHandler, ConfinementOperation, ConfinementService, ConfinementSnapshot, FileAccess, FilePolicy, FileVerdict, Launched, LaunchOptions, LaunchProgram, LaunchProvenance, LaunchRequest, PreparedLaunch, } from './services/confinement/service.js';
+export type { ConfigurationChange, ConfigurationResult, RetainOptions, RetainedMembers, Retention, ThreadFilter, Threads, ThreadsConfig, ThreadsService, } from './services/threads/index.js';
+export type { MissingDetail, OwnerHandle, OwnerReadiness, OwnerRegistration, StartOptions, StartupPolicy, ThreadInspection, WaitResolution, WaitValue, } from './services/threads/index.js';
+export { heldOrSettled, UnknownRunError, waitForRun } from './services/threads/index.js';
+export type { RunEvent, RunSource, RunState } from './services/threads/index.js';
+export type { BirthChoice, BirthInput, CreateThreadOptions, ForkCut, ForkOptions, Opening, Reuse, } from './services/threads/index.js';
+export type { Thread } from './services/threads/index.js';
+export type { ThreadView } from './services/threads/index.js';
+export type { CancelOptions, ConfirmationAnswer } from './services/threads/index.js';
+export { buildSpawnEnvironment, NON_INTERACTIVE_ENVIRONMENT, resolveTrustedPrograms } from './sys/environment.js';
+export { CODEX_ENVIRONMENT_POLICY } from './compositions/codex.js';
+export type { SpawnEnvironmentPolicy, TrustedPrograms } from './sys/environment.js';
+export { runToCompletion, spawnCommand } from './sys/spawn.js';
+export type { SpawnEnvironment, SpawnOptions, SpawnResult, SpawnStdio, SpawnedCommand, SpawnedGroup, SpawnedPipes, StopCause, } from './sys/spawn.js';
+export type { ChainStanding, ConfirmationState, ForkPoint, InputFate, InstallationRecord, ReplacementRule, RouteStatement, Target, ConstraintAnswer, Hold, HoldBasis, HoldReason, BirthSpec, ForkOpening, FreshOpening, Refusal, RowRef, RunOutcome, RowsResult, RowsWrite, InputReceipt, SendOptions, SendOutcome, TurnLimits, WaitDeclaration, WaitEntry, WithdrawOptions, WithdrawOutcome, WithdrawRows, } from './state/index.js';
+export type { CompactOptions, BirthConflict, StreamedChunk, SurfacePrepareOutcome } from './loop/index.js';
+export type { ModelSelection } from './llm/provider.js';
+export { AuxiliaryRefusedError, BirthConflictError, ConfirmationAnsweredError, CorruptHistoryError, DepthExceededError, RestoreFailedError, ThreadActivatingError, ThreadBusyError, ThreadUnsettledError, UnknownAgentError, WriteRefusedError, } from './loop/index.js';
+export { ForkCutError, ReplacementRefusedError, RouteConflictError, RouteUnavailableError, UnknownThreadError, } from './state/index.js';
+export { CorruptJournalError, forkChain, IncompatibleJournalError, InvalidOriginError, JournalBusyError, JournalCommitError, StoreBusyError, } from './journal/index.js';
+export type { AppendOutcome, Attempt, ForkLink, InvalidOriginReason, JournalStore, ThreadIndexEntry, ThreadSummaryCore, WriterLease, } from './journal/index.js';
+export { MemoryJournalStore } from './stores/memory.js';
+export { base } from './compositions/base.js';
+export { codexPreset } from './compositions/codex.js';
+export { COMMUNICATION_GUIDANCE_PROMPT, FORMATTING_PROMPT } from './compositions/codexPrompts.js';

package/dist/index.js

@@ -0,0 +1 @@
+import{a as n}from"./chunks/Q7S5LFGN.js";import{a as e,b as t}from"./chunks/ASSQZH3F.js";import{b,c as J,d as V,e as G,f as H,g as W,h as Y}from"./chunks/B4FXK5ER.js";import"./chunks/SS3B5W34.js";import"./chunks/IAAEP6VL.js";import"./chunks/OCBPT7KE.js";import"./chunks/2P47AHNK.js";import"./chunks/MHC6VPB4.js";import"./chunks/EMRB4KCN.js";import"./chunks/RCIHV3KG.js";import"./chunks/2GCIWSOA.js";import"./chunks/GGSVIIWJ.js";import{b as S,c as k,d as v}from"./chunks/CANPZYTH.js";import"./chunks/VYMT4TXD.js";import"./chunks/MNJ4SRF7.js";import"./chunks/JFZZXVWD.js";import{b as B,c as D,e as L}from"./chunks/N6IXG2VL.js";import{b as M}from"./chunks/6DRCKZ2C.js";import{c as h,d as y}from"./chunks/7LI64H5X.js";import{a as U}from"./chunks/3UMZMPWW.js";import"./chunks/Q75FUN7D.js";import"./chunks/PUSUPTAT.js";import"./chunks/34KW6VNQ.js";import"./chunks/DDZ7YF26.js";import"./chunks/KUZCL2SH.js";import{b as F}from"./chunks/CQEVREBT.js";import"./chunks/HK6ZSONF.js";import"./chunks/7VAPNE3L.js";import"./chunks/EPYQ5M3B.js";import"./chunks/5IRF47YB.js";import"./chunks/OL5A6ITQ.js";import"./chunks/JFX2MXBA.js";import"./chunks/S34ZA2R6.js";import"./chunks/6FRNHMCV.js";import{b as o}from"./chunks/CUK7CGC7.js";import{J as N,K as T,L as c,M as R,N as O,O as A,P as I,Q as g,R as P,S as w,T as _,j as l,k as u,u as d,v as x,w as C}from"./chunks/BPRCULZH.js";import"./chunks/FJLU4UH3.js";import"./chunks/DDANMY45.js";import{a,b as i,l as m,m as E,q as p,u as s,x as f}from"./chunks/BBCW2FZK.js";import"./chunks/MMNNZCBO.js";import"./chunks/G44LG6VL.js";import"./chunks/D4PQP5MA.js";var j={name:"lagent:base",inject:["agents"],async apply(r){o(r,X),await r.plugin(n),await r.plugin(e,{confirm:t})}},X={name:"main",basePrompt:"You are a helpful AI assistant."};export{_ as AuxiliaryRefusedError,O as BirthConflictError,H as CODEX_ENVIRONMENT_POLICY,V as COMMUNICATION_GUIDANCE_PROMPT,g as ConfirmationAnsweredError,w as CorruptHistoryError,p as CorruptJournalError,R as DepthExceededError,G as FORMATTING_PROMPT,U as FileAccessError,x as ForkCutError,s as IncompatibleJournalError,a as InvalidOriginError,m as JournalBusyError,f as JournalCommitError,Y as MemoryJournalStore,B as NON_INTERACTIVE_ENVIRONMENT,C as ReplacementRefusedError,c as RestoreFailedError,l as RouteConflictError,u as RouteUnavailableError,E as StoreBusyError,I as ThreadActivatingError,T as ThreadBusyError,P as ThreadUnsettledError,M as UNCONFINED_LAUNCH,N as UnknownAgentError,S as UnknownRunError,d as UnknownThreadError,A as WriteRefusedError,j as base,D as buildSpawnEnvironment,W as codexPreset,J as core,i as forkChain,v as heldOrSettled,F as registerPreset,b as registerProvider,L as resolveTrustedPrograms,y as runToCompletion,h as spawnCommand,k as waitForRun};

package/dist/journal/catalog.d.ts

@@ -0,0 +1,112 @@
+import type { ThreadOrigin, ThreadSummary } from '../records/journal.js';
+/**
+ * Why a walk up the origin tree stopped short of a thread with no caller: `missing`, the caller is
+ * not in the catalog; `cycle`, the caller was already met. `at` is the last thread the walk reached,
+ * the one whose caller could not be followed, or `null` when that is a prospective opening, which has
+ * no id yet. Neither happens in a journal that kept its rules: a
+ * caller exists before the threads it creates, so origins cannot form a cycle.
+ */
+export type OriginBreak = {
+    readonly broken: 'missing' | 'cycle';
+    readonly at: string | null;
+};
+/** A thread and the threads that called it, nearest first, with whether the walk reached a root. */
+export type CallerChain = {
+    /** `threadId` first, then its caller, that one's caller, out to a thread with no caller. */
+    readonly threads: readonly ThreadSummary[];
+    readonly chain: 'complete' | OriginBreak;
+};
+/** A thread not written yet, as far as its callers and requirements go: a write's resolved opening supplies both. */
+export type OriginOpening = {
+    readonly origin: ThreadOrigin | null;
+    readonly requires: readonly string[];
+};
+/** A constraint owner a run needs, and the threads whose `requires` name it. */
+export type RequiredOwner = {
+    readonly owner: string;
+    /** Nearest first. Empty for an owner only a prospective opening's own `requires` names. */
+    readonly introducedBy: readonly string[];
+};
+/** What `requiredOwners` found, with whether the callers it read up to a root. */
+export type RequiredOwners = {
+    readonly owners: readonly RequiredOwner[];
+    readonly chain: 'complete' | OriginBreak;
+};
+/** Which rule an origin broke: see {@link Origins.validate}. */
+export type InvalidOriginReason = 'unknown-caller' | 'source-missing' | 'source-off-lineage' | 'source-not-a-call';
+/** An origin whose caller or cited row breaks `origins.validate`'s rule; `reason` says which. */
+export declare class InvalidOriginError extends Error {
+    readonly origin: ThreadOrigin;
+    readonly reason: InvalidOriginReason;
+    constructor(origin: ThreadOrigin, reason: InvalidOriginReason);
+}
+/**
+ * The origin tree, read from the catalog: each thread's spawn row names the caller whose
+ * `tool/call` created it, and the threads with no caller head a tree each. Queries read summaries
+ * only and load nothing; they follow `origin` and never fork lineage, which is `Thread.lineageRoot`'s.
+ * A thread the catalog does not hold has no chain and no subtree.
+ */
+export interface Origins {
+    /**
+     * `threadId` and the threads that called it, upward to its origin root; see {@link CallerChain}.
+     * An incomplete chain says so, and its last thread still has an `origin`.
+     */
+    callers(threadId: string): CallerChain;
+    /** The last thread of {@link callers}: the origin root, or the last thread reached when the chain is incomplete. */
+    root(threadId: string): ThreadSummary | undefined;
+    /**
+     * The threads created under `threadId` at any depth, in spawn order, a caller before the threads
+     * it created, with `threadId` itself first when `self`. Each thread is listed once, so a cycle
+     * ends the walk rather than repeating it, and `self: false` drops the start in a cycle too.
+     */
+    subtree(threadId: string, options: {
+        readonly self: boolean;
+    }): ThreadSummary[];
+    /** Whether `threadId` is `ancestorId` or was created under it. */
+    isUnder(threadId: string, ancestorId: string): boolean;
+    /**
+     * The constraint owners a thread's run needs: what its own `requires` names and what every thread
+     * above it by origin requires, each with the threads that introduced it. A prospective opening
+     * stands for a thread not written yet; its callers are read from the catalog, and a caller the
+     * catalog does not hold is `missing` at `null`, the opening itself. Only readiness is inherited, never a
+     * caller's holds.
+     */
+    requiredOwners(threadOrOpening: string | OriginOpening): RequiredOwners;
+    /**
+     * Checks the one rule an origin's cited row must meet, whoever records the origin: its caller is a
+     * known thread, `source_seq` is a row of the caller's lineage, its own or one a fork it continues
+     * inherits, and for a `call` cause it is a `tool/call` row. What an assignment's granting row means
+     * is the owner's. Throws {@link InvalidOriginError} naming what is wrong. Reads the one row from
+     * the store when it is not loaded and loads nothing else, so a caller that is not loaded validates.
+     */
+    validate(origin: ThreadOrigin): Promise<void>;
+}
+/**
+ * The catalog of one summary per thread, in spawn order, with the index of which threads each
+ * caller created: the one owner of the origin graph, so the index cannot trail the summaries. Every
+ * change to the catalog goes through it. An origin never changes, so a thread's caller is indexed
+ * when its summary first enters.
+ */
+export declare class Catalog {
+    private readonly summaries;
+    /** Position in spawn order: kept by a replaced summary, new for one added after a delete. */
+    private readonly ranks;
+    /** Caller id to the threads it created, among those the catalog holds. The caller itself may not be held. */
+    private readonly children;
+    private nextRank;
+    readonly origins: Omit<Origins, 'validate'>;
+    get(threadId: string): ThreadSummary | undefined;
+    has(threadId: string): boolean;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<ThreadSummary>;
+    /** The summaries by thread id, live: a read sees later changes. */
+    view(): ReadonlyMap<string, ThreadSummary>;
+    /** Adds a thread's summary after the others, or replaces it where it stands. */
+    set(threadId: string, summary: ThreadSummary): void;
+    delete(threadId: string): void;
+    /** Replaces every summary, the new ones in the order given. */
+    reset(summaries: Iterable<ThreadSummary>): void;
+    private callers;
+    private subtree;
+    private requiredOwners;
+}

package/dist/journal/forkChain.d.ts

@@ -0,0 +1,16 @@
+/** What a fork walk reads of a catalog summary. */
+export type ForkLink = {
+    readonly thread_id: string;
+    readonly fork: {
+        readonly thread_id: string;
+    } | null;
+};
+/**
+ * `threadId` and the threads it was forked from, nearest first, out to the thread no fork leads
+ * from: the catalog's view of the lineage the journal folds, without loading a row. It follows
+ * `fork` and never delegation origin (`origins.callers`'). The start is first and an unknown start
+ * yields nothing; the walk stops at a source the catalog does not hold and at a thread it already
+ * met, so a journal that broke its rules, with a cycle or a lost source, ends the chain rather than
+ * looping or throwing.
+ */
+export declare function forkChain<S extends ForkLink>(summaries: ReadonlyMap<string, S>, threadId: string): S[];

package/dist/journal/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The journal: an append-only event stream and the folds over it.
+ *
+ * Knows envelopes and one row shape: a `thread/spawned` naming a fork point, where a thread's folds
+ * continue from another's. A writer judges what it writes inside its own `transact` callback; the
+ * journal parses and records. Nothing here has heard of agents, turns or tools. A store
+ * backend implements `JournalStore`; a plugin that wants durable state registers a `PluginProjection`. Neither
+ * needs the loop.
+ */
+export { InvalidOriginError } from './catalog.js';
+export type { CallerChain, InvalidOriginReason, OriginBreak, OriginOpening, Origins, RequiredOwner, RequiredOwners, } from './catalog.js';
+export * from './forkChain.js';
+export * from './journal.js';
+export * from './projection.js';
+export * from './store.js';