@sema-agent/core 7.55.0 → 7.56.0

package/dist/core/memory-engine/layout.js

@@ -1137,16 +1137,20 @@ export const QUARANTINE_DIR = "quarantine";
 const DELETED_TOMBSTONE = "---\ndeleted: true\n---\n";
 export function writeFileNoFollow(path, content) {
     const fd = openSync(path, O_WRONLY | O_CREAT | O_NOFOLLOW, 0o644);
+    let names;
     try {
-        const links = fstatSync(fd).nlink;
-        if (links > 1)
-            throw Object.assign(new Error(`${path} has ${links} names (a hard link) — a write through one name changes the file under the others; not written`), { path });
-        ftruncateSync(fd, 0);
-        writeFileSync(fd, content, "utf8");
+        const opened = fstatSync(fd);
+        names = opened.nlink > 1 && dropStagingSecondNames(path, opened) > 0 ? fstatSync(fd).nlink : opened.nlink;
+        if (names <= 1) {
+            ftruncateSync(fd, 0);
+            writeFileSync(fd, content, "utf8");
+        }
     }
     finally {
         closeSync(fd);
     }
+    if (names > 1)
+        atomicWriteFileSync(path, content);
 }
 export function writeFileNoReplace(path, content) {
     let fd;
@@ -1166,6 +1170,61 @@ export function writeFileNoReplace(path, content) {
     }
     return "written";
 }
