@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/shared/types/owned-runs.ts

@@ -0,0 +1,148 @@
+import type { WritableDeep } from "type-fest";
+import type { ResolvedAcceptanceConfig } from "./acceptance.ts";
+import type { ReadonlyInput } from "./inputs.ts";
+import type { SavedLaunchConfig } from "./launch.ts";
+import type { ReadonlyAgentProgress, SubagentResultStatus, SubagentRunMode } from "./progress.ts";
+import type { ArtifactPaths, ReadonlySingleResult } from "./results.ts";
+
+export type ManagementRunState = "live" | "completed" | "paused" | "blocked" | "failed" | "unknown";
+export type ManagementAction = "status" | "nudge" | "resume" | "interrupt" | "extend" | "review";
+
+export interface ParentRunReview {
+  readonly decision: "accepted" | "needs_changes";
+  readonly message?: string;
+  readonly reviewedAt: number;
+}
+
+/** Persisted ownership record; mutation belongs to the live tracker, not readers of this snapshot. */
+export interface OwnedRun {
+  readonly recoveryError?: string;
+  readonly runId: string;
+  readonly ownerSessionId: string;
+  readonly source: "foreground" | "async";
+  readonly mode: SubagentRunMode;
+  readonly cwd: string;
+  readonly task: string;
+  readonly startedAt: number;
+  readonly rootRunId: string;
+  readonly predecessorRunId?: string;
+  readonly predecessorIndex?: number;
+  readonly asyncDir?: string;
+  readonly pid?: number;
+  readonly children: readonly {
+    readonly agent: string;
+    readonly index: number;
+    readonly workflowNodeId?: string;
+    readonly task?: string;
+    readonly label?: string;
+    readonly sessionFile?: string;
+  }[];
+  readonly review?: ParentRunReview;
+  readonly completion?: {
+    readonly id: string;
+    readonly state: "pending" | "queued" | "dropped" | "journaled";
+    readonly channel?: "notification" | "intercom";
+    readonly queuedAt?: number;
+    readonly entryId?: string;
+  };
+  readonly accounting?: {
+    readonly state: "pending" | "complete" | "incomplete";
+    readonly error?: string;
+  };
+  readonly delivery?: {
+    readonly notifiedAt: number;
+    readonly intercomDelivered: boolean;
+    readonly completionId?: string;
+    readonly entryId?: string;
+  };
+  readonly legacy?: boolean;
+  readonly error?: string;
+}
+
+/** Mutable tracker ownership is deliberately separate from persisted run inputs. */
+export type TrackedOwnedRun = WritableDeep<OwnedRun>;
+
+export interface OwnedRunView extends OwnedRun {
+  readonly state: ManagementRunState;
+  readonly updatedAt: number;
+  readonly attention: readonly string[];
+  readonly children: readonly (OwnedRun["children"][number] & {
+    readonly state: ManagementRunState;
+    readonly result?: Omit<ReadonlySingleResult, "artifactPaths"> & {
+      readonly artifactPaths?: Partial<ArtifactPaths>;
+    };
+    readonly launch?: SavedLaunchConfig;
+    readonly configuration: "saved" | "legacy-partial";
+    readonly missingSession?: boolean;
+    readonly identityUnavailable?: boolean;
+    readonly modelSelection?: Pick<ReadonlyAgentProgress, "model" | "thinking" | "modelStartedAt">;
+    readonly activity?: Partial<
+      Pick<
+        ReadonlyAgentProgress,
+        | "status"
+        | "currentTool"
+        | "currentToolArgs"
+        | "currentPath"
+        | "recentOutput"
+        | "lastActivityAt"
+        | "streamingText"
+      >
+    >;
+  })[];
+  readonly continuations: readonly {
+    readonly runId: string;
+    readonly predecessorRunId: string;
+    readonly predecessorIndex?: number;
+  }[];
+  readonly resultPath?: string;
+  readonly canInterrupt: boolean;
+  readonly diagnosis?: string;
+}
+
+export interface ManagementControl {
+  readonly state: ManagementRunState;
+  readonly runId: string;
+  readonly capabilities: readonly ManagementAction[];
+  readonly nextActions: readonly {
+    readonly action: ManagementAction;
+    readonly runId: string;
+    readonly index?: number;
+    readonly intercomTarget?: string;
+  }[];
+  readonly unavailableActions?: Readonly<Partial<Record<ManagementAction, string>>>;
+  readonly revivedFromRunId?: string;
+  readonly pendingReplyContextValid?: boolean;
+}
+
+/** Live continuation owner, retained after foreground detachment. */
+export interface ForegroundResumeChild {
+  agent: string;
+  index: number;
+  sessionFile?: string;
+  status: SubagentResultStatus;
+  summary?: string;
+  artifactPath?: string;
+  effectiveAcceptance?: ResolvedAcceptanceConfig;
+  result?: ReadonlySingleResult;
+}
+
+export interface ForegroundResumeRun {
+  runId: string;
+  mode: SubagentRunMode;
+  cwd: string;
+  updatedAt: number;
+  error?: string;
+  /** Logical work left after detachment, independent of child success. */
+  pausedReason?: string;
+  children: ForegroundResumeChild[];
+}
+
+export type ReadonlyForegroundResumeRun = ReadonlyInput<ForegroundResumeRun>;
+
+export interface TimeoutExtensionResult {
+  readonly ok: boolean;
+  readonly timeoutAt?: number;
+  readonly message: string;
+}
+
+export type TimeoutExtensionCallback = (additionalMs: number) => TimeoutExtensionResult;

