@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/mods/dollar.js

@@ -0,0 +1,154 @@
+import { shellQuote } from "../../tools/fs/search.js";
+export const PROCESS_RUN_DEFAULT_TIMEOUT_MS = 30_000;
+export const PROCESS_RUN_MAX_TIMEOUT_MS = 600_000;
+export const MODEL_COMPLETE_DEFAULT_MAX_TOKENS = 1_024;
+export const SESSION_MESSAGES_MAX = 4_096;
+const refuse = (event, why) => new Error(`${event}: ${why} (host check)`);
+function only(args, event, keys) {
+    const extra = Object.keys(args).filter((k) => !keys.includes(k));
+    if (extra.length > 0)
+        throw refuse(event, `takes ${keys.length === 0 ? "no input" : `{ ${keys.join(", ")} }`}; "${extra[0]}" is not one`);
+}
+function wholeMs(v, max) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= max;
+}
+async function processRun(view, args, ctx) {
+    only(args, "process.run", ["argv", "init"]);
+    const argv = args["argv"];
+    if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === "string"))
+        throw refuse("process.run", "takes argv, a non-empty list of strings");
+    const init = args["init"] ?? {};
+    if (typeof init !== "object" || init === null || Array.isArray(init))
+        throw refuse("process.run", "takes init, { cwd?, timeoutMs? }");
+    const cwd = Reflect.get(init, "cwd");
+    const timeoutMs = Reflect.get(init, "timeoutMs") ?? PROCESS_RUN_DEFAULT_TIMEOUT_MS;
+    if (Object.keys(init).some((k) => k !== "cwd" && k !== "timeoutMs"))
+        throw refuse("process.run", "takes init, { cwd?, timeoutMs? }");
+    if (cwd !== undefined && (typeof cwd !== "string" || cwd === ""))
+        throw refuse("process.run", "init.cwd is a non-empty path");
+    if (!wholeMs(timeoutMs, PROCESS_RUN_MAX_TIMEOUT_MS))
+        throw refuse("process.run", `init.timeoutMs is a whole number of ms, 1 to ${PROCESS_RUN_MAX_TIMEOUT_MS}`);
+    const command = argv.map((a) => shellQuote(String(a))).join(" ");
+    const r = await view.env.exec(command, { ...(cwd !== undefined ? { cwd } : {}), timeout: timeoutMs / 1000, abortSignal: ctx.signal });
+    if (!r.ok)
+        throw new Error(`process.run: ${r.error.message}`);
+    return Object.freeze({ stdout: r.value.stdout, stderr: r.value.stderr, exitCode: r.value.exitCode });
+}
+const BLOCKS_FORM = "a string or a list of blocks, each { text } and at most `cache: true`";
+function blocksOf(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = [];
+    for (const b of v) {
+        if (typeof b !== "object" || b === null || typeof Reflect.get(b, "text") !== "string")
+            return undefined;
+        const cache = Reflect.get(b, "cache");
+        if (Object.keys(b).some((k) => k !== "text" && k !== "cache") || (cache !== undefined && typeof cache !== "boolean"))
+            return undefined;
+        out.push(Object.freeze({ text: Reflect.get(b, "text"), ...(cache === true ? { cache: true } : {}) }));
+    }
+    return out;
+}
+function modelCompleteEnter(args) {
+    const out = { ...args };
+    for (const [key, blocksKey] of [["prompt", "promptBlocks"], ["system", "systemBlocks"]]) {
+        const given = args[key];
+        if (typeof given === "string" || (key === "system" && given === undefined))
+            continue;
+        const blocks = blocksOf(given);
+        if (blocks === undefined)
+            throw refuse("model.complete", `takes ${key} as ${BLOCKS_FORM}`);
+        out[key] = blocks.map((b) => b.text).join("");
+        out[blocksKey] = blocks;
+    }
+    return out;
+}
+function alignedBlocks(text, blocks) {
+    const kept = [];
+    let at = 0;
+    for (const b of blocks) {
+        if (b.text === "" || !text.startsWith(b.text, at))
+            break;
+        kept.push(b);
+        at += b.text.length;
+    }
+    const rest = text.slice(at);
+    return rest === "" ? kept : [...kept, { text: rest }];
+}
+async function modelComplete(view, args, ctx) {
+    only(args, "model.complete", ["prompt", "promptBlocks", "system", "systemBlocks", "model", "maxTokens"]);
+    const prompt = args["prompt"];
+    const system = args["system"];
+    const model = args["model"];
+    const maxTokens = args["maxTokens"] ?? MODEL_COMPLETE_DEFAULT_MAX_TOKENS;
+    if (typeof prompt !== "string" || prompt === "")
+        throw refuse("model.complete", `takes { prompt }, ${BLOCKS_FORM}, not empty`);
+    if (system !== undefined && typeof system !== "string")
+        throw refuse("model.complete", `takes system as ${BLOCKS_FORM}`);
+    const promptBlocks = args["promptBlocks"] === undefined ? [] : blocksOf(args["promptBlocks"]);
+    const systemBlocks = args["systemBlocks"] === undefined ? [] : blocksOf(args["systemBlocks"]);
+    if (promptBlocks === undefined || systemBlocks === undefined)
+        throw refuse("model.complete", `takes promptBlocks and systemBlocks that are lists of blocks, each { text } and at most \`cache: true\``);
+    if (promptBlocks.some((b) => b.cache === true))
+        throw refuse("model.complete", "`cache: true` is taken on system blocks only (a prompt block has no cache seat); put the text to cache in system");
+    if (model !== undefined && (typeof model !== "string" || model === ""))
+        throw refuse("model.complete", "model is a model reference (a non-empty string)");
+    if (typeof maxTokens !== "number" || !Number.isInteger(maxTokens) || maxTokens < 1)
+        throw refuse("model.complete", "maxTokens is a positive whole number");
+    const spans = system !== undefined && systemBlocks.some((b) => b.cache === true) ? alignedBlocks(system, systemBlocks) : undefined;
+    const context = {
+        ...(system !== undefined && system !== "" ? { systemPrompt: system } : {}),
+        ...(spans !== undefined ? { systemBlocks: spans.map((b) => ({ text: b.text, cacheControlBoundary: b.cache === true })) } : {}),
+        messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
+    };
+    const reply = await view.complete({ ...(typeof model === "string" ? { model } : {}), maxTokens, context }, ctx.signal);
+    view.book({ model: reply.model, ...(reply.usage !== undefined ? { usage: reply.usage } : {}) });
+    return reply;
+}
+function sleep(args, ctx) {
+    only(args, "clock.sleep", ["ms"]);
+    const ms = args["ms"];
+    if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0)
+        throw refuse("clock.sleep", "takes { ms }, a non-negative number of milliseconds");
+    return new Promise((resolve, reject) => {
+        if (ctx.signal.aborted)
+            return reject(ctx.signal.reason);
+        const t = setTimeout(() => {
+            ctx.signal.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        const stop = () => {
+            clearTimeout(t);
+            reject(ctx.signal.reason);
+        };
+        ctx.signal.addEventListener("abort", stop, { once: true });
+    });
+}
+function detachedMessage(m) {
+    try {
+        return structuredClone(m);
+    }
+    catch {
+        throw refuse("session.messages", "a session message could not be copied; the history is not handed out live");
+    }
+}
+const read = (event, f) => (args) => {
+    only(args, event, []);
+    return f();
+};
+export function engineMethodBottoms(view) {
+    const run = (f) => Object.freeze({ run: f });
+    return Object.freeze({
+        "process.run": run((args, ctx) => processRun(view, args, ctx)),
+        "model.complete": Object.freeze({ enter: modelCompleteEnter, run: (args, ctx) => modelComplete(view, args, ctx) }),
+        "session.id": run(read("session.id", () => view.session.id())),
+        "session.cwd": run(read("session.cwd", () => view.session.cwd())),
+        "session.root": run(read("session.root", () => view.session.root())),
+        "session.model": run(read("session.model", () => view.session.model())),
+        "session.messages": run(read("session.messages", () => Object.freeze(view.session.messages().slice(-SESSION_MESSAGES_MAX).map(detachedMessage)))),
+        "clock.now": run(read("clock.now", () => view.now())),
+        "clock.sleep": run((args, ctx) => sleep(args, ctx)),
+        "tool.list": run(read("tool.list", () => Object.freeze([...view.tools()]))),
+        "agent.list": run(read("agent.list", () => Object.freeze([...view.agents()]))),
+    });
+}

package/dist/core/mods/host.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The engine's side of the mods bus's two outward faces: which registrations the two seats hold, the
+ * notice an admission refusal becomes, and the sink that carries handler failures to `onError`.
+ */
+import type { EngineNotice } from "../engine-notice.js";
+import type { RunnerDeps } from "../runner-deps.js";
+import type { TaskSpec } from "../task-spec.js";
+import { type ModAdmissionRecord, type ModBusInput, type ModSeats } from "./kernel/index.js";
+import type { EngineDollar } from "./dollar.js";
+/**
+ * The two seats, both kept: the deployment's (`RunnerDeps.mods`) and the task's (`TaskSpec.mods`). Neither overrides the other.
+ * (A retired `hooks` key on either is not read here: it is refused by name at the retired-key doors, where every other
+ * retired seat is — `retired-keys.ts`.)
+ */
+export declare function modSeatsOf(spec: Pick<TaskSpec, "mods">, deps: Pick<RunnerDeps, "mods">): ModSeats<EngineDollar>;
+/** Handler failures land on the deployment's `onError` with `phase: "hook"`; a throwing sink is swallowed. */
+export declare function modsReportToOnError(onError: RunnerDeps["onError"], sessionId: string): ModBusInput["report"];
+type RefusedRecord = Extract<ModAdmissionRecord, {
+    readonly refusedBy: string;
+}>;
+/** The notice for a registration admission refused: the run goes on without it. */
+export declare function registrationRefusedNotice(record: RefusedRecord, sessionId: string): EngineNotice;
+export {};

package/dist/core/mods/host.js

@@ -0,0 +1,21 @@
+import { MODS_REGISTRATION_REFUSED_CODE } from "./kernel/index.js";
+export function modSeatsOf(spec, deps) {
+    return { ...(deps.mods !== undefined ? { deployment: deps.mods } : {}), ...(spec.mods !== undefined ? { task: spec.mods } : {}) };
+}
+export function modsReportToOnError(onError, sessionId) {
+    return (err, classification) => {
+        try {
+            onError?.(err, { phase: "hook", sessionId, ...(classification !== undefined ? { classification } : {}) });
+        }
+        catch {
+        }
+    };
+}
+const REGISTRATION_REFUSED = "mods.registration_refused";
+export function registrationRefusedNotice(record, sessionId) {
+    return {
+        code: REGISTRATION_REFUSED,
+        message: `extension "${record.name}" (${record.seat} seat) was not mounted: ${record.refusedBy} refused it — ${record.reason}`,
+        detail: { name: record.name, seat: record.seat, tier: record.tier, refusedBy: record.refusedBy, reason: record.reason, sessionId },
+    };
+}

package/dist/core/mods/kernel/budget.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The self budget every handler runs under (CC form): a pausable timer that stops while the handler waits
+ * on `next` or on a `$` call, plus the budget constants and the bad-value fallback for `budgetMs`.
+ */
+/** A handler's own time when its registration declares none (CC 2.1.296 `kSe` (cli296.js:239763)). */
+export declare const DEFAULT_MOD_BUDGET_MS = 10000;
+/** A `.catch`'s own time (CC 2.1.296 `z3e` (cli296.js:239763)). */
+export declare const CATCH_BUDGET_MS = 1000;
+/** How long after its budget ran out a handler that still has not settled is reported as a runaway (CC 2.1.296 `TFe` (cli296.js:239763)). */
+export declare const RUNAWAY_AFTER_MS = 5000;
+/** How long an observation dispatch still waits after the task is cancelled. */
+export declare const POST_ABORT_GRACE_MS = 1000;
+/** `setTimeout`'s ceiling; above it the platform clamps to about 1 ms. */
+export declare const MAX_TIMER_MS = 2147483647;
+/** What `next.budget` reads: the handler's budget and what is left of it. */
+export interface ModBudgetReading {
+    readonly ms: number;
+    readonly remainingMs: number;
+}
+/**
+ * `budgetMs` as a usable budget: the declared value when it is one, the default when absent, and the
+ * default LOUDLY (one report) when it is garbage. A bad value is never a refusal.
+ */
+export declare function resolveModBudgetMs(supplied: unknown, report: (err: Error) => void, name: string): number;
+export interface SelfBudget {
+    /** Resolves once, when the budget runs out (never rejects). */
+    readonly expired: Promise<"expired">;
+    isExpired(): boolean;
+    /** Stop the clock; nested pauses need as many resumes. */
+    pause(): void;
+    resume(): void;
+    /** Stop for good (the handler settled). */
+    clear(): void;
+    /** The handler's own time so far. */
+    usedMs(): number;
+    reading(): ModBudgetReading;
+}
+/** Start a budget of `ms`; `onExpire` runs once when it runs out. A zero budget runs out on the next timer turn. */
+export declare function createSelfBudget(ms: number, onExpire: () => void): SelfBudget;
+/** Run `onRunaway` once if `settled` has not settled `RUNAWAY_AFTER_MS` after a budget ran out. */
+export declare function watchRunaway(settled: Promise<unknown>, onRunaway: () => void): void;
+/** Let a host process exit with a watch still pending (a no-op where timers are plain numbers). */
+export declare function unrefTimer(timer: unknown): void;

package/dist/core/mods/kernel/budget.js

@@ -0,0 +1,83 @@
+export const DEFAULT_MOD_BUDGET_MS = 10_000;
+export const CATCH_BUDGET_MS = 1_000;
+export const RUNAWAY_AFTER_MS = 5_000;
+export const POST_ABORT_GRACE_MS = 1_000;
+export const MAX_TIMER_MS = 2_147_483_647;
+export function resolveModBudgetMs(supplied, report, name) {
+    if (supplied === undefined)
+        return DEFAULT_MOD_BUDGET_MS;
+    if (typeof supplied === "number" && Number.isFinite(supplied) && supplied >= 0 && supplied <= MAX_TIMER_MS)
+        return supplied;
+    const got = typeof supplied === "number" ? String(supplied) : typeof supplied;
+    report(new Error(`${name}: budgetMs must be a non-negative finite number no greater than ${MAX_TIMER_MS} (got ${got}) — ` +
+        `every handler of this registration falls back to the ${DEFAULT_MOD_BUDGET_MS}ms default`));
+    return DEFAULT_MOD_BUDGET_MS;
+}
+export function createSelfBudget(ms, onExpire) {
+    let remaining = ms;
+    let runningSince;
+    let timer;
+    let pauses = 0;
+    let done = false;
+    let expired = false;
+    let fire = () => { };
+    const expiredP = new Promise((res) => (fire = res));
+    const left = () => (runningSince === undefined ? remaining : Math.max(0, remaining - (Date.now() - runningSince)));
+    const arm = () => {
+        runningSince = Date.now();
+        timer = setTimeout(() => {
+            if (done)
+                return;
+            expired = true;
+            done = true;
+            remaining = 0;
+            runningSince = undefined;
+            fire("expired");
+            onExpire();
+        }, remaining);
+    };
+    arm();
+    return {
+        expired: expiredP,
+        isExpired: () => expired,
+        pause() {
+            if (pauses++ !== 0 || done)
+                return;
+            clearTimeout(timer);
+            remaining = left();
+            runningSince = undefined;
+        },
+        resume() {
+            if (pauses === 0)
+                return;
+            if (--pauses !== 0 || done)
+                return;
+            arm();
+        },
+        clear() {
+            if (done)
+                return;
+            remaining = left();
+            runningSince = undefined;
+            done = true;
+            clearTimeout(timer);
+        },
+        usedMs: () => ms - left(),
+        reading: () => Object.freeze({ ms, remainingMs: left() }),
+    };
+}
+export function watchRunaway(settled, onRunaway) {
+    let over = false;
+    const mark = () => {
+        over = true;
+    };
+    settled.then(mark, mark);
+    unrefTimer(setTimeout(() => {
+        if (!over)
+            onRunaway();
+    }, RUNAWAY_AFTER_MS));
+}
+export function unrefTimer(timer) {
+    if (typeof timer === "object" && timer !== null && "unref" in timer && typeof timer.unref === "function")
+        timer.unref();
+}

package/dist/core/mods/kernel/dispatch.d.ts

@@ -0,0 +1,100 @@
+import { type ModBusSide, type ModEventName, type ModSeat } from "./events.js";
+import { type ModAdmissionRecord, type ModDollarBase, type ModOrigin, type ModSeats } from "./registration.js";
+import { type ModAnswerCheck, type ModEventPayload, type ModFailureCause, type ModMatcher, type ModSkip, type ProxyProbe } from "./site-rules.js";
+/** A frame on the dispatch stack: a registration's own `$` call, or one of its handlers running. */
+export type ModFrame = {
+    readonly kind: "dollar";
+    readonly plugin: string;
+} | {
+    readonly kind: "handler";
+    readonly plugin: string;
+    readonly handler: number;
+};
+/** What a chain bottom (the core of an event) receives besides `e`. */
+export interface ModBottomContext {
+    readonly frames: readonly ModFrame[];
+    readonly signal: AbortSignal;
+    readonly origin: ModOrigin;
+}
+/** A `$` method's chain bottom: the host's seat behind it. Its throw is the caller's throw. */
+export type ModMethodBottom = (args: ModEventPayload, ctx: ModBottomContext) => unknown;
+/**
+ * A `$` method on a bus: `run` is its chain bottom; `enter`, when the method has one, shapes the caller's (received)
+ * arguments into the event payload the chain sees — the one place a method's argument form is normalised before any
+ * handler reads it. Either one's throw is the caller's throw.
+ */
+export interface ModMethodSeat {
+    readonly run: ModMethodBottom;
+    readonly enter?: (args: ModEventPayload) => ModEventPayload;
+}
+export type ModMethodBottoms = Partial<Record<ModEventName, ModMethodSeat>>;
+export type ModDispatchOutcome = {
+    readonly kind: "answered";
+    readonly answer: unknown;
+    readonly answeredBy?: string;
+    readonly skipped: readonly ModSkip[];
+} | {
+    readonly kind: "failed";
+    readonly registration: string;
+    readonly cause: ModFailureCause;
+    readonly reason: string;
+    readonly skipped: readonly ModSkip[];
+} | {
+    readonly kind: "aborted";
+};
+/** What a participant filter sees of one mounted handler: its registration, that registration's seat, and whether it only observes. */
+export interface ModParticipant {
+    readonly plugin: string;
+    readonly seat: ModSeat;
+    readonly observe: boolean;
+}
+export interface ModDispatchOptions {
+    /** The core of the event: what the engine (or shell) does when the chain reaches the bottom. */
+    readonly bottom: (e: ModEventPayload, ctx: ModBottomContext) => unknown;
+    readonly signal?: AbortSignal;
+    /** The frames the event is raised under (a chain bottom hands its own `ctx.frames` on). */
+    readonly frames?: readonly ModFrame[];
+    readonly origin?: ModOrigin;
+    /** The raiser's reading of an answer; an answer it refuses is a violation of the site. */
+    readonly checkAnswer?: ModAnswerCheck;
+    /** Which mounted handlers take part (absent ⇒ every handler on the event). A handler it leaves out neither runs nor observes. */
+    readonly participant?: (p: ModParticipant) => boolean;
+}
+/** One handler as admission hung it — what a registration's `register` mounted, never its code. */
+export interface ModMountedHandler {
+    readonly plugin: string;
+    readonly seat: ModSeat;
+    readonly pattern: string;
+    readonly matcher?: ModMatcher;
+    readonly observe: boolean;
+    /** Whether it was hung with a `.catch`. */
+    readonly caught: boolean;
+}
+export interface ModBus {
+    readonly records: readonly ModAdmissionRecord[];
+    /** Every mounted handler, in mount order (registrations in run order, each in the order its `register` hung them). */
+    mounted(): readonly ModMountedHandler[];
+    /** Whether any mounted handler hangs on `event` (among those `participant` admits) — no handler, no dispatch (the station skips the call). */
+    hasHandlers(event: ModEventName, participant?: (p: ModParticipant) => boolean): boolean;
+    dispatch(event: ModEventName, e: ModEventPayload, options: ModDispatchOptions): Promise<ModDispatchOutcome>;
+}
+export interface ModBusInput<D extends ModDollarBase = ModDollarBase> {
+    readonly side: ModBusSide;
+    readonly seats: ModSeats<D>;
+    readonly bottoms: ModMethodBottoms;
+    /** Where handler failures go (the host's error channel). Never throws back into the bus. */
+    readonly report: (err: Error, classification?: "observational-hook-verdict-ignored") => void;
+    /** The host's one rule for turning a THROWN value into text (a handler, a `.catch` or a `register` may throw
+     *  anything). The bus has no rendering of its own: every failure reason it writes names the value this way. */
+    readonly describeThrown: (err: unknown) => string;
+    /** The host's Proxy probe: a Proxy a handler answers or hands on is refused before any of its traps runs (a violation
+     *  of the site). Absent ⇒ a Proxy is read like any object, its traps run by the copy. */
+    readonly isProxy?: ProxyProbe;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Screen both seats, then admit registrations one by one in run order: each is put to the
+ * `plugin.register` handlers of the registrations already admitted; a refused one is never registered
+ * (its code never runs). Throws `config.mods_invalid` for a registration the kernel cannot take.
+ */
+export declare function admitMods<D extends ModDollarBase = ModDollarBase>(input: ModBusInput<D>): Promise<ModBus>;