runling 0.1.1

package/dist/src/events.d.ts

@@ -0,0 +1,82 @@
+import type { TokenUsage } from "./usage.ts";
+export type RunlingEventPayload = {
+    type: "log";
+    level: "debug" | "info" | "success" | "error";
+    message: string;
+    depth: number;
+    color: string;
+    source?: "step" | "agent" | "command" | "input";
+    sourceId?: string;
+} | {
+    type: "step.started";
+    id: string;
+    label: string;
+} | {
+    type: "step.finished";
+    id: string;
+    status: "completed" | "failed";
+    durationMs: number;
+} | {
+    type: "command.started";
+    id: string;
+    command: string;
+} | {
+    type: "command.finished";
+    id: string;
+    status: "completed" | "failed";
+    durationMs: number;
+    output: {
+        stdout: string;
+        stderr: string;
+    };
+} | {
+    type: "input.requested";
+    id: string;
+    message: string;
+    defaultValue?: string;
+} | {
+    type: "input.finished";
+    id: string;
+    status: "answered";
+    value: string;
+    durationMs: number;
+} | {
+    type: "input.finished";
+    id: string;
+    status: "failed";
+    durationMs: number;
+} | {
+    type: "agent.started";
+    agentId: string;
+    model: string;
+    color: string;
+} | {
+    type: "agent.progress";
+    agentId: string;
+    text: string;
+} | {
+    type: "agent.action";
+    agentId: string;
+    action: string;
+} | {
+    type: "agent.usage";
+    agentId: string;
+    usage: TokenUsage;
+} | {
+    type: "agent.finished";
+    agentId: string;
+    outcome: "completed" | "blocked" | "failed";
+    usage: TokenUsage;
+} | {
+    type: "usage.updated";
+    usage: TokenUsage;
+};
+export type RunlingEvent = RunlingEventPayload & {
+    activityId?: string;
+    timestamp: number;
+};
+export type RunlingEventListener = (event: RunlingEvent) => void;
+export declare const emitRunlingEvent: (payload: RunlingEventPayload) => void;
+export declare const observeRunlingEvents: <T>(listener: RunlingEventListener, work: () => T) => T;
+export declare const withRunlingActivity: <T>(id: string, work: () => T) => T;
+export declare const bindRunlingContext: <Args extends unknown[], Result>(work: (...args: Args) => Result) => ((...args: Args) => Result);

package/dist/src/events.js

@@ -0,0 +1,21 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const listeners = new AsyncLocalStorage();
+const activity = new AsyncLocalStorage();
+export const emitRunlingEvent = (payload) => {
+    const event = {
+        ...payload,
+        activityId: activity.getStore(),
+        timestamp: performance.now(),
+    };
+    for (const listener of listeners.getStore() ?? [])
+        listener(event);
+};
+export const observeRunlingEvents = (listener, work) => listeners.run([...(listeners.getStore() ?? []), listener], work);
+export const withRunlingActivity = (id, work) => activity.run(id, work);
+export const bindRunlingContext = (work) => {
+    const capturedListeners = listeners.getStore() ?? [];
+    const capturedActivity = activity.getStore();
+    return (...args) => listeners.run(capturedListeners, () => capturedActivity === undefined
+        ? work(...args)
+        : activity.run(capturedActivity, () => work(...args)));
+};

package/dist/src/git.d.ts

@@ -0,0 +1,9 @@
+export declare function workingTreeHash(cwd?: string): Promise<string>;
+export declare class WorkingDirectory {
+    readonly path: string;
+    private readonly initialHash;
+    private constructor();
+    static create(path?: string): Promise<WorkingDirectory>;
+    get hasChanges(): Promise<boolean>;
+}
+export declare function getPwd(path?: string): Promise<WorkingDirectory>;

package/dist/src/git.js