package/src/shared/types/progress.ts

@@ -0,0 +1,106 @@
+import type { ActivityState, ControlEventType } from "./config.ts";
+import type { ReadonlyInput } from "./inputs.ts";
+
+export type SubagentResultStatus =
+  | "completed"
+  | "failed"
+  | "blocked"
+  | "paused"
+  | "detached"
+  | "timed-out";
+export type SubagentRunMode = "single" | "parallel" | "chain";
+
+export interface ControlEvent {
+  readonly type: ControlEventType;
+  readonly from?: ActivityState;
+  readonly to: ActivityState;
+  readonly ts: number;
+  readonly agent: string;
+  readonly index?: number;
+  readonly runId: string;
+  readonly message: string;
+  readonly reason?: "idle" | "completion_guard" | "tool_failures";
+  readonly turns?: number;
+  readonly tokens?: number;
+  readonly toolCount?: number;
+  readonly currentTool?: string;
+  readonly currentToolDurationMs?: number;
+  readonly currentPath?: string;
+  readonly elapsedMs?: number;
+  readonly recentFailureSummary?: string;
+  readonly supervisorQuestion?: {
+    readonly questionId: string;
+    readonly state: "awaiting_input" | "answer_pending";
+    readonly answer?: string;
+  };
+}
+
+/** Live progress owner: streaming and tool events update fields and bounded buffers in place. */
+export interface AgentProgress {
+  index: number;
+  agent: string;
+  status:
+    | "pending"
+    | "running"
+    | "completed"
+    | "complete"
+    | "failed"
+    | "blocked"
+    | "paused"
+    | "detached"
+    | "timed-out";
+  model?: string;
+  thinking?: string;
+  /** Display boundary: earlier native history belongs to a previous attempt. */
+  modelStartedAt?: number;
+  activityState?: ActivityState;
+  task: string;
+  skills?: readonly string[];
+  lastActivityAt?: number;
+  currentTool?: string;
+  currentToolArgs?: string;
+  currentToolStartedAt?: number;
+  currentPath?: string;
+  streamingText?: string;
+  recentTools: Array<{ tool: string; args: string; endMs: number }>;
+  recentOutput: string[];
+  toolCount: number;
+  turnCount?: number;
+  tokens: number;
+  durationMs: number;
+  error?: string;
+  failedTool?: string;
+}
+
+export type ReadonlyAgentProgress = ReadonlyInput<AgentProgress>;
+
+export interface ToolCallSummary {
+  readonly text: string;
+  readonly expandedText: string;
+}
+
+export interface ProgressSummary extends Partial<
+  Pick<
+    ReadonlyAgentProgress,
+    | "index"
+    | "agent"
+    | "status"
+    | "activityState"
+    | "task"
+    | "skills"
+    | "lastActivityAt"
+    | "currentTool"
+    | "currentToolArgs"
+    | "currentToolStartedAt"
+    | "currentPath"
+    | "recentTools"
+    | "recentOutput"
+    | "turnCount"
+    | "error"
+    | "failedTool"
+  >
+> {
+  readonly toolCount: number;
+  readonly tokens: number;
+  readonly durationMs: number;
+}

