@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/tool-usage-report.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The exact-range Tool Insights report (plan §3.1, S2; client contract in
+ * `docs/tool-insights/host-contract.md`).
+ *
+ * The projection keeps the detail; this module filters it to a window and produces the
+ * rollups the page renders. Range filtering uses the PER-DAY counters the projection
+ * records, so call/error/duration totals are exact for the window.
+ *
+ * Percentiles come from the retained 16-bucket histograms. The histograms are not split
+ * by day, so p50/p95 are an approximation over the retained settled calls while `maxMs`
+ * is exact for the window. `histogramScope: 'retained'` states this.
+ *
+ * @module @try-works/dsh-tool-mode/tool-usage-report
+ */
+import { type ToolUsageState } from './tool-usage-projection.ts';
+/** The ranges the page offers. */
+export type UsageRange = '24h' | '7d' | '30d' | 'all';
+/** One resolved window. `from` is inclusive, `to` exclusive (milliseconds). */
+export interface UsageWindow {
+    readonly range: UsageRange;
+    readonly from: number;
+    readonly to: number;
+    /** Host-local day key of `from` (inclusive). */
+    readonly fromDay: string;
+    /** Host-local day key of `to` (inclusive). */
+    readonly toDay: string;
+}
+/** One session's detail state joined with the workspace it belongs to. */
+export interface SessionUsageInput {
+    readonly sessionId: string;
+    readonly workspace: string | null;
+    readonly state: ToolUsageState;
+}
+/** One tool's performance over the window (flat client contract). */
+export interface UsageToolRow {
+    readonly name: string;
+    readonly owner: string;
+    readonly calls: number;
+    readonly errors: number;
+    readonly unsettled: number;
+    readonly codeCalls: number;
+    readonly directCalls: number;
+    readonly totalMs: number;
+    readonly maxMs: number;
+    readonly p50: number | null;
+    readonly p95: number | null;
+    readonly firstUsed: number | null;
+    readonly lastUsed: number | null;
+    readonly argsBytes: number;
+    readonly resultBytes: number;
+}
+/** One model row. */
+export interface UsageModelRow {
+    readonly model: string;
+    readonly calls: number;
+    readonly errors: number;
+    readonly tools: number;
+    readonly ms: number;
+    readonly p50: number | null;
+    readonly p95: number | null;
+}
+/** One day row. */
+export interface UsageDayRow {
+    readonly day: string;
+    readonly calls: number;
+    readonly errors: number;
+    readonly ms: number;
+    readonly unsettled: number;
+}
+/** One workspace row. */
+export interface UsageWorkspaceRow {
+    readonly workspace: string;
+    readonly sessions: number;
+    readonly calls: number;
+    readonly errors: number;
+    readonly ms: number;
+}
+/** One recent call, in the client's flat vocabulary. */
+export interface UsageRecentCall {
+    readonly time: number;
+    readonly name: string;
+    readonly owner: string;
+    readonly model: string;
+    readonly ms: number | null;
+    readonly ok: boolean | null;
+    readonly errorCode: string | null;
+    readonly kind: 'direct' | 'code';
+    readonly callId: string;
+    readonly parentCallId: string | null;
+    readonly sessionId: string;
+    readonly workspace: string | null;
+}
+/** One error-code row. */
+export interface UsageErrorCodeRow {
+    readonly code: string;
+    readonly calls: number;
+}
+/** The whole report (flat totals plus rollups; the client contract). */
+export interface UsageReport {
+    readonly range: UsageRange;
+    readonly from: number;
+    readonly to: number;
+    readonly calls: number;
+    readonly errors: number;
+    readonly unsettled: number;
+    readonly toolMs: number;
+    readonly codeCalls: number;
+    readonly sessions: number;
+    readonly uniqueTools: number;
+    /** Successes over SETTLED calls; null when nothing settled in the window. */
+    readonly successRate: number | null;
+    readonly p50: number | null;
+    readonly p95: number | null;
+    readonly tools: readonly UsageToolRow[];
+    readonly models: readonly UsageModelRow[];
+    readonly days: readonly UsageDayRow[];
+    readonly workspaces: readonly UsageWorkspaceRow[];
+    readonly errorCodes: readonly UsageErrorCodeRow[];
+    readonly recentCalls: readonly UsageRecentCall[];
+    readonly histogramScope: 'retained';
+}
+/**
+ * Resolve one range to a window.
+ * @param range - the selected range.
+ * @param now - the current time in milliseconds.
+ * @returns the window with host-local day keys.
+ */
+export declare function rangeWindow(range: UsageRange, now: number): UsageWindow;
+/**
+ * The percentile an aggregated 16-bucket histogram implies.
+ *
+ * Each bucket answers with its UPPER edge; the open-ended last bucket answers with the
+ * exact retained maximum. An empty histogram has no percentile.
+ * @param histogram - bucket counts.
+ * @param percentile - 1..100.
+ * @param maxMs - the exact maximum observed duration.
+ * @returns the derived duration, or null for an empty histogram.
+ */
+export declare function percentileFromHistogram(histogram: readonly number[], percentile: number, maxMs: number): number | null;
+/** The owner resolver the host supplies (live extension store), with a static fallback. */
+export type UsageOwnerResolver = (name: string) => string;
+/**
+ * Aggregate the sessions' detail states over one window.
+ * @param sessions - the sessions' detail states and workspaces.
+ * @param window - the resolved window.
+ * @param options - `recentLimit` bounds recent calls; `resolveOwner` supplies live owners.
+ * @returns the client-contract report.
+ */
+export declare function buildUsageReport(sessions: readonly SessionUsageInput[], window: UsageWindow, options?: {
+    readonly recentLimit?: number;
+    readonly resolveOwner?: UsageOwnerResolver;
+}): UsageReport;
+//# sourceMappingURL=tool-usage-report.d.ts.map

