@alisio/core 0.1.1 → 0.2.1

package/dist/core/runner.d.ts

@@ -1,6 +1,7 @@
 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 { HumanWaits } from "./human-wait.ts";
 import type { ToolRegistry } from "./registry.ts";
 export interface CompactionSettings {
     /** Compact automatically when context usage crosses `threshold` of a known window. */
@@ -62,6 +63,13 @@ export interface RunnerOptions {
     compaction?: CompactionSettings;
     /** When set, write/process tools not allowed by the policy are offered and ask first. */
     approve?: ApprovalHandler;
+    /**
+     * Registry of the waits for a person (approvals, questions, the plan review): the run's time
+     * limit does not count them. Share one with the plugin host and every other asking surface so a
+     * wait outside the runner (for example `ask_user_question`) pauses the same clocks. Without it
+     * the runner uses a private one, which still covers every approval it asks itself.
+     */
+    humanWaits?: HumanWaits;
     /**
      * 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.
@@ -179,6 +187,8 @@ export declare class AgentRunner {
     private inbox;
     /** Last provider-reported context size per session and the history length it covered. */
     private reported;
+    /** Where human waits are opened; the clocks of the active runs listen to it. */
+    readonly humanWaits: HumanWaits;
     constructor(options: RunnerOptions);
     /** Current capability policy (may widen when the user approves an effect for the session). */
     get policy(): Readonly<Policy>;
@@ -284,5 +294,7 @@ export declare class AgentRunner {
         };
         /** Tool calls the model made during the run (the goal controller's no-progress breaker). */
         toolCalls: number;
+        /** Time the run was really working: wall time minus the waits for a person. */
+        activeMs: number;
     }>;
 }

package/dist/core/runner.js

@@ -1,7 +1,9 @@
 import { isEphemeralRunEventType, textProjection, textResult, } from "@alisio/sdk";
 import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { HumanWaits } from "./human-wait.js";
 import { EXIT_PLAN_TOOL, optInAllows } from "./opt-in.js";
 import { resolveMaxOutputTokens } from "./output-limit.js";
+import { RunClock } from "./run-clock.js";
 import { attachRunStats } from "./run-stats.js";
 import { isTimeoutReason, providerLabel, RunTimeoutError } from "./timeout.js";
 import { incompleteCalls, isOutputTruncationError, lowerEffort, RunTruncationError, TRUNCATION_NOTICE, } from "./truncation.js";
