@nathapp/nax-agent 0.1.0

package/dist/session/adapter-failure.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Failure descriptor returned (or synthesized) by an agent adapter. Part of the
+ * session contract (S1 spec section 4.2, port 2); `context/engine` re-exports it.
+ *
+ * The runner uses this to decide between escalation (quality) and agent
+ * fallback (availability), and passes it to `rebuildForAgent()` so the new
+ * bundle carries a failure-note chunk.
+ *
+ * See: docs/specs/SPEC-context-engine-v2.md §Availability fallback
+ */
+export interface AdapterFailure {
+    /**
+     * "availability" — vendor quota, rate-limit, service down, auth error.
+     *   Triggers agent fallback (same tier, different agent).
+     * "quality" — review/verify rejected output.
+     *   Triggers tier escalation by default; agent fallback is opt-in.
+     */
+    category: "availability" | "quality";
+    /**
+     * Machine-readable outcome code.
+     * availability: fail-quota | fail-service-down | fail-auth | fail-rate-limit | fail-aborted | fail-stale
+     * quality:      fail-timeout | fail-adapter-error | fail-quality | fail-unknown | fail-spin | fail-incomplete
+     *
+     * `fail-aborted` — the run was cancelled via AgentRunOptions.abortSignal
+     * (shutdown in progress). Not retriable; fallback chains should not fire.
+     * `fail-stale` — either (a) the idle watchdog cancelled due to no stream activity
+     * within the configured idle timeout, or (b) the agent finished cleanly with empty
+     * output. The `reason` field distinguishes: "idle-watchdog" vs "empty-output".
+     * Retriable up to maxRetryAttempts.
+     * `fail-spin` — the spin breaker ended the turn: the model kept issuing tool
+     * calls whose shape it had already issued, with no new work between them
+     * (nax#2013). Distinct from `fail-timeout` on purpose — both mean "no usable
+     * answer within the budget", but only this one is measurable as a spin, and
+     * #2013 exists because the failure mode was invisible. Retriable: the retry
+     * opens a fresh session, so the repetition is not carried forward.
+     * `fail-incomplete` — the turn ended with tool calls outstanding (transport's
+     * `turnIncomplete` fact), reachable through `normalizeHopOutput` even when the
+     * turn carries prose (nax#2054). Distinct from `fail-quality` on purpose: that
+     * outcome's policy is sameAgentRetry "none" + swap "quality-gated", which would
+     * hard-fail with no retry or swap when `agent.fallback.onQualityFailure` is off.
+     * Retriable on the timeout lane, same as `fail-spin`.
+     * `fail-invalid-tool-call` — the invalid-call budget ended the turn (nax#2047);
+     * not a timeout, so the retry names the rejected call (nax#2200). Timeout lane.
+     */
+    outcome: "fail-quota" | "fail-service-down" | "fail-auth" | "fail-rate-limit" | "fail-aborted" | "fail-stale" | "fail-timeout" | "fail-adapter-error" | "fail-quality" | "fail-unknown" | "fail-spin" | "fail-incomplete" | "fail-invalid-tool-call";
+    /** Human-readable description (≤500 chars) for the failure-note chunk */
+    message: string;
+    /** True when the same agent/tier could succeed on immediate retry */
+    retriable: boolean;
+    /** Seconds to wait before retrying (for rate-limit failures) */
+    retryAfterSeconds?: number;
+    /**
+     * Observability tag — distinguishes outcome subtypes. No semantic effect on retry/swap.
+     * Examples: "idle-watchdog" (fail-stale from idle watchdog cancellation),
+     * "empty-output" (fail-stale synthesized when agent returned no output).
+     */
+    reason?: string;
+    /** The rejected call behind a `fail-invalid-tool-call`, for the retry prompt. */
+    invalidToolCall?: import("./session-types.ts").InvalidToolCallDetail;
+}

package/dist/session/adapter-failure.js

@@ -0,0 +1,11 @@
+/**
+ * Failure descriptor returned (or synthesized) by an agent adapter. Part of the
+ * session contract (S1 spec section 4.2, port 2); `context/engine` re-exports it.
+ *
+ * The runner uses this to decide between escalation (quality) and agent
+ * fallback (availability), and passes it to `rebuildForAgent()` so the new
+ * bundle carries a failure-note chunk.
+ *
+ * See: docs/specs/SPEC-context-engine-v2.md §Availability fallback
+ */
+export {};

