@getfamiliar/shared 0.1.2

package/build/index.d.ts

@@ -0,0 +1,37 @@
+export type { AgentRunCallType, AgentRunPatch, AgentRunRow, AgentRunState, NewAgentRun, } from "./AgentRun.js";
+export { AgentRunBus, type AgentRunUnsubscribe } from "./AgentRunBus.js";
+export { buildCalendarEventId, type CalendarApi, type CalendarAttachmentMeta, type CalendarAttendee, type CalendarChangePayload, type CalendarEventRow, type CalendarEventType, type CalendarImportance, type CalendarProvider, type CalendarResponseStatus, type CalendarRow, type CalendarSensitivity, type CalendarShowAs, type CalendarType, type CreateEventInput, type FindEventsQuery, type NewCalendarEvent, parseCalendarEventId, type UpdateEventInput, type UpsertCalendarInput, } from "./Calendar.js";
+export type { ChatFilter, ChatMessage, ChatRole, NewChatMessage } from "./ChatMessage.js";
+export { type ChatHandler, ChatMessageBus, type ChatUnsubscribe } from "./ChatMessageBus.js";
+export type { ConfigService } from "./Config.js";
+export type { ContainerToolInfo } from "./ContainerTool.js";
+export { type ParsedCron, parseCron } from "./CronExpression.js";
+export type { EventFile, EventFilter, EventPatch, EventRow, EventState, NewEvent, } from "./Event.js";
+export { EVENT_PRIORITY } from "./Event.js";
+export { DuplicateIdempotencyKeyError, EventBus } from "./EventBus.js";
+export { estimateTokens } from "./estimateTokens.js";
+export { HandlerCatalog, type HandlerPath } from "./HandlerCatalog.js";
+export type { InferenceEventRow, InferenceOutcome, NewInferenceEvent, } from "./InferenceEvent.js";
+export { InferenceEventBus } from "./InferenceEventBus.js";
+export { type CreateLoggerOptions, createLogger, jsonStdoutStream, type Logger, type LogLevel, type LogStream, prettyStdoutStream, } from "./logging/Logger.js";
+export { buildMailId, type ForwardInput, type MailAddress, type MailApi, type MailAttachment, type MailAttachmentMeta, type MailFolder, type MailProvider, type MailSearchHit, type MailSearchQuery, type NewMailInput, parseMailId, type ReplyInput, } from "./Mail.js";
+export { MAIL_STYLE_TEMPLATE_DEFAULTS, type MailStyleTemplate, mailStyleTemplatePath, signatureToPlainText, } from "./MailStyleTemplate.js";
+export { type ModelMetaData, ModelNotSupported, type ModelProviderDescriptor, } from "./ModelMetaData.js";
+export { renderMarkdownToHtml } from "./markdownHtml.js";
+export { renderMarkdown } from "./markdownTerminal.js";
+export { matchesAnyGlob, matchesGlob } from "./PathGlob.js";
+export type { AnyCommandDef, EmitHandle, EmitOptions, EventContextProvider, HostContext, McpClient, McpInfo, PluginHostManifest, PluginManifest, PluginTool, PluginToolCallContext, } from "./Plugin.js";
+export { DaemonStoppedError, definePlugin } from "./Plugin.js";
+export { type NotificationHandler, POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, PostgresConnection, type PostgresConnectionConfig, } from "./PostgresConnection.js";
+export type { NewScheduledSubagent, ScheduledSubagentRow } from "./ScheduledSubagent.js";
+export { ScheduledSubagentBus, type ScheduledSubagentNotification, type ScheduledSubagentOp, type ScheduledSubagentUnsubscribe, } from "./ScheduledSubagentBus.js";
+export { AGENTRUNS_CHANNEL, CHATMESSAGES_NEW_CHANNEL, EVENT_TERMINAL_UPDATE_SQL, EVENTS_NEW_CHANNEL, EVENTS_STATE_CHANNEL, SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL, STEPRESULTS_NEW_CHANNEL, TOPIC_PATTERN, } from "./Schema.js";
+export type { NewStepResult, StepResultRow } from "./StepResult.js";
+export { StepResultBus, type StepResultUnsubscribe } from "./StepResultBus.js";
+export { dayBoundsInZone, type ParseInZoneResult, parseInZone, renderInZone, } from "./Timezone.js";
+export type { NewToolCall, ToolCallRow, ToolUsageCount } from "./ToolCall.js";
+export { ToolCallBus } from "./ToolCallBus.js";
+export { DEFAULT_TOOL_LEVEL, type ToolLevel } from "./ToolLevel.js";
+export { DEFAULT_TOOL_CALL_OFFLOADING_LIMIT, type OffloadedJson, runJsonLinesTool, runJsonTool, runTextTool, ToolError, type ToolRunContext, truncateUtf8, } from "./ToolRunner.js";
+export { ALL_GROUP_NAME, CORE_PLUGIN_ID, IDENT_PATTERN, MCP_GROUP_NAME, matchesAnyToolPattern, NONE_GROUP_NAME, RESERVED_GROUP_NAMES, toolPatternMatches, validateGroupName, } from "./ToolsExpressionUtils.js";
+export type { WorkspaceFile, WorkspaceFileFilter, WorkspaceWatcherApi, } from "./WorkspaceFile.js";

