@ronana/mcp 0.3.2 → 0.4.0

package/README.md

@@ -39,6 +39,7 @@ ronana generate get <id> | wait <id> [--out dir]
 ronana generate list
 ronana upscale <id | file | url> --resolution 4k --out ./renders
 ronana folder list | add <folder> <id…>
+ronana listen [--with claude|codex|gemini|ollama|command] [--model m]
 ```
 
 Every field from `model get` is a flag (`--aspect_ratio 16:9`, `--seed 7`).
@@ -53,6 +54,14 @@ the full list.
 the same command run twice makes two generations. Pass `--idempotency-key` to
 make a retry bill once.
 
+`listen` lets the Ronana studio send work to an AI on your computer. While it
+runs, the studio's assistant and agent list it under their model menu, and
+Enhance, assistant messages and agent turns go to it instead of Ronana's own
+models, so they cost no credits. Renders still do, and agent cards wait for
+your Confirm. `--with` picks the AI (Claude Code by default); `--with command
+--command "…"` runs any program that reads the prompt on stdin and prints its
+answer.
+
 ## Use Ronana from an AI app
 
 Most AI apps connect to Ronana's remote MCP server directly. Add this URL as a
@@ -112,6 +121,7 @@ library.
 | --- | --- |
 | `list_models` | List the available models. |
 | `get_model` | Get one model's contract: its input schema. |
+| `get_prompt_guide` | Get the guide for writing a prompt for one model. |
 | `estimate_cost` | Estimate the credit cost of a generation. Takes the same `model` and `input` as `generate`. |
 | `generate` | Start an image or video generation. |
 | `get_generation` | Get one generation and its download link. Pass `wait_seconds` (up to 45) to wait for the result in one call. |
@@ -124,6 +134,11 @@ library.
 | `list_folders` | List the folders in the library. |
 | `add_to_folder` | File library items into a folder. |
 | `get_account` | Get the plan and credit balance. |
+| `wait_for_requests` | Wait for Enhance, assistant and agent work from the studio. While an app calls it, the studio lists it as listening. |
+| `get_request` | Read one request the studio sent, by its id. |
+| `request_progress` | Tell the studio you are still working on a request you took, so a slow answer is not treated as abandoned. |
+| `agent_tool` | Look up models, prompt guides and prices for an agent request. |
+| `reply` | Answer a request: a prompt for the composer, a message, or cards for the board. |
 
 A generate call takes a `model` and an `input`, exactly as `get_model` shows it
 in `input_schema`. A media field takes a public https URL or a Ronana id

package/dist/cli.js

@@ -14,6 +14,7 @@
 //   ronana generate list [--limit n]
 //   ronana upscale <id | file | https-url> [--resolution r] [--model m] [--wait] [--out dir]
 //   ronana folder list | add <folder> <id…>
+//   ronana listen [--with claude|codex|gemini|ollama|command] [--model m] [--command "…"]
 import { randomUUID } from "node:crypto";
 import { createWriteStream, existsSync, statSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
@@ -22,6 +23,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { login, logout, readCredentials } from "./oauth.js";
 import { callTool, remoteClient, ToolError, uploadFile } from "./remote.js";
+import { listen, runnerFor } from "./listen.js";
 import { buildInput, flag, has, isRemoteValue, parseArgs, replaceLocalMedia, typeOf } from "./input.js";
 const HELP = `Usage: ronana <command>
 
