@rynx-ai/cli 0.1.10

package/dist/agent-file.d.ts

@@ -0,0 +1,13 @@
+import { type LoadedAgentSpec } from "@rynx-ai/core";
+/** Absolute path to an agent's spec file. */
+export declare function agentSpecPath(id: string): string;
+/**
+ * Validate + atomically write a spec into the agent's config directory. The id
+ * is the directory name and is never persisted inside the file (any `id` in the
+ * input is dropped by the schema). Throws on a schema violation.
+ */
+export declare function writeAgentSpec(id: string, spec: Record<string, unknown>): LoadedAgentSpec;
+/** Remove an agent (its whole config directory). Returns false if it didn't exist. */
+export declare function removeAgentSpec(id: string): boolean;
+/** Write a minimal, valid starter spec for `rynx agent add`. */
+export declare function scaffoldAgentSpec(id: string): LoadedAgentSpec;

package/dist/agent-file.js

@@ -0,0 +1,61 @@
+/**
+ * `~/.rynx/agents/<id>/agent.json` — CLI/web-managed declarative agents. Each
+ * agent is a directory whose **name is the agent id**; the spec lives at
+ * `agent.json` inside it (alongside any instruction markdown the spec references).
+ *
+ * Reading + validation live in `@rynx-ai/core` (`loadAgentSpec` / `listAgentSpecs`);
+ * this module owns the write/remove side (atomic tmp+rename for the spec file).
+ */
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { agentSpecSchema, assertValidAgentId, rynxAgentDir, rynxAgentSpecFile, } from "@rynx-ai/core";
+/** Absolute path to an agent's spec file. */
+export function agentSpecPath(id) {
+    return rynxAgentSpecFile(id);
+}
+/**
+ * Validate + atomically write a spec into the agent's config directory. The id
+ * is the directory name and is never persisted inside the file (any `id` in the
+ * input is dropped by the schema). Throws on a schema violation.
+ */
+export function writeAgentSpec(id, spec) {
+    assertValidAgentId(id); // id is a directory name — reject path-escaping / unsafe ids
+    const parsed = agentSpecSchema.parse(spec); // unknown keys (incl. `id`) are stripped
+    mkdirSync(rynxAgentDir(id), { recursive: true });
+    const path = rynxAgentSpecFile(id);
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    renameSync(tmp, path);
+    return { ...parsed, id };
+}
+/** Remove an agent (its whole config directory). Returns false if it didn't exist. */
+export function removeAgentSpec(id) {
+    assertValidAgentId(id); // guard rmSync against `..`/path-escaping ids
+    const dir = rynxAgentDir(id);
+    if (!existsSync(dir)) {
+        return false;
+    }
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+}
+/** Write a minimal, valid starter spec for `rynx agent add`. */
+export function scaffoldAgentSpec(id) {
+    return writeAgentSpec(id, {
+        specVersion: 1,
+        name: id,
+        description: "A rynx agent.",
+        instructions: "You are a helpful agent.",
+        executor: {
+            runtime: "claude",
+            model: "claude-sonnet-4-6",
+            reasoningEffort: "medium",
+            // Runtime budget (edit/remove as needed): timeout is enforced on every
+            // runtime; retry maps to per-runtime env. maxIterations (claude only) and
+            // contextWindow (codex only) are also accepted.
+            timeout: 1800,
+            retry: { maxRetries: 2 },
+        },
+        osEnv: { sandbox: "danger-full-access", approvalPolicy: "never" },
+        tools: { allowed: [], disallowed: [], mcp: [] },
+        params: {},
+    });
+}

package/dist/browser-cli-args.d.ts

@@ -0,0 +1,28 @@
+import type { RuntimeBrowserBootstrapCredential } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+export type BrowserCliSubcommand = "install" | "update" | "version" | "clean" | "open" | "status" | "pages" | "endpoint" | "snapshot" | "navigate" | "click" | "type" | "screenshot" | "close";
+export interface BrowserCliArgs {
+    subcommand: BrowserCliSubcommand;
+    json: boolean;
+    ensure: boolean;
+    channel?: string;
+    version?: string;
+    runtime?: string;
+    session?: string;
+    url?: string;
+    ref?: string;
+    selector?: string;
+    text?: string;
+    output?: string;
+    format?: "png" | "jpeg" | "webp";
+    quality?: number;
+    x?: number;
+    y?: number;
+}
+export interface BrowserCliTarget {
+    runtimeSelector: string;
+    sessionId: string;
+    credential?: RuntimeBrowserBootstrapCredential;
+}
+export declare function parseBrowserCliArgs(args: readonly string[]): BrowserCliArgs;
+/** Resolve authority without ever turning a managed Session into an operator. */
+export declare function resolveBrowserCliTarget(args: BrowserCliArgs, managedCredential: RuntimeBrowserBootstrapCredential | undefined): BrowserCliTarget;

