@relayflows/core 0.0.1 → 1.0.0

package/dist/budget-tracker.js

@@ -0,0 +1,184 @@
+function emptyUsage() {
+    return { input: 0, output: 0, cacheRead: 0, total: 0 };
+}
+function toUsage(value) {
+    if (typeof value === 'number') {
+        const input = Number.isFinite(value) ? Math.max(0, Math.round(value)) : 0;
+        return { input, output: 0, cacheRead: 0, total: input };
+    }
+    const input = Number.isFinite(value.input) ? Math.max(0, Math.round(value.input ?? 0)) : 0;
+    const output = Number.isFinite(value.output) ? Math.max(0, Math.round(value.output ?? 0)) : 0;
+    const cacheRead = Number.isFinite(value.cacheRead) ? Math.max(0, Math.round(value.cacheRead ?? 0)) : 0;
+    return {
+        input,
+        output,
+        cacheRead,
+        total: input + output,
+    };
+}
+function addUsage(left, right) {
+    const input = left.input + right.input;
+    const output = left.output + right.output;
+    const cacheRead = left.cacheRead + right.cacheRead;
+    return {
+        input,
+        output,
+        cacheRead,
+        total: input + output,
+    };
+}
+export class BudgetExceededError extends Error {
+    stepName;
+    budgetType;
+    limit;
+    actual;
+    used;
+    constructor(stepName, budgetType, limit, actual) {
+        const qualifier = budgetType === 'workflow' ? 'workflow budget exhausted' : 'agent budget exceeded';
+        super(`Step "${stepName}" cannot continue: ${qualifier} (${actual}/${limit})`);
+        this.name = 'BudgetExceededError';
+        this.stepName = stepName;
+        this.budgetType = budgetType;
+        this.limit = limit;
+        this.actual = actual;
+        this.used = actual;
+    }
+}
+export class BudgetTracker {
+    defaultAgentBudget;
+    workflowBudget;
+    stepLimits = new Map();
+    stepUsage = new Map();
+    totalUsage = emptyUsage();
+    workflowBudgetExhausted = false;
+    constructor(options) {
+        this.defaultAgentBudget = options.perAgent;
+        this.workflowBudget = options.workflowBudget ?? options.perWorkflow;
+        for (const step of options.steps ?? []) {
+            this.stepLimits.set(step.stepName, step.maxTokens);
+        }
+    }
+    recordUsage(stepName, usage) {
+        const normalized = toUsage(usage);
+        const current = this.stepUsage.get(stepName) ?? emptyUsage();
+        const next = addUsage(current, normalized);
+        this.stepUsage.set(stepName, next);
+        this.totalUsage = addUsage(this.totalUsage, normalized);
+        if (this.workflowBudget !== undefined && this.totalUsage.total >= this.workflowBudget) {
+            this.workflowBudgetExhausted = true;
+        }
+    }
+    getStepUsage(stepName) {
+        return this.stepUsage.get(stepName) ?? emptyUsage();
+    }
+    getTotalUsage() {
+        return this.totalUsage;
+    }
+    getRemainingBudget() {
+        return {
+            agent: this.defaultAgentBudget !== undefined
+                ? Math.max(0, this.defaultAgentBudget - this.totalUsage.total)
+                : undefined,
+            workflow: this.workflowBudget !== undefined
+                ? Math.max(0, this.workflowBudget - this.totalUsage.total)
+                : undefined,
+        };
+    }
+    checkCanSpawn(stepName) {
+        if (this.workflowBudget !== undefined && this.totalUsage.total >= this.workflowBudget) {
+            return {
+                allowed: false,
+                reason: `Cannot spawn ${stepName}: workflow budget exceeded (${this.totalUsage.total}/${this.workflowBudget})`,
+            };
+        }
+        if (this.workflowBudget !== undefined) {
+            const remainingWorkflowBudget = this.workflowBudget - this.totalUsage.total;
+            const stepLimit = this.getStepLimit(stepName);
+            const minimumHeadroom = stepLimit !== undefined
+                ? Math.min(stepLimit, this.workflowBudget)
+                : this.defaultAgentBudget !== undefined
+                    ? Math.ceil(this.defaultAgentBudget * 0.1)
+                    : Math.ceil(this.workflowBudget * 0.1);
+            if (remainingWorkflowBudget <= minimumHeadroom) {
+                return {
+                    allowed: false,
+                    reason: stepLimit !== undefined
+                        ? `Cannot spawn ${stepName}: remaining workflow budget ${remainingWorkflowBudget} is below step budget ${stepLimit}`
+                        : this.defaultAgentBudget !== undefined
+                            ? `Cannot spawn ${stepName}: remaining workflow budget ${remainingWorkflowBudget} ` +
+                                `is below 10% of per-agent budget ${this.defaultAgentBudget}`
+                            : `Cannot spawn ${stepName}: remaining workflow budget ${remainingWorkflowBudget} ` +
+                                `is below 10% headroom threshold for workflow budget ${this.workflowBudget}`,
+                };
+            }
+        }
+        return { allowed: true };
+    }
+    isOverBudget(stepName) {
+        const stepUsage = this.getStepUsage(stepName);
+        const stepLimit = this.getStepLimit(stepName);
+        if (stepLimit !== undefined && stepUsage.total > stepLimit) {
+            return {
+                over: true,
+                reason: `Step "${stepName}" exceeded per-agent budget (${stepUsage.total}/${stepLimit})`,
+            };
+        }
+        if (this.workflowBudget !== undefined && this.totalUsage.total > this.workflowBudget) {
+            return {
+                over: true,
+                reason: `Workflow exceeded total budget (${this.totalUsage.total}/${this.workflowBudget})`,
+            };
+        }
+        return { over: false };
+    }
+    getBudgetStatus(stepName) {
+        const stepUsage = this.getStepUsage(stepName);
+        const stepLimit = this.getStepLimit(stepName);
+        return {
+            agentLimitExceeded: stepLimit !== undefined && stepUsage.total > stepLimit,
+            workflowBudgetExceeded: this.workflowBudget !== undefined && this.totalUsage.total > this.workflowBudget,
+            workflowBudgetExhausted: this.workflowBudget !== undefined &&
+                (this.workflowBudgetExhausted || this.totalUsage.total >= this.workflowBudget),
+        };
+    }
+    getStepBudgetStatus(stepName) {
+        const usage = this.stepUsage.get(stepName);
+        const hasExplicitLimit = this.stepLimits.has(stepName);
+        const limit = this.getStepLimit(stepName);
+        if (!usage && !hasExplicitLimit && limit === undefined) {
+            return undefined;
+        }
+        return {
+            used: usage?.total,
+            limit,
+            over: limit !== undefined && (usage?.total ?? 0) > limit,
+        };
+    }
+    getRunSummaryBudgetData() {
+        const steps = new Map();
+        const stepNames = new Set([...this.stepLimits.keys(), ...this.stepUsage.keys()]);
+        for (const stepName of stepNames) {
+            const status = this.getStepBudgetStatus(stepName);
+            if (status) {
+                steps.set(stepName, status);
+            }
+        }
+        const workflow = this.workflowBudget !== undefined || this.totalUsage.total > 0
+            ? {
+                used: this.totalUsage.total,
+                limit: this.workflowBudget,
+                exhausted: this.workflowBudget !== undefined &&
+                    (this.workflowBudgetExhausted || this.totalUsage.total >= this.workflowBudget),
+            }
+            : undefined;
+        if (steps.size === 0 && !workflow) {
+            return undefined;
+        }
+        return { steps, workflow };
+    }
+    getStepLimit(stepName) {
+        const limit = this.stepLimits.get(stepName);
+        return limit ?? this.defaultAgentBudget;
+    }
+}
+//# sourceMappingURL=budget-tracker.js.map

