@sema-agent/core 7.51.1 → 7.52.0

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

@@ -0,0 +1,131 @@
+/**
+ * The registration form, the two seats, and the screen every registration passes before admission:
+ * shape, unique name, the seat × tier table, the `uses` declaration, and the `budgetMs` fallback.
+ */
+import { type ModBusSide, type ModEventName, type ModRegistrationTier, type ModSeat, type ModTier } from "./events.js";
+import { type ModBudgetReading } from "./budget.js";
+import type { ModEventPayload, ModFailureCause, ModMatcher, ModSkip } from "./site-rules.js";
+/** The configuration refusal: a registration the kernel cannot take refuses the whole prepare. */
+export declare const MODS_INVALID_CODE = "config.mods_invalid";
+/** The notice an admission refusal becomes (the run goes on without the refused registration). */
+export declare const MODS_REGISTRATION_REFUSED_CODE = "mods.registration_refused";
+/** What a registration declares it will touch — the upper bound the kernel holds it to. */
+export interface ModUses {
+    /** Events it hangs handlers on (names or `<prefix>.*`). */
+    readonly events: readonly string[];
+    /** `$` methods it calls (method event names). */
+    readonly calls: readonly string[];
+}
+/** Who raised a dispatch: a registration (through its `$`), or the engine (`{plugin: "engine", tier: "core"}`). */
+export interface ModOrigin {
+    readonly plugin: string;
+    readonly tier: ModTier;
+}
+/** The engine's own origin; its `plugin` word is reserved (no registration may take it). */
+export declare const ENGINE_ORIGIN: ModOrigin;
+/** The facts `$.plugin` carries. */
+export interface ModPluginFacts {
+    readonly name: string;
+}
+/** The part of `$` every bus gives; each side adds its methods (`$.<noun>.<method>`). */
+export interface ModDollarBase {
+    readonly plugin: ModPluginFacts;
+}
+/** One entry of `next.trace`: a handler (or the core) that ran beneath, and how it ended. */
+export interface ModTraceEntry {
+    readonly index: number;
+    readonly plugin: string;
+    readonly tier: ModTier;
+    readonly outcome: ModTraceOutcome;
+    readonly ms: number;
+}
+/** How a chain member ended (CC words). */
+export declare const MOD_TRACE_OUTCOMES: readonly ["returned", "passed", "rejected", "caught", "expired", "kept", "skipped", "bypassed"];
+export type ModTraceOutcome = (typeof MOD_TRACE_OUTCOMES)[number];
+/** What a `.catch` reads off `next.error`. */
+export interface ModCaughtError {
+    readonly kind: ModFailureCause;
+    readonly message?: string;
+    readonly budget: number;
+}
+/** The third argument of a handler: continue the chain, or jump (prepend / append only). */
+export interface ModNext {
+    (e: ModEventPayload): Promise<unknown>;
+    to(e: ModEventPayload, tier: ModTier): Promise<unknown>;
+    readonly origin: ModOrigin;
+    readonly signal: AbortSignal;
+    /** What ran beneath this handler's last `next`. */
+    readonly trace: readonly ModTraceEntry[];
+    readonly budget: ModBudgetReading;
+    /** Present on a `.catch`'s `next` only. */
+    readonly error?: ModCaughtError;
+    /** Present on a `.catch`'s `next` only: whether the failed handler had called `next`. */
+    readonly called?: boolean;
+}
+export type ModHandler<D extends ModDollarBase = ModDollarBase> = ($: D, e: ModEventPayload, next: ModNext) => unknown;
+export interface ModHandlerOptions<D extends ModDollarBase = ModDollarBase> {
+    /** Answers for the handler when it throws, runs out of budget or breaks the site's contract. */
+    readonly catch?: ModHandler<D>;
+    /** Watch only: a detached `e`, outside the chain, its answer refused and disclosed. */
+    readonly observe?: boolean;
+}
+/** `on(pattern, handler, options?)` or `on(pattern, matcher, handler, options?)`. */
+export interface On<D extends ModDollarBase = ModDollarBase> {
+    (pattern: string, handler: ModHandler<D>, options?: ModHandlerOptions<D>): void;
+    (pattern: string, matcher: ModMatcher, handler: ModHandler<D>, options?: ModHandlerOptions<D>): void;
+}
+export interface ModRegistration<D extends ModDollarBase = ModDollarBase> {
+    /** Unique in the run; names the registration everywhere (origin, trace, disclosures, admission). */
+    readonly name: string;
+    /** Deployment seat: required. Task seat: absent or `user`. */
+    readonly tier?: ModRegistrationTier;
+    readonly uses: ModUses;
+    /** The host's provenance label, handed to admission as given. */
+    readonly provenance?: string;
+    /** Each handler's own time; default 10 000 ms. */
+    readonly budgetMs?: number;
+    readonly options?: unknown;
+    register(on: On<D>, options: unknown): void;
+}
+/** One admission result: mounted (with the patterns it actually hung) or refused (by whom, why). */
+export type ModAdmissionRecord = {
+    readonly name: string;
+    readonly seat: ModSeat;
+    readonly tier: ModTier;
+    readonly events: readonly string[];
+    readonly observe?: readonly string[];
+    /** Judges skipped while this registration was judged (their failure or site violation), as the dispatch listed them. */
+    readonly skipped?: readonly ModSkip[];
+} | {
+    readonly name: string;
+    readonly seat: ModSeat;
+    readonly tier: ModTier;
+    readonly refusedBy: string;
+    readonly reason: string;
+};
+/** The two seats as a bus receives them; a seat is a list of registrations or absent. Screened as untrusted input. */
+export interface ModSeats<D extends ModDollarBase = ModDollarBase> {
+    readonly deployment?: readonly ModRegistration<D>[];
+    readonly task?: readonly ModRegistration<D>[];
+}
+/** A registration that passed the screen, in run order. */
+export interface ScreenedRegistration<D extends ModDollarBase = ModDollarBase> {
+    readonly registration: ModRegistration<D>;
+    readonly name: string;
+    readonly seat: ModSeat;
+    readonly tier: ModRegistrationTier;
+    readonly budgetMs: number;
+    readonly uses: ModUses;
+    readonly provenance?: string;
+    readonly eventsBound: ReadonlySet<ModEventName>;
+    readonly callsBound: ReadonlySet<ModEventName>;
+}
+export declare function modsInvalid(message: string): Error & {
+    readonly code: string;
+};
+/**
+ * Screen both seats and put the registrations in run order: by tier, then deployment before task, then
+ * each seat's own order. Throws `config.mods_invalid` for anything the kernel cannot take; a bad
+ * `budgetMs` is reported and replaced by the default instead.
+ */
+export declare function screenModSeats<D extends ModDollarBase>(seats: ModSeats<D>, side: ModBusSide, report: (err: Error) => void): ScreenedRegistration<D>[];

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

