@sema-agent/core/dist/core/mods/kernel/events.d.ts

Stateless, task-oriented AI agent core

/**
 * The mods kernel's closed vocabulary: tiers, seats, sides, the `next.to` allow table, the seat × tier
 * table, and the ONE event table every other rule reads (which events exist, which side's bus raises
 * them, and — for the ones a station raises — the failure, abort and pinned-key columns).
 *
 * Zero-dependency on purpose: this folder is compiled on its own into `@sema-agent/mods-kernel`, so the
 * engine and the shell run the same rules. It imports nothing outside the folder.
 */
/**
 * The kernel CONTRACT number — a monotonic integer, independent of the package version (the package is
 * cut with core every release; this number is not). It is exported for a host that loads a kernel copy
 * beside another one to compare for EQUALITY; nothing in this folder or in the engine reads it, so two
 * copies that differ are not detected here. It is raised when, and only when, one of four things changes:
 * the chain semantics (`next`, `next.to`, origin, trace, re-entry frames), the registration form (`ModRegistration`, `on`, `uses`),
 * the event closed set (names and their `side`), or the failure columns (failure, abort, pinned keys — which keys,
 * and how a pinned key is judged: by value since 2).
 */
export declare const KERNEL_CONTRACT_VERSION = 2;
/** The five tiers in run order (CC names). `builtin` and `core` are the engine's own. */
export declare const MOD_TIERS: readonly ["prepend", "user", "append", "builtin", "core"];
export type ModTier = (typeof MOD_TIERS)[number];
/** The tiers a registration may stand in. */
export type ModRegistrationTier = Exclude<ModTier, "builtin" | "core">;
/** Where a registration came from: the deployment's deps or the task's spec — listed most trusted first. */
export declare const MOD_SEATS: readonly ["deployment", "task"];
export type ModSeat = (typeof MOD_SEATS)[number];
/** Which bus raises an event: the engine's, the shell's, or each its own. */
export declare const MOD_EVENT_SIDES: readonly ["engine", "surface", "both"];
export type ModEventSide = (typeof MOD_EVENT_SIDES)[number];
/** A bus is one side. */
export type ModBusSide = Exclude<ModEventSide, "both">;
/** What a handler's failure means for the dispatch: the station's refusal (final), or skip the handler. */
export declare const MOD_FAILURE_ANSWERS: readonly ["refuse", "skip"];
export type ModFailureAnswer = (typeof MOD_FAILURE_ANSWERS)[number];
/** What a cancel does to a dispatch: end it now, give it one second, or follow the calling handler. */
export declare const MOD_ABORT_POSTURES: readonly ["immediate", "grace", "caller"];
export type ModAbortPosture = (typeof MOD_ABORT_POSTURES)[number];
/** `next.to(e, to)` from a handler in tier `from` is allowed iff `to` is in `NEXT_TO_TABLE[from]` (CC `pvt`). */
export declare const NEXT_TO_TABLE: Readonly<{
    prepend: readonly ["append", "builtin", "core"];
    user: readonly [];
    append: readonly ["core"];
    builtin: readonly [];
    core: readonly [];
}>;
/** Why `next.to(e, to)` from `from` is refused, or undefined when the table allows it. */
export declare function nextToRefusal(from: ModTier, to: unknown): string | undefined;
/** Which tiers each seat may declare, and whether it must declare one (absent ⇒ the first listed). */
export declare const SEAT_TIER_TABLE: Readonly<{
    deployment: Readonly<{
        declared: "required";
        tiers: readonly ["prepend", "user", "append"];
    }>;
    task: Readonly<{
        declared: "optional";
        tiers: readonly ["user"];
    }>;
}>;
/** The station columns of an event a bus raises. `method` marks a `$` method (the event a `$` call raises). */
export interface ModStation {
    readonly failure: ModFailureAnswer;
    readonly abort: ModAbortPosture;
    /** Keys a handler may not change when it passes `e` on through `next` — compared by value: the engine's fact handed on,
     *  or a copy of it (a spread, a structured clone, a JSON round trip), is not a change; a different value is. */
    readonly pinned: readonly string[];
    readonly method?: {
        readonly pausesCallerBudget: boolean;
    };
}
/** One event: its side, and its station when a bus raises it in this version (absent ⇒ named, not raised). */
export interface ModEventRow {
    readonly side: ModEventSide;
    readonly station?: ModStation;
}
/**
 * Every event the kernel knows: the reference's closed set of 142 names (CC 2.1.296 `J3e` (cli296.js:238573) — its 33 `classic.*` names,
 * its 46 engine events and its 63 `$` methods, in its own order). The shell's names (`ui.*`, `command.*`,
 * `config.*`, `audio.*`, the prompt-box events and `prompt.read`) carry `side: "surface"`, so one table serves both
 * buses and the shell fills their stations. A row with a station is raised on its side in this version; a name with
 * none is named, not raised, and a registration that selects only such names is refused.
 */
