@sema-agent/core/dist/core/mods/dollar.d.ts

Stateless, task-oriented AI agent core

/**
 * The engine's `$`: the seat view a runner hands the mods bus, and the chain bottom of each wave-one method
 * event over it. Every method's bottom is a seat the engine already has; each method's limits are part of
 * its contract and are checked here (a refused input is the caller's throw, "(host check)").
 */
import type { ExecutionEnv } from "../../internal/harness-types.js";
import type { Context, Message, Usage } from "../../internal/llm.js";
import type { ModDollarBase, ModMethodBottoms } from "./kernel/index.js";
/** `$.process.run`'s default command timeout (CC). */
export declare const PROCESS_RUN_DEFAULT_TIMEOUT_MS = 30000;
/** `$.process.run`'s largest command timeout (CC). */
export declare const PROCESS_RUN_MAX_TIMEOUT_MS = 600000;
/** `$.model.complete`'s output cap when the call names none. */
export declare const MODEL_COMPLETE_DEFAULT_MAX_TOKENS = 1024;
/** How many of the session's latest messages `$.session.messages` returns (CC). */
export declare const SESSION_MESSAGES_MAX = 4096;
/** One block of a `$.model.complete` prompt or system text (CC form): its text, and at most `cache: true`. */
export interface ModelCompleteBlock {
    readonly text: string;
    readonly cache?: boolean;
}
/** What the leg's model seat is asked: the model, the cap, and the request already in the brain's own form. */
export interface ModelCompleteRequest {
    /** A model reference the leg's catalog resolves; absent ⇒ the leg's own model. */
    readonly model?: string;
    readonly maxTokens: number;
    /** The system text (with its cache-span blocks on the brain's `systemBlocks` seat) and the one user message. */
    readonly context: Pick<Context, "systemPrompt" | "systemBlocks" | "messages">;
}
export interface ModelCompleteResult {
    readonly text: string;
    readonly model: string;
    /** The provider's usage, returned to the caller; the same reply is booked once on the run's account ({@link ModSeatView.book}). */
    readonly usage?: Usage;
}
/**
 * What a runner hands the bus: the seats behind the wave-one methods. `env` is the leg's execution
 * environment itself — a `$.process.run` command is the extension's, not a model tool call, so it does
 * not pass the approval gate; the deployment's environment is its boundary.
 */
export interface ModSeatView {
    readonly env: Pick<ExecutionEnv, "exec">;
    /** The leg's model seat (brain / role resolution). */
    complete(request: ModelCompleteRequest, signal: AbortSignal): Promise<ModelCompleteResult>;
    /** The run's one account of side model calls: every `$.model.complete` reply is booked here once, its usage as the
     *  provider reported it (absent ⇒ the reply reported none). */
    book(reply: {
        readonly model: string;
        readonly usage?: Usage;
    }): void;
    readonly session: {
        id(): string;
        /** The task's tracked working directory (not the environment's own cwd). */
        cwd(): string;
        root(): string;
        model(): string;
        messages(): readonly Message[];
    };
    /** The deployment clock (`RunnerDeps.now`). */
    now(): number;
    tools(): readonly string[];
    agents(): readonly string[];
}
export interface ProcessRunResult {
    readonly stdout: string;
    readonly stderr: string;
    readonly exitCode: number;
}
/** The engine `$` a handler receives on the engine bus. */
export interface EngineDollar extends ModDollarBase {
    readonly process: {
        run(args: {
            argv: readonly string[];
            init?: {
                cwd?: string;
                timeoutMs?: number;
            };
        }): Promise<ProcessRunResult>;
    };
    readonly model: {
        complete(args: {
            prompt: string | readonly ModelCompleteBlock[];
            system?: string | readonly ModelCompleteBlock[];
            model?: string;
            maxTokens?: number;
        }): Promise<ModelCompleteResult>;
    };
    readonly session: {
        id(): Promise<string>;
        cwd(): Promise<string>;
        root(): Promise<string>;
        model(): Promise<string>;
        messages(): Promise<readonly Message[]>;
    };
    readonly clock: {
        now(): Promise<number>;
        sleep(args: {
            ms: number;
        }): Promise<void>;
    };
    readonly tool: {
        list(): Promise<readonly string[]>;
    };
    readonly agent: {
        list(): Promise<readonly string[]>;
    };
}
/** The chain bottoms of the wave-one method events over a runner's seat view. */
export declare function engineMethodBottoms(view: ModSeatView): ModMethodBottoms;