@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/services/threads.d.ts

@@ -0,0 +1,449 @@
+import { Context, Service, type ScopeKey } from '@leuduan/cordis';
+import type { PromptBlock } from '../llm/index.js';
+import type { ChainStanding, CompactOptions, ConfirmationState, RouteAuthority, StreamedChunk, SurfacePrepareOutcome, Target, TurnLimits, BirthConflict, BirthSpec, HoldBasis } from '../loop/index.js';
+import { ChunkChannel } from '../loop/index.js';
+import type { ThreadOrigin } from '../models/index.js';
+import { type DeepReadonly } from '../util/json.js';
+import { type OwnerHandle, type OwnerRegistration, type StartOptions, type ThreadInspection } from './owner.js';
+import type { RunEvent, RunState } from './runEvents.js';
+import type { InstallationInput } from './presets.js';
+import { type CreateThreadOptions, type ForkOptions } from './birth.js';
+import { Thread } from './thread.js';
+import { ThreadView } from './threadView.js';
+export type ThreadsConfig = {
+    /** Default `environment.cwd` for threads created without one; absolute. */
+    cwd: string;
+    /** The turn limits, resolved once by `core`, which hands the journal the same ones. */
+    limits: TurnLimits;
+    /**
+     * What becomes of a thread the owner loaded to run once its execution lets go and nothing else
+     * holds it: `retire` takes it out of memory, `keep` leaves it loaded. The application's choice.
+     */
+    retention: RetainOptions['lastRelease'];
+    /** How many reactive turns in a row a thread may run before its chain is at the limit. */
+    chainLimit: number;
+};
+/**
+ * A change to one thread's preset installations; see `Thread.configure`. Removals are recorded
+ * before applications, so a change that replaces an installation lists the old id in `remove` and
+ * the new one in `apply`.
+ */
+export type ConfigurationChange = {
+    readonly apply?: readonly InstallationInput[];
+    /** Installation ids to take off; one not installed is no change. */
+    readonly remove?: readonly string[];
+    /**
+     * Render the recorded prompt again once the change is restored, the one way a preset's prompt
+     * sections reach a thread that has already run. A thread with no recorded prompt records one on
+     * its first run anyway.
+     */
+    readonly rebuildPrompt?: boolean;
+};
+/** What a configuration change did. */
+export type ConfigurationResult = {
+    /** The id of every installation the change applies, in order, one applied before included. */
+    readonly applied: readonly string[];
+    /** The installations it took off. */
+    readonly removed: readonly string[];
+};
+export type ThreadFilter = {
+    /** Threads whose `origin` is this one, caller and cause alike. */
+    origin?: ThreadOrigin;
+    /** Threads a caller thread created, by any cause. */
+    callerThreadId?: string;
+    agentName?: string;
+    /**
+     * This thread, and every thread created under it at any depth, by `origin`, in spawn order. One
+     * catalog read; an unknown thread has nothing under it.
+     */
+    under?: string;
+};
+/**
+ * `ctx.threads` as an application sees it: the questions about the set of threads, and what starts
+ * one. Everything about one thread is on its {@link Thread}.
+ */
+export interface Threads {
+    /**
+     * Aborts once lagent is closing: no thread is created, run or released after that. A refusal
+     * because lagent is closing throws `signal.reason` itself, so a host recognizes it by identity
+     * (`error === threads.signal.reason`), never by message.
+     */
+    readonly signal: AbortSignal;
+    /** The `environment.cwd` a thread created without one gets. */
+    readonly defaultCwd: string;
+    create(agentName: string, options: CreateThreadOptions): Promise<Thread>;
+    fork(sourceId: string, options: ForkOptions): Promise<Thread>;
+    get(threadId: string): Thread | undefined;
+    list(filter?: ThreadFilter): Thread[];
+    liveThreads(): Thread[];
+    /**
+     * Starts running threads, once, after the application composed its plugins and attached its
+     * observers: nothing runs before. Repairs the registered constraints' owners first, then runs the
+     * requests pending at boot that `resume` accepts, at most `startLimit` at once; the rest are held
+     * (`startup`) until a releasing cause. A second call is refused.
+     */
+    start(options: StartOptions): Promise<void>;
+    /**
+     * Where a thread stands: its state, current operation and primary hold, and what is behind a
+     * `missing` hold; `null` for an unknown thread. Synchronous: it admits nothing, changes no backoff
+     * and publishes nothing. `catalog` loads and activates nothing and reports the screening the
+     * catalog shows with this process's owners; `loaded` decides the hold from the thread's folds and
+     * throws unless the thread and the callers above it are loaded already.
+     */
+    inspect(threadId: string, options: {
+        readonly basis: HoldBasis;
+    }): ThreadInspection | null;
+    /** Every run's state changes, as {@link RunEvent}s. Returns the unsubscribe. */
+    onRunEvent(listener: (event: RunEvent) => void): () => void;
+    /**
+     * Where run `runId` of the thread stands, by the rule its events follow; `null` for a run it never
+     * had. Out of memory, a thread answers from its catalog entry, which knows its pending run and its
+     * latest settlement only: an older run reads `null` until the thread is loaded (a read or a hold).
+     */
+    runState(threadId: string, runId: string): RunState | null;
+    /**
+     * Where the thread's chain of unattended work stands: whether its open turn has a person's
+     * authority, how many reactive turns in a row it has run, and whether that reached the configured
+     * limit, which a producer of more unattended work (a background start, a notifying command)
+     * refuses at. Synchronous, by a caller that holds the thread, as `view` is.
+     */
+    chain(threadId: string): ChainStanding;
+    /**
+     * What differs between thread `threadId`'s recorded birth and `request`'s: the agent, that the
+     * thread is a fresh one and not a fork, then the route, environment, installations and `requires`
+     * its spawn row recorded, against the {@link BirthSpec} asked for. Empty when it is the same birth.
+     * The origin is not compared: an owner continuing its child on a later assignment checks the
+     * configuration it pinned for the participant. This is **birth** equality, read from the immutable
+     * spawn row outside any write, not the equality of the thread's current configuration. An unknown
+     * thread throws `UnknownThreadError`.
+     */
+    birthConflicts(threadId: string, request: {
+        agent: string;
+        spec: BirthSpec;
+    }): Promise<BirthConflict[]>;
+    /** Registers a feature as an owner, with its say over when its threads run; see {@link OwnerRegistration}. */
+    registerOwner(registration: OwnerRegistration): OwnerHandle;
+    pendingConfirmations(options?: {
+        under?: string;
+    }): Promise<DeepReadonly<ConfirmationState[]>>;
+    onChunk(listener: (chunk: StreamedChunk) => void): () => void;
+    retain(members: RetainedMembers, options: RetainOptions): Promise<Retention>;
+    /**
+     * What a thread's folds say, read synchronously by a caller that already holds the thread: inside
+     * a journal write or a contributor running for it, during its run, or under a retention. Loads
+     * nothing; a caller that holds nothing reads through `thread.read`. A view of a thread nothing
+     * holds may find it unloaded and throws `ThreadNotLoadedError`.
+     */
+    view(threadId: string): ThreadView;
+}
+/**
+ * A set of threads held in memory until `release()`; see `ctx.threads.retain`. Its members are
+ * read through `ctx.threads.view` while it holds them.
+ */
+export interface Retention {
+    /** Gives the set back; see `RetainOptions.lastRelease`. Releasing twice does nothing. */
+    release(): void;
+}
+/**
+ * The threads a retention keeps in memory, as a function the engine asks for them: read at the
+ * start, to load them, and again at release and by every other retention's check, since the set a
+ * host means (a conversation and what it delegated to, say) can grow while it is held. A constant
+ * set is `() => ids`. A member that appears later is covered by the live check, not loaded.
+ */
+export type RetainedMembers = () => Iterable<string>;
+export type RetainOptions = {
+    /**
+     * What releasing this retention does to its members that no other retention covers: `retire`
+     * takes them out of memory, as `close()` does, once any operation holding one has settled; `keep`
+     * leaves them loaded. Named by the caller, since what to cache is the host's choice.
+     */
+    readonly lastRelease: 'retire' | 'keep';
+};
+/**
+ * Durable handles, live activations, and application-wide shutdown. Registry lookups stay live;
+ * journal operations never require an execution runtime. Every question about the set of threads —
+ * listing, finding, lineage, what needs resuming — is answered from the journal's catalog, so a
+ * thread's rows are in memory only once something reads or runs it.
+ */
+export declare class ThreadsService extends Service<ThreadsConfig> {
+    static inject: string[];
+    readonly chunks: ChunkChannel;
+    readonly limits: TurnLimits;
+    readonly defaultCwd: string;
+    private readonly live;
+    /** The retentions not yet released, each with its membership as it reads now. */
+    private readonly retentions;
+    /** Retirements in flight, by thread: a new retention waits for one before it loads. */
+    private readonly retiring;
+    /** Which operation holds each thread; the handle and the activation are given its view at construction. */
+    private readonly admission;
+    /** When threads run: see {@link RunOwner}. */
+    private readonly owner;
+    private readonly retention;
+    private readonly chainLimit;
+    private readonly handles;
+    /** Threads whose corrupt history was reported; see `reportCorrupt`. */
+    private readonly reportedCorrupt;
+    private readonly controller;
+    private closing;
+    constructor(ctx: Context, config: ThreadsConfig);
+    /** See {@link Threads.signal}: refusals because lagent is closing throw this signal's reason itself. */
+    get signal(): AbortSignal;
+    /** Close execution admission and abort every loop before waiting for any one to finish. */
+    private shutdown;
+    /** Every thread in creation order, or those matching `filter`; from the catalog, loading nothing. */
+    list(filter?: ThreadFilter): Thread[];
+    get(threadId: string): Thread | undefined;
+    /** Threads with a live activation, running or not, in the order they activated. */
+    liveThreads(): Thread[];
+    start(options: StartOptions): Promise<void>;
+    inspect(threadId: string, { basis }: {
+        readonly basis: HoldBasis;
+    }): ThreadInspection | null;
+    onRunEvent(listener: (event: RunEvent) => void): () => void;
+    runState(threadId: string, runId: string): RunState | null;
+    chain(threadId: string): ChainStanding;
+    registerOwner(registration: OwnerRegistration): OwnerHandle;
+    /** The release as an admitted operation: the activation goes, then `after` runs, under one admission. */
+    private releaseUnder;
+    /**
+     * Keeps `members` loaded until the returned function is called. Releasing a `retire` retention
+     * then retires each of its members, its membership read again, that no other retention's current
+     * membership covers; releasing a `keep` one retires nothing. Waits for a retirement already in
+     * flight on a member before loading it, so a thread is never read as it is being dropped. A
+     * thread whose operation is admitted is retired once it settles; an ancestor a retained fork folds
+     * through stays, as the journal keeps it. Releasing twice does nothing, and once lagent is
+     * closing releasing only gives the hold back. `waitOn`, for the engine's own acquisition alone and
+     * not part of {@link RetainOptions}, names the members whose retirement in flight is waited for,
+     * all of them when omitted.
+     */
+    retain(members: RetainedMembers, options: RetainOptions & {
+        readonly waitOn?: readonly string[];
+    }): Promise<Retention>;
+    view(threadId: string): ThreadView;
+    /** The threads the retentions not yet released cover, by their membership as it reads now. */
+    private covered;
+    /**
+     * Takes a thread no retention covers out of memory: one retirement at a time per thread, after the
+     * operation admitted on it settles, and only if no retention covers it by then; refused quietly
+     * when an operation is admitted again meanwhile, since that operation's caller is reading it.
+     */
+    private retire;
+    /**
+     * Takes the thread out of the working set: releases an idle activation, then drops the thread's
+     * rows and folds from memory under the same admission, so nothing runs it in between; the catalog
+     * entry stays, and the next touch loads the thread again. The rows stay while a retention covers
+     * the thread, or a covered fork folds through it. Refused busy while an operation holds the
+     * thread. The threads it inherited from or delegated to are their own, closed on their own.
+     */
+    close(threadId: string): Promise<void>;
+    /**
+     * Starts a thread that continues `sourceId`'s conversation from the row `at`, on the same agent.
+     *
+     * The fork is one spawn row that names its source and cut; the journal folds the source's lineage
+     * up to there into every thread-scoped projection, so the fork inherits the conversation, the
+     * prompt, the route and plugin state without a copy, and nothing its source does later. What
+     * described the source's execution — queued input, calls in flight, usage — starts fresh.
+     *
+     * With `input`, the first input is queued in the same append, so the fork never exists without
+     * its task, and `rows` adds a plugin's rows to it or refuses it (see {@link Opening}). A cut at
+     * a row the source inherited is redirected to the thread that owns the row. Forking only reads
+     * the journal; the source may be running.
+     *
+     * Get-or-create, as `create` is: the recorded fork is returned when it matches by `reuse`, its
+     * resolved cut, agent and origin under `identity`, and also its own environment and `requires`
+     * under `configuration`; any other holder of the id throws `BirthConflictError`. Nothing else is
+     * compared or written.
+     */
+    fork(sourceId: string, options: ForkOptions): Promise<Thread>;
+    private forkHeld;
+    /** A fork found under its id: returned when it is the fork asked for, by its {@link Reuse}, else a conflict. */
+    private reuseFork;
+    /**
+     * A new thread's one group: its spawn row; its first input, if any, queued for a turn of its own
+     * and citing the spawn row, which is how a fork's folds tell its task from what it inherited; the
+     * cause its `wake` asks for, opening the thread's first run request; and last the rows the
+     * caller's `rows` adds, built inside the write. A veto of those rejects the creation, as a
+     * callback that threw does: the thread is never recorded.
+     */
+    private openingGroup;
+    /**
+     * Starts a thread on `agentName`, with its first input and a plugin's rows in the same append
+     * when given (see {@link Opening}). Get-or-create, the idempotent entry point a re-dispatched
+     * delegating call relies on.
+     *
+     * Two explicit choices say what is created and what an existing id must match. `birth.from` says
+     * where the thread's configuration comes from: `defaults` fills what is left out from core's
+     * configuration; `caller` from the origin's caller, whose live activation it requires, plus the
+     * installations its scope hands down; `exact` takes a whole spec and reads nothing. `reuse` says
+     * what an existing thread under the id must match to be returned: `identity`, its agent, origin and
+     * that it is not a fork, checked before anything of the request is resolved, or `configuration`,
+     * which also resolves the request and compares its birth with the recorded spawn row. A thread
+     * that does not match is never adopted: it throws {@link BirthConflictError}. Metadata, input,
+     * wake and rows apply to a new thread only; a write-time veto throws {@link WriteRefusedError}.
+     */
+    create(agentName: string, options: CreateThreadOptions): Promise<Thread>;
+    /** What resolving `threadId`'s birth reads beyond its options; see {@link BirthContext}. */
+    private birthContext;
+    /**
+     * A fresh creation's id already taken: the thread is returned when it is the one asked for. Its
+     * identity is always compared, and returned on, before the request is resolved or a live caller
+     * touched; under `configuration` reuse the request is resolved and its birth compared with the
+     * spawn row.
+     */
+    private reuseFresh;
+    /** What differs between `summary`'s recorded spawn row and the birth `spec`; read outside any write. */
+    private specConflictsOf;
+    birthConflicts(threadId: string, request: {
+        agent: string;
+        spec: BirthSpec;
+    }): Promise<BirthConflict[]>;
+    /**
+     * Requests waiting on the user: across every thread, or only on `under` and the threads created
+     * beneath it — the set one conversation's driver is responsible for answering. The threads that
+     * have any are found in the flushed catalog; only those are retained for the requests themselves,
+     * without activating plugins. Returns owned frozen snapshots and releases its retention even on failure.
+     */
+    pendingConfirmations(options?: {
+        under?: string;
+    }): Promise<DeepReadonly<ConfirmationState[]>>;
+    /**
+     * Loads a thread so its synchronous reads answer: its lineage — its own rows and those of the
+     * threads it was forked from — and the threads that called it, whose policies a running thread
+     * may read. A run, `compact()` and every write load what they need themselves; a host loads what
+     * it reads.
+     */
+    load(threadId: string): Promise<void>;
+    /**
+     * Reports, once per thread and process, a loaded thread whose surface refused a replacement: where
+     * its corrupt history is first seen. Nothing executes on it (`requireExecutable`).
+     */
+    private reportCorrupt;
+    /** Refuses to execute on a thread whose surface refused a replacement; it stays readable. */
+    private requireExecutable;
+    /** A thread and the threads that called it, out to its origin root: what a run of it reads. */
+    private readSet;
+    /**
+     * What an execution of `threadId`, a run or a compaction, reads, loaded and held for the whole of
+     * it: the thread and the callers out to its origin root, as they stand now, held by one retention
+     * that releases with `keep`, so the end of a child's run never retires a caller's activation. The
+     * callers are held loaded, never waited on: a retirement in flight is waited for on the thread
+     * alone, since a caller's own teardown may be waiting for this very execution. The release, once
+     * only, then retires the thread alone when the application's policy is `retire` and `retiring`
+     * says so, as a run's does; so does a failed acquisition, once the retention undid its holds. A
+     * compaction passes `retiring: false`: it releases every member with `keep`, so it never starts a
+     * retirement its own cleanup, or an activation's teardown reading the thread, could wait on. A
+     * retirement waits for the operation admitted on the thread to settle and is not started before.
+     * The one acquisition for an execution's reads: a storage or load failure is the caller's, a
+     * corrupt thread is `requireExecutable`'s to refuse.
+     */
+    private retainExecutionReads;
+    /** The model's output as it streams, on every thread. Returns the unsubscribe function. */
+    onChunk(listener: (chunk: StreamedChunk) => void): () => void;
+    /** `ancestorId` and every thread under it by `origin`, from the catalog. */
+    private subtreeIds;
+    /**
+     * The installations a new child is born with because its caller's scope hands them down, read
+     * from the caller's live activation, so only what the caller's own plugins declared applies.
+     */
+    private handedDown;
+    /**
+     * Changes a thread's preset installations as one operation; see `Thread.configure`. Validated,
+     * then admitted before anything is awaited (busy while another operation holds the thread,
+     * refused with `ThreadActivatingError` while the activation is still getting ready, and after
+     * shutdown), then decided against the installations as they stand: a change that records nothing,
+     * such as a retry, returns without touching the thread, even with a confirmation unfinished.
+     * Otherwise it is refused with `ThreadUnsettledError` for an unfinished confirmation, releases the live activation, records every installation change in
+     * one write decided again inside it, and restores the thread when it should.
+     */
+    configure(threadId: string, change: ConfigurationChange): Promise<ConfigurationResult>;
+    /** What a change may not be recorded under: shutdown, or a confirmation still unfinished (`ThreadUnsettledError`). */
+    private refuseRecording;
+    /**
+     * Throws `UnknownAgentError` for a global agent name that is not registered. A scoped name passes:
+     * only the thread's own installations can define it, and they are known once it is ready.
+     */
+    private requireGlobalAgent;
+    /**
+     * The origin `threadId` records, validated: a known caller within the delegation depth, citing a row
+     * of its lineage that is the cause it claims (`origins.validate`).
+     */
+    private originFor;
+    /** The prompt `threadId` would record if rendered now from `scope`, with the thread's plugins in it. */
+    private renderPrompt;
+    /** Records the thread's prompt the first time it is about to run; later turns reuse it. */
+    recordPromptOnce(scope: ScopeKey): Promise<void>;
+    /** Re-renders through the thread's activation, waiting for its plugins, and records the result. */
+    rebuildPrompt(threadId: string): Promise<PromptBlock[]>;
+    /**
+     * Activates the thread if need be and waits for its plugins. Readiness is a barrier, not an
+     * exclusive operation: a release or a configuration change in progress is waited for, since an
+     * activation on its way out is not ready, and the fresh one is then activated.
+     */
+    whenReady(threadId: string): Promise<void>;
+    /** The thread's live context, activating it; see `Thread.ctx`. */
+    contextOf(threadId: string): Context;
+    /** The current activation's signal, activating the thread; see `Thread.signal`. */
+    signalOf(threadId: string): AbortSignal;
+    private activate;
+    /**
+     * One execution of a run request under its admitted operation, the owner's to call: whatever the
+     * run reads is held (`retainExecutionReads`), and an interrupted turn is closed first, as a write,
+     * so it lands after any `send()` queued before this run, and what the run decides from is what
+     * that send left. The owner's continuation decision is asked at its entry and after every turn and
+     * recorded on `execution`, which the owner's finalization settles the request by. Resolves once
+     * the work is done, however it ended, a setup failure, settled as one, included; only a failure
+     * past its setup rejects.
+     */
+    private execute;
+    /**
+     * The thread's route as a statement is checked against, read where it is called: inside a write,
+     * as the write's rows stand. A route change is accepted only while no run serving the pending
+     * request holds the thread (a compaction does not count), and while no request is pending, the
+     * route cannot run, or the request is held by a failure or a cancellation (whatever else holds it):
+     * such a request runs only on a releasing cause, so changing its route moves nothing that is
+     * running or about to run. A runnable pending request is never moved under itself.
+     */
+    target(threadId: string): Target;
+    /** What checks every route statement, inside the write that records it: the one guard on route changes. */
+    readonly routes: RouteAuthority;
+    /**
+     * One request to prepare the surface; see `Thread.compact`. Cancellation owns it from this call:
+     * `cancel()`, the caller's signal or shutdown ends it at any point, and it then resolves
+     * `cancelled`, with nothing dispatched if it had not yet begun.
+     */
+    compact(threadId: string, options: CompactOptions): Promise<SurfacePrepareOutcome>;
+    /**
+     * Releases an activation whose setup failed while no operation held the thread; one that fails
+     * while an operation holds the thread is released by that operation as it settles. An operation
+     * admitted meanwhile waits for the disposal (`settledLive`) before it activates the thread again,
+     * so a retry never finds the failed scope's resources still held.
+     */
+    releaseFailed(threadId: string): Promise<void>;
+    /**
+     * The thread's activation for `operation`: one whose plugins changed since it was ready is
+     * released first, under the operation, marked as releasing so the scope's unload guard does not
+     * wait for it, and a fresh one is activated from the thread's listeners and installations.
+     */
+    private activationFor;
+    /** Resolves once the thread's activation, if one is being released, is gone: what every operation awaits before activating. */
+    private settledLive;
+    /** The loop's view of the registries, bound to one activation's scope. */
+    private loopServices;
+    /** The journal with core's writes, which the thread owner and the loop record through; never handed to a plugin. */
+    private get journal();
+    /**
+     * Runs `work` as an admitted operation other than a run, whose envelope is the owner's; see
+     * `Admission.hold`. An activation whose setup failed, or that went stale, could not be released
+     * while this operation held the thread: it is released as the operation's cleanup (`cleanup`).
+     */
+    private under;
+    /**
+     * The cleanup of every admitted operation, a run included, still under its admission: an
+     * activation whose setup failed, or that went stale, is released so a run meanwhile is busy and
+     * nothing activates afresh, in the releasing phase so the scope's unload guard does not wait for it.
+     */
+    private cleanup;
+    private requireThread;
+    private handle;
+}

