@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/shared/types/acceptance.ts

@@ -0,0 +1,149 @@
+/** Acceptance configuration and recorded evidence, independent of execution and verification code. */
+export type AcceptanceProvenanceLevel = "none" | "attested" | "checked" | "verified";
+
+export type AcceptanceEvidenceKind =
+  | "changed-files"
+  | "tests-added"
+  | "commands-run"
+  | "validation-output"
+  | "residual-risks"
+  | "no-staged-files"
+  | "diff-summary"
+  | "review-findings"
+  | "manual-notes";
+
+export interface AcceptanceGate {
+  readonly id: string;
+  readonly must: string;
+  readonly evidence?: readonly AcceptanceEvidenceKind[];
+  readonly severity?: "required" | "recommended";
+}
+
+export interface AcceptanceVerifyCommand {
+  readonly id: string;
+  readonly command: string;
+  readonly timeoutMs?: number;
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly allowFailure?: boolean;
+}
+
+export interface AcceptanceConfig {
+  readonly criteria?: readonly (string | AcceptanceGate)[];
+  readonly evidence?: readonly AcceptanceEvidenceKind[];
+  readonly verify?: readonly AcceptanceVerifyCommand[];
+  readonly stopRules?: readonly string[];
+  readonly maxFinalizationTurns?: number;
+}
+
+export type AcceptanceInput = AcceptanceConfig;
+
+export interface ResolvedAcceptanceGate extends AcceptanceGate {
+  readonly id: string;
+  readonly must: string;
+  readonly evidence: readonly AcceptanceEvidenceKind[];
+  readonly severity: "required" | "recommended";
+}
+
+export interface ResolvedAcceptanceConfig {
+  readonly level: AcceptanceProvenanceLevel;
+  readonly explicit: boolean;
+  readonly inferredReason: readonly string[];
+  readonly criteria: readonly ResolvedAcceptanceGate[];
+  readonly evidence: readonly AcceptanceEvidenceKind[];
+  readonly verify: readonly AcceptanceVerifyCommand[];
+  readonly stopRules: readonly string[];
+  readonly finalization: {
+    readonly mode: "none" | "self-review-loop";
+    readonly maxTurns: number;
+  };
+}
+
+export interface AcceptanceReport {
+  readonly criteriaSatisfied?: readonly {
+    readonly id?: string;
+    readonly status: "satisfied" | "not-satisfied" | "not-applicable" | "blocked";
+    readonly evidence: string;
+    readonly humanAction?: string;
+  }[];
+  readonly changedFiles?: readonly string[];
+  readonly testsAddedOrUpdated?: readonly string[];
+  readonly commandsRun?: readonly {
+    readonly command: string;
+    readonly result: "passed" | "failed" | "not-run";
+    readonly summary: string;
+  }[];
+  readonly validationOutput?: readonly string[];
+  readonly residualRisks?: readonly string[];
+  readonly noStagedFiles?: boolean;
+  readonly diffSummary?: string;
+  readonly reviewFindings?: readonly (string | Readonly<Record<string, unknown>>)[];
+  readonly manualNotes?: string;
+  readonly notes?: string;
+}
+
+export type AcceptanceRuntimeCheckStatus = "passed" | "failed" | "blocked" | "not-applicable";
+
+export interface AcceptanceRuntimeCheck {
+  readonly id: string;
+  readonly status: AcceptanceRuntimeCheckStatus;
+  readonly message: string;
+}
+
+export interface AcceptanceVerifyResult {
+  readonly id: string;
+  readonly command: string;
+  readonly cwd?: string;
+  readonly exitCode: number | null;
+  readonly status: "passed" | "failed" | "timed-out" | "allowed-failure";
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly durationMs: number;
+}
+
+export type AcceptanceLedgerStatus =
+  | "not-required"
+  | "claimed"
+  | "attested"
+  | "checked"
+  | "verified"
+  | "accepted"
+  | "blocked"
+  | "rejected";
+
+export interface AcceptanceFinalizationTurn {
+  readonly turn: number;
+  readonly prompt: string;
+  readonly status: AcceptanceLedgerStatus;
+  readonly rawOutput?: string;
+  readonly unconfirmedOutput?: string;
+  readonly report?: AcceptanceReport;
+  readonly parseError?: string;
+  readonly runtimeChecks: readonly AcceptanceRuntimeCheck[];
+  readonly verifyRuns: readonly AcceptanceVerifyResult[];
+  readonly failureMessage?: string;
+}
+
+export interface AcceptanceFinalizationLedger {
+  readonly mode: "self-review-loop";
+  readonly status: "not-run" | "completed" | "blocked" | "failed";
+  readonly maxTurns: number;
+  readonly turns: readonly AcceptanceFinalizationTurn[];
+}
+
+export interface AcceptanceLedger {
+  readonly status: AcceptanceLedgerStatus;
+  readonly explicit: boolean;
+  readonly effectiveAcceptance: ResolvedAcceptanceConfig;
+  readonly inferredReason: readonly string[];
+  readonly criteria: readonly ResolvedAcceptanceGate[];
+  readonly childReport?: AcceptanceReport;
+  readonly childReportParseError?: string;
+  readonly initialChildReport?: AcceptanceReport;
+  readonly initialChildReportParseError?: string;
+  /** Prior full report retained as audit evidence, never as current acceptance. */
+  readonly unconfirmedOutput?: string;
+  readonly runtimeChecks: readonly AcceptanceRuntimeCheck[];
+  readonly verifyRuns: readonly AcceptanceVerifyResult[];
+  readonly finalization?: AcceptanceFinalizationLedger;
+}

