@settlemint/dalp-cli 3.1.32-main.42194559254 → 3.1.32-main.42209626311

package/src/hosted-mcp.ts

@@ -0,0 +1,127 @@
+import { fromJsonSchema, type McpServer } from "@modelcontextprotocol/server";
+import type { DalpClient } from "@settlemint/dalp-sdk";
+import { Cli, Mcp, z } from "incur";
+import { listCliOperations, type OperationDescriptor } from "./lib/operation-inventory.ts";
+import { registerGeneratedOperations } from "./lib/register-operations.ts";
+import { CLI_VERSION, cliVars } from "./lib/vars.ts";
+
+export type { OperationDescriptor };
+
+export const HOSTED_MCP_VERSION: string = CLI_VERSION;
+
+export const HOSTED_EXECUTION_MODES: readonly ["inbox", "mandate"] = ["inbox", "mandate"];
+export type HostedExecutionMode = (typeof HOSTED_EXECUTION_MODES)[number];
+
+export const PREPARE_GROUP = "prepare";
+
+export interface PrepareToolField {
+  readonly description: string;
+  readonly required: boolean;
+  readonly options?: ReadonlyArray<string>;
+}
+
+export interface PrepareTool {
+  readonly name: string;
+  readonly description: string;
+  readonly fields: Readonly<Record<string, PrepareToolField>>;
+}
+
+export interface PrepareCall {
+  readonly tool: string;
+  readonly assetId: string;
+  readonly fields: Readonly<Record<string, string>>;
+  readonly execution: HostedExecutionMode;
+}
+
+export type PrepareOutcome =
+  | { readonly prepared: unknown }
+  | { readonly refused: { readonly code: string; readonly message: string } };
+
+export type PrepareExecutor = (call: PrepareCall) => Promise<PrepareOutcome>;
+
+export interface HostedMcpRequest {
+  readonly client: DalpClient;
+  readonly prepare: PrepareExecutor;
+}
+
+export interface HostedMcpTools {
+  readonly reads: ReadonlyArray<OperationDescriptor>;
+  readonly register: (server: McpServer, request: HostedMcpRequest) => void;
+}
+
+const hostedVars = cliVars.extend({ prepare: z.custom<PrepareExecutor>().optional() });
+
+const executionOption = z
+  .enum(HOSTED_EXECUTION_MODES)
+  .default("inbox")
+  .describe(
+    "inbox (default): post the prepared write to the member's DALP inbox, where a person reviews and signs it. mandate: execute as the organisation's agent principal, only inside its mandate."
+  );
+
+const fieldOption = (field: PrepareToolField) => {
+  const value = field.options === undefined ? z.string() : z.enum(field.options);
+  const described = value.describe(field.description);
+  return field.required ? described : described.optional();
+};
+
+type PrepareOptions = Readonly<Record<string, string | undefined>>;
+
+const prepareCommand = (tool: PrepareTool) => ({
+  description: tool.description,
+  mcp: { annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false } },
+  options: z.object({
+    assetId: z.string().describe("The asset the write acts on: its contract address."),
+    ...Object.fromEntries(Object.entries(tool.fields).map(([name, field]) => [name, fieldOption(field)])),
+    execution: executionOption,
+  }),
+  run: async (context: {
+    readonly options: PrepareOptions;
+    readonly var: { readonly prepare?: PrepareExecutor | undefined };
+    readonly error: (error: { readonly code: string; readonly message: string }) => unknown;
+  }) => {
+    const { assetId, execution, ...rest } = context.options;
+    if (context.var.prepare === undefined || typeof assetId !== "string") {
+      return context.error({ code: "PREPARE_UNAVAILABLE", message: "This server does not prepare writes." });
+    }
+    const fields = Object.fromEntries(
+      Object.entries(rest).flatMap(([name, value]) => (typeof value === "string" ? [[name, value]] : []))
+    );
+    const outcome = await context.var.prepare({
+      tool: tool.name,
+      assetId,
+      fields,
+      execution: execution === "mandate" ? "mandate" : "inbox",
+    });
+    return "refused" in outcome ? context.error(outcome.refused) : outcome.prepared;
+  },
+});
+
+export function makeHostedMcpTools(input: { readonly prepareTools: ReadonlyArray<PrepareTool> }): HostedMcpTools {
+  const reads = listCliOperations().filter((descriptor) => descriptor.method === "GET");
+  const cli = Cli.create("dalp", { version: CLI_VERSION, vars: hostedVars });
+  registerGeneratedOperations(cli, reads);
+  const prepare = Cli.create(PREPARE_GROUP, {
+    description: "Prepare a write for a person to review and sign in DALP.",
+    vars: hostedVars,
+  });
+  for (const tool of input.prepareTools) {
+    prepare.command(tool.name, prepareCommand(tool));
+  }
+  cli.command(prepare);
+  const registered: WeakMap<object, Map<string, unknown>> = Cli.toCommands;
+  const commands = registered.get(cli) ?? new Map<string, unknown>();
+  return {
+    reads,
+    register: (server, request) =>
+      Mcp.registerTools(server, commands, {
+        fromJsonSchema,
+        name: "dalp",
+        version: CLI_VERSION,
+        vars: hostedVars.extend({
+          client: z.custom<DalpClient>().default(() => request.client),
+          prepare: z.custom<PrepareExecutor>().default(() => request.prepare),
+        }),
+        sendNotification: (notification) => server.server.notification(notification),
+      }),
+  };
+}