@@ -0,0 +1,82 @@
+import { createReadStream } from "node:fs";
+import { lstat, readlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+async function git(cwd, args) {
+    const { stdout } = await exec("git", args, {
+        cwd,
+        encoding: "buffer",
+        maxBuffer: 128 * 1024 * 1024,
+    });
+    return stdout;
+}
+async function hasHead(cwd) {
+    try {
+        await git(cwd, ["rev-parse", "--verify", "HEAD"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function updateField(hasher, value) {
+    const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value;
+    hasher.update(`${bytes.byteLength}:`);
+    hasher.update(bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes);
+}
+async function updateUntrackedFile(hasher, cwd, path) {
+    const absolutePath = resolve(cwd, path);
+    const stat = await lstat(absolutePath);
+    updateField(hasher, path);
+    updateField(hasher, String(stat.mode));
+    if (stat.isSymbolicLink()) {
+        updateField(hasher, await readlink(absolutePath));
+        return;
+    }
+    if (!stat.isFile()) {
+        return;
+    }
+    updateField(hasher, String(stat.size));
+    for await (const chunk of createReadStream(absolutePath)) {
+        hasher.update(chunk);
+    }
+}
+export async function workingTreeHash(cwd = process.cwd()) {
+    const hasher = createHash("sha256");
+    if (await hasHead(cwd)) {
+        updateField(hasher, await git(cwd, ["diff", "--binary", "HEAD"]));
+    }
+    else {
+        updateField(hasher, await git(cwd, ["diff", "--binary", "--cached"]));
+        updateField(hasher, await git(cwd, ["diff", "--binary"]));
+    }
+    const untrackedFiles = new TextDecoder()
+        .decode(await git(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]))
+        .split("\0")
+        .filter(Boolean)
+        .sort();
+    for (const path of untrackedFiles) {
+        await updateUntrackedFile(hasher, cwd, path);
+    }
+    return hasher.digest("hex");
+}
+export class WorkingDirectory {
+    path;
+    initialHash;
+    constructor(path, initialHash) {
+        this.path = path;
+        this.initialHash = initialHash;
+    }
+    static async create(path = process.cwd()) {
+        return new WorkingDirectory(path, await workingTreeHash(path));
+    }
+    get hasChanges() {
+        return workingTreeHash(this.path).then((currentHash) => currentHash !== this.initialHash);
+    }
+}
+export function getPwd(path = process.cwd()) {
+    return WorkingDirectory.create(path);
+}

package/dist/src/id.d.ts

@@ -0,0 +1 @@
+export declare function randomId(): string;

package/dist/src/id.js

@@ -0,0 +1,7 @@
+import { randomInt } from "node:crypto";
+import { adjectives, nouns } from "human-id";
+export function randomId() {
+    const adjective = adjectives[randomInt(adjectives.length)];
+    const noun = nouns[randomInt(nouns.length)];
+    return `${adjective}-${noun}-${randomInt(1_000, 10_000)}`;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,15 @@
+export { agent, type AgentExtension, type AgentExtensionAPI, AgentOutcomeError, type AgentOptions, type AgentReport, type AgentResult, type AgentResourceOptions, type AgentRunOptions, type CompletedAgentReport, defineAgentExtension, type RunlingAgent, runAgent, type RunAgentOptions, } from "./agent.ts";
+export { getPwd, WorkingDirectory, workingTreeHash } from "./git.ts";
+export type { RunlingEvent, RunlingEventListener, RunlingEventPayload, } from "./events.ts";
+export { randomId } from "./id.ts";
+export { createInput, InputUnavailableError, type Input, type InputHandler, type InputOptions, type InputRequest, } from "./input.ts";
+export { log, type LogLevel } from "./log.ts";
+export { step, type StepWork } from "./step.ts";
+export { createShell, createExec, CommandError, type Exec, type CreateExecOptions, type CreateShellOptions, ShellError, type Shell, } from "./shell.ts";
+export { concat, type ConcatPart } from "./utils.ts";
+export { isWorkflow, workflow, type Workflow, type WorkflowDefinition, } from "./workflow.ts";
+export { Type, type Static, type TSchema } from "typebox";
+export { isWorkflowSchema } from "./schema.ts";
+export { createRunling, type Runling, type CreateRunlingOptions, type JsonValue, type WorkflowResult, type WorkflowReturn, } from "./runtime.ts";
+export { runWorkflow, type RunWorkflowOptions, type WorkflowExecution, } from "./runner.ts";
+export { accumulateTokenUsage, emptyTokenUsage, formatTokenUsage, getRecordedTokenUsage, isTokenUsage, recordTokenUsage, resetTokenUsage, totalTokens, type TokenUsage, } from "./usage.ts";

package/dist/src/index.js

@@ -0,0 +1,14 @@
+export { agent, AgentOutcomeError, defineAgentExtension, runAgent, } from "./agent.js";
+export { getPwd, WorkingDirectory, workingTreeHash } from "./git.js";
+export { randomId } from "./id.js";
+export { createInput, InputUnavailableError, } from "./input.js";
+export { log } from "./log.js";
+export { step } from "./step.js";
+export { createShell, createExec, CommandError, ShellError, } from "./shell.js";
+export { concat } from "./utils.js";
+export { isWorkflow, workflow, } from "./workflow.js";
+export { Type } from "typebox";
+export { isWorkflowSchema } from "./schema.js";
+export { createRunling, } from "./runtime.js";
+export { runWorkflow, } from "./runner.js";
+export { accumulateTokenUsage, emptyTokenUsage, formatTokenUsage, getRecordedTokenUsage, isTokenUsage, recordTokenUsage, resetTokenUsage, totalTokens, } from "./usage.js";

package/dist/src/input.d.ts

@@ -0,0 +1,14 @@
+export interface InputOptions {
+    defaultValue?: string;
+    signal?: AbortSignal;
+}
+export interface InputRequest extends InputOptions {
+    id: string;
+    message: string;
+}
+export type InputHandler = (request: InputRequest) => Promise<string>;
+export type Input = (message: string, options?: InputOptions) => Promise<string>;
+export declare class InputUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare const createInput: (handleInput?: InputHandler) => Input;

package/dist/src/input.js

@@ -0,0 +1,49 @@
+import { bindRunlingContext, emitRunlingEvent } from "./events.js";
+import { log, logInput } from "./log.js";
+export class InputUnavailableError extends Error {
+    constructor(message) {
+        super(`Workflow requested input, but this host cannot provide it: ${message}`);
+        this.name = "InputUnavailableError";
+    }
+}
+export const createInput = (handleInput) => async (message, options = {}) => {
+    const id = crypto.randomUUID();
+    const startedAt = performance.now();
+    const request = { id, message, ...options };
+    const emit = bindRunlingContext(emitRunlingEvent);
+    emit({
+        type: "input.requested",
+        id,
+        message,
+        defaultValue: options.defaultValue,
+    });
+    logInput(id, "info", `${log.highlight("Asking", "#f59f00")} ${message}`);
+    try {
+        options.signal?.throwIfAborted();
+        if (handleInput === undefined)
+            throw new InputUnavailableError(message);
+        const value = await handleInput(request);
+        if (typeof value !== "string") {
+            throw new TypeError("An input handler must return a string");
+        }
+        emit({
+            type: "input.finished",
+            id,
+            status: "answered",
+            value,
+            durationMs: performance.now() - startedAt,
+        });
+        logInput(id, "success", `${log.highlight("Answered")} ${value}`);
+        return value;
+    }
+    catch (error) {
+        emit({
+            type: "input.finished",
+            id,
+            status: "failed",
+            durationMs: performance.now() - startedAt,
+        });
+        logInput(id, "error", `${log.highlight("Input failed", "crimson")} ${message}`);
+        throw error;
+    }
+};

package/dist/src/log.d.ts

@@ -0,0 +1,35 @@
+declare function highlight(text: string, color?: string): string;
+export type LogLevel = "info" | "debug";
+type LogDestination = "stdout" | "stderr" | "silent";
+interface LogSource {
+    type: "agent" | "command" | "input";
+    id: string;
+}
+export declare const logStep: (message: string) => void;
+export declare const logCommand: (id: string, message: string) => void;
+export declare const logInput: (id: string, level: "info" | "success" | "error", message: string) => void;
+export declare const withLogSource: <T>(source: LogSource, work: LoggedWork<T>) => T;
+/** A chunk of work whose log output is indented one level deeper. */
+export type LoggedWork<T> = () => T;
+export declare const log: {
+    level: LogLevel;
+    debug: (message: string) => void;
+    info: (message: string) => void;
+    success: (message: string) => void;
+    error: (message: string) => void;
+    /** Renders `text` in the active contextual color, if there is one. */
+    colorize(text: string): string;
+    /** Renders `text` in a bold, bright color. */
+    highlight: typeof highlight;
+    /** Runs `work` with log markers rendered in `color`. */
+    withColor<T>(color: string, work: LoggedWork<T>): T;
+    /** Runs `work` with informational output written to `destination`. */
+    withDestination<T>(destination: LogDestination, work: LoggedWork<T>): T;
+    /**
+     * Runs `work` with all of its log output indented one level deeper than the
+     * surrounding log output. The indentation level is restored once `work`
+     * finishes, even if it throws.
+     */
+    indented<T>(work: LoggedWork<T>): T;
+};
+export {};

package/dist/src/log.js

@@ -0,0 +1,92 @@
+import { ansiColor } from "./ansi.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { emitRunlingEvent } from "./events.js";
+function paint(color, text) {
+    const ansi = ansiColor(color);
+    return ansi ? `${ansi}${text}\x1b[0m` : text;
+}
+function highlight(text, color = "white") {
+    const ansi = ansiColor(color) ?? "";
+    return `\x1b[1m${ansi}${text}\x1b[0m`;
+}
+const INDENT_UNIT = "  ";
+/**
+ * Tracks how deeply nested the currently running work is. Using
+ * `AsyncLocalStorage` keeps concurrent steps (e.g. two agents running at the
+ * same time) from corrupting each other's indentation level.
+ */
+const depthStorage = new AsyncLocalStorage();
+const colorStorage = new AsyncLocalStorage();
+const destinationStorage = new AsyncLocalStorage();
+const sourceStorage = new AsyncLocalStorage();
+function indent() {
+    return INDENT_UNIT.repeat(depthStorage.getStore() ?? 0);
+}
+function write(level, message, defaultColor, source) {
+    const color = colorStorage.getStore() ?? defaultColor;
+    const contextualSource = sourceStorage.getStore();
+    emitRunlingEvent({
+        type: "log",
+        level,
+        message,
+        depth: depthStorage.getStore() ?? 0,
+        color,
+        source: source ?? contextualSource?.type,
+        sourceId: contextualSource?.id,
+    });
+    const destination = destinationStorage.getStore();
+    if (destination === "silent")
+        return;
+    const symbol = level === "success"
+        ? "✓"
+        : level === "error"
+            ? "✗"
+            : level === "debug"
+                ? "·"
+                : "●";
+    const line = `${indent()}${paint(color, symbol)} ${message}`;
+    if (level === "error" || destination === "stderr") {
+        console.error(line);
+    }
+    else {
+        console.log(line);
+    }
+}
+export const logStep = (message) => write("info", message, "dodgerblue", "step");
+export const logCommand = (id, message) => withLogSource({ type: "command", id }, () => log.info(message));
+export const logInput = (id, level, message) => withLogSource({ type: "input", id }, () => log[level](message));
+export const withLogSource = (source, work) => sourceStorage.run(source, work);
+export const log = {
+    level: "info",
+    debug: (message) => {
+        if (log.level === "debug") {
+            write("debug", message, "gray");
+        }
+    },
+    info: (message) => write("info", message, "dodgerblue"),
+    success: (message) => write("success", message, "limegreen"),
+    error: (message) => write("error", message, "crimson"),
+    /** Renders `text` in the active contextual color, if there is one. */
+    colorize(text) {
+        const color = colorStorage.getStore();
+        return color === undefined ? text : paint(color, text);
+    },
+    /** Renders `text` in a bold, bright color. */
+    highlight,
+    /** Runs `work` with log markers rendered in `color`. */
+    withColor(color, work) {
+        return colorStorage.run(color, work);
+    },
+    /** Runs `work` with informational output written to `destination`. */
+    withDestination(destination, work) {
+        return destinationStorage.run(destination, work);
+    },
+    /**
+     * Runs `work` with all of its log output indented one level deeper than the
+     * surrounding log output. The indentation level is restored once `work`
+     * finishes, even if it throws.
+     */
+    indented(work) {
+        return depthStorage.run((depthStorage.getStore() ?? 0) + 1, work);
+    },
+};

package/dist/src/markdown.d.ts

@@ -0,0 +1,2 @@
+/** Renders Markdown as width-aware ANSI terminal text. */
+export declare const renderMarkdown: (markdown: string, width: number) => string;

package/dist/src/markdown.js

@@ -0,0 +1,32 @@
+import { ansiColor } from "./ansi.js";
+import { Markdown } from "@earendil-works/pi-tui";
+const foreground = (color) => (text) => {
+    const open = ansiColor(color);
+    return open ? `${open}${text}\x1b[39m` : text;
+};
+const style = (open, close) => (text) => `\x1b[${open}m${text}\x1b[${close}m`;
+const bold = style(1, 22);
+const dim = style(2, 22);
+const theme = {
+    heading: (text) => bold(foreground("white")(text)),
+    link: foreground("cyan"),
+    linkUrl: dim,
+    code: foreground("magenta"),
+    codeBlock: foreground("white"),
+    codeBlockBorder: dim,
+    quote: dim,
+    quoteBorder: foreground("gray"),
+    hr: foreground("gray"),
+    listBullet: foreground("cyan"),
+    bold,
+    italic: style(3, 23),
+    strikethrough: style(9, 29),
+    underline: style(4, 24),
+};
+/** Renders Markdown as width-aware ANSI terminal text. */
+export const renderMarkdown = (markdown, width) => new Markdown(markdown, 0, 0, theme)
+    .render(Number.isFinite(width) && width > 0
+    ? Math.max(1, Math.floor(width))
+    : 80)
+    .map((line) => line.trimEnd())
+    .join("\n");

package/dist/src/model.d.ts

@@ -0,0 +1,5 @@
+export interface ModelReference {
+    provider: string;
+    id: string;
+}
+export declare function parseModelReference(reference: string): ModelReference;

package/dist/src/model.js

@@ -0,0 +1,10 @@
+export function parseModelReference(reference) {
+    const separator = reference.indexOf("/");
+    if (separator <= 0 || separator === reference.length - 1) {
+        throw new Error(`Invalid model reference "${reference}"; expected "provider/model-id"`);
+    }
+    return {
+        provider: reference.slice(0, separator),
+        id: reference.slice(separator + 1),
+    };
+}

package/dist/src/paths.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Format a path for display: strip the working directory prefix so paths
+ * echoed in logs look like local (project-relative) paths.
+ */
+export declare function displayPath(path: string, cwd?: string): string;
+/**
+ * Best-effort removal of absolute working-directory prefixes from a free-form
+ * string (e.g. an echoed shell command) so embedded paths read as relative.
+ */
+export declare function displayText(text: string, cwd?: string): string;

package/dist/src/paths.js

@@ -0,0 +1,18 @@
+/**
+ * Format a path for display: strip the working directory prefix so paths
+ * echoed in logs look like local (project-relative) paths.
+ */
+export function displayPath(path, cwd = process.cwd()) {
+    if (path === cwd)
+        return ".";
+    if (path.startsWith(`${cwd}/`))
+        return path.slice(cwd.length + 1);
+    return path;
+}
+/**
+ * Best-effort removal of absolute working-directory prefixes from a free-form
+ * string (e.g. an echoed shell command) so embedded paths read as relative.
+ */
+export function displayText(text, cwd = process.cwd()) {
+    return text.replaceAll(`${cwd}/`, "");
+}

package/dist/src/runner.d.ts

@@ -0,0 +1,43 @@
+import { type RunlingEventListener } from "./events.ts";
+import type { InputHandler } from "./input.ts";
+import { type Runling, type WorkflowResult, type WorkflowReturn } from "./runtime.ts";
+import type { Static, TSchema } from "typebox";
+import { type Workflow } from "./workflow.ts";
+import { getRecordedTokenUsage } from "./usage.ts";
+export declare function formatDuration(ms: number): string;
+export interface WorkflowExecution<Output = unknown> {
+    durationMs: number;
+    usage: ReturnType<typeof getRecordedTokenUsage>;
+    output: Output | null;
+    result: WorkflowResult | null;
+    error: string | null;
+    ok: boolean;
+}
+export interface TerminalCapabilities {
+    isTTY?: boolean;
+    columns?: number;
+}
+export interface ExecutionOptions {
+    json?: boolean;
+    presentation?: "log" | "tui";
+    terminal?: TerminalCapabilities;
+    title?: string;
+}
+export interface RunWorkflowOptions<Input = unknown> {
+    cwd?: string;
+    input: Input;
+    verbose?: boolean;
+    onInput?: InputHandler;
+    onEvent?: RunlingEventListener;
+}
+export declare function formatWorkflowDetails(details: string, terminal?: TerminalCapabilities): string;
+export declare function normalizeWorkflowResult(value: unknown): WorkflowResult | null;
+export declare function executeWorkflow(run: (f: Runling) => Promise<WorkflowReturn> | WorkflowReturn, f: Runling, options?: ExecutionOptions): Promise<WorkflowExecution>;
+/** Run a workflow without assuming a terminal, printing, or changing process state. */
+export declare function runWorkflow<InputSchema extends TSchema, OutputSchema extends TSchema>(run: Workflow<InputSchema, OutputSchema>, { cwd, input, verbose, onInput, onEvent, }: RunWorkflowOptions<Static<InputSchema>>): Promise<WorkflowExecution<Static<OutputSchema>>>;
+export declare function loadWorkflow(path: string): Promise<Workflow>;
+export declare function runRunling(argv?: readonly string[]): Promise<void>;
+export declare function shouldUseTui(argv: readonly string[], terminal?: {
+    stdinIsTTY?: boolean;
+    stdoutIsTTY?: boolean;
+}): boolean;