@leuduan/lagent 0.1.2 → 44.0.0

package/dist/sandbox/policy.d.ts

@@ -1,86 +0,0 @@
-import type { SpawnEnvironment } from '../sys/spawn.js';
-import type { CallConfig, PathEntry } from './protocol.js';
-export declare function refuseStartupInjection(environment: SpawnEnvironment): void;
-/** The most command text one launch carries, which travels in the environment of the process that starts it. */
-export declare const MAX_COMMAND_BYTES: number;
-/** `path` with every link in its existing part resolved, so containment is judged on real locations. */
-export declare function canonical(path: string): string;
-/**
- * The root a command's protected names are rebuilt for, canonical. sandbox-runtime substitutes the
- * real prefix before it compiles a pattern, and cannot anchor one this module hands it, so a root
- * whose real path holds glob characters or its compiler's placeholders would turn the patterns
- * below into something else: it is refused, not escaped.
- */
-export declare function canonicalRoot(root: string): string;
-/**
- * sandbox-runtime's mandatory write denies, rebuilt for `root`: its own set anchors at the host's
- * working directory and only ever adds denies there. Each name once as the path at the root and
- * once as a pattern for the same name anywhere beneath it. `root` is canonical and holds no glob
- * characters (`canonicalRoot`).
- */
-export declare function mandatoryDenies(root: string): PathEntry[];
-/**
- * The programs a launch runs before confinement, as the search path finds them: the directories
- * searched, since a program dropped into an earlier one would win, and the real file of every
- * candidate for each program, wherever its link leads.
- */
-export declare function helperLocations(searchPath: string): string[];
-/**
- * Refuses roots a command could use against the sandbox itself: one overlapping, either way, what
- * a launch runs before confinement, or the temporary root, whose directories the host creates
- * unconfined. `roots` are canonical.
- */
-export declare function refuseUnsafeRoots(roots: readonly string[], trusted: readonly string[], tmpRoot: string): void;
-/** What a command's filesystem policy is made of, besides its root and scratch directory. */
-export type HostFacts = {
-    readonly allowWrite: readonly string[];
-    readonly denyWrite: readonly string[];
-    readonly denyRead: readonly string[];
-    readonly dataDir: string;
-    /** The paths under the home directory sandbox-runtime keeps writable for itself, as its worker reported them. */
-    readonly conveniences: readonly string[];
-    readonly privateDirectory: string;
-};
-/**
- * A command's complete filesystem lists, which replace the initialized ones for the call: writes
- * only in the root, the host's roots and the scratch directory, and never in what the host or
- * sandbox-runtime keeps for itself or in the root's protected names. Every path is literal.
- */
-export declare function callPolicy(facts: HostFacts, root: string, scratchDirectory: string): CallConfig['filesystem'];
-/**
- * The script the sandbox runs: restores the command's `PATH`, sets its temporary directory and runs
- * it with `/bin/sh -c`. Everything it needs arrives in variables, never spliced into the script.
- */
-export declare const BOOTSTRAP: string;
-/**
- * The environment of the process that starts the sandbox: the command's own, but with the trusted
- * `PATH` until the sandbox holds, since the wrapped line runs `env` and `sandbox-exec` before
- * confinement. The bootstrap restores the rest.
- */
-export declare function launchEnvironment(environment: SpawnEnvironment, searchPath: string, scratchDirectory: string, command: string): SpawnEnvironment;
-/** What the name and version say in a command's recorded launch. */
-export declare const LAUNCHER = "lagent-srt";
-export declare const versionOf: (runtime: string) => string;
-/** Everything enforcement depends on, digested: recorded with a launch as its policy. */
-export declare function policyDigest(facts: {
-    readonly filesystem: CallConfig['filesystem'];
-    readonly network: unknown;
-    readonly searchPath: string;
-    readonly cwd: string;
-    readonly home: string;
-    readonly conveniences: readonly string[];
-    readonly javaAgent: string;
-    readonly version: string;
-}): string;
-/** What the model is told about sandboxed commands. */
-export declare function instructionsFor(config: {
-    readonly filesystem: {
-        readonly allowWrite: readonly string[];
-    };
-    readonly network: {
-        readonly mode: 'allowlist';
-        readonly allowedDomains: readonly string[];
-    } | {
-        readonly mode: 'unrestricted';
-    };
-}): string;

package/dist/services/launches.d.ts