package/build/index.js

@@ -0,0 +1,26 @@
+export { AgentRunBus } from "./AgentRunBus.js";
+export { buildCalendarEventId, parseCalendarEventId, } from "./Calendar.js";
+export { ChatMessageBus } from "./ChatMessageBus.js";
+export { parseCron } from "./CronExpression.js";
+export { EVENT_PRIORITY } from "./Event.js";
+export { DuplicateIdempotencyKeyError, EventBus } from "./EventBus.js";
+export { estimateTokens } from "./estimateTokens.js";
+export { HandlerCatalog } from "./HandlerCatalog.js";
+export { InferenceEventBus } from "./InferenceEventBus.js";
+export { createLogger, jsonStdoutStream, prettyStdoutStream, } from "./logging/Logger.js";
+export { buildMailId, parseMailId, } from "./Mail.js";
+export { MAIL_STYLE_TEMPLATE_DEFAULTS, mailStyleTemplatePath, signatureToPlainText, } from "./MailStyleTemplate.js";
+export { ModelNotSupported, } from "./ModelMetaData.js";
+export { renderMarkdownToHtml } from "./markdownHtml.js";
+export { renderMarkdown } from "./markdownTerminal.js";
+export { matchesAnyGlob, matchesGlob } from "./PathGlob.js";
+export { DaemonStoppedError, definePlugin } from "./Plugin.js";
+export { POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, PostgresConnection, } from "./PostgresConnection.js";
+export { ScheduledSubagentBus, } from "./ScheduledSubagentBus.js";
+export { AGENTRUNS_CHANNEL, CHATMESSAGES_NEW_CHANNEL, EVENT_TERMINAL_UPDATE_SQL, EVENTS_NEW_CHANNEL, EVENTS_STATE_CHANNEL, SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL, STEPRESULTS_NEW_CHANNEL, TOPIC_PATTERN, } from "./Schema.js";
+export { StepResultBus } from "./StepResultBus.js";
+export { dayBoundsInZone, parseInZone, renderInZone, } from "./Timezone.js";
+export { ToolCallBus } from "./ToolCallBus.js";
+export { DEFAULT_TOOL_LEVEL } from "./ToolLevel.js";
+export { DEFAULT_TOOL_CALL_OFFLOADING_LIMIT, runJsonLinesTool, runJsonTool, runTextTool, ToolError, truncateUtf8, } from "./ToolRunner.js";
+export { ALL_GROUP_NAME, CORE_PLUGIN_ID, IDENT_PATTERN, MCP_GROUP_NAME, matchesAnyToolPattern, NONE_GROUP_NAME, RESERVED_GROUP_NAMES, toolPatternMatches, validateGroupName, } from "./ToolsExpressionUtils.js";

package/build/logging/Logger.d.ts