package/dist/session/agent-stream-events.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Agent stream events: what an adapter reports while a call runs. Part of the
+ * session contract (S1 spec section 4.2, port 2). `runtime/agent-stream-events`
+ * re-exports these and keeps the bus.
+ */
+export interface AgentStreamEventBase {
+    /**
+     * Stream-local UUID minted per turn by the emitting adapter
+     * (`native/session-adapter.ts` `randomUUID()`, mirrored by ACP per prompt).
+     * It is the watchdog's and `onActiveCall`'s handle and is NOT a durable join key.
+     */
+    readonly callId: string;
+    readonly runId: string;
+    readonly agentName: string;
+    readonly sessionName: string;
+    readonly storyId?: string;
+    /** Pipeline stage label. A plain string: the contract does not know nax's stage union. */
+    readonly stage?: string;
+    readonly pid?: number;
+    readonly timestamp: number;
+    /**
+     * The exact join key for this dispatch: the same value as the transcript's
+     * `owner` and the cost ledger's `scopeId`. Native only, because only native
+     * carries a `transcriptOwner` (ACP ignores it). It is deliberately NOT the
+     * sibling `callId`, which is a stream-local UUID — joining on `callId` is the
+     * mistake that produced nax#2045's 0-of-1,940 match rate.
+     *
+     * Absent means "unknown", never a coerced `""` and never the `callId`. An
+     * absent key must not be joined on; a present-but-wrong key would silently
+     * corrupt the join.
+     */
+    readonly scopeId?: string;
+}
+export interface AgentCallStartedEvent extends AgentStreamEventBase {
+    readonly kind: "agent.call_started";
+    readonly model: string;
+    readonly timeoutSeconds: number;
+}
+export interface AgentMessageUpdateEvent extends AgentStreamEventBase {
+    readonly kind: "agent.message_update";
+    readonly deltaBytes?: number;
+}
+export interface AgentThinkingUpdateEvent extends AgentStreamEventBase {
+    readonly kind: "agent.thinking_update";
+    readonly deltaBytes?: number;
+}
+export interface AgentUsageUpdateEvent extends AgentStreamEventBase {
+    readonly kind: "agent.usage_update";
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly costUsd?: number;
+    /**
+     * Set when this usage report IS one round trip, which is the native
+     * transport's cadence: `turn-loop.ts` emits exactly one per `complete()`.
+     *
+     * The idle watchdog reads it to classify the event as tool-call-tier
+     * activity rather than semantic progress. Without it, a spinning native
+     * session reset `lastNonToolCallActivityAt` on every iteration and
+     * `toolCallOnlyIdleTimeoutSeconds` — the timer built for exactly that shape
+     * — could never expire (nax#2013).
+     *
+     * Absent on ACP, whose loop is separately bounded by `maxInteractions` and
+     * whose usage cadence is the agent's, not nax's.
+     */
+    readonly perRoundTrip?: true;
+    /** Cache-read tokens the provider served from its prompt cache. Absent when
+     *  the round trip reported no cache data — never coerced to 0, so "no cache
+     *  data" and "zero cache tokens" stay distinguishable. */
+    readonly cacheRead?: number;
+    /** Cache-creation (write) tokens the round trip billed. Absent when unknown,
+     *  for the same reason as `cacheRead`. */
+    readonly cacheWrite?: number;
+    /** Native only: 1-based index of the round trip this usage covers, within the turn.
+     *  Absent on a compaction-summary or retry beat, which are not round-trip boundaries. */
+    readonly roundTrip?: number;
+    /** Whose cadence this report follows. "round-trip" is nax's own loop (native);
+     *  "agent" is the delegated agent's, which is not a nax turn marker (ACP). */
+    readonly cadence?: "round-trip" | "agent";
+}
+export interface AgentToolCallUpdateEvent extends AgentStreamEventBase {
+    readonly kind: "agent.tool_call_update";
+    readonly toolName?: string;
+}
+export interface AgentProcessUpdateEvent extends AgentStreamEventBase {
+    readonly kind: "agent.process_update";
+    readonly status: "spawned" | "stderr" | "cancelled" | "exited";
+    readonly exitCode?: number;
+}
+export interface AgentCallEndedEvent extends AgentStreamEventBase {
+    readonly kind: "agent.call_ended";
+    readonly status: "success" | "error" | "cancelled" | "timeout";
+    readonly exitCode?: number;
+}
+/**
+ * US-004: the native turn is waiting on a human approval prompt. Emitted as
+ * activity from the turn loop while a prompt is pending so the idle watchdog
+ * does not read legitimate human waiting as idleness. Carries no payload — the
+ * timestamp is all the watchdog reads.
+ */
+export interface AgentAwaitingHumanEvent extends AgentStreamEventBase {
+    readonly kind: "agent.awaiting_human";
+}
+export type AgentStreamEvent = AgentCallStartedEvent | AgentMessageUpdateEvent | AgentThinkingUpdateEvent | AgentUsageUpdateEvent | AgentToolCallUpdateEvent | AgentProcessUpdateEvent | AgentCallEndedEvent | AgentAwaitingHumanEvent;