@@ -1,104 +0,0 @@
-import { Service, type Context } from '@leuduan/cordis';
-import { z } from 'zod';
-import { type SpawnedCommand, type SpawnEnvironment } from '../sys/spawn.js';
-/**
- * How a model-driven process becomes a local launch: the one place `run_command`, and later other
- * model-driven processes such as MCP stdio servers, start a process, so a host's confinement sees
- * every one. Not `sys/spawn`: lagent's own spawns (`rg`, git, the shell probe, stop-check hooks) call
- * `spawnCommand` directly and are never intercepted.
- */
-/** Which launch a process got, recorded with it: never secrets, ids or ports. */
-export declare const LaunchProvenanceSchema: z.ZodObject<{
-    launcher: z.ZodString;
-    version: z.ZodString;
-    policy: z.ZodString;
-}, z.core.$strict>;
-export type LaunchProvenance = z.output<typeof LaunchProvenanceSchema>;
-/** The `policy` of a launch a handler chose to run unconfined: what a host or a listing marks as such. */
-export declare const UNCONFINED_LAUNCH = "unconfined";
-/**
- * What to launch: the geometry to confine (`root`, `scratch`) and the thread the launch is for, the
- * subject a handler's per-thread policy is decided on.
- */
-export type LaunchRequest = {
-    /** The thread the launch serves: the policy subject, never a place to confine. */
-    readonly threadId: string;
-    /** What runs. */
-    readonly program: {
-        readonly shell: string;
-    };
-    /** Absolute: where it starts. */
-    readonly workdir: string;
-    /** The writable root the protected names are rebuilt for: the thread's working directory for commands. */
-    readonly root: string;
-    /** Keys the process's temporary directory: `thread:<id>` for commands. Equal keys share one directory. */
-    readonly scratch: string;
-    /** The process's environment: the caller's. */
-    readonly environment: SpawnEnvironment;
-    /** Aborting it stops the launch: preparation at once, and the process within its stop bound. */
-    readonly signal: AbortSignal;
-};
-export type LaunchOptions = {
-    readonly timeoutMs?: number;
-    readonly killGraceMs: number;
-    /** Awaited before the process is released, as `spawnCommand`'s, with the launch it got. */
-    readonly beforeRelease?: (pgid: number, launch: LaunchProvenance | null) => Promise<void>;
-};
-/** A local process to spawn in place of `/bin/sh -c <command>`. */
-export type PreparedLaunch = {
-    readonly argv: readonly [string, ...string[]];
-    readonly cwd: string;
-    readonly env: SpawnEnvironment;
-    readonly provenance: LaunchProvenance;
-    /** After the process ended: bounded report lines, or `null`. Never rejects the process's outcome. */
-    violations(): Promise<string | null>;
-};
-/** What confines launches, such as the OS sandbox of `@leuduan/lagent/sandbox`. */
-export type LaunchHandler = {
-    /** Rejects, with a message for the model, to refuse the launch. */
-    prepare(request: LaunchRequest): Promise<PreparedLaunch>;
-};
-export type LaunchHandle = {
-    /**
-     * Stops admitting through the handler, aborts every launch it prepared, and waits for each one's
-     * preparation, process and report within `timeoutMs`. Resolves `true` only when every group was
-     * confirmed stopped: no `stopFailed` result, ever, and nothing still running at the bound.
-     * Idempotent: every caller shares the first call's result.
-     */
-    release(timeoutMs: number): Promise<boolean>;
-};
-/** A launched process: its group, what it was launched as, and the handler's report once it ends. */
-export type Launched = {
-    readonly spawned: SpawnedCommand;
-    readonly launch: LaunchProvenance | null;
-    /** Settles after `spawned.result`, within {@link DIAGNOSTICS_MS}; `null` for nothing to report. Never rejects. */
-    readonly diagnostics: Promise<string | null>;
-};
-/** How long after a process ended its report may take. */
-export declare const DIAGNOSTICS_MS = 1000;
-/**
- * The launch seam. With no handler, a launch is `/bin/sh -c <command>`. The first {@link handle}
- * declares for the root's lifetime that launches go through a handler, which decides what each one
- * gets (confinement, or refusal): from then on a launch with no live handler, because it was
- * released, failed or never mounted again, is refused, and nothing falls back to a plain spawn. A
- * host mounts the handler before anything launches.
- *
- * A handler is told nothing about consumers. It is released as a whole: core aborts what it
- * prepared and reports whether every group stopped, so the handler may then free what confined them.
- */
-export declare class LaunchesService extends Service {
-    private readonly root;
-    constructor(ctx: Context);
-    /**
-     * Registers the one handler. Throws while another is live. Afterwards, until the root ends, a
-     * launch with no live handler is refused.
-     */
-    handle(handler: LaunchHandler): LaunchHandle;
-    /** One launch: through the handler when one was registered, else `/bin/sh -c`. */
-    launch(request: LaunchRequest, options: LaunchOptions): Promise<Launched>;
-    private spawnPlain;
-    private spawnThrough;
-    private release;
-    /** Whether every operation settled within `timeoutMs` and no stop ever failed. */
-    private settle;
-}

package/dist/services/threadDirs.d.ts