package/dist/services/tools.d.ts

@@ -0,0 +1,41 @@
+import { Context, Service, type ScopeKey } from '@leuduan/cordis';
+import { type AgentSelector } from '../kit/scope.js';
+import type { Tool, ToolEntry } from '../loop/index.js';
+/**
+ * The tools this process can offer, and who may call them. Live: a tool or a grant lasts
+ * exactly as long as the plugin that registered it, and an agent's reachable set is resolved when a
+ * request is built, never captured earlier. Untagged registrations are global; scoped registrations
+ * are visible from that scope and its descendants. The closest definition of a name wins.
+ *
+ * What an agent may call is exactly what it is granted. A grant holds the selector it was made
+ * with and is matched against the agent asking, so a grant to `'global'` or `'all'` keeps up with
+ * agents registered after it, and a grant may name a tool or an agent that does not exist yet; it
+ * simply resolves to nothing until they do. A scoped agent is reached only by grants naming it or
+ * by `'all'` (`selects`).
+ */
+export declare class ToolsService extends Service {
+    static inject: string[];
+    private readonly layers;
+    constructor(ctx: Context);
+    /** Registered tool names visible from `scope`, sorted and deduplicated. */
+    names(scope: ScopeKey | undefined): string[];
+    has(scope: ScopeKey | undefined, name: string): boolean;
+    /** The closest registered definition of `name`, then the global fallback. */
+    get(scope: ScopeKey | undefined, name: string): ToolEntry | undefined;
+    /**
+     * Adds a tool to one layer; returns the unregister function. Duplicates fail within that layer,
+     * and so does a tool that does not say what a re-dispatch after an interruption may do: the
+     * declaration has no default, and a missing one would surface as a schema error mid-turn.
+     */
+    register(scope: ScopeKey | undefined, name: string, tool: Tool): () => void;
+    /** Lets the agents `agents` selects call `toolName` in one layer; returns the revoke function. */
+    grant(scope: ScopeKey | undefined, agents: AgentSelector, toolName: string): () => void;
+    /**
+     * What `agentName` may call right now: its global-to-local grants in registration order, each name
+     * once, names nothing answers to skipped. Throws for an agent unknown from `scope`.
+     */
+    toolsFor(scope: ScopeKey | undefined, agentName: string): ToolEntry[];
+    /** One tool `agentName` may call, or `undefined` when it is unknown or not granted. */
+    toolFor(scope: ScopeKey | undefined, agentName: string, toolName: string): ToolEntry | undefined;
+    mayCall(scope: ScopeKey | undefined, agentName: string, toolName: string): boolean;
+}

