runline 0.29.0 → 0.30.0

package/dist/commands/exec.js

@@ -1,5 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
-import { loadConfig } from "../config/loader.js";
+import { join } from "node:path";
+import { findConfigDir, loadConfig } from "../config/loader.js";
+import { FileConnectionProvider } from "../connections/file.js";
 import { ExecutionEngine } from "../core/engine.js";
 import { loadAllPlugins } from "../plugin/loader.js";
 import { registry } from "../plugin/registry.js";
@@ -9,7 +11,10 @@ export async function exec(code, options) {
     await loadAllPlugins({
         builtinAllowlist: new Set(config.connections.map((c) => c.plugin)),
     });
-    const engine = new ExecutionEngine(registry, config);
+    const configDir = findConfigDir() ?? join(process.cwd(), ".runline");
+    const engine = new ExecutionEngine(registry, config, {
+        connectionProvider: new FileConnectionProvider(join(configDir, "config.json")),
+    });
     if (options.file) {
         if (!existsSync(code)) {
             printError(`File not found: ${code}`);

package/dist/commands/init.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import chalk from "chalk";
+import { updateConnectionFile } from "../config/store.js";
 import { DEFAULT_CONFIG } from "../config/types.js";
 import { printJson, printSuccess, printWarn } from "../utils/output.js";
 export async function init(options) {
@@ -16,7 +17,13 @@ export async function init(options) {
     }
     mkdirSync(dir, { recursive: true });
     mkdirSync(join(dir, "plugins"), { recursive: true });
-    writeFileSync(join(dir, "config.json"), `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`);
+    const path = join(dir, "config.json");
+    await updateConnectionFile(path, (data) => {
+        if (existsSync(path))
+            return { result: undefined, write: false };
+        Object.assign(data, structuredClone(DEFAULT_CONFIG));
+        return { result: undefined, write: true };
+    });
     if (options.json) {
         printJson({ ok: true, path: dir });
     }

package/dist/config/loader.d.ts

@@ -1,20 +1,14 @@
 import type { ConnectionConfig, ConnectionSchema } from "../plugin/types.js";
 import { type RunlineConfig } from "./types.js";
 export declare function findConfigDir(): string | null;
+export declare function loadConfigFrom(path: string): RunlineConfig;
 export declare function loadConfig(): RunlineConfig;
-export declare function saveConfig(config: RunlineConfig): void;
-export declare function addConnection(name: string, plugin: string, configValues: Record<string, unknown>): void;
-export declare function removeConnection(name: string): boolean;
-/**
- * Merge a partial config patch into an existing connection, atomically.
- *
- * Used by plugins that need to persist refreshed OAuth tokens (or any
- * other runtime-mutated credential) back to disk. The whole read-
- * modify-write is guarded by a file lock so two concurrent `runline
- * exec` processes refreshing the same token don't stomp each other.
- *
- * If the connection doesn't exist the call is a no-op.
- */
+/** Replace the entire config, fencing handles bound to its previous accounts. */
+export declare function saveConfig(config: RunlineConfig): Promise<void>;
+/** A new generation fences handles from an earlier login with the same name. */
+export declare function addConnection(name: string, plugin: string, configValues: Record<string, unknown>): Promise<void>;
+export declare function removeConnection(name: string): Promise<boolean>;
+/** Administrative patch. Plugin refreshes use their resolved connection handle. */
 export declare function updateConnectionConfig(name: string, patch: Record<string, unknown>): Promise<void>;
 export declare function getConnection(plugin: string, name?: string): ConnectionConfig | undefined;
 export declare function applyEnvOverrides(conn: ConnectionConfig, schema?: ConnectionSchema): ConnectionConfig;

package/dist/config/loader.js

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import lockfile from "proper-lockfile";
 import { connectionFields } from "../plugin/schema.js";
+import { readConnectionFile, updateConnectionFile } from "./store.js";
 import { DEFAULT_CONFIG } from "./types.js";
 const CONFIG_DIR_NAME = ".runline";
 const CONFIG_FILE = "config.json";
@@ -18,108 +19,77 @@ export function findConfigDir() {
     }
     return null;
 }
+function configPath() {
+    return join(findConfigDir() ?? join(process.cwd(), CONFIG_DIR_NAME), CONFIG_FILE);
+}
+export function loadConfigFrom(path) {
+    return { ...DEFAULT_CONFIG, ...readConnectionFile(path) };
+}
 export function loadConfig() {
-    const configDir = findConfigDir();
-    if (!configDir)
-        return { ...DEFAULT_CONFIG };
-    const configPath = join(configDir, CONFIG_FILE);
-    if (!existsSync(configPath))
-        return { ...DEFAULT_CONFIG };
-    try {
-        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
-        return {
-            ...DEFAULT_CONFIG,
-            ...raw,
-        };
-    }
-    catch {
-        return { ...DEFAULT_CONFIG };
-    }
+    return loadConfigFrom(configPath());
 }
-export function saveConfig(config) {
-    const configDir = findConfigDir() ?? join(process.cwd(), CONFIG_DIR_NAME);
-    mkdirSync(configDir, { recursive: true });
-    const configPath = join(configDir, CONFIG_FILE);
-    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+/** Replace the entire config, fencing handles bound to its previous accounts. */
+export async function saveConfig(config) {
+    const replacement = structuredClone(config);
+    await updateConnectionFile(configPath(), (data) => {
+        for (const key of Object.keys(data))
+            delete data[key];
+        Object.assign(data, replacement, {
+            connections: replacement.connections.map((entry) => ({
+                ...entry,
+                generation: randomUUID(),
+            })),
+        });
+        return { result: undefined, write: true };
+    });
 }
-export function addConnection(name, plugin, configValues) {
-    const config = loadConfig();
-    const existing = config.connections.findIndex((c) => c.name === name);
-    const conn = { name, plugin, config: configValues };
-    if (existing >= 0) {
-        config.connections[existing] = conn;
-    }
-    else {
-        config.connections.push(conn);
-    }
-    saveConfig(config);
+/** A new generation fences handles from an earlier login with the same name. */
+export async function addConnection(name, plugin, configValues) {
+    const conn = {
+        name,
+        plugin,
+        config: structuredClone(configValues),
+        generation: randomUUID(),
+    };
+    await updateConnectionFile(configPath(), (data) => {
+        const existing = data.connections.findIndex((c) => c.name === name);
+        if (existing >= 0)
+            data.connections[existing] = conn;
+        else
+            data.connections.push(conn);
+        return { result: undefined, write: true };
+    });
 }
-export function removeConnection(name) {
-    const config = loadConfig();
-    const idx = config.connections.findIndex((c) => c.name === name);
-    if (idx < 0)
-        return false;
-    config.connections.splice(idx, 1);
-    saveConfig(config);
-    return true;
+export async function removeConnection(name) {
+    return updateConnectionFile(configPath(), (data) => {
+        const idx = data.connections.findIndex((c) => c.name === name);
+        if (idx < 0)
+            return { result: false, write: false };
+        data.connections.splice(idx, 1);
+        return { result: true, write: true };
+    });
 }
-/**
- * Merge a partial config patch into an existing connection, atomically.
- *
- * Used by plugins that need to persist refreshed OAuth tokens (or any
- * other runtime-mutated credential) back to disk. The whole read-
- * modify-write is guarded by a file lock so two concurrent `runline
- * exec` processes refreshing the same token don't stomp each other.
- *
- * If the connection doesn't exist the call is a no-op.
- */
+/** Administrative patch. Plugin refreshes use their resolved connection handle. */
 export async function updateConnectionConfig(name, patch) {
-    const configDir = findConfigDir() ?? join(process.cwd(), CONFIG_DIR_NAME);
-    mkdirSync(configDir, { recursive: true });
-    const configPath = join(configDir, CONFIG_FILE);
-    if (!existsSync(configPath))
-        writeFileSync(configPath, "{}\n");
-    const release = await lockfile.lock(configPath, {
-        retries: { retries: 10, factor: 2, minTimeout: 50, maxTimeout: 2_000 },
-        stale: 30_000,
-        realpath: false,
+    const copy = structuredClone(patch);
+    await updateConnectionFile(configPath(), (data) => {
+        const current = data.connections.find((entry) => entry.name === name);
+        if (!current)
+            throw new Error(`Connection not found: ${name}`);
+        current.config = { ...current.config, ...copy };
+        return { result: undefined, write: true };
     });
-    try {
-        let raw;
-        try {
-            raw = {
-                ...DEFAULT_CONFIG,
-                ...JSON.parse(readFileSync(configPath, "utf-8")),
-            };
-        }
-        catch {
-            raw = { ...DEFAULT_CONFIG };
-        }
-        const idx = raw.connections.findIndex((c) => c.name === name);
-        if (idx < 0)
-            return;
-        raw.connections[idx] = {
-            ...raw.connections[idx],
-            config: { ...raw.connections[idx].config, ...patch },
-        };
-        writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`);
-    }
-    finally {
-        await release();
-    }
 }
 export function getConnection(plugin, name) {
     const config = loadConfig();
-    if (name)
-        return config.connections.find((c) => c.name === name);
-    return config.connections.find((c) => c.plugin === plugin);
+    return config.connections.find((c) => c.plugin === plugin && (name === undefined || c.name === name));
 }
 export function applyEnvOverrides(conn, schema) {
     if (!schema)
         return conn;
     const config = { ...conn.config };
     for (const [key, field] of Object.entries(connectionFields(schema))) {
-        if (field.env && !config[key]) {
+        if (field.env && config[key] == null) {
             const envVal = process.env[field.env];
             if (envVal)
                 config[key] = envVal;

package/dist/config/store.d.ts

@@ -0,0 +1,17 @@
+import type { ConnectionConfig } from "../plugin/types.js";
+export interface ConnectionFile {
+    connections: Array<ConnectionConfig & {
+        generation?: string;
+    }>;
+    [key: string]: unknown;
+}
+/** Missing files are empty; invalid files never become empty credential stores. */
+export declare function readConnectionFile(path: string): ConnectionFile;
+/** All local writes share ownership across reread, async work, and atomic commit. */
+export declare function updateConnectionFile<T>(path: string, update: (data: ConnectionFile) => Promise<{
+    result: T;
+    write: boolean;
+}> | {
+    result: T;
+    write: boolean;
+}): Promise<T>;

package/dist/config/store.js

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import lockfile from "proper-lockfile";
+/** Missing files are empty; invalid files never become empty credential stores. */
+export function readConnectionFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { connections: [] };
+        throw new Error("Invalid connection file: unreadable or malformed JSON");
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        // JSON parser diagnostics can include secret-bearing input.
+        throw new Error("Invalid connection file: unreadable or malformed JSON");
+    }
+    if (!data ||
+        typeof data !== "object" ||
+        Array.isArray(data) ||
+        (data.connections !== undefined && !Array.isArray(data.connections))) {
+        throw new Error("Invalid connection file: expected connections array");
+    }
+    data.connections ??= [];
+    const names = new Set();
+    for (const entry of data.connections) {
+        if (!entry ||
+            typeof entry.name !== "string" ||
+            typeof entry.plugin !== "string" ||
+            !entry.config ||
+            typeof entry.config !== "object" ||
+            Array.isArray(entry.config) ||
+            (entry.generation !== undefined &&
+                typeof entry.generation !== "string") ||
+            names.has(entry.name)) {
+            throw new Error("Invalid connection file: malformed or duplicate connection");
+        }
+        names.add(entry.name);
+    }
+    return data;
+}
+/** All local writes share ownership across reread, async work, and atomic commit. */
+export async function updateConnectionFile(path, update) {
+    mkdirSync(dirname(path), { recursive: true });
+    let compromised;
+    const release = await lockfile.lock(path, {
+        realpath: false,
+        stale: 30_000,
+        retries: { retries: 10, factor: 2, minTimeout: 50, maxTimeout: 2_000 },
+        onCompromised: (error) => {
+            compromised = error;
+        },
+    });
+    try {
+        if (compromised)
+            throw compromised;
+        const data = readConnectionFile(path);
+        const { result, write } = await update(data);
+        if (compromised)
+            throw compromised;
+        if (write) {
+            const temporary = `${path}.${randomUUID()}.tmp`;
+            try {
+                writeFileSync(temporary, `${JSON.stringify(data, null, 2)}\n`, {
+                    mode: 0o600,
+                    flag: "wx",
+                });
+                renameSync(temporary, path);
+            }
+            finally {
+                rmSync(temporary, { force: true });
+            }
+        }
+        return result;
+    }
+    finally {
+        await release();
+    }
+}

package/dist/connections/file.d.ts

@@ -0,0 +1,13 @@
+import { type ConnectionHandle, type ConnectionProvider, type ConnectionRequest } from "./types.js";
+/**
+ * Explicit CLI adapter for a config file. The absolute path is captured at
+ * construction; environment hints fill missing values only on this adapter.
+ * Runtime and config-management writes share a renewable file-wide lock.
+ * Manual file editors are not coordinated. This is plaintext local storage
+ * (writes use 0600), not an encrypted vault or a distributed credential broker.
+ */
+export declare class FileConnectionProvider implements ConnectionProvider {
+    readonly path: string;
+    constructor(path: string);
+    resolve(request: ConnectionRequest): Promise<ConnectionHandle>;
+}

package/dist/connections/file.js

@@ -0,0 +1,53 @@
+import { resolve } from "node:path";
+import { applyEnvOverrides } from "../config/loader.js";
+import { readConnectionFile, updateConnectionFile, } from "../config/store.js";
+import { connectionPatch, } from "./types.js";
+/**
+ * Explicit CLI adapter for a config file. The absolute path is captured at
+ * construction; environment hints fill missing values only on this adapter.
+ * Runtime and config-management writes share a renewable file-wide lock.
+ * Manual file editors are not coordinated. This is plaintext local storage
+ * (writes use 0600), not an encrypted vault or a distributed credential broker.
+ */
+export class FileConnectionProvider {
+    path;
+    constructor(path) {
+        this.path = resolve(path);
+    }
+    async resolve(request) {
+        const plugin = request.plugin;
+        const schema = structuredClone(request.schema);
+        const connection = readConnectionFile(this.path).connections.find((entry) => entry.plugin === plugin);
+        const name = connection?.name ?? plugin;
+        const generation = connection?.generation;
+        const hydrate = (entry) => applyEnvOverrides(structuredClone(entry), schema);
+        const find = (data) => data.connections.find((entry) => entry.name === name &&
+            entry.plugin === plugin &&
+            entry.generation === generation);
+        const missing = () => new Error(`Connection not found: ${name}`);
+        return {
+            read: async () => {
+                // A credential-free binding never attaches to an account created later.
+                if (!connection)
+                    return hydrate({ name, plugin, config: {} });
+                const current = find(readConnectionFile(this.path));
+                if (!current)
+                    throw missing();
+                return hydrate(current);
+            },
+            update: async (change) => {
+                if (!connection)
+                    throw missing();
+                return updateConnectionFile(this.path, async (data) => {
+                    const current = find(data);
+                    if (!current)
+                        throw missing();
+                    const patch = await connectionPatch(change, hydrate(current).config);
+                    if (patch !== undefined)
+                        current.config = { ...current.config, ...patch };
+                    return { result: hydrate(current), write: patch !== undefined };
+                });
+            },
+        };
+    }
+}

package/dist/connections/memory.d.ts

@@ -0,0 +1,15 @@
+import type { ConnectionConfig } from "../plugin/types.js";
+import { type ConnectionHandle, type ConnectionProvider, type ConnectionRequest } from "./types.js";
+/**
+ * Process-local storage. Share this instance across engines to share credentials
+ * and update ownership. It neither reads environment variables nor touches disk.
+ */
+export declare class MemoryConnectionProvider implements ConnectionProvider {
+    private readonly connections;
+    private readonly pending;
+    constructor(connections?: ConnectionConfig[]);
+    /** Add new identities, never overwrite a credential during an in-flight refresh. */
+    add(connections: ConnectionConfig[]): void;
+    list(): ConnectionConfig[];
+    resolve(request: ConnectionRequest): Promise<ConnectionHandle>;
+}

package/dist/connections/memory.js

@@ -0,0 +1,70 @@
+import { connectionPatch, } from "./types.js";
+/**
+ * Process-local storage. Share this instance across engines to share credentials
+ * and update ownership. It neither reads environment variables nor touches disk.
+ */
+export class MemoryConnectionProvider {
+    connections = new Map();
+    pending = new Map();
+    constructor(connections = []) {
+        this.add(connections);
+    }
+    /** Add new identities, never overwrite a credential during an in-flight refresh. */
+    add(connections) {
+        const names = new Set(this.connections.keys());
+        for (const connection of connections) {
+            if (names.has(connection.name))
+                throw new Error(`Duplicate connection: ${connection.name}`);
+            names.add(connection.name);
+        }
+        const copies = structuredClone(connections);
+        for (const connection of copies)
+            this.connections.set(connection.name, connection);
+    }
+    list() {
+        return structuredClone([...this.connections.values()]);
+    }
+    async resolve(request) {
+        let connection = [...this.connections.values()].find((value) => value.plugin === request.plugin);
+        if (!connection) {
+            // Credential-free plugins also have a mutable, process-local connection.
+            let name = request.plugin;
+            while (this.connections.has(name))
+                name = `_${name}`;
+            connection = { name, plugin: request.plugin, config: {} };
+            this.connections.set(name, connection);
+        }
+        const name = connection.name;
+        const read = () => {
+            const current = this.connections.get(name);
+            if (!current)
+                throw new Error(`Connection not found: ${name}`);
+            return structuredClone(current);
+        };
+        return {
+            read: async () => read(),
+            update: async (change) => {
+                const previous = this.pending.get(name) ?? Promise.resolve();
+                const work = previous
+                    .catch(() => { })
+                    .then(async () => {
+                    const current = read();
+                    const patch = await connectionPatch(change, current.config);
+                    if (patch !== undefined) {
+                        current.config = { ...current.config, ...patch };
+                        this.connections.set(name, current);
+                    }
+                    return structuredClone(current);
+                });
+                this.pending.set(name, work);
+                try {
+                    return await work;
+                }
+                finally {
+                    if (this.pending.get(name) === work)
+                        this.pending.delete(name);
+                }
+            },
+        };
+    }
+}

package/dist/connections/types.d.ts

@@ -0,0 +1,47 @@
+import type { ConnectionConfig, ConnectionSchema } from "../plugin/types.js";
+export type ConnectionPatch = Record<string, unknown>;
+/**
+ * Runs once under the adapter's update ownership, against freshly read state.
+ * Return a shallow config patch, or undefined to keep the current state.
+ * May perform a token refresh. Must not recursively update the same store.
+ * A thrown error aborts the write; adapters must not automatically replay it.
+ */
+export type ConnectionUpdater = (current: Readonly<Record<string, unknown>>) => ConnectionPatch | undefined | Promise<ConnectionPatch | undefined>;
+export type ConnectionUpdate = ConnectionPatch | ConnectionUpdater;
+export interface ConnectionRequest {
+    plugin: string;
+    action?: string;
+    schema?: ConnectionSchema;
+    /** Host-supplied per-execution authority, never action input. */
+    context?: unknown;
+}
+/**
+ * An adapter-owned binding to one resolved connection. Read and update must
+ * target that same identity even when other callers resolve different accounts.
+ * Returned snapshots must not alias authoritative storage.
+ */
+export interface ConnectionHandle {
+    read(): Promise<ConnectionConfig>;
+    /**
+     * Acquire ownership, re-read, run the updater, persist, then return the committed
+     * snapshot. Ownership spans the updater's async work, not just the final write.
+     * Coordinate across every writer sharing this storage; fail closed on failure
+     * to acquire ownership. Do not recreate a deleted connection. The host must
+     * fence lifecycle changes (disconnect/reconnect) against stale refreshes.
+     *
+     * This is not a distributed transaction with the remote provider: a provider
+     * may rotate a token before a write fails. Surface that failure; never silently
+     * report the replacement token as durably saved or replay the callback.
+     */
+    update(change: ConnectionUpdate): Promise<ConnectionConfig>;
+}
+/**
+ * Trusted-host integration seam. Resolve and authorize on each action invocation;
+ * rejection never falls back to environment variables or local files.
+ * These handles are for trusted plugin code, not a security boundary for arbitrary
+ * code. A broker for untrusted plugins must expose constrained requests instead.
+ */
+export interface ConnectionProvider {
+    resolve(request: ConnectionRequest): Promise<ConnectionHandle>;
+}
+export declare function connectionPatch(change: ConnectionUpdate, current: Record<string, unknown>): Promise<ConnectionPatch | undefined>;

package/dist/connections/types.js

@@ -0,0 +1,10 @@
+export async function connectionPatch(change, current) {
+    const patch = typeof change === "function"
+        ? await change(structuredClone(current))
+        : change;
+    if (patch !== undefined &&
+        (patch === null || typeof patch !== "object" || Array.isArray(patch))) {
+        throw new Error("Connection update must return an object patch or undefined");
+    }
+    return patch === undefined ? undefined : structuredClone(patch);
+}

package/dist/core/engine.d.ts

@@ -1,4 +1,5 @@
 import type { RunlineConfig } from "../config/types.js";
+import type { ConnectionProvider } from "../connections/types.js";
 import type { PluginRegistry } from "../plugin/registry.js";
 export interface ExecuteResult {
     result: unknown;
@@ -31,11 +32,13 @@ export interface ActionInvocation {
     error?: unknown;
 }
 export interface EngineHooks {
+    /** Host-owned resolution and persistence. Defaults to process-local memory. */
+    connectionProvider?: ConnectionProvider;
     /**
      * Observer for every action invocation. Must not throw — but if it
      * does, the engine swallows it: observability never breaks a run.
      */
-    onAction?: (info: ActionInvocation) => void;
+    onAction?: (info: ActionInvocation) => void | Promise<void>;
 }
 /**
  * Whether to arm the host-side RSS watchdog for a worker run.
@@ -84,6 +87,7 @@ export declare class ExecutionEngine {
     private registry;
     private config;
     private hooks;
+    private connectionProvider;
     private pooled;
     private readonly maxRunsPerWorker;
     constructor(registry: PluginRegistry, config: RunlineConfig, hooks?: EngineHooks);
@@ -116,7 +120,6 @@ export declare class ExecutionEngine {
      * teach the caller — agents read error messages and self-correct.
      */
     private selfPrefixHint;
-    private resolveConnection;
 }
 /**
  * Normalize a caller's code into a function body. Kept host-side so the