@@ -1,38 +0,0 @@
-import { Service, type Context } from '@leuduan/cordis';
-export type ThreadDirsConfig = {
-    /**
-     * Absolute application data directory; thread directories live under `<dataDir>/threads`. `null`
-     * turns thread directories off, for a host without a filesystem of its own. Required either way.
-     */
-    dataDir: string | null;
-};
-/**
- * Where each thread keeps files of its own: `<dataDir>/threads/<thread-id>/`, a scratch space its
- * file tools may read and write as part of the application's shared data directory. Harness-written
- * files go in named subdirectories such as `tool-outputs/`.
- *
- * The path is derived from the data directory and thread id, but absolute paths are also recorded
- * in prompts and tool results. Keep the data directory at the same location when reopening a
- * durable journal. Plugins can use the id supplied by their activation hook to find the directory.
- *
- * File tools may read and write the entire data directory, including other threads' scratch files.
- *
- * With `dataDir: null` there are no directories: `dataDir` and `root` are `null`, activation creates
- * nothing, and `dirFor` and `ensure` throw. The service stays mounted either way, because the threads
- * service injects it. A plugin that needs directories calls {@link ThreadDirsService.require} where it
- * mounts, so a composition without them fails there.
- */
-export declare class ThreadDirsService extends Service<ThreadDirsConfig> {
-    readonly dataDir: string | null;
-    readonly root: string | null;
-    constructor(ctx: Context, config: ThreadDirsConfig);
-    /**
-     * The data directory, for the plugin `user` that cannot work without thread directories. Call it
-     * first where the plugin mounts, so a root mounted with `dataDir: null` refuses there.
-     */
-    require(user: string): string;
-    /** The directory of `threadId`, without touching the filesystem. */
-    dirFor(threadId: string): string;
-    /** The directory of `threadId`, created if missing. */
-    ensure(threadId: string): string;
-}

package/dist/testing/sandbox.d.ts

@@ -1,71 +0,0 @@
-import type { Fiber } from '@leuduan/cordis';
-import { type LLMClient } from '../llm/index.js';
-import type { ToolResult } from '../models/index.js';
-import { type SandboxConfigInput } from '../sandbox/index.js';
-import type { Launched, LaunchOptions } from '../services/launches.js';
-import type { SandboxService } from '../sandbox/service.js';
-import { type TestRoot } from './helpers.js';
-/**
- * A root with the OS sandbox mounted over real sandbox-runtime, for the sandbox's tests. The sandbox
- * starts once per process, so a test file starts one harness and every test in it shares the service.
- */
-/** Whether this machine can run the sandbox: macOS with Seatbelt. */
-export declare const sandboxSupported: boolean;
-type RunOptions = {
-    signal?: AbortSignal;
-    workdir?: string;
-    root?: string;
-    /** Keys the launch's scratch directory. */
-    threadId?: string;
-    /** The thread the launch serves, which must exist: its conversation's mode decides it. */
-    subject?: string;
-    beforeRelease?: LaunchOptions['beforeRelease'];
-};
-type RunOutcome = {
-    launched: Launched;
-    output: string;
-    result: Awaited<Launched['spawned']['result']>;
-    report: string | null;
-};
-export type SandboxHarness = {
-    readonly root: TestRoot;
-    /** Canonical, like every path the sandbox judges. */
-    readonly base: string;
-    readonly workspace: string;
-    /** The extra writable root, when the harness was started with one. */
-    readonly extraRoot: string;
-    readonly data: string;
-    readonly tmpRoot: string;
-    readonly config: SandboxConfigInput;
-    readonly fiber: Fiber;
-    readonly service: SandboxService;
-    readonly environment: Record<string, string>;
-    /** Calls a `commands` tool as a thread's model would; needs the harness started with `commands`. */
-    tool(name: string, args: Record<string, unknown>, options?: {
-        threadId?: string;
-        callSeq?: number;
-    }): Promise<ToolResult>;
-    /**
-     * Launches `command` through `ctx.launches` as `commands` does:
-     * resolves once it runs, with output attached, and `done` settles when it has ended.
-     */
-    launch(command: string, options?: RunOptions): Promise<{
-        launched: Launched;
-        done: Promise<RunOutcome>;
-    }>;
-    /** {@link launch}, then waits for the end. */
-    run(command: string, options?: RunOptions): Promise<RunOutcome>;
-    dispose(): Promise<void>;
-};
-export declare function startSandboxHarness(options?: {
-    config?: Partial<SandboxConfigInput>;
-    /** The model the root's threads run on; one with no script unless a test drives turns. */
-    llm?: LLMClient;
-    /** Mount `commands` over it, as a host does. */
-    commands?: boolean;
-    /** Lists `<workspace>/cache` as an extra writable root, created. */
-    extraRoot?: boolean;
-    /** The worker entry; the sources' `worker.ts` unless a test needs another. */
-    worker?: URL;
-}): Promise<SandboxHarness>;
-export {};