package/src/lib/api-client.ts

@@ -0,0 +1,50 @@
+import { createDalpClient, type CompressionRequestInit, type DalpClient } from "@settlemint/dalp-sdk";
+import type { StoredCredentials } from "./credential-store.ts";
+import { CLI_USER_AGENT } from "./vars.ts";
+
+export interface CliGeneratedClientOptions {
+  readonly fetch?: typeof globalThis.fetch;
+  readonly organizationId?: string;
+}
+
+const withCliUserAgent = (fetchImpl: typeof globalThis.fetch): typeof globalThis.fetch =>
+  Object.assign(async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const request = new Request(input, init);
+    const headers = new Headers(request.headers);
+    headers.set("User-Agent", CLI_USER_AGENT);
+    const compress = (init as CompressionRequestInit | undefined)?.compress;
+    const transportInit: CompressionRequestInit | undefined = compress === undefined ? undefined : { compress };
+    return fetchImpl(new Request(request, { headers }), transportInit);
+  }, fetchImpl);
+
+export function resolveActiveOrganizationId(
+  credentials: StoredCredentials,
+  defaultOrg?: string,
+  override?: string
+): string | undefined {
+  if (override !== undefined && override.trim() !== "") {
+    return override;
+  }
+  if (credentials.activeOrgId !== undefined && credentials.activeOrgId.trim() !== "") {
+    return credentials.activeOrgId;
+  }
+  if (defaultOrg !== undefined && defaultOrg.trim() !== "") {
+    return defaultOrg;
+  }
+  return undefined;
+}
+
+export function makeCliClient(
+  apiUrl: string,
+  credentials: StoredCredentials,
+  options: CliGeneratedClientOptions & { readonly defaultOrg?: string } = {}
+): DalpClient {
+  const organizationId = resolveActiveOrganizationId(credentials, options.defaultOrg, options.organizationId);
+  return createDalpClient({
+    apiKey: credentials.apiKey,
+    baseUrl: apiUrl,
+    context: organizationId === undefined ? {} : { organizationId },
+    fetch: withCliUserAgent(options.fetch ?? globalThis.fetch),
+    runtime: "server",
+  });
+}

package/src/lib/auth-request.ts

