@alisio/core 0.1.1 → 0.2.1

package/dist/application.js

@@ -16,6 +16,7 @@ import { subagentTasks } from "./background/mirror.js";
 import { BackgroundTasks } from "./background/service.js";
 import { configFile, configHome, loadConfigWithProvenance, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
 import { completeText } from "./core/compaction.js";
+import { HumanWaits } from "./core/human-wait.js";
 import { DEFAULT_MAX_OUTPUT_TOKENS } from "./core/output-limit.js";
 import { ToolRegistry } from "./core/registry.js";
 import { AgentRunner } from "./core/runner.js";
@@ -86,11 +87,25 @@ export async function createApplication(options = {}) {
     const addDirs = options.readOnly
         ? []
         : await Promise.all((options.addDirs ?? []).map((dir) => realpath(resolve(cwd, dir)).catch(() => resolve(cwd, dir))));
+    // Waits for a person (approvals, questions, the plan review) do not count against the run's
+    // time limit. One registry serves the runner, the plugin host's interactive UI and the
+    // external-directory approval, so every host (TUI, web server, embedders) gets it for free.
+    const humanWaits = new HumanWaits((session) => {
+        try {
+            return store.get(session).parentId ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    });
+    const askExternalDirectory = options.approveExternalDirectory;
     const pathAccess = new PathAccess({
         workspace,
         extraRoots: [...config.additionalDirectories, ...addDirs],
-        ...(options.approveExternalDirectory && !options.readOnly
-            ? { approve: options.approveExternalDirectory }
+        ...(askExternalDirectory && !options.readOnly
+            ? {
+                approve: (request) => humanWaits.track(request.session, () => askExternalDirectory(request)),
+            }
             : {}),
         readOnly: !!options.readOnly,
     });
@@ -413,7 +428,15 @@ export async function createApplication(options = {}) {
         }
         // `exit_plan` (opt-in: only the plan agent's run sees it): the plan review hand-over.
         const { registerExitPlan } = await import("./plan/exit-plan.js");
-        registerExitPlan(registry, { store, ui: plugins.ui, readOnly: !!options.readOnly });
+        registerExitPlan(registry, {
+            store,
+            ui: plugins.ui,
+            readOnly: !!options.readOnly,
+            diagrams: () => ({
+                enabled: config.plan.diagrams,
+                max: config.plan.diagrams ? config.plan.maxDiagrams : 0,
+            }),
+        });
         // Data tools only read (effect `read`): they stay available under --read-only.
         if (config.analysis.enabled) {
             const { registerDataTools } = await import("./tools/data.js");
@@ -722,7 +745,9 @@ export async function createApplication(options = {}) {
                 : [];
             return declared.length ? Math.min(...declared) : undefined;
         };
+        plugins.setHumanWaits(humanWaits);
         const runner = new AgentRunner({
+            humanWaits,
             provider,
             providerFor,
             registry,
@@ -1152,6 +1177,13 @@ export async function createApplication(options = {}) {
                         };
                         break;
                     }
+                    case "plan.diagrams":
+                        // Read live: `exit_plan` offers (or hides) its `diagrams` field on the next request.
+                        config.plan = { ...config.plan, diagrams: value === true };
+                        break;
+                    case "plan.maxDiagrams":
+                        config.plan = { ...config.plan, maxDiagrams: Number(value) };
+                        break;
                     case "tasks.enabled":
                         // Tools are registered when the application starts: the change applies to the next
                         // application (a restart; the web recycles the workspace application).

package/dist/artifacts/chart-lint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A cheap, deterministic quality gate for HTML dashboards: it spots the chart mistakes that models
+ * make when they hand-write charts (SVG pie arcs, fixed-size SVGs, libraries loaded from a CDN that
+ * the viewer blocks) and names the helper that avoids them. It only produces warnings for the
+ * `python_run` / `artifact_create` result; it never rejects an artifact.
+ */
+/** Warnings (empty when the page looks fine) for one HTML document. */
+export declare function chartWarnings(html: string): string[];

package/dist/artifacts/chart-lint.js

@@ -0,0 +1,84 @@
+/**
+ * A cheap, deterministic quality gate for HTML dashboards: it spots the chart mistakes that models
+ * make when they hand-write charts (SVG pie arcs, fixed-size SVGs, libraries loaded from a CDN that
+ * the viewer blocks) and names the helper that avoids them. It only produces warnings for the
+ * `python_run` / `artifact_create` result; it never rejects an artifact.
+ */
+const HELPERS = "alisio_runtime.charts (Chart.js, interactive) or alisio_runtime.svg (static)";
+/** Strips scripts and styles so a bundled library never triggers the markup checks. */
+function markupOf(html) {
+    return html
+        .replace(/(<script\b[^>]*>)[\s\S]*?<\/script\s*>/gi, "$1</script>")
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, "<style></style>");
+}
+/** `d` attributes that draw a wedge: a line to/from the centre, an arc command and a close. */
+function wedgeCount(markup) {
+    let count = 0;
+    for (const match of markup.matchAll(/<path\b[^>]*?\sd\s*=\s*["']([^"']*)["']/gi)) {
+        const d = match[1] ?? "";
+        if (/[Aa]\s*[\d.]+[\s,]+[\d.]+[\s,]+-?[\d.]+[\s,]+[01][\s,]*[01]/.test(d) &&
+            /[Ll]/.test(d) &&
+            /[Zz]/.test(d))
+            count++;
+    }
+    return count;
+}
+const numeric = (value) => {
+    const match = /^\s*(\d+(?:\.\d+)?)(?:px)?\s*$/.exec(value ?? "");
+    return match ? Number(match[1]) : undefined;
+};
+/** Fixed-size SVG charts: numeric width and height, no `viewBox` (they do not scale with the card). */
+function fixedSvgCount(markup) {
+    let count = 0;
+    for (const block of markup.split(/<svg\b/i).slice(1)) {
+        const tagEnd = block.indexOf(">");
+        if (tagEnd < 0)
+            continue;
+        const tag = block.slice(0, tagEnd);
+        const body = block.slice(tagEnd, Math.max(tagEnd, block.search(/<\/svg\s*>/i)));
+        const attr = (name) => new RegExp(`\\s${name}\\s*=\\s*["']([^"']*)["']`, "i").exec(tag)?.[1];
+        const width = numeric(attr("width"));
+        const height = numeric(attr("height"));
+        const drawn = (body.match(/<(?:rect|path|polyline|circle|line)\b/gi) ?? []).length;
+        if (width !== undefined &&
+            height !== undefined &&
+            width >= 150 &&
+            drawn >= 4 &&
+            !/\sviewBox\s*=/i.test(tag))
+            count++;
+    }
+    return count;
+}
+/** `<script src>`, `<link href>` and `@import` that point at the network. */
+function remoteHosts(markup, html) {
+    const hosts = new Set();
+    const sources = [
+        ...markup.matchAll(/<script\b[^>]*\ssrc\s*=\s*["']((?:https?:)?\/\/[^"']+)["']/gi),
+        ...markup.matchAll(/<link\b[^>]*\shref\s*=\s*["']((?:https?:)?\/\/[^"']+)["']/gi),
+        ...html.matchAll(/@import\s+(?:url\()?["']?((?:https?:)?\/\/[^"')\s]+)/gi),
+    ];
+    for (const match of sources) {
+        try {
+            hosts.add(new URL(match[1].replace(/^\/\//, "https://")).host);
+        }
+        catch {
+            // Not a URL: ignore it.
+        }
+    }
+    return [...hosts];
+}
+/** Warnings (empty when the page looks fine) for one HTML document. */
+export function chartWarnings(html) {
+    const markup = markupOf(html);
+    const warnings = [];
+    const hosts = remoteHosts(markup, html);
+    if (hosts.length)
+        warnings.push(`loads resources from the network (${hosts.slice(0, 3).join(", ")}); the viewer blocks the network, so they will not load. Charts: use ${HELPERS}, which inlines Chart.js`);
+    const wedges = wedgeCount(markup);
+    if (wedges >= 2)
+        warnings.push(`${wedges} hand-written SVG arc paths look like a pie or donut; hand-written arcs are often wrong (large-arc flag, 100% slice). Use charts.pie/donut or svg.pie/donut`);
+    const fixed = fixedSvgCount(markup);
+    if (fixed)
+        warnings.push(`${fixed} SVG chart${fixed === 1 ? "" : "s"} with a fixed width and height and no viewBox will not scale with its container (small text, empty space). Use ${HELPERS}, or give the SVG a viewBox and width:100%`);
+    return warnings;
+}

package/dist/artifacts/publisher.js

@@ -8,6 +8,9 @@ export function createArtifactPublisher(store, owner, announce) {
         async publish(input) {
             return done(await store.publish(input, owner)).artifact;
         },
+        async publishDetailed(input) {
+            return done(await store.publish(input, owner));
+        },
         async publishText(input) {
             return done(await store.publishText(input, owner)).artifact;
         },

package/dist/artifacts/store.d.ts

@@ -71,7 +71,9 @@ export declare class ArtifactStore {
         title?: string;
     }): Promise<PublishedArtifact[]>;
     /** Publishes one caller-owned file or directory. */
-    publish(input: ArtifactPublishInput, owner: ArtifactOwner): Promise<PublishedArtifact>;
+    publish(input: ArtifactPublishInput & {
+        fileName?: string;
+    }, owner: ArtifactOwner): Promise<PublishedArtifact>;
     /** Publishes a single text file the caller holds in memory. */
     publishText(input: {
         fileName: string;

package/dist/artifacts/store.js

@@ -11,6 +11,7 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { newId } from "../runtime/ids.js";
 import { inside, workspaceKey } from "../runtime/paths.js";
 import { writeZip } from "../runtime/zip.js";
+import { chartWarnings } from "./chart-lint.js";
 import { classifyArtifact, isPreviewable } from "./kinds.js";
 export const DEFAULT_ARTIFACT_LIMITS = {
     maxFiles: 200,
@@ -21,6 +22,8 @@ export const DEFAULT_ARTIFACT_LIMITS = {
 export class ArtifactRejected extends Error {
 }
 const MAX_DEPTH = 8;
+/** HTML larger than this is not scanned for chart mistakes. */
+const MAX_LINT_BYTES = 8 * 1024 * 1024;
 const HEAD_BYTES = 8192;
 /** `title` → `[a-z0-9-]`, at most 48 characters (`artifact` when nothing remains). */
 export function slugify(title) {
@@ -200,6 +203,7 @@ export class ArtifactStore {
                 source: resolve(input.source),
                 ...(input.title ? { title: input.title } : {}),
                 ...(input.entry ? { entry: input.entry } : {}),
+                ...(input.fileName ? { fileName: checkName(input.fileName) } : {}),
             },
         ], owner);
         return published;
@@ -380,19 +384,25 @@ export class ArtifactStore {
                     kind = type.kind;
                     mimeType = type.mimeType;
                     fileName = only.path;
+                    if (kind === "dashboard" && only.bytes <= MAX_LINT_BYTES)
+                        for (const note of chartWarnings(await readFile(join(filesDir, only.path), "utf8")))
+                            warnings.push(`${label}: ${note}`);
                 }
                 else {
                     entry = plan.entry;
                     const type = classifyArtifact(entry, await readHead(join(filesDir, ...entry.split("/"))));
                     kind = type.kind;
                     mimeType = type.mimeType;
-                    fileName = files.length > 1 ? `${baseName}.zip` : basename(entry);
+                    fileName =
+                        plan.candidate.fileName ?? (files.length > 1 ? `${baseName}.zip` : basename(entry));
                     if (type.kind === "dashboard") {
                         const html = await readFile(join(filesDir, ...entry.split("/")), "utf8");
                         const entryDir = entry.includes("/") ? entry.slice(0, entry.lastIndexOf("/")) : "";
                         const missing = missingReferences(html, entryDir, new Set(files.map((f) => f.path)));
                         if (missing.length)
                             warnings.push(`${label}: ${entry} references missing files: ${missing.join(", ")}`);
+                        for (const note of chartWarnings(html))
+                            warnings.push(`${label}: ${entry} ${note}`);
                     }
                 }
             }

package/dist/changelog/data.js

@@ -2,9 +2,55 @@
 export const CHANGELOG_DATA = {
     schema: 1,
     entries: [
+        {
+            version: "0.2.1",
+            date: "2026-10-02",
+            sections: [
+                {
+                    title: "Fixed",
+                    items: [
+                        'A run no longer stops with "reached its 600 s limit" while you read a plan or answer a question. The run time limit (`limits.timeoutMs`) now counts only active time: the time the agent waits for you (the plan review, a question, a tool approval) is not counted. A model or tool that really stalls still hits the limit. The same applies to the `goal.maxMinutes` cap of a session goal.',
+                        'A run that ended or was stopped during a plan review no longer leaves the next message failing with an "Uncertain tool outcome" error.',
+                        "In the web, a plan review or a question can wait up to 60 minutes for your answer (tool approvals still expire after 10 minutes).",
+                        'The Settings label of `limits.timeoutMs` said "Provider request timeout"; it now says it is the run time limit.',
+                    ],
+                },
+            ],
+        },
+        {
+            version: "0.2.0",
+            date: "2026-10-02",
+            sections: [
+                {
+                    title: "Added",
+                    items: [
+                        "Plan diagrams: the plan agent can attach small Mermaid diagrams (flows, sequences, architecture) to the plan it proposes with `exit_plan`.",
+                        "A plan viewer in the web UI: the plan opens in the artifact panel with its diagrams drawn in your theme, next to the plan review. The terminal shows the diagram source.",
+                        "Plan files are saved in a plan folder with a `plan.json` manifest, so the plan and its diagrams are easy to find and reuse.",
+                        "Two new settings, `plan.diagrams` and `plan.maxDiagrams` (in the configuration file, **Settings** in the web and `/settings` in the terminal), to turn diagrams off or cap how many a plan keeps.",
+                        "Dashboard charts for Python analysis: `alisio_runtime.charts` builds interactive pie, donut, bar, line, area and scatter charts, KPI tiles and cards with an embedded Chart.js (MIT), so dashboards work offline, in the viewer and in the downloaded file.",
+                    ],
+                },
+                {
+                    title: "Improved",
+                    items: [
+                        "Charts adapt to their card and follow the light and dark theme, with value labels, tooltips and a data table for screen readers.",
+                        "The pure-SVG helpers (`alisio_runtime.svg`) were rewritten: they scale with their container and carry a title and description.",
+                        "The agent receives clearer guidance for `python_run` about how to draw charts and dashboards.",
+                    ],
+                },
+                {
+                    title: "Fixed",
+                    items: [
+                        "Pie charts drew wrong or broken slices in generated dashboards (including a single 100% slice), and bar charts rendered at a fixed small size.",
+                        "A dashboard that draws SVG pies by hand, uses fixed-size SVG charts or loads a script from the network now gets a warning in the `python_run` result that points to the chart helpers.",
+                    ],
+                },
+            ],
+        },
         {
             version: "0.1.1",
-            date: "2026-10-03",
+            date: "2026-10-02",
             sections: [
                 {
                     title: "Fixed",

package/dist/config.d.ts

@@ -231,6 +231,10 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         noToolTurnsLimit: z.ZodDefault<z.ZodNumber>;
         blockedRepeats: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
+    plan: z.ZodDefault<z.ZodObject<{
+        diagrams: z.ZodDefault<z.ZodBoolean>;
+        maxDiagrams: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
     tui: z.ZodDefault<z.ZodObject<{
         paddingX: z.ZodDefault<z.ZodNumber>;
         contentPaddingX: z.ZodDefault<z.ZodNumber>;
@@ -338,6 +342,10 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         noToolTurnsLimit: number;
         blockedRepeats: number;
     };
+    plan: {
+        diagrams: boolean;
+        maxDiagrams: number;
+    };
     tui: {
         paddingX: number;
         contentPaddingX: number;
@@ -528,6 +536,10 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         noToolTurnsLimit: number;
         blockedRepeats: number;
     };
+    plan: {
+        diagrams: boolean;
+        maxDiagrams: number;
+    };
     tui: {
         paddingX: number;
         contentPaddingX: number;
@@ -643,6 +655,8 @@ declare const SETTABLE_KEYS: {
     readonly "goal.repeatedReplyLimit": z.ZodDefault<z.ZodNumber>;
     readonly "goal.noToolTurnsLimit": z.ZodDefault<z.ZodNumber>;
     readonly "goal.blockedRepeats": z.ZodDefault<z.ZodNumber>;
+    readonly "plan.diagrams": z.ZodDefault<z.ZodBoolean>;
+    readonly "plan.maxDiagrams": z.ZodDefault<z.ZodNumber>;
 };
 export type SettableSettingKey = keyof typeof SETTABLE_KEYS;
 export declare function isSettableSettingKey(key: string): key is SettableSettingKey;

package/dist/config.js

@@ -386,6 +386,18 @@ const configObjectSchema = z
         noToolTurnsLimit: 3,
         blockedRepeats: 2,
     })),
+    /**
+     * Plan diagrams (`exit_plan`): the plan agent may add Mermaid diagrams to a plan. `diagrams`
+     * off removes them from the tool and from the agent's instructions; `maxDiagrams` caps how
+     * many one plan keeps (0 to 8). The size and node limits of one diagram are constants.
+     */
+    plan: z
+        .object({
+        diagrams: z.boolean().default(true),
+        maxDiagrams: z.number().int().min(0).max(8).default(5),
+    })
+        .strict()
+        .default(() => ({ diagrams: true, maxDiagrams: 5 })),
     tui: z
         .object({
         /** Horizontal padding (columns) around the editor input box. Editor-only. */
@@ -767,6 +779,7 @@ const SETTABLE_SECTIONS = {
     analysis: configObjectSchema.shape.analysis.removeDefault(),
     tasks: configObjectSchema.shape.tasks.removeDefault(),
     goal: configObjectSchema.shape.goal.removeDefault(),
+    plan: configObjectSchema.shape.plan.removeDefault(),
 };
 const ANALYSIS_LIMITS = SETTABLE_SECTIONS.analysis.shape.limits.removeDefault();
 const ANALYSIS_RETENTION = SETTABLE_SECTIONS.analysis.shape.retention.removeDefault();
@@ -807,6 +820,8 @@ const SETTABLE_KEYS = {
     "goal.repeatedReplyLimit": SETTABLE_SECTIONS.goal.shape.repeatedReplyLimit,
     "goal.noToolTurnsLimit": SETTABLE_SECTIONS.goal.shape.noToolTurnsLimit,
     "goal.blockedRepeats": SETTABLE_SECTIONS.goal.shape.blockedRepeats,
+    "plan.diagrams": SETTABLE_SECTIONS.plan.shape.diagrams,
+    "plan.maxDiagrams": SETTABLE_SECTIONS.plan.shape.maxDiagrams,
 };
 export function isSettableSettingKey(key) {
     return Object.prototype.hasOwnProperty.call(SETTABLE_KEYS, key);

package/dist/core/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { AnalysisCapability, ArtifactPublisher, ArtifactRef, CompactionCheckpoint, InstallPreview, Message, ToolCall, ToolResult } from "@alisio/sdk";
+import type { AnalysisCapability, ArtifactPublisher, ArtifactPublishInput, ArtifactRef, CompactionCheckpoint, InstallPreview, Message, ToolCall, ToolResult } from "@alisio/sdk";
 export interface Session {
     id: string;
     workspace: string;
@@ -255,6 +255,13 @@ export interface CoreArtifactPublisher extends ArtifactPublisher {
         partial?: boolean;
         provenance?: Record<string, unknown>;
     }): Promise<PublishedArtifactInfo[]>;
+    /**
+     * Detailed variant of `publish` (path and warnings). `fileName` names a multi-file folder with
+     * an `entry` after its main file (`plan.md`) instead of `<folder>.zip`; downloads are still ZIPs.
+     */
+    publishDetailed(input: ArtifactPublishInput & {
+        fileName?: string;
+    }): Promise<PublishedArtifactInfo>;
     /** Detailed variant of `publishText` (path and warnings). */
     publishTextDetailed(input: {
         fileName: string;

package/dist/core/human-wait.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Human waits: the moments a run is blocked on a PERSON (a tool approval, an external-directory
+ * approval, `ask_user_question`, the plan review) and not on work. The run's time limit does not
+ * count them (see `RunClock`).
+ *
+ * One registry per application. Each active run registers its clock under its session; anything
+ * that asks a person goes through `track`, which pauses the clocks involved until the answer
+ * arrives. A child session (a subagent) pauses its own clock AND its ancestors': a parent that
+ * waits for a child is doing real work, but when that child waits for a person nobody works.
+ */
+import type { RunClock } from "./run-clock.ts";
+export declare class HumanWaits {
+    private readonly parentOf;
+    private clocks;
+    constructor(parentOf?: (session: string) => string | undefined);
+    /** A run began: its clock follows the waits of its session. Returns the unregister function. */
+    register(session: string, clock: RunClock): () => void;
+    /**
+     * Opens a wait for `session` (the session asking; its ancestors are paused too). Without a
+     * session every active run is paused: somebody is being asked and nobody can say who for.
+     */
+    begin(session?: string): () => void;
+    /** Runs `wait` as a human wait: the clocks are paused until it settles, however it settles. */
+    track<T>(session: string | undefined, wait: () => Promise<T>): Promise<T>;
+}

package/dist/core/human-wait.js

@@ -0,0 +1,54 @@
+export class HumanWaits {
+    parentOf;
+    clocks = new Map();
+    constructor(parentOf = () => undefined) {
+        this.parentOf = parentOf;
+    }
+    /** A run began: its clock follows the waits of its session. Returns the unregister function. */
+    register(session, clock) {
+        this.clocks.set(session, clock);
+        return () => {
+            if (this.clocks.get(session) === clock)
+                this.clocks.delete(session);
+        };
+    }
+    /**
+     * Opens a wait for `session` (the session asking; its ancestors are paused too). Without a
+     * session every active run is paused: somebody is being asked and nobody can say who for.
+     */
+    begin(session) {
+        const releases = [];
+        if (session === undefined)
+            for (const clock of this.clocks.values())
+                releases.push(clock.pause());
+        else {
+            const seen = new Set();
+            for (let id = session; id !== undefined && !seen.has(id);) {
+                seen.add(id);
+                const clock = this.clocks.get(id);
+                if (clock)
+                    releases.push(clock.pause());
+                try {
+                    id = this.parentOf(id);
+                }
+                catch {
+                    id = undefined;
+                }
+            }
+        }
+        return () => {
+            for (const release of releases)
+                release();
+        };
+    }
+    /** Runs `wait` as a human wait: the clocks are paused until it settles, however it settles. */
+    async track(session, wait) {
+        const end = this.begin(session);
+        try {
+            return await wait();
+        }
+        finally {
+            end();
+        }
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * The run's time limit (`limits.timeoutMs`) as a PAUSABLE clock.
+ *
+ * The limit exists to stop runaway work (a stuck model, a looping tool), not to cap how long a
+ * person takes to read a plan or answer a question. So the clock counts ACTIVE time only: while at
+ * least one human wait is open (an approval, a question, a plan review) it is paused, and it
+ * resumes with the remaining time when the last wait ends.
+ *
+ * Waits nest and overlap (several tools can wait for approvals in parallel), so pausing is
+ * counted: the clock runs again only when every pause was released. A pause is released exactly
+ * once (the function `pause()` returns is idempotent), and a released or disposed clock ignores
+ * late calls, so an aborted run can never leave a timer behind.
+ */
+/** Time source and timers, replaceable in tests. */
+export interface ClockSource {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare class RunClock {
+    readonly limitMs: number;
+    private readonly controller;
+    private readonly source;
+    private consumed;
+    /** Start of the current running stretch (undefined while paused or finished). */
+    private since;
+    private timer;
+    private pauses;
+    private done;
+    constructor(limitMs: number, source?: ClockSource);
+    /** Aborts with a `TimeoutError` (the same reason `AbortSignal.timeout` uses) at the limit. */
+    get signal(): AbortSignal;
+    /** Whether at least one human wait is open. */
+    get paused(): boolean;
+    /** Time the run was really working: elapsed time minus every paused stretch. */
+    activeMs(): number;
+    remainingMs(): number;
+    /**
+     * Opens a human wait. Returns the function that closes it (idempotent). Pausing a clock that
+     * already ended (limit reached or disposed) does nothing.
+     */
+    pause(): () => void;
+    /** Stops the clock for good and frees its timer (call when the run ends, whatever the reason). */
+    dispose(): void;
+    private arm;
+    private disarm;
+}

package/dist/core/run-clock.js

@@ -0,0 +1,111 @@
+/**
+ * The run's time limit (`limits.timeoutMs`) as a PAUSABLE clock.
+ *
+ * The limit exists to stop runaway work (a stuck model, a looping tool), not to cap how long a
+ * person takes to read a plan or answer a question. So the clock counts ACTIVE time only: while at
+ * least one human wait is open (an approval, a question, a plan review) it is paused, and it
+ * resumes with the remaining time when the last wait ends.
+ *
+ * Waits nest and overlap (several tools can wait for approvals in parallel), so pausing is
+ * counted: the clock runs again only when every pause was released. A pause is released exactly
+ * once (the function `pause()` returns is idempotent), and a released or disposed clock ignores
+ * late calls, so an aborted run can never leave a timer behind.
+ */
+/** Longest delay a timer supports; a longer limit re-arms itself. */
+const MAX_TIMER_MS = 2_147_483_647;
+const realSource = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => {
+        const timer = setTimeout(fn, ms);
+        // Like `AbortSignal.timeout`: the limit alone never keeps the process alive.
+        timer.unref?.();
+        return timer;
+    },
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export class RunClock {
+    limitMs;
+    controller = new AbortController();
+    source;
+    consumed = 0;
+    /** Start of the current running stretch (undefined while paused or finished). */
+    since;
+    timer;
+    pauses = 0;
+    done = false;
+    constructor(limitMs, source = realSource) {
+        this.limitMs = limitMs;
+        this.source = source;
+        this.since = source.now();
+        this.arm();
+    }
+    /** Aborts with a `TimeoutError` (the same reason `AbortSignal.timeout` uses) at the limit. */
+    get signal() {
+        return this.controller.signal;
+    }
+    /** Whether at least one human wait is open. */
+    get paused() {
+        return this.pauses > 0;
+    }
+    /** Time the run was really working: elapsed time minus every paused stretch. */
+    activeMs() {
+        return (this.consumed + (this.since === undefined ? 0 : Math.max(0, this.source.now() - this.since)));
+    }
+    remainingMs() {
+        return Math.max(0, this.limitMs - this.activeMs());
+    }
+    /**
+     * Opens a human wait. Returns the function that closes it (idempotent). Pausing a clock that
+     * already ended (limit reached or disposed) does nothing.
+     */
+    pause() {
+        if (this.done)
+            return () => { };
+        if (this.pauses++ === 0) {
+            if (this.since !== undefined)
+                this.consumed += Math.max(0, this.source.now() - this.since);
+            this.since = undefined;
+            this.disarm();
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (this.done)
+                return;
+            if (--this.pauses === 0) {
+                this.since = this.source.now();
+                this.arm();
+            }
+        };
+    }
+    /** Stops the clock for good and frees its timer (call when the run ends, whatever the reason). */
+    dispose() {
+        if (this.done)
+            return;
+        this.consumed = this.activeMs();
+        this.done = true;
+        this.since = undefined;
+        this.disarm();
+    }
+    arm() {
+        this.disarm();
+        this.timer = this.source.setTimeout(() => {
+            this.timer = undefined;
+            if (this.done || this.pauses > 0)
+                return;
+            if (this.remainingMs() > 0)
+                return this.arm();
+            this.consumed = this.activeMs();
+            this.done = true;
+            this.since = undefined;
+            this.controller.abort(new DOMException("The operation timed out.", "TimeoutError"));
+        }, Math.min(this.remainingMs(), MAX_TIMER_MS));
+    }
+    disarm() {
+        if (this.timer !== undefined)
+            this.source.clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+}

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

@@ -11,6 +11,8 @@ export interface RunStats {
         output: number;
     };
     toolCalls: number;
+    /** Active time of the run (waits for a person excluded). */
+    activeMs?: number;
 }
 export declare function attachRunStats(error: unknown, stats: RunStats): void;
 export declare function runStatsOf(error: unknown): RunStats | undefined;