package/dist/sys/environment.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/**
+ * What a process lagent spawns may see, and which programs lagent itself runs: both chosen by the
+ * host, never read from lagent's own process. A plugin that spawns takes them as required
+ * configuration; the helpers here only build them from what the host hands in.
+ */
+/** A spawned process's whole environment, as configuration: every variable it gets, nothing else. */
+export declare const SpawnEnvironmentSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/**
+ * The overrides for a process with no terminal: colour and pagers off, and an editor that fails at
+ * once rather than sitting until the deadline. `CI` is deliberately not set, since test runners
+ * change more than interactivity under it.
+ */
+export declare const NON_INTERACTIVE_ENVIRONMENT: Readonly<Record<string, string>>;
+/** How a host derives a spawn environment from its own. */
+export type SpawnEnvironmentPolicy = {
+    /**
+     * Variables whose names match one of these patterns are dropped. A pattern matches a whole name,
+     * case-insensitively; `*` stands for any run of characters.
+     */
+    readonly drop: readonly string[];
+    /** Set over what remains. */
+    readonly set: Readonly<Record<string, string>>;
+};
+/**
+ * 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;
+/** `source` filtered and overridden by `policy`: the whole environment a spawned process gets. */
+export declare function buildSpawnEnvironment(source: Readonly<Record<string, string | undefined>>, policy: SpawnEnvironmentPolicy): Record<string, string>;
+/**
+ * The programs lagent runs itself, by absolute path: never looked up through a spawned process's
+ * `PATH`, which a workspace can reach. `rg` is `null` when there is none; the search tools, which
+ * run it, are then not provided.
+ */
+export declare const TrustedProgramsSchema: z.ZodObject<{
+    git: z.ZodString;
+    rg: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type TrustedPrograms = z.output<typeof TrustedProgramsSchema>;
+/**
+ * Each trusted program as the first executable file of its name in `searchPath`'s directories, in
+ * order. Relative directories are skipped: what they name depends on the working directory. Throws
+ * when `git` is not found; `rg` is `null` when it is not.
+ */
+export declare function resolveTrustedPrograms(searchPath: string): TrustedPrograms;

package/dist/sys/git.d.ts

@@ -0,0 +1,60 @@
+/** Variables that select a repository, an index or an object store other than the working directory's. */
+export declare const GIT_REPOSITORY_VARIABLES: readonly ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_NAMESPACE"];
+/**
+ * Where a repository keeps its metadata, as found from a path in its working tree. Read from the
+ * filesystem alone, without running git, so it costs a few `stat`s and runs nothing the repository
+ * configures.
+ */
+export type RepositoryLocation = {
+    /** The working tree's top directory: the one holding `.git`. */
+    readonly worktree: string;
+    /**
+     * The `.git` entry itself, with its symbolic links resolved: the git directory, or the pointer
+     * file a linked worktree or a submodule has, under whatever name it really has.
+     */
+    readonly dotGit: string;
+    /** The git directory: `.git` itself, or the `gitdir:` target its pointer file names. */
+    readonly gitDir: string;
+    /**
+     * The shared git directory the git directory's `commondir` names, as a linked worktree's does;
+     * else `null`.
+     */
+    readonly commonDir: string | null;
+};
+/**
+ * The repository containing `path`: the nearest directory at or above it holding a `.git` entry,
+ * so a nested repository is found before the one around it. `path` need not exist. The walk starts
+ * from `path` with its symbolic links resolved, as git's own discovery does from the physical
+ * working directory, so a workspace reached through a link is found in the repository it lives in,
+ * not among the link's own parents; the worktree, git and common directories are given resolved
+ * too. A `.git` file that names no git directory is taken as its own, so it still marks the
+ * repository. `null` outside every repository.
+ */
+export declare function findRepository(path: string): RepositoryLocation | null;
+/**
+ * Read roots for a thread working in `cwd`: the top of the git repository holding it, when that is
+ * above it, so the file tools reach the code around a package and every `AGENTS.md` from the
+ * repository root down; none outside a repository, nor at its top. Never more than the repository: a
+ * sibling checkout stays out of reach. A host's choice to record when it creates a thread; lagent
+ * applies it nowhere itself.
+ */
+export declare function repositoryReadRoots(cwd: string): string[];
+/**
+ * `path` with its symbolic links resolved, the part that does not exist yet kept as named; the
+ * lexical path when it cannot be resolved, such as behind a directory that may not be listed.
+ */
+export declare function physical(path: string): string;
+/** What a repository's `HEAD` names: a branch, or a commit it is detached at. */
+export type GitHead = {
+    readonly kind: 'branch';
+    readonly name: string;
+} | {
+    readonly kind: 'detached';
+    readonly commit: string;
+};
+/**
+ * The `HEAD` of the worktree `repository` locates, read from its git directory without running git:
+ * a branch by its short name (`ref: refs/heads/main` is `main`, another ref its full name), a commit
+ * id as a detached head at its first seven digits; `null` when it cannot be read or says neither.
+ */
+export declare function readHead(repository: RepositoryLocation): GitHead | null;

package/dist/sys/paths.d.ts

@@ -0,0 +1,56 @@
+import type { InvocationContext } from '../loop/index.js';
+import type { ThreadEnvironment } from '../models/index.js';
+import type { DeepReadonly } from '../util/json.js';
+/**
+ * What a file tool does with a path. `write` is for anything that can modify what the path reaches.
+ */
+export type PathAccess = 'read' | 'write';
+/**
+ * Where one call of a tool may reach: the thread's workspace and the application's data directory,
+ * and for a read also the read roots its environment names.
+ *
+ * Every comparison is made between real locations: the roots and each path checked against them
+ * have their symlinks resolved first, so a link inside a root cannot carry a read or a write
+ * outside it. A path that does not exist yet, such as a file about to be created, is located
+ * through its nearest existing ancestor, and a dangling link through its target.
+ */
+export type PathBoundary = {
+    /** The thread's working directory, which relative paths are resolved against. */
+    readonly cwd: string;
+    /**
+     * `pathValue` resolved against the cwd: the path a tool then opens, without its symlinks
+     * resolved, so results name what the model named. Throws when its real location is outside
+     * every root.
+     */
+    resolve(pathValue: string): string;
+    /** Whether the real location of an absolute path is inside a root: for the entries a walk finds. */
+    contains(path: string): Promise<boolean>;
+    /** `contains` for a caller that cannot await, such as a step listener; tools use `contains`. */
+    containsSync(path: string): boolean;
+};
+/**
+ * What a boundary is drawn from: a tool call's context, or the same facts about a thread for a
+ * plugin that reads on the thread's behalf, as `agentsMd` does.
+ */
+export type BoundaryScope = Pick<InvocationContext, 'ctx'> & {
+    readonly environment: DeepReadonly<ThreadEnvironment>;
+};
+export declare function pathBoundary(context: BoundaryScope, access: PathAccess): PathBoundary;
+/**
+ * Where an absolute path really is: its symlinks resolved, for a path that exists. For one that
+ * does not, its nearest existing ancestor's real location with the rest appended, following a
+ * dangling link to its target, since opening it to write would create that target. What the
+ * boundary compares, and what a tool that must tell two names of one file apart compares too.
+ */
+export declare function realLocation(path: string): string;
+/** `realLocation` without blocking the event loop, for a walk that checks every entry it finds. */
+export declare function realLocationAsync(path: string): Promise<string>;
+/** Whether `candidate` is `root` or a path inside it, by whole segments: `/a/bc` is not inside `/a/b`. Both normalized. */
+export declare const isWithin: (candidate: string, root: string) => boolean;
+/** A path as results show it: relative to the cwd inside it, absolute outside it. */
+export declare function displayPath(cwd: string, path: string): string;
+/**
+ * `path` normalized, refused when relative: a relative path would mean the process's directory,
+ * which is the host's to choose. `what` names the setting in the error.
+ */
+export declare function absolutePath(path: string, what: string): string;