@@ -0,0 +1,83 @@
+import { DalpApiError } from "@settlemint/dalp-sdk";
+import { z } from "incur";
+import type { StoredCredentials } from "./credential-store.ts";
+import { CLI_USER_AGENT } from "./vars.ts";
+
+const AUTH_REQUEST_TIMEOUT_MS = 10_000;
+
+export async function authRequest(
+  apiUrl: string,
+  credentials: StoredCredentials,
+  route: `/${string}`,
+  init?: { readonly method: "GET" | "POST"; readonly body?: unknown }
+): Promise<unknown> {
+  const request = init ?? { method: "GET" as const };
+  const headers = new Headers({ Accept: "application/json", "User-Agent": CLI_USER_AGENT });
+  if (credentials.apiKey !== undefined) {
+    headers.set("X-Api-Key", credentials.apiKey);
+  }
+  if (request.body !== undefined) {
+    headers.set("Content-Type", "application/json");
+  }
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(), AUTH_REQUEST_TIMEOUT_MS);
+  let response: Response;
+  let text: string;
+  try {
+    response = await fetch(`${apiUrl.replace(/\/+$/u, "")}/api/auth${route}`, {
+      method: request.method,
+      headers,
+      signal: deadline.signal,
+      ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+    });
+    text = await response.text();
+  } catch (error) {
+    if (!deadline.signal.aborted) {
+      throw error;
+    }
+    throw new DalpApiError({
+      message: `Auth request timed out: ${route}`,
+      code: "sdk.transport.REQUEST_FAILED",
+      category: "dependency",
+      retryable: true,
+      why: `The auth surface did not answer ${route} within ${String(AUTH_REQUEST_TIMEOUT_MS / 1000)} seconds.`,
+      fix: "Check that the platform URL is reachable, then retry.",
+      cause: error,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  const payload: unknown = text === "" ? undefined : JSON.parse(text);
+  if (!response.ok) {
+    throw new DalpApiError({
+      message: `Auth request failed: ${String(response.status)} ${route}`,
+      code: `sdk.transport.HTTP_${response.status}`,
+      category: "dependency",
+      retryable: response.status >= 500,
+      why: `The auth surface answered ${String(response.status)} for ${route}.`,
+      fix: "Check the API key and the platform URL, then retry.",
+      status: response.status,
+      cause: payload,
+    });
+  }
+  return payload;
+}
+
+export type KeyRevocation = { readonly _tag: "Revoked" } | { readonly _tag: "Unconfirmed"; readonly cause: unknown };
+
+const KeyDisabledAnswerSchema = z.object({ code: z.literal("KEY_DISABLED") });
+
+const keyNoLongerExists = (error: unknown): boolean =>
+  error instanceof DalpApiError && error.status === 401 && !KeyDisabledAnswerSchema.safeParse(error.cause).success;
+
+export async function revokeOwnApiKey(credentials: StoredCredentials): Promise<KeyRevocation> {
+  try {
+    await authRequest(credentials.apiUrl, credentials, "/api-key/delete", {
+      method: "POST",
+      body: { keyId: credentials.apiKeyId },
+    });
+    return { _tag: "Revoked" };
+  } catch (error) {
+    return keyNoLongerExists(error) ? { _tag: "Revoked" } : { _tag: "Unconfirmed", cause: error };
+  }
+}

package/src/lib/cli-config.ts

@@ -0,0 +1,104 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { makeCliError } from "./errors.ts";
+
+const PROJECT_CONFIG_FILE = ".dalprc.json";
+
+const DalpConfigSchema = z.object({
+  apiUrl: z.string().optional(),
+  defaultOrg: z.string().optional(),
+  format: z.enum(["toon", "json", "yaml", "md"]).optional(),
+});
+
+export type DalpConfig = z.infer<typeof DalpConfigSchema>;
+
+export function getConfigDir(): string {
+  const override = process.env.DALP_CONFIG_DIR;
+  if (override !== undefined && override.trim() !== "") {
+    return override;
+  }
+  return path.join(homedir(), ".config", "dalp");
+}
+
+export interface CliConfigPaths {
+  readonly configDir?: string;
+  readonly cwd?: string;
+  readonly environment?: () => DalpConfig;
+}
+
+const defaultEnvironment = (): DalpConfig => ({
+  ...(process.env.DALP_URL === undefined || process.env.DALP_URL === "" ? {} : { apiUrl: process.env.DALP_URL }),
+  ...(process.env.DALP_ORG === undefined || process.env.DALP_ORG === "" ? {} : { defaultOrg: process.env.DALP_ORG }),
+});
+
+const mergeConfig = (
+  globalConfig: DalpConfig,
+  projectConfig: DalpConfig,
+  environmentConfig: DalpConfig,
+  overrides: Partial<DalpConfig>
+): DalpConfig => ({
+  ...globalConfig,
+  ...projectConfig,
+  ...environmentConfig,
+  ...Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined)),
+});
+
+async function readConfigFile(file: string): Promise<DalpConfig> {
+  try {
+    const raw = await readFile(file, "utf8");
+    return DalpConfigSchema.parse(JSON.parse(raw));
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return {};
+    }
+    if (error instanceof z.ZodError) {
+      throw makeCliError({
+        code: "kit.cli.CONFIG_INVALID",
+        message: `Invalid config at ${file}: ${error.message}`,
+        why: "The configuration file does not match the expected schema.",
+        fix: `Edit ${file} or delete it and re-run 'dalp config set'.`,
+        cause: error,
+      });
+    }
+    throw makeCliError({
+      code: "kit.cli.CONFIG_READ_FAILED",
+      message: error instanceof Error ? error.message : "Failed to read CLI configuration",
+      cause: error,
+    });
+  }
+}
+
+async function ensureConfigDir(configDir: string = getConfigDir()): Promise<void> {
+  await mkdir(configDir, { recursive: true, mode: 0o700 });
+}
+
+export async function loadGlobalConfig(configDir: string = getConfigDir()): Promise<DalpConfig> {
+  return readConfigFile(path.join(configDir, "config.json"));
+}
+
+async function loadProjectConfig(cwd: string = process.cwd()): Promise<DalpConfig> {
+  return readConfigFile(path.join(cwd, PROJECT_CONFIG_FILE));
+}
+
+export async function resolveConfig(
+  overrides: Partial<DalpConfig> = {},
+  paths: CliConfigPaths = {}
+): Promise<DalpConfig> {
+  const configDir = paths.configDir ?? getConfigDir();
+  const cwd = paths.cwd ?? process.cwd();
+  const environment = paths.environment ?? defaultEnvironment;
+  const [globalConfig, projectConfig] = await Promise.all([loadGlobalConfig(configDir), loadProjectConfig(cwd)]);
+  return mergeConfig(globalConfig, projectConfig, environment(), overrides);
+}
+
+export async function saveGlobalConfig(
+  updates: Partial<DalpConfig>,
+  configDir: string = getConfigDir()
+): Promise<void> {
+  await ensureConfigDir(configDir);
+  const existing = await loadGlobalConfig(configDir);
+  const next = DalpConfigSchema.parse({ ...existing, ...updates });
+  await writeFile(path.join(configDir, "config.json"), `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+}

package/src/lib/cli-cta.ts

@@ -0,0 +1,231 @@
+import { z } from "incur";
+import { commandPathForUrl } from "@settlemint/dalp-sdk/routes";
+
+export interface CliCtaCommandObject {
+  readonly command: string;
+  readonly description?: string;
+  readonly args?: Readonly<Record<string, string | number | boolean>>;
+  readonly options?: Readonly<Record<string, string | number | boolean>>;
+}
+
+export type CliCtaCommand = string | CliCtaCommandObject;
+
+export interface CliCtaBlock {
+  readonly description: string;
+  readonly commands: Array<CliCtaCommand>;
+}
+
+export type ResourceLinks = Readonly<Record<string, string | null | undefined>>;
+
+const LINK_REL_ORDER = ["next", "prev", "first", "last", "self", "history"] as const;
+
+const REL_DESCRIPTION: Readonly<Record<string, string>> = {
+  next: "Fetch the next page",
+  prev: "Fetch the previous page",
+  first: "Fetch the first page",
+  last: "Fetch the last page",
+  self: "Re-fetch this resource",
+  history: "Fetch related history",
+};
+
+const jsonBagSchema = z.record(z.string(), z.json());
+
+export type JsonBag = z.output<typeof jsonBagSchema>;
+
+const isJsonBag = (value: unknown): value is JsonBag => jsonBagSchema.safeParse(value).success;
+
+export function extractResourceLinks(value: unknown): ResourceLinks | undefined {
+  if (!isJsonBag(value)) {
+    return undefined;
+  }
+  const { links: direct, data } = value;
+  if (isJsonBag(direct)) {
+    return linksFromRecord(direct);
+  }
+  if (isJsonBag(data)) {
+    const { links: nested } = data;
+    if (isJsonBag(nested)) {
+      return linksFromRecord(nested);
+    }
+  }
+  return undefined;
+}
+
+function linksFromRecord(record: JsonBag): ResourceLinks | undefined {
+  const out: Record<string, string | null> = {};
+  let any = false;
+  for (const [key, entry] of Object.entries(record)) {
+    if (entry === null) {
+      out[key] = null;
+      any = true;
+      continue;
+    }
+    if (typeof entry === "string" && entry.trim() !== "") {
+      out[key] = entry;
+      any = true;
+    }
+  }
+  return any ? out : undefined;
+}
+
+function parseHref(href: string): { pathname: string; searchParams: URLSearchParams } | undefined {
+  try {
+    const url =
+      href.startsWith("http://") || href.startsWith("https://") ? new URL(href) : new URL(href, "https://dalp.local");
+    return { pathname: url.pathname, searchParams: url.searchParams };
+  } catch {
+    return undefined;
+  }
+}
+
+export function mapApiHrefToCliCommand(
+  href: string,
+  method = "GET"
+): { readonly command: string; readonly options?: Readonly<Record<string, string>> } | undefined {
+  const parsed = parseHref(href);
+  if (parsed === undefined) {
+    return undefined;
+  }
+  const { pathname, searchParams } = parsed;
+  if (!(pathname.includes("/api/v2/") || pathname.startsWith("/api/"))) {
+    return undefined;
+  }
+  const path = commandPathForUrl(method, pathname);
+  if (path.length === 0) {
+    return undefined;
+  }
+  const options: Record<string, string> = {};
+  for (const [key, value] of searchParams.entries()) {
+    const optionKey = key.includes("[") ? key : key;
+    options[optionKey] = value;
+  }
+  return {
+    command: path.join(" "),
+    ...(Object.keys(options).length > 0 ? { options } : {}),
+  };
+}
+
+export function commandsFromLinks(links: ResourceLinks | undefined): Array<CliCtaCommandObject> {
+  if (links === undefined) {
+    return [];
+  }
+  const orderedKeys = [
+    ...LINK_REL_ORDER.filter((rel) => rel in links),
+    ...Object.keys(links)
+      .filter((key) => !(LINK_REL_ORDER as ReadonlyArray<string>).includes(key))
+      .sort((left, right) => left.localeCompare(right)),
+  ];
+  const commands: Array<CliCtaCommandObject> = [];
+  const seen = new Set<string>();
+  for (const rel of orderedKeys) {
+    const href = links[rel];
+    if (href === null || href === undefined || href === "") {
+      continue;
+    }
+    const mapped = mapApiHrefToCliCommand(href);
+    if (mapped === undefined) {
+      continue;
+    }
+    const signature = `${mapped.command}|${JSON.stringify(mapped.options ?? {})}`;
+    if (seen.has(signature)) {
+      continue;
+    }
+    seen.add(signature);
+    commands.push({
+      command: mapped.command,
+      ...(mapped.options === undefined ? {} : { options: mapped.options }),
+      description: REL_DESCRIPTION[rel] ?? `Follow ${rel} link`,
+    });
+  }
+  return commands;
+}
+
+function commandsFromErrorHints(input: {
+  readonly code?: string;
+  readonly category?: string;
+  readonly fix: string;
+}): Array<CliCtaCommandObject> {
+  const code = (input.code ?? "").toUpperCase();
+  const category = (input.category ?? "").toLowerCase();
+  const fix = input.fix.toLowerCase();
+  const commands: Array<CliCtaCommandObject> = [];
+
+  const auth =
+    category === "auth" ||
+    code.includes("AUTH") ||
+    code.includes("NOT_AUTHENTICATED") ||
+    code.includes("UNAUTHORIZED") ||
+    fix.includes("authenticate") ||
+    fix.includes("log in") ||
+    fix.includes("sign in") ||
+    fix.includes("api key");
+  if (auth) {
+    commands.push({ command: "login", description: "Authenticate with device authorization" });
+  }
+
+  const org =
+    category === "permission" ||
+    code.includes("ORGANIZATION") ||
+    code.includes("ACTIVE_ORG") ||
+    fix.includes("organization") ||
+    fix.includes("org ");
+  if (org) {
+    commands.push({ command: "org switch", description: "Save the key's organization as active" });
+    commands.push({ command: "whoami", description: "Show current user and organization" });
+  }
+
+  if (commands.length === 0 && (category === "client" || category === "config")) {
+    commands.push({ command: "whoami", description: "Check the active session" });
+    commands.push({ command: "config get", description: "Inspect local CLI configuration" });
+  }
+
+  return commands;
+}
+
+function dedupeCommands(commands: ReadonlyArray<CliCtaCommand>): Array<CliCtaCommand> {
+  const seen = new Set<string>();
+  const out: Array<CliCtaCommand> = [];
+  for (const command of commands) {
+    const key =
+      typeof command === "string"
+        ? command
+        : `${command.command}|${JSON.stringify(command.args ?? {})}|${JSON.stringify(command.options ?? {})}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    out.push(command);
+  }
+  return out;
+}
+
+export function buildErrorCta(input: {
+  readonly why: string;
+  readonly fix: string;
+  readonly code?: string;
+  readonly category?: string;
+  readonly links?: ResourceLinks;
+}): CliCtaBlock {
+  const fromLinks = commandsFromLinks(input.links);
+  const fromHints = commandsFromErrorHints(input);
+  let commands = dedupeCommands([...fromLinks, ...fromHints]);
+  if (commands.length === 0) {
+    commands = [{ command: "whoami", description: input.fix }];
+  }
+  return {
+    description: `Why: ${input.why}\nFix: ${input.fix}`,
+    commands,
+  };
+}
+
+export function buildSuccessCtaFromResult(result: unknown): CliCtaBlock | undefined {
+  const links = extractResourceLinks(result);
+  const commands = commandsFromLinks(links);
+  if (commands.length === 0) {
+    return undefined;
+  }
+  return {
+    description: commands.length === 1 ? "Related:" : "Related:",
+    commands,
+  };
+}