@@ -60,8 +62,20 @@ export class AgentRunner {
     inbox = new Map();
     /** Last provider-reported context size per session and the history length it covered. */
     reported = new Map();
+    /** Where human waits are opened; the clocks of the active runs listen to it. */
+    humanWaits;
     constructor(options) {
         this.options = options;
+        this.humanWaits =
+            options.humanWaits ??
+                new HumanWaits((session) => {
+                    try {
+                        return options.store.get(session).parentId ?? undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                });
     }
     /** Current capability policy (may widen when the user approves an effect for the session). */
     get policy() {
@@ -465,17 +479,20 @@ export class AgentRunner {
                     ...(options.label ? { label: options.label } : {}),
                     ...(capability ? { capability } : {}),
                 });
-                const decision = await o.approve({
+                const approve = o.approve;
+                const callInput = p.input;
+                // Waiting for the person is not work: the run's time limit does not count it.
+                const decision = await this.humanWaits.track(sessionId, () => approve({
                     call,
                     effect,
-                    input: p.input,
+                    input: callInput,
                     signal: combined,
                     session: sessionId,
                     ...(options.label ? { label: options.label } : {}),
                     ...(capability ? { capability } : {}),
                     ...(preview !== undefined ? { preview } : {}),
                     ...(capability && gate?.runtime ? { runtime: gate.runtime } : {}),
-                });
+                }));
                 combined.throwIfAborted();
                 const persisted = !!capability && !!gate && decision === "session";
                 if (capability && gate)
@@ -530,7 +547,8 @@ export class AgentRunner {
                 });
                 let decision = "deny";
                 try {
-                    decision = await o.approve({
+                    const approve = o.approve;
+                    decision = await this.humanWaits.track(sessionId, () => approve({
                         call: installCall,
                         effect: "process",
                         input: { extras: install.extras },
@@ -539,7 +557,7 @@ export class AgentRunner {
                         ...(options.label ? { label: options.label } : {}),
                         capability: "analysis.install",
                         install,
-                    });
+                    }));
                 }
                 finally {
                     combined.throwIfAborted();
@@ -607,8 +625,12 @@ export class AgentRunner {
         }
         catch (error) {
             result = textResult(error instanceof Error ? error.message : String(error), true);
-            // A cancellation after execution may have left effects; journal remains pending.
-            if (!combined.aborted)
+            // A cancellation after execution may have left effects, so the journal stays pending for
+            // the user to inspect. A `read` call cannot have left any (and `exit_plan`, which is one,
+            // is exactly what a stop or the run limit interrupts while a person decides): it is closed
+            // with the cancellation, so the next message continues normally instead of asking to
+            // "recover" a call nobody needs to inspect.
+            if (!combined.aborted || p.tool?.effect === "read")
                 o.store.endCall(sessionId, call, result);
         }
         emit("tool_completed", {
@@ -649,10 +671,11 @@ export class AgentRunner {
             }
         };
         const runTimeoutMs = options.timeoutMs ?? o.timeoutMs ?? 300_000;
-        const timeout = AbortSignal.timeout(runTimeoutMs);
+        const clock = new RunClock(runTimeoutMs);
+        const unregisterClock = this.humanWaits.register(sessionId, clock);
         const combined = AbortSignal.any([
             controller.signal,
-            timeout,
+            clock.signal,
             ...(options.signal ? [options.signal] : []),
         ]);
         const workspace = options.workspace ?? o.workspace;
@@ -730,6 +753,8 @@ export class AgentRunner {
             throw error;
         }
         finally {
+            unregisterClock();
+            clock.dispose();
             if (acquired)
                 o.store.release(sessionId);
             this.active.delete(sessionId);
@@ -760,9 +785,14 @@ export class AgentRunner {
         /** Continuation notice and lowered effort for the request that follows a cut-off response. */
         let recoveryNotice;
         let recoveryEffort;
-        const runStartedAt = Date.now();
-        const timeout = AbortSignal.timeout(runTimeoutMs);
-        const combined = AbortSignal.any([controller.signal, timeout, ...(signal ? [signal] : [])]);
+        // Active time only: waits for a person pause it (see `RunClock`).
+        const clock = new RunClock(runTimeoutMs);
+        const unregisterClock = this.humanWaits.register(sessionId, clock);
+        const combined = AbortSignal.any([
+            controller.signal,
+            clock.signal,
+            ...(signal ? [signal] : []),
+        ]);
         // What the run was doing, so a timeout can say where it was stuck (see `RunTimeoutError`).
         let stage = "other";
         let stageTool;
@@ -1006,7 +1036,7 @@ export class AgentRunner {
                     }
                     // Do not start an attempt the whole-run limit could not let finish.
                     const retryPauseMs = FIRST_TOKEN_RETRY_PAUSE_MS;
-                    if (runTimeoutMs - (Date.now() - runStartedAt) < retryPauseMs + firstTokenMs) {
+                    if (clock.remainingMs() < retryPauseMs + firstTokenMs) {
                         if (failure !== undefined)
                             throw failure;
                         break;
@@ -1118,7 +1148,14 @@ export class AgentRunner {
                     }
                     emit("run_completed", final);
                     finish("completed");
-                    return { sessionId, text: lastText, status: "completed", usage: usageTotal, toolCalls };
+                    return {
+                        sessionId,
+                        text: lastText,
+                        status: "completed",
+                        usage: usageTotal,
+                        toolCalls,
+                        activeMs: clock.activeMs(),
+                    };
                 }
                 toolCalls += completion.calls.length;
                 const prepared = completion.calls.map((call) => {
@@ -1209,7 +1246,14 @@ export class AgentRunner {
             // token budget (`maxTokens`) and the timeout; the turn count is a safety rail.
             emit("run_turns_exceeded", { turns: maxTurns, maxTurns });
             finish("turns_exceeded");
-            return { sessionId, text: lastText, status: "turns-exceeded", usage: usageTotal, toolCalls };
+            return {
+                sessionId,
+                text: lastText,
+                status: "turns-exceeded",
+                usage: usageTotal,
+                toolCalls,
+                activeMs: clock.activeMs(),
+            };
         }
         catch (error) {
             const timedOut = silentTimedOut
@@ -1228,7 +1272,11 @@ export class AgentRunner {
                 });
                 emit("run_failed", { error: failure.message, code: "timeout", timeout: failure.info });
                 finish("failed", failure.message);
-                attachRunStats(failure, { usage: { ...usageTotal }, toolCalls });
+                attachRunStats(failure, {
+                    usage: { ...usageTotal },
+                    toolCalls,
+                    activeMs: clock.activeMs(),
+                });
                 throw failure;
             }
             if (error instanceof RunTruncationError) {
@@ -1238,7 +1286,7 @@ export class AgentRunner {
                     truncation: error.info,
                 });
                 finish("failed", error.message);
-                attachRunStats(error, { usage: { ...usageTotal }, toolCalls });
+                attachRunStats(error, { usage: { ...usageTotal }, toolCalls, activeMs: clock.activeMs() });
                 throw error;
             }
             // On cancellation report the abort reason, not the transport's secondary error.
@@ -1246,10 +1294,12 @@ export class AgentRunner {
             const message = cause instanceof Error ? cause.message : String(cause);
             emit(combined.aborted ? "run_cancelled" : "run_failed", { error: message });
             finish(combined.aborted ? "cancelled" : "failed", message);
-            attachRunStats(error, { usage: { ...usageTotal }, toolCalls });
+            attachRunStats(error, { usage: { ...usageTotal }, toolCalls, activeMs: clock.activeMs() });
             throw error;
         }
         finally {
+            unregisterClock();
+            clock.dispose();
             if (acquired)
                 o.store.release(sessionId);
             this.active.delete(sessionId);

package/dist/core/timeout.js

@@ -48,7 +48,7 @@ export function describeTimeout(info) {
         return info.firstRequest
             ? `${who} did not respond within ${limit}: no tokens were received. ` +
                 "Retry, switch to another model, or raise limits.timeoutMs."
-            : `The run reached its ${limit} limit while waiting for ${info.model ? `the model ${info.model}` : "the model"}` +
+            : `The run reached its limit of ${limit} of active time (time spent waiting for you is not counted) while waiting for ${info.model ? `the model ${info.model}` : "the model"}` +
                 `${info.provider ? ` (${info.provider})` : ""}. ` +
                 "Everything produced so far is kept: prompt again to continue, switch model, or raise limits.timeoutMs.";
     const doing = info.stage === "tool" && info.tool
@@ -56,6 +56,6 @@ export function describeTimeout(info) {
         : info.stage === "streaming"
             ? "while the model was answering"
             : "";
-    return (`The run reached its ${limit} limit${doing ? ` ${doing}` : ""}. ` +
+    return (`The run reached its limit of ${limit} of active time (time spent waiting for you is not counted)${doing ? ` ${doing}` : ""}. ` +
         "Everything produced so far is kept: prompt again to continue, or raise limits.timeoutMs.");
 }

package/dist/goal/host.d.ts

@@ -8,6 +8,8 @@ export interface RunSummary {
         output: number;
     };
     toolCalls?: number;
+    /** Active time of the run: waits for a person are not counted. */
+    activeMs?: number;
 }
 /**
  * The outcome of one run. `cancelled` is whether the run's abort signal fired (the user stopped

package/dist/goal/host.js

@@ -30,7 +30,8 @@ export function goalOutcome(input) {
         text: result?.text ?? "",
         toolCalls: result?.toolCalls ?? stats?.toolCalls ?? 0,
         startedAt: input.startedAt,
-        durationMs: Math.max(0, input.endedAt - input.startedAt),
+        // `goal.maxMinutes` counts the time a run was working, never the time it waited for you.
+        durationMs: Math.max(0, Math.min(input.endedAt - input.startedAt, result?.activeMs ?? stats?.activeMs ?? Number.POSITIVE_INFINITY)),
     };
 }
 /**

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /** @alisio/core public API: embed the Alisio agent programmatically. */
 export * from "@alisio/sdk";
-export { type ActiveAgent, AGENT_COMMAND_PREFIX, type AgentPickerItem, activeAgentCatalog, agentCatalogFromState, agentCommandDescriptors, agentCommandName, agentIdFromCommand, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, cycleableAgents, DEFAULT_AGENT_ID, type MainCapableAgentRecord, mainAgentFromRecord, nextAgent, PLAN_AGENT_ID, resolveActiveAgent, } from "./agents/active.ts";
+export { type ActiveAgent, AGENT_COMMAND_PREFIX, type AgentPickerItem, activeAgentCatalog, agentCatalogFromState, agentCommandDescriptors, agentCommandName, agentIdFromCommand, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, cycleableAgents, DEFAULT_AGENT_ID, type MainCapableAgentRecord, mainAgentFromRecord, nextAgent, PLAN_AGENT_ID, type PlanInstructionSettings, planInstructions, resolveActiveAgent, } from "./agents/active.ts";
 export { agentModelCapabilities, agentModelLabels, agentModelOptions, DEFAULT_EFFORT_LEVELS, fitAgentSettings, } from "./agents/capabilities.ts";
 export { AGENT_AUTHORING_SKILL_NAMES, CREATE_AGENT_SKILL, } from "./agents/create-agent-skill.ts";
 export { AGENT_ID_PATTERN, AGENT_LIMITS, AGENT_REASONING_SUMMARIES, AGENT_TEXT_FORMATS, AGENT_VERBOSITIES, type AgentFieldError, AgentNotFoundError, AgentScopeStore, agentIdFromName, agentScopeDir, parseAgentFile, RESERVED_AGENT_IDS, slugify, validateAgentDefinitionInput, } from "./agents/definitions.ts";
@@ -34,15 +34,19 @@ export { BUILTIN_COMMANDS, type BuiltinCommand, CommandCatalog, type CommandExec
 export { type Config, type ConfigLoadResult, type ConfigProvenance, configFile, configHome, configSchema, isSettableSettingKey, type LoadedConfig, loadConfig, loadConfigWithProvenance, type McpServerSource, OCI_IMAGE_PATTERN, overridesSavedProviderProfile, type SettableSettingInfo, type SettableSettingKey, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.ts";
 export { type ContextBudget, checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.ts";
 export type { ApprovalDecision, ApprovalHandler, ApprovalRequest, ArtifactPublisherFactory, BeginRunInput, CapabilityGate, ContextSource, CoreArtifactPublisher, EndRunInput, EventPage, HookFailure, MessagePage, PageOptions, Policy, PublishedArtifactInfo, RunnerExtensions, RunRecord, RunStatus, Session, SessionStore, StoredEvent, TerminalRunStatus, ToolCallMeta, } from "./core/contracts.ts";
+export { HumanWaits } from "./core/human-wait.ts";
 export { EXIT_PLAN_TOOL, GOAL_TOOLS, OPT_IN_TOOLS } from "./core/opt-in.ts";
 export { DEFAULT_MAX_OUTPUT_TOKENS, describeOutputLimitSource, MAX_AUTO_OUTPUT_TOKENS, type OutputLimit, type OutputLimitSource, resolveMaxOutputTokens, } from "./core/output-limit.ts";
 export { ToolRegistry } from "./core/registry.ts";
+export { RunClock } from "./core/run-clock.ts";
 export { AgentRunner, type CompactionResult, defaultTokenBudget, type RunnerOptions, type RunnerSettingsPatch, type RunOptions, } from "./core/runner.ts";
 export { type ExtensionConflict, ExtensionRegistry } from "./extensions/registry.ts";
 export * from "./goal/index.ts";
 export { HerdrBridge } from "./integrations/herdr.ts";
 export { McpConnector, type McpServerInfo, type McpStatus, type McpToolInfo, } from "./mcp/connector.ts";
 export { describePermissionStatus, type EffectState, effectState, FULL_ACCESS_WARNING, type ModeFlags, type ModePolicy, modeFromFlags, modeToPreset, PERMISSION_MODE_TABLE, PERMISSION_MODES, PERMISSION_MODES_LOCKED, PERMISSION_USAGE, type PermissionCommand, type PermissionModeLabel, type PermissionModeSpec, parsePermissionCommand, parsePermissionMode, presetToMode, READ_ONLY_POLICY, } from "./permissions/modes.ts";
+export { DIAGRAM_MAX_BYTES, DIAGRAM_MAX_NODES, DIAGRAM_SYNTAXES, DIAGRAMS_MAX_ALLOWED, mermaidProblem, type PlanDiagram, validateDiagrams, } from "./plan/diagrams.ts";
+export { buildPlanManifest, parsePlanHeadings, slugifyHeading, } from "./plan/manifest.ts";
 export { claimApprovedPlan, currentPlan, discardApprovedPlan, IMPLEMENTATION_AGENT_ID, implementationPrompt, PLAN_CONTEXT_MAX_CHARS, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, type PlanFollowUp, type PlanState, type PlanStatus, planHash, readPlanState, settlePlanRun, withdrawPendingPlan, } from "./plan/state.ts";
 export { discoverPlugins, PluginHost, type PluginHostOptions, pluginPrefix, type ViewInfo, ViewRunError, } from "./plugins/host.ts";
 export { type CliInstallOptions, cliInstall, INSTALL_TIMEOUT_MS, type InstallPluginInput, type InstallPluginResult, type InstallRunner, installedNpmPlugins, installPlugin, npmInstallTarget, type PluginSpec, parsePluginSpec, pluginTrustRemark, printInstallResult, registerPluginInstallTool, sanitizeNpmError, } from "./plugins/install.ts";

package/dist/index.js

@@ -1,6 +1,6 @@
 /** @alisio/core public API: embed the Alisio agent programmatically. */
 export * from "@alisio/sdk";
-export { AGENT_COMMAND_PREFIX, activeAgentCatalog, agentCatalogFromState, agentCommandDescriptors, agentCommandName, agentIdFromCommand, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, cycleableAgents, DEFAULT_AGENT_ID, mainAgentFromRecord, nextAgent, PLAN_AGENT_ID, resolveActiveAgent, } from "./agents/active.js";
+export { AGENT_COMMAND_PREFIX, activeAgentCatalog, agentCatalogFromState, agentCommandDescriptors, agentCommandName, agentIdFromCommand, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, cycleableAgents, DEFAULT_AGENT_ID, mainAgentFromRecord, nextAgent, PLAN_AGENT_ID, planInstructions, resolveActiveAgent, } from "./agents/active.js";
 export { agentModelCapabilities, agentModelLabels, agentModelOptions, DEFAULT_EFFORT_LEVELS, fitAgentSettings, } from "./agents/capabilities.js";
 export { AGENT_AUTHORING_SKILL_NAMES, CREATE_AGENT_SKILL, } from "./agents/create-agent-skill.js";
 export { AGENT_ID_PATTERN, AGENT_LIMITS, AGENT_REASONING_SUMMARIES, AGENT_TEXT_FORMATS, AGENT_VERBOSITIES, AgentNotFoundError, AgentScopeStore, agentIdFromName, agentScopeDir, parseAgentFile, RESERVED_AGENT_IDS, slugify, validateAgentDefinitionInput, } from "./agents/definitions.js";
@@ -33,15 +33,19 @@ export { changelogNews, compareVersions, formatChangelogMarkdown, isVersion, loa
 export { BUILTIN_COMMANDS, CommandCatalog, } from "./commands/catalog.js";
 export { configFile, configHome, configSchema, isSettableSettingKey, loadConfig, loadConfigWithProvenance, OCI_IMAGE_PATTERN, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.js";
 export { checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.js";
+export { HumanWaits } from "./core/human-wait.js";
 export { EXIT_PLAN_TOOL, GOAL_TOOLS, OPT_IN_TOOLS } from "./core/opt-in.js";
 export { DEFAULT_MAX_OUTPUT_TOKENS, describeOutputLimitSource, MAX_AUTO_OUTPUT_TOKENS, resolveMaxOutputTokens, } from "./core/output-limit.js";
 export { ToolRegistry } from "./core/registry.js";
+export { RunClock } from "./core/run-clock.js";
 export { AgentRunner, defaultTokenBudget, } from "./core/runner.js";
 export { ExtensionRegistry } from "./extensions/registry.js";
 export * from "./goal/index.js";
 export { HerdrBridge } from "./integrations/herdr.js";
 export { McpConnector, } from "./mcp/connector.js";
 export { describePermissionStatus, effectState, FULL_ACCESS_WARNING, modeFromFlags, modeToPreset, PERMISSION_MODE_TABLE, PERMISSION_MODES, PERMISSION_MODES_LOCKED, PERMISSION_USAGE, parsePermissionCommand, parsePermissionMode, presetToMode, READ_ONLY_POLICY, } from "./permissions/modes.js";
+export { DIAGRAM_MAX_BYTES, DIAGRAM_MAX_NODES, DIAGRAM_SYNTAXES, DIAGRAMS_MAX_ALLOWED, mermaidProblem, validateDiagrams, } from "./plan/diagrams.js";
+export { buildPlanManifest, parsePlanHeadings, slugifyHeading, } from "./plan/manifest.js";
 export { claimApprovedPlan, currentPlan, discardApprovedPlan, IMPLEMENTATION_AGENT_ID, implementationPrompt, PLAN_CONTEXT_MAX_CHARS, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, planHash, readPlanState, settlePlanRun, withdrawPendingPlan, } from "./plan/state.js";
 export { discoverPlugins, PluginHost, pluginPrefix, ViewRunError, } from "./plugins/host.js";
 export { cliInstall, INSTALL_TIMEOUT_MS, installedNpmPlugins, installPlugin, npmInstallTarget, parsePluginSpec, pluginTrustRemark, printInstallResult, registerPluginInstallTool, sanitizeNpmError, } from "./plugins/install.js";

package/dist/plan/diagrams.d.ts

@@ -0,0 +1,76 @@
+import type { PlanDiagramType } from "@alisio/sdk";
+/** Largest Mermaid source of one diagram (UTF-8 bytes). */
+export declare const DIAGRAM_MAX_BYTES: number;
+/** Most nodes (participants, entities, states, tasks...) of one diagram, estimated from the text. */
+export declare const DIAGRAM_MAX_NODES = 40;
+/** Hard ceiling of `plan.maxDiagrams`. */
+export declare const DIAGRAMS_MAX_ALLOWED = 8;
+export declare const DIAGRAM_ID_MAX = 40;
+export declare const DIAGRAM_TITLE_MAX = 80;
+export declare const DIAGRAM_EXPLANATION_MAX = 400;
+export declare const DIAGRAM_SECTION_MAX = 120;
+/** Mermaid diagram keywords a plan may use (the first statement of the source). */
+export declare const DIAGRAM_SYNTAXES: readonly string[];
+export declare const DIAGRAM_TYPES: readonly PlanDiagramType[];
+/**
+ * The semantic classes of the style guide. The web applies the same names as a `classDef` block
+ * at render time when a diagram uses a class without defining it (colors live in the web).
+ */
+export declare const DIAGRAM_CLASSES: readonly string[];
+export interface PlanDiagram {
+    id: string;
+    title: string;
+    explanation: string;
+    /** As the model wrote it; the manifest resolves it against the plan headings. */
+    section?: string;
+    type: PlanDiagramType;
+    syntax: string;
+    mermaid: string;
+    nodes: number;
+}
+export interface DroppedDiagram {
+    /** The id as given (or `#<position>` when it has none). */
+    id: string;
+    reason: string;
+}
+export interface DiagramValidation {
+    accepted: PlanDiagram[];
+    dropped: DroppedDiagram[];
+}
+export interface DiagramLimits {
+    /** Most diagrams of one plan (0 accepts none). */
+    max: number;
+    maxBytes?: number;
+    maxNodes?: number;
+}
+/** Normalizes line endings and trims: what is stored and hashed. */
+export declare const normalizeMermaid: (source: string) => string;
+/** The diagram keyword of a source (its first statement), or undefined when it has none. */
+export declare function diagramSyntax(source: string): string | undefined;
+/** The purpose a syntax implies when the model gave none. */
+export declare function defaultDiagramType(syntax: string): PlanDiagramType;
+/**
+ * An estimate of the diagram's nodes from its text (participants, entities, states, tasks, topics
+ * or flowchart node ids). It errs on the high side: it is a guard against walls of boxes, not a
+ * parser.
+ */
+export declare function estimateNodes(source: string, syntax: string): number;
+/** The first problem that makes a Mermaid source unsafe or unsupported, or undefined when fine. */
+export declare function mermaidProblem(source: string, limits?: {
+    maxBytes?: number;
+    maxNodes?: number;
+}): string | undefined;
+/** SHA-256 of what makes a diagram "the same" across revisions. */
+export declare function diagramHash(diagram: {
+    title: string;
+    explanation: string;
+    section?: string;
+    type: string;
+    mermaid: string;
+}): string;
+/**
+ * Validates the `diagrams` argument of `exit_plan`. Never throws: every problem becomes a dropped
+ * diagram with the reason the model needs to fix it. Order is kept; the first diagram with an id
+ * wins; only `limits.max` are accepted.
+ */
+export declare function validateDiagrams(input: unknown, limits: DiagramLimits): DiagramValidation;