export declare const MOD_EVENT_TABLE: Readonly<{
    "classic.PreToolUse": ModEventRow;
    "classic.PostToolUse": ModEventRow;
    "classic.PostToolUseFailure": ModEventRow;
    "classic.PostToolBatch": ModEventRow;
    "classic.Notification": ModEventRow;
    "classic.UserPromptSubmit": ModEventRow;
    "classic.UserPromptExpansion": ModEventRow;
    "classic.SessionStart": ModEventRow;
    "classic.SessionEnd": ModEventRow;
    "classic.Stop": ModEventRow;
    "classic.StopFailure": ModEventRow;
    "classic.SubagentStart": ModEventRow;
    "classic.SubagentStop": ModEventRow;
    "classic.PreCompact": ModEventRow;
    "classic.PostCompact": ModEventRow;
    "classic.PreModelSwitch": ModEventRow;
    "classic.PostModelSwitch": ModEventRow;
    "classic.PermissionRequest": ModEventRow;
    "classic.PermissionDenied": ModEventRow;
    "classic.Setup": ModEventRow;
    "classic.TeammateIdle": ModEventRow;
    "classic.TaskCreated": ModEventRow;
    "classic.TaskCompleted": ModEventRow;
    "classic.Elicitation": ModEventRow;
    "classic.ElicitationResult": ModEventRow;
    "classic.ConfigChange": ModEventRow;
    "classic.WorktreeCreate": ModEventRow;
    "classic.WorktreeRemove": ModEventRow;
    "classic.InstructionsLoaded": ModEventRow;
    "classic.CwdChanged": ModEventRow;
    "classic.FileChanged": ModEventRow;
    "classic.DirectoryAdded": ModEventRow;
    "classic.MessageDisplay": ModEventRow;
    "tool.call": ModEventRow;
    "tool.check": ModEventRow;
    "ui.render": ModEventRow;
    "ui.resolve": ModEventRow;
    "ui.press": ModEventRow;
    "ui.input": ModEventRow;
    "ui.select": ModEventRow;
    "ui.message": ModEventRow;
    "ui.fault": ModEventRow;
    "ui.scroll": ModEventRow;
    "ui.focus": ModEventRow;
    "agent.offer": ModEventRow;
    "agent.spawn": ModEventRow;
    "prompt.submit": ModEventRow;
    "prompt.fill": ModEventRow;
    "prompt.suggest": ModEventRow;
    "prompt.edit": ModEventRow;
    "prompt.autocomplete": ModEventRow;
    "prompt.section": ModEventRow;
    "prompt.context": ModEventRow;
    "prompt.attachment": ModEventRow;
    "prompt.mention": ModEventRow;
    "prompt.compose": ModEventRow;
    "tool.describe": ModEventRow;
    "command.run": ModEventRow;
    "command.describe": ModEventRow;
    "config.set": ModEventRow;
    "config.describe": ModEventRow;
    "telemetry.log": ModEventRow;
    "telemetry.mark": ModEventRow;
    "skill.prompt": ModEventRow;
    "attribution.text": ModEventRow;
    "session.start": ModEventRow;
    "session.receive": ModEventRow;
    "session.append": ModEventRow;
    "session.send": ModEventRow;
    "session.compact": ModEventRow;
    "session.attach": ModEventRow;
    "session.detach": ModEventRow;
    "session.measure": ModEventRow;
    "session.end": ModEventRow;
    "plugin.register": Readonly<{
        side: "both";
        station: ModStation;
    }>;
    "turn.start": ModEventRow;
    "turn.step": ModEventRow;
    "turn.complete": ModEventRow;
    "engine.create": ModEventRow;
    "model.complete": ModEventRow;
    "model.classify": ModEventRow;
    "model.fork": ModEventRow;
    "audio.play": ModEventRow;
    "audio.speak": ModEventRow;
    "mcp.call": ModEventRow;
    "mcp.connect": ModEventRow;
    "session.cwd": ModEventRow;
    "session.root": ModEventRow;
    "session.model": ModEventRow;
    "session.turns": ModEventRow;
    "session.id": ModEventRow;
    "session.messages": ModEventRow;
    "session.repo": ModEventRow;
    "session.surface": ModEventRow;
    "session.surfaces": ModEventRow;
    "session.authorize": ModEventRow;
    "session.usage": ModEventRow;
    "session.version": ModEventRow;
    "turn.abort": ModEventRow;
    "prompt.read": ModEventRow;
    "flag.value": ModEventRow;
    "tool.list": ModEventRow;
    "tool.register": ModEventRow;
    "command.list": ModEventRow;
    "command.register": ModEventRow;
    "config.list": ModEventRow;
    "agent.list": ModEventRow;
    "agent.register": ModEventRow;
    "ui.toast": ModEventRow;
    "ui.status": ModEventRow;
    "ui.log": ModEventRow;
    "ui.notice": ModEventRow;
    "ui.invalidate": ModEventRow;
    "ui.open": ModEventRow;
    "ui.close": ModEventRow;
    "ui.panes": ModEventRow;
    "ui.selection": ModEventRow;
    "ui.copy": ModEventRow;
    "ui.notify": ModEventRow;
    "ui.blit": ModEventRow;
    "fs.read": ModEventRow;
    "fs.write": ModEventRow;
    "fs.list": ModEventRow;
    "fs.exists": ModEventRow;
    "fs.stat": ModEventRow;
    "fs.ancestors": ModEventRow;
    "store.get": ModEventRow;
    "store.set": ModEventRow;
    "store.delete": ModEventRow;
    "store.keys": ModEventRow;
    "state.get": ModEventRow;
    "state.set": ModEventRow;
    "clock.now": ModEventRow;
    "clock.sleep": ModEventRow;
    "clock.after": ModEventRow;
    "clock.every": ModEventRow;
    "http.fetch": ModEventRow;
    "process.run": ModEventRow;
    "process.spawn": ModEventRow;
    "settings.read": ModEventRow;
    "env.get": ModEventRow;
    "env.set": ModEventRow;
}>;
export type ModEventName = keyof typeof MOD_EVENT_TABLE;
export declare function isModEventName(name: unknown): name is ModEventName;
/** The row's station when a bus of `side` raises it; undefined otherwise. */
export declare function stationOn(name: ModEventName, side: ModBusSide): ModStation | undefined;
/** Whether a bus of `side` reads `name` at all (its own side or both). */
export declare function readOnSide(name: ModEventName, side: ModBusSide): boolean;
/**
 * The known names a pattern selects: an exact name, or `<prefix>.*` for every name under the prefix.
 * A pattern that selects no known name is refused (a typo is not an empty declaration).
 */
export declare function expandModPattern(pattern: unknown): {
    readonly names: readonly ModEventName[];
} | {
    readonly refusal: string;
};
/** A safe one-word description of a host value for a sentence (never calls the value's own toString). */
export declare function describe(value: unknown): string;