package/src/lib/cli-status.ts

@@ -0,0 +1,102 @@
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+export interface StatusEvent {
+  readonly phase: string;
+  readonly message: string;
+}
+
+export interface CliStatusReporter {
+  readonly update: (event: StatusEvent) => StatusEvent | undefined;
+  readonly succeed: (message: string) => StatusEvent | undefined;
+  readonly fail: (message: string) => StatusEvent | undefined;
+  readonly stop: () => void;
+}
+
+export interface CreateCliStatusOptions {
+  readonly agent: boolean;
+  readonly stream?: { write: (chunk: string) => unknown; isTTY?: boolean };
+  readonly isTty?: boolean;
+}
+
+export function createCliStatus(options: CreateCliStatusOptions): CliStatusReporter {
+  const stream = options.stream ?? process.stderr;
+  const isTty = options.isTty ?? Boolean("isTTY" in stream && stream.isTTY);
+  const human = options.agent !== true;
+  let frame = 0;
+  let currentMessage = "";
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let spinning = false;
+
+  const clearLine = (): void => {
+    if (human && isTty) {
+      stream.write("\r\u001B[K");
+    }
+  };
+
+  const paint = (): void => {
+    if (!human || !isTty || !spinning) {
+      return;
+    }
+    const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length]!;
+    stream.write(`\r\u001B[K${glyph} ${currentMessage}`);
+    frame += 1;
+  };
+
+  const startSpinner = (): void => {
+    if (!human || !isTty || spinning) {
+      return;
+    }
+    spinning = true;
+    timer = setInterval(paint, 80);
+    paint();
+  };
+
+  const stopSpinner = (): void => {
+    if (timer !== undefined) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+    if (spinning) {
+      clearLine();
+      spinning = false;
+    }
+  };
+
+  const emitHuman = (prefix: string, message: string): void => {
+    stopSpinner();
+    if (!human) {
+      return;
+    }
+    if (isTty) {
+      stream.write(`${prefix} ${message}\n`);
+    } else {
+      stream.write(`${message}\n`);
+    }
+  };
+
+  return {
+    update(event) {
+      currentMessage = event.message;
+      if (!options.agent) {
+        if (isTty) {
+          startSpinner();
+          paint();
+        } else {
+          stream.write(`${event.message}\n`);
+        }
+      }
+      return options.agent ? event : undefined;
+    },
+    succeed(message) {
+      emitHuman("✔", message);
+      return options.agent ? { phase: "done", message } : undefined;
+    },
+    fail(message) {
+      emitHuman("✖", message);
+      return options.agent ? { phase: "error", message } : undefined;
+    },
+    stop() {
+      stopSpinner();
+    },
+  };
+}