@@ -0,0 +1,102 @@
+import { describe, expandModPattern, MOD_SEATS, readOnSide, SEAT_TIER_TABLE, } from "./events.js";
+import { resolveModBudgetMs } from "./budget.js";
+export const MODS_INVALID_CODE = "config.mods_invalid";
+export const MODS_REGISTRATION_REFUSED_CODE = "mods.registration_refused";
+export const ENGINE_ORIGIN = Object.freeze({ plugin: "engine", tier: "core" });
+export const MOD_TRACE_OUTCOMES = Object.freeze(["returned", "passed", "rejected", "caught", "expired", "kept", "skipped", "bypassed"]);
+export function modsInvalid(message) {
+    return Object.assign(new Error(message), { code: MODS_INVALID_CODE });
+}
+const TIER_ORDER = ["prepend", "user", "append"];
+export function screenModSeats(seats, side, report) {
+    const out = [];
+    const names = new Set();
+    for (const seat of MOD_SEATS) {
+        const list = seats[seat];
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list))
+            throw modsInvalid(`the ${seat} seat's mods must be a list of registrations, not ${describe(list)}`);
+        for (const item of list) {
+            const screened = screenOne(item, seat, side, report);
+            if (names.has(screened.name))
+                throw modsInvalid(`two registrations are named "${screened.name}" — a registration name is unique in the run`);
+            names.add(screened.name);
+            out.push(screened);
+        }
+    }
+    return out.sort((a, b) => TIER_ORDER.indexOf(a.tier) - TIER_ORDER.indexOf(b.tier));
+}
+function isRegistration(v) {
+    return typeof v === "object" && v !== null && typeof Reflect.get(v, "name") === "string" && typeof Reflect.get(v, "register") === "function";
+}
+function screenOne(item, seat, side, report) {
+    if (!isRegistration(item))
+        throw modsInvalid(`a ${seat} mods entry is ${describe(item)}; a registration has a name and a register function`);
+    const name = item.name;
+    if (name === "")
+        throw modsInvalid(`a ${seat} registration has an empty name`);
+    if (name === ENGINE_ORIGIN.plugin)
+        throw modsInvalid(`a ${seat} registration is named "${name}", the engine's own origin word — choose another name`);
+    const tier = tierOf(item.tier, seat, name);
+    const uses = usesOf(item.uses, name);
+    if (item.provenance !== undefined && typeof item.provenance !== "string")
+        throw modsInvalid(`${name}: provenance is ${describe(item.provenance)}; it is a label (a string)`);
+    const eventsBound = new Set();
+    for (const p of uses.events)
+        for (const n of namesOf(p, name, "uses.events"))
+            eventsBound.add(n);
+    const callsBound = new Set();
+    for (const c of uses.calls)
+        for (const n of namesOf(c, name, "uses.calls"))
+            if (readOnSide(n, side))
+                callsBound.add(n);
+    return {
+        registration: item,
+        name,
+        seat,
+        tier,
+        budgetMs: resolveModBudgetMs(item.budgetMs, report, name),
+        uses,
+        ...(item.provenance !== undefined ? { provenance: item.provenance } : {}),
+        eventsBound,
+        callsBound,
+    };
+}
+function tierOf(declared, seat, name) {
+    const row = SEAT_TIER_TABLE[seat];
+    const allowed = row.tiers;
+    if (declared === undefined) {
+        if (row.declared === "required")
+            throw modsInvalid(`${name}: a ${seat} registration declares its tier (${allowed.join(", ")})`);
+        return allowed[0];
+    }
+    const tier = allowed.find((t) => t === declared);
+    if (tier === undefined)
+        throw modsInvalid(`${name}: a ${seat} registration's tier is ${allowed.join(" or ")}, not ${describe(declared)}`);
+    return tier;
+}
+function usesOf(uses, name) {
+    if (typeof uses !== "object" || uses === null)
+        throw modsInvalid(`${name}: uses is ${describe(uses)}; it declares { events, calls }`);
+    const events = stringList(Reflect.get(uses, "events"), name, "uses.events");
+    const calls = stringList(Reflect.get(uses, "calls"), name, "uses.calls");
+    return Object.freeze({ events, calls });
+}
+function stringList(v, name, field) {
+    if (!Array.isArray(v))
+        throw modsInvalid(`${name}: ${field} is ${describe(v)}; it is a list of event names`);
+    const out = [];
+    for (const x of v) {
+        if (typeof x !== "string")
+            throw modsInvalid(`${name}: ${field} holds ${describe(x)}; it is a list of event names`);
+        out.push(x);
+    }
+    return Object.freeze(out);
+}
+function namesOf(pattern, name, field) {
+    const expanded = expandModPattern(pattern);
+    if ("refusal" in expanded)
+        throw modsInvalid(`${name}: ${field}: ${expanded.refusal}`);
+    return expanded.names;
+}

