runling 0.1.1

package/dist/src/agent.js

@@ -0,0 +1,450 @@
+import { stripVTControlCharacters } from "node:util";
+import { createAgentSession, DefaultResourceLoader, defineTool, getAgentDir, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import webFetchExtension from "../extensions/web-fetch.js";
+import { bindRunlingContext, emitRunlingEvent } from "./events.js";
+import { randomId } from "./id.js";
+import { log, withLogSource } from "./log.js";
+import { parseModelReference } from "./model.js";
+import { displayPath, displayText } from "./paths.js";
+import { RUNLING_SYSTEM_PROMPT, formatAgentInstructions, } from "./system-prompt.js";
+import { containsMalformedToolCall, toSingleLine } from "./text.js";
+import { accumulateTokenUsage, emptyTokenUsage, formatTokenUsage, recordTokenUsage, } from "./usage.js";
+const reportSchema = Type.Object({
+    outcome: Type.Union([
+        Type.Literal("completed"),
+        Type.Literal("blocked"),
+        Type.Literal("failed"),
+    ]),
+    summary: Type.String({
+        description: "A concise, single-line summary of the outcome",
+        minLength: 1,
+        maxLength: 500,
+        pattern: "^[^\\r\\n]+$",
+    }),
+    details: Type.Optional(Type.String({
+        description: "Optional detailed Markdown supporting the summary",
+        minLength: 1,
+        maxLength: 20_000,
+    })),
+});
+const AGENT_COLORS = [
+    "#f59f00",
+    "#40c057",
+    "#15aabf",
+    "#4c6ef5",
+    "#ae3ec9",
+    "#e64980",
+    "#f76707",
+    "#12b886",
+];
+const MIN_AGENT_RETRIES = 5;
+const TOOL_ACTION_COLORS = {
+    read: "#40c057",
+    bash: "#ae3ec9",
+    edit: "#f76707",
+    write: "#15aabf",
+};
+let nextAgentColor = 0;
+function takeAgentColor() {
+    const color = AGENT_COLORS[nextAgentColor % AGENT_COLORS.length];
+    nextAgentColor++;
+    return color;
+}
+/** Preserve contextual typing when declaring a reusable agent extension. */
+export function defineAgentExtension(extension) {
+    return extension;
+}
+export class AgentOutcomeError extends Error {
+    report;
+    name = "AgentOutcomeError";
+    constructor(report) {
+        super(report.summary);
+        this.report = report;
+    }
+}
+export function describeTool(name, args) {
+    switch (name) {
+        case "read":
+            return `Reading ${displayPath(String(args.path))}`;
+        case "edit":
+            return `Editing ${displayPath(String(args.path))}`;
+        case "write":
+            return `Writing ${displayPath(String(args.path))}`;
+        case "bash":
+            return `Running ${displayText(String(args.command).replaceAll("\n", " "))}`;
+        default:
+            return `Using ${name}`;
+    }
+}
+function highlightToolAction(tool, description) {
+    const separator = description.indexOf(" ");
+    const color = TOOL_ACTION_COLORS[tool] ?? "white";
+    if (separator === -1)
+        return log.highlight(description, color);
+    return `${log.highlight(description.slice(0, separator), color)}${description.slice(separator)}`;
+}
+export async function runAgent(prompt, options) {
+    const { signal, ...createOptions } = options;
+    signal?.throwIfAborted();
+    const instance = await agent(createOptions);
+    try {
+        return await instance.runOutcome(prompt, { signal });
+    }
+    finally {
+        instance.dispose();
+    }
+}
+export async function agent(options) {
+    return createRunlingAgent(options);
+}
+async function createRunlingAgent(options, initialize) {
+    const agentId = randomId();
+    const color = takeAgentColor();
+    const progress = (text) => {
+        const line = stripVTControlCharacters(text).replace(/\s+/g, " ").trim();
+        if (line) {
+            emitRunlingEvent({ type: "agent.progress", agentId, text: line.slice(-500) });
+        }
+    };
+    const prefixLog = (message) => `${log.colorize(`[${agentId}]`)} ${message}`;
+    const writeAgentLog = (level, message, showProgress = true) => {
+        if (showProgress && level !== "debug")
+            progress(message);
+        if (level !== "debug" || log.level === "debug") {
+            emitRunlingEvent({
+                type: "agent.action",
+                agentId,
+                action: stripVTControlCharacters(message),
+            });
+        }
+        withLogSource({ type: "agent", id: agentId }, () => log.withColor(color, () => log[level](prefixLog(message))));
+    };
+    const agentLog = {
+        debug: (message) => writeAgentLog("debug", message),
+        error: (message) => writeAgentLog("error", message),
+        info: (message) => writeAgentLog("info", message),
+        success: (message) => writeAgentLog("success", message),
+    };
+    let activeReport;
+    const reportOutcome = defineTool({
+        name: "report_outcome",
+        label: "Report outcome",
+        description: "Report the final outcome of the task and terminate the run.",
+        promptSnippet: "Report the task outcome as structured data",
+        promptGuidelines: [
+            "Always call report_outcome as your final action.",
+            "Do not finish with a plain-text assistant response.",
+        ],
+        parameters: reportSchema,
+        async execute(_toolCallId, params) {
+            activeReport = params;
+            return {
+                content: [{ type: "text", text: "Outcome recorded." }],
+                details: params,
+                terminate: true,
+            };
+        },
+    });
+    const cwd = options.cwd ?? process.cwd();
+    const agentDir = options.resources?.agentDir ?? getAgentDir();
+    const modelRuntime = await ModelRuntime.create();
+    const modelReference = parseModelReference(options.model);
+    const model = modelRuntime.getModel(modelReference.provider, modelReference.id);
+    if (model === undefined) {
+        throw new Error(`Model ${options.model} is unavailable`);
+    }
+    const additionalInstructions = formatAgentInstructions(options.instructions ?? []);
+    const resources = options.resources;
+    const extensionsEnabled = resources?.extensions !== false;
+    const settingsManager = SettingsManager.create(cwd, agentDir);
+    const retrySettings = settingsManager.getRetrySettings();
+    settingsManager.applyOverrides({
+        retry: {
+            ...retrySettings,
+            maxRetries: Math.max(retrySettings.maxRetries, MIN_AGENT_RETRIES),
+        },
+    });
+    const resourceLoader = new DefaultResourceLoader({
+        cwd,
+        agentDir,
+        settingsManager,
+        extensionFactories: [
+            ...(extensionsEnabled
+                ? [{ name: "runling-web-fetch", factory: webFetchExtension }]
+                : []),
+            ...(options.extensions ?? []),
+        ],
+        noExtensions: !extensionsEnabled,
+        noSkills: resources?.skills === false,
+        noPromptTemplates: resources?.promptTemplates === false,
+        noThemes: resources?.themes === false,
+        noContextFiles: resources?.contextFiles === false,
+        appendSystemPromptOverride: (base) => [
+            ...base,
+            RUNLING_SYSTEM_PROMPT,
+            ...(additionalInstructions === undefined ? [] : [additionalInstructions]),
+        ],
+    });
+    await resourceLoader.reload();
+    const { session } = await createAgentSession({
+        cwd,
+        model,
+        thinkingLevel: options.thinkingLevel,
+        modelRuntime,
+        resourceLoader,
+        sessionManager: SessionManager.inMemory(),
+        settingsManager,
+        customTools: [reportOutcome],
+        tools: [
+            ...new Set([
+                ...(options.tools ?? [
+                    "read",
+                    "bash",
+                    "edit",
+                    "write",
+                    ...(extensionsEnabled ? ["web_fetch"] : []),
+                ]),
+                "report_outcome",
+            ]),
+        ],
+    });
+    initialize?.(session);
+    let disposed = false;
+    let running = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        if (running)
+            abortSession(session, agentLog);
+        session.dispose();
+    };
+    const runOutcome = async (prompt, { signal } = {}) => {
+        if (disposed) {
+            throw new Error(`Agent ${agentId} has been disposed`);
+        }
+        if (running) {
+            throw new Error(`Agent ${agentId} is already running`);
+        }
+        signal?.throwIfAborted();
+        running = true;
+        activeReport = undefined;
+        let finalText;
+        const usage = emptyTokenUsage();
+        let turn = 0;
+        let lastTextUpdate = -Infinity;
+        let preparingReport = false;
+        const toolStartedAt = new Map();
+        const unsubscribe = session.subscribe(bindRunlingContext((event) => {
+            options.onEvent?.(event);
+            if (event.type === "message_update") {
+                const update = event.assistantMessageEvent;
+                if (!preparingReport &&
+                    (update.type === "toolcall_start" ||
+                        update.type === "toolcall_delta" ||
+                        update.type === "toolcall_end")) {
+                    const part = update.partial.content[update.contentIndex];
+                    if (part?.type === "toolCall" && part.name === "report_outcome") {
+                        progress("Preparing result…");
+                        preparingReport = true;
+                    }
+                }
+                if (update.type === "text_start")
+                    lastTextUpdate = -Infinity;
+                if (update.type === "text_delta" || update.type === "text_end") {
+                    const now = performance.now();
+                    if (update.type === "text_end" || now - lastTextUpdate >= 100) {
+                        const part = update.partial.content[update.contentIndex];
+                        if (part?.type === "text")
+                            progress(part.text);
+                        lastTextUpdate = now;
+                    }
+                }
+            }
+            if (event.type === "agent_start") {
+                emitRunlingEvent({
+                    type: "agent.started",
+                    agentId,
+                    model: `${model.provider}/${model.id}`,
+                    color,
+                });
+                agentLog.info(`Agent started (model: ${model.provider}/${model.id})`);
+            }
+            if (event.type === "turn_start") {
+                turn++;
+                agentLog.debug(`Turn ${turn} started`);
+            }
+            if (event.type === "turn_end") {
+                agentLog.debug(`Turn ${turn} finished (${formatCount(event.toolResults.length, "tool result")})`);
+            }
+            if (event.type === "tool_execution_start" &&
+                event.toolName !== "report_outcome") {
+                toolStartedAt.set(event.toolCallId, performance.now());
+                const action = describeTool(event.toolName, event.args);
+                agentLog.info(highlightToolAction(event.toolName, action));
+            }
+            if (event.type === "tool_execution_end" &&
+                event.toolName !== "report_outcome") {
+                const startedAt = toolStartedAt.get(event.toolCallId);
+                toolStartedAt.delete(event.toolCallId);
+                const duration = startedAt === undefined
+                    ? ""
+                    : ` in ${formatDuration(performance.now() - startedAt)}`;
+                if (event.isError) {
+                    agentLog.error(`${event.toolName} failed${duration}`);
+                }
+                else {
+                    agentLog.debug(`${event.toolName} finished${duration}`);
+                }
+            }
+            if (event.type === "compaction_start") {
+                agentLog.info(`Compacting context (${event.reason})`);
+            }
+            if (event.type === "compaction_end") {
+                if (event.aborted) {
+                    agentLog.info("Context compaction aborted");
+                }
+                else if (event.result === undefined) {
+                    agentLog.error(`Context compaction failed: ${toSingleLine(event.errorMessage ?? "Unknown error")}`);
+                }
+                else {
+                    const estimatedAfter = event.result.estimatedTokensAfter;
+                    agentLog.success(estimatedAfter === undefined
+                        ? `Context compacted (${event.result.tokensBefore.toLocaleString()} tokens before compaction)`
+                        : `Context compacted from ${event.result.tokensBefore.toLocaleString()} to about ${estimatedAfter.toLocaleString()} tokens`);
+                }
+            }
+            if (event.type === "summarization_retry_scheduled") {
+                agentLog.info(`Retrying context summary in ${formatDelay(event.delayMs)} ` +
+                    `(attempt ${event.attempt}/${event.maxAttempts}): ${toSingleLine(event.errorMessage)}`);
+            }
+            if (event.type === "summarization_retry_attempt_start") {
+                agentLog.debug(`Retrying ${formatSummarySource(event.source)} summary`);
+            }
+            if (event.type === "summarization_retry_finished") {
+                agentLog.debug("Context summary retry finished");
+            }
+            if (event.type === "agent_end") {
+                agentLog.debug(`Agent finished (${formatCount(event.messages.length, "message")})`);
+            }
+            if (event.type === "auto_retry_start") {
+                agentLog.info(`Retrying agent in ${formatDelay(event.delayMs)} ` +
+                    `(attempt ${event.attempt}/${event.maxAttempts}): ${toSingleLine(event.errorMessage)}`);
+            }
+            if (event.type === "auto_retry_end") {
+                if (event.success) {
+                    agentLog.success(`Agent recovered after ${formatAttempts(event.attempt)}`);
+                }
+                else {
+                    agentLog.error(`Agent retry failed after ${formatAttempts(event.attempt)}: ${toSingleLine(event.finalError ?? "Unknown error")}`);
+                }
+            }
+            if (event.type === "message_end" &&
+                event.message.role === "assistant") {
+                finalText = event.message.content
+                    .filter((part) => part.type === "text")
+                    .map((part) => part.text)
+                    .join("\n");
+                if (finalText.trim())
+                    agentLog.info(finalText);
+                accumulateTokenUsage(usage, event.message.usage);
+                recordTokenUsage(event.message.usage);
+                emitRunlingEvent({ type: "agent.usage", agentId, usage: { ...usage } });
+                agentLog.debug(`Tokens: ${formatTokenUsage(usage)}`);
+            }
+        }));
+        const abort = () => abortSession(session, agentLog);
+        signal?.addEventListener("abort", abort, { once: true });
+        let result;
+        try {
+            result = await log.withColor(color, async () => {
+                signal?.throwIfAborted();
+                await session.prompt(prompt);
+                signal?.throwIfAborted();
+                if (activeReport === undefined) {
+                    agentLog.info(finalText !== undefined && containsMalformedToolCall(finalText)
+                        ? "Retrying malformed outcome report"
+                        : "Retrying missing outcome report");
+                    finalText = undefined;
+                    await session.prompt("Finish the original task by calling report_outcome with the truthful outcome. Use native tool calling; do not respond with plain text.");
+                    signal?.throwIfAborted();
+                }
+                if (activeReport !== undefined) {
+                    agentLog.info(activeReport.details?.trim() || activeReport.summary);
+                    return { ...activeReport, usage };
+                }
+                if (finalText !== undefined && finalText.trim() !== "") {
+                    agentLog.debug(`Discarding unreported final text: ${toSingleLine(finalText)}`);
+                }
+                return {
+                    outcome: "failed",
+                    summary: "Agent finished without a valid outcome report",
+                    usage,
+                };
+            });
+            return result;
+        }
+        finally {
+            signal?.removeEventListener("abort", abort);
+            unsubscribe();
+            running = false;
+            writeAgentLog("info", `Token usage: ${formatTokenUsage(usage)}`, false);
+            emitRunlingEvent({
+                type: "agent.finished",
+                agentId,
+                outcome: result?.outcome ?? "failed",
+                usage: { ...usage },
+            });
+        }
+    };
+    return {
+        id: agentId,
+        async run(prompt, runOptions) {
+            const report = await runOutcome(prompt, runOptions);
+            if (report.outcome !== "completed") {
+                throw new AgentOutcomeError(report);
+            }
+            return report;
+        },
+        runOutcome,
+        async fork() {
+            if (disposed) {
+                throw new Error(`Agent ${agentId} has been disposed`);
+            }
+            if (running) {
+                throw new Error(`Agent ${agentId} is already running`);
+            }
+            const messages = session.agent.state.messages;
+            return createRunlingAgent(options, (forkedSession) => {
+                forkedSession.agent.state.messages = messages;
+            });
+        },
+        dispose,
+        async [Symbol.asyncDispose]() {
+            dispose();
+        },
+    };
+}
+function abortSession(session, agentLog) {
+    void session.abort().catch((error) => {
+        agentLog.error(`Failed to abort agent: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
+function formatDelay(delayMs) {
+    return delayMs % 1000 === 0 ? `${delayMs / 1000}s` : `${delayMs}ms`;
+}
+function formatAttempts(attempts) {
+    return `${attempts} retry ${attempts === 1 ? "attempt" : "attempts"}`;
+}
+function formatCount(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function formatDuration(durationMs) {
+    return durationMs < 1000
+        ? `${Math.round(durationMs)}ms`
+        : `${(durationMs / 1000).toFixed(1)}s`;
+}
+function formatSummarySource(source) {
+    return source === "branchSummary" ? "branch" : "context";
+}

package/dist/src/ansi.d.ts

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

package/dist/src/ansi.js

@@ -0,0 +1,9 @@
+import colors from "color-name";
+export function ansiColor(color) {
+    const rgb = color.startsWith("#") && /^#[0-9a-f]{6}$/i.test(color)
+        ? [1, 3, 5].map((offset) => Number.parseInt(color.slice(offset, offset + 2), 16))
+        : Object.hasOwn(colors, color.toLowerCase())
+            ? colors[color.toLowerCase()]
+            : undefined;
+    return rgb ? `\x1b[38;2;${rgb.join(";")}m` : "";
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,8 @@
+export interface CliArguments {
+    workflowPath: string;
+    prompt: string;
+    json: boolean;
+    logMode: boolean;
+    verbose: boolean;
+}
+export declare function cli(argv?: readonly string[], command?: string): CliArguments;

package/dist/src/cli.js

@@ -0,0 +1,46 @@
+import { parseArgs } from "node:util";
+import { log } from "./log.js";
+import { displayPath } from "./paths.js";
+function parseCliArguments(argv) {
+    return parseArgs({
+        args: [...argv],
+        options: {
+            json: {
+                type: "boolean",
+                default: false,
+            },
+            log: {
+                type: "boolean",
+                default: false,
+            },
+            verbose: {
+                type: "boolean",
+                short: "v",
+                default: false,
+            },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+}
+export function cli(argv = process.argv.slice(2), command = displayPath((process.argv[1] ?? "runling"))) {
+    let parsed;
+    try {
+        parsed = parseCliArguments(argv);
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+    const [workflowPath, prompt = "", ...extraPositionals] = parsed.positionals;
+    if (workflowPath === undefined) {
+        throw new Error(`Usage: ${command} [-v|--verbose] [--log|--json] <workflow.ts> [prompt]`);
+    }
+    if (extraPositionals.length > 0) {
+        throw new Error("The prompt must be passed as a single quoted argument");
+    }
+    const json = parsed.values.json ?? false;
+    const logMode = parsed.values.log ?? false;
+    const verbose = parsed.values.verbose ?? false;
+    log.level = verbose ? "debug" : "info";
+    return { workflowPath, prompt, json, logMode, verbose };
+}

package/dist/src/config-reloader.d.ts

@@ -0,0 +1,20 @@
+import { type WebConfig } from "./web-config.ts";
+/** Reload project modules without replacing active runs or installed packages. */
+export declare class ConfigReloader {
+    readonly path: string;
+    private current?;
+    private pending?;
+    private timer?;
+    private disposed;
+    private listeners;
+    private watcher;
+    private ready;
+    error: string | undefined;
+    revision: number;
+    constructor(path: string);
+    load(): Promise<WebConfig>;
+    reload(): Promise<WebConfig>;
+    private read;
+    subscribe(listener: () => void): () => void;
+    close(): Promise<void>;
+}

package/dist/src/config-reloader.js

@@ -0,0 +1,110 @@
+import { dirname, relative, sep } from "node:path";
+import { watch } from "chokidar";
+import { createJiti } from "jiti";
+import * as runling from "./index.js";
+import * as web from "./web-config.js";
+import { isWebConfig } from "./web-config.js";
+/** Reload project modules without replacing active runs or installed packages. */
+export class ConfigReloader {
+    path;
+    current;
+    pending;
+    timer;
+    disposed = false;
+    listeners = new Set();
+    watcher;
+    ready;
+    error;
+    revision = 0;
+    constructor(path) {
+        this.path = path;
+        const root = dirname(path);
+        this.watcher = watch(root, {
+            ignoreInitial: true,
+            persistent: false,
+            ignored: (file, stats) => {
+                if (file === path)
+                    return false;
+                const parts = relative(root, file).split(sep);
+                if (parts.some((part) => part.startsWith(".") ||
+                    ["node_modules", "dist", "build", "coverage"].includes(part)))
+                    return true;
+                return stats?.isFile() ? !/\.(?:[cm]?[jt]sx?|json)$/.test(file) : false;
+            },
+        });
+        this.ready = new Promise((resolve, reject) => {
+            this.watcher.once("ready", resolve);
+            this.watcher.on("error", (error) => {
+                reject(error);
+                this.error = `Configuration watcher failed: ${error instanceof Error ? error.message : String(error)}`;
+                console.error(this.error);
+                for (const listener of this.listeners)
+                    listener();
+            });
+        });
+        this.watcher.on("all", () => {
+            clearTimeout(this.timer);
+            this.timer = setTimeout(() => {
+                void (this.pending ?? Promise.resolve())
+                    .catch(() => { })
+                    .then(() => (this.disposed ? undefined : this.reload()))
+                    .catch(() => { });
+            }, 100);
+            this.timer.unref();
+        });
+    }
+    load() {
+        return this.current
+            ? Promise.resolve(this.current)
+            : (this.pending ?? this.reload());
+    }
+    reload() {
+        if (this.pending)
+            return this.pending;
+        this.pending = this.read().finally(() => {
+            this.pending = undefined;
+        });
+        return this.pending;
+    }
+    async read() {
+        try {
+            await this.ready;
+            const jiti = createJiti(this.path, {
+                moduleCache: false,
+                tryNative: false,
+                interopDefault: false,
+                // Reuse the host runtime: live events must reach its AsyncLocalStorage.
+                virtualModules: { runling, "runling/web": web },
+            });
+            const module = await jiti.import(this.path);
+            if (!isWebConfig(module.default))
+                throw new Error(`${this.path} must export a valid Runling configuration`);
+            this.current = module.default;
+            this.error = undefined;
+            this.revision++;
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+            console.error(`Config reload failed: ${this.error}`);
+            if (!this.current)
+                throw error;
+        }
+        finally {
+            for (const listener of this.listeners)
+                listener();
+        }
+        return this.current;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    close() {
+        this.disposed = true;
+        clearTimeout(this.timer);
+        this.listeners.clear();
+        return this.watcher.close();
+    }
+}