package/src/shared/types/async.ts

@@ -0,0 +1,247 @@
+import type { AcceptanceLedger } from "./acceptance.ts";
+import type { ActivityState, MaxOutputConfig } from "./config.ts";
+import type { ReadonlyInput } from "./inputs.ts";
+import type { AsyncParallelGroupStatus, NestedRouteInfo, NestedRunSummary } from "./nested.ts";
+import type { SubagentRunMode } from "./progress.ts";
+import type {
+  AgentProcessExit,
+  ArtifactPaths,
+  ModelAttempt,
+  ResourceLimitExceeded,
+  SingleResult,
+} from "./results.ts";
+import type { TokenUsage, Usage } from "./usage.ts";
+import type { ChainOutputMap, WorkflowGraphSnapshot } from "./workflow.ts";
+
+export type AsyncResultTerminalState = "complete" | "failed" | "blocked" | "paused";
+
+export interface AsyncResultChild extends Partial<
+  Pick<
+    SingleResult,
+    | "task"
+    | "finalOutput"
+    | "initialOutput"
+    | "outputMode"
+    | "savedOutputPath"
+    | "outputReference"
+    | "outputSaveError"
+    | "outputCleanup"
+    | "toolCalls"
+    | "progressSummary"
+    | "truncation"
+    | "skills"
+    | "skillsWarning"
+    | "accounting"
+    | "nativeSessionId"
+    | "terminalLeafId"
+    | "terminalEntryId"
+    | "auditPath"
+    | "auditSaveError"
+    | "fullOutputPath"
+    | "initialOutputPath"
+  >
+> {
+  usage?: Usage;
+  timedOut?: boolean;
+  agent?: string;
+  agentProcessExit?: AgentProcessExit;
+  exitCode?: number | null;
+  output?: string;
+  error?: string;
+  success?: boolean;
+  skipped?: boolean;
+  sessionFile?: string;
+  intercomTarget?: string;
+  model?: string;
+  attemptedModels?: readonly string[];
+  modelAttempts?: readonly ModelAttempt[];
+  artifactPaths?: Partial<ArtifactPaths>;
+  truncated?: boolean;
+  structuredOutput?: unknown;
+  structuredOutputPath?: string;
+  structuredOutputSchemaPath?: string;
+  acceptance?: AcceptanceLedger;
+  resourceLimitExceeded?: ResourceLimitExceeded;
+  interrupted?: boolean;
+  children?: unknown;
+}
+
+export interface AsyncResultFile {
+  legacySource?: string;
+  /** Saved legacy results remain readable until their v3 publication replaces them. */
+  recordVersion?: 1 | 2 | 3;
+  completionId?: string;
+  maxOutput?: MaxOutputConfig;
+  error?: string;
+  runtimeVersion?: 2;
+  timedOut?: boolean;
+  id?: string;
+  runId?: string;
+  agent?: string;
+  mode?: SubagentRunMode;
+  success?: boolean;
+  state?: string;
+  summary?: string;
+  results?: AsyncResultChild[];
+  outputs?: ChainOutputMap;
+  workflowGraph?: WorkflowGraphSnapshot;
+  exitCode?: number;
+  timestamp?: number;
+  durationMs?: number;
+  truncated?: boolean;
+  artifactsDir?: string;
+  cwd?: string;
+  asyncDir?: string;
+  sessionId?: string;
+  sessionFile?: string;
+  intercomTarget?: string;
+  shareUrl?: string;
+  gistUrl?: string;
+  shareError?: string;
+  taskIndex?: number;
+  totalTasks?: number;
+  nestedChildren?: unknown;
+}
+
+export interface AsyncStartedEvent {
+  readonly id?: string;
+  readonly asyncDir?: string;
+  readonly pid?: number;
+  readonly sessionId?: string;
+  readonly mode?: SubagentRunMode;
+  readonly agent?: string;
+  readonly agents?: readonly string[];
+  readonly chain?: readonly string[];
+  readonly chainStepCount?: number;
+  readonly parallelGroups?: readonly AsyncParallelGroupStatus[];
+  readonly workflowGraph?: WorkflowGraphSnapshot;
+  readonly nestedRoute?: NestedRouteInfo;
+}
+
+/** Mutable producer-side status projection. Readers consume ReadonlyAsyncStatus. */
+export interface AsyncStatus {
+  runtimeVersion?: 2;
+  error?: string;
+  timeoutAt?: number;
+  timedOut?: boolean;
+  runId: string;
+  indexedControl?: boolean;
+  controlRequestFiles?: boolean;
+  sessionId?: string;
+  mode: SubagentRunMode;
+  state: "queued" | "running" | "complete" | "failed" | "blocked" | "paused";
+  activityState?: ActivityState;
+  lastActivityAt?: number;
+  currentTool?: string;
+  currentToolStartedAt?: number;
+  currentPath?: string;
+  turnCount?: number;
+  toolCount?: number;
+  startedAt: number;
+  endedAt?: number;
+  lastUpdate?: number;
+  pid?: number;
+  cwd?: string;
+  currentStep?: number;
+  chainStepCount?: number;
+  parallelGroups?: readonly AsyncParallelGroupStatus[];
+  workflowGraph?: WorkflowGraphSnapshot;
+  steps?: Array<{
+    agent: string;
+    phase?: string;
+    label?: string;
+    outputName?: string;
+    structured?: boolean;
+    status:
+      | "pending"
+      | "running"
+      | "complete"
+      | "completed"
+      | "failed"
+      | "blocked"
+      | "paused"
+      | "timed-out";
+    children?: readonly NestedRunSummary[];
+    sessionFile?: string;
+    activityState?: ActivityState;
+    lastActivityAt?: number;
+    currentTool?: string;
+    currentToolArgs?: string;
+    streamingText?: string;
+    currentToolStartedAt?: number;
+    currentPath?: string;
+    recentTools?: readonly {
+      readonly tool: string;
+      readonly args: string;
+      readonly endMs: number;
+    }[];
+    recentOutput?: readonly string[];
+    turnCount?: number;
+    toolCount?: number;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    exitCode?: number | null;
+    agentProcessExit?: AgentProcessExit;
+    tokens?: TokenUsage;
+    skills?: readonly string[];
+    model?: string;
+    thinking?: string;
+    modelStartedAt?: number;
+    attemptedModels?: readonly string[];
+    modelAttempts?: readonly ModelAttempt[];
+    error?: string;
+    structuredOutput?: unknown;
+    structuredOutputPath?: string;
+    structuredOutputSchemaPath?: string;
+    acceptance?: AcceptanceLedger;
+    resourceLimitExceeded?: ResourceLimitExceeded;
+  }>;
+  sessionDir?: string;
+  outputFile?: string;
+  totalTokens?: TokenUsage;
+  sessionFile?: string;
+  outputs?: ChainOutputMap;
+}
+
+export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & { index?: number };
+
+/** The async tracker owns the current job projection and its mutable step collection. */
+export interface AsyncJobState {
+  asyncId: string;
+  asyncDir: string;
+  status: "queued" | "running" | "complete" | "failed" | "blocked" | "paused";
+  pid?: number;
+  sessionId?: string;
+  activityState?: ActivityState;
+  lastActivityAt?: number;
+  currentTool?: string;
+  currentToolStartedAt?: number;
+  currentPath?: string;
+  turnCount?: number;
+  toolCount?: number;
+  mode?: SubagentRunMode;
+  agents?: readonly string[];
+  currentStep?: number;
+  chainStepCount?: number;
+  parallelGroups?: readonly AsyncParallelGroupStatus[];
+  steps?: AsyncJobStep[];
+  stepsTotal?: number;
+  runningSteps?: number;
+  completedSteps?: number;
+  activeParallelGroup?: boolean;
+  startedAt?: number;
+  updatedAt?: number;
+  totalTokens?: TokenUsage;
+  sessionFile?: string;
+  controlEventCursor?: number;
+  controlEventIdentity?: string;
+  controlEventSince?: number;
+  nestedRoute?: NestedRouteInfo;
+  nestedChildren?: readonly NestedRunSummary[];
+}
+
+export type ReadonlyAsyncResultChild = ReadonlyInput<AsyncResultChild>;
+export type ReadonlyAsyncResultFile = ReadonlyInput<AsyncResultFile>;
+export type ReadonlyAsyncStatus = ReadonlyInput<AsyncStatus>;
+export type ReadonlyAsyncJobState = ReadonlyInput<AsyncJobState>;

