@nathapp/nax-agent 0.1.0

package/dist/native/session/turn-tool-batch.js

@@ -0,0 +1,259 @@
+/**
+ * The per-batch tool-call loop of the native turn loop.
+ *
+ * One assistant message may carry several tool calls; this module answers every
+ * one of them, applying the six distinct rules the loop has accumulated. It is
+ * the largest move out of `turn-loop.ts` and the one with the most invariants,
+ * so it is extracted unchanged: the rules are the point, not the plumbing.
+ *
+ * The batch owns a mutable copy of the transcript for its duration and returns
+ * the final array; `interactions` and `codingToolsCalled` accumulate locally and
+ * come back as NEW entries, so the caller appends rather than the batch
+ * mutating turn-lifetime arrays it does not own.
+ *
+ * `spinWarned` is a snapshot: it is set by the spin breaker's `onSpinStop`
+ * callback during this batch only in tandem with a `terminate` outcome, which
+ * breaks the batch immediately — so no later call in the same batch needs the
+ * flipped value. The batch reports the resulting `spinStopped` back out.
+ */
+import { ASK_HUMAN_TOOL_NAME } from "./ask-human.js";
+import { rewriteToolCallInput } from "./handle-invalid-tool-call.js";
+import { withNudge } from "./nudge.js";
+import { buildToolResult } from "./tool-result.js";
+import { handleAskHumanCall } from "./turn-ask-human.js";
+export async function runToolBatch(args) {
+    const { toolCalls, tools, codingToolNames, roundTrips, opts, deps, loopEvents, invalidCallBudget, spinBreaker, maxInteractions, spinWarned, interactionsSoFar, } = args;
+    let messages = [...args.messages];
+    const interactions = [];
+    const codingToolsCalled = [];
+    // The ask_human budget counts exchanges across the whole turn, not this
+    // batch: `interactionsSoFar` is the caller's count at dispatch, and each
+    // successful exchange below advances `recorded` so a second ask in the same
+    // batch sees the first one spent.
+    let recorded = interactionsSoFar;
+    let spinStopped = false;
+    // US-002: a cancelled turn signal short-circuits this batch. The check runs
+    // at the TOP of every iteration (before activity, before dispatch) so an
+    // already-aborted signal at batch start also answers this-and-later calls
+    // from the first iteration; an in-flight call (the one that triggered the
+    // abort) finishes on its own path, the check begins there.
+    let cancelled = false;
+    const isTurnCancelled = () => deps.signal?.aborted === true;
+    function answerCancelledFrom(callIndex) {
+        cancelled = true;
+        for (const outstanding of toolCalls.slice(callIndex)) {
+            messages.push(buildToolResult({
+                toolCallId: outstanding.id,
+                content: "Not run: the turn was cancelled.",
+                isError: true,
+            }));
+        }
+    }
+    for (const [callIndex, call] of toolCalls.entries()) {
+        // US-002: check the turn signal FIRST (before spinWarned) so a cancelled
+        // turn always synthesises results for every outstanding call. A batch
+        // dispatch that arrives with both a frozen `spinWarned` snapshot AND an
+        // aborted signal must preserve the one-result-per-id invariant — the
+        // cancelled branch is the stronger guarantee, so it wins when both hold.
+        // AC1 / AC7 / AC8.
+        if (isTurnCancelled()) {
+            answerCancelledFrom(callIndex);
+            break;
+        }
+        if (spinWarned) {
+            spinStopped = true;
+            // The terminal round trip is answer-only. Any subsequent tool call
+            // is neither executed nor answered; the fail-spin retry starts from
+            // a fresh session and deliberately drops this unanswered request.
+            break;
+        }
+        deps.onActivity?.({ kind: "tool", toolName: call.name });
+        try {
+            if (call.name === ASK_HUMAN_TOOL_NAME) {
+                const question = String(call.input?.text ?? "");
+                // These push sites — and the spin notice below — are answers to a call no
+                // tool produced. They use the chokepoint and deliberately fire no
+                // `after_tool` event: a policy that shapes tool output has nothing to
+                // shape here.
+                const outcome = await handleAskHumanCall({
+                    toolCallId: call.id,
+                    question,
+                    interactionsSoFar: recorded,
+                    maxInteractions,
+                    roundTrips,
+                    interactionHandler: opts.interactionHandler,
+                });
+                if (outcome.exchange !== undefined) {
+                    interactions.push(outcome.exchange);
+                    recorded += 1;
+                }
+                messages.push(outcome.result);
+                continue;
+            }
+            const outcome = await loopEvents.dispatch("before_tool", { call, tools });
+            if (isTurnCancelled()) {
+                answerCancelledFrom(callIndex);
+                break;
+            }
+            // nax#2047 Task 4: a tripped invalid-call budget ends the batch with
+            // NO result — "a result nobody reads only grows the transcript". None
+            // of the four seam outcomes can express that (each answers the call),
+            // so the halt is read from the budget the repair handler counts into,
+            // and checked before the outcome is applied.
+            if (invalidCallBudget.exceeded)
+                break;
+            // The spin breaker's stop is a batch-level outcome (nax#2120): every
+            // OUTSTANDING call in this batch is answered, not just the triggering
+            // one, or the next `complete()` is sent a tool_call with no matching
+            // result, which strict providers reject. Answer-only — the loop
+            // continues so the model can close the turn out — and synthetic, so
+            // no `after_tool` handler sees it.
+            if (outcome.kind === "terminate") {
+                for (const outstanding of toolCalls.slice(callIndex)) {
+                    messages.push(buildToolResult({
+                        toolCallId: outstanding.id,
+                        content: outcome.content,
+                        isError: outcome.isError,
+                    }));
+                }
+                break;
+            }
+            if (outcome.kind === "block") {
+                // Answered on the tool's behalf: the call never runs. A blocked
+                // call may still carry the input to record in its place (the
+                // invalid-call repair's redacted call), written before the answer.
+                if (outcome.input !== undefined)
+                    messages = rewriteToolCallInput(messages, call.id, outcome.input);
+                messages.push(buildToolResult({ toolCallId: call.id, content: outcome.content, isError: outcome.isError }));
+                continue;
+            }
+            // `allow` and `nudge` may rewrite the call's input; the rewritten value
+            // is what the transcript records and what the tool is invoked with, so
+            // the model's own history stays a truthful account of what ran.
+            const rewritten = outcome.input;
+            const input = rewritten ?? call.input;
+            if (rewritten !== undefined)
+                messages = rewriteToolCallInput(messages, call.id, rewritten);
+            const nudgeText = outcome.kind === "nudge" ? outcome.text : undefined;
+            const kind = codingToolNames.has(call.name) ? "coding-tool" : "context-tool";
+            if (kind === "coding-tool")
+                codingToolsCalled.push(call.name);
+            const answer = await opts.interactionHandler.onInteraction(kind === "coding-tool"
+                ? {
+                    kind,
+                    name: call.name,
+                    // MUST be `input`, NOT `call.input`. #2162's US-002 added a
+                    // `before_tool` `allow` outcome that may REWRITE the input;
+                    // the merged line is `input: (input ?? {}) as Record<...>`
+                    // where `input = rewritten ?? call.input` (turn-loop.ts:448).
+                    // Using `call.input` here runs the tool on the model's
+                    // original arguments while `rewriteToolCallInput` has already
+                    // recorded the corrected ones — execution and transcript
+                    // diverge, silently, with no test in this plan covering it.
+                    input: (input ?? {}),
+                    ...(opts.turnId !== undefined ? { turnId: opts.turnId } : {}),
+                    roundTrips,
+                    toolCallId: call.id,
+                    deferModelTruncation: true,
+                    // US-002: forward the per-turn signal into the coding-tool
+                    // request. The handler copies it onto the `ToolCallContext`
+                    // and `runTool` copies it onto the tool's `ToolRunContext`, so
+                    // an in-flight tool observes the turn's cancellation. Absent
+                    // when no signal is in scope (the no-signal regression guard).
+                    ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+                    // US-002 AC14: forward the per-turn onWaiting callback too.
+                    // Without this forwarding the `onWaiting` field on the request
+                    // is unreachable from native tool dispatch, leaving the
+                    // handler's onWaiting-forwarding plumbing inert in the real
+                    // native path. Absent when no watcher is in scope.
+                    //
+                    // US-004 AC1: the forwarded onWaiting ALSO emits awaiting_human
+                    // activity through deps.onActivity — a bare forwarding of
+                    // deps.onWaiting never reaches the activity hook, so the
+                    // watchdog would still cancel a turn that is legitimately
+                    // waiting on a human approval prompt.
+                    //
+                    // Activity is emitted FIRST so a throwing onWaiting does not
+                    // suppress the watchdog beat. The onWaiting call is wrapped in
+                    // try/catch because it is a notification, not a gate — the
+                    // request proceeds either way.
+                    ...(deps.onWaiting !== undefined || deps.onActivity !== undefined
+                        ? {
+                            onWaiting: () => {
+                                deps.onActivity?.({ kind: "awaiting_human" });
+                                try {
+                                    deps.onWaiting?.();
+                                }
+                                catch {
+                                    // notification only — onWaiting throwing must not
+                                    // surface to the tool, the run, or the cancel logic
+                                }
+                            },
+                        }
+                        : {}),
+                }
+                : { kind, name: call.name, input });
+            const answerText = answer?.answer ?? "";
+            // Genuine execution: the result is shaped by `after_tool` BEFORE it
+            // enters the array, which is what makes the event safe by
+            // construction (no handler can rewrite history). `denied` is threaded
+            // through untouched — a refused Write is not a crashed Write
+            // (ADR-029 s5) — and `nudge` prefixes the surviving content.
+            // Model-facing truncation (US-003) is the LAST of those handlers, so it
+            // shapes whatever earlier handlers produced; the payload carries the
+            // tool identity and the pending nudge, whose bytes the handler reserves
+            // out of this result's budget before `withNudge` prepends it below.
+            const patch = await loopEvents.dispatch("after_tool", {
+                content: answerText,
+                denied: answer?.denied,
+                toolName: call.name,
+                callId: call.id,
+                ...(nudgeText !== undefined ? { nudgeText } : {}),
+            });
+            const finalContent = withNudge(nudgeText, patch.content ?? answerText);
+            answer?.finalizeAudit?.(finalContent);
+            messages.push(buildToolResult({
+                toolCallId: call.id,
+                content: finalContent,
+                isError: patch.isError,
+                denied: answer?.denied,
+            }));
+            // The breaker observed the call through the seam, i.e. with whatever
+            // input a handler rewrote in place — so the result has to be noted
+            // against that same input, or the key misses and result-based
+            // repetition detection silently stops for rewritten calls.
+            spinBreaker?.noteResult(call.name, input, answerText);
+        }
+        catch (err) {
+            // A tool failure is data, not a turn failure: the existing pull-tool
+            // contract already surfaces a handler throw as status "error". The
+            // event still fires — a policy that bounds result size has to see the
+            // results that arrive as errors too.
+            const errorText = err instanceof Error ? err.message : String(err);
+            const patch = await loopEvents.dispatch("after_tool", {
+                content: errorText,
+                isError: true,
+                toolName: call.name,
+                callId: call.id,
+            });
+            messages.push(buildToolResult({
+                toolCallId: call.id,
+                content: patch.content ?? errorText,
+                isError: patch.isError ?? true,
+            }));
+        }
+    }
+    return {
+        messages,
+        interactions,
+        codingToolsCalled,
+        spinStopped,
+        budgetExceeded: invalidCallBudget.exceeded,
+        // US-002: true when this batch saw an aborted `deps.signal` between tool
+        // calls; the loop throws the abort reason instead of issuing another
+        // round trip. A batch that never consulted a signal — the normal
+        // pre-feature path — never sees an aborted signal, so this stays false
+        // and the result shape is unchanged.
+        cancelled: cancelled || isTurnCancelled(),
+    };
+}

