@zachwill/pi-orchestrate 0.8.0 → 0.9.0

package/extension/tools.ts

@@ -20,13 +20,15 @@ import {
   keyHint,
   truncateHead,
 } from "@earendil-works/pi-coding-agent";
+import { Result, Schema } from "effect";
 import { Type } from "typebox";
 import {
+  MAX_WORKER_INSTRUCTIONS_LENGTH,
+  MAX_WORKER_TITLE_LENGTH,
   type CatalogDiagnostic,
   type RunRecord,
   type WorkerCatalog,
   type WorkerDefinition,
-  type WorkerId,
   type WorkerOutcome,
   type WorkerRecord,
   type WorkerUsage,
@@ -36,33 +38,68 @@ import type {
   AcceptedRun,
   CompletedRun,
   OrchestrationContext,
-  OrchestratorRuntime,
   RunResult,
   RuntimeSnapshot,
   SettlementListener,
-  WorkerSettlement,
 } from "./runtime.js";
+import type { OrchestratorRuntime } from "./host.js";
+import {
+  disposeComponent,
+  formatElapsed,
+  resultAppearance,
+  WidthBoundComponent,
+} from "./tui.js";
+import {
+  decodeInlineWorkerToolDetails,
+  encodeInlineWorkerToolDetails,
+  type InlineWorkerSettlementDetails,
+  WorkerSettlementDetails,
+  type WorkerSettlement,
+} from "./worker-settlement.js";
 
 const STRICT_OBJECT = { additionalProperties: false } as const;
 const MAX_INSTRUCTION_PREVIEW_LINES = 2;
+const shortTextSchema = Type.String({
+  pattern: "\\S",
+  maxLength: MAX_WORKER_TITLE_LENGTH,
+});
+const instructionsSchema = Type.String({
+  pattern: "\\S",
+  maxLength: MAX_WORKER_INSTRUCTIONS_LENGTH,
+});
+const workerIdSchema = Type.String({ pattern: "^worker-\\S+$" });
+
+const AcceptedRunRenderDetails = Schema.Struct({
+  mode: Schema.Literal("async"),
+  run_id: WorkerSettlementDetails.fields.runId,
+  worker_id: WorkerSettlementDetails.fields.workerId,
+});
+const UnavailableWorkerRenderDetails = Schema.Union([
+  Schema.Struct({ result: Schema.Unknown }),
+  Schema.Struct({ worker_id: Schema.Unknown }),
+]);
+const decodeAcceptedRunRenderDetails = Schema.decodeUnknownResult(
+  AcceptedRunRenderDetails,
+);
+const decodeUnavailableWorkerRenderDetails = Schema.decodeUnknownResult(
+  UnavailableWorkerRenderDetails,
+);
 
 const taskSchema = Type.Object(
   {
-    worker: Type.String(),
-    title: Type.String(),
-    instructions: Type.String(),
+    worker: shortTextSchema,
+    title: shortTextSchema,
+    instructions: instructionsSchema,
   },
   STRICT_OBJECT,
 );
 
-const orchestrateSchema = taskSchema;
-
 const statusSchema = Type.Object({}, STRICT_OBJECT);
 
 const interactiveSendSchema = Type.Object(
   {
-    worker_id: Type.String({ minLength: 1 }),
-    instructions: Type.String(),
+    worker_id: workerIdSchema,
+    instructions: instructionsSchema,
   },
   STRICT_OBJECT,
 );
@@ -70,7 +107,7 @@ const interactiveSendSchema = Type.Object(
 const workerAbortSchema = Type.Union([
   Type.Object(
     {
-      worker_ids: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+      worker_ids: Type.Array(workerIdSchema, { minItems: 1 }),
     },
     STRICT_OBJECT,
   ),
@@ -84,7 +121,7 @@ const workerAbortSchema = Type.Union([
 
 const interactiveCloseSchema = Type.Object(
   {
-    worker_id: Type.String({ minLength: 1 }),
+    worker_id: workerIdSchema,
   },
   STRICT_OBJECT,
 );
@@ -99,7 +136,7 @@ export interface DispatchDecision {
 
 export interface OrchestrationToolDependencies {
   readonly runtime: OrchestratorRuntime;
-  getCatalog(ctx: ExtensionContext): WorkerCatalog | Promise<WorkerCatalog>;
+  getCatalog(ctx: ExtensionContext): WorkerCatalog;
   getDispatchDecision(toolCallId: string): DispatchDecision;
 }
 
@@ -120,7 +157,7 @@ export function registerOrchestrationTools(
       "Form all N calls before emitting or finalizing the response. Never emit one call and wait for its result before forming the rest of the wave: a successfully admitted sole async orchestrate call returns terminate=true and ends the turn.",
     ],
     executionMode: "parallel",
-    parameters: orchestrateSchema,
+    parameters: taskSchema,
     renderCall(args, theme, { expanded }) {
       return renderDispatchCall(theme, args, expanded);
     },
@@ -130,7 +167,7 @@ export function registerOrchestrationTools(
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       const decision = deps.getDispatchDecision(toolCallId);
       const mode = decision.mode;
-      const runtimeContext = await buildRuntimeContext(ctx, deps, decision.synthesisGroup);
+      const runtimeContext = buildRuntimeContext(ctx, deps, decision.synthesisGroup);
       if (mode === "async") {
         const acceptedRun = await deps.runtime.orchestrate(
           runtimeContext,
@@ -140,13 +177,7 @@ export function registerOrchestrationTools(
         );
         const readable = acceptedRunDetails(acceptedRun);
         return {
-          content: [
-            {
-              type: "text",
-              text: readableDetails(`Accepted async run ${readable.run_id}.`, readable),
-            },
-          ],
-          details: readable,
+          ...readableToolResult(`Accepted async run ${readable.run_id}.`, readable),
           terminate: true,
         };
       }
@@ -159,18 +190,10 @@ export function registerOrchestrationTools(
         createInlineSettlementListener(onUpdate),
       );
       const readable = completedRunDetails(completedRun);
-      return {
-        content: [
-          {
-            type: "text",
-            text: readableDetails(
-              `Completed inline run ${readable.run_id}.`,
-              readable,
-            ),
-          },
-        ],
-        details: readable,
-      };
+      return readableToolResult(
+        `Completed inline run ${readable.run_id}.`,
+        readable,
+      );
     },
   });
 
@@ -191,24 +214,14 @@ export function registerOrchestrationTools(
       return renderDiagnosticsResult(result, isPartial, theme);
     },
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-      const ownerSessionId = requireNonblank(
-        "owner session ID",
-        ctx.sessionManager.getSessionId(),
-      );
-      const [catalog, snapshot] = await Promise.all([
-        deps.getCatalog(ctx),
-        deps.runtime.snapshot(ownerSessionId),
-      ]);
+      const ownerSessionId = ctx.sessionManager.getSessionId();
+      const catalog = deps.getCatalog(ctx);
+      const snapshot = await deps.runtime.snapshot(ownerSessionId);
       const readable = statusDetails(catalog, snapshot);
-      return {
-        content: [
-          {
-            type: "text",
-            text: readableDetails("Worker diagnostics and recovery snapshot.", readable),
-          },
-        ],
-        details: readable,
-      };
+      return readableToolResult(
+        "Worker diagnostics and recovery snapshot.",
+        readable,
+      );
     },
   });
 
@@ -229,9 +242,9 @@ export function registerOrchestrationTools(
       return renderOrchestrationResult(result, isPartial, expanded, theme, context.lastComponent);
     },
     async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const workerId = asWorkerId(params.worker_id);
+      const workerId = params.worker_id;
       const mode = deps.getDispatchDecision(toolCallId).mode;
-      const runtimeContext = await buildRuntimeContext(ctx, deps);
+      const runtimeContext = buildRuntimeContext(ctx, deps);
       if (mode === "async") {
         const acceptedRun = await deps.runtime.sendInteractive(
           runtimeContext,
@@ -242,13 +255,7 @@ export function registerOrchestrationTools(
         );
         const readable = acceptedRunDetails(acceptedRun);
         return {
-          content: [
-            {
-              type: "text",
-              text: readableDetails(`Accepted async run ${readable.run_id}.`, readable),
-            },
-          ],
-          details: readable,
+          ...readableToolResult(`Accepted async run ${readable.run_id}.`, readable),
           terminate: true,
         };
       }
@@ -262,18 +269,10 @@ export function registerOrchestrationTools(
         createInlineSettlementListener(onUpdate),
       );
       const readable = completedRunDetails(completedRun);
-      return {
-        content: [
-          {
-            type: "text",
-            text: readableDetails(
-              `Completed inline run ${readable.run_id}.`,
-              readable,
-            ),
-          },
-        ],
-        details: readable,
-      };
+      return readableToolResult(
+        `Completed inline run ${readable.run_id}.`,
+        readable,
+      );
     },
   });
 
@@ -297,22 +296,15 @@ export function registerOrchestrationTools(
       return renderSimpleResult(result, isPartial ? "Requesting worker stop…" : "Worker stop requested", theme, "warning");
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const ownerSessionId = requireNonblank(
-        "owner session ID",
-        ctx.sessionManager.getSessionId(),
-      );
-      const target = abortTarget(params);
-      await deps.runtime.abort(ownerSessionId, target.runtime);
-      const readable = { target: target.external };
-      return {
-        content: [
-          {
-            type: "text",
-            text: readableDetails("Abort request completed.", readable),
-          },
-        ],
-        details: { target: target.external },
+      const ownerSessionId = ctx.sessionManager.getSessionId();
+      const target = normalizeAbortTarget(params);
+      await deps.runtime.abort(ownerSessionId, target);
+      const readable = {
+        target: "worker_ids" in params
+          ? { worker_ids: params.worker_ids }
+          : { all: params.all },
       };
+      return readableToolResult("Abort request completed.", readable);
     },
   });
 