package/src/shared/types/questions.ts

@@ -0,0 +1,103 @@
+import type { ResolvedAcceptanceConfig } from "./acceptance.ts";
+import type { JsonSchemaObject, OutputMode } from "./config.ts";
+import type { SavedLaunchConfig } from "./launch.ts";
+import type { ReadonlyAgentProgress } from "./progress.ts";
+import type { ReadonlySingleResult } from "./results.ts";
+
+export interface SupervisorRunContract {
+  readonly legacySource?: string;
+  /** Readers migrate v1/v2 owner records; all new publications use v3. */
+  readonly recordVersion?: 1 | 2 | 3;
+  readonly nativeSessionId?: string;
+  readonly terminalLeafId?: string | null;
+  readonly terminalEntryId?: string;
+  readonly attemptBaseline?: readonly string[];
+  readonly baselineSource?: "native-migration";
+  readonly effectiveConfiguration?: {
+    readonly model?: string;
+    readonly thinking?: string;
+    readonly modelRecordedAt?: number;
+  };
+  readonly accounting?: { readonly state: "complete" | "incomplete"; readonly error?: string };
+  readonly auditPath?: string;
+  readonly task?: string;
+  readonly label?: string;
+  readonly result?: ReadonlySingleResult;
+  readonly effectiveAcceptance?: ResolvedAcceptanceConfig;
+  readonly output?: string | false;
+  readonly outputMode?: OutputMode;
+  readonly outputSchema?: JsonSchemaObject;
+  readonly launch?: SavedLaunchConfig;
+  /** Retained independently of progress after detachment. */
+  readonly modelSelection?: Pick<ReadonlyAgentProgress, "model" | "thinking" | "modelStartedAt">;
+  readonly sessionFile?: string;
+  readonly pid?: number;
+  readonly processIdentity?: string;
+  readonly updatedAt?: number;
+}
+
+export interface SupervisorQuestion extends SupervisorRunContract {
+  readonly questionId: string;
+  readonly runId: string;
+  readonly ownerSessionId: string;
+  readonly ownerTarget: string;
+  readonly agent: string;
+  readonly index: number;
+  readonly childSessionId: string;
+  readonly childTarget: string;
+  readonly sessionFile: string;
+  readonly cwd: string;
+  readonly pid: number;
+  readonly createdAt: number;
+  readonly reason: "need_decision" | "interview_request";
+  readonly message: string;
+  readonly interview?: unknown;
+}
+
+export interface QuestionAnswer {
+  readonly message: string;
+  readonly answeredAt: number;
+  readonly origin?: "human";
+}
+
+export interface QuestionDelivery {
+  readonly kind: "live" | "revive";
+  readonly runId: string;
+  readonly deliveredAt: number;
+}
+
+export interface SupervisorQuestionView extends SupervisorQuestion {
+  readonly state: "awaiting_input" | "answer_pending" | "answered" | "cancelled";
+  readonly answer?: QuestionAnswer;
+  readonly delivery?: QuestionDelivery;
+  readonly revival?: { readonly runId: string; readonly pid: number; readonly startedAt: number };
+}
+
+export interface SupervisorQuestionSummary extends Pick<
+  SupervisorQuestionView,
+  | "questionId"
+  | "runId"
+  | "ownerSessionId"
+  | "ownerTarget"
+  | "agent"
+  | "index"
+  | "childSessionId"
+  | "childTarget"
+  | "sessionFile"
+  | "cwd"
+  | "pid"
+  | "processIdentity"
+  | "createdAt"
+  | "reason"
+  | "message"
+  | "state"
+  | "answer"
+  | "delivery"
+  | "revival"
+> {
+  readonly questionPath: string;
+  readonly answerPath?: string;
+  readonly messageTruncated?: boolean;
+  readonly answerTruncated?: boolean;
+  readonly hasInterview?: boolean;
+}