@@ -0,0 +1,66 @@
+import { type DestinationStream } from "pino";
+/**
+ * Structured logger used by both host and container.
+ *
+ * Thin shape over `pino.Logger` so call sites only see the small surface
+ * we actually use, and so the streams plumbing (multistream, levels) is
+ * owned in one place. Always create child loggers via {@link Logger.child}
+ * so per-component tags (`component`, `source`, …) accumulate.
+ */
+export interface Logger {
+    debug(obj: object, msg?: string): void;
+    debug(msg: string): void;
+    info(obj: object, msg?: string): void;
+    info(msg: string): void;
+    warn(obj: object, msg?: string): void;
+    warn(msg: string): void;
+    error(obj: object, msg?: string): void;
+    error(msg: string): void;
+    /**
+     * Return a child logger that always includes `bindings` on every
+     * record. Children share the underlying streams and level.
+     */
+    child(bindings: Record<string, unknown>): Logger;
+}
+/** Levels exposed to call sites. `debug` is what `--verbose` enables. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * One sink for the logger. Wraps a pino-compatible {@link DestinationStream}
+ * so {@link createLogger} can compose multiple sinks via `pino.multistream`.
+ */
+export interface LogStream {
+    readonly stream: DestinationStream;
+}
+/** Options accepted by {@link createLogger}. */
+export interface CreateLoggerOptions {
+    /** Top-level component tag stamped on every record. */
+    readonly component: string;
+    /** Minimum level emitted. */
+    readonly level: LogLevel;
+    /**
+     * One or more sinks. Multiple streams use `pino.multistream`. A
+     * single stream is wired directly. Levels on individual streams
+     * default to the logger's level.
+     */
+    readonly streams: readonly LogStream[];
+}
+/**
+ * Build a {@link Logger}. Call once per process (host: in `Start.ts`;
+ * container: in `index.ts`); pass children into subsystems.
+ *
+ * @throws If `streams` is empty — there's no useful default sink.
+ */
+export declare function createLogger(options: CreateLoggerOptions): Logger;
+/**
+ * Pretty-printed stdout for interactive use. Imports `pino-pretty`
+ * lazily so the container image — which never wants pretty output —
+ * doesn't have to ship the dep.
+ *
+ * @throws If `pino-pretty` isn't installed in the current package.
+ */
+export declare function prettyStdoutStream(): LogStream;
+/**
+ * Raw JSON to stdout. Used by the container (the host parses each line
+ * back) and by the host when stdout isn't a TTY.
+ */
+export declare function jsonStdoutStream(): LogStream;

package/build/logging/Logger.js