package/src/shared/types/config.ts

@@ -0,0 +1,139 @@
+/** Configuration data is caller-owned. Resolution constructs new values rather than mutating inputs. */
+import type { AcceptanceInput } from "./acceptance.ts";
+
+export interface MaxOutputConfig {
+  readonly bytes?: number;
+  readonly lines?: number;
+}
+
+export type OutputMode = "inline" | "file-only";
+export type JsonSchemaObject = Readonly<Record<string, unknown>>;
+export type ChildProjectTrustPolicy = "inherit" | "approve" | "no-approve";
+export type ActivityState = "needs_attention";
+export type ControlEventType = "needs_attention";
+export type ControlNotificationChannel = "event" | "async" | "intercom";
+
+export interface ControlConfig {
+  readonly enabled?: boolean;
+  readonly needsAttentionAfterMs?: number;
+  readonly failedToolAttemptsBeforeAttention?: number;
+  readonly notifyOn?: readonly ControlEventType[];
+  readonly notifyChannels?: readonly ControlNotificationChannel[];
+}
+
+export interface ResolvedControlConfig {
+  readonly enabled: boolean;
+  readonly needsAttentionAfterMs: number;
+  readonly failedToolAttemptsBeforeAttention: number;
+  readonly notifyOn: readonly ControlEventType[];
+  readonly notifyChannels: readonly ControlNotificationChannel[];
+}
+
+export interface ProjectTrustConfig {
+  readonly childRuns?: ChildProjectTrustPolicy;
+}
+
+interface TopLevelParallelConfig {
+  readonly maxTasks?: number;
+  readonly concurrency?: number;
+}
+
+interface ExtensionChainConfig {
+  readonly dynamicFanout?: { readonly maxItems?: number };
+}
+
+export interface ExtensionConfig {
+  /** Start authorized children with everyday tools; false restores the full subagent-only surface. */
+  readonly compactChildTools?: boolean;
+  readonly asyncByDefault?: boolean;
+  readonly forceTopLevelAsync?: boolean;
+  readonly defaultSessionDir?: string;
+  readonly maxSubagentDepth?: number;
+  readonly control?: ControlConfig;
+  readonly parallel?: TopLevelParallelConfig;
+  readonly chain?: ExtensionChainConfig;
+  readonly worktreeSetupHook?: string;
+  readonly worktreeSetupHookTimeoutMs?: number;
+  readonly projectTrust?: ChildProjectTrustPolicy | ProjectTrustConfig;
+}
+
+export type AgentScope = "user" | "project" | "both";
+export type AgentSource = "builtin" | "package" | "user" | "project";
+export type SystemPromptMode = "append" | "replace";
+export type AgentDefaultContext = "fresh" | "fork";
+
+export interface AgentConfig {
+  readonly name: string;
+  readonly localName?: string;
+  readonly packageName?: string;
+  readonly description: string;
+  readonly tools?: readonly string[];
+  readonly mcpDirectTools?: readonly string[];
+  readonly allowSubagents?: boolean;
+  readonly model?: string;
+  readonly fallbackModels?: readonly string[];
+  readonly thinking?: string;
+  readonly systemPromptMode: SystemPromptMode;
+  readonly inheritProjectContext: boolean;
+  readonly inheritSkills: boolean;
+  readonly defaultContext?: AgentDefaultContext;
+  readonly systemPrompt: string;
+  readonly source: AgentSource;
+  readonly filePath: string;
+  readonly skills?: readonly string[];
+  readonly extensions?: readonly string[];
+  readonly output?: string;
+  readonly defaultReads?: readonly string[];
+  readonly defaultProgress?: boolean;
+  readonly interactive?: boolean;
+  readonly maxSubagentDepth?: number;
+  readonly maxExecutionTimeMs?: number;
+  readonly maxTokens?: number;
+  readonly completionGuard?: boolean;
+  readonly disabled?: boolean;
+  readonly extraFields?: Readonly<Record<string, string>>;
+}
+
+export interface ChainStepConfig {
+  readonly agent?: string;
+  readonly task?: string;
+  readonly phase?: string;
+  readonly label?: string;
+  readonly as?: string;
+  readonly outputSchema?: string | JsonSchemaObject;
+  readonly output?: string | false;
+  readonly outputMode?: OutputMode;
+  readonly reads?: readonly string[] | false;
+  readonly model?: string;
+  readonly skills?: readonly string[] | false;
+  readonly progress?: boolean;
+  readonly parallel?: unknown;
+  readonly expand?: unknown;
+  readonly collect?: unknown;
+  readonly concurrency?: number;
+  readonly failFast?: boolean;
+  readonly worktree?: boolean;
+  readonly acceptance?: AcceptanceInput;
+}
+
+export interface ChainConfig {
+  readonly name: string;
+  readonly localName?: string;
+  readonly packageName?: string;
+  readonly description: string;
+  readonly source: AgentSource;
+  readonly filePath: string;
+  readonly steps: readonly ChainStepConfig[];
+  readonly extraFields?: Readonly<Record<string, string>>;
+}
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type ThinkingLevelMap = Readonly<Partial<Record<ThinkingLevel, string | null>>>;
+
+export interface ModelInfo {
+  readonly provider: string;
+  readonly id: string;
+  readonly fullId: string;
+  readonly reasoning?: boolean;
+  readonly thinkingLevelMap?: ThinkingLevelMap;
+}

