@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/shared/types/history.ts

@@ -0,0 +1,217 @@
+import type { AcceptanceLedgerStatus } from "./acceptance.ts";
+import type {
+  ManagementRunState,
+  OwnedRun,
+  OwnedRunView,
+  ReadonlyForegroundResumeRun,
+} from "./owned-runs.ts";
+import type { SupervisorQuestionView } from "./questions.ts";
+
+export interface HistoryOwner {
+  readonly ownerSessionId: string;
+  readonly ownerSessionFile?: string;
+  readonly runs: readonly OwnedRun[];
+  readonly foregroundRuns?: readonly ReadonlyForegroundResumeRun[];
+}
+
+export interface HistoryFreshness {
+  /** Browse observations only; never proof of completion, ownership, or receipt absence. */
+  readonly authoritative: false;
+  readonly state: "current" | "catching-up" | "degraded";
+  readonly pending: number;
+  readonly errors: number;
+  readonly indexedAt: number | null;
+}
+
+export interface HistoryVersion {
+  readonly version: number;
+  readonly indexedAt: number | null;
+  readonly freshness: HistoryFreshness;
+}
+
+export interface HistoryConfiguration {
+  readonly model?: string;
+  readonly thinking?: string;
+  readonly modelRecordedAt?: number;
+}
+
+export interface HistoryRunRow extends OwnedRunView {
+  readonly summary?: string;
+  readonly questions?: readonly SupervisorQuestionView[];
+  /** Children satisfying the combined filters, before run pagination. */
+  readonly matchedChildIndexes?: readonly number[];
+  readonly children: readonly (OwnedRunView["children"][number] & {
+    readonly savedConfiguration?: HistoryConfiguration;
+    readonly nativeConfiguration?: HistoryConfiguration;
+    readonly humanAction?: string;
+    readonly acceptanceStatus?: AcceptanceLedgerStatus;
+  })[];
+}
+
+export interface HistoryRunOptions {
+  readonly offset?: number;
+  readonly limit?: number;
+  readonly cursor?: string;
+  readonly sort?: "attention" | "newest" | "oldest";
+  readonly agent?: string;
+  readonly state?: ManagementRunState;
+  readonly text?: string;
+  /** Hide only child attempts superseded by an admitted continuation. */
+  readonly latestTasksOnly?: boolean;
+  readonly signal?: AbortSignal;
+}
+
+export interface HistoryRunPage extends HistoryVersion {
+  readonly rows: readonly HistoryRunRow[];
+  readonly total: number;
+  readonly offset: number;
+  readonly nextOffset?: number;
+  readonly nextCursor?: string;
+}
+
+export interface HistoryByteRef {
+  readonly sourceId: string;
+  readonly generation: number;
+  readonly start: number;
+  readonly end: number;
+  readonly digest: string;
+}
+
+export interface HistoryEntry {
+  readonly id: string;
+  /** Missing in older journals; id then identifies the physical byte range. */
+  readonly nativeId: string | null;
+  readonly parentId: string | null;
+  readonly sequence: number;
+  readonly timestamp: number | null;
+  readonly type: string;
+  readonly ref: HistoryByteRef;
+  /** Bounded previews; untrusted detail values require narrowing at their consumer. */
+  readonly entry: Readonly<Record<string, unknown>>;
+}
+
+export interface HistoryPageInput {
+  readonly runId: string;
+  readonly index: number;
+  readonly limit?: number;
+  readonly before?: number;
+  readonly after?: number;
+  readonly cursor?: string;
+  readonly terminalEntryId?: string;
+  readonly endedAt?: number;
+  /** Configuration ancestry; null is an intentionally empty branch. */
+  readonly leaf?: string | null;
+  readonly messageIds?: readonly string[];
+  readonly readThrough?: string | null;
+  readonly signal?: AbortSignal;
+}
+
+export interface HistoryPage extends HistoryVersion {
+  readonly entries: readonly HistoryEntry[];
+  readonly count: number;
+  readonly hasMore: boolean;
+  readonly previousBefore?: number;
+  readonly previousCursor?: string;
+  readonly nextAfter?: number;
+  readonly sourceId: string | null;
+  readonly generation: number | null;
+  readonly sessionId: string | null;
+  readonly sourceState: string;
+  readonly configuration: HistoryConfiguration;
+  readonly deliveredMessages: readonly (readonly [string, boolean])[];
+  readonly latestEntryId: string | null;
+  readonly unreadAfter?: boolean;
+  readonly terminalSequence?: number;
+  /** Canonical answer match, not a truncated-preview comparison. */
+  readonly finalResultId?: string;
+  readonly unavailable?: string;
+}
+
+export interface HistoryResult {
+  readonly text: string;
+  readonly timestamp: number;
+  readonly finalResultId?: string;
+}
+
+export interface HistorySearchInput {
+  /** AND tokens or quoted phrase; at most 12 tokens, no operators/prefixes. */
+  readonly query: string;
+  readonly runId?: string;
+  readonly index?: number;
+  readonly limit?: number;
+  readonly cursor?: string;
+  readonly sort?: "relevance" | "newest";
+  readonly agent?: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface HistorySearchMatch {
+  readonly id: number;
+  readonly runId: string;
+  readonly index: number;
+  readonly agent: string;
+  readonly entryId: string;
+  readonly nativeId: string | null;
+  readonly sessionId: string | null;
+  readonly sessionFile: string;
+  readonly timestamp: number | null;
+  readonly ref: HistoryByteRef;
+  /** Indexed excerpt, not an authoritative/validated full record. */
+  readonly preview: string;
+  readonly field: string;
+  readonly textStart: number;
+  readonly textEnd: number;
+  readonly score: number;
+}
+
+export interface HistorySearchPage extends HistoryVersion {
+  readonly matches: readonly HistorySearchMatch[];
+  readonly nextCursor?: string;
+}
+
+export interface HistoryEntryInput {
+  readonly runId: string;
+  readonly index: number;
+  readonly entryId?: string;
+  readonly ref?: HistoryByteRef;
+  readonly toolCallId?: string;
+  readonly kind?: "call" | "result";
+  readonly terminalEntryId?: string;
+  readonly endedAt?: number;
+  readonly signal?: AbortSignal;
+}
+
+export interface HistoryIndexStatus extends HistoryVersion {
+  readonly databaseFile: string;
+  readonly physicalSources: number;
+  readonly publishedEntries: number;
+  readonly operations: {
+    readonly sourceChecks: number;
+    readonly sourceOpens: number;
+    readonly sourceBytesRead: number;
+    readonly runProjections: number;
+    readonly queries: number;
+  };
+}
+
+/** Public process-owner capability contract; the type model never imports the index implementation. */
+export interface HistoryIndexHandle {
+  /** Diagnostic view of the original failure; reading the capability must not permit error mutation. */
+  readonly failure: Readonly<Error> | undefined;
+  readonly setOwner: (input: HistoryOwner) => Promise<void>;
+  readonly updateRun: (run: OwnedRun, foreground?: ReadonlyForegroundResumeRun) => Promise<void>;
+  readonly needsControls: () => Promise<boolean>;
+  readonly listRuns: (options?: HistoryRunOptions) => Promise<HistoryRunPage>;
+  readonly historyPage: (input: HistoryPageInput) => Promise<HistoryPage>;
+  readonly search: (input: HistorySearchInput) => Promise<HistorySearchPage>;
+  readonly status: () => Promise<HistoryIndexStatus>;
+  readonly entry: (input: HistoryEntryInput) => Promise<HistoryEntry | null>;
+  readonly record: (input: HistoryEntryInput) => Promise<Record<string, unknown> | null>;
+  readonly result: (
+    input: Pick<HistoryEntryInput, "runId" | "index" | "signal">,
+  ) => Promise<HistoryResult | null>;
+  readonly refresh: (runId?: string, options?: { readonly signal?: AbortSignal }) => Promise<void>;
+  readonly onChanged: (listener: () => void) => () => void;
+  readonly cancel: () => void;
+  readonly close: () => Promise<void>;
+}

package/src/shared/types/inputs.ts

@@ -0,0 +1,4 @@
+import type { ReadonlyDeep } from "type-fest";
+
+/** Read-only consumer view of application-owned data; does not freeze the live owner. */
+export type ReadonlyInput<T> = ReadonlyDeep<T>;

package/src/shared/types/intercom.ts

@@ -0,0 +1,57 @@
+import type { PublicNestedRunSummary } from "./nested.ts";
+import type { SubagentResultStatus, SubagentRunMode } from "./progress.ts";
+
+export interface SubagentResultIntercomChild {
+  readonly agent: string;
+  readonly status: SubagentResultStatus;
+  readonly summary: string;
+  readonly index?: number;
+  readonly artifactPath?: string;
+  readonly metadataPath?: string;
+  readonly sessionPath?: string;
+  readonly intercomTarget?: string;
+  readonly children?: readonly PublicNestedRunSummary[];
+}
+
+export interface SubagentResultIntercomPayload {
+  readonly completionId?: string;
+  readonly to: string;
+  readonly message: string;
+  readonly requestId?: string;
+  readonly runId: string;
+  readonly mode: SubagentRunMode;
+  readonly status: SubagentResultStatus;
+  readonly summary: string;
+  readonly error?: string;
+  readonly source: "foreground" | "async";
+  readonly children: readonly SubagentResultIntercomChild[];
+  readonly resultPath?: string;
+  readonly asyncId?: string;
+  readonly asyncDir?: string;
+  readonly chainSteps?: number;
+  readonly agent?: string;
+  readonly index?: number;
+  readonly artifactPath?: string;
+  readonly sessionPath?: string;
+}
+
+export interface IntercomEventBus {
+  readonly on: (channel: string, handler: (data: unknown) => void) => () => void;
+  readonly emit: (channel: string, data: unknown) => void;
+}
+
+export interface SubagentIntercomConnection {
+  readonly status: "connected" | "disconnected" | "connecting" | "unknown";
+  readonly sessionId?: string;
+  readonly reason?: string;
+}
+
+export interface SubagentLiveIntercomHealth {
+  readonly target: string;
+  readonly status: "registered" | "none" | "missing" | "ambiguous" | "prefix_too_short";
+  readonly sessionId?: string;
+  readonly sessionName?: string;
+  readonly sessionStatus?: string;
+  readonly acceptsAsks?: boolean;
+  readonly pendingAsks?: number;
+}

package/src/shared/types/launch.ts

@@ -0,0 +1,39 @@
+import type { ResolvedAcceptanceConfig } from "./acceptance.ts";
+import type {
+  AgentConfig,
+  ChildProjectTrustPolicy,
+  JsonSchemaObject,
+  MaxOutputConfig,
+  OutputMode,
+  ResolvedControlConfig,
+} from "./config.ts";
+
+/** Persisted launch snapshot. Resume consumers must not modify the original launch. */
+export interface SavedLaunchConfig {
+  readonly agent: AgentConfig;
+  readonly model?: string;
+  readonly thinking?: string;
+  /** Timestamp of the native model entry captured with this frozen launch. */
+  readonly modelRecordedAt?: number;
+  readonly modelCandidates: readonly string[];
+  readonly artifacts: boolean;
+  readonly artifactsDir?: string;
+  readonly share: boolean;
+  readonly systemPrompt: string;
+  readonly skills: readonly string[];
+  readonly cwd: string;
+  readonly context: "fresh" | "fork";
+  readonly output: string | false;
+  /** Proven generated output filename; absent on legacy snapshots. */
+  readonly generatedOutputFilename?: string;
+  readonly outputMode: OutputMode;
+  readonly outputSchema?: JsonSchemaObject;
+  readonly effectiveAcceptance?: ResolvedAcceptanceConfig;
+  readonly maxOutput?: MaxOutputConfig;
+  readonly maxSubagentDepth?: number;
+  readonly maxExecutionTimeMs?: number;
+  readonly maxTokens?: number;
+  readonly controlConfig?: ResolvedControlConfig;
+  readonly projectTrust?: ChildProjectTrustPolicy;
+  readonly projectTrusted?: boolean;
+}

package/src/shared/types/messages.ts

@@ -0,0 +1,104 @@
+/** Native streaming events expose a header before complete content is available. */
+export interface ChildMessageHeader {
+  readonly [key: string]: unknown;
+  readonly role: string;
+  readonly timestamp?: number;
+}
+
+/** Observations from native journals and external runners are not necessarily complete SDK messages. */
+export interface ObservedUsage {
+  readonly input?: number;
+  readonly output?: number;
+  readonly cacheRead?: number;
+  readonly cacheWrite?: number;
+  readonly cacheWrite1h?: number;
+  readonly reasoning?: number;
+  readonly totalTokens?: number;
+  readonly cost?: {
+    readonly input?: number;
+    readonly output?: number;
+    readonly cacheRead?: number;
+    readonly cacheWrite?: number;
+    readonly total?: number;
+  };
+}
+
+export type ObservedContent =
+  | { readonly type: "text"; readonly text: string; readonly textSignature?: string }
+  | {
+      readonly type: "thinking";
+      readonly thinking: string;
+      readonly thinkingSignature?: string;
+      readonly redacted?: boolean;
+    }
+  | { readonly type: "image"; readonly data: string; readonly mimeType: string }
+  | {
+      readonly type: "toolCall";
+      readonly id: string;
+      readonly name: string;
+      readonly arguments: Readonly<Record<string, unknown>>;
+      readonly thoughtSignature?: string;
+      readonly namespace?: string;
+    };
+
+interface ObservedMessageMetadata {
+  readonly timestamp?: number;
+}
+
+export type ObservedMessage =
+  | (ObservedMessageMetadata & {
+      readonly role: "assistant";
+      readonly content: readonly ObservedContent[];
+      readonly api?: string;
+      readonly provider?: string;
+      readonly model?: string;
+      readonly responseModel?: string;
+      readonly responseId?: string;
+      readonly usage?: ObservedUsage;
+      readonly stopReason?: string;
+      readonly errorMessage?: string;
+    })
+  | (ObservedMessageMetadata & {
+      readonly role: "toolResult";
+      readonly content: readonly ObservedContent[];
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly isError?: boolean;
+      readonly observedExitCode?: number;
+      readonly usage?: ObservedUsage;
+      readonly details?: unknown;
+    })
+  | (ObservedMessageMetadata & {
+      readonly role: "user" | "system";
+      readonly content: string | readonly ObservedContent[];
+    })
+  | (ObservedMessageMetadata & {
+      readonly role: "custom";
+      readonly customType: string;
+      readonly content: string | readonly ObservedContent[];
+      readonly display?: boolean;
+      readonly details?: unknown;
+    })
+  | (ObservedMessageMetadata & {
+      readonly role: "bashExecution";
+      readonly command: string;
+      readonly output: string;
+      readonly exitCode?: number;
+      readonly cancelled?: boolean;
+      readonly truncated?: boolean;
+      readonly fullOutputPath?: string;
+      readonly excludeFromContext?: boolean;
+      readonly content?: never;
+    })
+  | (ObservedMessageMetadata & {
+      readonly role: "branchSummary";
+      readonly summary: string;
+      readonly fromId: string | null;
+      readonly content?: never;
+    })
+  | (ObservedMessageMetadata & {
+      readonly role: "compactionSummary";
+      readonly summary: string;
+      readonly tokensBefore: number;
+      readonly content?: never;
+    });

package/src/shared/types/nested.ts

@@ -0,0 +1,153 @@
+import type { WritableDeep } from "type-fest";
+import type { ActivityState } from "./config.ts";
+import type { SubagentRunMode } from "./progress.ts";
+import type { TokenUsage } from "./usage.ts";
+
+export interface AsyncParallelGroupStatus {
+  readonly start: number;
+  readonly count: number;
+  readonly stepIndex: number;
+}
+
+export type NestedRunState = "queued" | "running" | "complete" | "failed" | "blocked" | "paused";
+export type NestedOwnerState = "live" | "gone" | "unknown";
+
+export interface NestedRunAddress {
+  readonly id: string;
+  readonly parentRunId: string;
+  readonly parentStepIndex?: number;
+  readonly parentAgent?: string;
+  readonly depth: number;
+  readonly path: readonly {
+    readonly runId: string;
+    readonly stepIndex?: number;
+    readonly agent?: string;
+  }[];
+}
+
+export interface NestedStepSummary {
+  readonly agent: string;
+  readonly status:
+    | "pending"
+    | "running"
+    | "complete"
+    | "completed"
+    | "failed"
+    | "blocked"
+    | "paused"
+    | "timed-out";
+  readonly sessionFile?: string;
+  readonly activityState?: ActivityState;
+  readonly lastActivityAt?: number;
+  readonly currentTool?: string;
+  readonly currentToolStartedAt?: number;
+  readonly currentPath?: string;
+  readonly turnCount?: number;
+  readonly toolCount?: number;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  readonly error?: string;
+  readonly children?: readonly NestedRunSummary[];
+}
+
+export interface NestedRunSummary extends NestedRunAddress {
+  readonly indexedControl?: boolean;
+  readonly asyncDir?: string;
+  readonly pid?: number;
+  readonly sessionId?: string;
+  readonly sessionFile?: string;
+  readonly intercomTarget?: string;
+  readonly ownerIntercomTarget?: string;
+  readonly leafIntercomTarget?: string;
+  readonly ownerState?: NestedOwnerState;
+  readonly controlInbox?: string;
+  readonly capabilityToken?: string;
+  readonly mode?: SubagentRunMode;
+  readonly state: NestedRunState;
+  readonly agent?: string;
+  readonly agents?: readonly string[];
+  readonly currentStep?: number;
+  readonly chainStepCount?: number;
+  readonly parallelGroups?: readonly AsyncParallelGroupStatus[];
+  readonly steps?: readonly NestedStepSummary[];
+  readonly children?: readonly NestedRunSummary[];
+  readonly activityState?: ActivityState;
+  readonly lastActivityAt?: number;
+  readonly currentTool?: string;
+  readonly currentToolStartedAt?: number;
+  readonly currentPath?: string;
+  readonly turnCount?: number;
+  readonly toolCount?: number;
+  readonly totalTokens?: TokenUsage;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  readonly lastUpdate?: number;
+  readonly error?: string;
+}
+
+/** The nested-event reducer owns and updates the projected tree before publishing a summary. */
+export type NestedRunProjection = WritableDeep<NestedRunSummary>;
+export type NestedStepProjection = WritableDeep<NestedStepSummary>;
+
+export interface NestedRouteInfo {
+  readonly rootRunId: string;
+  readonly eventSink: string;
+  readonly controlInbox: string;
+  readonly capabilityToken: string;
+}
+
+export type PublicNestedStepSummary = Pick<
+  NestedStepSummary,
+  | "agent"
+  | "status"
+  | "sessionFile"
+  | "activityState"
+  | "lastActivityAt"
+  | "currentTool"
+  | "currentToolStartedAt"
+  | "currentPath"
+  | "turnCount"
+  | "toolCount"
+  | "startedAt"
+  | "endedAt"
+  | "error"
+> & { readonly children?: readonly PublicNestedRunSummary[] };
+
+export type PublicNestedRunSummary = Pick<
+  NestedRunSummary,
+  | "id"
+  | "parentRunId"
+  | "parentStepIndex"
+  | "parentAgent"
+  | "depth"
+  | "path"
+  | "asyncDir"
+  | "sessionId"
+  | "sessionFile"
+  | "intercomTarget"
+  | "ownerIntercomTarget"
+  | "leafIntercomTarget"
+  | "ownerState"
+  | "mode"
+  | "state"
+  | "agent"
+  | "agents"
+  | "currentStep"
+  | "chainStepCount"
+  | "parallelGroups"
+  | "activityState"
+  | "lastActivityAt"
+  | "currentTool"
+  | "currentToolStartedAt"
+  | "currentPath"
+  | "turnCount"
+  | "toolCount"
+  | "totalTokens"
+  | "startedAt"
+  | "endedAt"
+  | "lastUpdate"
+  | "error"
+> & {
+  readonly steps?: readonly PublicNestedStepSummary[];
+  readonly children?: readonly PublicNestedRunSummary[];
+};