@sema-agent/mods-kernel 0.0.0-stage → 7.54.1

package/LICENSE

@@ -0,0 +1,106 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             clay (github.com/clayboby)
+Licensed Work:        @sema-agent/core (sema-core) and the satellite packages
+                      published from this repository (currently
+                      @sema-agent/mods-kernel)
+                      (formerly published as @sema-ai/core)
+                      The Licensed Work is (c) 2026 clay.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      personal, educational, research, or other
+                      non-commercial purposes. Commercial production use
+                      requires a commercial license from the Licensor.
+Change Date:          2030-07-13
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact the Licensor.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Third-party notices
+
+Versions of this package up to and including 1.277.1 were published under the
+MIT License; those published copies remain governed by the license they were
+distributed under. This package incorporates design and (where noted) prompt
+content adapted from MIT-licensed projects — see NOTICE.md for attributions.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @sema-agent/mods-kernel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The mods kernel of the sema engine: one extension bus — registration and its two seats, tiers, admission
+through `plugin.register`, the `($, e, next)` chain with `next.to`, re-entry frames, site rules, the
+failure / abort columns, `.catch` and the self budget. It is compiled from the same source the engine
+embeds, so a shell or a client can run the same rules on its own bus. Zero dependencies; runs in Node and in
+browsers; ships its own types.
+
+## Install
+
+```sh
+npm install @sema-agent/mods-kernel
+```
+
+ES modules only (`"type": "module"`), Node >= 20.18.1 where Node is used. One entry, `.`; there are no deep paths.
+
+## Version
+
+`@sema-agent/mods-kernel@X.Y.Z` is cut with `@sema-agent/core@X.Y.Z`: the same version number, built from the same
+commit. A package version moves with every core release whether or not the kernel changed; it says which core it was
+cut with, not whether the contract moved.
+
+## Two copies: `KERNEL_CONTRACT_VERSION`
+
+Two copies of the kernel interoperate on plain objects (no `instanceof`, no module identity). A host that loads
+one copy beside another compares `KERNEL_CONTRACT_VERSION` for equality. Nothing in the kernel or the engine reads it,
+so two copies that differ are told apart only by a host that compares them. The number is an integer independent of the
+package version; it moves only when the chain semantics, the registration form, the event closed set (names and
+`side`) or the failure columns (failure, abort, pinned keys — which keys, and how a pinned key is judged) change.
+
+## Which side raises an event
+
+Every name in `MOD_EVENT_TABLE` carries a `side` — `engine`, `surface` or `both`, the closed set `MOD_EVENT_SIDES` — and
+that is the one place the answer lives: `readOnSide(name, side)` and `stationOn(name, side)` read the same row.
+
+```js
+import { KERNEL_CONTRACT_VERSION, MOD_EVENT_SIDES, MOD_EVENT_TABLE, readOnSide } from "@sema-agent/mods-kernel";
+
+console.log(KERNEL_CONTRACT_VERSION);                  // an integer
+console.log(MOD_EVENT_SIDES);                          // [ 'engine', 'surface', 'both' ]
+console.log(MOD_EVENT_TABLE["tool.check"].side);       // engine
+console.log(MOD_EVENT_TABLE["ui.render"].side);        // surface
+console.log(readOnSide("plugin.register", "surface")); // true: its side is both
+```
+
+## Exports
+
+Each name below is a runtime value or a type exported from the package root. The root's declarations are the
+contract; a removed or re-kinded export is named as breaking in the `@sema-agent/core` release notes.
+
+| Group | Names |
+| --- | --- |
+| Contract and closed sets | `KERNEL_CONTRACT_VERSION` `MOD_TIERS` `MOD_SEATS` `MOD_EVENT_SIDES` `MOD_FAILURE_ANSWERS` `MOD_ABORT_POSTURES` `NEXT_TO_TABLE` `SEAT_TIER_TABLE` |
+| Event table and readers | `MOD_EVENT_TABLE` `isModEventName` `expandModPattern` `stationOn` `readOnSide` `nextToRefusal` |
+| Event table types | `ModTier` `ModRegistrationTier` `ModSeat` `ModEventSide` `ModBusSide` `ModFailureAnswer` `ModAbortPosture` `ModStation` `ModEventRow` `ModEventName` |
+| Budgets | `DEFAULT_MOD_BUDGET_MS` `CATCH_BUDGET_MS` `RUNAWAY_AFTER_MS` `POST_ABORT_GRACE_MS` `MAX_TIMER_MS` `resolveModBudgetMs` `ModBudgetReading` |
+| Failure causes and site rules | `MOD_FAILURE_CAUSES` `ModFailureCause` `ModEventPayload` `ModAnswerCheck` `ModAnswerer` `ModMatcher` `ModSkip` |
+| Registration | `ENGINE_ORIGIN` `MODS_INVALID_CODE` `MODS_REGISTRATION_REFUSED_CODE` `MOD_TRACE_OUTCOMES` `ModTraceOutcome` `ModUses` `ModOrigin` `ModPluginFacts` `ModDollarBase` `ModTraceEntry` `ModCaughtError` `ModNext` `ModHandler` `ModHandlerOptions` `On` `ModRegistration` `ModAdmissionRecord` `ModSeats` |
+| Admission and the bus | `admitMods` `ModFrame` `ModBottomContext` `ModMethodBottom` `ModMethodSeat` `ModMethodBottoms` `ModDispatchOutcome` `ModDispatchOptions` `ModBus` `ModMountedHandler` `ModBusInput` |
+
+## License
+
+Business Source License 1.1, the same terms as `@sema-agent/core`; the licence text is the `LICENSE` file in this package.

