railcode 0.1.18 → 0.1.20

package/README.md

@@ -22,6 +22,8 @@ railcode login --setup-token <token>  Sign in with a one-time onboarding setup t
 railcode init <app> [--template react|static]
 railcode deploy                    Build (if configured) and deploy the app here
 railcode db <list|query> ...       List data connectors / run read-only SQL
+railcode agent <list|show|create|update|delete|run|schedule> ...
+                                   Manage org-scoped managed agents
 ```
 
 - **`login`** prompts for the server URL (default `https://api.railcode.app`),
@@ -60,6 +62,24 @@ railcode db <list|query> ...       List data connectors / run read-only SQL
   list when omitted, `--params '<json-array>'` binds `$1, $2, …` placeholders
   (SQL is never interpolated), `--file <path>` reads SQL from a file, and
   `--json` prints the raw `{ columns, rows, rowcount, truncated }` envelope.
+- **`agent`** manages org-scoped managed agents when your permissions allow it.
+  Manifests are JSON files in the same shape the API stores under
+  `agent.manifest`.
+  - `railcode agent list` lists agents; `--json` prints raw `AgentOut[]`.
+  - `railcode agent show <name|uuid>` prints one agent; `--manifest` prints only
+    its manifest JSON.
+  - `railcode agent pull <name|uuid> --output agent.json` writes the existing
+    manifest for editing.
+  - `railcode agent create --file agent.json` creates an agent; `update <agent>
+    --file agent.json` replaces an existing agent manifest; `delete <agent> --yes`
+    archives it.
+  - `railcode agent test --file agent.json --input '{"k":"v"}'` runs a draft
+    manifest without saving; `railcode agent run <agent> --input '{"k":"v"}'`
+    invokes a saved agent and prints the result. Use `--trace` for the step trace
+    and `--json` for the raw run detail.
+  - `railcode agent schedule set <agent> --cron "0 9 * * *" --timezone UTC`
+    creates or updates the agent's one schedule. `schedule show`, `pause`,
+    `resume`, `delete --yes`, and `run-now` operate on that single schedule.
 
 ## Configuration
 

package/dist/index.js

@@ -43,6 +43,8 @@ Usage:
   railcode connector <list|docs|fetch> ...  List connectors / show API docs / proxy a call
   railcode llm <providers|models>      List the LLM providers/models apps can call
   railcode manifest <validate|show> ...  Validate ${APP_MANIFEST_NAME} locally / show an app's ratified manifest
+  railcode agent <list|show|create|update|delete|run|schedule> ...
+                                      Manage org-scoped managed agents
   railcode --version
   railcode --help
 
@@ -97,6 +99,10 @@ async function main() {
         case "manifest":
             await commandManifest(args);
             return;
+        case "agent":
+        case "agents":
+            await commandAgent(args);
+            return;
         default:
             throw new CliError(`Unknown command: ${args.command}\n\n${HELP}`, 2);
     }
@@ -3534,6 +3540,550 @@ async function commandManifestShow(args) {
     }
 }
 // ---------------------------------------------------------------------------