+let stagingSeq = 0;
+export function mintStagingName(owner, now) {
+    stagingSeq += 1;
+    return `${owner}.staging-${now()}-${process.pid}-${stagingSeq}`;
+}
+export function stagingNamePattern(owner) {
+    const head = owner === undefined
+        ? String.raw `(?:hold-\d+-[0-9a-f]{12}\.staging-\d+-\d+-\d+|\d+-residue-[^/]+\.md\.staging(?:-\d+-\d+-\d+)?)`
+        : String.raw `${owner.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\.staging-\d+-\d+-\d+`;
+    return new RegExp(String.raw `^${head}(?:\.claim-\d+-\d+)*$`);
+}
+export function claimStaging(stagingPath) {
+    stagingSeq += 1;
+    const claimed = `${stagingPath}.claim-${process.pid}-${stagingSeq}`;
+    try {
+        renameSync(stagingPath, claimed);
+        return claimed;
+    }
+    catch {
+        return stagingPath;
+    }
+}
+export function isSameFile(path, ref) {
+    try {
+        const st = lstatSync(path);
+        return st.isFile() && st.dev === ref.dev && st.ino === ref.ino;
+    }
+    catch {
+        return false;
+    }
+}
+export function dropStagingSecondNames(seat, opened) {
+    const dir = dirname(seat);
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return 0;
+    }
+    const minted = stagingNamePattern();
+    let dropped = 0;
+    for (const name of names) {
+        const at = join(dir, name);
+        if (name === basename(seat) || !minted.test(name) || !isSameFile(at, opened))
+            continue;
+        try {
+            unlinkSync(at);
+            dropped += 1;
+        }
+        catch {
+        }
+    }
+    return dropped;
+}
 function readForVerification(path, maxBytes) {
     let fd;
     try {
@@ -2628,7 +2687,7 @@ export function writeAllSync(fd, data) {
 export function atomicWriteFileSync(path, data) {
     ensureDirExists(dirname(path));
     const tmp = join(dirname(path), `.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`);
-    const fd = openSync(tmp, "w", 0o600);
+    const fd = openSync(tmp, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, 0o600);
     try {
         writeAllSync(fd, data);
         fsyncSync(fd);

package/dist/core/model-seat.d.ts

@@ -49,9 +49,16 @@ export type RoleSpec = ModelRef | {
     select?: import("./select-model.js").ModelCriteria;
     thinking?: ThinkingLevel;
     /**
-     * Optional preset system prompt for this role (e.g. {@link CODE_AGENT_PROMPT} for a dev role).
-     * Used only when the task does not supply its own `TaskSpec.systemPrompt`. Lets coding roles run
-     * a coding prompt while other roles keep the neutral default — without touching the global default.
+     * The role's preset role base, by WORD: which catalog role base (`core/role.base` variant) tasks of this role
+     * are assembled for — `"code"` for a coding role — and their host role. Same closed set and door as
+     * `TaskSpec.promptRole` (`HOST_ROLES`; outside it ⇒ `config.prompt_selector_invalid`, naming `roles.<role>.promptRole`).
+     * The preset applies only when the task names no role base of its own (neither `promptRole` nor `systemPrompt`):
+     * the first source that names one — task, then this preset, then an engine spawner's child persona — decides it.
+     */
+    promptRole?: import("../prompt-assembly/catalog/schema.js").HostRole;
+    /**
+     * The role's preset role base, by TEXT (it replaces the base `promptRole` selects; the role is `promptRole`, else
+     * `general`). Same precedence as `promptRole`: used only when the task names no role base of its own.
      */
     systemPrompt?: string;
 };

package/dist/core/mods/classic-events.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The one typing of the engine's classic stations: each `classic.*` event a station raises, paired with its `e` and its
+ * answer form. Every raise site constructs its `e` against it (`dispatchClassic` / `observeClassic`), and the engine's
+ * registration form types a handler by it. Its keys are the event table's `classic.*` rows that carry a station — the key
+ * set is held to that table.
+ */
+import type { PermissionDeniedPayload, PostCompactEvent, PostToolBatchEvent, PostToolBatchResult, PostToolUseEvent, PostToolUseFailureEvent, PostToolUseFailureResult, PostToolUseResult, PreCompactEvent, PreCompactResult, PreToolUseEvent, PreToolUseResult, StopEvent, StopFailureEvent, StopHookResult, UserPromptSubmitEvent, UserPromptSubmitResult } from "../hooks.js";
+import type { MappedOn, ModRegistration } from "./kernel/index.js";
+import type { EngineDollar } from "./dollar.js";
+/** The answer of an event whose station reads none (an observation event): a chain handler passes `next(e)`'s on. */
+export type ObservedAnswer = Readonly<Record<string, never>>;
+/** Each `classic.*` event a station raises, with its `e` and its answer form. */
+export type ClassicEventMap = {
+    readonly "classic.PreToolUse": {
+        readonly e: PreToolUseEvent;
+        readonly answer: PreToolUseResult | null | false;
+    };
+    readonly "classic.PostToolUse": {
+        readonly e: PostToolUseEvent;
+        readonly answer: PostToolUseResult;
+    };
+    readonly "classic.PostToolUseFailure": {
+        readonly e: PostToolUseFailureEvent;
+        readonly answer: PostToolUseFailureResult;
+    };
+    readonly "classic.PostToolBatch": {
+        readonly e: PostToolBatchEvent;
+        readonly answer: PostToolBatchResult;
+    };
+    readonly "classic.UserPromptSubmit": {
+        readonly e: UserPromptSubmitEvent;
+        readonly answer: UserPromptSubmitResult;
+    };
+    readonly "classic.Stop": {
+        readonly e: StopEvent;
+        readonly answer: StopHookResult;
+    };
+    readonly "classic.SubagentStop": {
+        readonly e: StopEvent;
+        readonly answer: StopHookResult;
+    };
+    readonly "classic.StopFailure": {
+        readonly e: StopFailureEvent;
+        readonly answer: ObservedAnswer;
+    };
+    readonly "classic.PreCompact": {
+        readonly e: PreCompactEvent;
+        readonly answer: PreCompactResult;
+    };
+    readonly "classic.PostCompact": {
+        readonly e: PostCompactEvent;
+        readonly answer: ObservedAnswer;
+    };
+    readonly "classic.PermissionDenied": {
+        readonly e: PermissionDeniedPayload;
+        readonly answer: ObservedAnswer;
+    };
+};
+/** A `classic.*` event a station raises. */
+export type ClassicEventName = keyof ClassicEventMap;
+/**
+ * A registration on the engine's bus (`RunnerDeps.mods`, `TaskSpec.mods`): the kernel's registration form whose `on`
+ * types a handler of a `classic.*` event by {@link ClassicEventMap} — its `e`, its `next`, its answer.
+ */
+export interface EngineModRegistration extends Omit<ModRegistration<EngineDollar>, "register"> {
+    register(on: MappedOn<EngineDollar, ClassicEventMap>, options: unknown): void;
+}

package/dist/core/mods/classic-events.js

@@ -0,0 +1 @@
+export {};

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

@@ -100,10 +100,23 @@ export interface EngineDollar extends ModDollarBase {
     };
     readonly tool: {
         list(): Promise<readonly string[]>;
+        /** `$.tool.call({ tool, ...input })`: the run's own pipeline for one call of a mounted tool (`tool-call.ts`). */
+        call(args: {
+            readonly tool: string;
+        } & Readonly<Record<string, unknown>>): Promise<ToolCallAnswer>;
     };
     readonly agent: {
         list(): Promise<readonly string[]>;
     };
 }
+/** What `$.tool.call` answers — `tool.call`'s own forms: the frozen view of the call's result, or the refusal (returned, not thrown). */
+export type ToolCallAnswer = {
+    readonly result: {
+        readonly content: readonly object[];
+        readonly isError: boolean;
+    };
+} | {
+    readonly deny: string;
+};
 /** The chain bottoms of the wave-one method events over a runner's seat view. */
 export declare function engineMethodBottoms(view: ModSeatView): ModMethodBottoms;

package/dist/core/mods/extension-call.d.ts

@@ -0,0 +1,31 @@
+import { type ModBottomContext, type ModBus } from "./kernel/index.js";
+import type { ExtensionRequester } from "../task-event.js";
+/** One extension's call while it runs. */
+export interface ExtensionCall {
+    /** The leg bus the call was made on (the one {@link legBusOf} returned). */
+    readonly bus: ModBus;
+    readonly toolCallId: string;
+    /** The `$` call's context: the frames its pipeline's events are raised under, and its origin. */
+    readonly caller: ModBottomContext;
+    /** Cleared when the call's pipeline settles — the one reading of "this call is still running". */
+    readonly live: boolean;
+    /** The call's end projection refused it (its latest gate record is a refusal) — written once, by the leg's tool_end station. */
+    readonly denied: boolean;
+}
+/** The running extension call this chain carries for `bus`, when it is the call `toolCallId` names (or any, unnamed). */
+export declare function extensionCallOf(bus: object, toolCallId?: string): ExtensionCall | undefined;
+/** Who asked for the call `toolCallId` names, when it is the running extension call: the one projection every carrier of
+ *  `requestedBy` reads (the occurrence the frames are projected from, the approval card). */
+export declare function requesterOf(bus: object, toolCallId: string): {
+    readonly requestedBy?: ExtensionRequester;
+};
+/** The leg's tool_end station says the call it is closing was refused (a no-op for any call that is not the running extension call). */
+export declare function noteExtensionCallDenied(bus: object, toolCallId: string): void;
+/** Run an extension's call: `pipeline` runs with the call's record in scope; the record stops being live when it settles. */
+export declare function runExtensionCall<T>(bus: ModBus, toolCallId: string, caller: ModBottomContext, pipeline: (call: ExtensionCall) => Promise<T>): Promise<T>;
+/**
+ * The leg bus every station raises on: a dispatch inside a running extension call made on it is raised under that call's
+ * frames and origin (a raiser that names its own frames keeps them — they extend the call's); one raised under a call
+ * that has settled is refused, `failed` by the engine and said once on `report`; any other dispatch is the bus's own.
+ */
+export declare function legBusOf(bus: ModBus, report: (err: Error) => void): ModBus;

package/dist/core/mods/extension-call.js

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { ENGINE_ORIGIN } from "./kernel/index.js";
+const store = new AsyncLocalStorage();
+export function extensionCallOf(bus, toolCallId) {
+    const c = store.getStore();
+    return c !== undefined && c.live && c.bus === bus && (toolCallId === undefined || c.toolCallId === toolCallId) ? c : undefined;
+}
+export function requesterOf(bus, toolCallId) {
+    const c = extensionCallOf(bus, toolCallId);
+    return c !== undefined ? { requestedBy: Object.freeze({ kind: "extension", name: c.caller.origin.plugin }) } : {};
+}
+export function noteExtensionCallDenied(bus, toolCallId) {
+    const c = store.getStore();
+    if (c !== undefined && c.live && c.bus === bus && c.toolCallId === toolCallId)
+        c.denied = true;
+}
+export async function runExtensionCall(bus, toolCallId, caller, pipeline) {
+    const call = { bus, toolCallId, caller, live: true, denied: false };
+    try {
+        return await store.run(call, () => pipeline(call));
+    }
+    finally {
+        call.live = false;
+    }
+}
+export function legBusOf(bus, report) {
+    const leg = {
+        records: bus.records,
+        mounted: () => bus.mounted(),
+        hasHandlers: (event, participant) => bus.hasHandlers(event, participant),
+        dispatch: (event, e, options) => {
+            const c = store.getStore();
+            if (c === undefined || c.bus !== leg || options.frames !== undefined)
+                return bus.dispatch(event, e, options);
+            if (c.live)
+                return bus.dispatch(event, e, { ...options, frames: c.caller.frames, origin: c.caller.origin });
+            const reason = `${event}: raised under extension "${c.caller.origin.plugin}"'s call ${c.toolCallId}, which has ended — an event is not raised under a call that is over`;
+            report(new Error(`engine: ${reason} — the dispatch was not run`));
+            return Promise.resolve(Object.freeze({ kind: "failed", registration: ENGINE_ORIGIN.plugin, cause: "violation", reason, skipped: Object.freeze([]) }));
+        },
+    };
+    return leg;
+}

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

@@ -1,6 +1,6 @@
 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";
+import { type ModAnswerCheck, type ModAnswerRanks, 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";
@@ -28,6 +28,13 @@ export interface ModMethodSeat {
     readonly enter?: (args: ModEventPayload) => ModEventPayload;
 }
 export type ModMethodBottoms = Partial<Record<ModEventName, ModMethodSeat>>;
+/**
+ * A callable event's host entry: what a `$` call of the event reaches. It runs whatever stands before the event and
+ * raises the event once at its own station, under `ctx.frames` and `ctx.origin` (so the caller's own handlers stay out
+ * of that raise); its answer is the call's answer (a `{ deny }` is returned, not thrown) and its throw the caller's.
+ */
+export type ModCallEntry = (args: ModEventPayload, ctx: ModBottomContext) => unknown;
+export type ModCallEntries = Partial<Record<ModEventName, ModCallEntry>>;
 export type ModDispatchOutcome = {
     readonly kind: "answered";
     readonly answer: unknown;
@@ -39,8 +46,12 @@ export type ModDispatchOutcome = {
     readonly cause: ModFailureCause;
     readonly reason: string;
     readonly skipped: readonly ModSkip[];
-} | {
+}
+/** `bottomStarted`: the chain's bottom had started when the dispatch was cancelled — on an effect event, what it did is
+ *  not known from here. */
+ | {
     readonly kind: "aborted";
+    readonly bottomStarted?: true;
 };
 /** What a participant filter sees of one mounted handler: its registration, that registration's seat, and whether it only observes. */
 export interface ModParticipant {
@@ -57,6 +68,9 @@ export interface ModDispatchOptions {
     readonly origin?: ModOrigin;
     /** The raiser's reading of an answer; an answer it refuses is a violation of the site. */
     readonly checkAnswer?: ModAnswerCheck;
+    /** The station's ranking of its answers — named by every dispatch of an event whose failure column refuses (one that
+     *  names none is not run), and read by the seat-trust law. */
+    readonly ranks?: ModAnswerRanks;
     /** 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;
 }
@@ -76,12 +90,15 @@ export interface ModBus {
     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>;
+    /** Raise `event` with the raiser's `e` (an object the bus receives whole, an event map's `e` as it is). */
+    dispatch(event: ModEventName, e: object, options: ModDispatchOptions): Promise<ModDispatchOutcome>;
 }
 export interface ModBusInput<D extends ModDollarBase = ModDollarBase> {
     readonly side: ModBusSide;
     readonly seats: ModSeats<D>;
     readonly bottoms: ModMethodBottoms;
+    /** The host's entries of the callable events its bus raises (absent ⇒ none: a `$` call of such an event throws). */
+    readonly entries?: ModCallEntries;
     /** 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