@@ -332,41 +324,27 @@ export function registerOrchestrationTools(
       return renderSimpleResult(result, isPartial ? "Closing worker…" : "✓ Worker closed", theme);
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const ownerSessionId = requireNonblank(
-        "owner session ID",
-        ctx.sessionManager.getSessionId(),
-      );
-      const workerId = asWorkerId(params.worker_id);
+      const ownerSessionId = ctx.sessionManager.getSessionId();
+      const workerId = params.worker_id;
       await deps.runtime.closeInteractive(ownerSessionId, workerId);
       const readable = { worker_id: workerId };
-      return {
-        content: [
-          {
-            type: "text",
-            text: readableDetails(`Closed worker ${workerId}.`, readable),
-          },
-        ],
-        details: readable,
-      };
+      return readableToolResult(`Closed worker ${workerId}.`, readable);
     },
   });
 }
 
-async function buildRuntimeContext(
+function buildRuntimeContext(
   ctx: ExtensionContext,
   deps: OrchestrationToolDependencies,
   synthesisGroup?: DispatchDecision["synthesisGroup"],
-): Promise<OrchestrationContext> {
+): OrchestrationContext {
   return {
-    ownerSessionId: requireNonblank(
-      "owner session ID",
-      ctx.sessionManager.getSessionId(),
-    ),
+    ownerSessionId: ctx.sessionManager.getSessionId(),
     cwd: ctx.cwd,
     agentDir: getAgentDir(),
     parentSessionFile: ctx.sessionManager.getSessionFile(),
     projectTrusted: ctx.isProjectTrusted(),
-    catalog: await deps.getCatalog(ctx),
+    catalog: deps.getCatalog(ctx),
     parentModel: ctx.model,
     modelRegistry: ctx.modelRegistry,
     ...(synthesisGroup ? { synthesisGroup } : {}),
@@ -379,53 +357,21 @@ function createInlineSettlementListener(
   return (settlement) => {
     onUpdate?.({
       content: [{ type: "text", text: "Worker response received." }],
-      details: {
+      details: encodeInlineWorkerToolDetails({
         mode: "inline",
-        result: inlineResultDetails(settlement),
-      },
+        result: inlineResultValue(settlement),
+      }),
     });
   };
 }
 
-function requireNonblank(name: string, value: string): string {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`${name} must not be blank`);
-  }
-  return value;
-}
-
-function asWorkerId(value: string): WorkerId {
-  return requireNonblank("worker_id", value) as WorkerId;
-}
-
-function abortTarget(params: {
+function normalizeAbortTarget(params: {
   worker_ids?: string[];
-  all?: true;
-}): {
-  runtime: AbortTarget;
-  external: { worker_ids: readonly WorkerId[] } | { all: true };
-} {
-  const selectedTargetCount = [
-    params.worker_ids !== undefined,
-    params.all !== undefined,
-  ].filter(Boolean).length;
-  if (selectedTargetCount !== 1 || (params.all !== undefined && params.all !== true)) {
-    throw new Error("Abort target must specify exactly one target");
-  }
-
-  if (params.worker_ids !== undefined) {
-    if (!Array.isArray(params.worker_ids) || params.worker_ids.length === 0) {
-      throw new Error("worker_ids must contain at least one worker ID");
-    }
-    const workerIds = params.worker_ids.map(asWorkerId);
-    return {
-      runtime: { workerIds },
-      external: { worker_ids: workerIds },
-    };
-  }
+  all?: boolean;
+}): AbortTarget {
   return {
-    runtime: { all: true },
-    external: { all: true },
+    ...(params.worker_ids !== undefined ? { workerIds: params.worker_ids } : {}),
+    ...(params.all !== undefined ? { all: params.all } : {}),
   };
 }
 
@@ -438,39 +384,29 @@ function acceptedRunDetails(run: AcceptedRun) {
 }
 
 function completedRunDetails(run: CompletedRun) {
-  return {
-    mode: run.mode,
-    run_id: run.id,
-    owner_session_id: run.ownerSessionId,
-    result: completedResultDetails(run.result),
-  };
+  return encodeInlineWorkerToolDetails({
+    mode: "inline",
+    runId: run.id,
+    ownerSessionId: run.ownerSessionId,
+    result: inlineResultValue(run.result),
+  });
 }
 
-function completedResultDetails(result: RunResult) {
+function inlineResultValue(
+  result: RunResult | WorkerSettlement,
+): InlineWorkerSettlementDetails {
   return {
-    worker_id: result.workerId,
+    workerId: result.workerId,
     worker: result.worker,
     title: result.title,
     status: result.status,
-    outcome: outcomeDetails(result.outcome),
-    usage: usageDetails(result.usage),
-    started_at: result.startedAt,
-    settled_at: result.settledAt,
-    session_file: result.sessionFile,
-  };
-}
-
-function inlineResultDetails(settlement: WorkerSettlement) {
-  return {
-    worker_id: settlement.workerId,
-    worker: settlement.worker,
-    title: settlement.title,
-    status: settlement.status,
-    outcome: outcomeDetails(settlement.outcome),
-    usage: usageDetails(settlement.usage),
-    started_at: settlement.startedAt,
-    settled_at: settlement.settledAt,
-    session_file: settlement.sessionFile,
+    outcome: result.outcome,
+    usage: result.usage,
+    startedAt: result.startedAt,
+    settledAt: result.settledAt,
+    ...(result.sessionFile === undefined
+      ? {}
+      : { sessionFile: result.sessionFile }),
   };
 }
 
@@ -580,6 +516,13 @@ function outcomeDetails(outcome: WorkerOutcome) {
   }
 }
 
+function readableToolResult<T>(title: string, details: T) {
+  return {
+    content: [{ type: "text" as const, text: readableDetails(title, details) }],
+    details,
+  };
+}
+
 function readableDetails(title: string, details: unknown): string {
   const content = `${title}\n\n${JSON.stringify(details, null, 2)}`;
   const truncation = truncateHead(content);
@@ -659,18 +602,6 @@ function renderInteractiveMessageCall(
   return new WidthBoundComponent(container);
 }
 
-class WidthBoundComponent implements Component {
-  constructor(private readonly child: Component, private readonly maxLines?: number) {}
-  render(width: number): string[] {
-    const bounded = Math.max(1, Math.floor(width));
-    const lines = this.child.render(bounded);
-    return (this.maxLines === undefined ? lines : lines.slice(0, this.maxLines))
-      .map((line) => truncateToWidth(line, bounded, "…"));
-  }
-  invalidate(): void { this.child.invalidate(); }
-  dispose(): void { (this.child as Component & { dispose?: () => void }).dispose?.(); }
-}
-
 function safeTerminalText(value: unknown): string {
   const text = typeof value === "string" ? value : value == null ? "" : String(value);
   return text.replace(/\r\n?/g, "\n").replace(/\t/g, "    ").replace(/[\x00-\x08\x0B-\x1F\x7F]/g, (character) => {
@@ -714,7 +645,7 @@ function renderOrchestrationResult(
   lastComponent: unknown,
 ): Component {
   const details = result.details;
-  if (isRecord(details) && typeof details.run_id === "string" && typeof details.worker_id === "string" && details.mode === "async") {
+  if (Result.isSuccess(decodeAcceptedRunRenderDetails(details))) {
     return new WidthBoundComponent(new Text(theme.fg("success", "Sent to worker") + theme.fg("dim", " · response arrives when complete"), 0, 0));
   }
   const inlineResult = readInlineResult(details);
@@ -725,28 +656,28 @@ function renderOrchestrationResult(
     component.update(inlineResult, isPartial, expanded);
     return component;
   }
-  if (isRecord(details) && ("result" in details || "worker_id" in details)) {
+  if (Result.isSuccess(decodeUnavailableWorkerRenderDetails(details))) {
     return new WidthBoundComponent(new Text(theme.fg("warning", "Worker result details unavailable"), 0, 0));
   }
   if (isPartial) return new WidthBoundComponent(new Text(theme.fg("warning", "Sending work…"), 0, 0));
   return new WidthBoundComponent(renderSimpleResult(result, firstResultLine(result) || "Work sent", theme, "warning"));
 }
 
-interface InlineSettlement {
+interface RenderedInlineSettlement {
   worker: string;
   title: string;
-  status: "completed" | "ready" | "failed" | "aborted";
+  status: InlineWorkerSettlementDetails["status"];
   response: string;
   elapsed?: string;
 }
 
 class InlineResultComponent implements Component {
-  private result: InlineSettlement | undefined;
+  private result: RenderedInlineSettlement | undefined;
   private partial = false;
   private expanded = false;
   private child: Component = new Container();
   constructor(private readonly theme: Theme) {}
-  update(result: InlineSettlement, partial: boolean, expanded: boolean): void {
+  update(result: RenderedInlineSettlement, partial: boolean, expanded: boolean): void {
     this.result = result;
     this.partial = partial;
     this.expanded = expanded;
@@ -754,16 +685,16 @@ class InlineResultComponent implements Component {
   }
   render(width: number): string[] { return new WidthBoundComponent(this.child).render(width); }
   invalidate(): void { this.rebuild(); }
-  dispose(): void { (this.child as Component & { dispose?: () => void }).dispose?.(); }
+  dispose(): void { disposeComponent(this.child); }
   private rebuild(): void {
-    (this.child as Component & { dispose?: () => void }).dispose?.();
+    disposeComponent(this.child);
     const container = new Container();
     const result = this.result;
     if (!result) {
       this.child = container;
       return;
     }
-    const appearance = inlineResultAppearance(result.status);
+    const appearance = resultAppearance(result.status, "ready for follow-up");
     const suffix = [appearance.qualifier, result.elapsed].filter(Boolean).join(" · ");
     const title = this.theme.bold(result.title);
     const workerName = this.theme.fg("muted", this.theme.italic(result.worker));
@@ -784,58 +715,27 @@ class InlineResultComponent implements Component {
   }
 }
 
-function readInlineResult(details: unknown): InlineSettlement | undefined {
-  if (!isRecord(details)) return undefined;
-  return readInlineSettlement(details.result);
-}
-
-function readInlineSettlement(value: unknown): InlineSettlement | undefined {
-  if (!isRecord(value) || typeof value.worker !== "string" || typeof value.title !== "string" || !isRecord(value.outcome)) return undefined;
-  const outcome = value.outcome;
-  const statuses = ["completed", "ready", "failed", "aborted"] as const;
-  const status = statuses.find((item) => item === value.status);
-  const outcomeStatus = statuses.find((item) => item === outcome.status);
-  if (!status || outcomeStatus !== status) return undefined;
-  const message = outcome.message;
-  const assistantText = outcome.assistant_text;
-  if (message !== undefined && typeof message !== "string") return undefined;
-  if (assistantText !== undefined && typeof assistantText !== "string") return undefined;
-  if ((status === "completed" || status === "ready") && typeof assistantText !== "string") return undefined;
-  if (status === "failed" && typeof message !== "string") return undefined;
-  const startedAt = value.started_at;
-  const settledAt = value.settled_at;
-  const elapsed = typeof startedAt === "number" && typeof settledAt === "number" && settledAt >= startedAt
-    ? formatElapsed(settledAt - startedAt)
+function readInlineResult(details: unknown): RenderedInlineSettlement | undefined {
+  const decoded = decodeInlineWorkerToolDetails(details);
+  if (Result.isFailure(decoded)) return undefined;
+  const settlement = decoded.success.result;
+  const outcome = settlement.outcome;
+  const message = outcome.status === "failed" || outcome.status === "aborted"
+    ? outcome.message
     : undefined;
+  const assistantText = outcome.assistantText;
+  const response = [message, assistantText]
+    .filter((item): item is string => typeof item === "string" && item.length > 0)
+    .join("\n\n");
   return {
-    worker: value.worker,
-    title: value.title,
-    status,
-    response: [message, assistantText].filter((item): item is string => typeof item === "string" && item.length > 0).join("\n\n"),
-    ...(elapsed ? { elapsed } : {}),
+    worker: settlement.worker,
+    title: settlement.title,
+    status: settlement.status,
+    response,
+    elapsed: formatElapsed(settlement.settledAt - settlement.startedAt),
   };
 }
 
-function inlineResultAppearance(status: InlineSettlement["status"]): {
-  readonly color: "success" | "error" | "warning";
-  readonly icon: "✓" | "✗" | "■";
-  readonly qualifier?: string;
-} {
-  if (status === "failed") return { color: "error", icon: "✗", qualifier: "failed" };
-  if (status === "aborted") return { color: "warning", icon: "■", qualifier: "aborted" };
-  if (status === "ready") {
-    return { color: "success", icon: "✓", qualifier: "ready for follow-up" };
-  }
-  return { color: "success", icon: "✓" };
-}
-
-function formatElapsed(milliseconds: number): string {
-  const seconds = Math.floor(milliseconds / 1000);
-  if (seconds < 60) return `${seconds}s`;
-  const minutes = Math.floor(seconds / 60);
-  return seconds % 60 === 0 ? `${minutes}m` : `${minutes}m ${seconds % 60}s`;
-}
-
 function renderDiagnosticsResult(result: AgentToolResult<unknown>, isPartial: boolean, theme: Theme): Text {
   if (isPartial) return new Text(theme.fg("muted", "Reading worker diagnostics…"), 0, 0);
   const details = result.details;

package/extension/tui.ts

@@ -0,0 +1,50 @@
+import { truncateToWidth, type Component } from "@earendil-works/pi-tui";
+
+export class WidthBoundComponent implements Component {
+  constructor(
+    private readonly child: Component,
+    private readonly maxLines?: number,
+  ) {}
+
+  render(width: number): string[] {
+    const bounded = Math.max(1, Math.floor(width));
+    const lines = this.child.render(bounded);
+    return (this.maxLines === undefined ? lines : lines.slice(0, this.maxLines))
+      .map((line) => truncateToWidth(line, bounded, "…"));
+  }
+
+  invalidate(): void { this.child.invalidate(); }
+  dispose(): void { disposeComponent(this.child); }
+}
+
+export function disposeComponent(component: Component): void {
+  (component as Component & { dispose?: () => void }).dispose?.();
+}
+
+export function resultAppearance(
+  status: "completed" | "ready" | "failed" | "aborted",
+  readyQualifier: string,
+  failedQualifier = "failed",
+): {
+  readonly color: "success" | "error" | "warning";
+  readonly icon: "✓" | "✗" | "■";
+  readonly qualifier?: string;
+} {
+  if (status === "failed") {
+    return { color: "error", icon: "✗", qualifier: failedQualifier };
+  }
+  if (status === "aborted") {
+    return { color: "warning", icon: "■", qualifier: "aborted" };
+  }
+  if (status === "ready") {
+    return { color: "success", icon: "✓", qualifier: readyQualifier };
+  }
+  return { color: "success", icon: "✓" };
+}
+
+export function formatElapsed(milliseconds: number): string {
+  const seconds = Math.floor(milliseconds / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  return seconds % 60 === 0 ? `${minutes}m` : `${minutes}m ${seconds % 60}s`;
+}