package/lib/tool-usage-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-usage-report.d.ts","sourceRoot":"","sources":["../src/tool-usage-report.ts"],"names":[],"mappings":"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"}

package/lib/tool-usage-report.js

@@ -0,0 +1,274 @@
+/**
+ * The exact-range Tool Insights report (plan §3.1, S2; client contract in
+ * `docs/tool-insights/host-contract.md`).
+ *
+ * The projection keeps the detail; this module filters it to a window and produces the
+ * rollups the page renders. Range filtering uses the PER-DAY counters the projection
+ * records, so call/error/duration totals are exact for the window.
+ *
+ * Percentiles come from the retained 16-bucket histograms. The histograms are not split
+ * by day, so p50/p95 are an approximation over the retained settled calls while `maxMs`
+ * is exact for the window. `histogramScope: 'retained'` states this.
+ *
+ * @module @try-works/dsh-tool-mode/tool-usage-report
+ */
+import { DURATION_BUCKETS_MS, TOOL_USAGE_CAPS, toolUsageDayKey, } from "./tool-usage-projection.js";
+import { staticToolOwner } from "./tool-sources.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Resolve one range to a window.
+ * @param range - the selected range.
+ * @param now - the current time in milliseconds.
+ * @returns the window with host-local day keys.
+ */
+export function rangeWindow(range, now) {
+    const from = range === 'all' ? 0 : now - (range === '24h' ? DAY_MS : range === '7d' ? 7 * DAY_MS : 30 * DAY_MS);
+    return { range, from, to: now, fromDay: toolUsageDayKey(from), toDay: toolUsageDayKey(now) };
+}
+/**
+ * The percentile an aggregated 16-bucket histogram implies.
+ *
+ * Each bucket answers with its UPPER edge; the open-ended last bucket answers with the
+ * exact retained maximum. An empty histogram has no percentile.
+ * @param histogram - bucket counts.
+ * @param percentile - 1..100.
+ * @param maxMs - the exact maximum observed duration.
+ * @returns the derived duration, or null for an empty histogram.
+ */
+export function percentileFromHistogram(histogram, percentile, maxMs) {
+    const total = histogram.reduce((sum, count) => sum + count, 0);
+    if (total <= 0)
+        return null;
+    if (percentile >= 100)
+        return maxMs;
+    const rank = Math.max(1, Math.ceil((Math.max(1, percentile) / 100) * total));
+    let seen = 0;
+    for (let index = 0; index < histogram.length; index += 1) {
+        seen += histogram[index] ?? 0;
+        if (seen < rank)
+            continue;
+        if (index >= DURATION_BUCKETS_MS.length - 1)
+            return maxMs;
+        return DURATION_BUCKETS_MS[index] ?? maxMs;
+    }
+    return maxMs;
+}
+/** Whether a day key falls inside the window's inclusive day span. */
+function dayInWindow(day, window) {
+    return day >= window.fromDay && day <= window.toDay;
+}
+/** The retained minimum time when it falls inside the window, else null. */
+function minTime(current, candidate, window) {
+    const values = [current, candidate].filter((value) => value !== null && value >= window.from && value < window.to);
+    return values.length === 0 ? null : Math.min(...values);
+}
+/** The retained maximum time when it falls inside the window, else null. */
+function maxTime(current, candidate, window) {
+    const values = [current, candidate].filter((value) => value !== null && value >= window.from && value < window.to);
+    return values.length === 0 ? null : Math.max(...values);
+}
+/** The default owner resolution: pinned map, Tool Mode, MCP grammar, else `unattributed`. */
+function defaultOwner(name) {
+    return staticToolOwner(name).owner;
+}
+/**
+ * Aggregate the sessions' detail states over one window.
+ * @param sessions - the sessions' detail states and workspaces.
+ * @param window - the resolved window.
+ * @param options - `recentLimit` bounds recent calls; `resolveOwner` supplies live owners.
+ * @returns the client-contract report.
+ */
+export function buildUsageReport(sessions, window, options = {}) {
+    const recentLimit = options.recentLimit ?? TOOL_USAGE_CAPS.recent;
+    const resolveOwner = options.resolveOwner ?? defaultOwner;
+    let calls = 0;
+    let errors = 0;
+    let unsettled = 0;
+    let toolMs = 0;
+    let codeCalls = 0;
+    let sessionsWithCalls = 0;
+    const overallHistogram = Array.from({ length: TOOL_USAGE_CAPS.buckets }, () => 0);
+    const days = new Map();
+    const tools = new Map();
+    const models = new Map();
+    const workspaces = new Map();
+    const errorCodes = new Map();
+    const recentCalls = [];
+    for (const session of sessions) {
+        let sessionCalls = 0;
+        let sessionErrors = 0;
+        let sessionMs = 0;
+        for (const [day, usage] of Object.entries(session.state.byDay)) {
+            if (!dayInWindow(day, window))
+                continue;
+            sessionCalls += usage.calls;
+            sessionErrors += usage.errors;
+            sessionMs += usage.ms;
+            const current = days.get(day) ?? { day, calls: 0, errors: 0, ms: 0, unsettled: 0 };
+            days.set(day, { day, calls: current.calls + usage.calls, errors: current.errors + usage.errors, ms: current.ms + usage.ms, unsettled: current.unsettled + usage.unsettled });
+            for (const [code, count] of Object.entries(usage.byCode))
+                errorCodes.set(code, (errorCodes.get(code) ?? 0) + count);
+        }
+        calls += sessionCalls;
+        errors += sessionErrors;
+        toolMs += sessionMs;
+        if (sessionCalls === 0)
+            continue;
+        sessionsWithCalls += 1;
+        const workspaceLabel = session.workspace ?? '(no workspace)';
+        const workspace = workspaces.get(workspaceLabel) ?? { workspace: workspaceLabel, sessions: 0, calls: 0, errors: 0, ms: 0 };
+        workspaces.set(workspaceLabel, { ...workspace, sessions: workspace.sessions + 1, calls: workspace.calls + sessionCalls, errors: workspace.errors + sessionErrors, ms: workspace.ms + sessionMs });
+        for (const [name, bucket] of Object.entries(session.state.byTool)) {
+            let rowCalls = 0;
+            let rowErrors = 0;
+            let rowMs = 0;
+            let rowMax = 0;
+            let rowUnsettled = 0;
+            let rowCode = 0;
+            let rowDirect = 0;
+            for (const [day, count] of Object.entries(bucket.byDay)) {
+                if (!dayInWindow(day, window))
+                    continue;
+                rowCalls += count.calls;
+                rowErrors += count.errors;
+                rowMs += count.ms;
+                rowMax = Math.max(rowMax, count.maxMs);
+                rowUnsettled += count.unsettled;
+                rowCode += count.codeCalls;
+                rowDirect += count.calls - count.codeCalls;
+            }
+            if (rowCalls === 0 && rowUnsettled === 0)
+                continue;
+            codeCalls += rowCode;
+            const current = tools.get(name) ?? {
+                calls: 0, errors: 0, unsettled: 0, codeCalls: 0, directCalls: 0, totalMs: 0, maxMs: 0,
+                histogram: Array.from({ length: TOOL_USAGE_CAPS.buckets }, () => 0), firstUsed: null, lastUsed: null,
+                argsBytes: 0, resultBytes: 0,
+            };
+            const histogram = current.histogram.map((count, index) => count + (bucket.histogram[index] ?? 0));
+            for (let index = 0; index < histogram.length; index += 1)
+                overallHistogram[index] = (overallHistogram[index] ?? 0) + (bucket.histogram[index] ?? 0);
+            tools.set(name, {
+                calls: current.calls + rowCalls,
+                errors: current.errors + rowErrors,
+                unsettled: current.unsettled + rowUnsettled,
+                codeCalls: current.codeCalls + rowCode,
+                directCalls: current.directCalls + rowDirect,
+                totalMs: current.totalMs + rowMs,
+                maxMs: Math.max(current.maxMs, rowMax),
+                histogram,
+                firstUsed: minTime(current.firstUsed, bucket.firstUsed, window),
+                lastUsed: maxTime(current.lastUsed, bucket.lastUsed, window),
+                argsBytes: current.argsBytes + bucket.argsBytes,
+                resultBytes: current.resultBytes + bucket.resultBytes,
+            });
+        }
+        for (const [model, usage] of Object.entries(session.state.byModel)) {
+            let rowCalls = 0;
+            let rowErrors = 0;
+            let rowMs = 0;
+            let rowMax = 0;
+            const rowHistogram = Array.from({ length: TOOL_USAGE_CAPS.buckets }, () => 0);
+            for (const [day, count] of Object.entries(usage.byDay)) {
+                if (!dayInWindow(day, window))
+                    continue;
+                rowCalls += count.calls;
+                rowErrors += count.errors;
+                rowMs += count.ms;
+                rowMax = Math.max(rowMax, count.maxMs);
+            }
+            if (rowCalls === 0)
+                continue;
+            for (let index = 0; index < rowHistogram.length; index += 1)
+                rowHistogram[index] = (rowHistogram[index] ?? 0) + (usage.histogram[index] ?? 0);
+            const current = models.get(model) ?? { model, calls: 0, errors: 0, ms: 0, tools: 0, histogram: Array.from({ length: TOOL_USAGE_CAPS.buckets }, () => 0), maxMs: 0 };
+            models.set(model, {
+                model,
+                calls: current.calls + rowCalls,
+                errors: current.errors + rowErrors,
+                ms: current.ms + rowMs,
+                tools: Math.max(current.tools, usage.tools.length),
+                histogram: current.histogram.map((count, index) => count + (rowHistogram[index] ?? 0)),
+                maxMs: Math.max(current.maxMs, rowMax),
+            });
+        }
+        for (const entry of session.state.recent) {
+            if (entry.time < window.from || entry.time >= window.to)
+                continue;
+            recentCalls.push(recentProjection(entry, resolveOwner(entry.name), session.sessionId, session.workspace));
+        }
+        for (const [day, usage] of Object.entries(session.state.byDay)) {
+            if (dayInWindow(day, window))
+                unsettled += usage.unsettled;
+        }
+    }
+    const toolRows = [...tools.entries()].map(([name, tool]) => ({
+        name,
+        owner: resolveOwner(name),
+        calls: tool.calls,
+        errors: tool.errors,
+        unsettled: tool.unsettled,
+        codeCalls: tool.codeCalls,
+        directCalls: tool.directCalls,
+        totalMs: tool.totalMs,
+        maxMs: tool.maxMs,
+        p50: percentileFromHistogram(tool.histogram, 50, tool.maxMs),
+        p95: percentileFromHistogram(tool.histogram, 95, tool.maxMs),
+        firstUsed: tool.firstUsed,
+        lastUsed: tool.lastUsed,
+        argsBytes: tool.argsBytes,
+        resultBytes: tool.resultBytes,
+    }));
+    const modelRows = [...models.values()].map(model => ({
+        model: model.model,
+        calls: model.calls,
+        errors: model.errors,
+        tools: model.tools,
+        ms: model.ms,
+        p50: percentileFromHistogram(model.histogram, 50, model.maxMs),
+        p95: percentileFromHistogram(model.histogram, 95, model.maxMs),
+    }));
+    const settled = calls - unsettled;
+    return {
+        range: window.range,
+        from: window.from,
+        to: window.to,
+        calls,
+        errors,
+        unsettled,
+        toolMs,
+        codeCalls,
+        sessions: sessionsWithCalls,
+        uniqueTools: toolRows.length,
+        successRate: settled <= 0 ? null : (settled - errors) / settled,
+        p50: percentileFromHistogram(overallHistogram, 50, Math.max(0, ...toolRows.map(row => row.maxMs))),
+        p95: percentileFromHistogram(overallHistogram, 95, Math.max(0, ...toolRows.map(row => row.maxMs))),
+        tools: toolRows.sort((left, right) => right.calls - left.calls || left.name.localeCompare(right.name)),
+        models: modelRows.sort((left, right) => right.calls - left.calls || left.model.localeCompare(right.model)),
+        days: [...days.values()].sort((left, right) => left.day.localeCompare(right.day)),
+        workspaces: [...workspaces.values()].sort((left, right) => right.calls - left.calls || left.workspace.localeCompare(right.workspace)),
+        errorCodes: [...errorCodes.entries()]
+            .map(([code, count]) => ({ code, calls: count }))
+            .sort((left, right) => right.calls - left.calls || left.code.localeCompare(right.code)),
+        recentCalls: recentCalls.sort((left, right) => left.time - right.time).slice(-recentLimit),
+        histogramScope: 'retained',
+    };
+}
+/** Project one detail recent call onto the client's flat vocabulary. */
+function recentProjection(entry, owner, sessionId, workspace) {
+    return {
+        time: entry.time,
+        name: entry.name,
+        owner,
+        model: entry.model,
+        ms: entry.ms,
+        ok: entry.ok,
+        errorCode: entry.code,
+        kind: entry.kind,
+        callId: entry.callId,
+        parentCallId: entry.parentCallId ?? null,
+        sessionId,
+        workspace,
+    };
+}
+//# sourceMappingURL=tool-usage-report.js.map

