@nathapp/nax-agent 0.1.0

package/dist/native/session/loop-events/registry.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The native session's in-process loop event seam (nax#2151, US-002).
+ *
+ * Typed function registrations, not an extension of `src/hooks/`: those events
+ * fire around a story, shell out with a 5s timeout, and cannot carry a
+ * rewritten tool result. Two events exist because two have real consumers
+ * today — invalid-call repair and the spin breaker on `before_tool`, and the
+ * truncation policy on `after_tool`.
+ *
+ * The dispatcher enforces four rules rather than leaving them to handler
+ * authors, because those rules are what let a future event be added without
+ * redesigning the seam:
+ *
+ *  1. Results are partial patches, never mutations. A handler returns only what
+ *     it wants changed and the dispatcher merges. Payloads carry the live
+ *     message array, readonly-TYPED only — mutation is not prevented at
+ *     runtime; what §3 enforces mechanically is history REWRITING across the
+ *     cache boundary, not object immutability.
+ *  2. Handlers chain, each seeing the previous handler's output, in
+ *     registration order.
+ *  3. A throwing handler is logged at warn and skipped — it never fails the
+ *     turn for its own defect. A rejected promise counts as a throw (spec
+ *     4.2): the await sits inside the try, so a handler whose promise rejects
+ *     is logged-and-skipped identically to one that throws — a bare try/catch
+ *     catches only the throw.
+ *  4. No handler may rewrite history. Measured prompt-cache hit rate on the
+ *     native path is 96.7%, and Anthropic-style caching is prefix-matched, so
+ *     rewriting anything early in the array re-bills every downstream turn at
+ *     input rather than cacheRead — roughly 5x more expensive, not cheaper.
+ *     `after_tool` is safe by construction: it shapes a result before the
+ *     result enters the array. Across the full event set that safety is no
+ *     longer left to construction — the cache-boundary checker (spec 4.7, §3)
+ *     enforces it mechanically.
+ */
+import type { BeforeToolOutcome, HandlerOf, LoopEvent, PatchOf, PayloadOf } from "./types.ts";
+export interface LoopEventRegistry {
+    register<E extends LoopEvent>(event: E, handler: HandlerOf<E>): void;
+    dispatch<E extends LoopEvent>(event: E, payload: PayloadOf<E>): Promise<PatchOf<E>>;
+}
+/**
+ * The event names, at runtime (US-001).
+ *
+ * A plugin's registration is validated against this set before it is staged,
+ * because an event name arriving from a plugin is `unknown` until then. The
+ * list is read off `PATCHABLE_FIELDS` rather than written out again: that map
+ * is pinned to `LoopEvent` in both directions — a missing event fails the
+ * `satisfies` clause, an extra one fails the field map's exhaustiveness pin —
+ * so its keys are the event set, and a second hand-written copy cannot drift
+ * out of step with the type.
+ */
+export declare const LOOP_EVENTS: readonly LoopEvent[];
+/**
+ * US-002: is this a well-formed `before_tool` outcome?
+ *
+ * A plugin module is plain JavaScript and can answer anything at all — a
+ * string, `null`, an array, or an object whose `kind` is not a decision. What
+ * makes an answer an outcome is its SHAPE, not merely its object-ness, so the
+ * dispatcher and `wrapExternalHandler` ask this one question rather than each
+ * holding a half of it.
+ *
+ * This checks the `kind` only. The dispatcher also calls it on built-in
+ * handlers, whose return type already guarantees the kind's payload, so
+ * requiring the payload here would reject a built-in that a mutable test
+ * fixture handed an out-of-type value. The untrusted boundary — a plugin's
+ * answer — additionally needs the payload and is checked by
+ * `isCompleteBeforeToolOutcome`.
+ */
+export declare function isBeforeToolOutcome(value: unknown): value is BeforeToolOutcome;
+/**
+ * Is this a plugin answer that carries everything its `kind` promises? A
+ * `kind` alone is not enough: `block`/`terminate` must carry the `content` the
+ * loop records as the call's result, and `nudge` must carry the `text` it
+ * appends. A plugin answering `{ kind: "block" }` with nothing to say would
+ * otherwise reach the transcript builder as `content: undefined`, and a
+ * textless `nudge` would be silently downgraded to `allow` — so both are
+ * malformed, exactly like a `kind` that is not a decision.
+ */
+export declare function isCompleteBeforeToolOutcome(value: unknown): value is BeforeToolOutcome;
+/**
+ * Registration order is the chain order within each event; events are
+ * independent chains. The built-ins register on the same registry the loop
+ * dispatches from (see ./loop-handlers for their per-turn lifetime).
+ */
+export declare function createLoopEventRegistry(): LoopEventRegistry;