@@ -40,6 +42,9 @@ const HELP = `Usage: ronana <command>
   upscale <id|file|url>         Upscale a video (costs credits; --resolution, --model)
   folder list                   Your library folders
   folder add <folder> <id…>     File items into a folder (made if missing)
+  listen                        Let the studio send Enhance and agent work to an AI
+                                on this computer (--with claude|codex|gemini|ollama|command,
+                                --model m, --command "…", --app "name"). No credits.
 
 Generate flags:
   --<field> <value>             Any field from \`model get\`. Repeat for lists.
@@ -347,6 +352,14 @@ async function main() {
         case "upscale": return upscaleCommand(args);
         case "folder":
         case "folders": return folderCommand(command === "folders" ? "list" : sub, args);
+        case "listen": {
+            const runner = runnerFor(flag(args, "with") ?? "claude", { model: flag(args, "model"), command: flag(args, "command"), app: flag(args, "app") });
+            const remote = await remoteClient();
+            const stop = () => { void remote.close().catch(() => null).finally(() => process.exit(0)); };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+            return listen(remote, runner, (line) => process.stderr.write(`${line}\n`));
+        }
         default: throw new Error(`Unknown command "${command}". Run \`ronana --help\`.`);
     }
 }

package/dist/listen.d.ts

@@ -0,0 +1,56 @@
+import { type remoteClient } from "./remote.js";
+type Remote = Awaited<ReturnType<typeof remoteClient>>;
+export interface Runner {
+    app: string;
+    command: string;
+    args: string[];
+    shell: boolean;
+}
+/** The AIs `--with` knows. Each reads the prompt on stdin and prints its answer. */
+export declare function runnerFor(name: string, options: {
+    model?: string;
+    command?: string;
+    app?: string;
+}): Runner;
+/** Run the AI once. Resolves with what it printed. */
+export declare function runOnce(runner: Runner, prompt: string, timeoutMs: number): Promise<string>;
+interface EnhanceRequest {
+    id: string;
+    kind: "enhance";
+    model: {
+        id: string;
+        name: string;
+    };
+    draft: string;
+    brief?: string;
+    guide: string;
+    max_chars: number;
+}
+interface AgentRequest {
+    id: string;
+    kind: "agent";
+    messages: {
+        role: string;
+        content: string;
+    }[];
+    references: {
+        target: unknown;
+        kind: string;
+        label: string;
+        duration_s?: number;
+    }[];
+    context?: string;
+    approval_mode: string;
+    max_cards: number;
+    card_schema: unknown;
+}
+export type StudioRequest = EnhanceRequest | AgentRequest;
+/** The prompt between <prompt> tags, or the whole answer when it has none. */
+export declare function extractPrompt(text: string): string;
+/** The first JSON object in the answer, fenced or bare. */
+export declare function extractJson(text: string): Record<string, unknown> | null;
+export declare function enhancePrompt(request: EnhanceRequest, refusal?: string): string;
+export declare function agentPrompt(request: AgentRequest, catalog: string, refusal?: string): string;
+/** Listen until Ctrl+C. */
+export declare function listen(remote: Remote, runner: Runner, log: (line: string) => void): Promise<never>;
+export {};

package/dist/listen.js

