@alisio/core 0.1.0-alpha.9 → 0.1.0

package/dist/core/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { CompactionCheckpoint, Message, ToolCall, ToolResult } from "@alisio/sdk";
+import type { AnalysisCapability, ArtifactPublisher, ArtifactRef, CompactionCheckpoint, InstallPreview, Message, ToolCall, ToolResult } from "@alisio/sdk";
 export interface Session {
     id: string;
     workspace: string;
@@ -18,6 +18,10 @@ export interface Session {
     options?: Record<string, unknown>;
     createdAt?: number;
     updatedAt?: number;
+    /** Root sessions pinned in web clients (v4). */
+    pinned?: boolean;
+    /** When a root session was archived in web clients (v4); absent when not archived. */
+    archivedAt?: number;
 }
 export interface ChildSessionRecord {
     id?: string;
@@ -30,6 +34,82 @@ export interface ChildSessionRecord {
     depth: number;
     options: Record<string, unknown>;
 }
+/** `queued` and `running` are the only non-terminal run states. */
+export type RunStatus = "queued" | "running" | "completed" | "turns_exceeded" | "failed" | "cancelled" | "interrupted";
+export type TerminalRunStatus = Exclude<RunStatus, "queued" | "running">;
+/** One `AgentRunner.run` execution (v4 `runs` table). `id` equals `RunEvent.runId`. */
+export interface RunRecord {
+    id: string;
+    session: string;
+    status: RunStatus;
+    /** Client idempotency key; absent for TUI/headless runs. */
+    requestId?: string;
+    correlationId?: string;
+    /** Process that executes (or executed) the run, for startup reconciliation. */
+    ownerPid?: number;
+    model?: string;
+    createdAt: number;
+    startedAt?: number;
+    endedAt?: number;
+    error?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cachedInput?: number;
+    };
+}
+export interface BeginRunInput {
+    id: string;
+    session: string;
+    /** `queued` for scheduled runs, `running` (default) when execution starts now. */
+    status?: "queued" | "running";
+    requestId?: string;
+    correlationId?: string;
+    model?: string;
+}
+export interface EndRunInput {
+    status: TerminalRunStatus;
+    error?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cachedInput?: number;
+    };
+}
+export interface PageOptions {
+    /** Only rows with a sequence greater than this (ascending from there). */
+    after?: number;
+    /** Only rows with a sequence lower than this (the newest `limit` of them). */
+    before?: number;
+    limit?: number;
+}
+export interface MessagePage {
+    items: Array<{
+        seq: number;
+        message: Message;
+        compacted: boolean;
+    }>;
+    /** More rows exist beyond the page in the paging direction. */
+    hasMore: boolean;
+}
+export interface StoredEvent {
+    /** Global `events.seq` as a string (same value as `RunEvent.eventId`). */
+    eventId: string;
+    runId: string;
+    type: string;
+    data: unknown;
+    createdAt?: number;
+    correlationId?: string;
+}
+export interface EventPage {
+    items: StoredEvent[];
+    hasMore: boolean;
+}
+/** Optional tool-call metadata (v4 columns); stores may ignore it. */
+export interface ToolCallMeta {
+    runId?: string;
+    effect?: string;
+}
 export interface SessionStore {
     create(workspace: string, provider: string, model: string): Session;
     get(id: string): Session;
@@ -64,10 +144,39 @@ export interface SessionStore {
     overwrite(id: string, messages: Message[]): void;
     acquire(id: string): void;
     release(id: string): void;
-    beginCall(session: string, call: ToolCall): void;
+    beginCall(session: string, call: ToolCall, meta?: ToolCallMeta): void;
     endCall(session: string, call: ToolCall, result: ToolResult): void;
+    /** The persisted result of a completed tool call, for replay of rich (ui/image) parts. */
+    callResult(session: string, callId: string): ToolResult | undefined;
     reconcile(id: string, acknowledge?: boolean): void;
-    event(id: string, runId: string, type: string, data: unknown): void;
+    /**
+     * Persist a durable run event. Stores that assign a global, monotonic sequence return it; the
+     * runner exposes it as `RunEvent.eventId`. Returning nothing is allowed (no `eventId`).
+     */
+    event(id: string, runId: string, type: string, data: unknown, meta?: {
+        correlationId?: string;
+    }): number | void;
+    /**
+     * Records a run, or moves an existing `queued` run with the same id to `running`. A run whose
+     * `(session, requestId)` already exists is returned as is (`created: false`): idempotency.
+     */
+    beginRun?(input: BeginRunInput): {
+        run: RunRecord;
+        created: boolean;
+    };
+    /** Moves a non-terminal run to a terminal state; terminal runs are never overwritten. */
+    endRun?(id: string, input: EndRunInput): void;
+    runByRequest?(session: string, requestId: string): RunRecord | undefined;
+    /** Runs of a session, newest first. */
+    runs?(session: string, options?: {
+        limit?: number;
+    }): RunRecord[];
+    messagesPage?(session: string, options?: PageOptions & {
+        compacted?: boolean;
+    }): MessagePage;
+    eventsPage?(session: string, options?: PageOptions): EventPage;
+    /** Marks queued/running runs whose owner process is not alive as interrupted. */
+    interruptRuns?(): number;
 }
 export interface ContextSource {
     /** System instructions; `sessionId` scopes lazily attached nested instructions. */
@@ -79,6 +188,11 @@ export interface Policy {
     write: boolean;
     process: boolean;
     external: boolean;
+    /**
+     * Pre-allows the `analysis.run` capability only (`--allow-analysis`); never widens `process`.
+     * Absent means false.
+     */
+    analysis?: boolean;
 }
 export type ApprovalDecision = "once" | "session" | "deny";
 export interface ApprovalRequest {
@@ -90,7 +204,70 @@ export interface ApprovalRequest {
     effect: "write" | "process" | "external";
     input: Record<string, unknown>;
     signal: AbortSignal;
+    /** The approval is for this capability of the tool, not for the whole effect. */
+    capability?: AnalysisCapability;
+    /** Capability approvals: the first 40 lines of the script. */
+    preview?: string;
+    /** Capability approvals: how the code runs (`managed` is not sandboxed). */
+    runtime?: "managed" | "oci";
+    /** `analysis.install`: the packages, the size estimate and the network need (once or deny). */
+    install?: InstallPreview;
+}
+/**
+ * Persisted capability grants as the runner sees them (implemented by `CapabilityGrants`). A
+ * `session` decision is stored for the ROOT session and survives restarts; `once` and `deny`
+ * decisions are audit rows only.
+ */
+export interface CapabilityGate {
+    granted(capability: AnalysisCapability, sessionId: string): boolean;
+    record(input: {
+        capability: AnalysisCapability;
+        sessionId: string;
+        scope: "once" | "session";
+        decision: "allow" | "deny";
+        source: "tui" | "web" | "flag" | "headless-grant";
+        callId?: string;
+        runId?: string;
+        correlationId?: string;
+    }): void;
+    /** Recorded as the source of interactive decisions (`tui` or `web`). */
+    source?: "tui" | "web";
+    /** Runtime mode shown with `analysis.run` approvals (read live: the configuration can change). */
+    runtime?: "managed" | "oci";
+    /**
+     * The script to show in an approval whose input does not carry it (a rerun runs a saved script).
+     * Absent or undefined: the preview is taken from `input.code`.
+     */
+    preview?(input: Record<string, unknown>, sessionId: string): Promise<string | undefined>;
+}
+/** One artifact published during a tool call, with its local path (for `artifact_published`). */
+export interface PublishedArtifactInfo {
+    artifact: ArtifactRef;
+    path: string;
+    warnings: string[];
+    executionId?: string;
+}
+/** The publisher core tools receive; `publishOutputs` publishes a whole staging folder at once. */
+export interface CoreArtifactPublisher extends ArtifactPublisher {
+    publishOutputs(staging: string, options: {
+        executionId: string;
+        title?: string;
+        partial?: boolean;
+        provenance?: Record<string, unknown>;
+    }): Promise<PublishedArtifactInfo[]>;
+    /** Detailed variant of `publishText` (path and warnings). */
+    publishTextDetailed(input: {
+        fileName: string;
+        title?: string;
+        text: string;
+    }): Promise<PublishedArtifactInfo>;
 }
+/** Creates the publisher of one tool call; `announce` emits `artifact_published`. */
+export type ArtifactPublisherFactory = (call: {
+    sessionId: string;
+    runId: string;
+    callId: string;
+}, announce: (published: PublishedArtifactInfo) => void) => CoreArtifactPublisher | undefined;
 /** Optional interactive approval for write/process/external tools not pre-allowed by the Policy. */
 export type ApprovalHandler = (request: ApprovalRequest) => Promise<ApprovalDecision>;
 export interface HookFailure {

package/dist/core/opt-in.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tools that exist only for runs that ask for them. The registry is shared by the main session,
+ * its child sessions and Code Mode, so hiding a tool from "everything but the plan agent" cannot
+ * be a filter on the plan run: the tool is hidden by default and a run lists it in
+ * `RunOptions.optInTools` to see (and be allowed to call) it.
+ */
+export declare const EXIT_PLAN_TOOL = "exit_plan";
+/** The goal tools: offered only while the session has an active goal (see `goal/service.ts`). */
+export declare const GOAL_TOOLS: readonly string[];
+export declare const OPT_IN_TOOLS: ReadonlySet<string>;
+/** Whether `name` may be offered or executed for a run that opted into `optIn`. */
+export declare const optInAllows: (name: string, optIn: readonly string[] | undefined) => boolean;

package/dist/core/opt-in.js

@@ -0,0 +1,12 @@
+/**
+ * Tools that exist only for runs that ask for them. The registry is shared by the main session,
+ * its child sessions and Code Mode, so hiding a tool from "everything but the plan agent" cannot
+ * be a filter on the plan run: the tool is hidden by default and a run lists it in
+ * `RunOptions.optInTools` to see (and be allowed to call) it.
+ */
+export const EXIT_PLAN_TOOL = "exit_plan";
+/** The goal tools: offered only while the session has an active goal (see `goal/service.ts`). */
+export const GOAL_TOOLS = ["get_goal", "update_goal"];
+export const OPT_IN_TOOLS = new Set([EXIT_PLAN_TOOL, ...GOAL_TOOLS]);
+/** Whether `name` may be offered or executed for a run that opted into `optIn`. */
+export const optInAllows = (name, optIn) => !OPT_IN_TOOLS.has(name) || !!optIn?.includes(name);

package/dist/core/output-limit.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The output-token budget of one model request.
+ *
+ * Priority: a value the user set explicitly (`limits.maxOutputTokens` in any config layer,
+ * `/settings`, a per-run option) always wins, even above the model's declared maximum (they asked
+ * for it, and a provider that rejects it says so); otherwise the maximum the model's catalog
+ * declares (`ModelInfo.maxOutputTokens`), capped at `MAX_AUTO_OUTPUT_TOKENS`; otherwise
+ * `DEFAULT_MAX_OUTPUT_TOKENS`. The value is resolved for the model of each request, so switching
+ * model within a session changes it.
+ */
+/** Output budget used when neither the user nor the model catalog says anything. */
+export declare const DEFAULT_MAX_OUTPUT_TOKENS = 16384;
+/**
+ * Upper bound of a budget taken from a model's declared maximum. Catalogs declare the model's
+ * hard limit (hundreds of thousands of tokens for some reasoning models), which is far more than
+ * a single agent turn should be allowed to stream; an explicit user value is never capped by it.
+ */
+export declare const MAX_AUTO_OUTPUT_TOKENS = 65536;
+/** Where the effective budget came from. */
+export type OutputLimitSource = "user" | "model" | "default";
+export interface OutputLimit {
+    value: number;
+    source: OutputLimitSource;
+}
+export declare function resolveMaxOutputTokens(input: {
+    /** Set by the user (config, settings or a per-run option); `undefined` when only defaulted. */
+    explicit?: number | undefined;
+    /** `ModelInfo.maxOutputTokens` of the model of the request, when its catalog declares one. */
+    declared?: number | undefined;
+    /** Used when nothing else applies; `DEFAULT_MAX_OUTPUT_TOKENS` unless the host knows better. */
+    fallback?: number | undefined;
+}): OutputLimit;
+/** A short English phrase for messages and logs. */
+export declare function describeOutputLimitSource(source: OutputLimitSource | undefined): string;

package/dist/core/output-limit.js

@@ -0,0 +1,39 @@
+/**
+ * The output-token budget of one model request.
+ *
+ * Priority: a value the user set explicitly (`limits.maxOutputTokens` in any config layer,
+ * `/settings`, a per-run option) always wins, even above the model's declared maximum (they asked
+ * for it, and a provider that rejects it says so); otherwise the maximum the model's catalog
+ * declares (`ModelInfo.maxOutputTokens`), capped at `MAX_AUTO_OUTPUT_TOKENS`; otherwise
+ * `DEFAULT_MAX_OUTPUT_TOKENS`. The value is resolved for the model of each request, so switching
+ * model within a session changes it.
+ */
+/** Output budget used when neither the user nor the model catalog says anything. */
+export const DEFAULT_MAX_OUTPUT_TOKENS = 16_384;
+/**
+ * Upper bound of a budget taken from a model's declared maximum. Catalogs declare the model's
+ * hard limit (hundreds of thousands of tokens for some reasoning models), which is far more than
+ * a single agent turn should be allowed to stream; an explicit user value is never capped by it.
+ */
+export const MAX_AUTO_OUTPUT_TOKENS = 65_536;
+const positive = (value) => typeof value === "number" && Number.isFinite(value) && value >= 1;
+export function resolveMaxOutputTokens(input) {
+    if (positive(input.explicit))
+        return { value: Math.floor(input.explicit), source: "user" };
+    if (positive(input.declared))
+        return { value: Math.min(Math.floor(input.declared), MAX_AUTO_OUTPUT_TOKENS), source: "model" };
+    return {
+        value: positive(input.fallback) ? Math.floor(input.fallback) : DEFAULT_MAX_OUTPUT_TOKENS,
+        source: "default",
+    };
+}
+/** A short English phrase for messages and logs. */
+export function describeOutputLimitSource(source) {
+    if (source === "user")
+        return "set by you";
+    if (source === "model")
+        return "from the model catalog";
+    if (source === "default")
+        return "default";
+    return "current limit";
+}

package/dist/core/run-stats.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a run that FAILED had already spent. `runner.run` resolves with its usage and tool-call
+ * count, but a run that throws (a provider error, a timeout, the token-budget guard) loses them;
+ * the goal controller still needs them (a run stopped by its own token cap must count as spent,
+ * not as an error). The runner remembers them against the thrown error, outside of it (a
+ * WeakMap), so no error object is changed.
+ */
+export interface RunStats {
+    usage: {
+        input: number;
+        output: number;
+    };
+    toolCalls: number;
+}
+export declare function attachRunStats(error: unknown, stats: RunStats): void;
+export declare function runStatsOf(error: unknown): RunStats | undefined;

package/dist/core/run-stats.js

@@ -0,0 +1,8 @@
+const STATS = new WeakMap();
+export function attachRunStats(error, stats) {
+    if (error && typeof error === "object")
+        STATS.set(error, stats);
+}
+export function runStatsOf(error) {
+    return error && typeof error === "object" ? STATS.get(error) : undefined;
+}

package/dist/core/runner.d.ts

@@ -1,5 +1,6 @@
-import { type Attachment, type Message, type ModelProvider, type RunEvent, type ToolDefinition } from "@alisio/sdk";
-import type { ApprovalHandler, ContextSource, Policy, RunnerExtensions, SessionStore } from "./contracts.ts";
+import { type Attachment, type DatasetRef, type Message, type ModelProvider, type RunEvent, type ToolDefinition, type ToolResult } from "@alisio/sdk";
+import type { PathAccess } from "../runtime/access.ts";
+import type { ApprovalHandler, ArtifactPublisherFactory, CapabilityGate, ContextSource, Policy, RunnerExtensions, SessionStore } from "./contracts.ts";
 import type { ToolRegistry } from "./registry.ts";
 export interface CompactionSettings {
     /** Compact automatically when context usage crosses `threshold` of a known window. */
@@ -23,8 +24,35 @@ export interface RunnerOptions {
     workspace: string;
     maxTurns?: number;
     timeoutMs?: number;
+    /** See `RunnerSettingsPatch.firstTokenTimeoutMs`. */
+    firstTokenTimeoutMs?: number;
+    /** See `RunnerSettingsPatch.firstTokenRetries`. */
+    firstTokenRetries?: number;
+    /** See `RunnerSettingsPatch.truncationRecoveries`. */
+    truncationRecoveries?: number;
+    /**
+     * Reasoning effort levels a model advertises (`ModelInfo.effort`), when known. Lets a recovery
+     * from an exhausted reasoning budget request one level lower; without it effort is unchanged.
+     */
+    effortLevels?: (model: string) => {
+        supportedLevels: string[];
+        defaultLevel?: string;
+    } | undefined;
     maxContextChars?: number;
+    /**
+     * Output-token budget the USER set (`limits.maxOutputTokens`). Left unset, the budget of each
+     * request is the model's declared maximum (`modelOutputLimit`, capped), else
+     * `fallbackMaxOutputTokens`. See `resolveMaxOutputTokens`.
+     */
     maxOutputTokens?: number;
+    /**
+     * The maximum output a model's catalog declares (`ModelInfo.maxOutputTokens`), when known.
+     * May be async (a catalog still loading); a failure counts as unknown. Called for the model
+     * of every request, so a model switch changes the budget.
+     */
+    modelOutputLimit?: (model: string) => number | undefined | Promise<number | undefined>;
+    /** Budget when neither the user nor the catalog says anything (4096 for bare embedders). */
+    fallbackMaxOutputTokens?: number;
     maxTokens?: number;
     onEvent?: (event: RunEvent) => void;
     readConcurrency?: number;
@@ -34,14 +62,28 @@ export interface RunnerOptions {
     compaction?: CompactionSettings;
     /** When set, write/process tools not allowed by the policy are offered and ask first. */
     approve?: ApprovalHandler;
+    /**
+     * Mediated path policy (workspace plus declared extra directories and external approval).
+     * When set, declared tool paths outside the allowed roots ask before the effect gate runs.
+     */
+    pathAccess?: PathAccess;
     /** Generic hooks (implemented by the plugin host) for compaction and session start. */
     extensions?: RunnerExtensions;
+    /** Persisted capability grants (`analysis.run`); without it capabilities only follow `effect`. */
+    capabilities?: CapabilityGate;
+    /** Artifact publisher of each tool call (`ToolContext.artifacts`). */
+    artifacts?: ArtifactPublisherFactory;
     /**
      * Provider-native tool definitions (for example a hosted `web_search` tool) appended to every
      * request's `tools` alongside the registry's function tools. Opt-in, set once for the whole
      * runner; only meaningful for a provider that documents an equivalent server-side tool.
      */
     nativeTools?: Array<Record<string, unknown>>;
+    /**
+     * Default reasoning effort level (a value from the current model's `ModelInfo.effort`), sent on
+     * every run unless overridden per-run. Providers that do not advertise effort levels ignore it.
+     */
+    reasoningEffort?: string;
 }
 /** The settings a running TUI can change live; merged into the runner options on apply. */
 export interface RunnerSettingsPatch {
@@ -55,6 +97,22 @@ export interface RunnerSettingsPatch {
     maxContextChars?: number;
     /** Per-run timeout in milliseconds; the next run honors it. */
     timeoutMs?: number;
+    /**
+     * Stop a model request that stays completely silent (no text, reasoning or tool-call delta)
+     * for this many milliseconds. `0` or unset disables it: only the run timeout applies.
+     */
+    firstTokenTimeoutMs?: number;
+    /**
+     * How many times the same request is sent again after a silent timeout (`firstTokenTimeoutMs`).
+     * `0` or unset disables it. A retry is not a turn; it only happens while nothing at all was
+     * received for the request.
+     */
+    firstTokenRetries?: number;
+    /**
+     * How many times a turn is requested again after the response was cut off by the output-token
+     * limit before it was usable. `0` or unset disables it. A recovery is not a turn.
+     */
+    truncationRecoveries?: number;
 }
 /**
  * Per-run overrides used by embedders and child sessions. Callers must only NARROW: `policy`
@@ -65,9 +123,16 @@ export interface RunOptions {
     display?: string;
     /** Images attached to this turn's user message, sent as vision content parts. */
     attachments?: Attachment[];
+    /** Datasets attached to this turn (UI chips); their text summary is part of the prompt. */
+    datasets?: DatasetRef[];
     /** Extra system instructions for this run (e.g. an agent persona). */
     instructions?: string;
     toolFilter?: (tool: ToolDefinition) => boolean;
+    /**
+     * Opt-in tools this run may use (see `OPT_IN_TOOLS`): they are hidden from every run that does
+     * not list them, for the model and for the executor alike.
+     */
+    optInTools?: string[];
     policy?: Policy;
     /** Allow interactive approvals for this run (default: when the runner has a handler). */
     approvals?: boolean;
@@ -77,7 +142,21 @@ export interface RunOptions {
     context?: ContextSource;
     maxTurns?: number;
     maxTokens?: number;
+    /** Per-call output token budget for this run; beats the runner-level budget when set. */
+    maxOutputTokens?: number;
     timeoutMs?: number;
+    /** Silent-request limit for this run; beats the runner-level `firstTokenTimeoutMs`. */
+    firstTokenTimeoutMs?: number;
+    /** Silent-request retries for this run; beats the runner-level `firstTokenRetries`. */
+    firstTokenRetries?: number;
+    /** Output-truncation recoveries for this run; beats the runner-level `truncationRecoveries`. */
+    truncationRecoveries?: number;
+    /** Reasoning effort level for this run; beats the runner-level default when set. */
+    reasoningEffort?: string;
+    /** Run id to use for this run's events (e.g. preassigned by an embedder); a UUID otherwise. */
+    runId?: string;
+    /** Copied to every event of this run as `RunEvent.correlationId` (e.g. an HTTP request id). */
+    correlationId?: string;
 }
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the
@@ -105,14 +184,23 @@ export declare class AgentRunner {
     get policy(): Readonly<Policy>;
     /** Whether write/process tools can be approved interactively. */
     get approvals(): boolean;
+    /**
+     * Sets which effects run without asking (a permission mode). The policy object is mutated in
+     * place because the application and the runner share it; `analysis` is never touched. Takes
+     * effect from the next tool call, so it also drops "allow for this session" widenings.
+     */
+    setPolicy(next: Partial<Pick<Policy, "write" | "process" | "external">>): void;
     /**
      * Live-update runnable settings so the next `run`/`compact` call honors them without restarting
      * Alisio. Every patch field is merged over the current options; unrelated settings are kept.
      */
     applySettings(patch: RunnerSettingsPatch): void;
     private emitter;
-    /** Tools offered to the model under the current policy (and optional run narrowing). */
-    availableTools(run?: RunOptions): ToolDefinition[];
+    /**
+     * Tools offered to the model under the current policy (and optional run narrowing). With a
+     * session, a capability tool is also offered when that session's root holds a persisted grant.
+     */
+    availableTools(run?: RunOptions, sessionId?: string): ToolDefinition[];
     /** Abort signal of the session's active run, if any (used to cascade cancellation). */
     signal(sessionId: string): AbortSignal | undefined;
     isRunning(sessionId: string): boolean;
@@ -138,6 +226,25 @@ export declare class AgentRunner {
         basis: "window" | "unknown";
         compactionAt: number;
     };
+    /**
+     * What a tool-less side call about a session needs (for example a `/btw` side question): the
+     * session's provider and model, its system instructions, its ACTIVE history and the current
+     * limits. Claims no lock and writes nothing, so it is safe while a run is active.
+     */
+    sideContext(sessionId: string): Promise<{
+        provider: ModelProvider;
+        model: string;
+        instructions: string;
+        messages: Message[];
+        maxContextChars: number;
+        maxOutputTokens: number;
+        timeoutMs: number;
+        /** Context window of the model in tokens, when known and trusted. */
+        contextWindow?: number;
+        reasoningEffort?: string;
+    }>;
+    /** The output-token budget for `model`: user value, else catalog maximum, else fallback. */
+    private outputLimit;
     /** Change the model used by subsequent turns of a session; recorded in the store. */
     setModel(sessionId: string, model: string): void;
     /** Manually compact a session outside a run. */
@@ -146,6 +253,27 @@ export declare class AgentRunner {
         signal?: AbortSignal;
     }): Promise<CompactionResult | undefined>;
     private compactLocked;
+    /**
+     * Gates and executes one tool call: external-directory paths, the capability/effect gate with
+     * its approval, the call journal, artifact publishing and the result bound. Shared by model
+     * runs and `runToolCall`, so a call started from a UI passes exactly the same gates.
+     */
+    private executeCall;
+    /**
+     * Runs ONE tool call without a model (spec §20 `runToolCall`): an action the user started from
+     * a UI, such as copying an artifact into the workspace. It is a real run of the session
+     * (`run_started` → `tool_*` → `run_completed`, journaled) and the call passes exactly the gates
+     * of a model call (`write` approval, capabilities, paths). The transcript stays valid for every
+     * provider: a user note (shown as `display`), an assistant message with the call, the tool
+     * result and a short assistant summary.
+     */
+    runToolCall(sessionId: string, name: string, input: Record<string, unknown>, options?: RunOptions & {
+        signal?: AbortSignal;
+    }): Promise<{
+        runId: string;
+        status: "completed";
+        result: ToolResult;
+    }>;
     run(sessionId: string, prompt: string, signal?: AbortSignal, options?: RunOptions): Promise<{
         sessionId: string;
         text: string;
@@ -154,5 +282,7 @@ export declare class AgentRunner {
             input: number;
             output: number;
         };
+        /** Tool calls the model made during the run (the goal controller's no-progress breaker). */
+        toolCalls: number;
     }>;
 }