package/dist/native/session/loop-events/registry.js

@@ -0,0 +1,305 @@
+/**
+ * The native session's in-process loop event seam (nax#2151, US-002).
+ *
+ * Typed function registrations, not an extension of `src/hooks/`: those events
+ * fire around a story, shell out with a 5s timeout, and cannot carry a
+ * rewritten tool result. Two events exist because two have real consumers
+ * today — invalid-call repair and the spin breaker on `before_tool`, and the
+ * truncation policy on `after_tool`.
+ *
+ * The dispatcher enforces four rules rather than leaving them to handler
+ * authors, because those rules are what let a future event be added without
+ * redesigning the seam:
+ *
+ *  1. Results are partial patches, never mutations. A handler returns only what
+ *     it wants changed and the dispatcher merges. Payloads carry the live
+ *     message array, readonly-TYPED only — mutation is not prevented at
+ *     runtime; what §3 enforces mechanically is history REWRITING across the
+ *     cache boundary, not object immutability.
+ *  2. Handlers chain, each seeing the previous handler's output, in
+ *     registration order.
+ *  3. A throwing handler is logged at warn and skipped — it never fails the
+ *     turn for its own defect. A rejected promise counts as a throw (spec
+ *     4.2): the await sits inside the try, so a handler whose promise rejects
+ *     is logged-and-skipped identically to one that throws — a bare try/catch
+ *     catches only the throw.
+ *  4. No handler may rewrite history. Measured prompt-cache hit rate on the
+ *     native path is 96.7%, and Anthropic-style caching is prefix-matched, so
+ *     rewriting anything early in the array re-bills every downstream turn at
+ *     input rather than cacheRead — roughly 5x more expensive, not cheaper.
+ *     `after_tool` is safe by construction: it shapes a result before the
+ *     result enters the array. Across the full event set that safety is no
+ *     longer left to construction — the cache-boundary checker (spec 4.7, §3)
+ *     enforces it mechanically.
+ */
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger } from "#src/infra/index";
+import { isThenable } from "#src/internal/thenable";
+import { restoreMutated, snapshotArrays } from "./payload-guard.js";
+/**
+ * The fields each event's patch type declares, keyed by event. Only these are
+ * read off a handler's return, so a handler that bypasses the type cannot
+ * surface a non-patchable field. Two compile-time pins keep this map aligned
+ * with the patch types in `./types`, in both directions:
+ *
+ *  - the `satisfies` pins every event to an entry whose members are valid
+ *    patch keys for that event;
+ *  - `_patchableFieldsExhaustive` below pins the converse — every patch key
+ *    appears under its own event.
+ *
+ * Together: a patch field must appear here, or typecheck fails — either
+ * because the entry is invalid, or because the field was added to a patch
+ * type without an entry. The second direction is the load-bearing one: an
+ * unlisted field compiles fine on the type and would be silently stripped by
+ * `pickPatchFields`, which is exactly the failure this map exists to make
+ * impossible.
+ */
+const PATCHABLE_FIELDS = {
+    // A decision, not a field patch — chained in dispatchBeforeTool below.
+    before_tool: [],
+    after_tool: ["content", "isError"],
+    before_turn: ["seed", "history"],
+    transform_context: ["messages"],
+    before_request: ["options"],
+    after_response: ["text", "toolCalls", "thinking"],
+    before_compaction: ["decline", "summary"],
+    before_turn_end: ["followUp"],
+};
+/**
+ * The event names, at runtime (US-001).
+ *
+ * A plugin's registration is validated against this set before it is staged,
+ * because an event name arriving from a plugin is `unknown` until then. The
+ * list is read off `PATCHABLE_FIELDS` rather than written out again: that map
+ * is pinned to `LoopEvent` in both directions — a missing event fails the
+ * `satisfies` clause, an extra one fails the field map's exhaustiveness pin —
+ * so its keys are the event set, and a second hand-written copy cannot drift
+ * out of step with the type.
+ */
+export const LOOP_EVENTS = Object.freeze(Object.keys(PATCHABLE_FIELDS));
+/**
+ * Only the patchable fields are read, so a handler that returns a
+ * denied-bearing object (bypassing the type) cannot surface one — the same
+ * defence keeps `usage` off an `after_response` patch, and every other event's
+ * surfaced-only fields out of its patch.
+ */
+function pickPatchFields(returned, fields) {
+    if (typeof returned !== "object" || returned === null)
+        return {};
+    const source = returned;
+    const picked = {};
+    for (const field of fields) {
+        const value = source[field];
+        if (value !== undefined)
+            picked[field] = value;
+    }
+    return picked;
+}
+/** The four kinds that make a `before_tool` answer an outcome, and nothing else. */
+const BEFORE_TOOL_KINDS = ["allow", "nudge", "block", "terminate"];
+/**
+ * US-002: is this a well-formed `before_tool` outcome?
+ *
+ * A plugin module is plain JavaScript and can answer anything at all — a
+ * string, `null`, an array, or an object whose `kind` is not a decision. What
+ * makes an answer an outcome is its SHAPE, not merely its object-ness, so the
+ * dispatcher and `wrapExternalHandler` ask this one question rather than each
+ * holding a half of it.
+ *
+ * This checks the `kind` only. The dispatcher also calls it on built-in
+ * handlers, whose return type already guarantees the kind's payload, so
+ * requiring the payload here would reject a built-in that a mutable test
+ * fixture handed an out-of-type value. The untrusted boundary — a plugin's
+ * answer — additionally needs the payload and is checked by
+ * `isCompleteBeforeToolOutcome`.
+ */
+export function isBeforeToolOutcome(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const kind = value.kind;
+    return typeof kind === "string" && BEFORE_TOOL_KINDS.includes(kind);
+}
+/**
+ * Is this a plugin answer that carries everything its `kind` promises? A
+ * `kind` alone is not enough: `block`/`terminate` must carry the `content` the
+ * loop records as the call's result, and `nudge` must carry the `text` it
+ * appends. A plugin answering `{ kind: "block" }` with nothing to say would
+ * otherwise reach the transcript builder as `content: undefined`, and a
+ * textless `nudge` would be silently downgraded to `allow` — so both are
+ * malformed, exactly like a `kind` that is not a decision.
+ */
+export function isCompleteBeforeToolOutcome(value) {
+    if (!isBeforeToolOutcome(value))
+        return false;
+    const outcome = value;
+    if (value.kind === "block" || value.kind === "terminate")
+        return typeof outcome.content === "string";
+    if (value.kind === "nudge")
+        return typeof outcome.text === "string";
+    return true;
+}
+/**
+ * A handler's answer arrives typed, but its `kind` may be missing or invented,
+ * and reading `kind` off such an answer is a dereference the dispatcher must
+ * not do: it would throw out of a seam whose whole contract is that it never
+ * fails the turn, and it would do so OUTSIDE the handler's try (US-002).
+ */
+function asOutcome(returned, tool) {
+    if (isBeforeToolOutcome(returned))
+        return returned;
+    getSafeLogger()?.warn("native-loop-events", "before_tool handler answered no valid outcome; treating it as allow", {
+        tool,
+    });
+    return { kind: "allow" };
+}
+/**
+ * Registration order is the chain order. `block` and `terminate` are a single
+ * decision, not a chained one: they short-circuit, because the outcome is the
+ * dispatcher's verdict and a later handler must not be able to veto it.
+ *
+ * `before_tool` is the one event whose patch is a DECISION, not a field patch,
+ * so it does not share the merge chain: an empty chain must still yield a
+ * verdict (`allow`, exactly as the pre-map dispatcher returned), and the thing
+ * a later handler sees is the accumulated input rewrite inside the call, not a
+ * merged payload.
+ */
+async function dispatchBeforeTool(handlers, payload) {
+    const { call, tools } = payload;
+    let input;
+    let nudgeText;
+    for (const [index, handler] of handlers.entries()) {
+        let returned;
+        const snapshot = snapshotArrays({ tools });
+        try {
+            // Each handler sees the previous handler's output, so an `allow`
+            // rewrite is what the next one judges — and what the loop runs.
+            //
+            // Invoke synchronously and await ONLY a real thenable. The two built-in
+            // handlers ahead of the plugin entries answer synchronously; awaiting
+            // them would yield a microtask before a plugin wrapper is invoked, and
+            // its abort subscription is installed when it is called. An abort
+            // landing in that gap would then be missed and a never-settling plugin
+            // handler would run to its deadline instead of blocking promptly
+            // (nax#2151 US-003). A thenable is still awaited inside the try, so a
+            // rejection is caught exactly like a throw (spec 4.2).
+            const candidate = handler({
+                call: { ...call, input: input ?? call.input },
+                tools,
+            });
+            returned = isThenable(candidate) ? await candidate : candidate;
+        }
+        catch (err) {
+            getSafeLogger()?.warn("native-loop-events", "before_tool handler threw; skipping it", {
+                tool: call.name,
+                error: errorMessage(err),
+            });
+            continue;
+        }
+        finally {
+            restoreMutated(snapshot, "before_tool", index);
+        }
+        const outcome = asOutcome(returned, call.name);
+        if (outcome.kind === "block" || outcome.kind === "terminate")
+            return outcome;
+        if (outcome.kind === "nudge")
+            nudgeText = outcome.text;
+        if (outcome.input !== undefined)
+            input = outcome.input;
+    }
+    // The nudge carries the accumulated rewrite: a nudged call still runs, so
+    // dropping the rewrite would run the model's uncorrected input. The
+    // built-in chain produces this pair — the invalid-call repair strips a
+    // `null` optional, then the spin breaker nudges a repeat of it (nax#2200).
+    if (nudgeText !== undefined) {
+        return input === undefined ? { kind: "nudge", text: nudgeText } : { kind: "nudge", text: nudgeText, input };
+    }
+    return input === undefined ? { kind: "allow" } : { kind: "allow", input };
+}
+/**
+ * The seven field-patch events. Serial `for`, each handler awaited INSIDE the
+ * try (spec 4.2), patches accumulated in registration order, each handler
+ * seeing the previous one's output as the payload it is handed.
+ */
+async function dispatchChain(event, handlers, payload) {
+    if (handlers.length === 0) {
+        // The empty fast path returns BEFORE touching the payload — never clone:
+        // transform_context fires before every request against a 200k+ token
+        // array, and cloning for an empty chain would make every request
+        // allocate a full copy for nothing (spec 4.4).
+        return {};
+    }
+    const fields = PATCHABLE_FIELDS[event];
+    let current = payload;
+    let accumulated = {};
+    for (const [index, handler] of handlers.entries()) {
+        const snapshot = snapshotArrays(current);
+        let returned;
+        try {
+            // The await sits inside the try, so a rejected promise is caught
+            // exactly like a throw (spec 4.2).
+            returned = await handler(current);
+        }
+        catch (err) {
+            // When the payload carries a tool name (after_tool does), the warn
+            // names the tool the failing handler was shaping — the context the
+            // first-argument dispatcher carried as `tool: call.name` before the
+            // single-payload signature replaced it.
+            const { toolName } = payload;
+            getSafeLogger()?.warn("native-loop-events", `${event} handler threw; skipping it`, {
+                event,
+                ...(toolName !== undefined ? { tool: toolName } : {}),
+                error: errorMessage(err),
+            });
+            continue;
+        }
+        finally {
+            restoreMutated(snapshot, event, index);
+        }
+        const picked = pickPatchFields(returned, fields);
+        if (Object.keys(picked).length > 0) {
+            // `before_request.options` is itself a partial patch. Preserve fields
+            // supplied by earlier handlers so independently registered policy hooks
+            // compose (for example, one can set temperature while another disables
+            // thinking for a retry).
+            const merged = event === "before_request" && typeof picked.options === "object" && picked.options !== null
+                ? { ...picked, options: { ...current.options, ...picked.options } }
+                : picked;
+            accumulated = { ...accumulated, ...merged };
+            // Only patch-declared fields ever overwrite anything, so the next
+            // handler sees the previous handler's output and nothing else moved.
+            current = { ...current, ...merged };
+        }
+    }
+    // Sound: `accumulated` holds only fields PATCHABLE_FIELDS declares for this
+    // event, which is exactly what PatchOf<E> declares.
+    return accumulated;
+}
+/**
+ * Registration order is the chain order within each event; events are
+ * independent chains. The built-ins register on the same registry the loop
+ * dispatches from (see ./loop-handlers for their per-turn lifetime).
+ */
+export function createLoopEventRegistry() {
+    const byEvent = new Map();
+    return {
+        register(event, handler) {
+            // Erase E for storage: the map keys by event, and dispatch only ever
+            // calls a handler back with the payload type it registered for, so the
+            // widening loses nothing at the call sites.
+            const erased = handler;
+            const handlers = byEvent.get(event);
+            if (handlers === undefined) {
+                byEvent.set(event, [erased]);
+                return;
+            }
+            handlers.push(erased);
+        },
+        async dispatch(event, payload) {
+            const handlers = byEvent.get(event) ?? [];
+            if (event === "before_tool") {
+                return dispatchBeforeTool(handlers, payload);
+            }
+            return dispatchChain(event, handlers, payload);
+        },
+    };
+}

