@cr1ms0n/pi-subagent 0.9.0 → 0.11.0

package/src/types.ts

@@ -41,6 +41,66 @@ export interface UsageStats {
 
 export type BackendName = "pi" | "codex" | "claude";
 
+/**
+ * Sticky current-invocation tool activity for the pre-tool switch boundary. `started` latches on tool_execution_start, a newly observed
+ * completed assistant toolCall or a toolResult; `unknown` marks malformed,
+ * truncated or absent evidence. Both are sticky: neither can be erased by a
+ * later complete event, and only a conclusive `none` authorizes a new child.
+ */
+export type ToolActivity = "none" | "started" | "unknown";
+
+/**
+ * Conservative classification of the latest completed assistant provider error
+ * (see `model-failover.ts`). Only the availability categories advance the
+ * ranked path; everything else stops and is reported without switching.
+ */
+export type ModelFailureCategory =
+  | "model_unavailable"
+  | "rate_limited"
+  | "service_overload"
+  | "transport"
+  | "auth"
+  | "quota"
+  | "invalid_request"
+  | "context_overflow"
+  | "refusal"
+  | "unknown";
+
+/**
+ * One locally finalized ranked execution candidate. Internal contract built by
+ * `policy.ts` from the validated ranking and the original model catalog; never
+ * a tool-request/config field and never decoded from a persisted snapshot into
+ * an executable plan. Thinking follows explicit > agent > profile > candidate >
+ * parent per entry; tools/writer classification are shared across all entries.
+ */
+export interface ModelAttemptSpec {
+  readonly model: string;
+  readonly probability: number;
+  readonly thinking?: ThinkingLevel;
+}
+
+/**
+ * Bounded descriptive history for one ranked/legacy attempt. Records are not
+ * a second usage ledger (TaskResult.usage stays cumulative) and never become
+ * executable: they carry the reason for a switch, the session pointer for
+ * discoverable partial work, and a 1 KiB output preview (16 KiB per task).
+ */
+export interface ModelAttemptRecord {
+  /** 1-based launch count for this task. */
+  attempt: number;
+  /** 0-based ranking position of the candidate that ran. */
+  rank: number;
+  model: string;
+  probability: number;
+  outcome: RunState;
+  stopReason?: string;
+  failureCategory?: ModelFailureCategory;
+  toolActivity?: ToolActivity;
+  sessionId?: string;
+  /** Bounded output preview; metadata/session pointer survive when text is trimmed. */
+  outputPreview?: string;
+}
+
 export interface TaskSpec {
   /** Agent CLI powering this child. Defaults to "pi". */
   backend?: BackendName;
@@ -75,8 +135,15 @@ export interface TaskSpec {
   graceTurns?: number;
   /** Ordered backup models tried on transient provider failures. */
   fallbackModels?: string[];
-  /** Extra attempts on transient failures (queue timeout, stall, provider error). */
+  /** Extra launches: ranked pre-tool recovery, or the legacy SDK transient loop. */
   maxRetries?: number;
+  /**
+   * Locally finalized probability-ranked candidate plan for extension-managed
+   * tasks (internal; built only by `policy.finalizeRoutedTasks`). Its presence
+   * selects the ranked attempt loop; the legacy `fallbackModels` loop stays
+   * untouched for trusted unranked SDK tasks.
+   */
+  modelAttemptPlan?: readonly ModelAttemptSpec[];
   /** Fork the parent conversation into the child (real branched session). */
   contextFork?: boolean;
   /** Parent session file used for contextFork. */
@@ -129,6 +196,22 @@ export interface TaskResult {
   attempts?: number;
   /** Models tried across attempts, in order. */
   attemptedModels?: string[];
+  /** Sticky current-invocation tool activity across this task's attempts. */
+  toolActivity?: ToolActivity;
+  /**
+   * Bounded errorMessage + primitive diagnostics.error.code from the latest
+   * completed assistant provider error. Set only for stopReason "error";
+   * generic runner/RPC errors and diagnostic bodies never fill it.
+   */
+  providerError?: string;
+  /**
+   * Runner-owned positive proof that no child/task work could have begun
+   * (queue/admission timeout or a spawn that never produced a process). Only
+   * this conclusive evidence permits a same-model infrastructure retry.
+   */
+  preWorkInfraFailure?: boolean;
+  /** Bounded per-attempt history for ranked runs (descriptive, never executable). */
+  modelAttempts?: ModelAttemptRecord[];
   /** Parsed structured result when output_schema was requested and validated. */
   structuredOutput?: unknown;
   /** Validation errors when output_schema was requested but the result failed. */
@@ -182,6 +265,10 @@ export interface RunSnapshot {
     stalledSince?: number;
     attempts?: number;
     attemptedModels?: string[];
+    /** Sticky tool-activity boundary state across the task's attempts. */
+    toolActivity?: ToolActivity;
+    /** Bounded ranked attempt history (descriptive; previews capped). */
+    modelAttempts?: ModelAttemptRecord[];
     structuredOutput?: unknown;
     structuredError?: string;
   }>;