package/dist/core/mods/kernel/site-rules.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Site rules: what a handler may hand on and answer. A handler that changes a pinned key on the way down,
+ * or answers outside the station's answer form, breaks the site's contract — a VIOLATION, judged by the
+ * failure column like a crash but never reported as one (no code crashed).
+ */
+import { type ModSeat, type ModTier } from "./events.js";
+/** The host's Proxy probe (this folder cannot recognise a Proxy on its own): with one, a handler's Proxy is refused
+ *  before any of its traps runs; without one, it is read like any object. */
+export type ProxyProbe = (value: object) => boolean;
+/** Why a handler did not answer for itself: it threw, it ran past its budget, it broke the site's contract, or it was
+ *  not run because the dispatch re-entered a frame it is part of (its `.catch` answers for it — CC 296 form, (cli296.js:242947) "hasCatch"). */
+export declare const MOD_FAILURE_CAUSES: readonly ["threw", "timeout", "violation", "reentry"];
+export type ModFailureCause = (typeof MOD_FAILURE_CAUSES)[number];
+/** A handler the dispatch skipped (a failure on a skip event), and why. */
+export interface ModSkip {
+    readonly registration: string;
+    readonly cause: ModFailureCause;
+    readonly reason: string;
+}
+/** An event payload as the kernel carries it: an object, top level frozen by the bus. */
+export type ModEventPayload = Readonly<Record<string, unknown>>;
+/** The registration whose handler gave an answer, as the station's answer check sees it. */
+export interface ModAnswerer {
+    readonly plugin: string;
+    readonly seat: ModSeat;
+    readonly tier: ModTier;
+}
+/** What an answer check reads, in `below`, for a `next` the handler started that has not answered yet (no `deny`, no `value`). */
+export declare const NEXT_IN_FLIGHT: Readonly<{
+    inFlight: true;
+}>;
+/** The station's own reading of an answer: undefined when it is one the station takes, else why not. `below` is every
+ *  answer the handler's `next` resolved with, plus `NEXT_IN_FLIGHT` while its `next` is still in flight —
+ *  empty when it never called `next`. */
+export type ModAnswerCheck = (answer: unknown, e: ModEventPayload, by: ModAnswerer, below: readonly unknown[]) => string | undefined;
+/** A matcher: top-level fields of `e` that must equal these values exactly. */
+export type ModMatcher = Readonly<Record<string, string | number | boolean>>;
+/** The first pinned key `next` changed, or undefined. Identity comparison: a pinned value is handed on as is. */
+export declare function pinnedKeyChanged(pinned: readonly string[], received: ModEventPayload, passed: ModEventPayload): string | undefined;
+/** Why a handler's answer breaks the site, or undefined. No answer at all is never an answer. */
+export declare function answerViolation(answer: unknown, check: ModAnswerCheck | undefined, e: ModEventPayload, by: ModAnswerer, below: readonly unknown[]): string | undefined;
+/**
+ * A `$` method's answer form: `{ value }` (the call's result) or `{ deny }` (the call throws). A `{ deny }` given after
+ * the handler's `next` was answered with something that is not a deny — or while that `next` is still running — breaks
+ * the form (the deny would stand in place of a call that already ran or is running) — a deny handed up from below is
+ * no such thing. A `{ value }` given while that `next` is still running stands in place of the same running call, so it
+ * breaks the form too; one given after `next` answered is the handler rewriting what it read, and stands. Counting the
+ * running `next` is stricter than the reference, which reads answered runs only.
+ */
+export declare function methodAnswerViolation(answer: unknown, _e?: ModEventPayload, _by?: ModAnswerer, below?: readonly unknown[]): string | undefined;
+/** Why `m` is not a matcher, or undefined. */
+export declare function matcherViolation(m: unknown): string | undefined;
+/** Whether every matcher field equals `e`'s own top-level field exactly. */
+export declare function matcherMatches(m: ModMatcher | undefined, e: ModEventPayload): boolean;
+/**
+ * What a payload hands on, received by the one receipt in the mods mode: a plain record, copied whole at every depth
+ * (cycles and shared references kept, a function or a class instance handed as it is), its top level frozen. A member
+ * the reader already holds (`held`: the dispatch's own members) is kept as itself, so a pinned value handed back
+ * unchanged is the same value. An accessor anywhere is refused (a getter is never run), and a payload that cannot be
+ * copied whole is refused — never handed on shorter than it was given.
+ */
+export declare function receivePayload(v: unknown, held?: ModEventPayload, isProxy?: ProxyProbe): {
+    readonly payload: ModEventPayload;
+} | {
+    readonly refusal: string;
+};
+/**
+ * The bottom's answer as it starts up the chain: its top level frozen, so no handler can turn the answer it got from
+ * `next` into another one (a deny in place of a result that already ran). A plain record or array the bottom made is
+ * copied once and frozen; an answer already frozen (an engine sentinel) or not a plain container is itself.
+ */
+export declare function answerUpward(v: unknown): unknown;
+/** A handler's answer, received by the same receipt and mode (an answer need not be a record; a primitive is itself). */
+export declare function receiveAnswer(answer: unknown, isProxy?: ProxyProbe): {
+    readonly answer: unknown;
+} | {
+    readonly refusal: string;
+};
+/**
+ * A copy for an observe handler: every data container (a plain object, an array) detached at whatever depth, a
+ * leaf the structured clone refuses (a function, a handle, a class instance holding one) handed as is. An
+ * uncloneable leaf therefore never leaves the data beside it — at the top or nested — aliased.
+ */
+export declare function detachedCopy(e: ModEventPayload): Record<string, unknown>;

