@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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/sqlite` for the SQLite store
+ * (which needs `node:sqlite`), `@leuduan/lagent/models` 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) or composes from `presets/`; 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.js';
+export type { ConfigurationPlan, InitialInstallationInput, InstallationInput, PresetsService, } from './services/presets.js';
+export { UNCONFINED_LAUNCH } from './services/launches.js';
+export type { LaunchesService, Launched, LaunchHandle, LaunchHandler, LaunchOptions, LaunchProvenance, LaunchRequest, PreparedLaunch, } from './services/launches.js';
+export type { ThreadDirsConfig, ThreadDirsService } from './services/threadDirs.js';
+export type { ConfigurationChange, ConfigurationResult, RetainOptions, RetainedMembers, Retention, ThreadFilter, Threads, ThreadsConfig, ThreadsService, } from './services/threads.js';
+export type { MissingDetail, OwnerHandle, OwnerReadiness, OwnerRegistration, StartOptions, StartupPolicy, ThreadInspection, WaitResolution, WaitValue, } from './services/owner.js';
+export { heldOrSettled, UnknownRunError, waitForRun } from './services/runEvents.js';
+export type { RunEvent, RunSource, RunState } from './services/runEvents.js';
+export type { BirthChoice, BirthInput, CreateThreadOptions, ForkCut, ForkOptions, Opening, Reuse, } from './services/birth.js';
+export { Thread } from './services/thread.js';
+export type { ThreadView } from './services/threadView.js';
+export type { CancelOptions, ConfirmationAnswer } from './services/thread.js';
+export { repositoryReadRoots } from './sys/git.js';
+export { buildSpawnEnvironment, CODEX_ENVIRONMENT_POLICY, NON_INTERACTIVE_ENVIRONMENT, resolveTrustedPrograms, } from './sys/environment.js';
+export type { SpawnEnvironmentPolicy, TrustedPrograms } from './sys/environment.js';
+export type { ChainStanding, CompactOptions, ConfirmationState, ForkPoint, InputFate, InstallationRecord, ModelSelection, ReplacementRule, RouteStatement, Target, ConstraintAnswer, Hold, HoldBasis, HoldReason, BirthConflict, BirthSpec, ForkOpening, FreshOpening, Refusal, RowRef, RunOutcome, RowsResult, RowsWrite, InputReceipt, SendOptions, SendOutcome, StreamedChunk, SurfacePrepareOutcome, TurnLimits, WaitDeclaration, WaitEntry, WithdrawOptions, WithdrawOutcome, WithdrawRows, } from './loop/index.js';
+export { AuxiliaryRefusedError, BirthConflictError, ConfirmationAnsweredError, CorruptHistoryError, DepthExceededError, ForkCutError, ReplacementRefusedError, RestoreFailedError, RouteConflictError, RouteUnavailableError, ThreadActivatingError, ThreadBusyError, ThreadUnsettledError, UnknownAgentError, UnknownThreadError, WriteRefusedError, } from './loop/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 './plugins/store/memory.js';
+export { base, codexPreset } from './presets/index.js';
+export { COMMUNICATION_GUIDANCE_PROMPT, FORMATTING_PROMPT } from './presets/prompts.js';

package/dist/index.js

@@ -0,0 +1,77 @@
+import{d as L}from"./chunks/3LQHQRIU.js";import{a as S}from"./chunks/ADHERZLW.js";import{a as N,b as A}from"./chunks/BM3S37EZ.js";import{a as F}from"./chunks/TOOIB6J2.js";import{c as d}from"./chunks/X65X4KP5.js";import{a as B}from"./chunks/IJ2WNMD5.js";import{a as s,b as x,c as i}from"./chunks/ENWFSU27.js";import{a as Me,b as Ue,c as Ye,d as Ke}from"./chunks/2O7ZGEIT.js";import{a as C,b as m,c as D,d as f}from"./chunks/P5ZHHOOM.js";import"./chunks/6ECI2GGV.js";import{e as W}from"./chunks/UCTEU62F.js";import{b as Y}from"./chunks/UC3FVVJ2.js";import"./chunks/4XVRUSCQ.js";import{a as G}from"./chunks/O4PPOM5Z.js";import{c as Fe}from"./chunks/OVZFGILJ.js";import{t as U}from"./chunks/EGZI4XQX.js";import{b as De,c as We,d as Ge}from"./chunks/UD3VJER6.js";import{b as v,c as M}from"./chunks/SGGMBSBA.js";import{b as Ce,c as I}from"./chunks/3QCW4WDJ.js";import"./chunks/C5LYCXJG.js";import"./chunks/J5S4URAW.js";import{e as w}from"./chunks/G74AGRAJ.js";import"./chunks/SL2YLB2F.js";import{b as Be,c as je,d as Ve,f as qe}from"./chunks/JPZFKSWT.js";import{b as p}from"./chunks/RK3VP2Q4.js";import"./chunks/74HKUGRR.js";import"./chunks/QMMLQJBS.js";import"./chunks/YIR5MYGU.js";import{a as P}from"./chunks/L3N4FIEN.js";import"./chunks/NAOUTU7A.js";import"./chunks/UKXMCHHT.js";import"./chunks/WUUKTSRT.js";import"./chunks/NDIM7MEW.js";import"./chunks/34KW6VNQ.js";import"./chunks/PUSUPTAT.js";import"./chunks/CDQG7RKA.js";import"./chunks/G6RXC3AL.js";import{b as Se}from"./chunks/GQGNVSKB.js";import"./chunks/DXFXAYDN.js";import"./chunks/DRYAN665.js";import"./chunks/2OSESBIL.js";import{A as ve,B as Pe,C as Ie,D as xe,E as Ne,H as Ae,I as Le,r as we,s as ye,t as ke,u as Oe,v as Ee,w as Te,x as be,y as Re,z as _e}from"./chunks/YLNJXQ3Z.js";import"./chunks/DDANMY45.js";import{b as ce,c as le,l as ue,m as ge,q as pe,u as me,x as fe}from"./chunks/37YOGDGY.js";import{a as _}from"./chunks/KESCTXGO.js";import"./chunks/TYTQRLTX.js";import"./chunks/D7E6EWIE.js";var y=["edit_files"],j={name:"main",basePrompt:"You are a helpful AI assistant."};var He={name:"lagent:base",inject:["agents"],async apply(e){v(e,j),await e.plugin(S),await e.plugin(L),await e.plugin(N,{confirm:A})}};import{z as R}from"zod";var V="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.",q=`- 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.
+- 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.
+- 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.
+- Do not guess or make up an answer: read the code, run the command, look it up.
+- 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.`,K='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.',k=`- 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.
+- 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.
+- 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.
+- Keep the change to what the task needs. Do not fix unrelated bugs or failing tests; mention them in your final answer.
+- Update the documentation your change makes wrong.
+- Default to ASCII in files, and add a comment only where the code does not explain itself.
+- Never add copyright or licence headers unless asked. Do not commit or create branches unless asked.`,c="- 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.",l="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.",O=`- 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.
+- Let coverage scale with risk: focused for a narrow change, broader when the change touches shared behaviour, contracts between modules, or what users do.
+- 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.
+- Run the project's formatter and linter on the files you changed when it has them.
+- A failure your change did not cause is not yours to fix: mention it.`,H=`- 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.
+- Hand work to a sub-agent when you do not need to see its steps, so your conversation keeps only its outcome:
+  - 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.
+  - 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.
+  - 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.
+  - 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.
+- 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.
+- 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.
+- 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.
+- In a forked task, do the work yourself rather than forking again.`,E="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.",J="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.",u=`- Your file tools read and change files in the working directory and the application data directory, and also read the read roots your workspace notice names. Do not go looking through the rest of the machine, such as other projects or the home directory, unless the task needs it.
+- Avoid destructive or irreversible commands, such as deleting what you did not create, force-pushing or dropping data, unless the user asked for them.
+- Do not push, publish, deploy or send anything to others unless asked.
+- Do not search for, print or copy out secrets such as credentials, API keys and tokens.`,$=`- For a task with no prior context, where the user is starting something new, be ambitious and show creativity in the implementation.
+- 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.
+- 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.`,X=`- Lead with the outcome, then give what the user needs to trust it and act on it, like a concise teammate handing off work.
+- 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.
+- Say what you ran to validate the work, and what you did not run and why.
+- Point to code as \`path:line\`, with the path relative to the working directory and a single line rather than a range.
+- 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.
+- Mention the problems you noticed but left alone, and anything you could not do.
+- 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.`,T=`- Write in English unless the user asks for another language.
+- Be direct and concise, and state the assumptions you made. Leave out flattery, filler and needless apologies.
+- Use plain characters: no emoji unless asked, and no look-alike or invisible Unicode, such as an en dash for a hyphen.`,b=`- 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.
+- Put code, commands and multi-line output in fenced code blocks labelled with their language.
+- Wrap file paths, commands, environment variables and code identifiers in backticks.`,z=e=>{let t=e("rg_search"),o=e("rg_files");return`You are an exploration sub-agent: you investigate the workspace to answer the task you are given, and report what you found without changing anything.
+
+Use read_file${t?" and rg_search to inspect and search":" to inspect"} code; read_file reads by line, so read the part you need.
+Use ${o?"rg_files to find files by name pattern, and ":""}list_dir to see what a directory holds or for an overview of the workspace.
+Request only the output you need, since tool output may be truncated, and make several targeted calls rather than one broad one.
+Answer with your findings, pointing to code as \`path:line\`, and say what you looked for but could not find.`},Q="Sub-agent that explores the workspace without changing it: codebase exploration, file discovery and code understanding. It reports its findings.",Z="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.",ee="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.",Je="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.",te=`- 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.
+- Before you answer, wait for every background command whose result you rely on, and stop every background command you started.`,$e=`Your answer is all the agent that asked gets back, so make it complete on its own:
+- Lead with the outcome: what you did, or what you found.
+- Point to code as \`path:line\`, with the path relative to the working directory.
+- Say what you ran to check it, each command exactly, and what it showed.
+- Say what is left undone, what you could not do, and what you are unsure of.`,Xe="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.",ze="- 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.",Qe=`Flag a problem only when all of these hold:
+- It meaningfully affects the correctness, performance, security or maintainability of the code.
+- It is discrete and actionable: one issue, not a remark about the codebase in general or several issues together.
+- 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.
+- 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.
+- It is clearly not a deliberate choice, and the author would fix it if they knew.
+- Fixing it does not demand more rigour than the rest of the codebase shows.
+
+Ignore 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.
+
+Report every finding the author would want to fix, not only the first; when nothing clearly qualifies, report none. For each finding:
+- 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.
+- Its location as \`path:line\` in the reviewed code, with the path relative to the repository, keeping the range as short as possible.
+- 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.
+
+When 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.
+
+End with:
+- the scope you reviewed, and for a git target the commits you compared;
+- the checks you ran, each command exactly, with its result;
+- every experiment, what it left behind, and where its reproduction is kept, with how to run it;
+- the limits of the review: what you did not read or could not check.
+Then 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.
+
+Answer 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.`,oe=(e,t)=>[e,...t.map(([o,a])=>_(o,a))].join(`
+
+`),re=oe(Je,[["codebase",k],["editing",c],["dirtyWorktree",l],["validation",O],["safety",u],["subAgent",te],["answer",$e]]),ne=oe(Xe,[["evidence",ze],["editing",c],["dirtyWorktree",l],["safety",u],["subAgent",te],["rubric",Qe]]),ae="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.",se="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.";var Ze=[...s,...y,...w,...i,d,...U],et=[{tool:d,plugin:"skills"}],tt=[{tag:"autonomy",render:()=>q},{tag:"preambles",render:()=>K},{tag:"codebase",render:()=>k},{tag:"editing",render:()=>c},{tag:"dirtyWorktree",render:()=>l},{tag:"validation",render:()=>O},{tag:"delegation",render:()=>H},{tag:"forking",render:()=>ee},{tag:"longWork",render:({tools:e})=>Y.every(t=>e.some(o=>o.name===t))?`${E}
+
+${J}`:E},{tag:"safety",render:()=>u},{tag:"ambitionPrecision",render:()=>$},{tag:"finalAnswer",render:()=>X},{tag:"communication",render:()=>T},{tag:"formatting",render:()=>b}],ot=R.strictObject({explore:R.strictObject({web:R.boolean().default(!1)}).prefault({}),agentsMd:C}),rt="codex.explore",nt="codex.general",at="codex.review",he=[...x,"web_search"],st=(e,t)=>[...s,...e?i:[]].filter(o=>t(o)||!he.includes(o)),ie=e=>[...s,...y,...w,...i,d].filter(t=>e(t)||!he.includes(t)),it=P({id:"codex#2",placement:"thread",schema:ot,inject:["tools","prompts","journal","threadDirs"],async setup(e,{explore:t,agentsMd:o},a){let r=[a.thread.agentName];if(e.get("presets")?.has(m)!==!0)throw new Error("codex hands down agents-md, which is not registered: register agentsMdPreset at startup");for(let{tool:n,plugin:g}of et)if(!e.tools.has(void 0,n))throw new Error(`codex grants ${n}, which is not registered: mount the ${g} plugin on the root`);for(let n of Ze)M(e,n,r);p(e,{tag:"base",slot:"base",agents:r,render:()=>V}),tt.forEach(({tag:n,render:g},de)=>p(e,{tag:n,slot:"instruction",agents:r,order:de,render:g})),a.kind==="installation"?(f(e,{holder:`codex in installation ${a.installationId}`,...o}),I(e,{presetId:m,config:o,installationId:D})):f(e,{holder:"codex for its agents",...o}),await e.plugin(F),await e.plugin(W,{agents:r});let h=n=>e.tools.has(void 0,n);await e.plugin(B,{endpoints:[{toolName:"explore",callers:r,description:Q,target:{kind:"role",id:rt,basePrompt:z(h),tools:st(t.web,h)}},{toolName:"delegate",callers:r,description:ae,target:{kind:"role",id:nt,basePrompt:re,tools:ie(h)}},{toolName:"fork",callers:r,description:Z,target:{kind:"fork"}},{toolName:"review",callers:r,description:se,target:{kind:"role",id:at,basePrompt:ne,tools:ie(h)}}]}),await e.plugin(G,{agents:r})}});export{Ne as AuxiliaryRefusedError,be as BirthConflictError,je as CODEX_ENVIRONMENT_POLICY,T as COMMUNICATION_GUIDANCE_PROMPT,ve as ConfirmationAnsweredError,xe as CorruptHistoryError,pe as CorruptJournalError,Ee as DepthExceededError,b as FORMATTING_PROMPT,Te as ForkCutError,me as IncompatibleJournalError,ce as InvalidOriginError,ue as JournalBusyError,fe as JournalCommitError,Ke as MemoryJournalStore,Be as NON_INTERACTIVE_ENVIRONMENT,Ie as ReplacementRefusedError,Oe as RestoreFailedError,Ae as RouteConflictError,Le as RouteUnavailableError,ge as StoreBusyError,Ue as Thread,_e as ThreadActivatingError,ke as ThreadBusyError,Pe as ThreadUnsettledError,Se as UNCONFINED_LAUNCH,we as UnknownAgentError,De as UnknownRunError,ye as UnknownThreadError,Re as WriteRefusedError,He as base,Ve as buildSpawnEnvironment,it as codexPreset,Ye as core,le as forkChain,Ge as heldOrSettled,Ce as registerPreset,Me as registerProvider,Fe as repositoryReadRoots,qe as resolveTrustedPrograms,We as waitForRun};

package/dist/journal/catalog.d.ts

@@ -0,0 +1,112 @@
+import type { ThreadOrigin, ThreadSummary } from '../models/index.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';