@bastani/atomic 0.9.16-alpha.2 → 0.9.16-alpha.3

package/dist/builtin/workflows/src/extension/companions.ts

@@ -1,210 +0,0 @@
-/**
- * Companion-package detection helpers.
- *
- * Why this exists:
- *   `@bastani/workflows` orchestrates a few first-party pi packages
- *   at runtime (delegation, MCP access, HIL bridge, web fetch). They are
- *   installed independently of workflows so pi's npm-identity
- *   dedup can share them with any other extensions the user already has
- *   (see pi docs/packages.md → "Scope and Deduplication"). Bundling them
- *   via `bundledDependencies` produced a parallel "local-path" identity
- *   that bypassed dedup and yielded `Tool "mcp" conflicts with ...` /
- *   `Tool "subagent" conflicts with ...` errors on load.
- *
- *   The trade-off of independent installs is that we cannot reach in and
- *   require() them — we instead **detect** their presence by inspecting
- *   pi's slash-command and tool registries.
- *
- * Detection is intentionally best-effort and structural:
- *   1. Path hints (preferred): `pi.getCommands()[].sourceInfo.path` /
- *      `.baseDir` typically include the package name (e.g.
- *      `.../node_modules/pi-subagents/...`). This survives command/tool
- *      renames in upstream packages.
- *   2. Command-name hints (fallback): a distinctive slash command
- *      registered by the companion.
- *   3. Tool-name hints (fallback): a registered tool name (e.g. `mcp`).
- *
- * Any match counts as "installed".
- *
- * cross-ref:
- *  - pi docs/packages.md → "Scope and Deduplication"
- */
-
-import type { ExtensionAPI } from "./index.js";
-
-// ---------------------------------------------------------------------------
-// Companion catalogue
-// ---------------------------------------------------------------------------
-
-/** One entry per companion pi package workflows can use at runtime. */
-export interface CompanionSpec {
-	/** Display name, e.g. `pi-subagents`. */
-	readonly name: string;
-	/** Install spec used for setup hints: `npm:pi-subagents`. */
-	readonly installSpec: string;
-	/** One-line description shown beside the status. */
-	readonly purpose: string;
-	/**
-	 * Path-fragment hints matched against `sourceInfo.path` / `.baseDir`.
-	 * First match wins. Prefer this over name hints — surviving renames.
-	 */
-	readonly pathHints: readonly string[];
-	/** Slash-command names registered by the package (without the leading `/`). */
-	readonly commandHints: readonly string[];
-	/** Registered tool names (matched against `pi.getAllTools()[].name`). */
-	readonly toolHints: readonly string[];
-}
-
-/**
- * Ordered companion catalogue. Order is preserved across detection
- * outputs so any UI surfacing companions can render a stable layout.
- */
-export const COMPANIONS: readonly CompanionSpec[] = [
-	{
-		name: "pi-subagents",
-		installSpec: "npm:pi-subagents",
-		purpose: "delegate stages to focused child agents",
-		pathHints: ["/pi-subagents/", "/pi-subagents-", "/pi-subagents."],
-		commandHints: [],
-		toolHints: ["subagent"],
-	},
-	{
-		name: "pi-mcp-adapter",
-		installSpec: "npm:pi-mcp-adapter",
-		purpose: "MCP servers through one proxy tool (no context bloat)",
-		pathHints: ["/pi-mcp-adapter/", "/pi-mcp-adapter-", "/pi-mcp-adapter."],
-		commandHints: ["mcp"],
-		toolHints: ["mcp"],
-	},
-	{
-		name: "pi-web-access",
-		installSpec: "npm:pi-web-access",
-		purpose: "fetch and search the web from inside a stage",
-		pathHints: ["/pi-web-access/", "/pi-web-access-", "/pi-web-access."],
-		commandHints: ["web", "web-access"],
-		toolHints: ["web_fetch", "web_search", "web"],
-	},
-	{
-		name: "pi-intercom",
-		installSpec: "npm:pi-intercom",
-		purpose: "child agents talk back to the parent session (HIL)",
-		pathHints: ["/pi-intercom/", "/pi-intercom-", "/pi-intercom."],
-		commandHints: ["intercom"],
-		toolHints: ["intercom", "contact_supervisor"],
-	},
-] as const;
-
-// ---------------------------------------------------------------------------
-// Detection
-// ---------------------------------------------------------------------------
-
-export interface CompanionStatus {
-	readonly companion: CompanionSpec;
-	readonly installed: boolean;
-	/** Human-readable signal that drove the verdict — empty when missing. */
-	readonly evidence?: string;
-}
-
-/**
- * Surface used for detection. Kept narrow so tests can stub it without
- * the full `ExtensionAPI`.
- */
-export interface CompanionProbeApi {
-	readonly getCommands?: () => ReadonlyArray<CommandProbe>;
-	readonly getAllTools?: () => ReadonlyArray<ToolProbe>;
-}
-
-interface CommandProbe {
-	readonly name: string;
-	readonly sourceInfo?: { readonly path?: string; readonly baseDir?: string };
-}
-
-interface ToolProbe {
-	readonly name: string;
-	readonly sourceInfo?: { readonly path?: string; readonly baseDir?: string };
-}
-
-/**
- * Inspect pi's registries and return one status per companion in the
- * catalogue order. Pure of side effects.
- */
-export function detectCompanions(pi: ExtensionAPI | CompanionProbeApi): readonly CompanionStatus[] {
-	const probe = pi as CompanionProbeApi;
-	const commands = safeProbeList(probe.getCommands);
-	const tools = safeProbeList(probe.getAllTools);
-
-	return COMPANIONS.map((companion) => detectOne(companion, commands, tools));
-}
-
-function detectOne(
-	companion: CompanionSpec,
-	commands: readonly CommandProbe[],
-	tools: readonly ToolProbe[],
-): CompanionStatus {
-	// 1. Path hints — most reliable (survives upstream renames).
-	const pathHit = findPathHit(commands, tools, companion.pathHints);
-	if (pathHit) return { companion, installed: true, evidence: `path ${pathHit}` };
-
-	// 2. Command-name hints.
-	for (const name of companion.commandHints) {
-		if (commands.some((c) => c.name === name)) {
-			return { companion, installed: true, evidence: `command /${name}` };
-		}
-	}
-
-	// 3. Tool-name hints.
-	for (const name of companion.toolHints) {
-		if (tools.some((t) => t.name === name)) {
-			return { companion, installed: true, evidence: `tool ${name}` };
-		}
-	}
-
-	return { companion, installed: false };
-}
-
-function findPathHit(
-	commands: readonly CommandProbe[],
-	tools: readonly ToolProbe[],
-	hints: readonly string[],
-): string | undefined {
-	const haystacks: string[] = [];
-	for (const c of commands) {
-		if (c.sourceInfo?.path) haystacks.push(c.sourceInfo.path);
-		if (c.sourceInfo?.baseDir) haystacks.push(c.sourceInfo.baseDir);
-	}
-	for (const t of tools) {
-		if (t.sourceInfo?.path) haystacks.push(t.sourceInfo.path);
-		if (t.sourceInfo?.baseDir) haystacks.push(t.sourceInfo.baseDir);
-	}
-	for (const hint of hints) {
-		const hit = haystacks.find((p) => p.includes(hint));
-		if (hit) return shortenForEvidence(hit);
-	}
-	return undefined;
-}
-
-function safeProbeList<T>(probe: undefined | (() => ReadonlyArray<T>)): readonly T[] {
-	if (typeof probe !== "function") return [];
-	try {
-		const result = probe();
-		return Array.isArray(result) ? result : [];
-	} catch {
-		return [];
-	}
-}
-
-/**
- * Shorten a node_modules path so the evidence row stays readable.
- * `…/node_modules/pi-subagents/dist/extension.ts` → `pi-subagents/dist/extension.ts`.
- */
-function shortenForEvidence(p: string): string {
-	const marker = "/node_modules/";
-	const idx = p.lastIndexOf(marker);
-	if (idx >= 0) return p.slice(idx + marker.length);
-	// Some installs (git, local) land under `~/.atomic/extensions/<name>` —
-	// surface the trailing `extensions/<name>/…` segment instead.
-	const extMarker = "/extensions/";
-	const extIdx = p.lastIndexOf(extMarker);
-	if (extIdx >= 0) return p.slice(extIdx + 1);
-	return p;
-}

