@sema-agent/core 7.55.0 → 7.57.0

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

@@ -1,8 +1,11 @@
-export const KERNEL_CONTRACT_VERSION = 2;
+export const KERNEL_CONTRACT_VERSION = 3;
 export const MOD_TIERS = Object.freeze(["prepend", "user", "append", "builtin", "core"]);
 export const MOD_SEATS = Object.freeze(["deployment", "task"]);
 export const MOD_EVENT_SIDES = Object.freeze(["engine", "surface", "both"]);
-export const MOD_FAILURE_ANSWERS = Object.freeze(["refuse", "skip"]);
+export const MOD_FAILURE_ANSWERS = Object.freeze(["refuse", "skip", "refuse_until_run"]);
+export function failureRefuses(failure) {
+    return failure !== "skip";
+}
 export const MOD_ABORT_POSTURES = Object.freeze(["immediate", "grace", "caller"]);
 export const NEXT_TO_TABLE = Object.freeze({
     prepend: Object.freeze(["append", "builtin", "core"]),
@@ -27,10 +30,19 @@ export const SEAT_TIER_TABLE = Object.freeze({
     deployment: Object.freeze({ declared: "required", tiers: Object.freeze(["prepend", "user", "append"]) }),
     task: Object.freeze({ declared: "optional", tiers: Object.freeze(["user"]) }),
 });
-const station = (failure, abort, pinned = []) => Object.freeze({ failure, abort, pinned: Object.freeze([...pinned]) });
+const station = (failure, abort, pinned = [], more = {}) => Object.freeze({
+    failure,
+    abort,
+    pinned: Object.freeze([...pinned]),
+    ...(more.call === true ? { call: Object.freeze({ pausesCallerBudget: true }) } : {}),
+    ...(more.budgetMs !== undefined ? { budgetMs: more.budgetMs } : {}),
+});
 const method = (pausesCallerBudget) => Object.freeze({ failure: "skip", abort: "caller", pinned: Object.freeze([]), method: Object.freeze({ pausesCallerBudget }) });
 const engine = (s) => Object.freeze(s === undefined ? { side: "engine" } : { side: "engine", station: s });
-const surface = Object.freeze({ side: "surface" });
+const surface = (s) => Object.freeze(s === undefined ? { side: "surface" } : { side: "surface", station: s });
+const RENDER_PINNED = ["surface", "component", "requestId", "viewport"];
+const ELEMENT_PINNED = ["plugin", "element", "component", "requestId", "surface"];
+const PROMPT_EDIT_BUDGET_MS = 50;
 export const MOD_EVENT_TABLE = Object.freeze({
     "classic.PreToolUse": engine(station("refuse", "immediate", ["tool", "tool_use_id", "agentId", "input"])),
     "classic.PostToolUse": engine(station("skip", "grace")),
@@ -65,34 +77,34 @@ export const MOD_EVENT_TABLE = Object.freeze({
     "classic.FileChanged": engine(),
     "classic.DirectoryAdded": engine(),
     "classic.MessageDisplay": engine(),
-    "tool.call": engine(),
+    "tool.call": engine(station("refuse_until_run", "immediate", ["tool", "tool_use_id", "agentId", "input"], { call: true })),
     "tool.check": engine(station("refuse", "immediate", ["tool", "input", "tool_use_id", "agentId", "ceiling"])),
-    "ui.render": surface,
-    "ui.resolve": surface,
-    "ui.press": surface,
-    "ui.input": surface,
-    "ui.select": surface,
-    "ui.message": surface,
-    "ui.fault": surface,
-    "ui.scroll": surface,
-    "ui.focus": surface,
+    "ui.render": surface(station("skip", "grace", RENDER_PINNED)),
+    "ui.resolve": surface(station("skip", "grace", ["surface", "component"])),
+    "ui.press": surface(station("skip", "grace", ELEMENT_PINNED)),
+    "ui.input": surface(station("skip", "grace", ELEMENT_PINNED)),
+    "ui.select": surface(station("skip", "grace", ELEMENT_PINNED)),
+    "ui.message": surface(),
+    "ui.fault": surface(),
+    "ui.scroll": surface(station("skip", "grace", ["component", "requestId", "by", "bodyRows", "contentRows", "origin", "pointer"], { call: true })),
+    "ui.focus": surface(station("skip", "grace", ["component", "requestId", "plugin", "origin", "element"], { call: true })),
     "agent.offer": engine(),
     "agent.spawn": engine(),
     "prompt.submit": engine(),
-    "prompt.fill": surface,
-    "prompt.suggest": surface,
-    "prompt.edit": surface,
-    "prompt.autocomplete": surface,
+    "prompt.fill": surface(station("skip", "grace", ["origin", "mode"], { call: true })),
+    "prompt.suggest": surface(station("skip", "grace", ["origin"], { call: true })),
+    "prompt.edit": surface(station("skip", "grace", ["origin", "key"], { budgetMs: PROMPT_EDIT_BUDGET_MS })),
+    "prompt.autocomplete": surface(),
     "prompt.section": engine(station("skip", "grace", ["name", "key", "mountedTools"])),
     "prompt.context": engine(),
     "prompt.attachment": engine(),
-    "prompt.mention": surface,
+    "prompt.mention": engine(station("refuse", "immediate", ["mention", "agentId"])),
     "prompt.compose": engine(station("skip", "grace", ["model", "catalog", "selectors"])),
     "tool.describe": engine(),
-    "command.run": surface,
-    "command.describe": surface,
-    "config.set": surface,
-    "config.describe": surface,
+    "command.run": surface(station("skip", "grace", ["command", "presentation", "origin"], { call: true })),
+    "command.describe": surface(station("skip", "grace", ["command", "immediate", "provider"])),
+    "config.set": surface(station("refuse", "immediate", ["key", "previous", "provider", "origin"], { call: true })),
+    "config.describe": surface(station("skip", "grace", ["key", "provider"])),
     "telemetry.log": engine(),
     "telemetry.mark": engine(),
     "skill.prompt": engine(),
@@ -106,7 +118,7 @@ export const MOD_EVENT_TABLE = Object.freeze({
     "session.detach": engine(),
     "session.measure": engine(),
     "session.end": engine(),
-    "plugin.register": Object.freeze({ side: "both", station: station("skip", "immediate", ["name", "seat", "tier", "uses"]) }),
+    "plugin.register": Object.freeze({ side: "both", station: station("refuse", "immediate", ["name", "seat", "tier", "uses"]) }),
     "turn.start": engine(),
     "turn.step": engine(),
     "turn.complete": engine(),
@@ -114,8 +126,8 @@ export const MOD_EVENT_TABLE = Object.freeze({
     "model.complete": engine(method(true)),
     "model.classify": engine(),
     "model.fork": engine(),
-    "audio.play": surface,
-    "audio.speak": surface,
+    "audio.play": surface(),
+    "audio.speak": surface(),
     "mcp.call": engine(),
     "mcp.connect": engine(),
     "session.cwd": engine(method(true)),
@@ -131,27 +143,27 @@ export const MOD_EVENT_TABLE = Object.freeze({
     "session.usage": engine(),
     "session.version": engine(),
     "turn.abort": engine(),
-    "prompt.read": surface,
+    "prompt.read": surface(method(true)),
     "flag.value": engine(),
     "tool.list": engine(method(true)),
     "tool.register": engine(),
-    "command.list": surface,
-    "command.register": surface,
-    "config.list": surface,
+    "command.list": surface(method(true)),
+    "command.register": surface(method(true)),
+    "config.list": surface(method(true)),
     "agent.list": engine(method(true)),
     "agent.register": engine(),
-    "ui.toast": surface,
-    "ui.status": surface,
-    "ui.log": surface,
-    "ui.notice": surface,
-    "ui.invalidate": surface,
-    "ui.open": surface,
-    "ui.close": surface,
-    "ui.panes": surface,
-    "ui.selection": surface,
-    "ui.copy": surface,
-    "ui.notify": surface,
-    "ui.blit": surface,
+    "ui.toast": surface(method(true)),
+    "ui.status": surface(),
+    "ui.log": surface(method(true)),
+    "ui.notice": surface(method(true)),
+    "ui.invalidate": surface(method(true)),
+    "ui.open": surface(),
+    "ui.close": surface(),
+    "ui.panes": surface(),
+    "ui.selection": surface(method(true)),
+    "ui.copy": surface(method(true)),
+    "ui.notify": surface(),
+    "ui.blit": surface(),
     "fs.read": engine(),
     "fs.write": engine(),
     "fs.list": engine(),
@@ -199,6 +211,18 @@ export function expandModPattern(pattern) {
     }
     return isModEventName(pattern) ? { names: [pattern] } : { refusal: `"${pattern}" is not an event` };
 }
+export function expandOnSide(pattern, side) {
+    const expanded = expandModPattern(pattern);
+    if ("refusal" in expanded)
+        return expanded;
+    const own = expanded.names.filter((n) => readOnSide(n, side));
+    if (own.length > 0)
+        return { names: own };
+    const named = String(pattern);
+    return named.endsWith(".*")
+        ? { refusal: `"${named}" selects no event the ${side} bus reads (${expanded.names.length === 1 ? "its one name is" : "its names are"} the ${MOD_EVENT_TABLE[expanded.names[0]].side} side's)` }
+        : { refusal: `"${named}" is a ${MOD_EVENT_TABLE[expanded.names[0]].side} event, read on that side's bus only — never on the ${side} bus` };
+}
 export function describe(value) {
     if (typeof value === "string")
         return `"${value}"`;

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

@@ -1,6 +1,6 @@
 /** The package entry of `@sema-agent/mods-kernel`; core reads the same modules directly. */
-export { KERNEL_CONTRACT_VERSION, MOD_TIERS, MOD_SEATS, MOD_EVENT_SIDES, MOD_FAILURE_ANSWERS, MOD_ABORT_POSTURES, NEXT_TO_TABLE, SEAT_TIER_TABLE, MOD_EVENT_TABLE, nextToRefusal, expandModPattern, isModEventName, stationOn, readOnSide, type ModTier, type ModRegistrationTier, type ModSeat, type ModEventSide, type ModBusSide, type ModFailureAnswer, type ModAbortPosture, type ModStation, type ModEventRow, type ModEventName, } from "./events.js";
+export { KERNEL_CONTRACT_VERSION, MOD_TIERS, MOD_SEATS, MOD_EVENT_SIDES, MOD_FAILURE_ANSWERS, MOD_ABORT_POSTURES, NEXT_TO_TABLE, SEAT_TIER_TABLE, MOD_EVENT_TABLE, nextToRefusal, expandModPattern, expandOnSide, failureRefuses, isModEventName, stationOn, readOnSide, type ModTier, type ModRegistrationTier, type ModSeat, type ModEventSide, type ModBusSide, type ModFailureAnswer, type ModAbortPosture, type ModStation, type ModEventRow, type ModEventName, } from "./events.js";
 export { DEFAULT_MOD_BUDGET_MS, CATCH_BUDGET_MS, RUNAWAY_AFTER_MS, POST_ABORT_GRACE_MS, MAX_TIMER_MS, resolveModBudgetMs, type ModBudgetReading, } from "./budget.js";
-export { MOD_FAILURE_CAUSES, type ModFailureCause, type ModEventPayload, type ModAnswerCheck, type ModAnswerer, type ModMatcher, type ModSkip } from "./site-rules.js";
-export { ENGINE_ORIGIN, MODS_INVALID_CODE, MODS_REGISTRATION_REFUSED_CODE, MOD_TRACE_OUTCOMES, type ModTraceOutcome, type ModUses, type ModOrigin, type ModPluginFacts, type ModDollarBase, type ModTraceEntry, type ModCaughtError, type ModNext, type ModHandler, type ModHandlerOptions, type On, type ModRegistration, type ModAdmissionRecord, type ModSeats, } from "./registration.js";
-export { admitMods, type ModFrame, type ModBottomContext, type ModMethodBottom, type ModMethodSeat, type ModMethodBottoms, type ModDispatchOutcome, type ModDispatchOptions, type ModBus, type ModMountedHandler, type ModBusInput, } from "./dispatch.js";
+export { MOD_FAILURE_CAUSES, type ModFailureCause, type ModEventPayload, type ModAnswerCheck, type ModAnswerRanks, type ModDispatchRun, type ModAnswerer, type ModMatcher, type ModSkip, } from "./site-rules.js";
+export { ENGINE_ORIGIN, MODS_INVALID_CODE, MODS_REGISTRATION_REFUSED_CODE, MOD_TRACE_OUTCOMES, type ModTraceOutcome, type ModUses, type ModOrigin, type ModPluginFacts, type ModDollarBase, type ModTraceEntry, type ModCaughtError, type ModNext, type ModHandler, type ModHandlerOptions, type ModEventPair, type ModEventMap, type ModTypedNext, type ModTypedHandler, type On, type MappedOn, type ModRegistration, type ModAdmissionRecord, type ModSeats, } from "./registration.js";
+export { admitMods, type ModFrame, type ModBottomContext, type ModMethodBottom, type ModMethodSeat, type ModMethodBottoms, type ModCallEntry, type ModCallEntries, type ModDispatchOutcome, type ModDispatchOptions, type ModBus, type ModMountedHandler, type ModBusInput, } from "./dispatch.js";

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

@@ -1,5 +1,5 @@
-export { KERNEL_CONTRACT_VERSION, MOD_TIERS, MOD_SEATS, MOD_EVENT_SIDES, MOD_FAILURE_ANSWERS, MOD_ABORT_POSTURES, NEXT_TO_TABLE, SEAT_TIER_TABLE, MOD_EVENT_TABLE, nextToRefusal, expandModPattern, isModEventName, stationOn, readOnSide, } from "./events.js";
+export { KERNEL_CONTRACT_VERSION, MOD_TIERS, MOD_SEATS, MOD_EVENT_SIDES, MOD_FAILURE_ANSWERS, MOD_ABORT_POSTURES, NEXT_TO_TABLE, SEAT_TIER_TABLE, MOD_EVENT_TABLE, nextToRefusal, expandModPattern, expandOnSide, failureRefuses, isModEventName, stationOn, readOnSide, } from "./events.js";
 export { DEFAULT_MOD_BUDGET_MS, CATCH_BUDGET_MS, RUNAWAY_AFTER_MS, POST_ABORT_GRACE_MS, MAX_TIMER_MS, resolveModBudgetMs, } from "./budget.js";
-export { MOD_FAILURE_CAUSES } from "./site-rules.js";
+export { MOD_FAILURE_CAUSES, } from "./site-rules.js";
 export { ENGINE_ORIGIN, MODS_INVALID_CODE, MODS_REGISTRATION_REFUSED_CODE, MOD_TRACE_OUTCOMES, } from "./registration.js";
 export { admitMods, } from "./dispatch.js";

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

@@ -1,16 +1,18 @@
 /**
  * The ONE receipt of a caller's object: how a value someone else's code built becomes a value the receiver owns.
  * Every reader of a caller's object reads it here — a constructor's configuration (`new Runner`'s deps, a brain's
- * config), a station's answer record, a mods handler's payload and answer — each with its own mode, never its own
+ * config), a station's answer record, a mods handler's payload and answer, what a tool's `execute` returns — each with its own mode, never its own
  * copy of the walk.
  *
  * The walk: a primitive is itself. A CONTAINER — an ordinary record (prototype `Object.prototype` or none) or an
  * ordinary array — within `depth` levels is copied member by member off its own property descriptors, captured in
- * one call before any of the caller's code can run; each member lands as an enumerable data property of the copy (a
- * defined property, never an assignment, so an own `__proto__` key stays a plain key). Anything else — a function, an
+ * one call before any of the caller's code can run (under `wire`, read live in the order `JSON.stringify` reads them); each
+ * member lands as an enumerable data property of the copy, which is filled on no prototype (so no setter up a chain runs and
+ * an own `__proto__` key stays a plain key) and handed its ordinary prototype when full. Anything else — a function, an
  * object of another prototype, a container past `depth` — is handed as it is, refused, or (an object of another
  * prototype under `copy`) copied off its own members like a record, by `others`, which also says whether cycles and
- * shared references keep their shape or are refused / walked again. A refusal refuses the whole receipt, or — under
+ * shared references keep their shape or are refused / walked again (and `leaves` whether what is handed on is a structured
+ * clone of itself; `wire`, whether the members are those the JSON wire reads). A refusal refuses the whole receipt, or — under
  * `contain` — only the member it was met in. The walk keeps its own stack (one frame per container being copied), so
  * neither how deep a value nests nor how deep its caller already stands decides a verdict: only `depth` does.
  *
@@ -55,6 +57,19 @@ export interface ReceiptMode {
     readonly contain?: true;
     /** Every container the copy makes is frozen (a received value cannot be changed after it was received). */
     readonly freeze?: boolean;
+    /** The members are the ones the JSON wire carries, read as it reads them, and none of the caller's serializers runs
+     *  (`accessors: "call-once"` only): a record's members are its own enumerable ones (a non-enumerable one is never read), a
+     *  list's its indices (another own member of a list is never read), named when the container is met and each read live, in
+     *  order, walked to its end before the next (a dense list or a record; a sparse list off its own members); an object that
+     *  would be serialized through a `toJSON` (found off
+     *  property descriptors up its prototype chain, nothing run) is not data — refused as `not-data`, its members with it —
+     *  except the platform's own `Date.prototype.toJSON` (by identity), whose answer the receipt reads off the date's own
+     *  time value (an ISO string, or `null` for an invalid date), never through a method the object could override. */
+    readonly wire?: true;
+    /** Under `others: "as-is"`, an object that is not copied is replaced by a structured clone of that object alone (one
+     *  clone per object, so a shared one stays shared); a function, and an object the clone refuses (a handle, a class
+     *  instance holding a function), are handed as they are. */
+    readonly leaves?: "cloned";
     /** The host's Proxy probe. */
     readonly isProxy?: (value: object) => boolean;
 }
@@ -79,12 +94,20 @@ export type Receipt = {
 };
 /** Whether `v` is an ordinary record: an object whose prototype is `Object.prototype` or none (an array is not one). */
 export declare function isPlainRecord(v: unknown): v is Record<string, unknown>;
+/** A data member's descriptor, itself on no prototype: a definition reads `get` / `set` / `value` … off its descriptor, and one
+ *  inherited from `Object.prototype` would be read (and run). */
+export declare function dataMember(value: unknown): PropertyDescriptor;
+/** `value` as the next member of an engine-owned list — defined, never assigned, so a setter some prototype holds at that index
+ *  never runs (a `push` or an assignment to a new index asks the prototype chain first). */
+export declare function appendOwn<T>(list: T[], value: T): void;
 /**
  * Receive `value` by `mode`. `held` names objects the reader already owns: met in the walk, each is kept as itself — not
  * received again, never walked — so a member handed back unchanged keeps its identity. The set is consulted as it is,
  * never copied, so one set serves every receipt of the same owner.
  */
-export declare function receive(value: unknown, mode: ReceiptMode, held?: ReadonlySet<object>): Receipt;
+export declare function receive(value: unknown, mode: ReceiptMode, held?: {
+    has(value: object): boolean;
+}): Receipt;
 /** The mods bus's mode: a payload and an answer received whole — no accessor runs, no depth limit, cycles and shared
  *  references kept, a function or a class instance handed as it is, every copied container frozen (so a member the
  *  bus holds cannot be changed under it by a handler that holds it too). The engine's own event is received in it as it
@@ -93,3 +116,14 @@ export declare function receive(value: unknown, mode: ReceiptMode, held?: Readon
 export declare const MODS_PAYLOAD_MODE: ReceiptMode;
 /** One clause naming a fault for a sentence ("an accessor at input.deep.x"). */
 export declare function describeFault(fault: ReceiptFault): string;
+/**
+ * The SEALED objects reachable from `roots`: every ordinary record or array whose whole graph is frozen data — frozen, of
+ * the ordinary prototype, every member an enumerable string-keyed data property holding a primitive (no symbol, no
+ * bigint) or another sealed object. Nothing in such a graph can change, so an answer may hold one as itself and the
+ * station's every read of it reads what was checked. Read off property descriptors (no getter ever runs), by an explicit
+ * stack (no depth decides); a cycle of frozen data is sealed. An object of another kind, an unfrozen container and every
+ * container that reaches one is not sealed: an answer holding it is received like any other value (copied as data, or
+ * refused); a sealed object an unfrozen container holds is still found. Taken as a snapshot at the moment it is asked —
+ * what a handler later freezes is not in it.
+ */
+export declare function sealedObjects(roots: readonly unknown[]): ReadonlySet<object>;