@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.2

package/dist/builtin/subagents/src/shared/types-results.ts

@@ -0,0 +1,318 @@
+/**
+ * Result, progress, and core subagent public types.
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { NestedRunAddress, NestedRunSummary, NestedStepSummary } from "./types-async.ts";
+
+export interface MaxOutputConfig {
+	bytes?: number;
+	lines?: number;
+}
+
+export type OutputMode = "inline" | "file-only";
+
+export type JsonSchemaObject = Record<string, unknown>;
+
+export interface ChainOutputMapEntry {
+	text: string;
+	structured?: unknown;
+	agent: string;
+	stepIndex: number;
+}
+
+export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
+
+export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "paused" | "detached";
+
+export interface WorkflowGraphNode {
+	id: string;
+	kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
+	agent?: string;
+	phase?: string;
+	label: string;
+	status: WorkflowNodeStatus;
+	flatIndex?: number;
+	stepIndex?: number;
+	children?: WorkflowGraphNode[];
+	dynamic?: {
+		sourceOutput: string;
+		sourcePath: string;
+		itemName: string;
+		maxItems?: number;
+		collectAs?: string;
+	};
+	itemKey?: string;
+	outputName?: string;
+	structured?: boolean;
+	error?: string;
+}
+
+export interface WorkflowGraphSnapshot {
+	runId: string;
+	mode: "chain" | "parallel" | "single";
+	phases: Array<{ title: string; nodeIds: string[] }>;
+	nodes: WorkflowGraphNode[];
+	currentNodeId?: string;
+}
+
+export interface SavedOutputReference {
+	path: string;
+	bytes: number;
+	lines: number;
+	message: string;
+}
+
+interface TruncationResult {
+	text: string;
+	truncated: boolean;
+	originalBytes?: number;
+	originalLines?: number;
+	artifactPath?: string;
+}
+
+export interface Usage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+}
+
+export interface TokenUsage {
+	input: number;
+	output: number;
+	total: number;
+}
+
+export type ActivityState = "active_long_running" | "needs_attention";
+export type ControlEventType = "active_long_running" | "needs_attention";
+export type ControlNotificationChannel = "event" | "async" | "intercom";
+
+export interface ControlConfig {
+	enabled?: boolean;
+	needsAttentionAfterMs?: number;
+	activeNoticeAfterMs?: number;
+	activeNoticeAfterTurns?: number;
+	activeNoticeAfterTokens?: number;
+	failedToolAttemptsBeforeAttention?: number;
+	notifyOn?: ControlEventType[];
+	notifyChannels?: ControlNotificationChannel[];
+}
+
+export interface ResolvedControlConfig {
+	enabled: boolean;
+	needsAttentionAfterMs: number;
+	activeNoticeAfterMs: number;
+	activeNoticeAfterTurns?: number;
+	activeNoticeAfterTokens?: number;
+	failedToolAttemptsBeforeAttention: number;
+	notifyOn: ControlEventType[];
+	notifyChannels: ControlNotificationChannel[];
+}
+
+export interface ControlEvent {
+	type: ControlEventType;
+	from?: ActivityState;
+	to: ActivityState;
+	ts: number;
+	agent: string;
+	index?: number;
+	runId: string;
+	nestedRunId?: string;
+	nestingPath?: NestedRunAddress["path"];
+	message: string;
+	reason?: "idle" | "active_long_running" | "tool_failures" | "time_threshold" | "turn_threshold" | "token_threshold";
+	turns?: number;
+	tokens?: number;
+	toolCount?: number;
+	currentTool?: string;
+	currentToolDurationMs?: number;
+	currentPath?: string;
+	elapsedMs?: number;
+	recentFailureSummary?: string;
+}
+
+export type SubagentResultStatus = "completed" | "failed" | "paused" | "detached";
+export type SubagentRunMode = "single" | "parallel" | "chain";
+
+export type PublicNestedStepSummary = Pick<
+	NestedStepSummary,
+	"agent" | "status" | "sessionFile" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "startedAt" | "endedAt" | "error"
+> & {
+	children?: 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"
+> & {
+	steps?: PublicNestedStepSummary[];
+	children?: PublicNestedRunSummary[];
+};
+
+export interface SubagentResultIntercomChild {
+	agent: string;
+	status: SubagentResultStatus;
+	summary: string;
+	index?: number;
+	artifactPath?: string;
+	sessionPath?: string;
+	intercomTarget?: string;
+	children?: PublicNestedRunSummary[];
+}
+
+export interface SubagentResultIntercomPayload {
+	to: string;
+	message: string;
+	requestId?: string;
+	runId: string;
+	mode: SubagentRunMode;
+	status: SubagentResultStatus;
+	summary: string;
+	source: "foreground" | "async";
+	children: SubagentResultIntercomChild[];
+	asyncId?: string;
+	asyncDir?: string;
+	chainSteps?: number;
+	agent?: string;
+	index?: number;
+	artifactPath?: string;
+	sessionPath?: string;
+}
+
+// ============================================================================
+// Progress Tracking
+// ============================================================================
+
+export interface AgentProgress {
+	index: number;
+	agent: string;
+	status: "pending" | "running" | "completed" | "failed" | "detached";
+	activityState?: ActivityState;
+	task: string;
+	skills?: string[];
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	recentTools: Array<{ tool: string; args: string; endMs: number }>;
+	recentOutput: string[];
+	toolCount: number;
+	turnCount?: number;
+	tokens: number;
+	durationMs: number;
+	error?: string;
+	failedTool?: string;
+}
+
+export interface ToolCallSummary {
+	text: string;
+	expandedText: string;
+}
+
+interface ProgressSummary {
+	toolCount: number;
+	tokens: number;
+	durationMs: number;
+}
+
+// ============================================================================
+// Results
+// ============================================================================
+
+export interface ModelAttempt {
+	model: string;
+	reasoningLevel?: string;
+	success: boolean;
+	exitCode?: number | null;
+	error?: string;
+	usage?: Usage;
+}
+
+export interface SingleResult {
+	agent: string;
+	task: string;
+	exitCode: number;
+	detached?: boolean;
+	detachedReason?: string;
+	interrupted?: boolean;
+	messages?: Message[];
+	usage: Usage;
+	model?: string;
+	fastMode?: boolean;
+	attemptedModels?: string[];
+	modelAttempts?: ModelAttempt[];
+	controlEvents?: ControlEvent[];
+	error?: string;
+	sessionFile?: string;
+	skills?: string[];
+	skillsWarning?: string;
+	progress?: AgentProgress;
+	progressSummary?: ProgressSummary;
+	toolCalls?: ToolCallSummary[];
+	artifactPaths?: ArtifactPaths;
+	truncation?: TruncationResult;
+	finalOutput?: string;
+	outputMode?: OutputMode;
+	savedOutputPath?: string;
+	outputReference?: SavedOutputReference;
+	outputSaveError?: string;
+	structuredOutput?: unknown;
+	structuredOutputPath?: string;
+	structuredOutputSchemaPath?: string;
+}
+
+export interface Details {
+	mode: SubagentRunMode | "management";
+	runId?: string;
+	context?: "fresh" | "fork";
+	results: SingleResult[];
+	controlEvents?: ControlEvent[];
+	asyncId?: string;
+	asyncDir?: string;
+	progress?: AgentProgress[];
+	progressSummary?: ProgressSummary;
+	artifacts?: {
+		dir: string;
+		files: ArtifactPaths[];
+	};
+	truncation?: {
+		truncated: boolean;
+		originalBytes?: number;
+		originalLines?: number;
+		artifactPath?: string;
+	};
+	// Chain metadata for observability
+	chainAgents?: string[];      // Agent names in order, e.g., ["scout", "planner"]
+	totalSteps?: number;         // Total steps in chain
+	currentStepIndex?: number;   // 0-indexed current step (for running chains)
+	workflowGraph?: WorkflowGraphSnapshot;
+	outputs?: ChainOutputMap;
+}
+
+// Upstream AgentToolResult omits the runtime isError flag that subagent tool results still emit/read.
+export type SubagentToolResult = AgentToolResult<Details> & { isError?: boolean };
+
+// ============================================================================
+// Artifacts
+// ============================================================================
+
+export interface ArtifactPaths {
+	inputPath: string;
+	outputPath: string;
+	jsonlPath: string;
+	metadataPath: string;
+}
+
+export interface ArtifactConfig {
+	enabled: boolean;
+	includeInput: boolean;
+	includeOutput: boolean;
+	includeJsonl: boolean;
+	includeMetadata: boolean;
+	cleanupDays: number;
+}

package/dist/builtin/subagents/src/shared/types-runtime.ts

@@ -0,0 +1,136 @@
+/**
+ * Runtime constants and helper functions for subagent storage and task wrapping.
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import { APP_NAME } from "@bastani/atomic";
+import type { ArtifactConfig, MaxOutputConfig } from "./types-results.ts";
+
+// Constants
+// ============================================================================
+
+export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
+	bytes: 200 * 1024,
+	lines: 5000,
+};
+
+export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
+	enabled: true,
+	includeInput: true,
+	includeOutput: true,
+	includeJsonl: false,
+	includeMetadata: true,
+	cleanupDays: 7,
+};
+
+function sanitizeTempScopeSegment(value: string): string {
+	const sanitized = value
+		.trim()
+		.replace(/[^A-Za-z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return sanitized || "unknown";
+}
+
+export function resolveTempScopeId(options?: {
+	env?: NodeJS.ProcessEnv;
+	getuid?: (() => number) | undefined;
+	userInfo?: (() => { username?: string | null }) | undefined;
+	homedir?: (() => string) | undefined;
+}): string {
+	const env = options?.env ?? process.env;
+	const getuid = options && Object.hasOwn(options, "getuid")
+		? options.getuid
+		: process.getuid?.bind(process);
+	if (typeof getuid === "function") {
+		return `uid-${getuid()}`;
+	}
+
+	for (const key of ["USERNAME", "USER", "LOGNAME"] as const) {
+		const value = env[key];
+		if (value) return `user-${sanitizeTempScopeSegment(value)}`;
+	}
+
+	const userInfo = options && Object.hasOwn(options, "userInfo")
+		? options.userInfo
+		: os.userInfo;
+	try {
+		const username = userInfo?.().username;
+		if (username) return `user-${sanitizeTempScopeSegment(username)}`;
+	} catch {
+		// Fall through to home-directory-based scoping.
+	}
+
+	const homedir = env.USERPROFILE ?? env.HOME;
+	if (homedir) return `home-${sanitizeTempScopeSegment(homedir)}`;
+
+	const resolveHomedir = options && Object.hasOwn(options, "homedir")
+		? options.homedir
+		: os.homedir;
+	try {
+		const fallbackHomedir = resolveHomedir?.();
+		if (fallbackHomedir) return `home-${sanitizeTempScopeSegment(fallbackHomedir)}`;
+	} catch {
+		// Fall through to the last-resort shared scope.
+	}
+
+	return "shared";
+}
+
+const MAX_PARALLEL = 8;
+export const MAX_CONCURRENCY = 4;
+export const TEMP_ROOT_DIR = path.join(os.tmpdir(), `${APP_NAME}-subagents-${resolveTempScopeId()}`);
+export const RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
+export const ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
+export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
+export const TEMP_ARTIFACTS_DIR = path.join(TEMP_ROOT_DIR, "artifacts");
+export const WIDGET_KEY = "subagent-async";
+export const SLASH_RESULT_TYPE = "subagent-slash-result";
+export const SLASH_SUBAGENT_REQUEST_EVENT = "subagent:slash:request";
+export const SLASH_SUBAGENT_STARTED_EVENT = "subagent:slash:started";
+export const SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";
+export const SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
+export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
+export const POLL_INTERVAL_MS = 250;
+export const MAX_WIDGET_JOBS = 4;
+export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
+export const SUBAGENT_ACTIONS = ["list", "get", "create", "update", "delete", "status", "interrupt", "resume", "doctor"] as const;
+
+export const DEFAULT_FORK_PREAMBLE =
+	"You are a delegated subagent running from a fork of the parent session. " +
+	"Treat the inherited conversation as reference-only context, not a live thread to continue. " +
+	"Do not continue or answer prior messages as if they are waiting for a reply. " +
+	"Your sole job is to execute the task below and return a focused result for that task using your tools.";
+
+function normalizeTopLevelParallelValue(value: unknown): number | undefined {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	if (!Number.isInteger(parsed) || parsed < 1) return undefined;
+	return parsed;
+}
+
+export function resolveTopLevelParallelMaxTasks(value: unknown): number {
+	return normalizeTopLevelParallelValue(value) ?? MAX_PARALLEL;
+}
+
+export function resolveTopLevelParallelConcurrency(
+	override: unknown,
+	configValue: unknown,
+): number {
+	return normalizeTopLevelParallelValue(override)
+		?? normalizeTopLevelParallelValue(configValue)
+		?? MAX_CONCURRENCY;
+}
+
+export function getAsyncConfigPath(suffix: string): string {
+	return path.join(TEMP_ROOT_DIR, `async-cfg-${suffix}.json`);
+}
+
+export function wrapForkTask(task: string, preamble?: string | false): string {
+	if (preamble === false) return task;
+	const effectivePreamble = preamble ?? DEFAULT_FORK_PREAMBLE;
+	const wrappedPrefix = `${effectivePreamble}\n\nTask:\n`;
+	if (task.startsWith(wrappedPrefix)) return task;
+	return `${wrappedPrefix}${task}`;
+}
+
+// ============================================================================