@kb-labs/workflow-runtime 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,524 @@
+import { StepSpec } from '@kb-labs/workflow-contracts';
+import { ArtifactClient } from '@kb-labs/workflow-artifacts';
+export { ArtifactClient, ArtifactInput, ArtifactOutput, ArtifactReference, FileSystemArtifactClient, createFileSystemArtifactClient } from '@kb-labs/workflow-artifacts';
+import { StepState } from '@kb-labs/workflow-constants';
+import { PluginContextV3, ExecutionTarget } from '@kb-labs/plugin-contracts';
+import { ExecutionBackend } from '@kb-labs/plugin-execution';
+import { IEntityRegistry, RegistrySnapshot } from '@kb-labs/core-registry';
+import { IAnalytics } from '@kb-labs/core-platform';
+import { z } from 'zod';
+
+interface RuntimeLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+interface RuntimeEvents {
+    emit(name: string, payload: Record<string, unknown>): Promise<void> | void;
+}
+interface RuntimeTrace {
+    traceId: string;
+    spanId?: string;
+    parentSpanId?: string;
+}
+interface StepContext {
+    runId: string;
+    jobId: string;
+    stepId: string;
+    attempt: number;
+    env: Record<string, string>;
+    secrets: Record<string, string>;
+    artifacts?: ArtifactClient;
+    events?: RuntimeEvents;
+    logger: RuntimeLogger;
+    trace?: RuntimeTrace;
+    pluginContext?: PluginContextV3;
+    onLog?: (entry: {
+        level: string;
+        message: string;
+        stream: 'stdout' | 'stderr';
+        lineNo: number;
+        timestamp: string;
+        meta?: Record<string, unknown>;
+    }) => void;
+}
+interface StepExecutionRequest {
+    spec: StepSpec;
+    context: StepContext;
+    workspace?: string;
+    target?: ExecutionTarget;
+    signal?: AbortSignal;
+}
+interface StepExecutionSuccess {
+    status: Extract<StepState, 'success'>;
+    outputs?: Record<string, unknown>;
+}
+interface StepExecutionFailure {
+    status: Extract<StepState, 'failed' | 'cancelled'>;
+    error: {
+        message: string;
+        code?: string;
+        stack?: string;
+        details?: Record<string, unknown>;
+    };
+}
+type StepExecutionResult = StepExecutionSuccess | StepExecutionFailure;
+interface Runner {
+    execute(request: StepExecutionRequest): Promise<StepExecutionResult>;
+}
+
+interface CreateStepContextInput {
+    runId: string;
+    jobId: string;
+    stepId: string;
+    attempt?: number;
+    env?: Record<string, string>;
+    secrets?: Record<string, string>;
+    artifacts?: ArtifactClient;
+    events?: RuntimeEvents;
+    logger: RuntimeLogger;
+    trace?: RuntimeTrace;
+}
+declare function createStepContext(input: CreateStepContextInput): StepContext;
+
+interface LocalRunnerOptions {
+    shell?: string;
+}
+declare class LocalRunner implements Runner {
+    private readonly shell;
+    constructor(options?: LocalRunnerOptions);
+    execute(request: StepExecutionRequest): Promise<StepExecutionResult>;
+}
+
+/**
+ * @module @kb-labs/workflow-runtime/runners/sandbox-runner
+ *
+ * V3 SandboxRunner - executes plugin handlers using platform ExecutionBackend.
+ *
+ * This runner is for steps that specify `uses: "plugin:..."` or `uses: "command:..."`.
+ * It delegates execution to the platform's unified ExecutionBackend instead of
+ * implementing custom plugin execution logic.
+ *
+ * ## Integration Pattern (REST API-style)
+ *
+ * Instead of resolving plugins inline inside the runner, we:
+ * 1. Accept ExecutionBackend from platform (via options)
+ * 2. Build ExecutionRequest with PluginContextDescriptor
+ * 3. Call backend.execute() - platform handles the rest
+ *
+ * This matches the REST API pattern where execution is delegated to the platform layer.
+ *
+ * @example
+ * ```typescript
+ * const runner = new SandboxRunner({
+ *   backend: platform.executionBackend,
+ *   cliApi, // For plugin resolution
+ * });
+ *
+ * const result = await runner.execute({
+ *   spec: { uses: 'plugin:release-manager/create-release', with: { version: '1.0.0' } },
+ *   context: stepContext,
+ * });
+ * ```
+ */
+
+interface SandboxRunnerOptions {
+    /**
+     * Platform ExecutionBackend (REQUIRED).
+     * Obtained from platform.executionBackend.
+     */
+    backend: ExecutionBackend;
+    /**
+     * CLI API for plugin resolution (REQUIRED).
+     * Needed to resolve plugin IDs to plugin roots and handler paths.
+     */
+    cliApi: IEntityRegistry;
+    /**
+     * Workspace root directory.
+     * Default: process.cwd()
+     */
+    workspaceRoot?: string;
+    /**
+     * Default timeout for plugin execution (ms).
+     * Default: 120000 (2 minutes)
+     */
+    defaultTimeout?: number;
+    /**
+     * Platform analytics adapter (OPTIONAL)
+     */
+    analytics?: IAnalytics;
+}
+/**
+ * SandboxRunner - V3 implementation using platform ExecutionBackend.
+ *
+ * Executes plugin handlers through the unified execution layer.
+ * Supports both `uses: "plugin:id/handler"` and `uses: "command:name"` syntax.
+ */
+declare class SandboxRunner implements Runner {
+    private readonly backend;
+    private readonly cliApi;
+    private readonly workspaceRoot;
+    private readonly defaultTimeout;
+    private readonly analytics?;
+    private readonly logger?;
+    constructor(options: SandboxRunnerOptions);
+    execute(request: StepExecutionRequest): Promise<StepExecutionResult>;
+    /**
+     * Validate step spec and build error result if invalid
+     */
+    private buildValidationError;
+    /**
+     * Try to resolve command, returning result wrapper
+     */
+    private tryResolveCommand;
+    /**
+     * Build ExecutionRequest from resolved command
+     */
+    private buildExecutionRequest;
+    /**
+     * Map ExecutionResult to StepExecutionResult
+     */
+    private mapExecutionResult;
+    /**
+     * Resolve command reference to plugin handler.
+     *
+     * Supports three formats:
+     * - `plugin:id/handler` - workflow handler (native)
+     * - `command:name` - CLI command (via adapter)
+     * - `builtin:shell` - built-in shell execution
+     */
+    private resolveCommand;
+    /**
+     * Resolve plugin handler reference.
+     * Format: `plugin:id/handler` or `plugin:id/path/to/handler`
+     */
+    private resolvePluginHandler;
+    /**
+     * Resolve CLI command to plugin handler (with adapter).
+     *
+     * Format: `command:name` (e.g., `command:mind:rag-index`)
+     *
+     * This uses the CLI Adapter pattern to make CLI commands work in workflow context:
+     * - Searches for CLI command in plugin manifests
+     * - Wraps workflow input in CLI-compatible format { argv, flags, cwd }
+     * - Allows reusing existing CLI commands without writing workflow handlers
+     */
+    private resolveCLICommand;
+    /**
+     * CLI Adapter: Convert workflow input to CLI-compatible format.
+     *
+     * Transforms:
+     *   { scope: "default", incremental: true }
+     * Into:
+     *   { argv: [], flags: { scope: "default", incremental: true }, cwd: "/workspace" }
+     *
+     * This allows CLI commands to work in workflow context without modification.
+     */
+    private adaptToCLIFormat;
+    /**
+     * Resolve builtin:shell to built-in shell handler.
+     *
+     * Returns a resolution pointing to the builtin-handlers/shell.js file
+     * that will be executed through ExecutionBackend.
+     */
+    private resolveBuiltinShell;
+}
+
+declare const RemoteMarketplaceSourceSchema: z.ZodObject<{
+    name: z.ZodString;
+    url: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    url: string;
+    ref?: string | undefined;
+    path?: string | undefined;
+}, {
+    name: string;
+    url: string;
+    ref?: string | undefined;
+    path?: string | undefined;
+}>;
+declare const BudgetConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    period: z.ZodDefault<z.ZodEnum<["run", "day", "week", "month"]>>;
+    action: z.ZodDefault<z.ZodEnum<["warn", "fail", "cancel"]>>;
+    costCalculator: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    period: "run" | "day" | "week" | "month";
+    action: "warn" | "fail" | "cancel";
+    limit?: number | undefined;
+    costCalculator?: string | undefined;
+}, {
+    enabled?: boolean | undefined;
+    limit?: number | undefined;
+    period?: "run" | "day" | "week" | "month" | undefined;
+    action?: "warn" | "fail" | "cancel" | undefined;
+    costCalculator?: string | undefined;
+}>;
+declare const WorkflowConfigSchema: z.ZodObject<{
+    workspaces: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    plugins: z.ZodDefault<z.ZodBoolean>;
+    remotes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodString;
+        ref: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        url: string;
+        ref?: string | undefined;
+        path?: string | undefined;
+    }, {
+        name: string;
+        url: string;
+        ref?: string | undefined;
+        path?: string | undefined;
+    }>, "many">>;
+    maxDepth: z.ZodDefault<z.ZodNumber>;
+    budget: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        period: z.ZodDefault<z.ZodEnum<["run", "day", "week", "month"]>>;
+        action: z.ZodDefault<z.ZodEnum<["warn", "fail", "cancel"]>>;
+        costCalculator: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        period: "run" | "day" | "week" | "month";
+        action: "warn" | "fail" | "cancel";
+        limit?: number | undefined;
+        costCalculator?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        limit?: number | undefined;
+        period?: "run" | "day" | "week" | "month" | undefined;
+        action?: "warn" | "fail" | "cancel" | undefined;
+        costCalculator?: string | undefined;
+    }>>;
+    defaults: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<["wait", "fire-and-forget"]>>;
+        inheritEnv: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "wait" | "fire-and-forget";
+        inheritEnv: boolean;
+    }, {
+        mode?: "wait" | "fire-and-forget" | undefined;
+        inheritEnv?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    workspaces: string[];
+    plugins: boolean;
+    maxDepth: number;
+    remotes?: {
+        name: string;
+        url: string;
+        ref?: string | undefined;
+        path?: string | undefined;
+    }[] | undefined;
+    budget?: {
+        enabled: boolean;
+        period: "run" | "day" | "week" | "month";
+        action: "warn" | "fail" | "cancel";
+        limit?: number | undefined;
+        costCalculator?: string | undefined;
+    } | undefined;
+    defaults?: {
+        mode: "wait" | "fire-and-forget";
+        inheritEnv: boolean;
+    } | undefined;
+}, {
+    workspaces?: string[] | undefined;
+    plugins?: boolean | undefined;
+    remotes?: {
+        name: string;
+        url: string;
+        ref?: string | undefined;
+        path?: string | undefined;
+    }[] | undefined;
+    maxDepth?: number | undefined;
+    budget?: {
+        enabled?: boolean | undefined;
+        limit?: number | undefined;
+        period?: "run" | "day" | "week" | "month" | undefined;
+        action?: "warn" | "fail" | "cancel" | undefined;
+        costCalculator?: string | undefined;
+    } | undefined;
+    defaults?: {
+        mode?: "wait" | "fire-and-forget" | undefined;
+        inheritEnv?: boolean | undefined;
+    } | undefined;
+}>;
+type WorkflowConfig = z.infer<typeof WorkflowConfigSchema>;
+type RemoteMarketplaceSource = z.infer<typeof RemoteMarketplaceSourceSchema>;
+type BudgetConfig = z.infer<typeof BudgetConfigSchema>;
+/**
+ * Load workflow configuration from kb.config.json
+ */
+declare function loadWorkflowConfig(workspaceRoot: string): Promise<WorkflowConfig>;
+/**
+ * Save workflow configuration to kb.config.json
+ * Safely merges with existing config without overwriting other sections
+ */
+declare function saveWorkflowConfig(workspaceRoot: string, updates: Partial<WorkflowConfig>): Promise<void>;
+
+/**
+ * Resolved workflow information from registry
+ */
+interface ResolvedWorkflow {
+    /** Workflow ID (e.g., "workspace:ai-ci", "plugin:@kb-labs/ai-review/full-audit") */
+    id: string;
+    /** Source of the workflow */
+    source: 'workspace' | 'plugin';
+    /** Absolute path to workflow file (YAML/JSON) */
+    filePath: string;
+    /** Optional description from workflow spec */
+    description?: string;
+    /** Optional tags for filtering */
+    tags?: string[];
+    /** Optional metadata (plugin ID, version, etc.) */
+    metadata?: {
+        pluginId?: string;
+        pluginVersion?: string;
+    };
+}
+/**
+ * Base interface for workflow registry
+ */
+interface WorkflowRegistry {
+    /**
+     * List all discovered workflows (cached)
+     */
+    list(): Promise<ResolvedWorkflow[]>;
+    /**
+     * Resolve workflow by ID
+     * @param id - Workflow ID (with or without prefix)
+     */
+    resolve(id: string): Promise<ResolvedWorkflow | null>;
+    /**
+     * Refresh the cache (explicit update)
+     */
+    refresh(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    dispose?(): Promise<void>;
+}
+/**
+ * Configuration for workflow registry
+ */
+interface WorkflowRegistryConfig {
+    /** Workspace root directory */
+    workspaceRoot: string;
+    /** Glob patterns for workspace workflows */
+    workspaces?: string[];
+    /** Include plugin workflows */
+    plugins?: boolean;
+    /** Cache configuration */
+    cache?: {
+        /** Time-to-live in milliseconds (optional, for future) */
+        ttl?: number;
+    };
+}
+
+interface WorkspaceWorkflowRegistryConfig {
+    workspaceRoot: string;
+    patterns: string[];
+}
+/**
+ * Registry for workspace workflows (from .kb/workflows glob patterns)
+ */
+declare class WorkspaceWorkflowRegistry implements WorkflowRegistry {
+    private readonly config;
+    private cache;
+    constructor(config: WorkspaceWorkflowRegistryConfig);
+    list(): Promise<ResolvedWorkflow[]>;
+    resolve(id: string): Promise<ResolvedWorkflow | null>;
+    refresh(): Promise<void>;
+    dispose(): Promise<void>;
+    private loadWorkflowSpec;
+    private generateId;
+}
+
+interface LoggerLike {
+    debug?(msg: string, meta?: Record<string, unknown>): void;
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+    error?(msg: string, meta?: Record<string, unknown>): void;
+}
+interface RemoteWorkflowRegistryConfig {
+    workspaceRoot: string;
+    remotes: RemoteMarketplaceSource[];
+    cacheDir?: string;
+    logger?: LoggerLike;
+}
+/**
+ * Registry for remote workflows (from git repositories)
+ */
+declare class RemoteWorkflowRegistry implements WorkflowRegistry {
+    private readonly config;
+    private cache;
+    private readonly cacheDir;
+    private readonly logger?;
+    constructor(config: RemoteWorkflowRegistryConfig);
+    list(): Promise<ResolvedWorkflow[]>;
+    resolve(id: string): Promise<ResolvedWorkflow | null>;
+    refresh(): Promise<void>;
+    dispose(): Promise<void>;
+    private loadWorkflowsFromRemote;
+    private ensureRemoteCloned;
+    private updateRemote;
+    private loadWorkflowSpec;
+    private generateId;
+    private getRepoName;
+}
+
+/**
+ * Composite registry that combines workspace, plugin (via IEntityRegistry), and remote registries
+ */
+declare class CompositeWorkflowRegistry implements WorkflowRegistry {
+    private readonly workspace;
+    private readonly cliApi;
+    private readonly remote?;
+    private cache;
+    constructor(workspace: WorkspaceWorkflowRegistry, cliApi: IEntityRegistry | null, remote?: RemoteWorkflowRegistry | undefined);
+    list(): Promise<ResolvedWorkflow[]>;
+    resolve(id: string): Promise<ResolvedWorkflow | null>;
+    refresh(): Promise<void>;
+    dispose(): Promise<void>;
+}
+
+/**
+ * Error thrown when workflow ID conflicts are detected
+ */
+declare class WorkflowRegistryError extends Error {
+    readonly workflowId?: string | undefined;
+    constructor(message: string, workflowId?: string | undefined);
+}
+
+/**
+ * Extract workflows from CLI API registry snapshot
+ *
+ * Uses the same pattern as REST API - no local discovery, just snapshot extraction.
+ */
+
+/**
+ * Extract workflows from registry snapshot
+ *
+ * @param snapshot - CLI API registry snapshot
+ * @returns Array of resolved workflows from plugin manifests
+ */
+declare function extractWorkflows(snapshot: RegistrySnapshot): Promise<ResolvedWorkflow[]>;
+/**
+ * Find workflow by ID in registry snapshot
+ *
+ * @param snapshot - CLI API registry snapshot
+ * @param id - Workflow ID (with or without "plugin:" prefix)
+ * @returns Resolved workflow or null if not found
+ */
+declare function findWorkflow(snapshot: RegistrySnapshot, id: string): Promise<ResolvedWorkflow | null>;
+
+export { type BudgetConfig, BudgetConfigSchema, CompositeWorkflowRegistry, type CreateStepContextInput, LocalRunner, type LocalRunnerOptions, type RemoteMarketplaceSource, RemoteMarketplaceSourceSchema, type ResolvedWorkflow, type Runner, type RuntimeEvents, type RuntimeLogger, type RuntimeTrace, SandboxRunner, type SandboxRunnerOptions, type StepContext, type StepExecutionFailure, type StepExecutionRequest, type StepExecutionResult, type StepExecutionSuccess, type WorkflowConfig, WorkflowConfigSchema, type WorkflowRegistry, type WorkflowRegistryConfig, WorkflowRegistryError, WorkspaceWorkflowRegistry, createStepContext, extractWorkflows, findWorkflow, loadWorkflowConfig, saveWorkflowConfig };