@rooaak/cli 0.1.0-beta.1

package/dist/src/commands/init/index.js

@@ -0,0 +1,756 @@
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { resolveBaseUrl } from "../../lib/base-url.js";
+import { ExitCode } from "../../lib/exit-codes.js";
+import { createRenderer } from "../../lib/renderer.js";
+import { normalizeLocalUsageError, toJsonErrorEnvelope, toJsonOkEnvelope, exitCodeForError } from "../../lib/normalize-error.js";
+import { parseOptions } from "../../lib/options.js";
+import { createProfileStore } from "../../lib/profile-store.js";
+import { isValidProfileName } from "../../lib/profile-name.js";
+import { createTransport } from "../../lib/transport.js";
+import { promptConfirm, promptSecret, promptText } from "./prompting.js";
+import { waitForMessageResponse } from "./wait-for-message.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function safeBasename(p) {
+    const base = path.basename(p || "");
+    return base && base !== "." && base !== path.sep ? base : "rooaak-project";
+}
+function slugToProfileName(input) {
+    const s = input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return s.length > 0 ? s : "default";
+}
+function normalizeInitError(input) {
+    return {
+        code: input.code,
+        message: input.message,
+        details: input.details ?? {},
+        meta: { status: input.meta?.status, requestId: input.meta?.requestId },
+    };
+}
+function noTtyUsageError(message, details = {}) {
+    return normalizeInitError({
+        code: "usage.validation_error",
+        message,
+        details,
+    });
+}
+async function requireAdminTransport(ctx, r, argvApiKey) {
+    const store = createProfileStore({ configPath: ctx.profileConfigPath });
+    const cfgRes = store.readConfig();
+    if (cfgRes.kind === "corrupt") {
+        // Allow remediation: if user provides an API key, we'll overwrite later. Surface a hint.
+        r.warn(cfgRes.message);
+    }
+    const config = cfgRes.kind === "ok" ? cfgRes.config : null;
+    const profile = config ? config.profiles[config.currentProfile] : null;
+    const baseUrl = resolveBaseUrl({
+        cliFlag: ctx.flags.baseUrl,
+        env: ctx.env.ROOAAK_BASE_URL,
+        profile: profile?.baseUrl,
+    });
+    async function validateAdminKey(candidate) {
+        const transport = createTransport({ baseUrl, apiKey: candidate, fetchFn: ctx.fetchFn });
+        const res = await transport.getJson("/api/v1/projects?limit=1");
+        if (!res.ok) {
+            return { ok: false, http: { status: res.status, requestId: res.requestId, err: res.error } };
+        }
+        return { ok: true, transport, meta: { status: res.status, requestId: res.requestId } };
+    }
+    if (typeof argvApiKey === "string" && argvApiKey.length > 0) {
+        const v = await validateAdminKey(argvApiKey);
+        if (v.ok)
+            return { ok: true, transport: v.transport, baseUrl, adminApiKey: argvApiKey, requestMeta: v.meta };
+        const status = v.http?.status;
+        if (status === 401) {
+            return {
+                ok: false,
+                exit: ExitCode.Auth,
+                err: normalizeInitError({
+                    code: "auth.invalid_api_key",
+                    message: "Invalid API key",
+                    meta: { status: v.http?.status, requestId: v.http?.requestId },
+                }),
+            };
+        }
+        if (status === 403) {
+            return {
+                ok: false,
+                exit: ExitCode.Permission,
+                err: normalizeInitError({
+                    code: "permission.admin_key_required",
+                    message: "Admin API key required to create/select projects.",
+                    details: { next: "Use an admin API key with scope admin:project (project_id must be NULL)." },
+                    meta: { status: v.http?.status, requestId: v.http?.requestId },
+                }),
+            };
+        }
+        return { ok: false, exit: exitCodeForError(v.http?.err ?? normalizeInitError({ code: "server.error", message: "Server error" })), err: v.http?.err ?? normalizeInitError({ code: "server.error", message: "Server error" }) };
+    }
+    if (profile?.apiKey) {
+        const v = await validateAdminKey(profile.apiKey);
+        if (v.ok)
+            return { ok: true, transport: v.transport, baseUrl, adminApiKey: profile.apiKey, requestMeta: v.meta };
+        const status = v.http?.status;
+        const err = v.http?.err ?? normalizeInitError({ code: "server.error", message: "Server error" });
+        if (ctx.flags.nonInteractive) {
+            if (status === 401) {
+                return {
+                    ok: false,
+                    exit: ExitCode.Auth,
+                    err: normalizeInitError({
+                        code: "auth.invalid_api_key",
+                        message: "Invalid API key",
+                        meta: { status: v.http?.status, requestId: v.http?.requestId },
+                    }),
+                };
+            }
+            if (status === 403) {
+                return {
+                    ok: false,
+                    exit: ExitCode.Permission,
+                    err: normalizeInitError({
+                        code: "permission.admin_key_required",
+                        message: err.message || "Admin API key required to create/select projects.",
+                        details: {
+                            next: "Pass --api-key with an admin API key (scope admin:project), or switch to an admin profile.",
+                        },
+                        meta: { status: v.http?.status, requestId: v.http?.requestId },
+                    }),
+                };
+            }
+            return { ok: false, exit: exitCodeForError(err), err };
+        }
+        // Interactive: allow recovery by prompting for an admin key on auth/permission failures.
+        if (status === 401) {
+            r.warn("Current profile API key is invalid. You'll be prompted for an admin API key.");
+        }
+        else if (status === 403) {
+            r.warn("Current profile API key cannot manage projects. You'll be prompted for an admin API key.");
+        }
+        else {
+            // Network/transient failures won't be fixed by prompting.
+            return { ok: false, exit: exitCodeForError(err), err };
+        }
+    }
+    if (ctx.flags.nonInteractive) {
+        return {
+            ok: false,
+            exit: ExitCode.Auth,
+            err: normalizeInitError({
+                code: "auth.not_logged_in",
+                message: "Not logged in. Provide --api-key or run `rooaak auth login --api-key ...`.",
+            }),
+        };
+    }
+    if (ctx.stdinIsTTY !== true) {
+        return {
+            ok: false,
+            exit: ExitCode.Usage,
+            err: noTtyUsageError("Cannot prompt for API key because stdin is not a TTY. Re-run with --non-interactive and provide --api-key, or run `rooaak auth login --api-key ...` from an interactive terminal."),
+        };
+    }
+    // Interactive: prompt until valid admin key is provided.
+    while (true) {
+        const entered = await promptSecret({ stderr: ctx.stderr, stdin: ctx.stdin, stdinIsTTY: ctx.stdinIsTTY }, "Admin API key", { allowEmpty: false });
+        const v = await validateAdminKey(entered);
+        if (v.ok)
+            return { ok: true, transport: v.transport, baseUrl, adminApiKey: entered, requestMeta: v.meta };
+        const status = v.http?.status;
+        if (status === 401) {
+            r.error("Invalid API key. Try again.");
+            continue;
+        }
+        if (status === 403) {
+            r.error("That key cannot manage projects. Use an admin API key with scope admin:project.");
+            continue;
+        }
+        r.error(v.http?.err.message ?? "Request failed. Try again.");
+    }
+}
+async function findProjectsByExactName(adminTransport, projectName) {
+    const matches = [];
+    let cursor = null;
+    let meta = null;
+    while (true) {
+        const qs = new URLSearchParams();
+        qs.set("limit", "500");
+        if (cursor)
+            qs.set("cursor", cursor);
+        const httpRes = await adminTransport.getJson(`/api/v1/projects?${qs.toString()}`);
+        if (!httpRes.ok)
+            return { ok: false, err: httpRes.error };
+        meta = { status: httpRes.status, requestId: httpRes.requestId };
+        const items = Array.isArray(httpRes.data.items) ? httpRes.data.items : [];
+        for (const p of items) {
+            if (p.name === projectName)
+                matches.push(p);
+            if (matches.length >= 2) {
+                return { ok: true, matches, meta };
+            }
+        }
+        const next = httpRes.data.nextCursor ?? null;
+        if (!next)
+            return { ok: true, matches, meta };
+        cursor = next;
+    }
+}
+async function ensureProjectByName(input) {
+    const findRes = await findProjectsByExactName(input.adminTransport, input.projectName);
+    if (!findRes.ok)
+        return { ok: false, err: findRes.err };
+    const matches = findRes.matches;
+    if (matches.length === 1)
+        return { ok: true, project: matches[0], created: false, meta: findRes.meta };
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            err: normalizeInitError({
+                code: "conflict.duplicate_project_name",
+                message: `Multiple projects named '${input.projectName}' exist.`,
+                details: { next: "Run `rooaak init` in interactive mode to select a project." },
+                meta: findRes.meta,
+            }),
+        };
+    }
+    const createRes = await input.adminTransport.requestJson({
+        method: "POST",
+        path: "/api/v1/projects",
+        body: { name: input.projectName },
+    });
+    if (createRes.ok) {
+        return { ok: true, project: { id: createRes.data.id, name: createRes.data.name }, created: true, meta: { status: createRes.status, requestId: createRes.requestId } };
+    }
+    // Best-effort recovery: if the create failed but the project exists now (race, duplicate name), select it.
+    const findAgain = await findProjectsByExactName(input.adminTransport, input.projectName);
+    if (findAgain.ok) {
+        const againMatches = findAgain.matches;
+        if (againMatches.length === 1)
+            return { ok: true, project: againMatches[0], created: false, meta: findAgain.meta };
+    }
+    return { ok: false, err: createRes.error };
+}
+async function createProjectApiKey(input) {
+    const httpRes = await input.adminTransport.requestJson({
+        method: "POST",
+        path: `/api/v1/projects/${input.projectId}/api-keys`,
+        body: { name: input.name },
+    });
+    if (!httpRes.ok)
+        return { ok: false, err: httpRes.error };
+    const key = isPlainObject(httpRes.data) && typeof httpRes.data.key === "string" ? httpRes.data.key : null;
+    if (!key) {
+        return {
+            ok: false,
+            err: normalizeInitError({
+                code: "server.invalid_response",
+                message: "Server returned an unexpected API key response.",
+                meta: { status: httpRes.status, requestId: httpRes.requestId },
+            }),
+        };
+    }
+    return { ok: true, apiKey: key, meta: { status: httpRes.status, requestId: httpRes.requestId } };
+}
+function writeProjectProfile(input) {
+    const store = createProfileStore({ configPath: input.ctx.profileConfigPath });
+    const existingRes = store.readConfig();
+    if (existingRes.kind === "corrupt") {
+        // Allowed remediation path.
+        input.r.warn(existingRes.message);
+    }
+    const existing = existingRes.kind === "ok" ? existingRes.config : null;
+    let profileName = input.profileName;
+    if (typeof profileName === "string" && profileName.length > 0) {
+        if (!isValidProfileName(profileName)) {
+            const err = normalizeLocalUsageError("Invalid profile name", { profile: profileName });
+            return { ok: false, exit: ExitCode.Usage, err };
+        }
+    }
+    else if (!existing) {
+        profileName = "default";
+    }
+    else {
+        const base = `project-${slugToProfileName(input.projectName)}`;
+        profileName = base;
+        // Avoid clobbering an existing profile name.
+        if (existing.profiles[profileName]) {
+            let i = 2;
+            while (existing.profiles[`${profileName}-${i}`])
+                i++;
+            profileName = `${profileName}-${i}`;
+        }
+    }
+    const now = new Date().toISOString();
+    const next = {
+        version: 1,
+        currentProfile: profileName,
+        profiles: {
+            ...(existing?.profiles ?? {}),
+            [profileName]: {
+                apiKey: input.apiKey,
+                baseUrl: input.baseUrl,
+                updatedAt: now,
+            },
+        },
+    };
+    store.writeConfig(next);
+    input.r.debug(`Wrote config: ${store.getConfigPath()}`);
+    return { ok: true, profileName };
+}
+export async function initCommand(ctx, argv) {
+    const r = createRenderer(ctx);
+    const parsed = parseOptions(argv, [
+        { name: "--help", takesValue: false },
+        { name: "--api-key", takesValue: true }, // admin key
+        { name: "--project-name", takesValue: true },
+        { name: "--agent-name", takesValue: true },
+        { name: "--test-message", takesValue: true },
+        { name: "--wait-timeout-ms", takesValue: true },
+        { name: "--profile", takesValue: true },
+        { name: "--start", takesValue: false },
+        { name: "--no-start", takesValue: false },
+    ]);
+    if (parsed.unknownOption) {
+        const err = normalizeLocalUsageError(`Unknown option: ${parsed.unknownOption}`);
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    if (parsed.missingValueOption) {
+        const err = normalizeLocalUsageError(`Missing value for: ${parsed.missingValueOption}`);
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    if (parsed.positionals.length > 0) {
+        const err = normalizeLocalUsageError("Unexpected extra arguments", { argc: parsed.positionals.length });
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    if (parsed.values["--help"]) {
+        if (ctx.flags.json) {
+            r.json(toJsonOkEnvelope({
+                type: "help",
+                command: "init",
+                usage: "rooaak init [--api-key <key>] [--project-name <name>] [--agent-name <name>] [--test-message <text>] [--wait-timeout-ms <ms>] [--profile <name>] [--start|--no-start] [--json] [--non-interactive]",
+                flags: [
+                    { name: "--api-key <key>", description: "Admin API key (required when not logged in as admin)" },
+                    { name: "--project-name <name>", description: "Project name to create/select" },
+                    { name: "--agent-name <name>", description: "Agent name to create" },
+                    { name: "--test-message <text>", description: "Message to send after creation" },
+                    { name: "--wait-timeout-ms <ms>", description: "How long to wait for the first response (default 60000ms; overrides ROOAAK_SYNC_MESSAGE_TIMEOUT_MS)" },
+                    { name: "--start", description: "Start the agent (default)" },
+                    { name: "--no-start", description: "Skip starting the agent" },
+                    { name: "--profile <name>", description: "Profile name to save the created project API key under" },
+                ],
+            }));
+            return ExitCode.Success;
+        }
+        ctx.stdout.write([
+            "Usage:",
+            "  rooaak init [flags]",
+            "",
+            "Flags:",
+            "  --api-key <key>          Admin API key (required when not logged in as admin)",
+            "  --project-name <name>    Project name to create/select",
+            "  --agent-name <name>      Agent name to create",
+            "  --test-message <text>    Message to send after creation",
+            "  --wait-timeout-ms <ms>   How long to wait for the first response (default 60000ms; overrides ROOAAK_SYNC_MESSAGE_TIMEOUT_MS)",
+            "  --start                  Start the agent (default)",
+            "  --no-start               Skip starting the agent",
+            "  --profile <name>         Profile name to save created project API key under",
+            "",
+            "Global flags:",
+            "  --json                   Machine output (single JSON object on stdout)",
+            "  --non-interactive        Fail fast instead of prompting",
+            "",
+        ].join("\n"));
+        return ExitCode.Success;
+    }
+    const interactive = !ctx.flags.nonInteractive;
+    const flagProjectName = parsed.values["--project-name"];
+    const flagAgentName = parsed.values["--agent-name"];
+    const flagTestMessage = parsed.values["--test-message"];
+    const flagWaitTimeoutMs = parsed.values["--wait-timeout-ms"];
+    const flagProfileName = parsed.values["--profile"];
+    let projectName = typeof flagProjectName === "string" && flagProjectName.trim().length > 0 ? flagProjectName.trim() : "";
+    let agentName = typeof flagAgentName === "string" && flagAgentName.trim().length > 0 ? flagAgentName.trim() : "";
+    let testMessage = typeof flagTestMessage === "string" && flagTestMessage.trim().length > 0 ? flagTestMessage.trim() : "";
+    const wantsStart = Boolean(parsed.values["--start"]);
+    const wantsNoStart = Boolean(parsed.values["--no-start"]);
+    if (wantsStart && wantsNoStart) {
+        const err = normalizeLocalUsageError("Conflicting flags: --start and --no-start");
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    let startAgent;
+    if (wantsStart)
+        startAgent = true;
+    else if (wantsNoStart)
+        startAgent = false;
+    else if (!interactive)
+        startAgent = true;
+    else if (ctx.stdinIsTTY !== true)
+        startAgent = true;
+    else
+        startAgent = await promptConfirm({ stderr: ctx.stderr, stdin: ctx.stdin, stdinIsTTY: ctx.stdinIsTTY }, "Start the agent now?", { defaultYes: true });
+    if (!projectName) {
+        if (!interactive) {
+            const err = normalizeLocalUsageError("Missing required flag: --project-name");
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return ExitCode.Usage;
+        }
+        if (ctx.stdinIsTTY !== true) {
+            const err = noTtyUsageError("Cannot prompt for --project-name because stdin is not a TTY. Re-run with --non-interactive and provide --project-name.");
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return ExitCode.Usage;
+        }
+        projectName = await promptText({ stderr: ctx.stderr, stdin: ctx.stdin, stdinIsTTY: ctx.stdinIsTTY }, "Project name", { defaultValue: safeBasename(ctx.cwd) });
+        projectName = projectName.trim();
+    }
+    if (!agentName) {
+        if (!interactive) {
+            const err = normalizeLocalUsageError("Missing required flag: --agent-name");
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return ExitCode.Usage;
+        }
+        if (ctx.stdinIsTTY !== true) {
+            const err = noTtyUsageError("Cannot prompt for --agent-name because stdin is not a TTY. Re-run with --non-interactive and provide --agent-name.");
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return ExitCode.Usage;
+        }
+        agentName = await promptText({ stderr: ctx.stderr, stdin: ctx.stdin, stdinIsTTY: ctx.stdinIsTTY }, "Agent name", { defaultValue: `${projectName}-agent` });
+        agentName = agentName.trim();
+    }
+    if (!testMessage) {
+        if (!interactive) {
+            const err = normalizeLocalUsageError("Missing required flag: --test-message");
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return ExitCode.Usage;
+        }
+        if (ctx.stdinIsTTY !== true) {
+            const err = noTtyUsageError("Cannot prompt for --test-message because stdin is not a TTY. Re-run with --non-interactive and provide --test-message.");
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return ExitCode.Usage;
+        }
+        testMessage = await promptText({ stderr: ctx.stderr, stdin: ctx.stdin, stdinIsTTY: ctx.stdinIsTTY }, "Test message", {
+            defaultValue: "Hello! Reply with a short greeting so I can verify you're working.",
+        });
+        testMessage = testMessage.trim();
+    }
+    // Wait timeout override: flag -> env -> default.
+    let waitTimeoutMs = 60_000;
+    const envTimeout = ctx.env.ROOAAK_SYNC_MESSAGE_TIMEOUT_MS;
+    if (typeof envTimeout === "string" && envTimeout.trim().length > 0) {
+        const n = Number(envTimeout);
+        if (Number.isFinite(n) && n > 0)
+            waitTimeoutMs = Math.floor(n);
+    }
+    if (typeof flagWaitTimeoutMs === "string" && flagWaitTimeoutMs.trim().length > 0) {
+        const n = Number(flagWaitTimeoutMs);
+        if (!Number.isFinite(n) || n <= 0) {
+            const err = normalizeLocalUsageError("Invalid value for --wait-timeout-ms", { value: flagWaitTimeoutMs });
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return ExitCode.Usage;
+        }
+        waitTimeoutMs = Math.floor(n);
+    }
+    const adminApiKey = typeof parsed.values["--api-key"] === "string" ? parsed.values["--api-key"] : undefined;
+    const adminRes = await requireAdminTransport(ctx, r, adminApiKey);
+    if (!adminRes.ok) {
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(adminRes.err));
+        else
+            r.error(adminRes.err.message);
+        return adminRes.exit;
+    }
+    const { transport: adminTransport, baseUrl } = adminRes;
+    if (interactive) {
+        r.warn("This will create/select a project, generate a project API key, create an agent, and send a first message.");
+    }
+    // Create/select project.
+    let projectRes;
+    if (interactive) {
+        const findRes = await findProjectsByExactName(adminTransport, projectName);
+        if (!findRes.ok) {
+            const err = findRes.err;
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return exitCodeForError(err);
+        }
+        if (findRes.matches.length === 1) {
+            const shouldPrompt = ctx.stdinIsTTY === true;
+            const useExisting = shouldPrompt
+                ? await promptConfirm({ stderr: ctx.stderr, stdin: ctx.stdin, stdinIsTTY: ctx.stdinIsTTY }, `Project '${projectName}' exists. Use it?`, { defaultYes: true })
+                : true;
+            if (useExisting) {
+                projectRes = { ok: true, project: findRes.matches[0], created: false, meta: findRes.meta };
+            }
+            else {
+                projectName = await promptText({ stderr: ctx.stderr, stdin: ctx.stdin, stdinIsTTY: ctx.stdinIsTTY }, "Project name", { defaultValue: `${projectName}-2` });
+                projectName = projectName.trim();
+                projectRes = await ensureProjectByName({ adminTransport, projectName });
+            }
+        }
+        else if (findRes.matches.length > 1) {
+            projectRes = {
+                ok: false,
+                err: normalizeInitError({
+                    code: "conflict.duplicate_project_name",
+                    message: `Multiple projects named '${projectName}' exist.`,
+                    details: { next: "Specify a unique --project-name or clean up duplicates." },
+                    meta: findRes.meta,
+                }),
+            };
+        }
+        else {
+            projectRes = await ensureProjectByName({ adminTransport, projectName });
+        }
+    }
+    else {
+        projectRes = await ensureProjectByName({ adminTransport, projectName });
+    }
+    if (!projectRes.ok) {
+        const err = projectRes.err;
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else {
+            r.error(err.message);
+            if (err.code === "permission.forbidden" || err.code.startsWith("permission.")) {
+                r.warn("Project management requires an admin API key with scope admin:project.");
+            }
+        }
+        return exitCodeForError(err);
+    }
+    const project = projectRes.project;
+    // Create a project-scoped API key and store it locally.
+    const apiKeyRes = await createProjectApiKey({
+        adminTransport,
+        projectId: project.id,
+        name: "rooaak-cli-init",
+    });
+    if (!apiKeyRes.ok) {
+        const err = apiKeyRes.err;
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else {
+            r.error(err.message);
+            r.warn("Creating project API keys requires admin:project (admin key) or project:api-keys (project key).");
+        }
+        return exitCodeForError(err);
+    }
+    const projectApiKey = apiKeyRes.apiKey;
+    const writeRes = writeProjectProfile({
+        ctx,
+        r,
+        baseUrl,
+        apiKey: projectApiKey,
+        projectName: project.name,
+        profileName: typeof flagProfileName === "string" ? flagProfileName : undefined,
+    });
+    if (!writeRes.ok) {
+        const err = writeRes.err;
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return writeRes.exit;
+    }
+    const profileName = writeRes.profileName;
+    const projectTransport = createTransport({ baseUrl, apiKey: projectApiKey, fetchFn: ctx.fetchFn });
+    // Create agent.
+    const agentRes = await projectTransport.requestJson({
+        method: "POST",
+        path: "/api/v1/agents",
+        body: { name: agentName },
+    });
+    if (!agentRes.ok) {
+        const err = agentRes.error;
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else {
+            r.error(err.message);
+            r.warn("Agent creation requires a project API key with scope project:agent.");
+        }
+        return exitCodeForError(err);
+    }
+    const agent = { id: agentRes.data.id, name: agentRes.data.name };
+    // Optional start.
+    let startMeta;
+    if (startAgent) {
+        const startRes = await projectTransport.requestJson({
+            method: "POST",
+            path: `/api/v1/agents/${agent.id}/start`,
+        });
+        if (!startRes.ok) {
+            const err = startRes.error;
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else {
+                r.error(err.message);
+                r.warn(`You can retry: rooaak agents start --agent-id ${agent.id}`);
+            }
+            return exitCodeForError(err);
+        }
+        startMeta = { status: startRes.status, requestId: startRes.requestId };
+    }
+    const suggestedSessionId = `init_${randomUUID()}`;
+    let messageId = null;
+    let messageSessionId = null;
+    let messageStatus = "skipped";
+    let messageResponse = null;
+    let waitedMs = null;
+    let sendMeta;
+    // Send a test message only when startup is enabled.
+    if (startAgent) {
+        messageSessionId = suggestedSessionId;
+        const sendRes = await projectTransport.requestJson({
+            method: "POST",
+            path: `/api/v1/agents/${agent.id}/messages`,
+            body: { sessionId: messageSessionId, message: testMessage },
+        });
+        if (!sendRes.ok) {
+            const err = sendRes.error;
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else {
+                r.error(err.message);
+                r.warn("Message sending requires a project API key with scope project:message.");
+            }
+            return exitCodeForError(err);
+        }
+        sendMeta = { status: sendRes.status, requestId: sendRes.requestId };
+        const sendData = sendRes.data;
+        if (!isPlainObject(sendData) || typeof sendData.messageId !== "string") {
+            const err = normalizeInitError({
+                code: "server.invalid_response",
+                message: "Server returned an unexpected message response.",
+                meta: { status: sendRes.status, requestId: sendRes.requestId },
+            });
+            if (ctx.flags.json)
+                r.json(toJsonErrorEnvelope(err));
+            else
+                r.error(err.message);
+            return exitCodeForError(err);
+        }
+        messageId = sendData.messageId;
+        messageStatus = "pending";
+        if (sendData.status === "responded" && typeof sendData.response === "string") {
+            messageStatus = "responded";
+            messageResponse = sendData.response;
+        }
+        else {
+            const waitRes = await waitForMessageResponse({
+                transport: projectTransport,
+                messageId,
+                timeoutMs: waitTimeoutMs,
+            });
+            if (!waitRes.ok) {
+                const err = waitRes.error;
+                if (ctx.flags.json)
+                    r.json(toJsonErrorEnvelope(err));
+                else
+                    r.error(err.message);
+                return waitRes.exit;
+            }
+            if (waitRes.kind === "responded") {
+                messageStatus = "responded";
+                messageResponse = waitRes.message.response ?? null;
+            }
+            else {
+                messageStatus = "timeout";
+                waitedMs = waitRes.waitedMs;
+            }
+        }
+    }
+    const next = {
+        agentStart: `rooaak agents start --agent-id ${agent.id}`,
+        messageSend: `rooaak messages send --agent-id ${agent.id} --session-id ${suggestedSessionId} --message "..."`,
+        ...(messageId ? { messageGet: `rooaak messages get --message-id ${messageId}` } : {}),
+    };
+    const output = {
+        baseUrl,
+        profile: profileName,
+        project: { id: project.id, name: project.name, created: projectRes.created },
+        agent: { id: agent.id, name: agent.name, started: startAgent },
+        message: {
+            id: messageId,
+            sessionId: messageSessionId,
+            status: messageStatus,
+            response: messageResponse,
+            ...(messageStatus === "timeout" ? { waitedMs } : {}),
+        },
+        next,
+    };
+    if (ctx.flags.json) {
+        // Use the final API request metadata if we have it; otherwise fall back to prior successful requests.
+        const meta = sendMeta ?? startMeta ?? { status: agentRes.status, requestId: agentRes.requestId };
+        r.json(toJsonOkEnvelope(output, meta));
+        return ExitCode.Success;
+    }
+    r.text(`Project: ${project.name} (${project.id})`);
+    r.text(`Profile saved: '${profileName}'`);
+    r.text(`Agent: ${agent.name} (${agent.id})`);
+    if (messageStatus === "responded") {
+        r.text("");
+        r.text("First response:");
+        r.text(messageResponse ?? "");
+    }
+    else if (messageStatus === "timeout") {
+        r.text("");
+        r.warn(`Message is still pending after waiting ${waitTimeoutMs}ms. It may finish shortly.`);
+        if ("messageGet" in output.next)
+            r.warn(`Check status: ${output.next.messageGet}`);
+    }
+    else if (messageStatus === "skipped") {
+        r.text("");
+        r.text("Skipped first message because agent startup was disabled.");
+        r.text(`Start later: ${output.next.agentStart}`);
+    }
+    r.text("");
+    r.text("Next steps:");
+    r.text(`  ${output.next.agentStart}`);
+    r.text(`  ${output.next.messageSend}`);
+    if ("messageGet" in output.next)
+        r.text(`  ${output.next.messageGet}`);
+    return ExitCode.Success;
+}