package/src/shared/types/results.ts

@@ -0,0 +1,119 @@
+import type { AcceptanceLedger } from "./acceptance.ts";
+import type { OutputMode } from "./config.ts";
+import type { ReadonlyInput } from "./inputs.ts";
+import type { ObservedMessage } from "./messages.ts";
+import type { AgentProgress, ControlEvent, ProgressSummary, ToolCallSummary } from "./progress.ts";
+import type { Usage } from "./usage.ts";
+
+export interface SavedOutputReference {
+  readonly path: string;
+  readonly bytes: number;
+  readonly lines: number;
+  readonly message: string;
+}
+
+export interface TruncationResult {
+  readonly text: string;
+  readonly truncated: boolean;
+  readonly originalBytes?: number;
+  readonly originalLines?: number;
+  readonly artifactPath?: string;
+}
+
+export interface ModelAttempt {
+  readonly accounting?: { readonly state: "complete" | "incomplete"; readonly error?: string };
+  readonly model: string;
+  readonly success: boolean;
+  readonly exitCode?: number | null;
+  readonly error?: string;
+  readonly usage?: Usage;
+}
+
+export interface ResourceLimitExceeded {
+  readonly kind: "maxExecutionTimeMs" | "maxTokens";
+  readonly limit: number;
+  readonly observed?: number;
+  readonly message: string;
+}
+
+export interface AgentProcessExit {
+  readonly pid?: number;
+  readonly code: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly at: number;
+}
+
+export interface ArtifactPaths {
+  readonly inputPath: string;
+  readonly outputPath: string;
+  readonly metadataPath: string;
+}
+
+/** Execution owns the result while collecting output, accounting and acceptance evidence. */
+export interface SingleResult {
+  accounting?: { readonly state: "complete" | "incomplete"; readonly error?: string };
+  nativeSessionId?: string;
+  terminalLeafId?: string | null;
+  terminalEntryId?: string;
+  auditPath?: string;
+  fullOutputPath?: string;
+  initialOutputPath?: string;
+  auditSaveError?: string;
+  agent: string;
+  agentProcessExit?: AgentProcessExit;
+  task: string;
+  exitCode: number;
+  detached?: boolean;
+  detachedReason?: string;
+  interrupted?: boolean;
+  timedOut?: boolean;
+  resourceLimitExceeded?: ResourceLimitExceeded;
+  messages?: readonly ObservedMessage[];
+  usage: Usage;
+  model?: string;
+  attemptedModels?: readonly string[];
+  modelAttempts?: readonly ModelAttempt[];
+  controlEvents?: readonly ControlEvent[];
+  error?: string;
+  sessionFile?: string;
+  skills?: readonly string[];
+  skillsWarning?: string;
+  progress?: AgentProgress;
+  progressSummary?: ProgressSummary;
+  toolCalls?: readonly ToolCallSummary[];
+  artifactPaths?: ArtifactPaths;
+  truncation?: TruncationResult;
+  finalOutput?: string;
+  initialOutput?: string;
+  outputMode?: OutputMode;
+  savedOutputPath?: string;
+  outputReference?: SavedOutputReference;
+  outputSaveError?: string;
+  outputCleanup?: {
+    readonly path: string;
+    readonly action: "deleted" | "already-missing" | "skipped";
+    readonly reason?: string;
+    readonly error?: string;
+  };
+  structuredOutput?: unknown;
+  structuredOutputPath?: string;
+  structuredOutputSchemaPath?: string;
+  acceptance?: AcceptanceLedger;
+}
+
+export type ReadonlySingleResult = ReadonlyInput<SingleResult>;
+
+export type DisplayItem =
+  | { readonly type: "text"; readonly text: string }
+  | {
+      readonly type: "tool";
+      readonly name: string;
+      readonly args: Readonly<Record<string, unknown>>;
+    };
+
+export interface ErrorInfo {
+  readonly hasError: boolean;
+  readonly exitCode?: number;
+  readonly errorType?: string;
+  readonly details?: string;
+}

