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

package/dist/builtin/workflows/src/extension/public-types.ts

@@ -0,0 +1,295 @@
+import type {
+  CreateAgentSessionOptions,
+  DefaultResourceLoaderInheritanceSnapshot,
+} from "@bastani/atomic";
+import type { SessionManager } from "../shared/persistence-restore.js";
+import type { StageSessionRuntime } from "../runs/foreground/stage-runner.js";
+import type { StageStatus } from "../shared/store-types.js";
+import type {
+  StageOptions,
+  WorkflowChainStep,
+  WorkflowDirectTaskItem,
+  WorkflowInputValues,
+  WorkflowMaxOutput,
+} from "../shared/types.js";
+import type { WidgetFactory } from "../tui/store-widget-installer.js";
+import type { RenderResultOpts, WorkflowToolResult } from "./render-result.js";
+import type { PiUISurface } from "./wiring.js";
+
+export type PiTheme = Record<string, string>;
+
+export interface PiRenderContext {
+  state?: {
+    runId?: string;
+    stages?: unknown[];
+  };
+  invalidate?: () => void;
+}
+
+export interface PiRenderResultOpts extends RenderResultOpts {}
+
+export interface PiRenderComponent {
+  render(width: number): string[];
+  invalidate?: () => void;
+  includes(searchString: string): boolean;
+}
+
+export interface PiMessageRenderComponent {
+  render(width: number): string[];
+  invalidate?: () => void;
+}
+
+export interface PiMessageRenderOptions {
+  expanded: boolean;
+}
+
+export type PiMessageRendererResult = string | PiMessageRenderComponent | null | undefined;
+export type PiMessageRenderer = (
+  payload: unknown,
+  options?: PiMessageRenderOptions,
+  theme?: unknown,
+) => PiMessageRendererResult;
+
+export interface PiArgumentCompletion {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+export type PiArgumentCompletionResult = PiArgumentCompletion[] | null;
+
+export interface PiCommandOptions {
+  description: string;
+  handler: (args: string, ctx: PiCommandContext) => Promise<void> | void;
+  getArgumentCompletions?: (partial: string) => PiArgumentCompletionResult;
+}
+
+export interface PiRuntimeModel {
+  readonly provider: string;
+  readonly id: string;
+}
+
+export interface PiRuntimeModelRegistry {
+  getAvailable(): PiRuntimeModel[];
+}
+
+export interface PiModelContext {
+  readonly model?: PiRuntimeModel;
+  readonly modelRegistry?: PiRuntimeModelRegistry;
+}
+
+export interface PiCommandContext extends PiModelContext {
+  ui: {
+    notify: (message: string, type?: "info" | "warning" | "error") => void;
+  } & PiUISurface;
+  hasUI?: boolean;
+}
+
+export interface PiFlagNamedOpts {
+  description: string;
+  type?: "string" | "boolean";
+  default?: unknown;
+}
+
+export interface PiAgentToolResult<TDetails> {
+  content: Array<
+    { type: "text"; text: string } | { type: "image"; [key: string]: unknown }
+  >;
+  details: TDetails;
+  terminate?: boolean;
+}
+
+export interface PiToolOpts<TArgs, TDetails> {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  promptGuidelines?: string[];
+  renderShell?: "default" | "self";
+  execute: (
+    toolCallId: string,
+    params: TArgs,
+    signal: AbortSignal | undefined,
+    onUpdate: ((partial: PiAgentToolResult<TDetails>) => void) | undefined,
+    ctx: PiExecuteContext,
+  ) => Promise<PiAgentToolResult<TDetails>>;
+  renderCall?: (
+    args: TArgs,
+    theme: PiTheme,
+    context: PiRenderContext,
+  ) => PiRenderComponent | string;
+  renderResult?: (
+    result: PiAgentToolResult<TDetails>,
+    opts: PiRenderResultOpts,
+    theme: PiTheme,
+    context: PiRenderContext,
+  ) => PiRenderComponent | string;
+}
+
+export interface PiExecuteContext extends PiModelContext {
+  sessionId?: string;
+  ui?: PiUISurface;
+  hasUI?: boolean;
+  orchestrationContext?: CreateAgentSessionOptions["orchestrationContext"];
+  sessionManager?: SessionManager & {
+    getSessionFile?: () => string | undefined;
+  };
+  [key: string]: unknown;
+}
+
+export interface WorkflowResourceInfo {
+  readonly path: string;
+  readonly enabled: boolean;
+  readonly metadata?: {
+    readonly source?: string;
+    readonly scope?: string;
+    readonly origin?: string;
+    readonly baseDir?: string;
+  };
+}
+
+export interface ExtensionAPI {
+  registerTool?: <TArgs, TResult>(opts: PiToolOpts<TArgs, TResult>) => void;
+  registerCommand?: (name: string, options: PiCommandOptions) => void;
+  registerMessageRenderer?: (
+    event: string,
+    renderer: PiMessageRenderer,
+  ) => void;
+  sendMessage?: <T = unknown>(
+    message: {
+      customType: string;
+      content?: string;
+      display?: boolean;
+      details?: T;
+    },
+    options?: {
+      triggerTurn?: boolean;
+      deliverAs?: "steer" | "followUp" | "nextTurn" | "interrupt";
+      excludeFromContext?: boolean;
+      interruptAbortMessage?: string;
+    },
+  ) => void | Promise<void>;
+  registerFlag?: (name: string, opts: PiFlagNamedOpts) => void;
+  getWorkflowResources?: () => readonly WorkflowResourceInfo[];
+  refreshWorkflowResources?: () => Promise<readonly WorkflowResourceInfo[]>;
+  getResourceLoaderInheritanceSnapshot?: () => DefaultResourceLoaderInheritanceSnapshot | undefined;
+  registerShortcut?: (
+    key: string,
+    opts: {
+      description: string;
+      handler: (ctx?: PiCommandContext) => void | Promise<void>;
+    },
+  ) => void;
+  getActiveTools?: () => string[];
+  setActiveTools?: (toolNames: string[]) => void;
+  setSessionName?: (name: string) => void | Promise<void>;
+  events?: {
+    emit?: (event: string, payload: Record<string, unknown>) => void;
+    on?: (event: string, handler: (payload: unknown) => void) => void;
+  };
+  exec?: (
+    command: string,
+    args: string[],
+    opts?: { signal?: AbortSignal; timeout?: number },
+  ) => Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+  }>;
+  createAgentSession?: (
+    options?: CreateAgentSessionOptions,
+  ) => Promise<{ session: StageSessionRuntime }>;
+  disableAsyncDiscovery?: boolean;
+  appendEntry?: (
+    type: string,
+    payload: Record<string, unknown>,
+  ) => string | undefined;
+  setLabel?: (entryId: string, label: string) => void;
+  appendCustomMessageEntry?: (
+    content: string,
+    meta?: Record<string, unknown>,
+  ) => string | undefined;
+  on?: (
+    event: string,
+    handler: (
+      event?: unknown,
+      ctx?: PiCommandContext & {
+        sessionManager?: SessionManager;
+        hasUI?: boolean;
+      },
+    ) => void | object | Promise<void | object>,
+  ) => void;
+  sessionManager?: SessionManager;
+  ui?: {
+    setWidget?: (
+      key: string,
+      factory: WidgetFactory | undefined,
+      opts?: { placement?: string },
+    ) => void;
+    custom?: PiUISurface["custom"];
+  } & PiUISurface;
+  [key: string]: unknown;
+}
+
+export interface WorkflowToolArgs extends StageOptions {
+  workflow?: string;
+  inputs?: WorkflowInputValues;
+  action?:
+    | "run"
+    | "list"
+    | "get"
+    | "status"
+    | "stages"
+    | "stage"
+    | "transcript"
+    | "send"
+    | "pause"
+    | "interrupt"
+    | "kill"
+    | "resume"
+    | "reload"
+    | "inputs";
+  runId?: string;
+  all?: boolean;
+  stageId?: string;
+  message?: string;
+  statusFilter?: StageStatus | "all";
+  format?: "text" | "json";
+  limit?: number;
+  tail?: number;
+  includeToolOutput?: boolean;
+  text?: string;
+  response?: unknown;
+  delivery?: "auto" | "answer" | "prompt" | "steer" | "followUp" | "resume";
+  promptId?: string;
+  reason?: string;
+  task?: WorkflowDirectTaskItem | string;
+  tasks?: WorkflowDirectTaskItem[];
+  chain?: WorkflowChainStep[];
+  chainName?: string;
+  context?: "fresh" | "fork";
+  forkFromSessionFile?: string;
+  concurrency?: number;
+  failFast?: boolean;
+  async?: boolean;
+  intercom?: {
+    enabled?: boolean;
+    delivery?: "off" | "notify" | "result" | "control-and-result";
+    parentSession?: string;
+    notifyOn?: Array<
+      "active_long_running" | "needs_attention" | "completed" | "failed"
+    >;
+  };
+  output?: string | false;
+  outputMode?: "inline" | "file-only";
+  reads?: readonly string[] | false;
+  chainDir?: string;
+  maxOutput?: WorkflowMaxOutput;
+  artifacts?: boolean;
+  worktree?: boolean;
+  gitWorktreeDir?: string;
+  baseBranch?: string;
+}
+
+export type WorkflowExecuteToolResult = PiAgentToolResult<WorkflowToolResult>;

