@alisio/core 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/config.d.ts

@@ -12,6 +12,11 @@ declare const serverSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     url: z.ZodString;
     bearerTokenEnv: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "transport">;
+/**
+ * A container image reference pinned by digest. Anchored at the start with a letter or digit so a
+ * value can never be read as an option by the container CLI.
+ */
+export declare const OCI_IMAGE_PATTERN: RegExp;
 export declare const configSchema: z.ZodPipe<z.ZodObject<{
     schemaVersion: z.ZodDefault<z.ZodLiteral<1>>;
     provider: z.ZodDefault<z.ZodObject<{
@@ -170,10 +175,46 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     limits: z.ZodDefault<z.ZodObject<{
         maxTurns: z.ZodDefault<z.ZodNumber>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
+        firstTokenTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        firstTokenRetries: z.ZodDefault<z.ZodNumber>;
         maxContextChars: z.ZodDefault<z.ZodNumber>;
         maxOutputTokens: z.ZodDefault<z.ZodNumber>;
         maxTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    analysis: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        runtime: z.ZodDefault<z.ZodEnum<{
+            managed: "managed";
+            oci: "oci";
+        }>>;
+        oci: z.ZodDefault<z.ZodObject<{
+            engine: z.ZodDefault<z.ZodEnum<{
+                docker: "docker";
+                podman: "podman";
+            }>>;
+            image: z.ZodOptional<z.ZodString>;
+            memoryMb: z.ZodDefault<z.ZodNumber>;
+            cpus: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        limits: z.ZodDefault<z.ZodObject<{
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+            maxFiles: z.ZodDefault<z.ZodNumber>;
+            maxFileBytes: z.ZodDefault<z.ZodNumber>;
+            maxOutputBytes: z.ZodDefault<z.ZodNumber>;
+            maxLogBytes: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        data: z.ZodDefault<z.ZodObject<{
+            maxUploadBytes: z.ZodDefault<z.ZodNumber>;
+            maxRows: z.ZodDefault<z.ZodNumber>;
+            queryTimeoutMs: z.ZodDefault<z.ZodNumber>;
+            maxInteractiveRows: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        retention: z.ZodDefault<z.ZodObject<{
+            jobsDays: z.ZodDefault<z.ZodNumber>;
+            intermediateDays: z.ZodDefault<z.ZodNumber>;
+            artifactsDays: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     tui: z.ZodDefault<z.ZodObject<{
         paddingX: z.ZodDefault<z.ZodNumber>;
         contentPaddingX: z.ZodDefault<z.ZodNumber>;
@@ -231,10 +272,40 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     limits: {
         maxTurns: number;
         timeoutMs: number;
+        firstTokenTimeoutMs: number;
+        firstTokenRetries: number;
         maxContextChars: number;
         maxOutputTokens: number;
         maxTokens?: number | undefined;
     };
+    analysis: {
+        enabled: boolean;
+        runtime: "managed" | "oci";
+        oci: {
+            engine: "docker" | "podman";
+            image?: string | undefined;
+            memoryMb: number;
+            cpus: number;
+        };
+        limits: {
+            timeoutMs: number;
+            maxFiles: number;
+            maxFileBytes: number;
+            maxOutputBytes: number;
+            maxLogBytes: number;
+        };
+        data: {
+            maxUploadBytes: number;
+            maxRows: number;
+            queryTimeoutMs: number;
+            maxInteractiveRows: number;
+        };
+        retention: {
+            jobsDays: number;
+            intermediateDays: number;
+            artifactsDays: number;
+        };
+    };
     tui: {
         paddingX: number;
         contentPaddingX: number;
@@ -375,10 +446,40 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     limits: {
         maxTurns: number;
         timeoutMs: number;
+        firstTokenTimeoutMs: number;
+        firstTokenRetries: number;
         maxContextChars: number;
         maxOutputTokens: number;
         maxTokens?: number | undefined;
     };
+    analysis: {
+        enabled: boolean;
+        runtime: "managed" | "oci";
+        oci: {
+            engine: "docker" | "podman";
+            image?: string | undefined;
+            memoryMb: number;
+            cpus: number;
+        };
+        limits: {
+            timeoutMs: number;
+            maxFiles: number;
+            maxFileBytes: number;
+            maxOutputBytes: number;
+            maxLogBytes: number;
+        };
+        data: {
+            maxUploadBytes: number;
+            maxRows: number;
+            queryTimeoutMs: number;
+            maxInteractiveRows: number;
+        };
+        retention: {
+            jobsDays: number;
+            intermediateDays: number;
+            artifactsDays: number;
+        };
+    };
     tui: {
         paddingX: number;
         contentPaddingX: number;
@@ -405,6 +506,8 @@ export interface ConfigProvenance {
         kind: "project" | "explicit";
         hasLegacyProvider: boolean;
     };
+    /** Keys a project or explicit layer set that only the global layer may decide (ignored). */
+    ignored?: string[];
 }
 export interface ConfigLoadResult {
     config: LoadedConfig;
@@ -458,6 +561,8 @@ declare const SETTABLE_KEYS: {
     readonly "limits.maxOutputTokens": z.ZodDefault<z.ZodNumber>;
     readonly "limits.maxContextChars": z.ZodDefault<z.ZodNumber>;
     readonly "limits.timeoutMs": z.ZodDefault<z.ZodNumber>;
+    readonly "limits.firstTokenTimeoutMs": z.ZodDefault<z.ZodNumber>;
+    readonly "limits.firstTokenRetries": z.ZodDefault<z.ZodNumber>;
     readonly "pluginHooks.timeoutMs": z.ZodDefault<z.ZodNumber>;
     readonly "tui.paddingX": z.ZodDefault<z.ZodNumber>;
     readonly "tui.contentPaddingX": z.ZodDefault<z.ZodNumber>;
@@ -473,6 +578,11 @@ declare const SETTABLE_KEYS: {
     }>>;
     readonly "agents.active": z.ZodDefault<z.ZodString>;
     readonly "agents.effort": z.ZodOptional<z.ZodString>;
+    readonly "analysis.enabled": z.ZodDefault<z.ZodBoolean>;
+    readonly "analysis.limits.timeoutMs": z.ZodDefault<z.ZodNumber>;
+    readonly "analysis.retention.jobsDays": z.ZodDefault<z.ZodNumber>;
+    readonly "analysis.retention.intermediateDays": z.ZodDefault<z.ZodNumber>;
+    readonly "analysis.retention.artifactsDays": z.ZodDefault<z.ZodNumber>;
 };
 export type SettableSettingKey = keyof typeof SETTABLE_KEYS;
 export declare function isSettableSettingKey(key: string): key is SettableSettingKey;

package/dist/config.js

@@ -75,6 +75,13 @@ const serversSchema = (value) => z.record(z.string(), value).superRefine((server
                 message: "MCP server names may contain only letters, numbers, dot, underscore and dash",
             });
 });
+/**
+ * A container image reference pinned by digest. Anchored at the start with a letter or digit so a
+ * value can never be read as an option by the container CLI.
+ */
+export const OCI_IMAGE_PATTERN = /^[a-zA-Z0-9][^\s@]*@sha256:[a-f0-9]{64}$/;
+/** Analysis keys only the user (global) layer decides; a project layer cannot set them. */
+const GLOBAL_ONLY_ANALYSIS = ["runtime", "oci", "retention"];
 const configObjectSchema = z
     .object({
     schemaVersion: z.literal(1).default(1),
@@ -166,7 +173,20 @@ const configObjectSchema = z
     limits: z
         .object({
         maxTurns: z.number().int().min(1).max(100).default(100),
-        timeoutMs: z.number().int().min(100).default(300000),
+        timeoutMs: z.number().int().min(100).default(600000),
+        /**
+         * Stop a model request that stays completely silent (no text, reasoning or tool-call
+         * delta) this long, so a queued or stuck provider is cut after 90 s instead of the
+         * whole-run `timeoutMs`. 0 disables it (models that do not stream their reasoning can stay
+         * silent for minutes: raise or disable it for those).
+         */
+        firstTokenTimeoutMs: z.number().int().min(0).default(90000),
+        /**
+         * How many times the SAME request is sent again after it stayed silent for
+         * `firstTokenTimeoutMs` (a stalled connection usually answers on the next try). 0
+         * disables the retry. Never counts as a turn.
+         */
+        firstTokenRetries: z.number().int().min(0).max(3).default(1),
         maxContextChars: z.number().int().positive().default(800000),
         /**
          * Per-call output token budget for one agent turn. 4096 starves reasoning-heavy models,
@@ -178,10 +198,130 @@ const configObjectSchema = z
     })
         .default(() => ({
         maxTurns: 100,
-        timeoutMs: 300000,
+        timeoutMs: 600000,
+        firstTokenTimeoutMs: 90000,
+        firstTokenRetries: 1,
         maxContextChars: 800000,
         maxOutputTokens: 16384,
     })),
+    /**
+     * Python analysis and downloadable artifacts. `enabled: false` registers none of the
+     * analysis tools. The interpreter is discovered automatically (or pinned with `--python`).
+     */
+    analysis: z
+        .object({
+        enabled: z.boolean().default(true),
+        /**
+         * Where `python_run` executes. `managed` is the discovered Python (not a sandbox); `oci`
+         * is a Docker or Podman container started from a pinned image. GLOBAL ONLY: a project
+         * layer cannot choose the runtime or the image (it is ignored with a diagnostic).
+         */
+        runtime: z.enum(["managed", "oci"]).default("managed"),
+        /** Container runtime settings (global only). Used when `runtime` is `oci`. */
+        oci: z
+            .object({
+            engine: z.enum(["docker", "podman"]).default("docker"),
+            /** `name@sha256:<digest>`: an image without a digest is rejected at load time. */
+            image: z
+                .string()
+                .regex(OCI_IMAGE_PATTERN, "analysis.oci.image must be pinned by digest: <name>@sha256:<64 hex characters>")
+                .optional(),
+            memoryMb: z.number().int().min(256).max(65_536).default(2048),
+            cpus: z.number().min(0.5).max(64).default(2),
+        })
+            .strict()
+            .default(() => ({ engine: "docker", memoryMb: 2048, cpus: 2 })),
+        limits: z
+            .object({
+            /** Default and maximum run time of one python_run call. */
+            timeoutMs: z.number().int().min(1000).max(900_000).default(120_000),
+            /** Files published by one execution. */
+            maxFiles: z.number().int().min(1).max(1000).default(200),
+            maxFileBytes: z
+                .number()
+                .int()
+                .positive()
+                .default(100 * 1024 * 1024),
+            /** Total bytes published by one execution. */
+            maxOutputBytes: z
+                .number()
+                .int()
+                .positive()
+                .default(500 * 1024 * 1024),
+            /** Size cap of each stdout/stderr log of a job. */
+            maxLogBytes: z
+                .number()
+                .int()
+                .positive()
+                .default(10 * 1024 * 1024),
+        })
+            .strict()
+            .default(() => ({
+            timeoutMs: 120_000,
+            maxFiles: 200,
+            maxFileBytes: 100 * 1024 * 1024,
+            maxOutputBytes: 500 * 1024 * 1024,
+            maxLogBytes: 10 * 1024 * 1024,
+        })),
+        /** Tabular data (CSV, TSV, JSON, JSONL, XLSX) ingested into one SQLite file per dataset. */
+        data: z
+            .object({
+            /** Largest file ingested (an upload or a workspace file). */
+            maxUploadBytes: z
+                .number()
+                .int()
+                .positive()
+                .default(200 * 1024 * 1024),
+            /** Rows per sheet; a larger file stops the ingestion and leaves no dataset. */
+            maxRows: z.number().int().positive().default(5_000_000),
+            /** Time limit of one `data_query` statement; the engine process is killed past it. */
+            queryTimeoutMs: z.number().int().min(100).max(60_000).default(5000),
+            /** Sorting and filtering are disabled above this many rows (the file has no indexes). */
+            maxInteractiveRows: z.number().int().positive().default(1_000_000),
+        })
+            .strict()
+            .default(() => ({
+            maxUploadBytes: 200 * 1024 * 1024,
+            maxRows: 5_000_000,
+            queryTimeoutMs: 5000,
+            maxInteractiveRows: 1_000_000,
+        })),
+        /**
+         * Retention of analysis data (`0` disables the automatic deletion of that class). Global
+         * only: one sweep covers every workspace, so a project layer cannot shorten it.
+         */
+        retention: z
+            .object({
+            /** Logs and staging of a job; its script and inputs once no artifact is `ready`. */
+            jobsDays: z.number().int().min(0).max(3650).default(30),
+            /** The scratch folder (`work/`) of a job. */
+            intermediateDays: z.number().int().min(0).max(3650).default(7),
+            /** Artifacts older than this become `expired` (folder deleted, row kept). 0 = keep. */
+            artifactsDays: z.number().int().min(0).max(3650).default(0),
+        })
+            .strict()
+            .default(() => ({ jobsDays: 30, intermediateDays: 7, artifactsDays: 0 })),
+    })
+        .strict()
+        .default(() => ({
+        enabled: true,
+        runtime: "managed",
+        oci: { engine: "docker", memoryMb: 2048, cpus: 2 },
+        retention: { jobsDays: 30, intermediateDays: 7, artifactsDays: 0 },
+        limits: {
+            timeoutMs: 120_000,
+            maxFiles: 200,
+            maxFileBytes: 100 * 1024 * 1024,
+            maxOutputBytes: 500 * 1024 * 1024,
+            maxLogBytes: 10 * 1024 * 1024,
+        },
+        data: {
+            maxUploadBytes: 200 * 1024 * 1024,
+            maxRows: 5_000_000,
+            queryTimeoutMs: 5000,
+            maxInteractiveRows: 1_000_000,
+        },
+    })),
     tui: z
         .object({
         /** Horizontal padding (columns) around the editor input box. Editor-only. */
@@ -328,7 +468,11 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
                 form: canonical && name in canonical ? "canonical" : "alias",
             },
         ]));
-        return { config, keys: new Set(Object.keys(object)), sources };
+        const analysisRaw = object.analysis && typeof object.analysis === "object" && !Array.isArray(object.analysis)
+            ? object.analysis
+            : {};
+        const ignored = GLOBAL_ONLY_ANALYSIS.filter((key) => key in analysisRaw).map((key) => `analysis.${key}`);
+        return { config, keys: new Set(Object.keys(object)), sources, ignored, file };
     };
     const global = await parseLayer(globalFile, "global");
     // Skill activation is deliberately project-local; never carry a similarly named global field
@@ -339,8 +483,10 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
     // Parsed `provider.model` of the selected layer itself (before env/CLI overrides), used to
     // decide whether its legacy root `provider` is usable against a saved `/connect` profile.
     let selectedLegacyModel = "";
+    let ignoredKeys = [];
     if (selectedFile && selectedFile !== globalFile) {
         const selected = await parseLayer(selectedFile, options.file ? "explicit" : "project");
+        ignoredKeys = selected.ignored;
         selectedLegacyModel = selected.config.provider.model;
         const overlaid = { ...config };
         for (const key of selected.keys) {
@@ -383,6 +529,17 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
                 overlaid.builtinPlugins = { ...overlaid.builtinPlugins, ...selected.config.builtinPlugins };
                 continue;
             }
+            if (key === "analysis") {
+                // `runtime`, `oci` and `retention` are global-only (a repository must not pick the binary
+                // that runs scripts, nor shorten the retention of every workspace's data).
+                overlaid.analysis = {
+                    ...selected.config.analysis,
+                    runtime: global.config.analysis.runtime,
+                    oci: global.config.analysis.oci,
+                    retention: global.config.analysis.retention,
+                };
+                continue;
+            }
             overlaid[key] = selected.config[key];
         }
         if (selected.keys.has("mcp") || selected.keys.has("mcpServers"))
@@ -421,6 +578,7 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
                     },
                 }
                 : {}),
+            ...(ignoredKeys.length ? { ignored: ignoredKeys } : {}),
         },
     };
 }
@@ -528,7 +686,10 @@ const SETTABLE_SECTIONS = {
     tui: configObjectSchema.shape.tui.removeDefault(),
     websearch: configObjectSchema.shape.websearch.removeDefault(),
     agents: configObjectSchema.shape.agents.removeDefault(),
+    analysis: configObjectSchema.shape.analysis.removeDefault(),
 };
+const ANALYSIS_LIMITS = SETTABLE_SECTIONS.analysis.shape.limits.removeDefault();
+const ANALYSIS_RETENTION = SETTABLE_SECTIONS.analysis.shape.retention.removeDefault();
 const SETTABLE_KEYS = {
     "compaction.auto": SETTABLE_SECTIONS.compaction.shape.auto,
     "compaction.threshold": SETTABLE_SECTIONS.compaction.shape.threshold,
@@ -540,6 +701,8 @@ const SETTABLE_KEYS = {
     "limits.maxOutputTokens": SETTABLE_SECTIONS.limits.shape.maxOutputTokens,
     "limits.maxContextChars": SETTABLE_SECTIONS.limits.shape.maxContextChars,
     "limits.timeoutMs": SETTABLE_SECTIONS.limits.shape.timeoutMs,
+    "limits.firstTokenTimeoutMs": SETTABLE_SECTIONS.limits.shape.firstTokenTimeoutMs,
+    "limits.firstTokenRetries": SETTABLE_SECTIONS.limits.shape.firstTokenRetries,
     "pluginHooks.timeoutMs": SETTABLE_SECTIONS.pluginHooks.shape.timeoutMs,
     "tui.paddingX": SETTABLE_SECTIONS.tui.shape.paddingX,
     "tui.contentPaddingX": SETTABLE_SECTIONS.tui.shape.contentPaddingX,
@@ -547,6 +710,11 @@ const SETTABLE_KEYS = {
     "websearch.provider": SETTABLE_SECTIONS.websearch.shape.provider,
     "agents.active": SETTABLE_SECTIONS.agents.shape.active,
     "agents.effort": SETTABLE_SECTIONS.agents.shape.effort,
+    "analysis.enabled": SETTABLE_SECTIONS.analysis.shape.enabled,
+    "analysis.limits.timeoutMs": ANALYSIS_LIMITS.shape.timeoutMs,
+    "analysis.retention.jobsDays": ANALYSIS_RETENTION.shape.jobsDays,
+    "analysis.retention.intermediateDays": ANALYSIS_RETENTION.shape.intermediateDays,
+    "analysis.retention.artifactsDays": ANALYSIS_RETENTION.shape.artifactsDays,
 };
 export function isSettableSettingKey(key) {
     return Object.prototype.hasOwnProperty.call(SETTABLE_KEYS, key);
@@ -603,11 +771,21 @@ export async function setConfigValue(input) {
             throw new Error("Global Alisio configuration must be a JSON object");
         raw = existing;
     }
-    const [section, leaf] = input.key.split(".");
-    const container = raw[section] && typeof raw[section] === "object" && !Array.isArray(raw[section])
-        ? raw[section]
-        : {};
-    raw[section] = { ...container, [leaf]: parsed.data };
+    // Keys are `section.leaf` or `section.group.leaf`: every object on the path keeps its other fields.
+    const path = input.key.split(".");
+    const setPath = (target, depth) => {
+        const name = path[depth];
+        if (depth === path.length - 1)
+            return { ...target, [name]: parsed.data };
+        const child = target[name];
+        return {
+            ...target,
+            [name]: setPath(child && typeof child === "object" && !Array.isArray(child)
+                ? child
+                : {}, depth + 1),
+        };
+    };
+    raw = setPath(raw, 0);
     raw.schemaVersion ??= 1;
     await mkdir(dirname(file), { recursive: true, mode: 0o700 });
     const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;

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;
@@ -188,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 {
@@ -199,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/runner.d.ts

@@ -1,6 +1,6 @@
-import { type Attachment, type Message, type ModelProvider, type RunEvent, type ToolDefinition } from "@alisio/sdk";
+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, ContextSource, Policy, RunnerExtensions, SessionStore } from "./contracts.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. */
@@ -24,6 +24,10 @@ export interface RunnerOptions {
     workspace: string;
     maxTurns?: number;
     timeoutMs?: number;
+    /** See `RunnerSettingsPatch.firstTokenTimeoutMs`. */
+    firstTokenTimeoutMs?: number;
+    /** See `RunnerSettingsPatch.firstTokenRetries`. */
+    firstTokenRetries?: number;
     maxContextChars?: number;
     maxOutputTokens?: number;
     maxTokens?: number;
@@ -42,6 +46,10 @@ export interface RunnerOptions {
     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
@@ -66,6 +74,17 @@ 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;
 }
 /**
  * Per-run overrides used by embedders and child sessions. Callers must only NARROW: `policy`
@@ -76,6 +95,8 @@ 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;
@@ -91,6 +112,10 @@ export interface RunOptions {
     /** 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;
     /** 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. */
@@ -130,8 +155,11 @@ export declare class AgentRunner {
      */
     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;
@@ -182,6 +210,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;