package/dist/builtin/workflows/src/extension/completed-stage-intercom-ask.ts

@@ -1,167 +0,0 @@
-import type {
-	EnsurePostMortemStageHandleResult,
-	PostMortemUnavailableReason,
-} from "../runs/foreground/postmortem-stage-chat.js";
-import type { StageControlHandle } from "../runs/foreground/stage-control-registry.js";
-
-const LATE_STAGE_MESSAGE_EVENT = "atomic:workflow-stage-late-message";
-const POST_MORTEM_ATTACH_TIMEOUT_MS = 10_000;
-
-interface IntercomAskMessage {
-	readonly customType: "intercom_message";
-	readonly content: string;
-	readonly details?: {
-		readonly message?: {
-			readonly expectsReply?: boolean;
-		};
-	};
-}
-
-interface CompletedStageAskEvent {
-	handled: boolean;
-	completion?: Promise<void>;
-	readonly batch: boolean;
-	readonly workflowRunId?: string;
-	readonly workflowStageId?: string;
-	readonly messages: readonly IntercomAskMessage[];
-}
-
-interface WorkflowEventSurface {
-	readonly events?: {
-		// `unknown`, not `(() => void) | undefined`: the host ExtensionAPI's `on`
-		// returns nothing while our own event bus returns an unsubscribe. The
-		// call site narrows with a typeof check.
-		on?(event: string, listener: (payload: unknown) => void): unknown;
-	};
-	on?(event: "session_shutdown", listener: () => void): void;
-}
-
-export type CompletedStageHandleResolver = (
-	runId: string,
-	stageId: string,
-) => EnsurePostMortemStageHandleResult | undefined;
-
-/**
- * Claims late blocking Intercom asks for completed workflow stages and runs one
- * post-mortem turn in the retained conversation. Ordinary late notifications
- * keep using the existing parent-chat route.
- */
-export function registerCompletedStageIntercomAskRouter(
-	pi: WorkflowEventSurface,
-	resolveHandle: CompletedStageHandleResolver,
-): () => void {
-	const queues = new Map<string, Promise<void>>();
-	let disposed = false;
-	const subscription = pi.events?.on?.(LATE_STAGE_MESSAGE_EVENT, (payload) => {
-		if (disposed || !isCompletedStageAskEvent(payload) || payload.handled === true) return;
-		payload.handled = true;
-		payload.completion = enqueueTargetTurn(queues, `${payload.workflowRunId}:${payload.workflowStageId}`, () =>
-			deliverAsPostMortemTurn(payload, resolveHandle),
-		);
-	});
-	const dispose = (): void => {
-		disposed = true;
-		queues.clear();
-		if (typeof subscription === "function") subscription();
-	};
-	pi.on?.("session_shutdown", dispose);
-	return dispose;
-}
-
-function isCompletedStageAskEvent(payload: unknown): payload is CompletedStageAskEvent & {
-	readonly workflowRunId: string;
-	readonly workflowStageId: string;
-} {
-	if (typeof payload !== "object" || payload === null) return false;
-	const event = payload as Partial<CompletedStageAskEvent>;
-	return (
-		typeof event.workflowRunId === "string" &&
-		event.workflowRunId.length > 0 &&
-		typeof event.workflowStageId === "string" &&
-		event.workflowStageId.length > 0 &&
-		Array.isArray(event.messages) &&
-		event.messages.length > 0 &&
-		event.messages.every(
-			(message) =>
-				message?.customType === "intercom_message" &&
-				typeof message.content === "string" &&
-				message.details?.message?.expectsReply === true,
-		)
-	);
-}
-
-function enqueueTargetTurn(
-	queues: Map<string, Promise<void>>,
-	key: string,
-	deliver: () => Promise<void>,
-): Promise<void> {
-	const previous = queues.get(key) ?? Promise.resolve();
-	const current = previous.catch(() => {}).then(deliver);
-	queues.set(key, current);
-	void current
-		.finally(() => {
-			if (queues.get(key) === current) queues.delete(key);
-		})
-		.catch(() => {});
-	return current;
-}
-
-async function deliverAsPostMortemTurn(
-	event: CompletedStageAskEvent & { readonly workflowRunId: string; readonly workflowStageId: string },
-	resolveHandle: CompletedStageHandleResolver,
-): Promise<void> {
-	const resolution = resolveHandle(event.workflowRunId, event.workflowStageId);
-	if (resolution === undefined) {
-		throw new Error(
-			`Intercom ask target is unavailable: completed workflow stage ${event.workflowRunId}/${event.workflowStageId} was deleted or is no longer retained.`,
-		);
-	}
-	if (!resolution.ok) {
-		throw new Error(unavailableReason(event.workflowRunId, event.workflowStageId, resolution.reason));
-	}
-	const handle = resolution.handle;
-	if (handle.status !== "completed" || handle.isDisposed === true) {
-		throw new Error(
-			`Intercom ask target is not resumable: workflow stage ${event.workflowRunId}/${event.workflowStageId} has no retained completed conversation.`,
-		);
-	}
-	await attachWithTimeout(handle);
-	for (const message of event.messages) {
-		if (handle.isStreaming) await handle.followUp(message.content);
-		else await handle.prompt(message.content);
-	}
-}
-
-async function attachWithTimeout(handle: StageControlHandle): Promise<void> {
-	let timeout: ReturnType<typeof setTimeout> | undefined;
-	const bounded = new Promise<never>((_, reject) => {
-		timeout = setTimeout(
-			() =>
-				reject(
-					new Error(
-						`Intercom ask target failed to resume within ${POST_MORTEM_ATTACH_TIMEOUT_MS}ms: retained stage conversation ${handle.runId}/${handle.stageId}.`,
-					),
-				),
-			POST_MORTEM_ATTACH_TIMEOUT_MS,
-		);
-	});
-	try {
-		await Promise.race([handle.ensureAttached(), bounded]);
-	} finally {
-		if (timeout !== undefined) clearTimeout(timeout);
-	}
-}
-
-function unavailableReason(runId: string, stageId: string, reason: PostMortemUnavailableReason): string {
-	const target = `${runId}/${stageId}`;
-	switch (reason) {
-		case "not_terminal":
-			return `Intercom ask target is not resumable: workflow stage ${target} is not a completed stage with a retained conversation.`;
-		case "no_session":
-			return `Intercom ask target is unavailable: completed workflow stage ${target} has no retained conversation.`;
-		case "invalid_session":
-			return `Intercom ask target is unavailable: retained conversation for completed workflow stage ${target} is missing, deleted, or invalid.`;
-		case "no_adapter":
-			return `Intercom ask target is not resumable: no workflow stage session adapter can reopen ${target}.`;
-	}
-}

