@bermudi/pi-delegate 0.1.1 → 0.1.3

package/types.ts

@@ -12,6 +12,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { Static } from "@sinclair/typebox";
 import type { delegateArgumentsSchema } from "./schema.ts";
+import type { CallRecord } from "./telemetry.ts";
 
 export interface AgentConfig {
   name: string;
@@ -25,18 +26,37 @@ export interface AgentConfig {
 }
 
 // ── Tool parameter types — derived from the TypeBox schema ────────────────
-// `delegateArgumentsSchema` in schema.ts is the single source of truth; these are
-// projections of it, so schema and types cannot drift. Field semantics live
-// in the schema's `description`s (which the calling model also sees).
-// The import is type-only, so the schema.ts ↔ types.ts cycle is erased at
-// compile time.
-
-export type DelegateArguments = Static<typeof delegateArgumentsSchema>;
-export type TaskDef = NonNullable<DelegateArguments["tasks"]>[number];
+// `delegateArgumentsSchema` in schema.ts is the canonical provider-visible
+// shape. The public types add deprecated `action` aliases so existing TypeScript
+// callers remain source-compatible without advertising the overloaded fields to
+// models. The import is type-only, so the schema.ts ↔ types.ts cycle is erased
+// at compile time.
+
+type CanonicalDelegateArguments = Static<typeof delegateArgumentsSchema>;
+type CanonicalTaskDef = NonNullable<
+  CanonicalDelegateArguments["tasks"]
+>[number];
+
 /** Top-level async ticket action: "poll" | "cancel" | "wait". */
-export type DelegateAction = NonNullable<DelegateArguments["action"]>;
+export type TicketAction = NonNullable<
+  CanonicalDelegateArguments["ticketAction"]
+>;
 /** Per-task session action: "prompt" | "close" | "list". */
-export type SessionAction = NonNullable<TaskDef["action"]>;
+export type SessionAction = NonNullable<CanonicalTaskDef["sessionAction"]>;
+
+export type TaskDef = CanonicalTaskDef & {
+  /** @deprecated Use `sessionAction` instead. Runtime normalization still accepts this alias. */
+  action?: SessionAction;
+};
+
+export type DelegateArguments = Omit<CanonicalDelegateArguments, "tasks"> & {
+  /** @deprecated Use `ticketAction` instead. Runtime normalization still accepts this alias. */
+  action?: TicketAction;
+  tasks?: TaskDef[];
+};
+
+/** @deprecated Use `TicketAction` instead. */
+export type DelegateAction = TicketAction;
 
 // ── Async Ticket Types ─────────────────────────────────────────────────────
 
@@ -61,8 +81,22 @@ export interface AsyncTicket {
   controller: AbortController;
   error?: string;
   parentModelId?: string;
+  /** Session-tree leaf active when the ticket was spawned (see leaf.ts).
+   *  `undefined` = the leaf the session opened on. Compared at delivery time
+   *  so results are not used to wake the agent on a foreign branch. */
+  spawnLeafId?: string | null;
   /** Active blocking waiters. Resolved by terminal delivery or timeout/abort. */
   waiters?: TicketWaiter[];
+  /** Telemetry call span id attached to this async ticket. */
+  callId?: string;
+  /** Telemetry call span start timestamp for accurate wall-time on cancellation. */
+  callStartedAt?: number;
+  /** Snapshot of the call row at spawn, used to write the cancelled/settled row. */
+  callRecord?: CallRecord;
+  /** Runtime generation for rejecting shutdown writes from stale tickets. */
+  telemetryGeneration?: number;
+  /** Resolves after every async worker has settled, including shutdown aborts. */
+  completion?: Promise<void>;
 }
 
 /** Live parent settings captured when a delegate call starts. The built-in
@@ -81,6 +115,7 @@ export interface ReuseIntent {
 }
 
 export interface ResolvedTask {
+  id?: string;
   prompt: string;
   agent?: string;
   model: Model<Api>;
@@ -90,8 +125,10 @@ export interface ResolvedTask {
   cwd: string;
   context?: "fresh" | "with-parent-transcript";
   sessionId?: string;
-  action?: SessionAction;
+  sessionAction?: SessionAction;
   resumeFrom?: string;
+  /** Hard wall-clock budget in milliseconds, measured from task start. */
+  deadlineMs?: number;
   agentName: string;
   warnings: string[];
   /** Explicit settings that must match a live pooled session on reuse. */
@@ -117,10 +154,14 @@ export interface ToolActivity {
  *  - `model_error`: the failure is attributable to the resolved model/provider
  *    (account usage limit, quota exhausted, auth lost) — not transient for that
  *    model, so same-model retry is pointless. The parent should resume with a
- *    different `model` (see `resumeFrom` + `model`). */
-export type TaskFailureKind = "stalled" | "model_error";
+ *    different `model` (see `resumeFrom` + `model`).
+ *  - `deadline_exceeded`: the task's `deadlineMs` wall-clock budget expired
+ *    (measured from when the task left the concurrency queue). The prompt was
+ *    cooperatively aborted; completed side effects are not rolled back. */
+export type TaskFailureKind = "stalled" | "model_error" | "deadline_exceeded";
 
 export interface TaskProgress {
+  id?: string;
   index: number;
   agent: string;
   task: string;
@@ -146,9 +187,13 @@ export interface DelegateDetails {
   ticketId?: string;
   /** Terminal/live ticket status when this result comes from an async ticket. */
   status?: AsyncTicket["status"];
+  /** Global overlap warning derived from result.attributedFiles, surfaced in both
+   *  the textual content and the custom TUI. */
+  overlapWarning?: string;
 }
 
 export interface TaskResult {
+  id?: string;
   agent: string;
   output: string;
   error?: string;
@@ -167,7 +212,14 @@ export interface TaskResult {
    *  Pi sums `cost.total` for nested usage anyway. */
   usage: Usage;
   sessionFile?: string;
+  /** All files the subagent is known to have touched, including bash mutations
+   *  captured via git diff and other tasks' concurrent git changes. This is a
+   *  best-effort, repository-wide list for display, not for attribution. */
   touchedFiles: string[];
+  /** Files directly attributable to this task's edit/write tool calls. Used
+   *  for overlap detection so concurrent tasks in the same repo do not
+   *  fabricate false conflicts from shared git snapshots. */
+  attributedFiles?: string[];
 }
 
 /** Single source of truth for a subagent's runtime configuration.
@@ -204,6 +256,12 @@ export interface TaskRunEnv {
   onProgress: (p: TaskProgress, u: AgentProgressUpdate) => void;
   /** Called after every TaskProgress mutation (early-returns, completion). Sync uses this to fire onUpdate. */
   onStatusChange?: () => void;
+  /** Telemetry call id for this dispatch. undefined when telemetry is disabled or not started. */
+  telemetryCallId?: string;
+  /** Runtime generation for rejecting writes from a stale shutdown worker. */
+  telemetryGeneration?: number;
+  /** Whether this task is part of an async ticket. */
+  async?: boolean;
 }
 
 /** Structural subset of Pi's `ExtensionContext` used by delegate's

package/usage.ts

@@ -1,5 +1,6 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { Usage } from "@earendil-works/pi-ai";
+import type { TaskResult } from "./types.ts";
 
 /** Snapshot of the cumulative session usage fields we read for delta accounting. */
 export interface SessionUsageSnapshot {
@@ -119,3 +120,21 @@ export function sumUsage(usages: readonly (Usage | undefined)[]): Usage {
     emptyUsage(),
   );
 }
+
+/** Aggregate the completed result rows used by async call telemetry. */
+export function aggregateTaskResults(
+  results: readonly (TaskResult | undefined)[],
+): { totalTokens: number; totalCost: number } {
+  return results
+    .filter(
+      (result): result is TaskResult =>
+        result !== undefined && "touchedFiles" in result,
+    )
+    .reduce(
+      (total, result) => ({
+        totalTokens: total.totalTokens + result.tokens,
+        totalCost: total.totalCost + (result.usage?.cost?.total ?? 0),
+      }),
+      { totalTokens: 0, totalCost: 0 },
+    );
+}