+// agent — managed agents (`railcode agent ...`)
+// ---------------------------------------------------------------------------
+const AGENT_HELP = `railcode agent — managed agents
+
+Usage:
+  railcode agent list                         List managed agents in this org
+  railcode agent show <agent>                 Show one agent
+  railcode agent pull <agent> [--output <path>]
+                                             Write the agent manifest as JSON
+  railcode agent create --file <path>         Create an agent from a JSON manifest
+  railcode agent update <agent> --file <path> Update an agent from a JSON manifest
+  railcode agent delete <agent> [--yes]       Delete/archive an agent
+  railcode agent test --file <path> [opts]    Run a draft manifest without saving
+  railcode agent run <agent> [opts]           Trigger a saved agent and print results
+  railcode agent schedule <show|set|add|update|pause|resume|delete|run-now> <agent>
+
+Agent options:
+  --json                                Print the raw API response
+  --file <path>                         JSON manifest file
+  --output <path>                       Output path for pull (default stdout)
+  --input '<json>'                      Invoke/test input JSON (default null)
+  --input-file <path>                   Read invoke/test input JSON from a file
+  --trace                               Include the run step trace in human output
+  --yes                                 Confirm delete without a prompt
+
+Schedule options:
+  --name <name>                         Schedule name (default: default on create)
+  --cron <expr>                         Five-field cron expression
+  --schedule <expr>                     Alias for --cron
+  --timezone <iana>                     IANA timezone (default: UTC on create)
+  --enabled / --disabled                Initial or updated enabled state
+
+Manifests are JSON files in the same shape the API stores under agent.manifest.
+Schedules are currently one per agent, so "set" creates the schedule if missing
+or updates the existing one.
+`;
+async function commandAgent(args) {
+    const sub = args.rest[0] ?? "";
+    switch (sub) {
+        case "list":
+        case "ls":
+            await commandAgentList(args);
+            return;
+        case "show":
+        case "get":
+            await commandAgentShow(args);
+            return;
+        case "pull":
+        case "export":
+            await commandAgentPull(args);
+            return;
+        case "create":
+            await commandAgentCreate(args);
+            return;
+        case "update":
+        case "edit":
+            await commandAgentUpdate(args);
+            return;
+        case "delete":
+        case "rm":
+            await commandAgentDelete(args);
+            return;
+        case "test":
+            await commandAgentTest(args);
+            return;
+        case "run":
+        case "invoke":
+            await commandAgentRun(args);
+            return;
+        case "schedule":
+        case "schedules":
+            await commandAgentSchedule(args);
+            return;
+        case "":
+        case "help":
+            console.log(AGENT_HELP);
+            return;
+        default:
+            throw new CliError(`Unknown agent command: ${sub}\n\n${AGENT_HELP}`, 2);
+    }
+}
+async function commandAgentList(args) {
+    assertKnownAgentOptions(args, ["json", "apiUrl"]);
+    if (args.rest.length > 1) {
+        throw new CliError(`railcode agent list takes no arguments (got "${args.rest[1]}").`, 2);
+    }
+    const config = requireLogin(args);
+    const agents = await fetchAgents(config);
+    if (args.options.json) {
+        console.log(JSON.stringify(agents, null, 2));
+        return;
+    }
+    if (agents.length === 0) {
+        console.log("No managed agents in this organization.");
+        return;
+    }
+    console.log(formatTable(["name", "model", "uuid", "updated"], agents.map((agent) => [
+        agent.name,
+        typeof agent.manifest.model === "string" ? agent.manifest.model : "-",
+        agent.uuid,
+        shortDate(agent.updated_at),
+    ])));
+}
+async function commandAgentShow(args) {
+    assertKnownAgentOptions(args, ["json", "manifest", "apiUrl"]);
+    const ref = agentArg(args, "show");
+    const config = requireLogin(args);
+    const agent = await fetchAgent(config, ref);
+    if (args.options.json) {
+        console.log(JSON.stringify(agent, null, 2));
+        return;
+    }
+    if (args.options.manifest) {
+        console.log(JSON.stringify(agent.manifest, null, 2));
+        return;
+    }
+    printAgent(agent);
+}
+async function commandAgentPull(args) {
+    assertKnownAgentOptions(args, ["output", "json", "apiUrl"]);
+    const ref = agentArg(args, "pull");
+    const output = optionString(args, "output");
+    const config = requireLogin(args);
+    const agent = await fetchAgent(config, ref);
+    const manifest = JSON.stringify(agent.manifest, null, 2) + "\n";
+    if (output) {
+        writeFileSync(resolve(process.cwd(), output), manifest, { mode: 0o644 });
+        console.log(`Wrote ${output}`);
+        return;
+    }
+    process.stdout.write(manifest);
+}
+async function commandAgentCreate(args) {
+    assertKnownAgentOptions(args, ["file", "json", "apiUrl"]);
+    const manifest = readAgentManifest(args);
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ manifest }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const result = (await readJsonOrThrow(resp, "Create agent"));
+    printAgentMutation(result, args.options.json === true, "created");
+}
+async function commandAgentUpdate(args) {
+    assertKnownAgentOptions(args, ["file", "json", "apiUrl"]);
+    const ref = agentArg(args, "update");
+    const manifest = readAgentManifest(args);
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ manifest }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const result = (await readJsonOrThrow(resp, `Update agent "${ref}"`));
+    printAgentMutation(result, args.options.json === true, "updated");
+}
+async function commandAgentDelete(args) {
+    assertKnownAgentOptions(args, ["yes", "apiUrl"]);
+    const ref = agentArg(args, "delete");
+    if (args.options.yes !== true) {
+        if (!process.stdin.isTTY) {
+            throw new CliError("Pass --yes to delete an agent in a non-interactive session.", 2);
+        }
+        const answer = await prompt(`Delete agent "${ref}"? Its run history is kept. [y/N] `);
+        if (!["y", "yes"].includes(answer.trim().toLowerCase())) {
+            throw new CliError("Delete cancelled.", 1);
+        }
+    }
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}`, { method: "DELETE" });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (!resp.ok) {
+        throw new CliError(`Delete agent "${ref}" failed (${resp.status}): ${await errorDetail(resp)}`, 1);
+    }
+    console.log(`Agent "${ref}" deleted.`);
+}
+async function commandAgentTest(args) {
+    assertKnownAgentOptions(args, ["file", "input", "inputFile", "json", "trace", "apiUrl"]);
+    const manifest = readAgentManifest(args);
+    const input = readJsonInput(args);
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/test`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ manifest, input }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const run = (await readJsonOrThrow(resp, "Test agent"));
+    printAgentRun(run, { json: args.options.json === true, trace: args.options.trace === true });
+}
+async function commandAgentRun(args) {
+    assertKnownAgentOptions(args, ["input", "inputFile", "json", "trace", "apiUrl"]);
+    const ref = agentArg(args, "run");
+    const input = readJsonInput(args);
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}/invoke`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ input }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const run = (await readJsonOrThrow(resp, `Run agent "${ref}"`));
+    printAgentRun(run, { json: args.options.json === true, trace: args.options.trace === true });
+}
+async function commandAgentSchedule(args) {
+    const sub = args.rest[1] ?? "";
+    switch (sub) {
+        case "show":
+        case "list":
+        case "ls":
+            await commandAgentScheduleShow(args);
+            return;
+        case "set":
+            await commandAgentScheduleSet(args, "upsert");
+            return;
+        case "add":
+        case "create":
+            await commandAgentScheduleSet(args, "create");
+            return;
+        case "update":
+            await commandAgentScheduleSet(args, "update");
+            return;
+        case "pause":
+            await commandAgentScheduleEnabled(args, false);
+            return;
+        case "resume":
+            await commandAgentScheduleEnabled(args, true);
+            return;
+        case "delete":
+        case "rm":
+            await commandAgentScheduleDelete(args);
+            return;
+        case "run-now":
+        case "run":
+            await commandAgentScheduleRunNow(args);
+            return;
+        case "":
+        case "help":
+            console.log(AGENT_HELP);
+            return;
+        default:
+            throw new CliError(`Unknown agent schedule command: ${sub}\n\n${AGENT_HELP}`, 2);
+    }
+}
+async function commandAgentScheduleShow(args) {
+    assertKnownAgentOptions(args, ["json", "apiUrl"]);
+    const ref = agentScheduleAgentArg(args, "show");
+    const config = requireLogin(args);
+    const schedules = await fetchAgentSchedules(config, ref);
+    if (args.options.json) {
+        console.log(JSON.stringify(schedules, null, 2));
+        return;
+    }
+    if (schedules.length === 0) {
+        console.log(`Agent "${ref}" has no schedule.`);
+        return;
+    }
+    printSchedule(schedules[0]);
+}
+async function commandAgentScheduleSet(args, mode) {
+    assertKnownAgentOptions(args, [
+        "name",
+        "cron",
+        "schedule",
+        "timezone",
+        "enabled",
+        "disabled",
+        "json",
+        "apiUrl",
+    ]);
+    const ref = agentScheduleAgentArg(args, mode === "upsert" ? "set" : mode);
+    const config = requireLogin(args);
+    const existing = await fetchAgentSchedules(config, ref);
+    if (mode === "create" && existing.length > 0) {
+        throw new CliError(`Agent "${ref}" already has a schedule. Use \`railcode agent schedule set ${ref}\` to update it.`, 1);
+    }
+    if (mode === "update" && existing.length === 0) {
+        throw new CliError(`Agent "${ref}" has no schedule. Use \`railcode agent schedule set ${ref} --cron "0 9 * * *"\` to create one.`, 1);
+    }
+    const body = schedulePayload(args, existing.length === 0);
+    const path = existing.length === 0
+        ? `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}/schedules`
+        : `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}/schedules/${encodeURIComponent(existing[0].uuid)}`;
+    const resp = await authedFetch(config, path, {
+        method: existing.length === 0 ? "POST" : "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const schedule = (await readJsonOrThrow(resp, `${existing.length === 0 ? "Create" : "Update"} agent schedule`));
+    if (args.options.json) {
+        console.log(JSON.stringify(schedule, null, 2));
+        return;
+    }
+    console.log(existing.length === 0 ? "Schedule created." : "Schedule updated.");
+    printSchedule(schedule);
+}
+async function commandAgentScheduleEnabled(args, enabled) {
+    assertKnownAgentOptions(args, ["json", "apiUrl"]);
+    const ref = agentScheduleAgentArg(args, enabled ? "resume" : "pause");
+    const config = requireLogin(args);
+    const schedule = await requireSingleSchedule(config, ref);
+    const updated = await patchAgentSchedule(config, ref, schedule.uuid, { enabled });
+    if (args.options.json) {
+        console.log(JSON.stringify(updated, null, 2));
+        return;
+    }
+    console.log(enabled ? "Schedule resumed." : "Schedule paused.");
+    printSchedule(updated);
+}
+async function commandAgentScheduleDelete(args) {
+    assertKnownAgentOptions(args, ["yes", "apiUrl"]);
+    const ref = agentScheduleAgentArg(args, "delete");
+    const config = requireLogin(args);
+    const schedule = await requireSingleSchedule(config, ref);
+    if (args.options.yes !== true) {
+        if (!process.stdin.isTTY) {
+            throw new CliError("Pass --yes to delete a schedule in a non-interactive session.", 2);
+        }
+        const answer = await prompt(`Delete schedule "${schedule.name}" for agent "${ref}"? [y/N] `);
+        if (!["y", "yes"].includes(answer.trim().toLowerCase())) {
+            throw new CliError("Delete cancelled.", 1);
+        }
+    }
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}/schedules/${encodeURIComponent(schedule.uuid)}`, { method: "DELETE" });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (!resp.ok) {
+        throw new CliError(`Delete agent schedule failed (${resp.status}): ${await errorDetail(resp)}`, 1);
+    }
+    console.log(`Schedule "${schedule.name}" deleted.`);
+}
+async function commandAgentScheduleRunNow(args) {
+    assertKnownAgentOptions(args, ["json", "trace", "apiUrl"]);
+    const ref = agentScheduleAgentArg(args, "run-now");
+    const config = requireLogin(args);
+    const schedule = await requireSingleSchedule(config, ref);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}/schedules/${encodeURIComponent(schedule.uuid)}/run-now`, { method: "POST" });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const run = (await readJsonOrThrow(resp, `Run schedule "${schedule.name}"`));
+    printAgentRun(run, { json: args.options.json === true, trace: args.options.trace === true });
+}
+async function fetchAgents(config) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    return (await readJsonOrThrow(resp, "List agents"));
+}
+async function fetchAgent(config, ref) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    return (await readJsonOrThrow(resp, `Fetch agent "${ref}"`));
+}
+async function fetchAgentSchedules(config, ref) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}/schedules`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    return (await readJsonOrThrow(resp, `List schedules for agent "${ref}"`));
+}
+async function patchAgentSchedule(config, ref, scheduleUuid, body) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}/schedules/${encodeURIComponent(scheduleUuid)}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    return (await readJsonOrThrow(resp, "Update agent schedule"));
+}
+async function requireSingleSchedule(config, ref) {
+    const schedules = await fetchAgentSchedules(config, ref);
+    if (schedules.length === 0) {
+        throw new CliError(`Agent "${ref}" has no schedule.`, 1);
+    }
+    return schedules[0];
+}
+function readAgentManifest(args) {
+    const path = optionString(args, "file");
+    if (!path)
+        throw new CliError("Pass --file <agent-manifest.json>.", 2);
+    return readJsonObjectFile(path, "Agent manifest");
+}
+function readJsonObjectFile(path, label) {
+    const resolved = resolve(process.cwd(), path);
+    if (!existsSync(resolved))
+        throw new CliError(`${label} file not found: ${path}`, 2);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(resolved, "utf8"));
+    }
+    catch (error) {
+        throw new CliError(`${label} file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, 2);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError(`${label} file must contain a JSON object.`, 2);
+    }
+    return parsed;
+}
+function readJsonInput(args) {
+    const inline = optionString(args, "input");
+    const file = optionString(args, "inputFile");
+    if (inline !== undefined && file !== undefined) {
+        throw new CliError("Pass either --input or --input-file, not both.", 2);
+    }
+    if (inline === undefined && file === undefined)
+        return null;
+    const raw = inline ?? readFileSync(resolve(process.cwd(), file), "utf8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new CliError(`Agent input is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, 2);
+    }
+}
+function schedulePayload(args, creating) {
+    const body = {};
+    const name = optionString(args, "name");
+    const cron = optionString(args, "cron") ?? optionString(args, "schedule");
+    const timezone = optionString(args, "timezone");
+    if (args.options.enabled === true && args.options.disabled === true) {
+        throw new CliError("Pass either --enabled or --disabled, not both.", 2);
+    }
+    if (name !== undefined)
+        body.name = name;
+    if (cron !== undefined)
+        body.schedule = cron;
+    if (timezone !== undefined)
+        body.timezone = timezone;
+    if (args.options.enabled === true)
+        body.enabled = true;
+    if (args.options.disabled === true)
+        body.enabled = false;
+    if (creating) {
+        if (!body.name)
+            body.name = "default";
+        if (!body.schedule)
+            throw new CliError("Creating an agent schedule requires --cron.", 2);
+        if (!body.timezone)
+            body.timezone = "UTC";
+        if (body.enabled === undefined)
+            body.enabled = true;
+    }
+    else if (Object.keys(body).length === 0) {
+        throw new CliError("Nothing to update. Pass --name, --cron, --timezone, --enabled or --disabled.", 2);
+    }
+    return body;
+}
+function agentArg(args, command) {
+    const ref = args.rest[1];
+    if (!ref || args.rest.length > 2) {
+        throw new CliError(`Usage: railcode agent ${command} <agent>`, 2);
+    }
+    return ref;
+}
+function agentScheduleAgentArg(args, command) {
+    const ref = args.rest[2];
+    if (!ref || args.rest.length > 3) {
+        throw new CliError(`Usage: railcode agent schedule ${command} <agent>`, 2);
+    }
+    return ref;
+}
+function printAgentMutation(result, json, verb) {
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Agent "${result.agent.name}" ${verb}.`);
+    console.log(`UUID: ${result.agent.uuid}`);
+    if (result.warnings.length > 0) {
+        console.log("");
+        console.log("Warnings:");
+        for (const warning of result.warnings)
+            console.log(`- ${warning}`);
+    }
+}
+function printAgent(agent) {
+    console.log(agent.name);
+    console.log(`UUID: ${agent.uuid}`);
+    console.log(`Description: ${agent.description || "-"}`);
+    console.log(`Model: ${typeof agent.manifest.model === "string" ? agent.manifest.model : "-"}`);
+    console.log(`Updated: ${agent.updated_at}`);
+    console.log(`Content hash: ${agent.content_hash}`);
+}
+function printAgentRun(run, options) {
+    if (options.json) {
+        console.log(JSON.stringify(run, null, 2));
+        return;
+    }
+    console.log(`Status: ${run.status}`);
+    console.log(`Request: ${run.request_id}`);
+    if (run.error_code || run.error_message) {
+        console.log(`Error: ${[run.error_code, run.error_message].filter(Boolean).join(" - ")}`);
+    }
+    console.log("Output:");
+    console.log(JSON.stringify(run.output_json, null, 2));
+    if (options.trace) {
+        console.log("");
+        if (run.steps.length === 0) {
+            console.log("Trace: no steps");
+        }
+        else {
+            console.log("Trace:");
+            console.log(formatTable(["#", "kind", "status", "tool", "summary"], run.steps.map((step) => [
+                String(step.step_index),
+                step.kind,
+                step.status,
+                step.tool_name ?? "-",
+                step.result_summary ?? step.args_summary ?? step.error_message ?? "-",
+            ])));
+        }
+    }
+}
+function printSchedule(schedule) {
+    console.log(schedule.name);
+    console.log(`UUID: ${schedule.uuid}`);
+    console.log(`Cron: ${schedule.schedule}`);
+    console.log(`Timezone: ${schedule.timezone}`);
+    console.log(`Enabled: ${schedule.enabled ? "yes" : "no"}`);
+    console.log(`Next fire: ${schedule.next_fire_at}`);
+    console.log(`Last fire: ${schedule.last_fire_at ?? "-"}`);
+    console.log(`Last run: ${schedule.last_run_uuid ?? "-"}`);
+}
+function assertKnownAgentOptions(args, allowed) {
+    for (const key of Object.keys(args.options)) {
+        if (!allowed.includes(key)) {
+            throw new CliError(`Unknown option --${camelToKebab(key)} for \`railcode agent\`.\n\n${AGENT_HELP}`, 2);
+        }
+    }
+}
+function shortDate(value) {
+    return value.includes("T") ? value.slice(0, 10) : value;
+}
+// ---------------------------------------------------------------------------
 // db — list data connectors + run read-only SQL (`railcode db list|query`)
 //
 // Data connectors are org-wide, so these commands use the app-less org data