package/dist/builtin/workflows/src/extension/render-component.ts

@@ -0,0 +1,14 @@
+import type { PiRenderComponent } from "./public-types.js";
+
+export function dynamicTextRenderComponent(
+  renderText: (width: number) => string,
+): PiRenderComponent {
+  return {
+    render(width: number): string[] {
+      return renderText(width).split("\n");
+    },
+    includes(searchString: string): boolean {
+      return renderText(120).includes(searchString);
+    },
+  };
+}

package/dist/builtin/workflows/src/extension/runtime-direct.ts

@@ -0,0 +1,96 @@
+import type {
+  WorkflowChainStep,
+  WorkflowDetails,
+  WorkflowDirectOptions,
+  WorkflowDirectTaskItem,
+} from "../shared/types.js";
+import type { WorkflowToolArgs } from "./index.js";
+
+export function withoutUndefinedProperties<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, field]) => field !== undefined),
+  ) as Partial<T>;
+}
+
+export function directOptions(args: WorkflowToolArgs): WorkflowDirectOptions {
+  const {
+    workflow: _workflow,
+    inputs: _inputs,
+    action: _action,
+    runId: _runId,
+    task,
+    tasks: _tasks,
+    chain: _chain,
+    chainName,
+    concurrency,
+    failFast,
+    async: _async,
+    intercom: _intercom,
+    output,
+    outputMode,
+    reads,
+    chainDir,
+    maxOutput,
+    artifacts,
+    worktree,
+    gitWorktreeDir,
+    baseBranch,
+    ...stageOptions
+  } = args;
+
+  return {
+    ...withoutUndefinedProperties(stageOptions),
+    ...(typeof task === "string" ? { task } : {}),
+    ...(typeof chainName === "string" ? { chainName } : {}),
+    ...(typeof concurrency === "number" ? { concurrency } : {}),
+    ...(typeof failFast === "boolean" ? { failFast } : {}),
+    ...(typeof chainDir === "string" ? { chainDir } : {}),
+    ...(output !== undefined ? { output } : {}),
+    ...(outputMode !== undefined ? { outputMode } : {}),
+    ...(reads !== undefined ? { reads } : {}),
+    ...(maxOutput !== undefined ? { maxOutput } : {}),
+    ...(typeof artifacts === "boolean" ? { artifacts } : {}),
+    ...(typeof worktree === "boolean" ? { worktree } : {}),
+    ...(typeof gitWorktreeDir === "string" ? { gitWorktreeDir } : {}),
+    ...(typeof baseBranch === "string" ? { baseBranch } : {}),
+  };
+}
+
+export function directMode(args: WorkflowToolArgs): WorkflowDetails["mode"] {
+  if (Array.isArray(args.chain)) return "chain";
+  if (Array.isArray(args.tasks)) return "parallel";
+  return "single";
+}
+
+export function directModelRequests(args: WorkflowToolArgs): Array<{ readonly model?: WorkflowDirectTaskItem["model"]; readonly fallbackModels?: readonly string[] }> {
+  const options = directOptions(args);
+  const withFallbackDefault = (item: WorkflowDirectTaskItem) => ({
+    model: item.model ?? options.model,
+    fallbackModels: item.fallbackModels ?? options.fallbackModels,
+  });
+  if (args.task !== undefined && typeof args.task === "object") return [withFallbackDefault(args.task)];
+  if (Array.isArray(args.tasks)) return args.tasks.map(withFallbackDefault);
+  if (Array.isArray(args.chain)) {
+    return args.chain.flatMap((step) =>
+      "parallel" in step
+        ? step.parallel.map(withFallbackDefault)
+        : [withFallbackDefault(step)],
+    );
+  }
+  return [];
+}
+
+export function directProgressTotal(args: WorkflowToolArgs): number {
+  const countTask = (task: WorkflowDirectTaskItem): number => task.count ?? 1;
+  const countChainStep = (step: WorkflowChainStep): number =>
+    "parallel" in step
+      ? step.parallel.reduce((total, task) => total + countTask(task), 0)
+      : 1;
+  if (Array.isArray(args.chain)) {
+    return args.chain.reduce((total, step) => total + countChainStep(step), 0);
+  }
+  if (Array.isArray(args.tasks)) {
+    return args.tasks.reduce((total, task) => total + countTask(task), 0);
+  }
+  return 1;
+}

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