package/dist/builtin/workflows/src/extension/config-file-loader.ts

@@ -1,185 +0,0 @@
-import { validateWorkflowBudget } from "../shared/budget.js";
-import type { ConfigDiagnostic, WorkflowExtensionConfig } from "./config-loader.js";
-import { WORKFLOW_LIFECYCLE_NOTICE_KINDS, type WorkflowLifecycleNoticeKind } from "./lifecycle-notifications.js";
-
-const WORKFLOW_LIFECYCLE_NOTICE_KIND_SET = new Set<string>(WORKFLOW_LIFECYCLE_NOTICE_KINDS);
-/**
- * Every accepted lifecycle kind, quoted for the rejection message, so adding a
- * kind can never leave the error naming a stale subset of what validates.
- */
-const WORKFLOW_LIFECYCLE_NOTICE_KIND_LIST = ((): string => {
-	const quoted = WORKFLOW_LIFECYCLE_NOTICE_KINDS.map((kind) => JSON.stringify(kind));
-	const last = quoted[quoted.length - 1] ?? "";
-	return quoted.length <= 1 ? last : `${quoted.slice(0, -1).join(", ")}, or ${last}`;
-})();
-
-async function tryReadFile(filePath: string): Promise<string | null> {
-	const { readFile } = await import("node:fs/promises");
-	try {
-		return await readFile(filePath, "utf-8");
-	} catch (err) {
-		if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-		throw err;
-	}
-}
-
-function isWorkflowLifecycleNoticeKind(value: unknown): value is WorkflowLifecycleNoticeKind {
-	return typeof value === "string" && WORKFLOW_LIFECYCLE_NOTICE_KIND_SET.has(value);
-}
-
-function validateConfig(value: unknown): string | null {
-	if (value === null || typeof value !== "object" || Array.isArray(value)) {
-		return "config must be a JSON object";
-	}
-	const c = value as Record<string, unknown>;
-
-	if (
-		"maxDepth" in c &&
-		(typeof c.maxDepth !== "number" || !Number.isInteger(c.maxDepth) || (c.maxDepth as number) < 0)
-	) {
-		return `"maxDepth" must be a non-negative integer, got ${JSON.stringify(c.maxDepth)}`;
-	}
-
-	if (
-		"defaultConcurrency" in c &&
-		(typeof c.defaultConcurrency !== "number" ||
-			!Number.isInteger(c.defaultConcurrency) ||
-			(c.defaultConcurrency as number) < 1)
-	) {
-		return `"defaultConcurrency" must be a positive integer, got ${JSON.stringify(c.defaultConcurrency)}`;
-	}
-
-	if ("persistRuns" in c && typeof c.persistRuns !== "boolean") {
-		return `"persistRuns" must be a boolean, got ${JSON.stringify(c.persistRuns)}`;
-	}
-
-	if ("statusFile" in c && typeof c.statusFile !== "boolean") {
-		return `"statusFile" must be a boolean, got ${JSON.stringify(c.statusFile)}`;
-	}
-
-	if ("resumeInFlight" in c) {
-		const v = c.resumeInFlight;
-		if (v !== "ask" && v !== "auto" && v !== "never") {
-			return `"resumeInFlight" must be "ask", "auto", or "never", got ${JSON.stringify(v)}`;
-		}
-	}
-
-	if ("budget" in c) {
-		const reason = validateWorkflowBudget(c.budget, "budget");
-		if (reason !== null) return reason;
-	}
-
-	if ("workflowNotifications" in c) {
-		const value = c.workflowNotifications;
-		if (value === null || typeof value !== "object" || Array.isArray(value)) {
-			return `"workflowNotifications" must be a JSON object, got ${JSON.stringify(typeof value)}`;
-		}
-		const notifications = value as Record<string, unknown>;
-		if ("enabled" in notifications && typeof notifications.enabled !== "boolean") {
-			return `"workflowNotifications.enabled" must be a boolean, got ${JSON.stringify(notifications.enabled)}`;
-		}
-		if ("notifyOn" in notifications) {
-			const notifyOn = notifications.notifyOn;
-			if (!Array.isArray(notifyOn)) {
-				return `"workflowNotifications.notifyOn" must be an array, got ${JSON.stringify(typeof notifyOn)}`;
-			}
-			if (notifyOn.length === 0) {
-				return `"workflowNotifications.notifyOn" must be a non-empty array`;
-			}
-			for (const item of notifyOn) {
-				if (!isWorkflowLifecycleNoticeKind(item)) {
-					return `"workflowNotifications.notifyOn" entries must be ${WORKFLOW_LIFECYCLE_NOTICE_KIND_LIST}, got ${JSON.stringify(item)}`;
-				}
-			}
-		}
-	}
-	if ("worktree" in c) {
-		const worktree = c.worktree;
-		if (worktree === null || typeof worktree !== "object" || Array.isArray(worktree)) {
-			return `"worktree" must be a JSON object, got ${JSON.stringify(typeof worktree)}`;
-		}
-		const config = worktree as Record<string, unknown>;
-		if ("symlinkDirectories" in config) {
-			const directories = config.symlinkDirectories;
-			if (!Array.isArray(directories) || directories.some((entry) => typeof entry !== "string")) {
-				return `"worktree.symlinkDirectories" must be an array of strings`;
-			}
-		}
-	}
-
-	if ("workflows" in c) {
-		if (c.workflows === null || typeof c.workflows !== "object" || Array.isArray(c.workflows)) {
-			return `"workflows" must be a JSON object, got ${JSON.stringify(typeof c.workflows)}`;
-		}
-		const wf = c.workflows as Record<string, unknown>;
-		for (const [name, entry] of Object.entries(wf)) {
-			if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
-				return `"workflows.${name}" must be an object with a "path" field`;
-			}
-			const e = entry as Record<string, unknown>;
-			if (typeof e.path !== "string" || (e.path as string).trim().length === 0) {
-				return `"workflows.${name}.path" must be a non-empty string, got ${JSON.stringify(e.path)}`;
-			}
-		}
-	}
-
-	return null;
-}
-
-export type LoadFileOutcome =
-	| { kind: "missing" }
-	| { kind: "ok"; parsed: WorkflowExtensionConfig }
-	| { kind: "error"; diagnostic: ConfigDiagnostic };
-
-export async function loadConfigFile(filePath: string): Promise<LoadFileOutcome> {
-	let text: string | null;
-	try {
-		text = await tryReadFile(filePath);
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		return {
-			kind: "error",
-			diagnostic: {
-				level: "error",
-				code: "CONFIG_INVALID",
-				message: `Failed to read config file: ${msg}`,
-				source: filePath,
-			},
-		};
-	}
-
-	if (text === null) {
-		return { kind: "missing" };
-	}
-
-	let value: unknown;
-	try {
-		value = JSON.parse(text);
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		return {
-			kind: "error",
-			diagnostic: {
-				level: "error",
-				code: "CONFIG_INVALID",
-				message: `Invalid JSON in config file: ${msg}`,
-				source: filePath,
-			},
-		};
-	}
-
-	const reason = validateConfig(value);
-	if (reason !== null) {
-		return {
-			kind: "error",
-			diagnostic: {
-				level: "error",
-				code: "CONFIG_INVALID",
-				message: `Invalid config shape: ${reason}`,
-				source: filePath,
-			},
-		};
-	}
-
-	return { kind: "ok", parsed: value as WorkflowExtensionConfig };
-}