package/dist/native/session/loop-events/types.d.ts

@@ -0,0 +1,251 @@
+/**
+ * The native session's loop-event map (nax#2151, P3).
+ *
+ * pi's `before_run`/`before_run_end` are `before_turn`/`before_turn_end` here:
+ * `runNativeTurn` is ONE TURN, while a nax "run" holds many stories each
+ * holding many turns, and `src/hooks/` already fires genuine run-level events.
+ * Keeping the vocabularies disjoint is the same reasoning ADR-030's D11 applied
+ * to the bash mode axis.
+ *
+ * `before_payload`, `before_drive` and `before_navigation` are deliberately
+ * absent: the payload is built inside nax-ai behind the import boundary, and
+ * nax has no branch navigation.
+ */
+import type { ThinkingBlock, ToolCall, ToolDefinition } from "@nathapp/nax-ai";
+import type { TokenUsage } from "#src/cost/standard-types";
+import type { TranscriptMessage as NativeTranscriptMessage } from "../compaction.ts";
+import type { DenialInfo } from "../tool-result.ts";
+export type LoopEvent = "before_tool" | "after_tool" | "before_turn" | "transform_context" | "before_request" | "after_response" | "before_compaction" | "before_turn_end";
+export interface BeforeToolPayload {
+    readonly call: ToolCall;
+    readonly tools: readonly ToolDefinition[];
+}
+/**
+ * `before_tool` outcomes:
+ *
+ * - `allow` optionally rewrites the tool's input; later handlers see the
+ *   rewrite, and the loop records it in the transcript and invokes the tool
+ *   with it.
+ * - `nudge` still invokes the tool, and prefixes its result with the handler's
+ *   text. `input` carries any `allow` rewrite accumulated earlier in the chain,
+ *   so a nudge never drops a correction — the null-optional strip ahead of the
+ *   spin breaker is the built-in pair (nax#2200).
+ * - `block` answers without invoking the tool. `input` optionally carries the
+ *   input the transcript should record instead, which is how the invalid-call
+ *   repair keeps the rejected value out of history (nax#2047) — recording the
+ *   model's call minus that property, never a fabricated one (nax#2200).
+ * - `terminate` answers every outstanding call in the current batch — the spin
+ *   breaker's stop is a batch-level outcome, not a per-call one, and a batch
+ *   left with an unanswered `tool_call` is rejected by strict providers.
+ */
+export type BeforeToolOutcome = {
+    kind: "allow";
+    input?: Record<string, unknown>;
+} | {
+    kind: "nudge";
+    text: string;
+    input?: Record<string, unknown>;
+} | {
+    kind: "block";
+    content: string;
+    isError?: boolean;
+    input?: Record<string, unknown>;
+} | {
+    kind: "terminate";
+    content: string;
+    isError?: boolean;
+};
+/**
+ * What an `after_tool` handler may change. Deliberately partial: a handler
+ * returns only the fields it wants patched.
+ *
+ * `denied` is NOT patchable — a refused Write is not a crashed Write (ADR-029
+ * s5), and letting a handler flip that erases a distinction the model is meant
+ * to act on.
+ */
+export type AfterToolPatch = {
+    content?: string;
+    isError?: boolean;
+};
+export interface AfterToolPayload {
+    readonly content: string;
+    readonly isError?: boolean;
+    /** Surfaced to handlers, never writable by them. */
+    readonly denied?: DenialInfo;
+    /** The name of the tool call the result answers, from the dispatched call. */
+    readonly toolName?: string;
+    /** The provider tool-call id the result answers, from the dispatched call. */
+    readonly callId?: string;
+    /**
+     * Present when `before_tool` produced a nudge that will be PREPENDED to the
+     * surviving content. The model-facing truncation handler spends these bytes
+     * out of the result's own budget (`nudgeOverheadBytes`), so the ceiling
+     * stays unconditional — without them a nudged result would exceed
+     * `MODEL_MAX_BYTES` by exactly the nudge's width.
+     */
+    readonly nudgeText?: string;
+}
+/** `before_turn` — fires once as a turn starts, after the transcript loads. */
+export interface BeforeTurnPayload {
+    readonly prompt: string;
+    /** The loaded transcript. Readonly: only a boundary rewrite may touch it. */
+    readonly history: readonly NativeTranscriptMessage[];
+    readonly sessionName: string;
+    /** Dispatcher-computed (spec 3.4). A handler may never assert a boundary. */
+    readonly boundary: boolean;
+}
+export interface BeforeTurnPatch {
+    /** The seed messages being appended now. */
+    readonly seed?: readonly NativeTranscriptMessage[];
+    /** Honoured ONLY when payload.boundary is true (spec 3.2, 6.1). */
+    readonly history?: readonly NativeTranscriptMessage[];
+}
+/** `transform_context` — fires before every provider request attempt. */
+export interface TransformContextPayload {
+    readonly messages: readonly NativeTranscriptMessage[];
+    readonly tools: readonly ToolDefinition[];
+    readonly model?: string;
+    readonly anchorIndex?: number;
+    readonly boundary: boolean;
+}
+export interface TransformContextPatch {
+    readonly messages?: readonly NativeTranscriptMessage[];
+}
+/** `before_request` — per request ATTEMPT, including transport retries. */
+export interface BeforeRequestPayload {
+    readonly model?: string;
+    readonly roundTrip: number;
+    /** 1 for the first attempt, 2..n inside retryTransportFault. */
+    readonly attempt: number;
+    readonly options: CompleteCallOptions;
+}
+export interface BeforeRequestPatch {
+    readonly options?: Partial<CompleteCallOptions>;
+}
+/**
+ * The per-call options bag added to TurnDeps.complete in Task 4 (spec 6.3).
+ * Minimal and additive by ruling: P6's extraction inherits one optional
+ * parameter, not a new concept.
+ */
+export interface CompleteCallOptions {
+    readonly thinking?: boolean;
+    readonly temperature?: number;
+}
+/** `after_response` — fires on a settled assistant message. */
+export interface AfterResponsePayload {
+    readonly text: string;
+    readonly toolCalls?: readonly ToolCall[];
+    readonly thinking?: readonly ThinkingBlock[];
+    /** Surfaced, NEVER patchable: billing truth is not a handler's to rewrite. */
+    readonly usage: TokenUsage;
+    readonly costUsd: number;
+    readonly roundTrip: number;
+}
+export interface AfterResponsePatch {
+    readonly text?: string;
+    readonly toolCalls?: readonly ToolCall[];
+    readonly thinking?: readonly ThinkingBlock[];
+}
+/** `before_compaction` — fires in both the proactive and overflow branches. */
+export interface BeforeCompactionPayload {
+    readonly reason: "proactive" | "overflow";
+    readonly toSummarize: readonly NativeTranscriptMessage[];
+    readonly previousSummary?: string;
+    readonly estimatedTokens: number;
+}
+export interface BeforeCompactionPatch {
+    /** Honoured when reason is "proactive", IGNORED + logged when "overflow". */
+    readonly decline?: boolean;
+    /** A replacement summary, skipping the summarizer call. */
+    readonly summary?: string;
+}
+/** `before_turn_end` — fires before the final saveTranscript. */
+export interface BeforeTurnEndPayload {
+    readonly messages: readonly NativeTranscriptMessage[];
+    readonly roundTrips: number;
+    /**
+     * How the turn ended. "completed" includes a stop (spin, invalid-call budget,
+     * deadline) -- see `stopped`. "aborted" means the turn signal fired (caller,
+     * idle watchdog or whole-turn deadline); "errored" is any other throw.
+     * On "aborted"/"errored" the result is ignored (review #20).
+     */
+    readonly ended: "completed" | "aborted" | "errored";
+    /** True when the turn ended by a STOP; followUp is not offered then. */
+    readonly stopped: boolean;
+    readonly followUpsSoFar: number;
+}
+export interface BeforeTurnEndPatch {
+    /** Re-enters the loop with another user turn. Capped; see registry.ts. */
+    readonly followUp?: string;
+}
+export interface LoopEventMap {
+    before_tool: {
+        payload: BeforeToolPayload;
+        patch: BeforeToolOutcome;
+    };
+    after_tool: {
+        payload: AfterToolPayload;
+        patch: AfterToolPatch;
+    };
+    before_turn: {
+        payload: BeforeTurnPayload;
+        patch: BeforeTurnPatch;
+    };
+    transform_context: {
+        payload: TransformContextPayload;
+        patch: TransformContextPatch;
+    };
+    before_request: {
+        payload: BeforeRequestPayload;
+        patch: BeforeRequestPatch;
+    };
+    after_response: {
+        payload: AfterResponsePayload;
+        patch: AfterResponsePatch;
+    };
+    before_compaction: {
+        payload: BeforeCompactionPayload;
+        patch: BeforeCompactionPatch;
+    };
+    before_turn_end: {
+        payload: BeforeTurnEndPayload;
+        patch: BeforeTurnEndPatch;
+    };
+}
+export type PayloadOf<E extends LoopEvent> = LoopEventMap[E]["payload"];
+export type PatchOf<E extends LoopEvent> = LoopEventMap[E]["patch"];
+export type HandlerOf<E extends LoopEvent> = (payload: PayloadOf<E>) => PatchOf<E> | Promise<PatchOf<E>>;
+/**
+ * The read-only facts a plugin handler is handed alongside its payload.
+ *
+ * Owned by the coding-agent side on purpose: a plugin imports these types, and
+ * native code never imports the plugin system. Everything here is a fact about
+ * the session the handler is running in — there is deliberately no abort, no UI
+ * and no config access, so a plugin scopes itself by reading this at runtime
+ * rather than by declaring filters.
+ */
+export interface LoopHandlerContext {
+    readonly sessionName: string;
+    readonly role?: string;
+    readonly storyId?: string;
+    readonly feature?: string;
+    readonly workdir?: string;
+    readonly model?: string;
+    readonly provider?: string;
+}
+/**
+ * A plugin's handler for one event: same payload and patch as a built-in,
+ * plus the context, and `undefined` is a valid "no patch" answer.
+ */
+export type ExternalHandlerOf<E extends LoopEvent> = (payload: PayloadOf<E>, ctx: LoopHandlerContext) => PatchOf<E> | undefined | Promise<PatchOf<E> | undefined>;
+/** One staged registration: which plugin it came from, its event, its handler. */
+export interface LoopHandlerEntry {
+    readonly plugin: string;
+    readonly event: LoopEvent;
+    readonly handler: ExternalHandlerOf<LoopEvent>;
+}
+/**
+ * Every plugin-contributed handler for a run, in install order. The registry
+ * returns this frozen, and an empty set is the normal case.
+ */
+export type LoopHandlerSet = readonly LoopHandlerEntry[];

package/dist/native/session/loop-events/types.js

@@ -0,0 +1,14 @@
+/**
+ * The native session's loop-event map (nax#2151, P3).
+ *
+ * pi's `before_run`/`before_run_end` are `before_turn`/`before_turn_end` here:
+ * `runNativeTurn` is ONE TURN, while a nax "run" holds many stories each
+ * holding many turns, and `src/hooks/` already fires genuine run-level events.
+ * Keeping the vocabularies disjoint is the same reasoning ADR-030's D11 applied
+ * to the bash mode axis.
+ *
+ * `before_payload`, `before_drive` and `before_navigation` are deliberately
+ * absent: the payload is built inside nax-ai behind the import boundary, and
+ * nax has no branch navigation.
+ */
+export {};