package/dist/browser-cli-args.js

@@ -0,0 +1,181 @@
+const SPECS = {
+    install: { values: ["--channel", "--version"], flags: ["--json"] },
+    update: { values: ["--channel"], flags: ["--json"] },
+    version: { values: [], flags: ["--json"] },
+    clean: { values: [], flags: ["--json"] },
+    open: {
+        values: ["--url", "--session", "--runtime"],
+        flags: ["--json"],
+        positionalUrl: true,
+    },
+    status: { values: ["--session", "--runtime"], flags: ["--json"] },
+    pages: { values: ["--session", "--runtime"], flags: ["--json"] },
+    endpoint: { values: ["--session"], flags: ["--ensure", "--json"] },
+    snapshot: { values: ["--session"], flags: ["--json"] },
+    navigate: {
+        values: ["--url", "--session"],
+        flags: ["--json"],
+        positionalUrl: true,
+    },
+    click: {
+        values: ["--ref", "--selector", "--x", "--y", "--session"],
+        flags: ["--json"],
+    },
+    type: {
+        values: ["--ref", "--selector", "--text", "--session"],
+        flags: ["--json"],
+    },
+    screenshot: {
+        values: ["--output", "--format", "--quality", "--session"],
+        flags: ["--json"],
+    },
+    close: { values: ["--session", "--runtime"], flags: ["--json"] },
+};
+export function parseBrowserCliArgs(args) {
+    const subcommand = args[0];
+    if (!isBrowserSubcommand(subcommand)) {
+        throw new Error("browser: expected install, update, version, clean, open, status, pages, endpoint, " +
+            "snapshot, navigate, click, type, screenshot, or close");
+    }
+    const spec = SPECS[subcommand];
+    const values = new Map();
+    const flags = new Set();
+    const positionals = [];
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg.startsWith("--")) {
+            if (spec.flags.includes(arg)) {
+                if (flags.has(arg))
+                    throw new Error(`browser ${subcommand}: duplicate option ${arg}`);
+                flags.add(arg);
+                continue;
+            }
+            if (spec.values.includes(arg)) {
+                if (values.has(arg))
+                    throw new Error(`browser ${subcommand}: duplicate option ${arg}`);
+                const value = args[index + 1];
+                if (!value || value.startsWith("--")) {
+                    throw new Error(`browser ${subcommand}: ${arg} requires a value`);
+                }
+                values.set(arg, value);
+                index += 1;
+                continue;
+            }
+            throw new Error(`browser ${subcommand}: unknown option ${arg}`);
+        }
+        positionals.push(arg);
+    }
+    if (!spec.positionalUrl && positionals.length > 0) {
+        throw new Error(`browser ${subcommand}: unexpected argument ${positionals[0]}`);
+    }
+    if (positionals.length > 1) {
+        throw new Error(`browser ${subcommand}: unexpected extra argument ${positionals[1]}`);
+    }
+    if (positionals.length === 1 && values.has("--url")) {
+        throw new Error("browser open: pass the URL once, either positionally or with --url");
+    }
+    const result = {
+        subcommand,
+        json: flags.has("--json"),
+        ensure: flags.has("--ensure"),
+        ...(values.has("--channel") ? { channel: values.get("--channel") } : {}),
+        ...(values.has("--version") ? { version: values.get("--version") } : {}),
+        ...(values.has("--runtime") ? { runtime: values.get("--runtime") } : {}),
+        ...(values.has("--session") ? { session: values.get("--session") } : {}),
+        ...(values.has("--url") || positionals[0]
+            ? { url: values.get("--url") ?? positionals[0] }
+            : {}),
+    };
+    if (values.has("--ref"))
+        result.ref = nonEmpty(values.get("--ref"), "--ref");
+    if (values.has("--selector"))
+        result.selector = nonEmpty(values.get("--selector"), "--selector");
+    if (values.has("--text"))
+        result.text = values.get("--text");
+    if (values.has("--output"))
+        result.output = nonEmpty(values.get("--output"), "--output");
+    if (values.has("--format")) {
+        const format = values.get("--format");
+        if (format !== "png" && format !== "jpeg" && format !== "webp") {
+            throw new Error(`browser screenshot: --format must be png, jpeg, or webp`);
+        }
+        result.format = format;
+    }
+    if (values.has("--quality")) {
+        result.quality = integer(values.get("--quality"), "--quality", 0, 100);
+    }
+    if (values.has("--x"))
+        result.x = finiteNumber(values.get("--x"), "--x");
+    if (values.has("--y"))
+        result.y = finiteNumber(values.get("--y"), "--y");
+    if (subcommand === "navigate" && !result.url) {
+        throw new Error("browser navigate: URL is required");
+    }
+    if (subcommand === "click") {
+        const targets = Number(result.ref !== undefined)
+            + Number(result.selector !== undefined)
+            + Number(result.x !== undefined || result.y !== undefined);
+        if (targets !== 1 || (result.x === undefined) !== (result.y === undefined)) {
+            throw new Error("browser click: pass exactly one of --ref, --selector, or both --x and --y");
+        }
+    }
+    if (subcommand === "type") {
+        if ((result.ref === undefined) === (result.selector === undefined)) {
+            throw new Error("browser type: pass exactly one of --ref or --selector");
+        }
+        if (result.text === undefined)
+            throw new Error("browser type: --text is required");
+    }
+    if (subcommand === "screenshot" && !result.output) {
+        throw new Error("browser screenshot: --output is required");
+    }
+    return result;
+}
+/** Resolve authority without ever turning a managed Session into an operator. */
+export function resolveBrowserCliTarget(args, managedCredential) {
+    const runtimeSelector = args.runtime ?? "local";
+    if (runtimeSelector !== "local") {
+        if (managedCredential) {
+            throw new Error("browser: a managed Session cannot select another Runtime");
+        }
+        if (!args.session) {
+            throw new Error("browser: --session is required when selecting a remote Runtime");
+        }
+        return { runtimeSelector, sessionId: args.session };
+    }
+    if (managedCredential) {
+        if (args.session && args.session !== managedCredential.sessionId) {
+            throw new Error("browser: a managed Session cannot control another Session with --session");
+        }
+        return {
+            runtimeSelector: "local",
+            sessionId: managedCredential.sessionId,
+            credential: managedCredential,
+        };
+    }
+    if (!args.session) {
+        throw new Error("browser: run inside a managed Rynx Session or pass --session for operator access");
+    }
+    return { runtimeSelector: "local", sessionId: args.session };
+}
+function isBrowserSubcommand(value) {
+    return value !== undefined && Object.hasOwn(SPECS, value);
+}
+function nonEmpty(value, option) {
+    if (value.length === 0)
+        throw new Error(`${option} must not be empty`);
+    return value;
+}
+function finiteNumber(value, option) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new Error(`${option} must be a finite number`);
+    return parsed;
+}
+function integer(value, option, minimum, maximum) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+        throw new Error(`${option} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return parsed;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { CliUsageError } from "./commands/errors.js";
+import { runCli } from "./run-cli.js";
+runCli(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = error instanceof CliUsageError ? error.exitCode : 1;
+});

package/dist/client.d.ts

@@ -0,0 +1,4 @@
+export { callManagedRuntimeBrowser, callResidentRuntime, cancelResidentPluginInstallation, commitResidentPluginInstallation, cleanResidentBrowserArtifacts, cleanupResidentSessions, createResidentRemoteRuntimePairingOffer, ensureResidentDaemon, forgetResidentRuntimeTarget, getResidentChromeInspectionStatus, getResidentDaemonIdentity, getResidentDaemonRuntimeStatus, getResidentBrowserArtifactVersion, getResidentRuntimeLocalBrowserEndpoint, invokeResidentPluginCommand, installResidentBrowserArtifact, listResidentPlugins, listResidentRemoteRuntimeClients, listResidentRuntimeTargets, pairResidentRuntimeTarget, prepareResidentPluginInstallation, readManagedRuntimeBrowserCredential, readOptionalManagedRuntimeBrowserCredential, reloadResidentPluginRuntime, revokeResidentRemoteRuntimeClient, setResidentPluginEnabled, shutdownResidentDaemonIfIdle, configureResidentChromeInspection, testResidentRuntimeTarget, uninstallResidentPlugin, updateResidentBrowserArtifact, connectResidentDesktopBrowserHost, ResidentRuntimeCallError, type InvokeResidentPluginCommandOptions, type ResidentDaemon, type ResidentDaemonIdentity, type ResidentDesktopBrowserHostCommandRequest, type ResidentDesktopBrowserHostConnectOptions, type ResidentDesktopBrowserHostConnection, type ResidentDesktopBrowserHostFailure, type ResidentPluginCommandResult, type ResidentPluginManagementItem, type ResidentPluginManagementState, type ResidentRemoteRuntimeClientGrant, type ResidentRuntimeCallErrorCode, type ResidentRuntimeCallOutcome, type ResidentRuntimeTargetTestResult, type ResidentRuntimeTargetView, } from "./control-client.js";
+export type { DaemonChromeInspectionConfigureInput, DaemonChromeInspectionStatus, } from "@rynx-ai/protocol/control";
+export type { PluginInstallCommitInput, PluginInstallCommitResult, PluginInstallPreparation, PluginInstallPrepareInput, } from "@rynx-ai/protocol/plugin-management";
+export { ensureDaemonControlEndpoint, resolveDaemonControlEndpoint, type DaemonControlEndpoint, type ResolveDaemonControlEndpointOptions, } from "./control-endpoint.js";

package/dist/client.js

@@ -0,0 +1,2 @@
+export { callManagedRuntimeBrowser, callResidentRuntime, cancelResidentPluginInstallation, commitResidentPluginInstallation, cleanResidentBrowserArtifacts, cleanupResidentSessions, createResidentRemoteRuntimePairingOffer, ensureResidentDaemon, forgetResidentRuntimeTarget, getResidentChromeInspectionStatus, getResidentDaemonIdentity, getResidentDaemonRuntimeStatus, getResidentBrowserArtifactVersion, getResidentRuntimeLocalBrowserEndpoint, invokeResidentPluginCommand, installResidentBrowserArtifact, listResidentPlugins, listResidentRemoteRuntimeClients, listResidentRuntimeTargets, pairResidentRuntimeTarget, prepareResidentPluginInstallation, readManagedRuntimeBrowserCredential, readOptionalManagedRuntimeBrowserCredential, reloadResidentPluginRuntime, revokeResidentRemoteRuntimeClient, setResidentPluginEnabled, shutdownResidentDaemonIfIdle, configureResidentChromeInspection, testResidentRuntimeTarget, uninstallResidentPlugin, updateResidentBrowserArtifact, connectResidentDesktopBrowserHost, ResidentRuntimeCallError, } from "./control-client.js";
+export { ensureDaemonControlEndpoint, resolveDaemonControlEndpoint, } from "./control-endpoint.js";

package/dist/commands/agent.d.ts

@@ -0,0 +1 @@
+export declare function runAgentCommand(args: readonly string[]): Promise<number>;

package/dist/commands/agent.js

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { listAgentSpecs, loadAgentSpec, rynxAgentsDir } from "@rynx-ai/core";
+import { agentSpecPath, removeAgentSpec, scaffoldAgentSpec } from "../agent-file.js";
+import { fail } from "./errors.js";
+export async function runAgentCommand(args) {
+    const [subcommand, id] = args;
+    switch (subcommand) {
+        case "list": {
+            const specs = await listAgentSpecs();
+            console.log(`Agents (dir: ${rynxAgentsDir()})`);
+            if (specs.length === 0) {
+                console.log("  (none)");
+                return 0;
+            }
+            for (const spec of specs) {
+                const runtime = spec.executor?.runtime ?? "(default)";
+                const model = spec.executor?.model ?? "(default)";
+                const display = spec.name && spec.name !== spec.id ? `  (${spec.name})` : "";
+                console.log(`  ${spec.id.padEnd(16)} ${runtime.padEnd(8)} ${model}${display}`);
+            }
+            return 0;
+        }
+        case "show": {
+            if (!id)
+                fail("agent show: missing agent id");
+            const spec = await loadAgentSpec(id);
+            if (!spec)
+                fail(`agent "${id}" not found at ${agentSpecPath(id)}`);
+            console.log(JSON.stringify(spec, null, 2));
+            return 0;
+        }
+        case "add": {
+            if (!id)
+                fail("agent add: missing agent id");
+            if (existsSync(agentSpecPath(id))) {
+                fail(`agent "${id}" already exists at ${agentSpecPath(id)}`);
+            }
+            scaffoldAgentSpec(id);
+            console.log(`Agent "${id}" created at ${agentSpecPath(id)}. ` +
+                `Edit it, then select it in a chat with \`/agent ${id}\`.`);
+            return 0;
+        }
+        case "rm":
+        case "remove": {
+            if (!id)
+                fail("agent rm: missing agent id");
+            if (!removeAgentSpec(id))
+                fail(`agent "${id}" not found`);
+            console.log(`Agent "${id}" removed.`);
+            return 0;
+        }
+        default:
+            fail("agent: expected list, show <id>, add <id>, or rm <id>");
+    }
+}

