@chrok/braid 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,238 @@
+export interface ExecuteNode {
+    type: "execute";
+    id: string;
+    prompt: string;
+    model?: string;
+}
+export interface DecisionNode {
+    type: "decision";
+    id: string;
+    prompt: string;
+    choices: readonly string[];
+    model?: string;
+}
+export interface MergeNode {
+    type: "merge";
+    id: string;
+    /** Defaults to reviewing and integrating all predecessor workspaces. */
+    prompt?: string;
+    model?: string;
+}
+export type BraidNode = ExecuteNode | DecisionNode | MergeNode;
+export interface NodeWorkspace {
+    nodeId: string;
+    mode: "read-only" | "worktree" | "merge";
+    workingDirectory: string;
+    worktreeRoot?: string;
+    sourceRoot?: string;
+    baseCommit?: string;
+    snapshotCommit?: string;
+    checkpointRef?: string;
+    checkpointCommit?: string;
+    /** Source checkout snapshot captured before a merge agent receives write access. */
+    backupRef?: string;
+    state: "preparing" | "ready" | "integrated" | "discarded" | "archived" | "failed";
+    reason?: string;
+}
+export interface MergeDisposition {
+    nodeId: string;
+    disposition: "integrated" | "discarded" | "archived";
+    reason: string;
+}
+export interface GitPreview {
+    text: string;
+    truncated: boolean;
+}
+export interface MergeSource extends NodeWorkspace {
+    /** Inspection-only summaries relative to snapshotCommit; omitted by custom runners. */
+    changes?: {
+        files: string[];
+        filesTruncated: boolean;
+        stat: GitPreview;
+        diff: GitPreview;
+    };
+}
+export interface SourceCheckoutStatus extends GitPreview {
+    /** True when Git porcelain status has any staged, unstaged, or untracked entries. */
+    dirty: boolean;
+}
+export interface GitResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface Edge {
+    from: string;
+    to: string;
+    /** Omit for an unconditional edge, including from a decision node. */
+    choice?: string;
+}
+export interface BraidInput {
+    goal: string;
+    nodes: readonly BraidNode[];
+    edges: readonly Edge[];
+}
+export type NodeStatus = "pending" | "runnable" | "running" | "completed" | "skipped" | "failed";
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface NodeOutput {
+    output: string;
+    decision?: string;
+    model?: string;
+}
+export interface PredecessorOutput extends NodeOutput {
+    nodeId: string;
+    /** Failed predecessors remain available on unconditional edges. */
+    error?: ExecutionError;
+    workspace?: NodeWorkspace;
+}
+export interface ExecutionContext {
+    runId: string;
+    /** Equal to runId in v0.1; reserved identity for future shared-root accounting. */
+    rootRunId: string;
+}
+export interface ModelRequest {
+    goal: string;
+    node: BraidNode;
+    /** Node override, otherwise the run's defaultModel, otherwise adapter default. */
+    model?: string;
+    /** Direct active predecessors, including failures on unconditional edges; no parent history. */
+    predecessors: PredecessorOutput[];
+    execution: ExecutionContext;
+    signal: AbortSignal;
+    /** Finite deadlines on the performance.now() clock; absent scopes are unlimited. */
+    deadlines?: {
+        node?: number;
+        graph?: number;
+    };
+    workspace?: NodeWorkspace;
+    /** Adapters must wrap mutating file tools so cancellation and cleanup wait for in-flight writes. */
+    withWorkspaceWrite?: <T>(operation: () => Promise<T>) => Promise<T>;
+    /** Local Git operations: inspection for workers, integration commands for merge nodes. */
+    git?: (args: string[], input?: string) => Promise<GitResult>;
+    /** Merge nodes must account for every source before returning their final answer. */
+    merge?: {
+        sources: MergeSource[];
+        sourceStatus?: SourceCheckoutStatus;
+        finish: (dispositions: MergeDisposition[]) => Promise<void>;
+    };
+    /** Present only on decision nodes. An adapter exposes this as the decide tool. */
+    decide?: (choice: string) => void;
+}
+export interface ModelResponse {
+    output: string;
+    /** The actual model reported by the provider, if known. */
+    model?: string;
+    usage?: TokenUsage;
+}
+/** Each call starts a fresh conversation and exposes only the adapter’s declared capabilities. */
+export type ModelRunner = (request: ModelRequest) => Promise<ModelResponse>;
+/** Frozen snapshots in emission order. Creation means admission of the submitted DAG, not mutation. */
+export type ExecutionEvent = Readonly<{
+    sequence: number;
+    timestamp: number;
+} & ({
+    type: "graph_created";
+    nodeCount: number;
+    edgeCount: number;
+} | {
+    type: "node_created";
+    nodeId: string;
+    nodeType: BraidNode["type"];
+    model?: string;
+} | {
+    type: "edge_created";
+    from: string;
+    to: string;
+    choice?: string;
+} | {
+    type: "workspace_updated";
+    workspace: Readonly<NodeWorkspace>;
+} | {
+    type: "node_runnable";
+    nodeId: string;
+} | {
+    type: "handoff";
+    from: string;
+    to: string;
+    output: string;
+    decision?: string;
+} | {
+    type: "node_started";
+    nodeId: string;
+    model?: string;
+} | ({
+    type: "node_completed";
+    nodeId: string;
+    latencyMs: number;
+    usage?: Readonly<TokenUsage>;
+} & NodeOutput) | {
+    type: "node_skipped";
+    nodeId: string;
+    reason: NonNullable<NodeResult["skipReason"]>;
+} | ({
+    type: "node_failed";
+    nodeId: string;
+    error: Readonly<ExecutionError>;
+    latencyMs: number;
+    usage?: Readonly<TokenUsage>;
+} & Partial<NodeOutput>) | {
+    type: "graph_completed";
+    terminalNodeIds: readonly string[];
+} | {
+    type: "graph_failed";
+    error: Readonly<ExecutionError>;
+    terminalNodeIds: readonly string[];
+})>;
+export interface BraidOptions {
+    runner: ModelRunner;
+    defaultModel?: string;
+    /** Source checkout. Git workspace management is automatic; outside Git, nodes are read-only. */
+    cwd?: string;
+    /** Positive integer. Defaults to 4. */
+    maxConcurrency?: number;
+    /** Applied separately to each invocation, starting when it runs. Default: 60s. Infinity disables it. */
+    nodeTimeoutMs?: number;
+    /** Includes queueing and execution of the entire graph. Default: 5 minutes. Infinity disables it. */
+    graphTimeoutMs?: number;
+    /** Caller cancellation, independent of node and graph deadlines. */
+    signal?: AbortSignal;
+    /** Live observer. Throws/rejections are ignored; returned work is not awaited. */
+    onEvent?: (event: ExecutionEvent) => void;
+}
+export interface ExecutionError {
+    code: "MODEL_ERROR" | "INVALID_RESPONSE" | "DECISION_REQUIRED" | "INVALID_DECISION" | "NODE_TIMEOUT" | "GRAPH_TIMEOUT" | "CANCELLED" | "MERGE_FAILED" | "CLEANUP_FAILED";
+    message: string;
+}
+/** Output is absent if no valid response was received; status determines success. */
+export interface NodeResult extends Partial<NodeOutput> {
+    id: string;
+    status: NodeStatus;
+    usage?: TokenUsage;
+    startedAt?: number;
+    finishedAt?: number;
+    latencyMs?: number;
+    error?: ExecutionError;
+    skipReason?: "inactive" | "upstream_failed" | "graph_timeout" | "cancelled";
+    workspace?: NodeWorkspace;
+}
+export interface BraidResult {
+    status: "completed" | "failed";
+    /** Completed nodes with no active outgoing edges in this execution. */
+    terminalOutputs: Record<string, NodeOutput>;
+    /** Immutable execution log, including graph construction and runtime handoffs. */
+    events: readonly ExecutionEvent[];
+    nodes: Record<string, NodeResult>;
+    workspaces?: Record<string, NodeWorkspace>;
+    error?: ExecutionError;
+    metadata: ExecutionContext & {
+        startedAt: number;
+        finishedAt: number;
+        latencyMs: number;
+        /** Sum of reported usage only, including responses that fail decision validation. */
+        usage: TokenUsage;
+        usageReportedNodes: number;
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,16 @@
+import type { BraidInput, BraidNode, Edge } from "./types.js";
+export declare class GraphValidationError extends Error {
+    constructor(message: string);
+}
+/** Internal, validated snapshot; arrays/maps are never handed to the runner. */
+export interface Graph {
+    goal: string;
+    nodes: BraidNode[];
+    topologicalOrder: BraidNode[];
+    edges: Edge[];
+    incoming: Map<string, Edge[]>;
+    outgoing: Map<string, Edge[]>;
+}
+/** Throws before execution for malformed graphs, references, choices, or cycles. */
+export declare function validateGraph(input: BraidInput): void;
+export declare function compileGraph(input: BraidInput): Graph;

package/dist/validate.js

@@ -0,0 +1,110 @@
+export class GraphValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GraphValidationError";
+    }
+}
+function requireValid(condition, message) {
+    if (!condition)
+        throw new GraphValidationError(message);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function fields(value, allowed, label) {
+    for (const key of Object.keys(value)) {
+        requireValid(allowed.includes(key), `${label}: unsupported field '${key}'`);
+    }
+}
+/** Throws before execution for malformed graphs, references, choices, or cycles. */
+export function validateGraph(input) {
+    compileGraph(input);
+}
+export function compileGraph(input) {
+    requireValid(isRecord(input), "Graph must be an object");
+    fields(input, ["goal", "nodes", "edges"], "Graph");
+    requireValid(text(input.goal), "Graph goal must be a non-empty string");
+    requireValid(Array.isArray(input.nodes) && input.nodes.length > 0, "Graph needs at least one node");
+    requireValid(Array.isArray(input.edges), "Graph edges must be an array");
+    const byId = new Map();
+    for (const node of input.nodes) {
+        requireValid(isRecord(node), "Node must be an object");
+        requireValid(node.type === "execute" || node.type === "decision" || node.type === "merge", "Unknown node type");
+        fields(node, node.type === "decision"
+            ? ["type", "id", "prompt", "model", "choices"]
+            : ["type", "id", "prompt", "model"], "Node");
+        requireValid(text(node.id), "Node id must be a non-empty string");
+        requireValid(!byId.has(node.id), `Duplicate node id '${node.id}'`);
+        requireValid(text(node.prompt) || (node.type === "merge" && node.prompt === undefined), `Node '${node.id}' needs a non-empty prompt`);
+        requireValid(node.model === undefined || text(node.model), `Invalid model on '${node.id}'`);
+        const common = {
+            id: node.id,
+            prompt: node.prompt ?? "Review all predecessor changes, decide how to integrate them into the source repository, and account for every source with finish_merge.",
+            ...(node.model !== undefined ? { model: node.model } : {}),
+        };
+        if (node.type === "decision") {
+            requireValid(Array.isArray(node.choices) && node.choices.length > 0, `Decision '${node.id}' needs at least one choice`);
+            const choices = [...node.choices];
+            requireValid(choices.every(text), `Invalid choice on '${node.id}'`);
+            requireValid(new Set(choices).size === choices.length, `Duplicate choices on '${node.id}'`);
+            byId.set(node.id, { type: "decision", ...common, choices });
+        }
+        else {
+            byId.set(node.id, { type: node.type, ...common });
+        }
+    }
+    const edges = [];
+    const incoming = new Map();
+    const outgoing = new Map();
+    const seen = new Set();
+    for (const id of byId.keys()) {
+        incoming.set(id, []);
+        outgoing.set(id, []);
+    }
+    for (const edge of input.edges) {
+        requireValid(isRecord(edge), "Edge must be an object");
+        fields(edge, ["from", "to", "choice"], "Edge");
+        requireValid(text(edge.from) && byId.has(edge.from), `Missing source node '${edge.from}'`);
+        requireValid(text(edge.to) && byId.has(edge.to), `Missing target node '${edge.to}'`);
+        if (edge.choice !== undefined) {
+            const source = byId.get(edge.from);
+            requireValid(source.type === "decision", `Choice edge from non-decision '${edge.from}'`);
+            requireValid(text(edge.choice) && source.choices.includes(edge.choice), `Undeclared edge choice '${edge.choice}' on '${edge.from}'`);
+        }
+        const key = JSON.stringify([edge.from, edge.to, edge.choice ?? null]);
+        requireValid(!seen.has(key), `Duplicate edge '${edge.from}' -> '${edge.to}'`);
+        seen.add(key);
+        const snapshot = {
+            from: edge.from,
+            to: edge.to,
+            ...(edge.choice !== undefined ? { choice: edge.choice } : {}),
+        };
+        edges.push(snapshot);
+        incoming.get(edge.to).push(snapshot);
+        outgoing.get(edge.from).push(snapshot);
+    }
+    // Kahn's algorithm is iterative, including for very deep graphs.
+    const nodes = [...byId.values()];
+    const remaining = new Map(nodes.map((node) => [node.id, incoming.get(node.id).length]));
+    const topologicalOrder = nodes.filter((node) => remaining.get(node.id) === 0);
+    for (let i = 0; i < topologicalOrder.length; i++) {
+        for (const edge of outgoing.get(topologicalOrder[i].id)) {
+            const count = remaining.get(edge.to) - 1;
+            remaining.set(edge.to, count);
+            if (count === 0)
+                topologicalOrder.push(byId.get(edge.to));
+        }
+    }
+    requireValid(topologicalOrder.length === nodes.length, "Graph contains a cycle");
+    return {
+        goal: input.goal,
+        nodes,
+        topologicalOrder,
+        edges,
+        incoming,
+        outgoing,
+    };
+}

package/dist/workspaces.d.ts

@@ -0,0 +1,29 @@
+import type { GitResult, MergeDisposition, MergeSource, ModelRequest, NodeWorkspace, SourceCheckoutStatus } from "./types.js";
+/** One source snapshot per graph; every invoked node gets its own detached worktree. */
+export declare class GitWorkspaces {
+    private readonly cwd;
+    private readonly onWorkspace?;
+    private snapshots;
+    private records;
+    private locations;
+    private allocated;
+    constructor(cwd: string, onWorkspace?: ((workspace: NodeWorkspace) => void) | undefined);
+    private report;
+    private snapshot;
+    prepare(request: ModelRequest): Promise<NodeWorkspace>;
+    all(): Record<string, NodeWorkspace>;
+    pending(): string[];
+    /** Checkpoint every file, including ignored node outputs, before releasing a worktree. */
+    private checkpoint;
+    private release;
+    /** Only archive/remove here. Choosing merge/cherry-pick/apply always belongs to the agent. */
+    archivePending(reason: string): Promise<void>;
+    close(): Promise<void>;
+    git(request: ModelRequest, args: string[], input?: string): Promise<GitResult>;
+    beginMerge(request: ModelRequest, sourceIds: string[]): Promise<{
+        sources: MergeSource[];
+        sourceStatus?: SourceCheckoutStatus;
+        finish: (dispositions: MergeDisposition[]) => Promise<void>;
+        complete: (success: boolean) => Promise<void>;
+    }>;
+}