package/dist/session/agent-stream-events.js

@@ -0,0 +1,6 @@
+/**
+ * Agent stream events: what an adapter reports while a call runs. Part of the
+ * session contract (S1 spec section 4.2, port 2). `runtime/agent-stream-events`
+ * re-exports these and keeps the bus.
+ */
+export {};

package/dist/session/interaction-handler.d.ts

@@ -0,0 +1,53 @@
+export type AdapterInteraction = {
+    kind: "context-tool";
+    name: string;
+    input?: unknown;
+    error?: string;
+} | {
+    kind: "question";
+    text: string;
+} | {
+    kind: "coding-tool";
+    name: string;
+    input?: Record<string, unknown>;
+    /** Turn context, for the audit ledger. Native only. */
+    turnId?: string;
+    roundTrips?: number;
+    toolCallId?: string;
+    /** Native shapes the final post-handler result at its loop chokepoint. */
+    deferModelTruncation?: boolean;
+    /**
+     * The turn's single abort signal (US-002). Native only, sent on every
+     * coding-tool request; the handler forwards it into the tool's
+     * `ToolCallContext` so an in-flight Bash/Exec can SIGKILL its process
+     * group when the turn is cancelled. Absent on the other kinds, which
+     * never run a tool.
+     */
+    signal?: AbortSignal;
+    /**
+     * Notifies the wiring layer that the tool is about to WAIT on something
+     * external (e.g. a human approval) (US-002). Native only; forwarded by
+     * the handler into the tool's `ToolCallContext`.
+     */
+    onWaiting?: () => void;
+};
+export interface AdapterInteractionResponse {
+    answer: string;
+    /** Completes deferred coding-tool audit with the final model-facing content. */
+    finalizeAudit?: (content: string) => void;
+    /**
+     * Present only when the permission policy refused the call.
+     *
+     * Structural rather than a string convention: `{ answer }` alone cannot
+     * distinguish "refused, and here is why" from "here is your file", and
+     * conflating the two is exactly what ADR-029 section 5 forbids.
+     */
+    denied?: {
+        reason: string;
+        breach: boolean;
+    };
+}
+export interface InteractionHandler {
+    onInteraction(request: AdapterInteraction): Promise<AdapterInteractionResponse | null>;
+}
+export declare const NO_OP_INTERACTION_HANDLER: InteractionHandler;

package/dist/session/interaction-handler.js

@@ -0,0 +1,2 @@
+import { NO_OP_INTERACTION_HANDLER as RUNTIME_NO_OP_INTERACTION_HANDLER } from "#src/session/no-op-interaction-handler";
+export const NO_OP_INTERACTION_HANDLER = RUNTIME_NO_OP_INTERACTION_HANDLER;

package/dist/session/no-op-interaction-handler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared no-op interaction handler singleton.
+ *
+ * Kept in runtime so both agent/session layers can reuse the same object
+ * identity without importing each other's modules.
+ */
+export declare const NO_OP_INTERACTION_HANDLER: {
+    onInteraction(): Promise<null>;
+};

package/dist/session/no-op-interaction-handler.js

@@ -0,0 +1,11 @@
+/**
+ * Shared no-op interaction handler singleton.
+ *
+ * Kept in runtime so both agent/session layers can reuse the same object
+ * identity without importing each other's modules.
+ */
+export const NO_OP_INTERACTION_HANDLER = {
+    async onInteraction() {
+        return null;
+    },
+};

package/dist/session/protocol-types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared protocol identifiers captured from adapter-backed sessions.
+ *
+ * Kept in runtime so agent/session subsystems can depend on a neutral type
+ * without importing each other.
+ */
+export interface ProtocolIds {
+    /** Stable protocol record ID for a logical session. */
+    recordId: string | null;
+    /** Volatile physical session ID (changes on reconnect). */
+    sessionId: string | null;
+}

package/dist/session/protocol-types.js

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