@@ -0,0 +1,90 @@
+import { createRequire } from "node:module";
+import pino, { multistream, } from "pino";
+/**
+ * `require` shim for the ESM build. {@link prettyStdoutStream} pulls
+ * in `pino-pretty` lazily at call time so consumers (notably the
+ * container) that never use pretty output don't have to ship the dep,
+ * and `pino-pretty` is published as CommonJS — both reasons make a
+ * dynamic ESM `import()` overkill compared with `createRequire`.
+ */
+const require = createRequire(import.meta.url);
+/**
+ * Build a {@link Logger}. Call once per process (host: in `Start.ts`;
+ * container: in `index.ts`); pass children into subsystems.
+ *
+ * @throws If `streams` is empty — there's no useful default sink.
+ */
+export function createLogger(options) {
+    if (options.streams.length === 0) {
+        throw new Error("createLogger requires at least one stream");
+    }
+    const opts = {
+        level: options.level,
+        base: { component: options.component },
+        timestamp: pino.stdTimeFunctions.isoTime,
+    };
+    // pino.multistream defaults each stream's accept level to `info`
+    // regardless of the parent logger's level, so debug records would
+    // be silently dropped at the stream gate. Tag every entry with the
+    // configured level so all streams accept it.
+    const pinoLogger = options.streams.length === 1
+        ? pino(opts, options.streams[0].stream)
+        : pino(opts, multistream(options.streams.map((s) => ({ stream: s.stream, level: options.level })), { dedupe: false }));
+    return wrap(pinoLogger);
+}
+/**
+ * Pretty-printed stdout for interactive use. Imports `pino-pretty`
+ * lazily so the container image — which never wants pretty output —
+ * doesn't have to ship the dep.
+ *
+ * @throws If `pino-pretty` isn't installed in the current package.
+ */
+export function prettyStdoutStream() {
+    // Required at call time so callers that don't use it don't pay
+    // the resolution cost (and the container build doesn't break).
+    const pretty = require("pino-pretty");
+    const stream = pretty({
+        colorize: true,
+        translateTime: "HH:MM:ss",
+        ignore: "pid,hostname",
+        messageFormat: "[{component}{if source}/{source}{end}] {msg}",
+        // Suppress the trailing structured payload on stdout. Most
+        // call sites bake the data they want a human to see into
+        // the message itself (`postgres ready on 127.0.0.1:5432`,
+        // not `{host:..., port:...} postgres ready`); the rolling
+        // file sink still gets full JSON for grep / jq, so nothing
+        // is actually lost. See `commands/Start.ts` and friends for
+        // the conversion pattern.
+        hideObject: true,
+    });
+    return { stream };
+}
+/**
+ * Raw JSON to stdout. Used by the container (the host parses each line
+ * back) and by the host when stdout isn't a TTY.
+ */
+export function jsonStdoutStream() {
+    return { stream: process.stdout };
+}
+/** Wrap a pino instance behind the {@link Logger} surface. */
+function wrap(p) {
+    return {
+        debug: (a, b) => emit(p, "debug", a, b),
+        info: (a, b) => emit(p, "info", a, b),
+        warn: (a, b) => emit(p, "warn", a, b),
+        error: (a, b) => emit(p, "error", a, b),
+        child: (bindings) => wrap(p.child(bindings)),
+    };
+}
+/** Forward to pino's overloaded level method preserving the (obj, msg) form. */
+function emit(p, level, a, b) {
+    if (typeof a === "string") {
+        p[level](a);
+        return;
+    }
+    if (b === undefined) {
+        p[level](a);
+        return;
+    }
+    p[level](a, b);
+}

package/build/markdownHtml.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Render the agent-supplied markdown body to an HTML fragment suitable for
+ * providers that want HTML on the wire (Microsoft Graph mail/calendar bodies,
+ * future SMTP/IMAP plugins, etc.). Output is a plain fragment — no `<html>`,
+ * `<head>`, or inline CSS — so callers can wrap it however the destination
+ * needs.
+ *
+ * `marked` is configured for GFM line breaks (a single newline becomes a
+ * `<br>`), which matches how a person typing the body in chat naturally
+ * thinks about paragraph breaks. The default `marked` behaviour requires two
+ * newlines for a paragraph break — that's markdown-correct but surprises
+ * agents and humans often enough to be worth the override.
+ */
+export declare function renderMarkdownToHtml(markdownBody: string): string;

package/build/markdownHtml.js

@@ -0,0 +1,21 @@
+import { marked } from "marked";
+/**
+ * Render the agent-supplied markdown body to an HTML fragment suitable for
+ * providers that want HTML on the wire (Microsoft Graph mail/calendar bodies,
+ * future SMTP/IMAP plugins, etc.). Output is a plain fragment — no `<html>`,
+ * `<head>`, or inline CSS — so callers can wrap it however the destination
+ * needs.
+ *
+ * `marked` is configured for GFM line breaks (a single newline becomes a
+ * `<br>`), which matches how a person typing the body in chat naturally
+ * thinks about paragraph breaks. The default `marked` behaviour requires two
+ * newlines for a paragraph break — that's markdown-correct but surprises
+ * agents and humans often enough to be worth the override.
+ */
+export function renderMarkdownToHtml(markdownBody) {
+    return marked.parse(markdownBody, {
+        async: false,
+        gfm: true,
+        breaks: true,
+    });
+}