package/src/shared/types/details.ts

@@ -0,0 +1,104 @@
+import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
+import type { HistoryFreshness, HistoryPage, HistorySearchPage } from "./history.ts";
+import type { ReadonlyInput } from "./inputs.ts";
+import type { ManagementControl, OwnedRunView } from "./owned-runs.ts";
+import type {
+  AgentProgress,
+  ControlEvent,
+  ProgressSummary,
+  SubagentResultStatus,
+  SubagentRunMode,
+} from "./progress.ts";
+import type { SupervisorQuestionSummary } from "./questions.ts";
+import type { ArtifactPaths, SingleResult } from "./results.ts";
+import type { UsageContribution } from "./usage.ts";
+import type { ChainOutputMap, WorkflowGraphSnapshot } from "./workflow.ts";
+
+/** Mutable assembly owner. Publish a ReadonlyDetails view without copying live progress sources. */
+export interface Details {
+  accounting?: { readonly state: "incomplete"; readonly error: string };
+  mode: SubagentRunMode | "management";
+  /** Receipt only on native tool result with matching top-level usage. */
+  parentUsage?: { readonly contributions: readonly UsageContribution[] };
+  runId?: string;
+  context?: "fresh" | "fork";
+  results: SingleResult[];
+  controlEvents?: readonly ControlEvent[];
+  asyncId?: string;
+  asyncDir?: string;
+  asyncPid?: number;
+  shareUrl?: string;
+  gistUrl?: string;
+  shareError?: string;
+  progress?: AgentProgress[];
+  progressSummary?: ProgressSummary;
+  intercomTargets?: readonly string[];
+  managementControl?: ManagementControl;
+  managementControls?: readonly ManagementControl[];
+  questions?: readonly SupervisorQuestionSummary[];
+  questionList?: {
+    readonly total: number;
+    readonly offset: number;
+    readonly limit: number;
+    readonly nextOffset?: number;
+  };
+  wait?: {
+    readonly runId: string;
+    readonly completionId?: string;
+    readonly index?: number;
+    readonly status: "completed" | "cancelled" | "yielded" | "awaiting_input" | "unavailable";
+  };
+  run?: OwnedRunView;
+  runs?: readonly (Pick<
+    OwnedRunView,
+    | "runId"
+    | "source"
+    | "mode"
+    | "cwd"
+    | "task"
+    | "state"
+    | "updatedAt"
+    | "attention"
+    | "review"
+    | "rootRunId"
+    | "predecessorRunId"
+    | "predecessorIndex"
+  > & { readonly summary?: string; readonly continuations?: readonly string[] })[];
+  runList?: {
+    readonly total: number;
+    readonly offset: number;
+    readonly limit: number;
+    readonly nextOffset?: number;
+    readonly nextCursor?: string;
+    readonly version: number;
+    readonly freshness: HistoryFreshness;
+  };
+  history?: HistoryPage;
+  historySearch?: HistorySearchPage;
+  intercomDelivery?: {
+    readonly delivered: boolean;
+    readonly to: string;
+    readonly status: SubagentResultStatus;
+    readonly summary: string;
+  };
+  artifacts?: { readonly dir: string; readonly files: readonly ArtifactPaths[] };
+  truncation?: {
+    readonly truncated: boolean;
+    readonly originalBytes?: number;
+    readonly originalLines?: number;
+    readonly artifactPath?: string;
+  };
+  chainAgents?: readonly string[];
+  totalSteps?: number;
+  currentStepIndex?: number;
+  workflowGraph?: WorkflowGraphSnapshot;
+  outputs?: ChainOutputMap;
+}
+
+export type ReadonlyDetails = ReadonlyInput<Details>;
+
+/** Native result envelope with an application-owned readonly details snapshot. */
+export type SubagentExecutionResult = AgentToolResult<ReadonlyDetails>;
+
+/** Native streaming callback; its supplied result has the same published details contract. */
+export type SubagentExecutionUpdateCallback = AgentToolUpdateCallback<ReadonlyDetails>;