@alisio/core 0.1.0-alpha.9 → 0.1.1

package/dist/core/timeout.d.ts

@@ -0,0 +1,15 @@
+import type { RunTimeoutInfo } from "@alisio/sdk";
+/** A run stopped by a time limit; the message says which limit, which model and what to do. */
+export declare class RunTimeoutError extends Error {
+    readonly info: RunTimeoutInfo;
+    constructor(info: RunTimeoutInfo);
+}
+/** `AbortSignal.timeout` aborts with a `TimeoutError`; an explicit `abort()` does not. */
+export declare function isTimeoutReason(reason: unknown): boolean;
+/**
+ * A short, human label for a provider id: the host of an OpenAI-compatible endpoint
+ * (`openai-compatible:chat:https://api.example.com/v1` → `api.example.com`), else the id itself.
+ */
+export declare function providerLabel(id: string | undefined): string | undefined;
+/** Plain-text message of a timeout (TUI, headless, logs, the `runs.error` column). English only. */
+export declare function describeTimeout(info: RunTimeoutInfo): string;

package/dist/core/timeout.js

@@ -0,0 +1,61 @@
+/** A run stopped by a time limit; the message says which limit, which model and what to do. */
+export class RunTimeoutError extends Error {
+    info;
+    constructor(info) {
+        super(describeTimeout(info));
+        this.name = "RunTimeoutError";
+        this.info = info;
+    }
+}
+/** `AbortSignal.timeout` aborts with a `TimeoutError`; an explicit `abort()` does not. */
+export function isTimeoutReason(reason) {
+    return (typeof reason === "object" &&
+        reason !== null &&
+        reason.name === "TimeoutError");
+}
+/**
+ * A short, human label for a provider id: the host of an OpenAI-compatible endpoint
+ * (`openai-compatible:chat:https://api.example.com/v1` → `api.example.com`), else the id itself.
+ */
+export function providerLabel(id) {
+    if (!id)
+        return undefined;
+    const url = /(https?:\/\/[^\s]+)/.exec(id)?.[1];
+    if (url)
+        try {
+            return new URL(url).host;
+        }
+        catch {
+            /* fall through to the raw id */
+        }
+    return id;
+}
+const seconds = (ms) => Math.round(ms / 1000);
+/** Plain-text message of a timeout (TUI, headless, logs, the `runs.error` column). English only. */
+export function describeTimeout(info) {
+    const who = info.model
+        ? `The model ${info.model}${info.provider ? ` (${info.provider})` : ""}`
+        : "The model";
+    const limit = `${seconds(info.ms)} s`;
+    if (info.kind === "first_token" && info.attempts && info.attempts > 1)
+        return (`${who} did not respond after ${info.attempts} attempts of ${limit} each: no tokens were received, so the run was stopped. ` +
+            "Retry, switch to another model, or raise or disable limits.firstTokenTimeoutMs (0 disables it); " +
+            "limits.firstTokenRetries sets how many times a silent request is sent again.");
+    if (info.kind === "first_token")
+        return (`${who} sent nothing within ${limit} of the request, so the run was stopped. ` +
+            "Retry, switch to another model, or raise or disable limits.firstTokenTimeoutMs (0 disables it).");
+    if (info.stage === "waiting_model")
+        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"}` +
+                `${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
+        ? `while running ${info.tool}`
+        : info.stage === "streaming"
+            ? "while the model was answering"
+            : "";
+    return (`The run reached its ${limit} limit${doing ? ` ${doing}` : ""}. ` +
+        "Everything produced so far is kept: prompt again to continue, or raise limits.timeoutMs.");
+}

package/dist/core/truncation.d.ts

@@ -0,0 +1,30 @@
+import { type RunTruncationInfo, type ToolCall } from "@alisio/sdk";
+/**
+ * Recovery from a model response that the output-token limit (`limits.maxOutputTokens`) cut
+ * off before it was usable. Provider-agnostic: the runner decides from the completed message
+ * (`truncated: true`) or from the typed `OutputTruncatedError` signal, never from SDK types.
+ */
+/** The run failed because every response was cut off; carries the numbers for the UIs. */
+export declare class RunTruncationError extends Error {
+    readonly code = "output_truncated";
+    readonly info: RunTruncationInfo;
+    constructor(info: RunTruncationInfo);
+}
+/** Plain-text failure message (TUI, headless, logs). English only; the web localizes it. */
+export declare function describeTruncation(info: RunTruncationInfo): string;
+/** Whether a provider failure means "the response was cut off by the output-token limit". */
+export declare function isOutputTruncationError(error: unknown): boolean;
+/**
+ * Whether a tool call of a truncated response cannot be trusted: missing id or name, or
+ * arguments that are not a complete JSON object. Empty arguments only count as incomplete for
+ * the LAST call (the one being streamed when the limit hit); an earlier call with no arguments
+ * is how a provider reports a call without parameters.
+ */
+export declare function incompleteCalls(calls: ToolCall[]): boolean;
+/** What the model is told on the request that follows a truncated response. */
+export declare const TRUNCATION_NOTICE: string;
+/**
+ * One step below `current` among the model's supported levels, or `undefined` when that cannot
+ * be decided cleanly (unknown level names, no current level, or already the lowest).
+ */
+export declare function lowerEffort(current: string | undefined, supported: readonly string[] | undefined): string | undefined;

package/dist/core/truncation.js

@@ -0,0 +1,83 @@
+import { OUTPUT_TRUNCATED_CODE } from "@alisio/sdk";
+import { describeOutputLimitSource } from "./output-limit.js";
+/**
+ * Recovery from a model response that the output-token limit (`limits.maxOutputTokens`) cut
+ * off before it was usable. Provider-agnostic: the runner decides from the completed message
+ * (`truncated: true`) or from the typed `OutputTruncatedError` signal, never from SDK types.
+ */
+/** The run failed because every response was cut off; carries the numbers for the UIs. */
+export class RunTruncationError extends Error {
+    code = OUTPUT_TRUNCATED_CODE;
+    info;
+    constructor(info) {
+        super(describeTruncation(info));
+        this.name = "RunTruncationError";
+        this.info = info;
+    }
+}
+/** Plain-text failure message (TUI, headless, logs). English only; the web localizes it. */
+export function describeTruncation(info) {
+    const who = info.model ? `The model ${info.model}` : "The model";
+    const times = info.attempts === 1 ? "once" : `${info.attempts} times`;
+    return (`${who} was cut off ${times} by the output-token limit (${info.maxOutputTokens} tokens, ${describeOutputLimitSource(info.source)}) ` +
+        "before it produced a usable response, so the run was stopped. " +
+        "Raise limits.maxOutputTokens (/settings or the config file), lower the reasoning effort (/effort), " +
+        "or ask for the result in smaller parts.");
+}
+/**
+ * COMPATIBILITY: provider plugins published before the typed signal (for example
+ * `@alisio/plugin-deepseek` 0.1.1) throw a plain `Error` with this text when a response is cut
+ * off before any visible text. It is the only place the text is matched; new providers should
+ * yield `completed` with `truncated: true` or throw `OutputTruncatedError` from `@alisio/sdk`.
+ */
+const LEGACY_TRUNCATION_TEXT = "cut off by max output tokens before any usable content";
+/** Whether a provider failure means "the response was cut off by the output-token limit". */
+export function isOutputTruncationError(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const { code, message } = error;
+    return (code === OUTPUT_TRUNCATED_CODE ||
+        (typeof message === "string" && message.includes(LEGACY_TRUNCATION_TEXT)));
+}
+/**
+ * Whether a tool call of a truncated response cannot be trusted: missing id or name, or
+ * arguments that are not a complete JSON object. Empty arguments only count as incomplete for
+ * the LAST call (the one being streamed when the limit hit); an earlier call with no arguments
+ * is how a provider reports a call without parameters.
+ */
+export function incompleteCalls(calls) {
+    return calls.some((call, index) => {
+        if (!call.id || !call.name)
+            return true;
+        const raw = call.arguments.trim();
+        if (!raw)
+            return index === calls.length - 1;
+        try {
+            const parsed = JSON.parse(raw);
+            return typeof parsed !== "object" || parsed === null || Array.isArray(parsed);
+        }
+        catch {
+            return true;
+        }
+    });
+}
+/** What the model is told on the request that follows a truncated response. */
+export const TRUNCATION_NOTICE = "Your previous reply was cut off by the output-token limit, so it was discarded. " +
+    "Do not repeat what you already produced. Work in smaller steps: write long files in several parts " +
+    "(for example save the script or data to files in several tool calls, or build the dashboard with " +
+    "the compact alisio_runtime.html and svg helpers), keep your reasoning short, and continue from where you stopped.";
+const EFFORT_RANK = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+/**
+ * One step below `current` among the model's supported levels, or `undefined` when that cannot
+ * be decided cleanly (unknown level names, no current level, or already the lowest).
+ */
+export function lowerEffort(current, supported) {
+    if (!current || !supported?.length)
+        return undefined;
+    const rank = (level) => EFFORT_RANK.indexOf(level);
+    if (rank(current) < 0 || supported.some((level) => rank(level) < 0))
+        return undefined;
+    const lower = [...supported].filter((level) => rank(level) < rank(current));
+    lower.sort((a, b) => rank(b) - rank(a));
+    return lower[0];
+}

package/dist/goal/blockers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The ONE ordered list of reasons a goal does not continue right now. Hosts (TUI, server) build
+ * a `GoalHostState` from what they can see and call `goalBlocker`; nothing else decides. A
+ * blocker is a WAIT, not a state change: the goal stays `active` and continues when the cause is
+ * gone (the host re-checks on the events that clear it).
+ *
+ * The order matters (the first match wins, and it is what the UI shows):
+ *  1. not active          - nothing to continue (paused, blocked, budget_limited, complete, none)
+ *  2. disabled            - `goal.enabled` is false
+ *  3. busy                - a run of the session is in flight, or a continuation is already claimed
+ *  4. queued_input        - the user has input queued: the user always goes first
+ *  5. approval            - a permission request is waiting for the user
+ *  6. question            - a question (or a plan review) is waiting for the user
+ *  7. plan_mode           - the active agent is the plan agent
+ *  8. background_tasks    - background tasks of the session are still running
+ */
+import type { GoalStatus, GoalWaiting } from "@alisio/sdk";
+export interface GoalHostState {
+    /** The goal's status, or undefined when the session has none. */
+    status: GoalStatus | undefined;
+    enabled: boolean;
+    /** A run is executing (or queued) for the session, or another process holds the session. */
+    running: boolean;
+    /** A continuation was claimed and its run has not settled yet. */
+    inflight: boolean;
+    /** The user has typed or queued something that has not been sent yet. */
+    queuedInput: boolean;
+    /** What is waiting for the user, if anything. */
+    awaiting?: "approval" | "question";
+    /** The agent that would run is the plan agent. */
+    planMode: boolean;
+    /** Live background tasks of the session. */
+    liveTasks: number;
+}
+export type GoalBlocker = "not_active" | "disabled" | "busy" | "queued_input" | "approval" | "question" | "plan_mode" | "background_tasks";
+/** The first reason the goal must not continue now, or undefined when it may. */
+export declare function goalBlocker(state: GoalHostState): GoalBlocker | undefined;
+/** What the UI shows as "waiting for…" (a busy session is working, not waiting). */
+export declare function waitingOf(blocker: GoalBlocker | undefined): GoalWaiting | undefined;
+/**
+ * The label a UI shows for an active goal. A question or approval is shown even while the run
+ * that asked it is still going (the run is what waits); the other waits only count once the
+ * session is idle (a task running while the agent works is not "waiting").
+ */
+export declare function goalWaiting(state: GoalHostState): GoalWaiting | undefined;

package/dist/goal/blockers.js

@@ -0,0 +1,51 @@
+/** The first reason the goal must not continue now, or undefined when it may. */
+export function goalBlocker(state) {
+    if (state.status !== "active")
+        return "not_active";
+    if (!state.enabled)
+        return "disabled";
+    if (state.running || state.inflight)
+        return "busy";
+    if (state.queuedInput)
+        return "queued_input";
+    if (state.awaiting === "approval")
+        return "approval";
+    if (state.awaiting === "question")
+        return "question";
+    if (state.planMode)
+        return "plan_mode";
+    if (state.liveTasks > 0)
+        return "background_tasks";
+    return undefined;
+}
+/** What the UI shows as "waiting for…" (a busy session is working, not waiting). */
+export function waitingOf(blocker) {
+    switch (blocker) {
+        case "approval":
+            return "approval";
+        case "question":
+            return "question";
+        case "queued_input":
+            return "user_input";
+        case "plan_mode":
+            return "plan_mode";
+        case "background_tasks":
+            return "background_tasks";
+        default:
+            return undefined;
+    }
+}
+/**
+ * The label a UI shows for an active goal. A question or approval is shown even while the run
+ * that asked it is still going (the run is what waits); the other waits only count once the
+ * session is idle (a task running while the agent works is not "waiting").
+ */
+export function goalWaiting(state) {
+    if (state.status !== "active" || !state.enabled)
+        return undefined;
+    if (state.awaiting)
+        return state.awaiting;
+    if (state.running || state.inflight)
+        return undefined;
+    return waitingOf(goalBlocker(state));
+}

package/dist/goal/budget.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Token budget syntax of `/goal` (`budget=50k`, `budget=1.5M`, `budget=clear`). Pure.
+ *
+ * A budget is a number of tokens as the runner counts them: the input AND output tokens of every
+ * request of every run of the goal (so a long context is paid again on each turn).
+ */
+/** The values that remove the budget. */
+export declare const BUDGET_CLEAR_WORDS: ReadonlySet<string>;
+/** The largest budget accepted (a typo guard: one billion tokens). */
+export declare const MAX_TOKEN_BUDGET = 1000000000;
+export type BudgetParse = {
+    ok: true;
+    tokens: number | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * `50k`, `1.5M`, `2m`, `50000` or a clear word. `tokens: null` clears the budget. Decimals are
+ * allowed with a suffix only (`1.5M`); the result is a positive integer.
+ */
+export declare function parseTokenBudget(raw: string): BudgetParse;
+/** `1.5M`, `50k`, `812` (the inverse of the parser, for UIs). */
+export declare function formatTokenCount(tokens: number): string;

package/dist/goal/budget.js

@@ -0,0 +1,53 @@
+/**
+ * Token budget syntax of `/goal` (`budget=50k`, `budget=1.5M`, `budget=clear`). Pure.
+ *
+ * A budget is a number of tokens as the runner counts them: the input AND output tokens of every
+ * request of every run of the goal (so a long context is paid again on each turn).
+ */
+/** The values that remove the budget. */
+export const BUDGET_CLEAR_WORDS = new Set(["clear", "none", "off", "0"]);
+/** The largest budget accepted (a typo guard: one billion tokens). */
+export const MAX_TOKEN_BUDGET = 1_000_000_000;
+const SUFFIX = { k: 1_000, m: 1_000_000, b: 1_000_000_000 };
+/**
+ * `50k`, `1.5M`, `2m`, `50000` or a clear word. `tokens: null` clears the budget. Decimals are
+ * allowed with a suffix only (`1.5M`); the result is a positive integer.
+ */
+export function parseTokenBudget(raw) {
+    const text = raw.trim().toLowerCase().replace(/_/g, "");
+    if (!text)
+        return { ok: false, error: "A budget is empty: use e.g. budget=50k or budget=clear." };
+    if (BUDGET_CLEAR_WORDS.has(text))
+        return { ok: true, tokens: null };
+    const match = /^(\d+(?:\.\d+)?)([kmb])?$/.exec(text);
+    if (!match)
+        return { ok: false, error: `"${raw}" is not a token budget: use e.g. 50k, 1.5M or clear.` };
+    const [, digits = "", suffix] = match;
+    if (!suffix && digits.includes("."))
+        return {
+            ok: false,
+            error: `"${raw}" is not a token budget: decimals need a K or M suffix (1.5M).`,
+        };
+    const tokens = Math.round(Number(digits) * (suffix ? (SUFFIX[suffix] ?? 1) : 1));
+    if (!Number.isFinite(tokens) || tokens < 1)
+        return {
+            ok: false,
+            error: `"${raw}" is not a token budget: it must be at least 1 token (or clear).`,
+        };
+    if (tokens > MAX_TOKEN_BUDGET)
+        return { ok: false, error: `"${raw}" is above the maximum budget of 1B tokens.` };
+    return { ok: true, tokens };
+}
+/** `1.5M`, `50k`, `812` (the inverse of the parser, for UIs). */
+export function formatTokenCount(tokens) {
+    if (!Number.isFinite(tokens) || tokens < 0)
+        return "0";
+    if (tokens < 1_000)
+        return String(Math.round(tokens));
+    const trim = (value) => value.replace(/\.0$/, "");
+    if (tokens < 1_000_000) {
+        const k = tokens / 1_000;
+        return `${k < 100 ? trim(k.toFixed(1)) : Math.round(k)}k`;
+    }
+    return `${trim((tokens / 1_000_000).toFixed(1))}M`;
+}

package/dist/goal/command.d.ts

@@ -0,0 +1,36 @@
+/** The longest objective accepted, in characters (it is sent to the model on the kickoff). */
+export declare const GOAL_OBJECTIVE_MAX = 4000;
+export declare const GOAL_SUBCOMMANDS: readonly ["pause", "resume", "edit", "clear", "help"];
+export type GoalCommand = {
+    type: "show";
+} | {
+    type: "help";
+} | {
+    type: "pause";
+} | {
+    type: "resume";
+} | {
+    type: "clear";
+}
+/** `objective` is absent when the UI should ask for the new text. */
+ | {
+    type: "edit";
+    objective?: string;
+} | {
+    type: "budget";
+    tokens: number | null;
+} | {
+    type: "create";
+    objective: string;
+    tokenBudget?: number;
+} | {
+    type: "error";
+    message: string;
+};
+export declare const GOAL_USAGE = "Usage: /goal [<objective> [budget=50k]] | pause | resume | edit [<objective>] | clear | budget=<n|clear> | help";
+/** Markdown help shown by `/goal help` (identical on every surface). */
+export declare const GOAL_HELP: string;
+/** Words of `args` split on whitespace, keeping the original spacing of the objective. */
+export declare function parseGoalCommand(args: string): GoalCommand;
+/** Why an objective is not acceptable (the same rule for the command and the API), if so. */
+export declare function objectiveError(objective: string): string | undefined;

package/dist/goal/command.js

@@ -0,0 +1,98 @@
+/**
+ * The `/goal` command line, parsed once for every surface (TUI, web, API). Pure.
+ *
+ *   /goal                         show the current goal
+ *   /goal <objective> [budget=N]  create (or replace) the goal and start working on it
+ *   /goal pause | resume | clear | help
+ *   /goal edit [<objective>]      change the objective of the current goal
+ *   /goal budget=50k              set the token budget of the current goal (budget=clear removes it)
+ */
+import { parseTokenBudget } from "./budget.js";
+/** The longest objective accepted, in characters (it is sent to the model on the kickoff). */
+export const GOAL_OBJECTIVE_MAX = 4000;
+export const GOAL_SUBCOMMANDS = ["pause", "resume", "edit", "clear", "help"];
+const BUDGET_WORD = /^budget=(.*)$/i;
+export const GOAL_USAGE = "Usage: /goal [<objective> [budget=50k]] | pause | resume | edit [<objective>] | clear | budget=<n|clear> | help";
+/** Markdown help shown by `/goal help` (identical on every surface). */
+export const GOAL_HELP = [
+    "**/goal** keeps the agent working on one objective until it is done, blocked, paused or out of budget.",
+    "",
+    "- `/goal` shows the current goal.",
+    "- `/goal <objective>` starts a goal (one per session; an existing goal is replaced after you confirm).",
+    "- `/goal <objective> budget=50k` also sets a token budget (`50k`, `1.5M`, `250000`).",
+    "- `/goal pause` stops the automatic continuation; `/goal resume` continues a paused or blocked goal.",
+    "- `/goal edit <objective>` changes the objective; `/goal clear` removes the goal.",
+    "- `/goal budget=50k` sets the token budget; `/goal budget=clear` (also `none`, `off`, `0`) removes it.",
+    "",
+    `The objective can be up to ${GOAL_OBJECTIVE_MAX} characters. Only you pause, resume, edit or clear a goal or change its budget; the agent marks it complete or blocked, with evidence.`,
+    "The goal never widens permissions: approvals work as in a normal turn, and it never runs in plan mode.",
+    "A goal without a token budget is limited only by its turn and time caps (`goal.maxTurns`, `goal.maxMinutes`).",
+].join("\n");
+/** Words of `args` split on whitespace, keeping the original spacing of the objective. */
+export function parseGoalCommand(args) {
+    const text = args.trim();
+    if (!text)
+        return { type: "show" };
+    const words = text.split(/\s+/);
+    // `budget=` words (anywhere) are options, never part of the objective.
+    const budgets = words.filter((word) => BUDGET_WORD.test(word));
+    if (budgets.length > 1)
+        return { type: "error", message: "Give only one budget=: it appears more than once." };
+    let tokens;
+    if (budgets[0]) {
+        const parsed = parseTokenBudget(BUDGET_WORD.exec(budgets[0])?.[1] ?? "");
+        if (!parsed.ok)
+            return { type: "error", message: parsed.error };
+        tokens = parsed.tokens;
+    }
+    const rest = words.filter((word) => !BUDGET_WORD.test(word));
+    const first = rest[0]?.toLowerCase();
+    const subcommand = GOAL_SUBCOMMANDS.find((name) => name === first);
+    if (!rest.length)
+        return { type: "budget", tokens: tokens ?? null };
+    if (subcommand) {
+        if (tokens !== undefined)
+            return {
+                type: "error",
+                message: `budget= goes with a new objective or alone (/goal budget=50k), not with /goal ${subcommand}.`,
+            };
+        if (subcommand === "edit") {
+            const objective = text.slice(text.search(/\s/) + 1).trim();
+            if (rest.length === 1)
+                return { type: "edit" };
+            return validateObjective(objective, (value) => ({ type: "edit", objective: value }));
+        }
+        if (rest.length > 1)
+            return {
+                type: "error",
+                message: `/goal ${subcommand} takes no arguments. To start a goal whose objective begins with "${subcommand}", reword it.`,
+            };
+        return { type: subcommand };
+    }
+    // The objective keeps the user's own spacing and line breaks; only the budget word is removed.
+    const objective = text
+        .split(/(\s+)/)
+        .filter((part) => !BUDGET_WORD.test(part))
+        .join("")
+        .trim();
+    return validateObjective(objective, (value) => ({
+        type: "create",
+        objective: value,
+        ...(typeof tokens === "number" ? { tokenBudget: tokens } : {}),
+    }));
+}
+function validateObjective(objective, build) {
+    const error = objectiveError(objective);
+    return error ? { type: "error", message: error } : build(objective.trim());
+}
+/** Why an objective is not acceptable (the same rule for the command and the API), if so. */
+export function objectiveError(objective) {
+    const value = objective.trim();
+    if (!value)
+        return "The goal objective is empty.";
+    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value))
+        return "The goal objective contains control characters.";
+    if (value.length > GOAL_OBJECTIVE_MAX)
+        return `The goal objective is too long (${value.length} characters; the limit is ${GOAL_OBJECTIVE_MAX}).`;
+    return undefined;
+}

package/dist/goal/format.d.ts

@@ -0,0 +1,19 @@
+/**
+ * English wording of goal states, reasons and waits, shared by the TUI and the text output of
+ * the API commands. The web UI has its own EN/ES dictionaries for the same codes. Pure.
+ */
+import type { GoalAction, GoalInfo, GoalStatus, GoalWaiting } from "@alisio/sdk";
+export declare const GOAL_STATUS_LABEL: Record<GoalStatus, string>;
+export declare const GOAL_WAITING_LABEL: Record<GoalWaiting, string>;
+/** Why the goal is in its state, as one short sentence (empty when there is nothing to say). */
+export declare function goalReasonText(goal: Pick<GoalInfo, "reason" | "detail">): string;
+/** `45s`, `4m 12s`, `1h 05m`. */
+export declare function formatGoalElapsed(ms: number): string;
+/** `12.3k / 50k tokens` or `12.3k tokens (no budget)`. */
+export declare function goalTokensText(goal: Pick<GoalInfo, "tokensUsed" | "tokenBudget">): string;
+/** The action hints of a state, e.g. `/goal pause · /goal edit · /goal clear`. */
+export declare function goalActionHints(actions: readonly GoalAction[], budget?: boolean): string;
+/** `Active · 12.3k / 50k tokens · turn 3/50 · 4m 12s`. */
+export declare function goalSummaryLine(goal: GoalInfo): string;
+/** The status as Markdown (API commands and `/goal` with no arguments). */
+export declare function formatGoalStatus(goal: GoalInfo): string;

package/dist/goal/format.js

@@ -0,0 +1,102 @@
+import { formatTokenCount } from "./budget.js";
+export const GOAL_STATUS_LABEL = {
+    active: "Active",
+    paused: "Paused",
+    blocked: "Blocked",
+    budget_limited: "Budget reached",
+    complete: "Complete",
+};
+export const GOAL_WAITING_LABEL = {
+    approval: "Waiting for permission",
+    question: "Waiting for your answer",
+    user_input: "Waiting for you to send or clear what you typed",
+    plan_mode: "Waiting: plan mode is on (switch to the build agent)",
+    background_tasks: "Waiting for background tasks",
+};
+const REASON_TEXT = {
+    created: "Started",
+    resumed: "Resumed",
+    edited: "Objective edited",
+    user_paused: "Paused by you",
+    user_interrupt: "You interrupted the turn",
+    model_complete: "The agent reports the goal complete",
+    model_blocked: "The agent reports it cannot continue",
+    policy_denied: "A permission was denied",
+    run_error: "A turn failed",
+    token_budget: "The token budget was reached",
+    max_turns: "The turn limit was reached",
+    max_wall: "The time limit was reached",
+    no_progress: "No progress",
+    restart: "Alisio restarted while the goal was running",
+};
+const DETAIL_TEXT = {
+    repeated_reply: "the same reply repeated",
+    no_tool_turns: "several turns without tool calls",
+};
+/** Why the goal is in its state, as one short sentence (empty when there is nothing to say). */
+export function goalReasonText(goal) {
+    if (!goal.reason)
+        return "";
+    const base = REASON_TEXT[goal.reason];
+    if (!goal.detail)
+        return base;
+    return `${base}: ${DETAIL_TEXT[goal.detail] ?? goal.detail}`;
+}
+/** `45s`, `4m 12s`, `1h 05m`. */
+export function formatGoalElapsed(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    if (total < 60)
+        return `${total}s`;
+    const minutes = Math.floor(total / 60);
+    if (minutes < 60)
+        return `${minutes}m ${String(total % 60).padStart(2, "0")}s`;
+    return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`;
+}
+/** `12.3k / 50k tokens` or `12.3k tokens (no budget)`. */
+export function goalTokensText(goal) {
+    return goal.tokenBudget !== undefined
+        ? `${formatTokenCount(goal.tokensUsed)} / ${formatTokenCount(goal.tokenBudget)} tokens`
+        : `${formatTokenCount(goal.tokensUsed)} tokens (no budget)`;
+}
+const ACTION_HINT = {
+    pause: "/goal pause",
+    resume: "/goal resume",
+    edit: "/goal edit",
+    clear: "/goal clear",
+    budget: "/goal budget=<n>",
+};
+/** The action hints of a state, e.g. `/goal pause · /goal edit · /goal clear`. */
+export function goalActionHints(actions, budget = false) {
+    return actions
+        .filter((action) => budget || action !== "budget")
+        .map((action) => ACTION_HINT[action])
+        .join(" · ");
+}
+/** `Active · 12.3k / 50k tokens · turn 3/50 · 4m 12s`. */
+export function goalSummaryLine(goal) {
+    return [
+        GOAL_STATUS_LABEL[goal.status],
+        goalTokensText(goal),
+        `turn ${goal.turnsUsed}/${goal.maxTurns}`,
+        formatGoalElapsed(goal.activeMs),
+    ].join(" · ");
+}
+/** The status as Markdown (API commands and `/goal` with no arguments). */
+export function formatGoalStatus(goal) {
+    const lines = [
+        `**Goal** · ${goalSummaryLine(goal)}`,
+        "",
+        `> ${goal.objective.replace(/\n/g, "\n> ")}`,
+    ];
+    const why = goal.waiting ? GOAL_WAITING_LABEL[goal.waiting] : goalReasonText(goal);
+    if (why && !(goal.status === "active" && !goal.waiting))
+        lines.push("", why);
+    if (goal.summary)
+        lines.push("", `Agent's report: ${goal.summary}`);
+    if (goal.evidence?.length)
+        lines.push("", ...goal.evidence.map((item) => `- ${item.kind}: ${item.detail}`));
+    const hints = goalActionHints(goal.actions, true);
+    if (hints)
+        lines.push("", hints);
+    return lines.join("\n");
+}

package/dist/goal/host.d.ts

@@ -0,0 +1,29 @@
+import type { GoalRecord, GoalRunOutcome } from "./machine.ts";
+/** What `runner.run` resolves with (the parts the goal needs). */
+export interface RunSummary {
+    text: string;
+    status: string;
+    usage: {
+        input: number;
+        output: number;
+    };
+    toolCalls?: number;
+}
+/**
+ * The outcome of one run. `cancelled` is whether the run's abort signal fired (the user stopped
+ * it, or the host is shutting down); a failed run carries its error; a provider timeout is flagged
+ * so the goal does not block on something the runner already retried.
+ */
+export declare function goalOutcome(input: {
+    runId: string;
+    startedAt: number;
+    endedAt: number;
+    cancelled: boolean;
+    result?: RunSummary;
+    error?: unknown;
+}): GoalRunOutcome;
+/**
+ * The opt-in tools a run of this session gets: the goal tools while the goal is `active` and the
+ * agent is not the plan agent (a plan run never works on a goal).
+ */
+export declare function goalOptInTools(goal: GoalRecord | undefined, planMode: boolean): string[];