@@ -4382,8 +4932,9 @@ class CliError extends Error {
 // dev — local development server (`railcode dev`)
 //
 // Serves the app on a single loopback origin and emulates the /_api/* data plane:
-// identity is synthetic, KV + files live on local disk. llm/sql/connections proxy
-// to the real instance (added in a later milestone). Mirrors railcode-core's dev.
+// identity is synthetic, KV + files live on local disk. llm/sql/queries/connectors/email
+// proxy to the real instance as the signed-in user (their token + org grants) via the
+// org/user-scoped routes — no deploy needed. Mirrors railcode-core's dev.
 // ---------------------------------------------------------------------------
 const DEFAULT_DEV_PORT = 7331;
 const DEFAULT_ASSET_PORT = 5173;
@@ -4922,8 +5473,10 @@ async function handleLocalApi(ctx, req, res, url) {
         path === "/llm/generate" ||
         path === "/llm/stream" ||
         path === "/llm/providers" ||
+        path === "/email" ||
+        path === "/email/send" ||
         path === "/service-connectors" ||
-        path === "/service-connectors/request") {
+        path.startsWith("/service-connectors/")) {
         await forwardCompute(ctx, req, res, path, url);
         return;
     }
@@ -5113,27 +5666,29 @@ function devCreds(config) {
         return null;
     return { apiUrl: normalizeApiOrigin(apiUrl), token, orgUuid };
 }
-// Resolve the server-side app for proxying — lazily and memoized. Local dev must
-// not create product apps: an app becomes real on first successful deploy, not on
-// a dev-time SQL/LLM/connector call.
-function resolveDevAppUuid(ctx, creds) {
-    const base = `${creds.apiUrl}/api/organizations/${creds.orgUuid}/apps`;
-    const authed = { Authorization: `Bearer ${creds.token}` };
-    if (!ctx.appUuidPromise) {
-        ctx.appUuidPromise = (async () => {
-            try {
-                const resp = await fetch(base, { headers: authed });
-                if (!resp.ok)
-                    return null;
-                const apps = (await resp.json());
-                return apps.find((a) => a.app_slug === ctx.app && a.status === "active")?.uuid ?? null;
-            }
-            catch {
-                return null;
-            }
-        })();
-    }
-    return ctx.appUuidPromise;
+// Map a local-dev /_api compute path to the real org/user-scoped upstream URL. Local
+// dev invokes compute as the signed-in user (their personal token + org grants), NOT
+// as a deployed app — so no `railcode deploy` is needed first. The app slug still
+// namespaces local KV/files, but plays no part here. Deployed apps keep their own
+// bearer app-scoped routes (.../apps/{app}/...); this is deliberately the user plane.
+export function devComputeTarget(creds, path, search) {
+    const org = `${creds.apiUrl}/api/organizations/${creds.orgUuid}`;
+    if (path === "/connections")
+        return `${org}/data/connections${search}`;
+    if (path === "/sql")
+        return `${org}/data/sql${search}`;
+    if (path === "/queries" || path.startsWith("/queries/"))
+        return `${org}/data${path}${search}`;
+    if (path === "/service-connectors" || path.startsWith("/service-connectors/")) {
+        return `${org}/data${path}${search}`;
+    }
+    if (path === "/llm/providers" || path === "/llm/generate" || path === "/llm/stream") {
+        return `${org}${path}${search}`;
+    }
+    if (path === "/email" || path === "/email/send") {
+        return `${org}${path}${search}`;
+    }
+    return null;
 }
 export function devUpstreamAuthFallback(status, degradeOk) {
     if (status !== 401)
@@ -5164,19 +5719,13 @@ async function forwardCompute(ctx, req, res, path, url) {
             return sendJson(res, 200, []);
         return sendJson(res, 503, {
             error: "not_logged_in",
-            message: "Run `railcode login` to use LLM and connectors in dev.",
+            message: "Run `railcode login` to use LLM, SQL, saved queries, connectors, and email in dev.",
         });
     }
-    const appUuid = await resolveDevAppUuid(ctx, creds);
-    if (!appUuid) {
-        if (degradeOk)
-            return sendJson(res, 200, []);
-        return sendJson(res, 503, {
-            error: "app_unavailable",
-            message: "Deploy this app once before using LLM, SQL, saved queries, or connectors in dev.",
-        });
+    const target = devComputeTarget(creds, path, url.search);
+    if (!target) {
+        return sendJson(res, 404, { detail: "not found" });
     }
-    const target = `${creds.apiUrl}/api/organizations/${creds.orgUuid}/apps/${appUuid}${path}${url.search}`;
     const body = req.method === "POST" ? await readBody(req) : undefined;
     const headers = {
         Authorization: `Bearer ${creds.token}`,
@@ -5409,10 +5958,11 @@ function printDevBanner(ctx, config) {
     const creds = devCreds(config);
     if (creds) {
         console.log(`  account:   ${config.email ?? "?"} @ ${creds.apiUrl}`);
-        console.log(`  proxied:   llm/sql/connectors → real instance (REAL spend + data)`);
+        console.log(`  compute:   llm/sql/queries/connectors/email → real instance (REAL spend + data)`);
+        console.log(`  runs as:   you — your saved token + org permissions (no deploy needed)`);
     }
     else {
-        console.log(`  account:   not logged in — llm/sql return 503, connectors empty`);
+        console.log(`  account:   not logged in — llm/sql/email return 503, connectors empty`);
     }
     console.log("");
     console.log("  Ctrl-C to stop.");

package/dist/manifest.js

@@ -13,8 +13,11 @@
 //       - GET /v1/balance
 //       - GET /v1/customers/*
 //   llm: true
+//   email: true
 //   adhoc_sql:
 //     - warehouse
+//   agents:
+//     - sales-digest
 //
 // Also supported, matching PyYAML: flow lists (`saved_queries: [a, b]`), a flow
 // map for connectors (`connectors: {stripe: [GET /v1/balance]}`), a whole-
@@ -30,7 +33,15 @@
 // test/manifest-fixtures.json (also run by
 // backend/tests/test_manifest_parse_fixtures.py) keeps the two parsers pinned.
 export const APP_MANIFEST_NAME = "manifest.yaml";
-const ALLOWED_KEYS = ["run_as", "saved_queries", "connectors", "llm", "adhoc_sql"];
+const ALLOWED_KEYS = [
+    "run_as",
+    "saved_queries",
+    "connectors",
+    "llm",
+    "email",
+    "adhoc_sql",
+    "agents",
+];
 const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 const SAVED_QUERY_NAME = /^[a-z0-9_]{1,80}$/;
 // PyYAML's YAML 1.1 plain-scalar resolver: a bare (unquoted) scalar matching one
@@ -322,7 +333,7 @@ function listString(s, key, num) {
         throw new ManifestParseError(`Empty list item under "${key}"`, num);
     return value;
 }
-function parseBool(s, num) {
+function parseBool(s, key, num) {
     // A quoted scalar is a STRING even if it spells a boolean — as on the server.
     if (!s.quoted) {
         if (YAML_TRUE.test(s.value))
@@ -330,7 +341,7 @@ function parseBool(s, num) {
         if (YAML_FALSE.test(s.value))
             return false;
     }
-    throw new ManifestParseError(`"llm" must be true or false (got "${s.value}")`, num);
+    throw new ManifestParseError(`"${key}" must be true or false (got "${s.value}")`, num);
 }
 // Strip the optional document markers: one leading "---" and one trailing "..."
 // are no-ops. Anything more is a multi-document stream, which the server
@@ -382,7 +393,9 @@ export function parseManifestYaml(source) {
         saved_queries: [],
         connectors: {},
         llm: false,
+        email: false,
         adhoc_sql: [],
+        agents: [],
     };
     for (const [key, entry] of entries) {
         if (key === "run_as") {
@@ -393,16 +406,21 @@ export function parseManifestYaml(source) {
             doc.run_as = value;
         }
         else if (key === "llm") {
-            doc.llm = parseBool(inlineScalar(entry, key), entry.keyLine.num);
+            doc.llm = parseBool(inlineScalar(entry, key), key, entry.keyLine.num);
+        }
+        else if (key === "email") {
+            doc.email = parseBool(inlineScalar(entry, key), key, entry.keyLine.num);
         }
         else if (key === "connectors") {
             doc.connectors = parseConnectors(entry);
         }
         else {
-            // saved_queries / adhoc_sql: a list of names.
+            // saved_queries / adhoc_sql / agents: a list of names.
             const items = parseStringList(entry, key);
             if (key === "saved_queries")
                 doc.saved_queries = items;
+            else if (key === "agents")
+                doc.agents = items;
             else
                 doc.adhoc_sql = items;
         }
@@ -624,6 +642,7 @@ function validateDoc(doc, lines) {
     }
     doc.saved_queries = [...new Set(doc.saved_queries)].sort();
     doc.adhoc_sql = [...new Set(doc.adhoc_sql)].sort();
+    doc.agents = [...new Set(doc.agents)].sort();
     for (const name of Object.keys(doc.connectors)) {
         doc.connectors[name] = [...new Set(doc.connectors[name])].sort();
     }
@@ -644,6 +663,8 @@ export function documentOperations(doc) {
     }
     if (doc.llm)
         ops.push({ type: "llm", id: "*", label: "LLM access" });
+    if (doc.email)
+        ops.push({ type: "email", id: "*", label: "email sending" });
     for (const name of doc.adhoc_sql) {
         ops.push({ type: "connector", id: name, label: `ad-hoc SQL on "${name}"` });
     }
@@ -666,6 +687,9 @@ export function renderManifestSummary(doc) {
     if (doc.adhoc_sql.length > 0) {
         lines.push("warning: adhoc_sql grants ad-hoc SQL authority — scarce by design; prefer saved queries");
     }
+    if (doc.agents.length > 0) {
+        lines.push(`agents: ${doc.agents.join(", ")}`);
+    }
     return lines.join("\n");
 }
 export function renderManifestDeployOutcome(m) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "railcode",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Developer CLI for the multi-tenant Railcode platform: log in, scaffold, and deploy static apps.",
   "license": "MIT",
   "type": "module",

package/static/sdk.js

@@ -175,8 +175,8 @@
     }
     return shorten(String(res), 48);
   }
-  function track(kind, label2, thunk) {
-    const entry = { kind, label: label2, status: "pending", t0: performance.now() };
+  function track(kind, label3, thunk) {
+    const entry = { kind, label: label3, status: "pending", t0: performance.now() };
     Inspector.add(entry);
     return thunk().then(
       (res) => {
@@ -195,8 +195,8 @@
       }
     );
   }
-  function trackStream(kind, label2, streamFactory) {
-    const entry = { kind, label: label2, status: "pending", t0: performance.now() };
+  function trackStream(kind, label3, streamFactory) {
+    const entry = { kind, label: label3, status: "pending", t0: performance.now() };
     Inspector.add(entry);
     return async function* () {
       let textLen = 0;
@@ -219,6 +219,15 @@
     }();
   }
 
+  // ../sdk/src/agents.ts
+  async function doInvoke(name, input) {
+    return call("POST", `/agents/${encodeURIComponent(name)}`, { body: { input } });
+  }
+  function invoke(name, input) {
+    return track("agents", `agents.invoke(${q(name)})`, () => doInvoke(name, input));
+  }
+  var agents = { invoke };
+
   // ../sdk/src/databases.ts
   var QUERY_LABEL_MAX = 80;
   var PARAMS_LABEL_MAX = 40;
@@ -234,10 +243,10 @@
   };
   var runSQL = (engine, connection, query2, params) => {
     const trimmed = shorten(query2.replace(/\s+/g, " ").trim(), QUERY_LABEL_MAX);
-    const label2 = `${engine ?? "data"}(${q(connection)}).runSQL(${q(trimmed)}${params && params.length ? `, ${shorten(JSON.stringify(params), PARAMS_LABEL_MAX)}` : ""})`;
+    const label3 = `${engine ?? "data"}(${q(connection)}).runSQL(${q(trimmed)}${params && params.length ? `, ${shorten(JSON.stringify(params), PARAMS_LABEL_MAX)}` : ""})`;
     return track(
       "sql",
-      label2,
+      label3,
       () => call("POST", "/sql", {
         // engine is advisory; omit it for the generic data() namespace so the backend
         // dispatches on the connection's stored kind. postgres() pins engine="postgres".
@@ -387,6 +396,32 @@
     return resp.markdown;
   });
 
+  // ../sdk/src/email.ts
+  function label(opts) {
+    const to = Array.isArray(opts.to) ? `${opts.to.length} recipients` : opts.to;
+    return `email.send(${q(shorten(`${to}: ${opts.subject}`, 70))})`;
+  }
+  function body(opts) {
+    const out = {
+      to: opts.to,
+      subject: opts.subject
+    };
+    if (opts.html !== void 0) out.html = opts.html;
+    if (opts.text !== void 0) out.text = opts.text;
+    if (opts.cc !== void 0) out.cc = opts.cc;
+    if (opts.bcc !== void 0) out.bcc = opts.bcc;
+    if (opts.replyTo !== void 0) out.replyTo = opts.replyTo;
+    return out;
+  }
+  function send2(opts) {
+    return track(
+      "email",
+      label(opts),
+      () => call("POST", "/email/send", { body: body(opts) })
+    );
+  }
+  var email = { send: send2 };
+
   // ../sdk/src/files.ts
   function contentTypeOf(data2, explicit) {
     if (explicit) return explicit;
@@ -431,12 +466,12 @@
   var appUsers = () => track("app-users", "appUsers()", () => call("GET", "/app-users"));
 
   // ../sdk/src/llm.ts
-  function label(method, input, opts = {}) {
+  function label2(method, input, opts = {}) {
     const preview = typeof input === "string" ? shorten(input.replace(/\s+/g, " ").trim(), 70) : `${input.length} message${input.length === 1 ? "" : "s"}`;
     const output = opts.output?.type === "json" ? " \u2192 json" : "";
     return `llm.${method}(${q(preview)})${output}`;
   }
-  function body(input, opts = {}) {
+  function body2(input, opts = {}) {
     const out = Array.isArray(input) ? { messages: input } : { input };
     if (opts.model !== void 0) out.model = opts.model;
     if (opts.provider !== void 0) out.provider = opts.provider;
@@ -452,7 +487,7 @@
       method: "POST",
       credentials: "include",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body(input, opts))
+      body: JSON.stringify(body2(input, opts))
     });
     if (!resp.ok) throw new ApiError(resp.status, await resp.text());
     return await resp.json();
@@ -465,7 +500,7 @@
       method: "POST",
       credentials: "include",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body(input, opts))
+      body: JSON.stringify(body2(input, opts))
     });
     if (!resp.ok) throw new ApiError(resp.status, await resp.text());
     if (!resp.body) throw new Error("LLM stream response has no body.");
@@ -493,10 +528,10 @@
     }
   }
   function generate(input, opts = {}) {
-    return track("llm", label("generate", input, opts), () => doGenerate(input, opts));
+    return track("llm", label2("generate", input, opts), () => doGenerate(input, opts));
   }
   function stream(input, opts = {}) {
-    return trackStream("llm", label("stream", input, opts), () => doStream(input, opts));
+    return trackStream("llm", label2("stream", input, opts), () => doStream(input, opts));
   }
   var llm = { generate, stream };
   var llmProviders = () => track("llm", "llmProviders()", () => call("GET", "/llm/providers"));
@@ -504,10 +539,10 @@
   // ../sdk/src/queries.ts
   var PARAMS_LABEL_MAX2 = 40;
   var query = (name, params) => {
-    const label2 = `query(${q(name)}${params && Object.keys(params).length ? `, ${shorten(JSON.stringify(params), PARAMS_LABEL_MAX2)}` : ""})`;
+    const label3 = `query(${q(name)}${params && Object.keys(params).length ? `, ${shorten(JSON.stringify(params), PARAMS_LABEL_MAX2)}` : ""})`;
     return track(
       "sql",
-      label2,
+      label3,
       () => call("POST", `/queries/${encPath(name)}`, {
         body: { params: params || {} }
       }).then(toSqlRows)
@@ -518,22 +553,22 @@
   // ../sdk/src/service-connectors.ts
   var PATH_LABEL_MAX = 60;
   var toResponse = (env) => {
-    const body2 = env.body ?? "";
+    const body3 = env.body ?? "";
     return {
       status: env.status,
       ok: env.ok,
       headers: env.headers || {},
       truncated: Boolean(env.truncated),
-      text: () => Promise.resolve(body2),
-      json: () => Promise.resolve(JSON.parse(body2))
+      text: () => Promise.resolve(body3),
+      json: () => Promise.resolve(JSON.parse(body3))
     };
   };
   var request = (name, path, opts) => {
     const method = (opts?.method || "GET").toUpperCase();
-    const label2 = `connector(${q(name)}).fetch(${q(method)} ${q(shorten(path, PATH_LABEL_MAX))})`;
+    const label3 = `connector(${q(name)}).fetch(${q(method)} ${q(shorten(path, PATH_LABEL_MAX))})`;
     return track(
       "connector",
-      label2,
+      label3,
       () => call("POST", "/service-connectors/request", {
         body: { connector: name, method, path, body: opts?.body }
       }).then(toResponse)
@@ -555,6 +590,7 @@
   target.me = me;
   target.appUsers = appUsers;
   target.designSystem = designSystem;
+  target.email = email;
   target.llm = llm;
   target.llmProviders = llmProviders;
   target.data = data;
@@ -566,4 +602,5 @@
   target.serviceConnectors = serviceConnectors;
   target.query = query;
   target.savedQueries = savedQueries;
+  target.agents = agents;
 })();