package/dist/commands/app-distribution.d.ts

@@ -0,0 +1,6 @@
+export declare function shouldUseAppDistributionCommand(command: string | undefined, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Prevent the App launcher from falling through to the compatibility daemon
+ * CLI and accidentally creating or inspecting a PM2-owned second lifecycle.
+ */
+export declare function runAppDistributionCommand(command: string, args: readonly string[]): Promise<number>;

package/dist/commands/app-distribution.js

@@ -0,0 +1,98 @@
+import { closeSync, fstatSync, openSync, readSync, } from "node:fs";
+import path from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+import { resolveDaemonControlEndpoint } from "../control-endpoint.js";
+import { fail } from "./errors.js";
+const APP_ONLY_COMMANDS = new Set([
+    "setup",
+    "update",
+    "start",
+    "restart",
+    "stop",
+    "status",
+    "logs",
+]);
+const LOG_TAIL_MAX_BYTES = 256 * 1024;
+export function shouldUseAppDistributionCommand(command, env = process.env) {
+    return command !== undefined
+        && APP_ONLY_COMMANDS.has(command)
+        && env.RYNX_DISTRIBUTION === "app";
+}
+/**
+ * Prevent the App launcher from falling through to the compatibility daemon
+ * CLI and accidentally creating or inspecting a PM2-owned second lifecycle.
+ */
+export async function runAppDistributionCommand(command, args) {
+    const json = args.includes("--json");
+    if (command === "status") {
+        const endpoint = await resolveDaemonControlEndpoint();
+        const status = endpoint
+            ? {
+                state: "running",
+                pid: endpoint.pid,
+                distribution: endpoint.distribution ?? "unknown",
+                lifecycle: endpoint.daemonLifecycle ?? "unknown",
+                version: endpoint.productVersion,
+                buildId: endpoint.buildId,
+                origin: endpoint.origin,
+            }
+            : { state: "stopped" };
+        console.log(json ? JSON.stringify(status, null, 2) : formatStatus(status));
+        return endpoint ? 0 : 1;
+    }
+    if (command === "logs") {
+        printRecentDaemonLogs();
+        return 0;
+    }
+    if (command === "setup") {
+        fail("Rynx App setup is completed in its onboarding and Desktop Settings.");
+    }
+    if (command === "update") {
+        fail("Rynx App updates are managed from Rynx > Check for Updates.");
+    }
+    if (command === "start") {
+        const endpoint = await resolveDaemonControlEndpoint();
+        if (endpoint?.distribution === "app") {
+            console.log(`Rynx Runtime is already running (PID ${endpoint.pid}).`);
+            return 0;
+        }
+        fail("Open Rynx App to start its bundled Runtime.");
+    }
+    fail(`rynx ${command} is managed by Rynx App. Use Desktop Settings > Daemon ` +
+        "so the App remains the only lifecycle owner.");
+}
+function formatStatus(status) {
+    if (status.state !== "running")
+        return "Rynx Runtime is stopped.";
+    return [
+        "Rynx Runtime is running",
+        status.version ? `version ${status.version}` : null,
+        status.lifecycle ? status.lifecycle : null,
+        status.pid ? `PID ${status.pid}` : null,
+    ].filter(Boolean).join(" · ");
+}
+function printRecentDaemonLogs() {
+    const root = path.join(rynxHome(), "logs");
+    for (const name of ["daemon.out.log", "daemon.err.log"]) {
+        const file = path.join(root, name);
+        console.log(`==> ${file} <==`);
+        let descriptor;
+        try {
+            descriptor = openSync(file, "r");
+            const size = fstatSync(descriptor).size;
+            const length = Math.min(size, LOG_TAIL_MAX_BYTES);
+            const buffer = Buffer.alloc(length);
+            readSync(descriptor, buffer, 0, length, Math.max(0, size - length));
+            const content = buffer.toString("utf8");
+            const lines = content.split(/\r?\n/);
+            console.log(lines.slice(Math.max(0, lines.length - 200)).join("\n"));
+        }
+        catch {
+            console.log("(no log output)");
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+        }
+    }
+}

package/dist/commands/browser.d.ts

@@ -0,0 +1 @@
+export declare function runBrowserCommand(args: readonly string[]): Promise<number>;