package/src/shared/types/state.ts

@@ -0,0 +1,56 @@
+import type { FSWatcher } from "node:fs";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AsyncJobState, ReadonlyAsyncJobState } from "./async.ts";
+import type { HistoryIndexHandle } from "./history.ts";
+import type {
+  ForegroundResumeRun,
+  OwnedRun,
+  ReadonlyForegroundResumeRun,
+  TrackedOwnedRun,
+} from "./owned-runs.ts";
+
+/** Session lifecycle owner. Only owner boundaries may update maps, timers, handles and projections. */
+export interface SubagentState {
+  baseCwd: string;
+  currentSessionId: string | null;
+  asyncJobs: Map<string, AsyncJobState>;
+  waitingRuns?: Map<string, number>;
+  isRunResultConsumed?: (runId: string) => boolean;
+  foregroundRuns?: Map<string, ForegroundResumeRun>;
+  ownedRuns?: Map<string, TrackedOwnedRun>;
+  historyIndex?: HistoryIndexHandle;
+  historyReady?: Promise<void>;
+  historyClosing?: Promise<void>;
+  persistOwnedRun?: (run: OwnedRun) => void;
+  onRunsChanged?: () => void;
+  cleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
+  lastUiContext: ExtensionContext | null;
+  poller: NodeJS.Timeout | null;
+  completionSeen: Map<string, number>;
+  watcher: FSWatcher | null;
+  watcherRestartTimer: ReturnType<typeof setTimeout> | null;
+  resultFileCoalescer: {
+    readonly schedule: (file: string, delayMs?: number) => boolean;
+    readonly clear: () => void;
+  };
+}
+
+/** Read-only application state around genuine native handles, which retain their SDK contracts. */
+export type ReadonlySubagentState = Readonly<
+  Omit<
+    SubagentState,
+    | "asyncJobs"
+    | "waitingRuns"
+    | "foregroundRuns"
+    | "ownedRuns"
+    | "cleanupTimers"
+    | "completionSeen"
+  >
+> & {
+  readonly asyncJobs: Readonly<ReadonlyMap<string, ReadonlyAsyncJobState>>;
+  readonly waitingRuns?: Readonly<ReadonlyMap<string, number>>;
+  readonly foregroundRuns?: Readonly<ReadonlyMap<string, ReadonlyForegroundResumeRun>>;
+  readonly ownedRuns?: Readonly<ReadonlyMap<string, OwnedRun>>;
+  readonly cleanupTimers: Readonly<ReadonlyMap<string, ReturnType<typeof setTimeout>>>;
+  readonly completionSeen: Readonly<ReadonlyMap<string, number>>;
+};

package/src/shared/types/usage.ts

@@ -0,0 +1,36 @@
+import type { ObservedUsage } from "./messages.ts";
+
+export interface UsageContribution {
+  readonly id: string;
+  /** Native tool and summary usage may not carry model attribution. */
+  readonly provider?: string;
+  readonly model?: string;
+  readonly usage: ObservedUsage;
+}
+
+export interface Usage {
+  readonly contributions?: readonly UsageContribution[];
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+  readonly cost: number;
+  readonly turns: number;
+}
+
+/** The billing reducer owns these counters and appends immutable contribution snapshots. */
+export interface UsageAccumulator {
+  contributions?: UsageContribution[];
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  turns: number;
+}
+
+export interface TokenUsage {
+  readonly input: number;
+  readonly output: number;
+  readonly total: number;
+}