package/dist/budget.d.ts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_MOD_BUDGET_MS = 10000;
+export declare const CATCH_BUDGET_MS = 1000;
+export declare const RUNAWAY_AFTER_MS = 5000;
+export declare const POST_ABORT_GRACE_MS = 1000;
+export declare const MAX_TIMER_MS = 2147483647;
+export interface ModBudgetReading {
+    readonly ms: number;
+    readonly remainingMs: number;
+}
+export declare function resolveModBudgetMs(supplied: unknown, report: (err: Error) => void, name: string): number;
+export interface SelfBudget {
+    readonly expired: Promise<"expired">;
+    isExpired(): boolean;
+    pause(): void;
+    resume(): void;
+    clear(): void;
+    usedMs(): number;
+    reading(): ModBudgetReading;
+}
+export declare function createSelfBudget(ms: number, onExpire: () => void): SelfBudget;
+export declare function watchRunaway(settled: Promise<unknown>, onRunaway: () => void): void;
+export declare function unrefTimer(timer: unknown): void;

package/dist/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/dispatch.d.ts

@@ -0,0 +1,73 @@
+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";
+export type ModFrame = {
+    readonly kind: "dollar";
+    readonly plugin: string;
+} | {
+    readonly kind: "handler";
+    readonly plugin: string;
+    readonly handler: number;
+};
+export interface ModBottomContext {
+    readonly frames: readonly ModFrame[];
+    readonly signal: AbortSignal;
+    readonly origin: ModOrigin;
+}
+export type ModMethodBottom = (args: ModEventPayload, ctx: ModBottomContext) => unknown;
+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";
+};
+export interface ModParticipant {
+    readonly plugin: string;
+    readonly seat: ModSeat;
+    readonly observe: boolean;
+}
+export interface ModDispatchOptions {
+    readonly bottom: (e: ModEventPayload, ctx: ModBottomContext) => unknown;
+    readonly signal?: AbortSignal;
+    readonly frames?: readonly ModFrame[];
+    readonly origin?: ModOrigin;
+    readonly checkAnswer?: ModAnswerCheck;
+    readonly participant?: (p: ModParticipant) => boolean;
+}
+export interface ModMountedHandler {
+    readonly plugin: string;
+    readonly seat: ModSeat;
+    readonly pattern: string;
+    readonly matcher?: ModMatcher;
+    readonly observe: boolean;
+    readonly caught: boolean;
+}
+export interface ModBus {
+    readonly records: readonly ModAdmissionRecord[];
+    mounted(): readonly ModMountedHandler[];
+    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;
+    readonly report: (err: Error, classification?: "observational-hook-verdict-ignored") => void;
+    readonly describeThrown: (err: unknown) => string;
+    readonly isProxy?: ProxyProbe;
+    readonly signal?: AbortSignal;
+}
+export declare function admitMods<D extends ModDollarBase = ModDollarBase>(input: ModBusInput<D>): Promise<ModBus>;