package/dist/core/mods/kernel/site-rules.js

@@ -0,0 +1,104 @@
+import { describe } from "./events.js";
+import { describeFault, isPlainRecord, MODS_PAYLOAD_MODE, receive } from "./receive.js";
+function payloadMode(isProxy) {
+    return isProxy === undefined ? MODS_PAYLOAD_MODE : Object.freeze({ ...MODS_PAYLOAD_MODE, isProxy });
+}
+export const MOD_FAILURE_CAUSES = Object.freeze(["threw", "timeout", "violation", "reentry"]);
+export const NEXT_IN_FLIGHT = Object.freeze({ inFlight: true });
+export function pinnedKeyChanged(pinned, received, passed) {
+    return pinned.find((k) => !Object.is(received[k], passed[k]));
+}
+export function answerViolation(answer, check, e, by, below) {
+    if (answer === undefined)
+        return "returned no answer (return next(e) to pass the event on)";
+    if (check === undefined)
+        return undefined;
+    try {
+        return check(answer, e, by, below);
+    }
+    catch {
+        return "returned an answer the station cannot read";
+    }
+}
+const denyOf = (a) => (typeof a === "object" && a !== null && Object.prototype.hasOwnProperty.call(a, "deny") ? Reflect.get(a, "deny") : undefined);
+export function methodAnswerViolation(answer, _e, _by, below = []) {
+    if (!isPlainRecord(answer))
+        return "takes { value } or { deny }";
+    const hasValue = Object.prototype.hasOwnProperty.call(answer, "value");
+    const deny = denyOf(answer);
+    if (deny !== undefined) {
+        if (hasValue || typeof deny !== "string" || deny === "")
+            return "takes { value } or { deny: <reason> }";
+        return below.some((b) => denyOf(b) === undefined) ? "a deny after its next() was answered or while it still runs (deny in place of next)" : undefined;
+    }
+    if (!hasValue)
+        return "takes { value } or { deny }";
+    return below.includes(NEXT_IN_FLIGHT) ? "a value while its next() still runs (value in place of next)" : undefined;
+}
+export function matcherViolation(m) {
+    if (typeof m !== "object" || m === null || Array.isArray(m))
+        return `a matcher is an object of top-level fields, not ${describe(m)}`;
+    for (const [k, v] of Object.entries(m)) {
+        if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean")
+            return `matcher field "${k}" is ${describe(v)}; a matcher value is a string, a number or a boolean`;
+    }
+    return undefined;
+}
+export function matcherMatches(m, e) {
+    if (m === undefined)
+        return true;
+    return Object.entries(m).every(([k, v]) => Object.prototype.hasOwnProperty.call(e, k) && e[k] === v);
+}
+export function receivePayload(v, held, isProxy) {
+    if (isProxy !== undefined && typeof v === "object" && v !== null && isProxy(v))
+        return { refusal: "the payload is a Proxy (refused before any of its traps runs)" };
+    if (!isPlainRecord(v))
+        return { refusal: `an event payload is a plain object, not ${describe(v)}` };
+    const r = receive(v, payloadMode(isProxy), held === undefined ? undefined : Object.values(held));
+    return r.ok ? { payload: Object.freeze(r.value) } : { refusal: `the payload holds ${describeFault(r.fault)}` };
+}
+export function answerUpward(v) {
+    if (typeof v !== "object" || v === null || Object.isFrozen(v))
+        return v;
+    if (Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype)
+        return Object.freeze([...v]);
+    return isPlainRecord(v) ? Object.freeze({ ...v }) : v;
+}
+export function receiveAnswer(answer, isProxy) {
+    const r = receive(answer, payloadMode(isProxy));
+    return r.ok ? { answer: r.value } : { refusal: `answered ${describeFault(r.fault)}` };
+}
+export function detachedCopy(e) {
+    const seen = new Map();
+    const out = {};
+    for (const [k, v] of Object.entries(e))
+        Object.defineProperty(out, k, { value: detachedValue(v, seen), enumerable: true, writable: true, configurable: true });
+    return out;
+}
+function detachedValue(v, seen) {
+    if (typeof v !== "object" || v === null)
+        return v;
+    const done = seen.get(v);
+    if (done !== undefined)
+        return done;
+    try {
+        return structuredClone(v);
+    }
+    catch {
+    }
+    const proto = Object.getPrototypeOf(v);
+    if (Array.isArray(v)) {
+        const arr = [];
+        seen.set(v, arr);
+        for (const x of v)
+            arr.push(detachedValue(x, seen));
+        return arr;
+    }
+    if (proto !== Object.prototype && proto !== null)
+        return v;
+    const obj = {};
+    seen.set(v, obj);
+    for (const [k, x] of Object.entries(v))
+        Object.defineProperty(obj, k, { value: detachedValue(x, seen), enumerable: true, writable: true, configurable: true });
+    return obj;
+}