package/dist/budget-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-tracker.js","sourceRoot":"","sources":["../src/budget-tracker.ts"],"names":[],"mappings":"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"}

package/dist/builder.d.ts

@@ -0,0 +1,229 @@
+import type { RuntimeSpawnOptions } from '@agent-relay/harness-driver';
+import type { AgentCli, AgentPreset, CoordinationConfig, DryRunReport, IdleNudgeConfig, PathDefinition, RelayYamlConfig, StateConfig, SwarmPattern, TrajectoryConfig, VerificationCheck, WorkflowRunRow } from './types.js';
+import { type WorkflowEventListener } from './runner.js';
+import type { RunnerStepExecutor } from './types.js';
+import { type LogLevel } from './default-logger.js';
+import type { VariableContext } from './template-resolver.js';
+export interface AgentOptions {
+    cli: AgentCli;
+    role?: string;
+    task?: string;
+    channels?: string[];
+    model?: string;
+    maxTokens?: number;
+    timeoutMs?: number;
+    retries?: number;
+    /**
+     * Seconds of silence on the agent's PTY before the runtime marks it idle and
+     * tears it down. Default: 30s. Set to `0` to disable idle detection entirely.
+     *
+     * When to override (per-agent):
+     *   - You expect long quiet stretches by design — a long-running reviewer
+     *     waiting for downstream verdicts, a grader watching a file that updates
+     *     every few minutes, or a `@-mention` recipient whose triggering event
+     *     may arrive >30s after spawn. Setting `0` (or a generous N) prevents
+     *     the runtime from killing the agent before the awaited event arrives.
+     *
+     * When NOT to override:
+     *   - One-shot worker steps. The default is right; idle-as-complete is what
+     *     makes `OWNER_DECISION: COMPLETE` + clean exit fast.
+     *
+     * See the `writing-agent-relay-workflows` skill ("Idle detection beats
+     * 'wait for X' prompts") for the trade-offs around long-running interactive
+     * agents and the Per-turn interactive spawn alternative.
+     */
+    idleThresholdSecs?: number;
+    /** When false, the agent runs as a non-interactive subprocess (no PTY, no relay messaging).
+     *  Default: true. */
+    interactive?: boolean;
+    /** Agent preset: 'lead' (interactive PTY), 'worker' | 'reviewer' | 'analyst' (non-interactive subprocess). */
+    preset?: AgentPreset;
+    /** Skills to make available to the agent (for API-mode agents). */
+    skills?: string;
+}
+/** Options for agent steps (default). */
+export interface AgentStepOptions {
+    agent: string;
+    task: string;
+    cwd?: string;
+    dependsOn?: string[];
+    verification?: VerificationCheck;
+    timeoutMs?: number;
+    retries?: number;
+}
+/** Options for deterministic (shell command) steps. */
+export interface DeterministicStepOptions {
+    type: 'deterministic';
+    command: string;
+    cwd?: string;
+    /** Capture stdout as step output for downstream steps. Default: true. */
+    captureOutput?: boolean;
+    /** Fail if command exit code is non-zero. Default: true. */
+    failOnError?: boolean;
+    dependsOn?: string[];
+    verification?: VerificationCheck;
+    timeoutMs?: number;
+}
+/** Options for worktree steps (create/checkout git worktrees). */
+export interface WorktreeStepOptions {
+    type: 'worktree';
+    branch: string;
+    baseBranch?: string;
+    path?: string;
+    createBranch?: boolean;
+    dependsOn?: string[];
+    timeoutMs?: number;
+}
+export type StepOptions = AgentStepOptions | DeterministicStepOptions | WorktreeStepOptions;
+export interface ErrorOptions {
+    maxRetries?: number;
+    retryDelayMs?: number;
+    notifyChannel?: string;
+    repairAgent?: string;
+    repairRetries?: number;
+}
+export type ReliabilityOptions = ErrorOptions;
+export interface WorkflowRunOptions {
+    /** Run a specific workflow by name (default: first). */
+    workflow?: string;
+    /** Template variable substitutions. */
+    vars?: VariableContext;
+    /** Working directory (default: process.cwd()). */
+    cwd?: string;
+    /** AgentRelay options (all optional). */
+    relay?: RuntimeSpawnOptions;
+    /** Progress callback. */
+    onEvent?: WorkflowEventListener;
+    /** Validate and print execution plan without spawning agents. */
+    dryRun?: boolean;
+    /** External step executor (e.g. Daytona sandbox backend). */
+    executor?: RunnerStepExecutor;
+    /** Start from a specific step, skipping all predecessors. */
+    startFrom?: string;
+    /** Previous run ID whose cached outputs are used with startFrom. */
+    previousRunId?: string;
+    /** Console log verbosity: "verbose" | "normal" (default) | "quiet" | false (silent). */
+    logLevel?: LogLevel;
+    /** Renderer: "listr" for listr2 UI, "default" for console logger, false to disable. */
+    renderer?: 'listr' | 'default' | false;
+    /** Run the workflow in the cloud instead of locally. */
+    cloud?: boolean;
+    /** Cloud API base URL (or set CLOUD_API_URL env var). */
+    cloudApiUrl?: string;
+    /** Cloud API authentication token (or set CLOUD_API_TOKEN env var). */
+    cloudApiToken?: string;
+    /** Environment secrets to forward to cloud agents. */
+    envSecrets?: Record<string, string>;
+    /** Polling interval in ms for cloud run status checks. */
+    cloudPollIntervalMs?: number;
+    /** Callback invoked when the cloud run status changes. */
+    onCloudStatusChange?: (status: string, runId: string) => void;
+}
+/**
+ * Fluent builder for constructing workflow configurations programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { workflow } from "@relayflows/core";
+ *
+ * const result = await workflow("my-workflow")
+ *   .pattern("dag")
+ *   .agent("worker", { cli: "claude", role: "Backend engineer" })
+ *   .step("build", { agent: "worker", task: "Build the project" })
+ *   .step("test", { agent: "worker", task: "Run tests", dependsOn: ["build"] })
+ *   .run();
+ * ```
+ */
+export declare class WorkflowBuilder {
+    private _name;
+    private _description?;
+    private _pattern;
+    private _maxConcurrency?;
+    private _timeoutMs?;
+    private _channel?;
+    private _idleNudge?;
+    private _paths?;
+    private _agents;
+    private _steps;
+    private _errorHandling?;
+    private _coordination?;
+    private _state?;
+    private _trajectories?;
+    private _startFrom?;
+    private _previousRunId?;
+    constructor(name: string);
+    /** Set workflow description. */
+    description(desc: string): this;
+    /** Set swarm pattern (default: "dag"). */
+    pattern(p: SwarmPattern): this;
+    /** Set maximum concurrent agents. */
+    maxConcurrency(n: number): this;
+    /** Set global timeout in milliseconds. */
+    timeout(ms: number): this;
+    /** Set the relay channel for agent communication. */
+    channel(ch: string): this;
+    /** Configure idle agent detection and nudging for interactive agents. */
+    idleNudge(config: IdleNudgeConfig): this;
+    /** Set workflow coordination settings (barriers, voting threshold, consensus strategy). */
+    coordination(config: CoordinationConfig): this;
+    /** Configure shared workflow state backend settings. */
+    state(config: StateConfig): this;
+    /** Configure trajectory recording, or pass `false` to disable it. */
+    trajectories(config: TrajectoryConfig | false): this;
+    /** Start execution from a specific step, skipping all predecessor steps. */
+    startFrom(stepName: string): this;
+    /** Set the previous run ID whose cached step outputs should be used with startFrom. */
+    previousRunId(id: string): this;
+    /**
+     * Declare named paths to additional directories the workflow needs.
+     *
+     * For multi-repo cloud workflows (relay#774, cloud#302), each entry is
+     * tarballed by the CLI at submit time and mounted at
+     * `/home/daytona/workspace/{name}/` in the sandbox. Locally, the runner
+     * resolves `path` relative to the workflow file's parent directory and
+     * agents reference each entry by its declared `name`.
+     *
+     * Calling this is a no-op for the runtime — the runner doesn't need
+     * `paths` to execute steps. The CLI and the cloud bootstrap consume
+     * it. Declaring via the builder keeps single-source-of-truth for tools
+     * that walk the built config (e.g. dashboards, dry-run reports).
+     */
+    paths(paths: PathDefinition[]): this;
+    /** Add an agent definition. */
+    agent(name: string, options: AgentOptions): this;
+    /** Add a workflow step (agent or deterministic). */
+    step(name: string, options: StepOptions): this;
+    /** Set error handling strategy. */
+    onError(strategy: 'fail-fast' | 'continue' | 'retry', options?: ErrorOptions): this;
+    /**
+     * Opt into the product reliability contract: repairable workflow failures get
+     * routed through an agent and retried before the workflow is allowed to fail.
+     */
+    repairable(options?: ReliabilityOptions): this;
+    /** Alias for `.repairable()` for workflow authors who think in product terms. */
+    reliable(options?: ReliabilityOptions): this;
+    private validateBuilderState;
+    /** Build and return the RelayYamlConfig object. */
+    toConfig(): RelayYamlConfig;
+    /** Serialize the config to a YAML string. */
+    toYaml(): string;
+    /** Build the config and execute it with the WorkflowRunner. */
+    run(options: WorkflowRunOptions & {
+        dryRun: true;
+    }): Promise<DryRunReport>;
+    run(options?: WorkflowRunOptions): Promise<WorkflowRunRow>;
+}
+/**
+ * Create a new workflow builder.
+ *
+ * @example
+ * ```typescript
+ * const result = await workflow("my-task")
+ *   .pattern("fan-out")
+ *   .agent("worker", { cli: "claude" })
+ *   .step("do-work", { agent: "worker", task: "Build the feature" })
+ *   .run();
+ * ```
+ */
+export declare function workflow(name: string): WorkflowBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}