@@ -19,9 +19,6 @@ import {
   type WorkflowMcpPort,
   type WorkflowRuntimeConfig,
   type WorkflowDetails,
-  type WorkflowDirectOptions,
-  type WorkflowDirectTaskItem,
-  type WorkflowChainStep,
   type WorkflowModelCatalogPort,
   type WorkflowExecutionPolicy,
 } from "../shared/types.js";
@@ -46,6 +43,7 @@ import { runDetached } from "../runs/background/runner.js";
 import type { JobTracker } from "../runs/background/job-tracker.js";
 import { appendRunEnd } from "../shared/persistence-session-entries.js";
 import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
+import { directMode, directModelRequests, directOptions, directProgressTotal } from "./runtime-direct.js";
 
 // ---------------------------------------------------------------------------
 // Options
@@ -185,95 +183,6 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
     };
   }
 
-  function withoutUndefinedProperties<T extends object>(value: T): Partial<T> {
-    return Object.fromEntries(
-      Object.entries(value).filter(([, field]) => field !== undefined),
-    ) as Partial<T>;
-  }
-
-  function directOptions(args: WorkflowToolArgs): WorkflowDirectOptions {
-    const {
-      workflow: _workflow,
-      inputs: _inputs,
-      action: _action,
-      runId: _runId,
-      task,
-      tasks: _tasks,
-      chain: _chain,
-      chainName,
-      concurrency,
-      failFast,
-      async: _async,
-      intercom: _intercom,
-      output,
-      outputMode,
-      reads,
-      chainDir,
-      maxOutput,
-      artifacts,
-      worktree,
-      gitWorktreeDir,
-      baseBranch,
-      ...stageOptions
-    } = args;
-
-    return {
-      ...withoutUndefinedProperties(stageOptions),
-      ...(typeof task === "string" ? { task } : {}),
-      ...(typeof chainName === "string" ? { chainName } : {}),
-      ...(typeof concurrency === "number" ? { concurrency } : {}),
-      ...(typeof failFast === "boolean" ? { failFast } : {}),
-      ...(typeof chainDir === "string" ? { chainDir } : {}),
-      ...(output !== undefined ? { output } : {}),
-      ...(outputMode !== undefined ? { outputMode } : {}),
-      ...(reads !== undefined ? { reads } : {}),
-      ...(maxOutput !== undefined ? { maxOutput } : {}),
-      ...(typeof artifacts === "boolean" ? { artifacts } : {}),
-      ...(typeof worktree === "boolean" ? { worktree } : {}),
-      ...(typeof gitWorktreeDir === "string" ? { gitWorktreeDir } : {}),
-      ...(typeof baseBranch === "string" ? { baseBranch } : {}),
-    };
-  }
-
-  function directMode(args: WorkflowToolArgs): WorkflowDetails["mode"] {
-    if (Array.isArray(args.chain)) return "chain";
-    if (Array.isArray(args.tasks)) return "parallel";
-    return "single";
-  }
-
-  function directModelRequests(args: WorkflowToolArgs): Array<{ readonly model?: WorkflowDirectTaskItem["model"]; readonly fallbackModels?: readonly string[] }> {
-    const options = directOptions(args);
-    const withFallbackDefault = (item: WorkflowDirectTaskItem) => ({
-      model: item.model ?? options.model,
-      fallbackModels: item.fallbackModels ?? options.fallbackModels,
-    });
-    if (args.task !== undefined && typeof args.task === "object") return [withFallbackDefault(args.task)];
-    if (Array.isArray(args.tasks)) return args.tasks.map(withFallbackDefault);
-    if (Array.isArray(args.chain)) {
-      return args.chain.flatMap((step) =>
-        "parallel" in step
-          ? step.parallel.map(withFallbackDefault)
-          : [withFallbackDefault(step)],
-      );
-    }
-    return [];
-  }
-
-  function directProgressTotal(args: WorkflowToolArgs): number {
-    const countTask = (task: WorkflowDirectTaskItem): number => task.count ?? 1;
-    const countChainStep = (step: WorkflowChainStep): number =>
-      "parallel" in step
-        ? step.parallel.reduce((total, task) => total + countTask(task), 0)
-        : 1;
-    if (Array.isArray(args.chain)) {
-      return args.chain.reduce((total, step) => total + countChainStep(step), 0);
-    }
-    if (Array.isArray(args.tasks)) {
-      return args.tasks.reduce((total, task) => total + countTask(task), 0);
-    }
-    return 1;
-  }
-
   function explicitIntercomDelivery(args: WorkflowToolArgs): WorkflowIntercomDelivery | undefined {
     if (args.intercom?.enabled === false) return "off";
     if (args.intercom?.delivery !== undefined) return args.intercom.delivery;