package/dist/native/session/turn-types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Public types and failure-usage ledger for the native turn loop.
+ *
+ * `runNativeTurn` (turn-loop.ts) carries this file's types as parameters; this
+ * file owns their shape. Splitting them out keeps turn-loop.ts focused on the
+ * algorithm and the file under the 600-line hard limit (see
+ * .nax/rules/project-conventions.md).
+ *
+ * The failure-usage ledger (`failureUsageByError` WeakMap +
+ * `recordNativeTurnFailureUsage` / `readNativeTurnFailureUsage`) also lives
+ * here: it is module-level state with a process-lifetime scope, and the
+ * loop's catch block only ever calls the write side through this file's
+ * public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
+ * attribute round-trip spend to the error a failed turn threw (nax#1840).
+ */
+import type { ConversationMessage, ThinkingBlock, ToolCall } from "@nathapp/nax-ai";
+import type { PricingRates, TokenUsage } from "#src/cost/standard-types";
+import type { SpinBreaker } from "#src/infra/spin-breaker/index";
+import type { TurnDeadline } from "#src/session/turn-deadline";
+import type { TranscriptMessage as NativeTranscriptMessage, ResolvedCompaction } from "./compaction.ts";
+import type { CompleteCallOptions, LoopEventRegistry, LoopHandlerContext, LoopHandlerSet } from "./loop-events/index.ts";
+import type { toToolDefinitions } from "./tool-mapping.ts";
+import type { TurnRetryConfig } from "./turn-retry.ts";
+export interface NativeTurnResponse {
+    readonly text: string;
+    readonly toolCalls?: readonly ToolCall[];
+    readonly thinking?: readonly ThinkingBlock[];
+    readonly usage: TokenUsage;
+    readonly costUsd: number;
+    /**
+     * US-002: the per-1M rates that priced this round-trip's `costUsd`.
+     * `runNativeTurn` stamps the LAST round-trip's `rates` on the
+     * `TurnResult` it returns — each round-trip re-prices on its own usage,
+     * and the most recent decision is what affected the user's last-mile
+     * spend. Optional so existing test fakes that build the response shape
+     * by hand keep compiling; the adapter's `complete` closure always sets
+     * it because native prices unconditionally.
+     */
+    readonly rates?: PricingRates;
+}
+/** What one summarization call returns. Usage and cost are surfaced, not swallowed. */
+export interface NativeSummaryResponse {
+    readonly text: string;
+    readonly usage: TokenUsage;
+    readonly costUsd: number;
+    /** Per-1M rates that priced this summary call, when known. */
+    readonly rates?: PricingRates;
+}
+export interface TurnDeps {
+    complete(messages: readonly ConversationMessage[], tools: ReturnType<typeof toToolDefinitions>, options?: CompleteCallOptions): Promise<NativeTurnResponse>;
+    /**
+     * One model call, no tools, used only to summarize a dropped span. Separate
+     * from complete() because it must not advertise tools, must not count as a
+     * round trip, and its cost must be attributable.
+     */
+    summarize?(messages: readonly NativeTranscriptMessage[], previousSummary?: string): Promise<NativeSummaryResponse>;
+    /** ResolvedModel.contextWindow. Absent disables compaction. */
+    contextWindow?: number;
+    /** Resolved settings. Absent disables compaction. */
+    compaction?: ResolvedCompaction;
+    /**
+     * Whole-turn wall-clock budget. Absent means unbounded — the adapter always
+     * supplies one for a real session; tests may omit it.
+     */
+    deadline?: TurnDeadline;
+    /**
+     * Per-round-trip observability hook. Absent in unit tests; the adapter
+     * supplies one that forwards onto the runtime stream bus so the idle
+     * watchdog can see native sessions.
+     */
+    onActivity?: (activity: import("./turn-events.ts").NativeTurnActivity) => void;
+    /**
+     * Which rate card priced this turn (US-003, first half of #1817). Absent
+     * on tests that build TurnDeps by hand and do not care about the source.
+     * When set, propagates to the returned TurnResult as `pricingSource` so the
+     * dispatch layer can stamp the row without re-deriving the rate-card branch.
+     */
+    pricingSource?: "catalog-rates" | "config-override";
+    /**
+     * nax#1870: bounded retry for a transport/overloaded fault thrown by
+     * deps.complete, resolved from `agent.native.transportRetry`. Absent
+     * disables retry — the pre-#1870 behaviour of rethrowing immediately.
+     */
+    transportRetry?: TurnRetryConfig;
+    /**
+     * Injectable sleep for the transport-retry backoff, so tests never
+     * actually wait (forbidden-patterns-tests.md). Absent uses a real timer —
+     * a real session always wants to actually wait.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Live repetition-breaker instance (nax#2013, session-lifetime since #2047). Absent disables the breaker.
+     */
+    spinBreaker?: SpinBreaker;
+    /**
+     * The one per-turn abort signal (US-002). The adapter builds it as
+     * `AbortSignal.any` over the caller's `opts.signal`, the watchdog's
+     * `turnController.signal` and a whole-turn deadline timer, and hands it to
+     * the loop; the loop's batch consults it between tool calls so a cancelled
+     * turn stops dispatching subsequent native tool calls. Absent in tests that
+     * drive the loop without cancellation.
+     */
+    signal?: AbortSignal;
+    /**
+     * The native batch forwards this onto every coding-tool `AdapterInteraction`
+     * (US-002). Tools that block on an external wait (e.g. a human approval)
+     * call it before the wait so the wiring layer can observe the activity and
+     * the idle watchdog does not time out the call. Absent when no watcher is
+     * in scope; tests that drive the loop without cancellation may omit it.
+     */
+    onWaiting?: () => void;
+    /**
+     * The in-process `before_tool` / `after_tool` seam (nax#2151, US-002).
+     * Absent is the normal case for a real session: the loop then builds its own
+     * registry, so the built-in handlers (invalid-call repair, spin breaker) run
+     * regardless. Supplying one is how a caller adds handlers — or observes the
+     * genuine-result dispatch sites — without the loop owning them.
+     *
+     * Per-turn, like the rest of `TurnDeps`: the loop registers its built-ins on
+     * the registry it is given, because both of them reset with the turn.
+     */
+    loopEvents?: LoopEventRegistry;
+    /**
+     * The run's plugin-contributed loop handlers (US-003), forwarded from
+     * `SendTurnOpts` by the adapter. Installed by `registerBuiltinLoopHandlers`
+     * between the built-in `before_tool` pair and the built-in truncation.
+     * Absent or empty is the normal case — most runs load no such plugin.
+     */
+    loopHandlers?: LoopHandlerSet;
+    /**
+     * The read-only facts each plugin handler is handed (US-003), forwarded from
+     * `SendTurnOpts`. Read at dispatch, like the rest of the per-turn state.
+     */
+    loopHandlerContext?: LoopHandlerContext;
+}
+/**
+ * nax#1840: round trips completed before a turn fails still spent real money.
+ * `inputTokens`/`outputTokens`/`costUsd` are locals inside runNativeTurn and
+ * reach a caller only through the clean-exit return, so a throw at round trip
+ * N silently drops everything spent on round trips 1..N-1.
+ *
+ * Recorded against the thrown error's own identity (a WeakMap), never by
+ * mutating the error itself: session-adapter.ts's `isProtocolStreamError`
+ * guard and its "propagate a non-protocol error untouched" rule both depend
+ * on the error's own shape staying exactly what was thrown.
+ */
+export interface NativeTurnFailureUsage {
+    readonly tokenUsage: TokenUsage;
+    readonly costUsd: number;
+}
+/** Writes the spend a failed turn accumulated, keyed on the error's own identity. */
+export declare function recordNativeTurnFailureUsage(err: object, usage: NativeTurnFailureUsage): void;
+/** Reads back what the catch block recorded, if anything did. */
+export declare function readNativeTurnFailureUsage(err: unknown): NativeTurnFailureUsage | undefined;
+/**
+ * Translate a `TokenUsage`'s cache fields into the spread that the
+ * `usage`-kind activity beat takes. Absent stays absent (never 0): the
+ * caller distinguishes "no cache data" from "zero cache tokens" downstream
+ * (nax#2045).
+ */
+export declare function cacheUsageFields(usage: TokenUsage): {
+    cacheRead?: number;
+    cacheWrite?: number;
+};

package/dist/native/session/turn-types.js

@@ -0,0 +1,36 @@
+/**
+ * Public types and failure-usage ledger for the native turn loop.
+ *
+ * `runNativeTurn` (turn-loop.ts) carries this file's types as parameters; this
+ * file owns their shape. Splitting them out keeps turn-loop.ts focused on the
+ * algorithm and the file under the 600-line hard limit (see
+ * .nax/rules/project-conventions.md).
+ *
+ * The failure-usage ledger (`failureUsageByError` WeakMap +
+ * `recordNativeTurnFailureUsage` / `readNativeTurnFailureUsage`) also lives
+ * here: it is module-level state with a process-lifetime scope, and the
+ * loop's catch block only ever calls the write side through this file's
+ * public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
+ * attribute round-trip spend to the error a failed turn threw (nax#1840).
+ */
+const failureUsageByError = new WeakMap();
+/** Writes the spend a failed turn accumulated, keyed on the error's own identity. */
+export function recordNativeTurnFailureUsage(err, usage) {
+    failureUsageByError.set(err, usage);
+}
+/** Reads back what the catch block recorded, if anything did. */
+export function readNativeTurnFailureUsage(err) {
+    return typeof err === "object" && err !== null ? failureUsageByError.get(err) : undefined;
+}
+/**
+ * Translate a `TokenUsage`'s cache fields into the spread that the
+ * `usage`-kind activity beat takes. Absent stays absent (never 0): the
+ * caller distinguishes "no cache data" from "zero cache tokens" downstream
+ * (nax#2045).
+ */
+export function cacheUsageFields(usage) {
+    return {
+        ...(usage.cacheReadTokens !== undefined ? { cacheRead: usage.cacheReadTokens } : {}),
+        ...(usage.cacheWriteTokens !== undefined ? { cacheWrite: usage.cacheWriteTokens } : {}),
+    };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * The native session adapter: openSession / sendTurn / closeSession over
+ * nax-ai, no subprocess. openSession/closeSession are transcript-file
+ * bookkeeping, and sendTurn maps the native turn loop (session/turn-loop.ts)
+ * over complete() — nax owns the conversation because nax-ai's client is
+ * stateless (ADR-027 section 10, ADR-028).
+ */
+import { type AgentSessionAdapter, type OpenSessionOpts, type SendTurnOpts, type SessionHandle, type TurnResult } from "#src/session/session-types";
+import { type NativeCatalogOverrides } from "./client.ts";
+export declare class NativeSessionAdapter implements AgentSessionAdapter {
+    private readonly catalogOverrides;
+    constructor(catalogOverrides?: NativeCatalogOverrides);
+    /**
+     * Can this agent authenticate to at least one provider?
+     *
+     * Deliberately not "is the provider this run needs satisfied": this method
+     * takes no provider, and it cannot get one. The registry receives the
+     * manager's config slice, and agentManagerConfigSelector excludes
+     * config.models by design (ADR-019). Probing every provider for a specific
+     * answer is not an alternative either — pi's resolve() may execute commands.
+     *
+     * So this prunes exactly one case: nothing stored anywhere and nothing
+     * ambient. That is the real failure — a user who has never run
+     * `nax auth login` and has no provider environment variables — and every
+     * native call is going to fail anyway. A wrong-provider credential still
+     * surfaces per request, through the typed mapping from ProtocolError.kind
+     * "auth" to availability / fail-auth.
+     *
+     * US-004: with `auth.source: "exec"` it answers true without asking anything.
+     * A helper's providers cannot be listed, so an empty credential file says
+     * nothing about whether this run can authenticate — and spawning the helper
+     * here would put a credential read before the run has any reason for one.
+     *
+     * Errors resolve to true. Pruning an agent that would have worked kills a
+     * run; the opposite costs one request-time error that is already handled.
+     */
+    hasCredentials(): Promise<boolean>;
+    openSession(name: string, opts: OpenSessionOpts): Promise<SessionHandle>;
+    sendTurn(handle: SessionHandle, prompt: string, opts: SendTurnOpts): Promise<TurnResult>;
+    closeSession(handle: SessionHandle): Promise<void>;
+    /**
+     * Run teardown addresses a session the process no longer has a handle for,
+     * by id string (execution/session-manager-runtime.ts). Without this the
+     * native maps were unreachable at teardown: every `keepOpen` session was
+     * removed from SessionManager._sessions by closeStory while its nine entries
+     * stayed behind for the process lifetime.
+     *
+     * The ACP contract takes a handle string and closeNativeSession takes a
+     * SessionHandle, but the maps are keyed by the session-name string both
+     * carry, so clear by name rather than synthesising a handle.
+     */
+    closePhysicalSession(handle: string, _workdir?: string, _options?: {
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}