@bermudi/pi-delegate 0.1.2 → 0.1.3

package/concurrency.ts

@@ -115,7 +115,17 @@ async function mapConcurrent<T, R>(
       results[i] = await fn(items[i]!, i);
     }
   };
-  await Promise.all(Array.from({ length: limit }, () => worker()));
+  // Promise.all would reject as soon as one task throws while sibling workers
+  // are still unwinding. Wait for every worker first so callers can safely use
+  // this promise as the batch-settled barrier (notably shutdown telemetry).
+  const outcomes = await Promise.allSettled(
+    Array.from({ length: limit }, () => worker()),
+  );
+  const rejection = outcomes.find(
+    (outcome): outcome is PromiseRejectedResult =>
+      outcome.status === "rejected",
+  );
+  if (rejection) throw rejection.reason;
   return results;
 }
 
@@ -155,8 +165,10 @@ export async function mapConcurrentByModel<T, R>(
     group.indices.push(i);
   }
 
-  // Run all groups in parallel, each with its own concurrency limit + global cap
-  await Promise.all(
+  // Run all groups in parallel, each with its own concurrency limit + global cap.
+  // As above, wait for every group before surfacing an unexpected rejection so
+  // a late sibling cannot mutate a ticket after its completion barrier resolves.
+  const outcomes = await Promise.allSettled(
     [...groups.entries()].map(([, group]) => {
       const groupItems = group.indices.map((i) => items[i]!);
       return mapConcurrent(
@@ -185,5 +197,10 @@ export async function mapConcurrentByModel<T, R>(
       );
     }),
   );
+  const rejection = outcomes.find(
+    (outcome): outcome is PromiseRejectedResult =>
+      outcome.status === "rejected",
+  );
+  if (rejection) throw rejection.reason;
   return results;
 }

package/config.ts

@@ -8,6 +8,52 @@ import {
   OUTPUT_SPILL_THRESHOLD_CHARS,
 } from "./constants.ts";
 
+export interface TelemetryConfig {
+  /** Whether to record delegate calls to the local SQLite store. Default true. */
+  enabled?: boolean;
+  /** Path to the SQLite database. Defaults to `~/.pi/agent/delegate-usage.db`. */
+  dbPath?: string;
+}
+
+const DEFAULT_TELEMETRY_CONFIG: TelemetryConfig = {
+  enabled: true,
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Validate the user-editable telemetry block at its boundary. An explicitly
+ * malformed block disables telemetry rather than silently turning it on with
+ * the default database path. Missing telemetry is different: it means the
+ * user did not configure the feature, so the default remains enabled.
+ */
+export function normalizeTelemetryConfig(raw: unknown): TelemetryConfig {
+  if (raw === undefined) return { ...DEFAULT_TELEMETRY_CONFIG };
+  if (!isRecord(raw)) return { enabled: false };
+
+  const hasEnabled = Object.prototype.hasOwnProperty.call(raw, "enabled");
+  const hasDbPath = Object.prototype.hasOwnProperty.call(raw, "dbPath");
+  const enabled = raw.enabled;
+  const dbPath = raw.dbPath;
+
+  if (hasEnabled && typeof enabled !== "boolean") {
+    return { enabled: false };
+  }
+  if (hasDbPath && (typeof dbPath !== "string" || dbPath.trim().length === 0)) {
+    return { enabled: false };
+  }
+
+  const normalizedEnabled =
+    typeof enabled === "boolean" ? enabled : DEFAULT_TELEMETRY_CONFIG.enabled;
+  const normalizedDbPath = typeof dbPath === "string" ? dbPath : undefined;
+  return {
+    enabled: normalizedEnabled,
+    ...(normalizedDbPath === undefined ? {} : { dbPath: normalizedDbPath }),
+  };
+}
+
 export interface DelegateConfig {
   agent: {
     /** Global default model for all agent types. */
@@ -41,6 +87,8 @@ export interface DelegateConfig {
   providerExtensions?: {
     [provider: string]: readonly string[];
   };
+  /** Local SQLite telemetry for usage/health analytics. See `telemetry.ts`. */
+  telemetry?: TelemetryConfig;
   /** LLM-facing output bounding: over-threshold final output is spilled to a
    *  temp file with a tail kept in-context. See `spill.ts`. */
   output?: {
@@ -108,6 +156,9 @@ const DEFAULT_DELEGATE_CONFIG: DelegateConfig = {
     wholeTaskBaseDelayMs: 1_000,
   },
   providerExtensions: DEFAULT_PROVIDER_EXTENSIONS,
+  telemetry: {
+    enabled: true,
+  },
   output: {
     spillThresholdChars: OUTPUT_SPILL_THRESHOLD_CHARS,
     spillTailChars: OUTPUT_SPILL_TAIL_CHARS,
@@ -119,6 +170,7 @@ let __delegateConfig: DelegateConfig = {
   ...DEFAULT_DELEGATE_CONFIG,
   agent: { ...DEFAULT_DELEGATE_CONFIG.agent },
   concurrency: { ...DEFAULT_DELEGATE_CONFIG.concurrency },
+  telemetry: { ...DEFAULT_DELEGATE_CONFIG.telemetry },
 };
 let stallTimeoutOverrideForTesting: number | undefined;
 
@@ -140,6 +192,7 @@ export function loadDelegateConfig(): DelegateConfig {
       },
       retry: { ...DEFAULT_DELEGATE_CONFIG.retry, ...(parsed.retry ?? {}) },
       providerExtensions: resolveProviderExtensions(parsed.providerExtensions),
+      telemetry: normalizeTelemetryConfig(parsed.telemetry),
       output: { ...DEFAULT_DELEGATE_CONFIG.output, ...(parsed.output ?? {}) },
     } as DelegateConfig;
   } catch {
@@ -203,6 +256,7 @@ export function _setDelegateConfigForTesting(
       ...(config.retry ?? {}),
     },
     providerExtensions: resolveProviderExtensions(config.providerExtensions),
+    telemetry: normalizeTelemetryConfig(config.telemetry),
     output: {
       ...DEFAULT_DELEGATE_CONFIG.output,
       ...(config.output ?? {}),
@@ -356,3 +410,10 @@ export function resolveModelSpec(options: {
     (v): v is string => typeof v === "string" && v.length > 0,
   );
 }
+
+/** Get the configured telemetry settings. */
+export function getTelemetryConfig(
+  config: DelegateConfig = __delegateConfig,
+): TelemetryConfig {
+  return normalizeTelemetryConfig(config.telemetry);
+}

package/delegate.ts

@@ -92,6 +92,7 @@ export type { ActiveTicketSummary } from "./status.ts";
 export { getHostDeps, invalidateHostDepsCache } from "./host.ts";
 export type { HostDeps, HostDepsOptions } from "./host.ts";
 export {
+  aggregateTaskResults,
   emptyUsage,
   snapshotSessionUsage,
   usageDelta,

package/dispatch.ts

@@ -12,7 +12,7 @@ import {
 import { getConcurrencyLimit, getMaxAsyncTickets } from "./config.ts";
 import { getCurrentLeafId } from "./leaf.ts";
 import { getModelKey, mapConcurrentByModel } from "./concurrency.ts";
-import { sumUsage } from "./usage.ts";
+import { aggregateTaskResults, sumUsage } from "./usage.ts";
 import { runResolvedTask, updateProgressFromRun } from "./lifecycle.ts";
 import {
   fmtDuration,
@@ -24,6 +24,7 @@ import {
 import { validateDelegateOperation } from "./schema.ts";
 import { notifyCrossLeafDelivery, syncDelegateStatus } from "./status.ts";
 import { validateTasks, resolveTasks } from "./task-resolution.ts";
+import type { CallSpan } from "./telemetry.ts";
 import type {
   AgentConfig,
   AsyncTicket,
@@ -113,6 +114,7 @@ export interface AsyncDispatchInput {
   resolved: ResolvedTask[];
   progress: TaskProgress[];
   parentModelId: string | undefined;
+  callSpan?: CallSpan;
 }
 
 /** Inputs needed by the sync (blocking) dispatch path. */
@@ -124,6 +126,7 @@ export interface SyncDispatchInput {
   parentModelId: string | undefined;
   signal: AbortSignal | undefined;
   fire: () => void;
+  callSpan?: CallSpan;
 }
 
 /** Inputs for the normal task-validation, resolution, and dispatch path. */
@@ -136,6 +139,7 @@ export interface DelegateDispatchInput {
   parentDefaults: ParentAgentDefaults;
   signal: AbortSignal | undefined;
   onUpdate: AgentToolUpdateCallback<DelegateDetails> | undefined;
+  callSpan?: CallSpan;
 }
 
 /** Validate, resolve, and dispatch a non-short-circuit delegate operation. */
@@ -151,11 +155,20 @@ export async function dispatchDelegate(
     parentDefaults,
     signal,
     onUpdate,
+    callSpan,
   } = input;
   const tasks = params.tasks ?? [];
 
   const validationError = validateTasks(tasks, agents, parentModelId);
-  if (validationError) return validationError;
+  if (validationError) {
+    callSpan?.finish({
+      status: "failed",
+      totalTokens: 0,
+      totalCost: 0,
+      wallMs: Date.now() - callSpan.startedAt,
+    });
+    return validationError;
+  }
 
   const resolved = resolveTasks(tasks, ctx, agents, parentDefaults);
   const progress = initProgress(resolved);
@@ -176,6 +189,7 @@ export async function dispatchDelegate(
       resolved,
       progress,
       parentModelId,
+      callSpan,
     });
   }
 
@@ -187,6 +201,7 @@ export async function dispatchDelegate(
     parentModelId,
     signal,
     fire,
+    callSpan,
   });
 }
 
@@ -199,17 +214,39 @@ function finishTicketDelivery(pi: ExtensionAPI, ticket: AsyncTicket): void {
   }
 }
 
+function settleAsyncCall(
+  ticket: AsyncTicket,
+  callSpan: CallSpan | undefined,
+): void {
+  if (!callSpan) return;
+  const { totalTokens, totalCost } = aggregateTaskResults(ticket.results);
+  const wallMs = (ticket.completedAt ?? Date.now()) - callSpan.startedAt;
+  const status =
+    ticket.status === "done"
+      ? "done"
+      : ticket.status === "cancelled"
+        ? "cancelled"
+        : "failed";
+  callSpan.finish({ status, totalTokens, totalCost, wallMs });
+}
+
 /** Fire-and-forget background execution. Registers an `AsyncTicket`, kicks off
  *  the concurrent run, and returns the ticket acknowledgment immediately.
  *  Results are delivered via `deliverTicketResults` when all tasks settle. */
 export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
-  const { pi, ctx, tasks, resolved, progress, parentModelId } = input;
+  const { pi, ctx, tasks, resolved, progress, parentModelId, callSpan } = input;
 
   sweepTickets();
   const runningCount = [...ticketRegistry.values()].filter(
     (t) => t.status === "running" || t.status === "cancelling",
   ).length;
   if (runningCount >= getMaxAsyncTickets()) {
+    callSpan?.finish({
+      status: "failed",
+      totalTokens: 0,
+      totalCost: 0,
+      wallMs: Date.now() - (callSpan?.startedAt ?? Date.now()),
+    });
     return {
       content: [
         {
@@ -236,8 +273,13 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
     // Leaf affinity for delivery: a ticket that outlives a /tree navigation
     // must not wake the agent on the branch the user moved to (issue #30).
     spawnLeafId: getCurrentLeafId(),
+    callId: callSpan?.id,
+    callStartedAt: callSpan?.startedAt,
+    callRecord: callSpan ? { ...callSpan.baseRecord() } : undefined,
+    telemetryGeneration: callSpan?.generation,
   };
   ticketRegistry.set(ticketId, ticket);
+  callSpan?.spawn();
   // Footer visibility for the new background work (see status.ts). Uses the
   // ctx cached from the dispatch path in extension.ts — DelegateToolCtx is
   // the intentionally narrowed surface and does not carry `ui`.
@@ -254,6 +296,9 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
     parentSessionManager: ctx.sessionManager,
     ticketId,
     delegateStartedAt: ticket.created,
+    telemetryCallId: callSpan?.id,
+    telemetryGeneration: callSpan?.generation,
+    async: true,
     onProgress: (p, u) => {
       updateProgressFromRun(p, u);
       notifyWaiters(ticket);
@@ -271,7 +316,7 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
   // Worker must store the TaskResult back into ticket.results, since
   // formatCompletedTicket/handlePoll read from there. Without the write,
   // completed async tasks would be reported as PENDING.
-  mapConcurrentByModel(
+  const completion = mapConcurrentByModel(
     resolved,
     (t) => getModelKey(t.model),
     getConcurrencyLimit,
@@ -283,12 +328,14 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
     ticketSignal,
   )
     .then(() => {
-      // A ticket that is already terminally "cancelled" at this point was
-      // finalized by cancelTicketForShutdown (user cancels pass through
-      // "cancelling" first): the extension runtime is being torn down, the
-      // captured `pi` is stale or about to be, and a follow-up message has
-      // no live session to land in. Skip delivery entirely.
-      if (ticket.status === "cancelled") return;
+      // Shutdown marks the ticket terminal before cooperative worker aborts
+      // have finished. Still write one final aggregate after every result has
+      // landed; the immediate shutdown snapshot may have missed late usage.
+      // The runtime is being torn down, so never attempt UI delivery here.
+      if (ticket.status === "cancelled") {
+        settleAsyncCall(ticket, callSpan);
+        return;
+      }
       // All tasks settled — determine final ticket status.
       // Use progress (set by runResolvedTask) for settled-ness so the
       // status reflects work completion, not just result-array density.
@@ -309,12 +356,17 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
         syncTicketBusyIndex(ticket);
       }
       syncDelegateStatus();
+      settleAsyncCall(ticket, callSpan);
       finishTicketDelivery(pi, ticket);
     })
     .catch((err) => {
       // Defense-in-depth — should not happen if individual tasks catch properly.
-      // Same shutdown guard as the .then path above.
-      if (ticket.status === "cancelled") return;
+      // Even an unexpected worker rejection must leave the shutdown aggregate
+      // with every result that did settle, without touching the stale UI.
+      if (ticket.status === "cancelled") {
+        settleAsyncCall(ticket, callSpan);
+        return;
+      }
       if (ticket.status === "cancelling") {
         ticket.status = "cancelled";
       } else if (ticket.status === "running") {
@@ -324,8 +376,10 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
       ticket.completedAt = Date.now();
       syncTicketBusyIndex(ticket);
       syncDelegateStatus();
+      settleAsyncCall(ticket, callSpan);
       finishTicketDelivery(pi, ticket);
     });
+  ticket.completion = completion;
 
   return {
     content: [
@@ -335,8 +389,8 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
           `Async ticket: ${ticketId}`,
           `${resolved.length} task(s) dispatched · ${runningCount + 1}/${getMaxAsyncTickets()} async slots in use`,
           "",
-          "Completed task results are available via poll. Final results delivered automatically when all tasks complete.",
-          `Check progress: delegate({ ticketAction: "poll", ticket: "${ticketId}" }) — avoid polling in a tight loop`,
+          "Work is detached. Stop this turn to let final results auto-deliver.",
+          `If this turn must block for the result, call once: delegate({ ticketAction: "wait", ticket: "${ticketId}" }) — omit timeoutMs and do not poll`,
           `Cancel if needed: delegate({ ticketAction: "cancel", ticket: "${ticketId}", force: true }) — first call without force is a preview`,
         ].join("\n"),
       },
@@ -357,7 +411,16 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
 export async function dispatchSync(
   input: SyncDispatchInput,
 ): Promise<DelegateToolResult> {
-  const { ctx, tasks, resolved, progress, parentModelId, signal, fire } = input;
+  const {
+    ctx,
+    tasks,
+    resolved,
+    progress,
+    parentModelId,
+    signal,
+    fire,
+    callSpan,
+  } = input;
 
   const startedAt = Date.now();
   const syncEnv: TaskRunEnv = {
@@ -366,6 +429,9 @@ export async function dispatchSync(
     parentSessionManager: ctx.sessionManager,
     ticketId: undefined,
     delegateStartedAt: startedAt,
+    telemetryCallId: callSpan?.id,
+    telemetryGeneration: callSpan?.generation,
+    async: false,
     onProgress: (p, u) => {
       updateProgressFromRun(p, u);
       fire();
@@ -401,6 +467,19 @@ export async function dispatchSync(
   );
   if (overlapWarning) parts.push("", overlapWarning);
 
+  const status = finalResults.some((r) => r.error) ? "failed" : "success";
+  const totalTokens = finalResults.reduce((sum, r) => sum + r.tokens, 0);
+  const totalCost = finalResults.reduce(
+    (sum, r) => sum + r.usage.cost.total,
+    0,
+  );
+  callSpan?.finish({
+    status,
+    totalTokens,
+    totalCost,
+    wallMs: Date.now() - callSpan.startedAt,
+  });
+
   return {
     content: [{ type: "text", text: parts.join("\n\n") }],
     details: {