package/build/markdownTerminal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Render markdown to ANSI-styled terminal output at the current terminal
+ * width. Caller is expected to have decided (e.g. via a TTY check) that
+ * ANSI styling is appropriate; this function does no TTY detection of its
+ * own and always emits styled output.
+ *
+ * Trailing newlines are preserved — call sites that print a separator
+ * afterwards may want to `.replace(/\n+$/, "")` to avoid compounding
+ * blank lines.
+ *
+ * @param input - markdown source
+ * @returns ANSI-styled terminal output
+ */
+export declare function renderMarkdown(input: string): string;

package/build/markdownTerminal.js

@@ -0,0 +1,376 @@
+import chalk from "chalk";
+import { highlight } from "cli-highlight";
+import Table from "cli-table3";
+import { Marked } from "marked";
+import { stdout as terminalSupportsHyperlinks } from "supports-hyperlinks";
+import wrapAnsi from "wrap-ansi";
+/**
+ * Render a markdown string to ANSI-styled terminal output. Used by
+ * host-side `report` rendering and by the cli-chat plugin so chat
+ * replies pick up headings, lists, code blocks, and inline emphasis
+ * instead of leaking raw markdown.
+ *
+ * This is a self-contained renderer built on `marked` (the parser)
+ * plus `cli-highlight` (code), `cli-table3` (tables), `chalk` (inline
+ * styling), and `wrap-ansi` (wrapping). It replaces `marked-terminal`,
+ * whose block-styling-plus-reflow model produced two classes of bug we
+ * could not fix from the outside:
+ *
+ *   1. **Indentation-blind width.** It reflowed each block to the full
+ *      width and only then indented it for blockquotes/lists, so nested
+ *      prose and tables overflowed the terminal.
+ *   2. **ANSI bleed.** It wrapped each block in a single open/close
+ *      style pair, then split the block into lines without re-opening
+ *      the style per line — so colour state leaked across newlines and
+ *      inner resets (a codespan's `ESC[39m`) cancelled the surrounding
+ *      block colour.
+ *
+ * Both are avoided here by (a) tracking the remaining content width
+ * (`avail`) as we descend into containers, so every block wraps to the
+ * width it will actually occupy, and (b) wrapping with `wrap-ansi`,
+ * which emits self-contained lines (styles re-opened at each line start
+ * and closed at each line end). Inline spans are never wrapped — all
+ * wrapping happens at block boundaries — so an escape sequence is never
+ * split mid-line.
+ *
+ * The output is width-aware per call: every render reads the current
+ * terminal width, so a long-lived chat REPL picks up resizes between
+ * turns.
+ */
+/** Upper bound on render width; full-width prose is hard to read on ultra-wide terminals. */
+const MAX_WIDTH = 180;
+/** Fallback width when stdout is not a TTY (no `columns`). */
+const FALLBACK_WIDTH = 100;
+/** Floor on the content width at deep nesting, so wrapping never degenerates. */
+const MIN_CONTENT_WIDTH = 12;
+/** Columns a blockquote reserves for its `│ ` bar. */
+const BLOCKQUOTE_RESERVE = 2;
+/** cli-table3 reserves one space of padding on each side of a cell; colWidth = content + this. */
+const CELL_PADDING = 2;
+/** Smallest table `colWidth` we will shrink a column to — one content char plus padding. */
+const MIN_COL_WIDTH = CELL_PADDING + 1;
+/** Inline and block styles. Kept here so the look is tweakable in one place. */
+const STYLE = {
+    // Bold gets a dark-gray background (palette index 236 ≈ #303030): plain
+    // bold is invisible in monospace fonts without a bold variant, so the
+    // block reads as a highlighter on any 256-colour terminal.
+    strong: chalk.bgAnsi256(236).bold,
+    em: chalk.italic,
+    del: chalk.dim.strikethrough,
+    codespan: chalk.yellow,
+    code: chalk.yellow,
+    link: chalk.blue.underline,
+    heading: chalk.green.bold,
+    firstHeading: chalk.magenta.underline.bold,
+    blockquoteBar: chalk.dim("│ "),
+    hr: chalk.dim,
+    html: chalk.gray,
+};
+/**
+ * Unescape the HTML entities marked emits in text and code spans, so the
+ * terminal shows the real characters (`&amp;` → `&`, `&lt;` → `<`, …).
+ *
+ * @param text - possibly entity-escaped string
+ * @returns the string with the common entities resolved
+ */
+function unescapeEntities(text) {
+    return text
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'");
+}
+/**
+ * Remove OSC 8 terminal-hyperlink escape sequences, keeping the visible
+ * link text. The `link` renderer emits these when the terminal supports
+ * hyperlinks, but cli-table3's cell wrapping only understands SGR colour
+ * codes — a link inside a wrapped table cell would have its width
+ * miscounted and its bytes split mid-sequence — so table cells render
+ * links as plain (non-clickable) text. The sequence is
+ * `ESC ] 8 ; params ; URI ST text ESC ] 8 ; ; ST`, ST = BEL or `ESC \`.
+ *
+ * @param text - possibly hyperlink-bearing styled string
+ * @returns the string with OSC 8 wrappers removed
+ */
+function stripHyperlinks(text) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: OSC escapes are control chars by definition.
+    return text.replace(/\x1b\]8;[^;]*;[^\x1b\x07]*(?:\x07|\x1b\\)/g, "");
+}
+/**
+ * Wrap an OSC 8 terminal hyperlink around visible (already-styled) text.
+ *
+ * @param text - the visible, clickable text
+ * @param url - the link target
+ * @returns the text wrapped in an OSC 8 hyperlink sequence
+ */
+function hyperlink(text, url) {
+    return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+/**
+ * Visible length of a cell's raw source text. Slightly over-estimates
+ * (markdown markers count), which only hands a column a touch more room
+ * — cli-table3 does the exact ANSI-aware wrapping itself.
+ *
+ * @param text - raw markdown cell text
+ * @returns character count
+ */
+function visibleLength(text) {
+    return text.length;
+}
+/**
+ * Decide per-column `colWidths` for a markdown table so it fits the
+ * available width. Returns `undefined` when the table's natural size
+ * already fits — letting cli-table3 size columns to content with no
+ * wrapping. On overflow, distributes the available width across columns
+ * proportionally to their natural size, with a per-column floor.
+ *
+ * @param naturalContent - natural content width of each column (no padding)
+ * @param width - width to fit within
+ * @returns colWidths array including padding, or `undefined` for natural sizing
+ */
+function budgetColumns(naturalContent, width) {
+    const columnCount = naturalContent.length;
+    if (columnCount === 0) {
+        return undefined;
+    }
+    const borders = columnCount + 1;
+    const naturalColWidths = naturalContent.map((content) => content + CELL_PADDING);
+    const naturalTotal = naturalColWidths.reduce((sum, w) => sum + w, 0) + borders;
+    if (naturalTotal <= width) {
+        return undefined;
+    }
+    const available = Math.max(width, MIN_COL_WIDTH * columnCount + borders) - borders;
+    const naturalSum = naturalColWidths.reduce((sum, w) => sum + w, 0);
+    const widths = naturalColWidths.map((w) => Math.max(MIN_COL_WIDTH, Math.round((available * w) / naturalSum)));
+    // Rounding and the floor can push the total back over `available`;
+    // trim from the widest column above the floor until it fits.
+    let total = widths.reduce((sum, w) => sum + w, 0);
+    while (total > available) {
+        let widestIndex = -1;
+        for (let i = 0; i < widths.length; i += 1) {
+            if (widths[i] > MIN_COL_WIDTH &&
+                (widestIndex === -1 || widths[i] > widths[widestIndex])) {
+                widestIndex = i;
+            }
+        }
+        if (widestIndex === -1) {
+            break;
+        }
+        widths[widestIndex] -= 1;
+        total -= 1;
+    }
+    return widths;
+}
+/**
+ * Build the marked renderer. All wrapping and indentation is driven by a
+ * mutable `avail` (remaining content width) captured in this closure:
+ * container renderers shrink it before parsing their children and
+ * restore it after (marked parses depth-first and synchronously, so this
+ * is safe), and block renderers wrap to it. The visible left margin is
+ * applied per line by the container as the recursion unwinds, so the
+ * total margin equals the columns reserved.
+ *
+ * @param width - the effective terminal width for this render
+ * @returns a marked `RendererObject` plus the `avail` accessor it closes over
+ */
+function buildRenderer(width) {
+    let avail = width;
+    /** Wrap styled text to a width, emitting self-contained lines. */
+    const wrap = (styled, w, trim = true) => wrapAnsi(styled, Math.max(MIN_CONTENT_WIDTH, w), { hard: true, trim });
+    /** Run `render` with `avail` reduced by `reserve`, then restore it. */
+    const withReserved = (reserve, render) => {
+        const saved = avail;
+        avail = Math.max(MIN_CONTENT_WIDTH, avail - reserve);
+        try {
+            return render();
+        }
+        finally {
+            avail = saved;
+        }
+    };
+    /** Prefix the first line with `first`, the rest with `rest` (empty lines stay empty). */
+    const prefixLines = (text, first, rest) => text
+        .split("\n")
+        .map((line, index) => (line === "" ? "" : (index === 0 ? first : rest) + line))
+        .join("\n");
+    const parseCell = function (cell) {
+        return stripHyperlinks(this.parser.parseInline(cell.tokens));
+    };
+    /**
+     * Render one list item: render its content at the reduced width, then
+     * wrap and prefix the first line with the bullet/number and
+     * continuation lines with matching spaces (hanging indent). Nested
+     * lists already fit the reduced width, so re-wrapping leaves them
+     * untouched while still wrapping the item's own long leading text.
+     */
+    const renderItem = function (item, marker, markerWidth) {
+        const contentWidth = Math.max(MIN_CONTENT_WIDTH, avail - markerWidth);
+        const saved = avail;
+        avail = contentWidth;
+        let content;
+        try {
+            content = this.parser.parse(item.tokens, !!item.loose);
+        }
+        finally {
+            avail = saved;
+        }
+        let body = content.replace(/\n+$/u, "");
+        if (item.task) {
+            body = `[${item.checked ? "x" : " "}] ${body}`;
+        }
+        // trim:false so the leading indentation of nested list lines survives;
+        // strip only trailing whitespace that the no-trim wrap leaves behind.
+        const wrapped = wrap(body, contentWidth, false).replace(/[^\S\n]+$/gmu, "");
+        return `${prefixLines(wrapped, marker, " ".repeat(markerWidth))}\n`;
+    };
+    const renderer = {
+        space() {
+            return "";
+        },
+        text(token) {
+            // Block `text` tokens (tight list items) carry inline children; render
+            // them and add a trailing newline so a following nested list separates
+            // from the item's leading text. Wrapping is the caller's job — never
+            // wrap inline content here. Inline `text` tokens have no `.tokens` and
+            // hit the plain branch, so this newline is block-only.
+            if ("tokens" in token && Array.isArray(token.tokens) && token.tokens.length > 0) {
+                return `${this.parser.parseInline(token.tokens)}\n`;
+            }
+            return unescapeEntities(token.text);
+        },
+        paragraph(token) {
+            // trim:false so author-supplied leading indentation on hard-break
+            // continuation lines survives (e.g. the report's indented `Thinking:`
+            // / `tool_call:` lines under a bold step header); strip only the
+            // trailing whitespace the no-trim wrap leaves behind, mirroring
+            // renderItem.
+            const wrapped = wrap(this.parser.parseInline(token.tokens), avail, false).replace(/[^\S\n]+$/gmu, "");
+            return `${wrapped}\n\n`;
+        },
+        heading(token) {
+            const prefix = `${"#".repeat(token.depth)} `;
+            const style = token.depth === 1 ? STYLE.firstHeading : STYLE.heading;
+            return `${wrap(style(prefix + this.parser.parseInline(token.tokens)), avail)}\n\n`;
+        },
+        blockquote(token) {
+            const inner = withReserved(BLOCKQUOTE_RESERVE, () => this.parser.parse(token.tokens)).replace(/\n+$/u, "");
+            const bar = STYLE.blockquoteBar;
+            const body = inner
+                .split("\n")
+                .map((line) => bar + line)
+                .join("\n");
+            return `${body}\n\n`;
+        },
+        list(token) {
+            const ordered = token.ordered;
+            const start = typeof token.start === "number" && token.start ? token.start : 1;
+            const markerWidth = ordered ? String(start + token.items.length - 1).length + 2 : 2;
+            const parts = token.items.map((item, index) => {
+                const marker = ordered ? `${start + index}. `.padEnd(markerWidth) : "• ";
+                return renderItem.call(this, item, marker, markerWidth);
+            });
+            return `${parts.join("")}\n`;
+        },
+        listitem() {
+            // Items are rendered by `list` via `renderItem`; never reached.
+            return "";
+        },
+        checkbox(_token) {
+            // Task state is handled inline in `renderItem`; never reached.
+            return "";
+        },
+        code(token) {
+            const language = token.lang?.trim() || undefined;
+            if (chalk.level === 0) {
+                return `${token.text.replace(/\n+$/u, "")}\n\n`;
+            }
+            let body;
+            try {
+                body = highlight(token.text, { language, ignoreIllegals: true });
+            }
+            catch {
+                body = STYLE.code(token.text);
+            }
+            return `${body.replace(/\n+$/u, "")}\n\n`;
+        },
+        hr() {
+            return `${STYLE.hr("─".repeat(Math.max(MIN_CONTENT_WIDTH, avail)))}\n\n`;
+        },
+        br() {
+            return "\n";
+        },
+        html(token) {
+            return STYLE.html(token.text);
+        },
+        strong(token) {
+            return STYLE.strong(this.parser.parseInline(token.tokens));
+        },
+        em(token) {
+            return STYLE.em(this.parser.parseInline(token.tokens));
+        },
+        del(token) {
+            return STYLE.del(this.parser.parseInline(token.tokens));
+        },
+        codespan(token) {
+            return STYLE.codespan(unescapeEntities(token.text));
+        },
+        link(token) {
+            const text = this.parser.parseInline(token.tokens);
+            const href = token.href;
+            if (terminalSupportsHyperlinks) {
+                return hyperlink(STYLE.link(text || href), href);
+            }
+            if (text && text !== href) {
+                return `${STYLE.link(text)} (${chalk.dim(href)})`;
+            }
+            return STYLE.link(href);
+        },
+        image(token) {
+            return `![${token.text}](${token.href})`;
+        },
+        table(token) {
+            const cell = parseCell.bind(this);
+            const naturalContent = token.header.map((header, columnIndex) => Math.max(visibleLength(header.text), ...token.rows.map((row) => visibleLength(row[columnIndex]?.text ?? ""))));
+            const colWidths = budgetColumns(naturalContent, avail);
+            const table = new Table({
+                head: token.header.map(cell),
+                wordWrap: true,
+                wrapOnWordBoundary: false,
+                // Passing `colWidths: undefined` makes cli-table3 throw, so the
+                // key is omitted entirely when the table fits naturally.
+                ...(colWidths ? { colWidths } : {}),
+            });
+            for (const row of token.rows) {
+                table.push(row.map(cell));
+            }
+            return `${table.toString()}\n\n`;
+        },
+        tablerow() {
+            return "";
+        },
+        tablecell() {
+            return "";
+        },
+    };
+    return renderer;
+}
+/**
+ * Render markdown to ANSI-styled terminal output at the current terminal
+ * width. Caller is expected to have decided (e.g. via a TTY check) that
+ * ANSI styling is appropriate; this function does no TTY detection of its
+ * own and always emits styled output.
+ *
+ * Trailing newlines are preserved — call sites that print a separator
+ * afterwards may want to `.replace(/\n+$/, "")` to avoid compounding
+ * blank lines.
+ *
+ * @param input - markdown source
+ * @returns ANSI-styled terminal output
+ */
+export function renderMarkdown(input) {
+    const width = Math.min(process.stdout.columns ?? FALLBACK_WIDTH, MAX_WIDTH);
+    const marked = new Marked();
+    marked.use({ renderer: buildRenderer(width) });
+    return marked.parse(input);
+}