@@ -0,0 +1,186 @@
+// `ronana listen`: keep an AI on this computer listening for work from the
+// Ronana studio. While it runs, the studio lists it under its model menus and
+// sends it Enhance and agent requests instead of using Ronana's own models, so
+// the thinking runs on the user's own AI and costs no Ronana credits.
+//
+// The loop holds `wait_for_requests` open, runs the chosen AI once per request
+// with the prompt on stdin, and sends its answer with `reply`. The server
+// checks every reply; a refused one is handed back to the AI once to fix.
+import { spawn } from "node:child_process";
+import { callTool, ToolError } from "./remote.js";
+/** The AIs `--with` knows. Each reads the prompt on stdin and prints its answer. */
+export function runnerFor(name, options) {
+    const shell = process.platform === "win32";
+    const app = options.app?.trim();
+    switch (name) {
+        case "claude": return { app: app || "Claude Code", command: "claude", args: ["-p", "--output-format", "text", ...(options.model ? ["--model", options.model] : [])], shell };
+        case "codex": return { app: app || "Codex", command: "codex", args: ["exec", ...(options.model ? ["-m", options.model] : []), "-"], shell };
+        case "gemini": return { app: app || "Gemini CLI", command: "gemini", args: options.model ? ["-m", options.model] : [], shell };
+        case "ollama":
+            if (!options.model)
+                throw new Error("--with ollama needs --model <name>, e.g. --model llama3.1.");
+            return { app: app || `Ollama ${options.model}`, command: "ollama", args: ["run", options.model], shell };
+        case "command":
+            if (!options.command?.trim())
+                throw new Error("--with command needs --command \"<your command>\"; it gets the prompt on stdin.");
+            return { app: app || "Desktop AI", command: options.command, args: [], shell: true };
+        default: throw new Error(`Unknown --with "${name}". Use claude, codex, gemini, ollama or command.`);
+    }
+}
+/** Run the AI once. Resolves with what it printed. */
+export function runOnce(runner, prompt, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(runner.command, runner.args, { shell: runner.shell, stdio: ["pipe", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        const timer = setTimeout(() => { child.kill(); reject(new Error(`${runner.app} took longer than ${Math.round(timeoutMs / 1000)}s.`)); }, timeoutMs);
+        child.stdout.on("data", (chunk) => { out += chunk.toString("utf8"); });
+        child.stderr.on("data", (chunk) => { err += chunk.toString("utf8"); });
+        child.on("error", (error) => { clearTimeout(timer); reject(new Error(`Could not start ${runner.command}: ${error.message}`)); });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(`${runner.app} exited with code ${code}${err.trim() ? `: ${err.trim().split("\n").slice(-3).join(" ")}` : ""}`));
+        });
+        child.stdin.end(prompt);
+    });
+}
+/** The prompt between <prompt> tags, or the whole answer when it has none. */
+export function extractPrompt(text) {
+    const tagged = /<prompt>([\s\S]*?)(?:<\/prompt>|$)/i.exec(text);
+    return (tagged ? tagged[1] : text).trim();
+}
+/** The first JSON object in the answer, fenced or bare. */
+export function extractJson(text) {
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+    const candidates = [fenced?.[1], text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1)];
+    for (const raw of candidates) {
+        if (!raw?.trim())
+            continue;
+        try {
+            const value = JSON.parse(raw);
+            if (value && typeof value === "object" && !Array.isArray(value))
+                return value;
+        }
+        catch { /* try the next shape */ }
+    }
+    return null;
+}
+export function enhancePrompt(request, refusal) {
+    return [
+        `Rewrite this draft into the best prompt for ${request.model.name}, following the guide.`,
+        "Keep every reference token exactly as the draft writes it (@image1, @video1, @audio1).",
+        `Answer with the final prompt only, between <prompt> and </prompt>, at most ${request.max_chars} characters.`,
+        "", "GUIDE:", request.guide,
+        ...(request.brief ? ["", "BRIEF:", request.brief] : []),
+        "", "DRAFT:", request.draft,
+        ...(refusal ? ["", `Your last answer was refused: ${refusal}`, "Fix that and answer again."] : []),
+    ].join("\n");
+}
+export function agentPrompt(request, catalog, refusal) {
+    const transcript = request.messages.map((m) => `${m.role === "user" ? "USER" : "AGENT"}: ${m.content}`).join("\n\n");
+    return [
+        "You are the agent on the user's Ronana board. Answer their latest message.",
+        `You may propose up to ${request.max_cards} generation cards; each waits for the user's Confirm and spends nothing until then.`,
+        "Answer with ONE JSON object and nothing else: {\"message\": \"what the user reads\", \"cards\": [ ... ]}.",
+        "Each card follows CARD SCHEMA; modelId must come from MODELS.",
+        "", "MODELS:", catalog,
+        "", "CARD SCHEMA:", JSON.stringify(request.card_schema),
+        ...(request.references.length ? ["", "ATTACHED:", JSON.stringify(request.references)] : []),
+        ...(request.context ? ["", "CONTEXT:", request.context] : []),
+        "", "CONVERSATION:", transcript,
+        ...(refusal ? ["", `Your last answer was refused: ${refusal}`, "Fix that and answer again."] : []),
+    ].join("\n");
+}
+const ENHANCE_TIMEOUT_MS = 120_000;
+/** The least time between two empty waits. */
+const IDLE_FLOOR_MS = 5_000;
+// Inside the board's own wait for an answer.
+const AGENT_TIMEOUT_MS = 150_000;
+/** "Still working" every 15s while the AI writes. The studio treats a taken
+ *  request that goes quiet for 45s as abandoned, so this is what lets a slow
+ *  answer take its time. Best effort: a missed beat is not an error. */
+const PROGRESS_EVERY_MS = 15_000;
+async function answer(remote, runner, request, log) {
+    const beat = setInterval(() => { void callTool(remote, "request_progress", { id: request.id }).catch(() => { }); }, PROGRESS_EVERY_MS);
+    try {
+        await answerOnce(remote, runner, request, log);
+    }
+    finally {
+        clearInterval(beat);
+    }
+}
+async function answerOnce(remote, runner, request, log) {
+    let catalog = "";
+    if (request.kind === "agent") {
+        catalog = JSON.stringify(await callTool(remote, "agent_tool", { id: request.id, name: "list_models", input: {} }));
+    }
+    let refusal;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const prompt = request.kind === "enhance" ? enhancePrompt(request, refusal) : agentPrompt(request, catalog, refusal);
+        const output = await runOnce(runner, prompt, request.kind === "enhance" ? ENHANCE_TIMEOUT_MS : AGENT_TIMEOUT_MS);
+        let args;
+        if (request.kind === "enhance") {
+            args = { id: request.id, prompt: extractPrompt(output) };
+        }
+        else {
+            const json = extractJson(output);
+            if (!json) {
+                refusal = "it was not one JSON object.";
+                continue;
+            }
+            args = { id: request.id, message: typeof json.message === "string" ? json.message : "", cards: Array.isArray(json.cards) ? json.cards : [] };
+        }
+        try {
+            await callTool(remote, "reply", args);
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof ToolError) || error.error.code !== "INVALID_REPLY")
+                throw error;
+            refusal = error.message;
+            log(`  refused (${refusal}); asking ${runner.app} to fix it`);
+        }
+    }
+    throw new Error(`${runner.app} could not produce an answer the studio accepts${refusal ? `: ${refusal}` : "."}`);
+}
+/** Listen until Ctrl+C. */
+export async function listen(remote, runner, log) {
+    log(`Listening as ${runner.app}. Ronana's studio now sends Enhance and agent requests here (Ctrl+C to stop).`);
+    let backoff = 0;
+    for (;;) {
+        try {
+            const asked = Date.now();
+            const { request } = await callTool(remote, "wait_for_requests", { app: runner.app });
+            backoff = 0;
+            if (!request) {
+                // The server answers at once (not after holding) when its budget of
+                // held calls is spent: pause instead of asking again in a tight loop.
+                if (Date.now() - asked < IDLE_FLOOR_MS)
+                    await new Promise((resolve) => setTimeout(resolve, IDLE_FLOOR_MS));
+                continue;
+            }
+            const started = Date.now();
+            log(`● ${request.kind} ${request.id}${request.kind === "enhance" ? ` · ${request.model.name}` : ""}`);
+            try {
+                await answer(remote, runner, request, log);
+                log(`✓ sent · ${((Date.now() - started) / 1000).toFixed(1)}s`);
+            }
+            catch (error) {
+                log(`✗ ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        catch (error) {
+            // A refused sign-in or a missing plan will not fix itself: stop.
+            if (error instanceof ToolError && (error.error.code === "SCOPE_REQUIRED" || error.error.code === "UNAUTHORIZED"))
+                throw error;
+            if (error instanceof Error && /sign.?in|401|pricing/i.test(error.message))
+                throw error;
+            backoff = Math.min(30_000, backoff ? backoff * 2 : 2_000);
+            log(`Connection problem (${error instanceof Error ? error.message : String(error)}). Retrying in ${backoff / 1000}s.`);
+            await new Promise((resolve) => setTimeout(resolve, backoff));
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronana/mcp",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Ronana command line and local MCP bridge.",
   "license": "MIT",
   "homepage": "https://ronana.ai",