runling 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hendrik Mans and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Runling
+
+Write TypeScript workflows for coding agents. Run them from the command line
+or use the included web console to trigger runs, inspect activity, and track
+token use and estimated cost.
+
+Requires Node.js 22.18 or later. The package includes the TypeScript loader
+and web UI; consumer projects do not need Bun, Vite, or SvelteKit.
+
+## Install
+
+After the first release is published:
+
+```sh
+npm install runling
+```
+
+Add `"runling": "runling"` to the `scripts` in your `package.json`.
+
+## Write a workflow
+
+Create `workflows/echo.ts`:
+
+```ts
+import { Type, workflow } from "runling";
+
+export default workflow(
+  { name: "Echo", input: Type.String(), output: Type.String() },
+  (r, input) => r.step("Echo input", () => input),
+);
+```
+
+Run it with `npm run runling -- workflows/echo.ts "hello"`.
+
+## Start the web console
+
+Create `runling.config.ts` in the project root:
+
+```ts
+import { defineWebConfig } from "runling/web";
+import echo from "./workflows/echo.ts";
+
+export default defineWebConfig({ webhooks: { echo: { workflow: echo } } });
+```
+
+Run `npm run runling`, then open `http://localhost:5173`.
+Use the console to start a run or send a request:
+
+```sh
+curl http://localhost:5173/api/webhooks/echo \
+  -H 'content-type: application/json' -d '"hello"'
+```
+
+Keep the console local: it does not provide authentication. Workflows can
+execute commands and modify files with the server's permissions. Configure
+model credentials before running workflows that use agents.
+
+See the [repository documentation](https://github.com/hmans/runling#readme)
+for agent sessions, configuration, and workflow examples.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/runling.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import "tsx/esm";
+import { existsSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { resolve } from "./workflow-loader.js";
+
+registerHooks({ resolve });
+
+try {
+  if (existsSync(".env")) process.loadEnvFile(".env");
+  const args = process.argv.slice(2);
+  if (
+    args.length === 0 ||
+    args[0] === "web" ||
+    ["--config", "--host", "--port", "--open", "--help", "-h"].includes(args[0].split("=")[0])
+  ) {
+    const { runRunlingWeb } = await import("../dist/src/web-server.js");
+    await runRunlingWeb(args[0] === "web" ? args.slice(1) : args);
+  } else {
+    const { runRunling } = await import("../dist/src/runner.js");
+    await runRunling(args);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/bin/workflow-loader.js

@@ -0,0 +1,10 @@
+// Workflow/config TypeScript uses ESM imports even in a CommonJS project.
+// Let tsx perform the transform; do not transform installed dependencies.
+export function resolve(specifier, context, nextResolve) {
+  const result = nextResolve(specifier, context);
+  const url = new URL(result.url);
+  if (url.protocol === "file:" && /\.(?:ts|tsx|mts)$/.test(url.pathname) && !url.pathname.includes("/node_modules/")) {
+    return { ...result, format: "module" };
+  }
+  return result;
+}

package/dist/extensions/web-fetch.d.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+interface WebFetchDependencies {
+    fetch(input: URL, init: RequestInit): Promise<Response>;
+    resolveAddresses(hostname: string): Promise<readonly string[]>;
+}
+export declare function createWebFetchExtension(dependencies?: WebFetchDependencies): (pi: ExtensionAPI) => void;
+declare const webFetchExtension: (pi: ExtensionAPI) => void;
+export default webFetchExtension;

package/dist/extensions/web-fetch.js

@@ -0,0 +1,245 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { Type } from "typebox";
+const MAX_RESPONSE_BYTES = 100_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_REDIRECTS = 5;
+const parameters = Type.Object({
+    url: Type.String({
+        description: "The absolute HTTP or HTTPS URL to fetch",
+        minLength: 1,
+    }),
+});
+const defaultDependencies = {
+    fetch: (input, init) => globalThis.fetch(input, init),
+    async resolveAddresses(hostname) {
+        if (isIP(hostname) !== 0)
+            return [hostname];
+        return (await lookup(hostname, { all: true, verbatim: true })).map(({ address }) => address);
+    },
+};
+export function createWebFetchExtension(dependencies = defaultDependencies) {
+    return function webFetchExtension(pi) {
+        pi.registerTool({
+            name: "web_fetch",
+            label: "Fetch URL",
+            description: "Fetch textual content from an HTTP or HTTPS URL. Returns the final URL, HTTP status, content type, and a size-limited response body.",
+            promptSnippet: "Fetch textual content from an HTTP or HTTPS URL",
+            parameters,
+            async execute(_toolCallId, { url }, signal) {
+                const parsedUrl = new URL(url);
+                if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+                    throw new Error("web_fetch only supports HTTP and HTTPS URLs");
+                }
+                if (parsedUrl.username !== "" || parsedUrl.password !== "") {
+                    throw new Error("web_fetch does not accept credentials in URLs");
+                }
+                const timeoutSignal = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+                const requestSignal = signal
+                    ? AbortSignal.any([signal, timeoutSignal])
+                    : timeoutSignal;
+                const response = await fetchPublicUrl(parsedUrl, requestSignal, dependencies);
+                const contentType = response.headers.get("content-type") ?? "unknown";
+                if (!isTextualContentType(contentType)) {
+                    await response.body?.cancel();
+                    throw new Error(`web_fetch cannot return content type ${contentType}`);
+                }
+                const { text, truncated } = await readLimitedText(response.body, MAX_RESPONSE_BYTES);
+                const metadata = [
+                    `URL: ${response.url}`,
+                    `Status: ${response.status} ${response.statusText}`,
+                    `Content-Type: ${contentType}`,
+                ];
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                ...metadata,
+                                "",
+                                text,
+                                ...(truncated
+                                    ? [`\n[Response truncated after ${MAX_RESPONSE_BYTES} bytes]`]
+                                    : []),
+                            ].join("\n"),
+                        },
+                    ],
+                    details: {
+                        url: response.url,
+                        status: response.status,
+                        contentType,
+                        truncated,
+                    },
+                };
+            },
+        });
+    };
+}
+const webFetchExtension = createWebFetchExtension();
+export default webFetchExtension;
+async function fetchPublicUrl(initialUrl, signal, dependencies) {
+    let url = initialUrl;
+    for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects++) {
+        await assertPublicDestination(url, dependencies.resolveAddresses);
+        const response = await dependencies.fetch(url, {
+            headers: {
+                accept: "text/plain, text/html, text/markdown, application/json, application/xml;q=0.9, text/xml;q=0.9",
+                "user-agent": "runling-web-fetch/1.0",
+            },
+            redirect: "manual",
+            signal,
+        });
+        if (!isRedirect(response.status))
+            return response;
+        const location = response.headers.get("location");
+        if (location === null)
+            return response;
+        await response.body?.cancel();
+        if (redirects === MAX_REDIRECTS) {
+            throw new Error(`web_fetch stopped after ${MAX_REDIRECTS} redirects`);
+        }
+        url = new URL(location, url);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            throw new Error("web_fetch redirects must use HTTP or HTTPS");
+        }
+        if (url.username !== "" || url.password !== "") {
+            throw new Error("web_fetch redirects cannot contain credentials");
+        }
+    }
+    throw new Error("web_fetch redirect limit exceeded");
+}
+function isRedirect(status) {
+    return [301, 302, 303, 307, 308].includes(status);
+}
+async function assertPublicDestination(url, resolveAddresses) {
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    const addresses = await resolveAddresses(hostname);
+    if (addresses.length === 0) {
+        throw new Error(`web_fetch could not resolve ${url.hostname}`);
+    }
+    const blockedAddress = addresses.find((address) => !isPublicIpAddress(address));
+    if (blockedAddress !== undefined) {
+        throw new Error(`web_fetch blocked non-public destination ${url.hostname} (${blockedAddress})`);
+    }
+}
+function isPublicIpAddress(address) {
+    if (isIP(address) === 4)
+        return isPublicIpv4(parseIpv4(address));
+    if (isIP(address) !== 6)
+        return false;
+    const bytes = parseIpv6(address);
+    if (bytes === undefined)
+        return false;
+    // Unspecified, loopback, IPv4-compatible, and IPv4-mapped addresses.
+    if (bytes.slice(0, 12).every((byte) => byte === 0)) {
+        return isPublicIpv4(bytes.slice(12));
+    }
+    if (bytes.slice(0, 10).every((byte) => byte === 0) &&
+        bytes[10] === 0xff &&
+        bytes[11] === 0xff) {
+        return isPublicIpv4(bytes.slice(12));
+    }
+    // Only globally routable unicast space is eligible.
+    if ((bytes[0] & 0xe0) !== 0x20)
+        return false;
+    if (bytes[0] === 0x20 &&
+        bytes[1] === 0x01 &&
+        ((bytes[2] === 0x0d && bytes[3] === 0xb8) || bytes[2] <= 0x01)) {
+        return false;
+    }
+    // 6to4 and NAT64 can otherwise tunnel requests to blocked IPv4 targets.
+    if (bytes[0] === 0x20 && bytes[1] === 0x02)
+        return false;
+    return true;
+}
+function isPublicIpv4(bytes) {
+    const [a = 0, b = 0, c = 0] = bytes;
+    return !(a === 0 ||
+        a === 10 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        a === 127 ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 0 && (c === 0 || c === 2)) ||
+        (a === 192 && b === 88 && c === 99) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        (a === 198 && b === 51 && c === 100) ||
+        (a === 203 && b === 0 && c === 113) ||
+        a >= 224);
+}
+function parseIpv4(address) {
+    return address.split(".").map(Number);
+}
+function parseIpv6(address) {
+    const sections = address.toLowerCase().split("::");
+    if (sections.length > 2)
+        return undefined;
+    const parseSection = (section) => {
+        if (section === "")
+            return [];
+        const groups = [];
+        for (const part of section.split(":")) {
+            if (part.includes(".")) {
+                const ipv4 = parseIpv4(part);
+                if (ipv4.length !== 4)
+                    return undefined;
+                groups.push((ipv4[0] << 8) | ipv4[1], (ipv4[2] << 8) | ipv4[3]);
+                continue;
+            }
+            const group = Number.parseInt(part, 16);
+            if (!Number.isInteger(group) || group < 0 || group > 0xffff) {
+                return undefined;
+            }
+            groups.push(group);
+        }
+        return groups;
+    };
+    const left = parseSection(sections[0]);
+    const right = parseSection(sections[1] ?? "");
+    if (left === undefined || right === undefined)
+        return undefined;
+    const missing = 8 - left.length - right.length;
+    if ((sections.length === 1 && missing !== 0) || missing < 0)
+        return undefined;
+    const groups = [...left, ...Array(missing).fill(0), ...right];
+    if (groups.length !== 8)
+        return undefined;
+    return groups.flatMap((group) => [group >> 8, group & 0xff]);
+}
+function isTextualContentType(contentType) {
+    const mediaType = contentType.split(";", 1)[0]?.trim().toLowerCase();
+    return (mediaType?.startsWith("text/") === true ||
+        mediaType?.endsWith("+json") === true ||
+        mediaType?.endsWith("+xml") === true ||
+        mediaType === "application/json" ||
+        mediaType === "application/xml" ||
+        mediaType === "application/javascript" ||
+        mediaType === "application/x-www-form-urlencoded");
+}
+async function readLimitedText(body, maxBytes) {
+    if (body === null)
+        return { text: "", truncated: false };
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let bytesRead = 0;
+    let text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                return { text: text + decoder.decode(), truncated: false };
+            const remaining = maxBytes - bytesRead;
+            if (value.byteLength > remaining) {
+                text += decoder.decode(value.subarray(0, remaining), { stream: true });
+                await reader.cancel();
+                return { text: text + decoder.decode(), truncated: true };
+            }
+            bytesRead += value.byteLength;
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/src/agent.d.ts

@@ -0,0 +1,78 @@
+import { type AgentSessionEvent, type ExtensionAPI, type InlineExtension } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { type TokenUsage } from "./usage.ts";
+declare const reportSchema: Type.TObject<{
+    outcome: Type.TUnion<[Type.TLiteral<"completed">, Type.TLiteral<"blocked">, Type.TLiteral<"failed">]>;
+    summary: Type.TString;
+    details: Type.TOptional<Type.TString>;
+}>;
+export type AgentReport = Static<typeof reportSchema>;
+/** A report enriched with the token usage of the agent interaction. */
+export type AgentResult = AgentReport & {
+    usage: TokenUsage;
+};
+export type CompletedAgentReport = AgentResult & {
+    outcome: "completed";
+};
+/** A named or anonymous pi extension instantiated for one agent session. */
+export type AgentExtension = InlineExtension;
+/** The API available while configuring an agent-local extension. */
+export type AgentExtensionAPI = ExtensionAPI;
+/** Preserve contextual typing when declaring a reusable agent extension. */
+export declare function defineAgentExtension(extension: AgentExtension): AgentExtension;
+export interface AgentResourceOptions {
+    /** Directory containing global pi configuration and resources. */
+    agentDir?: string;
+    extensions?: boolean;
+    skills?: boolean;
+    promptTemplates?: boolean;
+    themes?: boolean;
+    contextFiles?: boolean;
+}
+/**
+ * Reasoning effort for models that support extended thinking. "xhigh" and
+ * "max" are only supported by selected model families.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export interface RunAgentOptions {
+    model: string;
+    /** Reasoning effort for the model. Defaults to pi's own settings default. */
+    thinkingLevel?: ThinkingLevel;
+    instructions?: readonly string[];
+    cwd?: string;
+    /** Built-in and extension tools to expose. `report_outcome` is always added. */
+    tools?: readonly string[];
+    resources?: AgentResourceOptions;
+    /** Extensions instantiated only for this agent session. */
+    extensions?: readonly AgentExtension[];
+    /** Observe the raw pi event stream for this agent session. */
+    onEvent?: (event: AgentSessionEvent) => void;
+    /** Abort an active model turn. */
+    signal?: AbortSignal;
+}
+export type AgentOptions = Omit<RunAgentOptions, "signal">;
+export interface AgentRunOptions {
+    /** Abort this model turn without disposing the agent. */
+    signal?: AbortSignal;
+}
+export interface RunlingAgent extends AsyncDisposable {
+    /** Human-friendly ID used to prefix this agent's log lines. */
+    readonly id: string;
+    /** Run one turn and require it to complete successfully. */
+    run(prompt: string, options?: AgentRunOptions): Promise<CompletedAgentReport>;
+    /** Run one turn and return any reported outcome. */
+    runOutcome(prompt: string, options?: AgentRunOptions): Promise<AgentResult>;
+    /** Create an independent in-memory agent with a copy of this conversation. */
+    fork(): Promise<RunlingAgent>;
+    /** Release the underlying in-memory session. */
+    dispose(): void;
+}
+export declare class AgentOutcomeError extends Error {
+    readonly report: AgentResult;
+    readonly name = "AgentOutcomeError";
+    constructor(report: AgentResult);
+}
+export declare function describeTool(name: string, args: Record<string, unknown>): string;
+export declare function runAgent(prompt: string, options: RunAgentOptions): Promise<AgentResult>;
+export declare function agent(options: AgentOptions): Promise<RunlingAgent>;
+export {};