package/lib/transport.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Command transports: reaching a model that is not an in-process npm package.
+ *
+ * Two transports share one shape:
+ *
+ * - **cli** — runs the Desert Ant CLI (`desertant`/`da`), which exposes every
+ *   shipping model as `desertant <verb> … --json` and runs on macOS and Linux.
+ * - **remote** — POSTs to a bridge the user runs on a machine that can execute
+ *   the model. This is what makes an Apple-only model such as Title reachable
+ *   from a Windows host.
+ *
+ * Both are injected with their side-effecting primitive (`CommandRunner`,
+ * `HttpPost`) so behaviour is testable without spawning a process or opening a
+ * socket, and so a deployment can substitute its own runner.
+ *
+ * @module @try-works/dsh-tool-mode/transport
+ */
+import type { ModelCatalogEntry } from './types.ts';
+import { type JsonValue } from './adapters/types.ts';
+/** One invocation to route through a transport. */
+export interface TransportRequest {
+    /** The catalog entry being invoked. */
+    readonly entry: ModelCatalogEntry;
+    /** Validated tool arguments; the first declared parameter is the primary input. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Caller cancellation. */
+    readonly signal: AbortSignal;
+}
+/** Outcome of running one command. */
+export interface CommandOutcome {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Run a command to completion. Injectable so tests need no real process. */
+export type CommandRunner = (command: string, argv: readonly string[], signal: AbortSignal) => Promise<CommandOutcome>;
+/** Post a JSON body and read the response. Injectable for the same reason. */
+export type HttpPost = (url: string, body: unknown, headers: Readonly<Record<string, string>>, signal: AbortSignal) => Promise<{
+    readonly status: number;
+    readonly body: string;
+}>;
+/** A model invoked out-of-process. */
+export interface CommandTransport {
+    readonly kind: 'cli' | 'remote';
+    invoke(request: TransportRequest): Promise<Record<string, JsonValue>>;
+}
+/** The Desert Ant CLI's exit codes, as documented for agents. */
+export declare const CLI_EXIT_RUNTIME_ERROR = 1;
+export declare const CLI_EXIT_USAGE_ERROR = 64;
+/**
+ * Default command name. `da` is the short alias the CLI installs.
+ */
+export declare const DEFAULT_CLI_COMMAND = "desertant";
+/** The path every bridge must serve. */
+export declare const BRIDGE_PATH = "/invoke";
+/**
+ * Whether a command is on PATH.
+ *
+ * Probed by scanning PATH rather than by running the command, because this runs
+ * at plugin load and a capability probe must not start a process (or pay a
+ * CLI's startup cost) just to decide what to advertise.
+ * @param command - command name or an absolute path.
+ * @param pathValue - the PATH to search; defaults to the process environment.
+ * @returns whether an executable file of that name exists.
+ */
+export declare function commandExists(command: string, pathValue?: string): boolean;
+/**
+ * Split the tool arguments into the CLI's positional inputs and its
+ * `--option key=value` flags.
+ *
+ * The first declared catalog parameter is the primary input, matching how the
+ * registrar marks it required. A file model accepts several paths positionally
+ * (the CLI loads the model once for all of them), so a primary declared as a
+ * string list becomes several positionals. Everything else becomes an option,
+ * with lists comma-joined because the CLI's option syntax is `key=value`.
+ * @param entry - the catalog entry being invoked.
+ * @param args - validated tool arguments.
+ * @returns the positional inputs and the option list.
+ */
+export declare function splitArguments(entry: ModelCatalogEntry, args: Readonly<Record<string, unknown>>): {
+    positionals: string[];
+    options: [string, string][];
+};
+/**
+ * Build the CLI argv for one invocation.
+ *
+ * `--json` is what makes stdout a single JSON value, and it also implies
+ * `--no-color`, so no escape sequences have to be stripped.
+ * @param entry - the catalog entry being invoked.
+ * @param args - validated tool arguments.
+ * @returns the argv to run, after the command itself.
+ */
+export declare function buildArgv(entry: ModelCatalogEntry, args: Readonly<Record<string, unknown>>): string[];
+/**
+ * Parse the CLI's stdout into a canonical value.
+ *
+ * The CLI writes exactly one JSON value to stdout under `--json` and keeps every
+ * diagnostic on stderr, so a parse failure means the command did not behave as
+ * documented rather than that output needs cleaning.
+ * @param entry - the model, for error messages.
+ * @param outcome - the completed command.
+ * @returns the parsed value.
+ * @throws when the exit code is non-zero or stdout is not a single JSON value.
+ */
+export declare function parseCliOutcome(entry: ModelCatalogEntry, outcome: CommandOutcome): Record<string, JsonValue>;
+/** Spawn a command and capture its output. */
+export declare const spawnRunner: CommandRunner;
+/** POST JSON with the global fetch and read the response as text. */
+export declare const fetchPost: HttpPost;
+/** Options shared by both out-of-process transports. */
+export interface TransportOptions {
+    /** Command name or path for the CLI transport. */
+    readonly cliCommand?: string;
+    /** Bridge base URL for the remote transport. */
+    readonly endpoint?: string;
+    /** Optional bearer token sent to the bridge. */
+    readonly token?: string;
+    /** Injected command runner. */
+    readonly run?: CommandRunner;
+    /** Injected HTTP poster. */
+    readonly post?: HttpPost;
+}
+/**
+ * Build the CLI transport for one model.
+ * @param entry - the catalog entry, which must declare a CLI verb.
+ * @param options - command name and injected runner.
+ * @returns the transport.
+ */
+export declare function createCliTransport(entry: ModelCatalogEntry, options?: TransportOptions): CommandTransport;
+/**
+ * Build the remote transport for one model.
+ *
+ * The bridge contract is deliberately small so a user can implement it in a few
+ * lines on a machine that can run the model:
+ *
+ * ```
+ * POST <endpoint>/invoke
+ *   { "model": "title", "verb": "title", "input": "<primary>", "options": { "max-tokens": "96" } }
+ *   → 200 { "ok": true,  "result": <the model's JSON> }
+ *   → 4xx { "ok": false, "error": "<message>" }
+ * ```
+ * @param entry - the catalog entry to reach.
+ * @param options - endpoint, optional token, injected poster.
+ * @returns the transport.
+ */
+export declare function createRemoteTransport(entry: ModelCatalogEntry, options?: TransportOptions): CommandTransport;
+/**
+ * Interpret one bridge response.
+ * @param entry - the model, for error messages.
+ * @param response - the HTTP status and body.
+ * @returns the model's result as a canonical value.
+ * @throws when the bridge reports a failure or an unreadable body.
+ */
+export declare function parseBridgeResponse(entry: ModelCatalogEntry, response: {
+    readonly status: number;
+    readonly body: string;
+}): Record<string, JsonValue>;
+//# sourceMappingURL=transport.d.ts.map

package/lib/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}