@enter-pro/enter-cli 0.4.0 → 0.4.2

package/dist/commands/thread.js

@@ -1,10 +1,16 @@
 import { Command } from "commander";
+import { setTimeout as delay } from "node:timers/promises";
 import { writeFileSync, readFileSync } from "fs";
 import * as client from "../client.js";
-import { print, printMessage, printResult, printTable, pickList, getFormat } from "../output.js";
+import { print, printMessage, printResult, printTable, pick, pickList, getFormat } from "../output.js";
 import { pollUntil, TimeoutError } from "../poll.js";
 import { resolveLifecycleStatus } from "../lifecycle.js";
+import { ThreadEvents, isStateEvent } from "../thread-events.js";
+import { safeOutput } from "../safe-output.js";
+import { errorEnvelope } from "../errors.js";
+import { registerThreadTasks } from "./thread-tasks.js";
 export const threadCmd = new Command("thread").description("Manage project threads and chat");
+registerThreadTasks(threadCmd);
 // A turn has reached a terminal state when it appears in this set; everything
 // else (running/pending/queued/agent_start/agent_running/...) means in-flight.
 const TERMINAL_TURN_STATUSES = new Set(["completed", "cancelled", "error", "failed"]);
@@ -21,22 +27,45 @@ function normalizeAction(raw) {
         updated_at: String(raw.updated_at ?? raw.UpdatedAt ?? ""),
     };
 }
-async function loadToolCallArgs(projectId, action, toolName) {
+async function loadToolCallArgs(projectId, action, toolName, context = {}) {
     const turn = String(action.turn);
-    const data = await client.get(`/v1/projects/${projectId}/thread/messages`, { start_turn: turn, end_turn: turn });
+    const data = await (context.messages ??= client.get(`/v1/projects/${projectId}/thread/messages`, { start_turn: turn, end_turn: turn }, context.signal));
+    // Prefer completed arguments, but cards can exist before tool_call_end.
+    // Stream deltas may split JSON across tool_call_arguments events.
+    const candidates = new Map();
+    const names = new Map();
     for (const e of data.messages ?? []) {
-        if (e.message_type !== "tool_call_end")
+        const type = String(e.message_type ?? "");
+        if (!["tool_call_start", "tool_call_arguments", "tool_call_arguments_start", "tool_call_arguments_delta", "tool_call_arguments_end", "tool_call_end"].includes(type))
             continue;
-        const detail = e.detail?.tool_call_end;
-        if (!detail || detail.tool_name !== toolName)
+        const detail = e.detail?.[type];
+        if (!detail)
             continue;
-        // When the action carries a tool_call_id, prefer the matching event so we
-        // don't pick up a stale invocation from an earlier round in the same turn.
-        if (action.tool_call_id && detail.tool_call_id !== action.tool_call_id)
+        const callId = String(detail.tool_call_id ?? "");
+        if (detail.tool_name)
+            names.set(callId, String(detail.tool_name));
+        if (names.get(callId) !== toolName && !(action.tool_call_id && action.tool_call_id === callId && !detail.tool_name))
             continue;
-        const raw = String(detail.full_arguments ?? "");
+        if (action.tool_call_id && callId !== action.tool_call_id)
+            continue;
+        const raw = String(detail.full_arguments ?? detail.accumulated_arguments ?? detail.arguments_delta ?? detail.arguments ?? detail.tool_call_args ?? "");
+        if (!raw)
+            continue;
+        if (detail.full_arguments !== undefined || detail.accumulated_arguments !== undefined)
+            candidates.set(callId, raw);
+        else if (type === "tool_call_arguments" || type === "tool_call_arguments_delta" || detail.arguments_delta !== undefined)
+            candidates.set(callId, (candidates.get(callId) ?? "") + raw);
+        else
+            candidates.set(callId, raw);
+    }
+    if (candidates.size > 1 && !action.tool_call_id)
+        return { kind: "not_found" };
+    for (const raw of candidates.values()) {
         try {
-            return { kind: "ok", value: JSON.parse(raw) };
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return { kind: "parse_error", raw_arguments: "Expected an argument object" };
+            return { kind: "ok", value: parsed };
         }
         catch {
             return { kind: "parse_error", raw_arguments: raw };
@@ -51,8 +80,8 @@ const TOOL_HANDLERS = {
         kind: "questions",
         approveSuffix: (pid, a) => `--answers '<json>' OR enter-cli thread approve ${pid} ${a.action_id} --skip-answers`,
         instructions: "Questions are included in this action's `questions` field. Forward each question (with its options and multiSelect) to the user, collect answers, then run approve_command --answers '<json>' (or --skip-answers).",
-        enrich: async (projectId, action) => {
-            const args = await loadToolCallArgs(projectId, action, "ask_user_question");
+        enrich: async (projectId, action, context) => {
+            const args = await loadToolCallArgs(projectId, action, "ask_user_question", context);
             switch (args.kind) {
                 case "ok":
                     return { questions: args.value.questions ?? [] };
@@ -65,13 +94,24 @@ const TOOL_HANDLERS = {
     },
     supabase_add_secret: {
         kind: "secret",
-        approveSuffix: () => `--secret-name <NAME> --secret-value <VALUE>`,
-        instructions: "Ask the user for the secret name and value, then substitute into approve_command.",
+        approveSuffix: () => `--secret-name <NAME> --secret-value-stdin`,
+        instructions: "Use a secure input surface for the secret name and value; direct CLI callers can use stdin. Never request or echo credentials in ordinary chat.",
+    },
+    supabase_configure_auth_provider: {
+        kind: "auth_provider",
+        approveSuffix: () => "",
+        instructions: "Configure the requested provider through Enter's secure form, then approve. For direct CLI use, --auth-config-stdin accepts provider configuration JSON through stdin. Never collect credentials in ordinary chat. Approval verifies saved configuration with the backend.",
+        enrich: async (projectId, action, context) => ({ provider: await authProviderFor(projectId, action, context) }),
     },
     stripe_enable: {
         kind: "secret",
-        approveSuffix: () => `--secret-name STRIPE_SECRET_KEY --secret-value <sk_...>`,
-        instructions: "Ask the user for the secret name and value, then substitute into approve_command.",
+        approveSuffix: () => `--secret-value-stdin`,
+        instructions: "Use a secure input surface or direct CLI stdin for the Stripe key. Never request credentials in ordinary chat.",
+    },
+    stripe_update_key_and_migrate: {
+        kind: "secret",
+        approveSuffix: () => `--secret-value-stdin`,
+        instructions: "Product IDs come from the pending tool call. Supply the new Stripe key through a secure input surface or direct CLI stdin, never ordinary chat.",
     },
     // confirm_plan_mode: surface the plan text directly on the action so callers
     // don't have to fetch + parse thread messages themselves.
@@ -79,8 +119,8 @@ const TOOL_HANDLERS = {
         kind: "none",
         approveSuffix: () => "",
         instructions: "Plan is included in this action's `plan` field. Show it to the user, then run approve_command.",
-        enrich: async (projectId, action) => {
-            const args = await loadToolCallArgs(projectId, action, "confirm_plan_mode");
+        enrich: async (projectId, action, context) => {
+            const args = await loadToolCallArgs(projectId, action, "confirm_plan_mode", context);
             switch (args.kind) {
                 case "ok": {
                     const v = args.value;
@@ -102,8 +142,42 @@ const TOOL_HANDLERS = {
 const DEFAULT_HANDLER = {
     kind: "none",
     approveSuffix: () => "",
-    instructions: "No input required. Run the approve_command as-is.",
+    instructions: "No additional input required. Approve only within the user-authorized scope; input_kind none does not itself grant authorization.",
 };
+const FEATURE_ENABLE_ROUTES = new Map([
+    ["supabase_enable", "entercloud/enable"],
+    ["enable_analytics", "analytics/enable"],
+    ["i18n_enable", "i18n/enable"],
+    ["enable_ai_capability", "ai-capability/connect"],
+]);
+const AUTH_PROVIDER_FIELDS = {
+    google: ["enabled", "client_ids", "client_secret", "skip_nonce_checks"],
+    wechat: ["enabled", "client_id", "client_secret"],
+    alipay: ["enabled", "app_id", "private_key"],
+    feishu: ["enabled", "app_id", "app_secret"],
+};
+async function authProviderFor(projectId, action, context = {}) {
+    if (!action.tool_call_id)
+        throw new Error("Auth provider action is missing its tool_call_id");
+    const args = await loadToolCallArgs(projectId, action, action.tool_name, context);
+    const provider = args.kind === "ok" ? args.value?.provider : undefined;
+    if (typeof provider !== "string" || !Object.hasOwn(AUTH_PROVIDER_FIELDS, provider)) {
+        throw new Error("Unable to resolve the requested auth provider from the matching tool call");
+    }
+    return provider;
+}
+function parseObjectJSON(value, option) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${option} must contain a JSON object`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error(`${option} must contain a JSON object`);
+    return parsed;
+}
 function handlerFor(toolName) {
     return TOOL_HANDLERS[toolName] ?? DEFAULT_HANDLER;
 }
@@ -112,21 +186,31 @@ function buildApproveCommand(projectId, action) {
     const suffix = handlerFor(action.tool_name).approveSuffix(projectId, action);
     return suffix ? `${base} ${suffix}` : base;
 }
-async function fetchPendingActions(projectId) {
-    const data = await client.post(`/v1/projects/${projectId}/thread/actions`, {});
+async function fetchPendingActions(projectId, actionIds = [], signal) {
+    return (await fetchActions(projectId, actionIds, signal)).filter((a) => a.status === "waiting_response");
+}
+async function fetchActions(projectId, actionIds = [], signal) {
+    const body = actionIds.length > 0 ? { actions: actionIds } : {};
+    const data = await client.post(`/v1/projects/${projectId}/thread/actions`, body, signal);
     const resp = data;
-    const all = (resp.actions || []).map(normalizeAction);
-    return all.filter((a) => a.status === "waiting_response");
+    return (resp.actions || []).map(normalizeAction);
 }
 threadCmd
     .command("chat <project_id>")
-    .description("Send a chat message to project thread")
+    .description("Submit a message immediately, including while a turn is running. Enter may queue a new turn or interject into the active turn; accepted does not mean applied.")
     .option("-m, --message <text>", "Chat message content")
     .option("--file <path>", "Read message content from a file (for long or multi-line messages)")
+    .option("--stdin", "Read message from stdin, avoiding shell quoting and process arguments")
+    .option("--chat-id <id>", "Target a specific chat")
     .option("--auto-approve", "Pass auto_approve flag to the server")
     .action(async (id, opts, cmd) => {
     let content;
-    if (opts.file) {
+    if ([opts.file !== undefined, opts.message !== undefined, Boolean(opts.stdin)].filter(Boolean).length !== 1)
+        throw new Error("Provide exactly one of --message, --file or --stdin");
+    if (opts.stdin) {
+        content = readFileSync(0, "utf-8");
+    }
+    else if (opts.file) {
         content = readFileSync(opts.file, "utf-8");
     }
     else if (opts.message) {
@@ -136,11 +220,19 @@ threadCmd
         console.error("Error: either -m <text> or --file <path> is required");
         process.exit(1);
     }
+    if (!content.trim())
+        throw new Error("Message must not be empty");
     const body = { prompt: content, attachments: [] };
     if (opts.autoApprove)
         body.auto_approve = true;
+    if (opts.chatId)
+        body.chat_id = opts.chatId;
     const data = await client.post(`/v1/projects/${id}/thread/chat`, body);
-    print(getFormat(cmd), data);
+    print(getFormat(cmd), {
+        ...data,
+        submission_status: "accepted",
+        ...threadInteraction(id, { taskId: String(data.task_id ?? ""), chatId: opts.chatId }),
+    });
 });
 threadCmd
     .command("messages <project_id>")
@@ -150,7 +242,11 @@ threadCmd
     .option("--turn <n>", "Get messages for a specific turn (shorthand for --start-turn N --end-turn N)")
     .option("--latest", "Get messages from the most recent turn (most common usage)")
     .option("--tail <n>", "Get messages from the last N turns")
-    .option("--follow", "Follow the latest turn in real-time via WebSocket")
+    .option("--follow", "Stream NDJSON events over WebSocket; no automatic approval")
+    .option("--cursor <id>", "Resume after a previously returned event ID")
+    .option("--chat-id <id>", "Scope the stream to a chat")
+    .option("--timeout <seconds>", "Bound --follow lifetime", "60")
+    .option("--max-events <n>", "Stop --follow after N events")
     .action(async (id, opts, cmd) => {
     if (opts.follow) {
         await followThreadStream(id, opts);
@@ -197,66 +293,45 @@ threadCmd
     const data = await client.get(`/v1/projects/${id}/thread/messages`, params);
     print(getFormat(cmd), data);
 });
-async function followThreadStream(projectId, _opts) {
-    const wsBase = (await import("../config.js")).baseURL()
-        .replace(/^https?:\/\//, "ws://")
-        .replace(/^wss?:\/\//, "ws://");
-    const { getToken } = await import("../auth.js");
-    const url = `${wsBase}/v1/projects/${projectId}/thread/stream`;
-    const token = getToken();
-    // Use native WebSocket available in Node 22+ or ws package fallback
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let WS;
+async function followThreadStream(projectId, opts) {
+    const timeout = positiveNumber(opts.timeout ?? "60", "--timeout") * 1000;
+    if (timeout > 2147483647)
+        throw new Error("--timeout is too large");
+    const turn = opts.turn ? positiveNumber(opts.turn, "--turn", true) : undefined;
+    if (opts.cursor && !/^\d+-\d+$/.test(opts.cursor))
+        throw new Error("--cursor must be an event ID such as 123-0");
+    const maxEvents = opts.maxEvents ? positiveNumber(opts.maxEvents, "--max-events", true) : Infinity;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    const abort = () => controller.abort();
+    process.once("SIGINT", abort);
+    process.once("SIGTERM", abort);
+    let count = 0;
+    let stream;
     try {
-        WS = WebSocket;
-    }
-    catch {
-        try {
-            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-            // @ts-ignore -- optional peer dependency
-            const mod = await import("ws");
-            WS = mod.default;
-        }
-        catch {
-            console.error("Error: WebSocket not available. Node 22+ required or install 'ws' package.");
-            process.exit(1);
+        stream = new ThreadEvents(projectId, {
+            signal: controller.signal, turn,
+            chatId: opts.chatId, cursor: opts.cursor,
+            onMode: mode => console.error(`[events] ${mode}`),
+            onEvent: event => {
+                process.stdout.write(JSON.stringify(safeOutput(event)) + "\n");
+                if (++count >= maxEvents)
+                    controller.abort();
+            },
+        });
+        while (!controller.signal.aborted) {
+            if (stream.failure)
+                throw stream.failure;
+            await stream.wait(stream.revision, Math.min(timeout, 30000));
         }
     }
-    const wsUrl = token ? `${url}?token=${encodeURIComponent(token)}` : url;
-    const ws = new WS(wsUrl, {
-        headers: token ? { Authorization: `Bearer ${token}` } : {},
-    });
-    const terminalTypes = new Set([
-        "turn_end", "turn_cancelled", "turn_error", "build_end",
-    ]);
-    let connected = false;
-    ws.on("open", () => {
-        connected = true;
-        console.error("[follow] WebSocket connected, streaming messages...");
-    });
-    ws.on("message", (data) => {
-        try {
-            const msg = JSON.parse(data.toString());
-            process.stdout.write(JSON.stringify(msg) + "\n");
-            if (typeof msg.message_type === "string" && terminalTypes.has(msg.message_type)) {
-                console.error(`[follow] Turn ended (${msg.message_type}), closing.`);
-                ws.close();
-            }
-        }
-        catch {
-            process.stdout.write(data.toString() + "\n");
-        }
-    });
-    ws.on("error", (err) => {
-        console.error(`[follow] WebSocket error: ${err.message}`);
-        if (!connected)
-            process.exit(1);
-    });
-    ws.on("close", () => {
-        console.error("[follow] Connection closed.");
-    });
-    // Keep process alive until ws closes
-    await new Promise((resolve) => ws.on("close", resolve));
+    finally {
+        stream?.close();
+        clearTimeout(timer);
+        process.removeListener("SIGINT", abort);
+        process.removeListener("SIGTERM", abort);
+        console.error(`[events] stopped; events=${count}; cursor=${stream?.cursor ?? "none"}; reason=${stream?.reason ?? "observation_ended"}`);
+    }
 }
 threadCmd
     .command("turns <project_id>")
@@ -266,7 +341,7 @@ threadCmd
     const data = await client.get(`/v1/projects/${id}/thread/turns`);
     const resp = data;
     const turns = resp.turns || [];
-    const items = opts.latest ? turns.slice(-1) : turns;
+    const items = opts.latest ? turns.slice(0, 1) : turns;
     const picked = pickList(items, [
         "id", "turn", "turn_name", "status", "model", "credits_consumed", "created_at",
     ]);
@@ -285,96 +360,230 @@ threadCmd
     ]);
     printTable(["Turn", "Name", "Status", "Model", "Credits", "Created"], rows);
 });
-threadCmd
-    .command("wait <project_id>")
-    .description("Wait until the latest turn reaches a terminal state. Exits with status: completed | blocked | failed.")
-    .option("--timeout <seconds>", "Timeout in seconds", "300")
-    .action(async (id, opts, cmd) => {
-    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
-    console.error("Waiting for turn to complete...");
-    let lastTurn = null;
-    try {
-        const turns = await pollUntil(async () => {
-            const data = await client.get(`/v1/projects/${id}/thread/turns`);
-            const resp = data;
-            return resp.turns || [];
-        }, (turns) => {
-            if (turns.length === 0)
-                return false;
-            // turns are returned newest-first.
-            const latest = turns[0];
-            return TERMINAL_TURN_STATUSES.has(String(latest.status));
-        }, {
-            intervalMs: 2000,
-            timeoutMs,
-            onTick: (elapsed) => {
-                process.stderr.write(`\rWaiting for turn... ${Math.round(elapsed / 1000)}s elapsed`);
-            },
-        });
-        process.stderr.write("\n");
-        lastTurn = turns[0] ?? null;
+export function threadInteraction(id, { taskId, chatId, turn, requireBuild } = {}) {
+    const target = (taskId ? ` --task-id ${taskId}` : turn === undefined ? "" : ` --turn ${turn}`)
+        + (chatId ? ` --chat-id ${chatId}` : "") + (requireBuild ? " --require-build" : "");
+    return {
+        monitoring_required: true,
+        wait_command: `enter-cli --output json thread wait ${id}${target}`,
+        watch_command: `enter-cli thread watch ${id}${target}`,
+        status_command: `enter-cli --output json thread status ${id}${target}`,
+        follow_up_command: `enter-cli --output json thread chat ${id}${chatId ? ` --chat-id ${chatId}` : ""} --file <message-file>`,
+        instructions: "Accepted or timeout is not completion. Follow this task until blocked, failed or completed. Forward questions unchanged; approve only within existing authorization. Watching never approves or cancels remote work. Hosts own background scheduling.",
+    };
+}
+function positiveNumber(value, option, integer = false) {
+    const number = Number(value);
+    if (!Number.isFinite(number) || number <= 0 || (integer && !Number.isSafeInteger(number))) {
+        throw new Error(`${option} must be a positive ${integer ? "integer" : "number"}`);
     }
-    catch (err) {
-        if (err instanceof TimeoutError) {
-            console.error(`\nTimed out after ${opts.timeout}s waiting for the turn to terminate`);
-            process.exit(1);
-        }
-        throw err;
+    return number;
+}
+async function readThreadSnapshot(id, turnNumber, signal, taskId, chatId) {
+    const data = await client.get(`/v1/projects/${id}/thread/turns`, chatId ? { chat_id: chatId } : undefined, signal);
+    const turns = data.turns ?? [];
+    const selected = taskId ? turns.find(t => t.id === taskId || t.task_id === taskId)
+        : turnNumber === undefined ? turns[0] : turns.find(t => Number(t.turn) === turnNumber);
+    if (!selected && taskId) {
+        const queue = await client.get(`/v1/projects/${id}/thread/tasks`, { simple: "true", ...(chatId ? { chat_id: chatId } : {}) }, signal);
+        return { status: queue.task_ids?.includes(taskId) ? "queued" : "unknown", project_id: id, turn: null,
+            reason: queue.task_ids?.includes(taskId) ? "task_queued" : "task_not_observed",
+            ...(!queue.task_ids?.includes(taskId) ? {
+                correlation: "unavailable",
+                project_activity: turns[0] ? pick(turns[0], ["id", "turn", "status", "chat_id", "commit_id"]) : null,
+                project_status_command: `enter-cli --output json thread status ${id}${chatId ? ` --chat-id ${chatId}` : ""}`,
+                message: "This ID may be an interjection rather than a queued task. Project activity is separate and does not prove this submission was applied. Inspect thread messages and the resulting change; do not resubmit blindly.",
+            } : {}) };
     }
-    const turnStatus = String(lastTurn?.status ?? "");
-    if (turnStatus === "cancelled" || turnStatus === "error") {
-        print(getFormat(cmd), {
-            status: "failed",
-            reason: `turn_${turnStatus}`,
-            project_id: id,
-            turn: lastTurn,
-        });
-        process.exit(1);
+    if (!selected) {
+        return { status: turnNumber === undefined ? "idle" : "unknown", reason: turnNumber === undefined ? "no_turns" : "turn_not_found", project_id: id, turn: null };
+    }
+    const base = { project_id: id, turn: selected };
+    const status = String(selected.status ?? "");
+    if (["cancelled", "error", "failed"].includes(status)) {
+        return { ...base, status: "failed", reason: `turn_${status}` };
     }
-    // Turn is completed — but a "completed" turn can still be blocked
-    // by a pending tool action. Check actions exactly once now.
-    const pending = await fetchPendingActions(id);
-    if (pending.length > 0) {
-        const enriched = await Promise.all(pending.map(async (a) => {
+    const pending = (await fetchPendingActions(id, [], signal)).filter(a => String(a.turn) === String(selected.turn));
+    if (pending.length) {
+        const context = { signal };
+        const actions = await Promise.all(pending.map(async (a) => {
             const handler = handlerFor(a.tool_name);
-            const base = {
-                action_id: a.action_id,
-                tool_name: a.tool_name,
-                turn: a.turn,
-                input_kind: handler.kind,
-                approve_command: buildApproveCommand(id, a),
-                instructions: handler.instructions,
+            const result = {
+                action_id: a.action_id, tool_name: a.tool_name, turn: a.turn,
+                input_kind: handler.kind, approve_command: buildApproveCommand(id, a), instructions: handler.instructions,
             };
-            if (!handler.enrich)
-                return base;
-            try {
-                const extra = await handler.enrich(id, a);
-                return { ...base, ...extra };
-            }
-            catch (err) {
-                return { ...base, enrich_error: err.message };
+            if (handler.enrich) {
+                try {
+                    Object.assign(result, await handler.enrich(id, a, context));
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        throw error;
+                    result.enrich_error = error.message;
+                }
             }
+            return result;
         }));
-        print(getFormat(cmd), {
-            status: "blocked",
-            reason: "pending_actions",
-            project_id: id,
-            actions: enriched,
-        });
-        return;
+        return { ...base, status: "blocked", reason: "pending_actions", actions };
     }
-    // Turn done, no gate. Return current project snapshot. Note: a completed
-    // turn may not produce a commit (e.g. config-only changes), so we do not
-    // wait for build_status.commit_id here. Callers that need a committed
-    // build (e.g. `proj publish`) check that themselves.
-    const detail = await client.get(`/v1/projects/${id}/detail`);
+    if (status !== "completed")
+        return { ...base, status: status ? "running" : "unknown" };
+    const detail = await client.get(`/v1/projects/${id}/detail`, undefined, signal);
     const project = (detail.project ?? detail);
-    print(getFormat(cmd), {
-        status: "completed",
-        project_id: id,
-        project: { ...project, lifecycle_status: resolveLifecycleStatus(project) },
+    // This is turn completion. Project build state remains separate and may refer
+    // to an earlier build; callers must not interpret it as this turn's build ID.
+    return { ...base, status: "completed", project: { ...project, lifecycle_status: resolveLifecycleStatus(project) } };
+}
+function projectSnapshot(snapshot, compact = false) {
+    const result = { ...snapshot };
+    if (compact && snapshot.turn)
+        result.turn = pick(snapshot.turn, ["id", "turn", "status", "turn_name", "created_at", "updated_at", "commit_id", "chat_id"]);
+    if (snapshot.project) {
+        const p = snapshot.project;
+        if (compact)
+            result.project = pick(p, ["project_id", "name", "status", "lifecycle_status", "commit", "commit_turn", "preview_url", "publish_url", "build_status"]);
+        const build = p.build_status;
+        result.build_matches_turn = Boolean(snapshot.turn?.commit_id && build?.commit_id === snapshot.turn.commit_id);
+        const supabase = p.supabase;
+        result.integrations = { cloud: supabase?.status ?? "unknown", ai: p.ai_connection_state ?? (p.ai_capability_enabled === true ? "enabled" : "unknown") };
+    }
+    return result;
+}
+// Owns observation and lifetime only; callers choose JSON or NDJSON rendering.
+async function observeThread(id, opts, wait, onSnapshot) {
+    let target = opts.turn === undefined ? undefined : positiveNumber(opts.turn, "--turn", true);
+    if (opts.taskId && target !== undefined)
+        throw new Error("Use only one of --task-id and --turn");
+    if (opts.transport && !["auto", "poll"].includes(opts.transport))
+        throw new Error("--transport must be auto or poll");
+    if (opts.cursor && !/^\d+-\d+$/.test(opts.cursor))
+        throw new Error("--cursor must be an event ID such as 123-0");
+    const timeoutMs = positiveNumber(opts.timeout, "--timeout") * 1000;
+    if (timeoutMs > 2147483647)
+        throw new Error("--timeout is too large");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const interrupt = () => controller.abort("SIGINT");
+    const terminate = () => controller.abort("SIGTERM");
+    process.once("SIGINT", interrupt);
+    process.once("SIGTERM", terminate);
+    let last = { status: "unknown", project_id: id, turn: null };
+    let querying = false;
+    let stream;
+    let reconcileUntil = 0;
+    const emit = (extra = {}, final = false) => onSnapshot({
+        ...last,
+        ...(["idle", "running", "queued", "pending", "unknown"].includes(last.status)
+            ? threadInteraction(id, { taskId: opts.taskId, chatId: opts.chatId, turn: target, requireBuild: opts.requireBuild }) : {}),
+        ...(opts.taskId ? { task_id: opts.taskId } : {}),
+        ...(stream ? { transport: stream.mode, transport_reason: stream.reason, cursor: stream.cursor } : {}), ...extra,
+    }, final);
+    const interruption = () => {
+        const reason = controller.signal.reason;
+        if (reason !== "SIGINT" && reason !== "SIGTERM")
+            return undefined;
+        emit({ interrupted: true, signal: reason }, true);
+        return reason === "SIGINT" ? 130 : 143;
+    };
+    try {
+        while (!controller.signal.aborted) {
+            if (stream?.failure)
+                throw stream.failure;
+            const revision = stream?.revision ?? 0;
+            querying = true;
+            last = await readThreadSnapshot(id, target, controller.signal, opts.taskId, opts.chatId);
+            if (opts.requireBuild && last.status === "completed") {
+                const build = last.project?.build_status;
+                const matches = Boolean(last.turn?.commit_id && build?.commit_id === last.turn.commit_id);
+                if (!matches || typeof build?.success !== "boolean")
+                    last = { ...last, status: "running", reason: "awaiting_matching_build" };
+                else if (build?.success === false)
+                    last = { ...last, status: "failed", reason: "build_failed" };
+            }
+            querying = false;
+            if (target === undefined && last.turn && !opts.taskId)
+                target = positiveNumber(String(last.turn.turn), "server turn", true);
+            // A newly accepted task can be temporarily absent from both reads. Keep
+            // bounded observation alive without claiming it is pending or failed.
+            const unobservedTask = last.status === "unknown" && last.reason === "task_not_observed";
+            if (!wait || (!unobservedTask && !["running", "idle", "queued", "pending"].includes(last.status))) {
+                emit({}, true);
+                return last.status === "failed" || last.status === "unknown" ? 1 : 0;
+            }
+            if (!stream && opts.transport !== "poll") {
+                stream = new ThreadEvents(id, {
+                    signal: controller.signal, turn: target ?? (last.turn ? Number(last.turn.turn) : undefined),
+                    chatId: opts.chatId ?? last.turn?.chat_id, cursor: opts.cursor, stateOnly: true,
+                    onEvent: event => { if (isStateEvent(event))
+                        reconcileUntil = Date.now() + 1500; },
+                });
+            }
+            emit();
+            if (stream)
+                await stream.wait(revision, Date.now() < reconcileUntil ? 250 : stream.mode === "websocket" ? 30000 : 2000);
+            else
+                await delay(2000, undefined, { signal: controller.signal });
+        }
+        const interrupted = interruption();
+        if (interrupted !== undefined)
+            return interrupted;
+        emit({ wait_timed_out: true, query_timed_out: false }, true);
+        return 2;
+    }
+    catch (error) {
+        const interrupted = interruption();
+        if (interrupted !== undefined)
+            return interrupted;
+        if (!controller.signal.aborted) {
+            emit({ ...errorEnvelope(error), last_observed: true }, true);
+            return 1;
+        }
+        emit({ wait_timed_out: wait, query_timed_out: querying, ...(querying ? { error: { code: "QUERY_TIMEOUT", retryable: true, outcome_unknown: false } } : {}) }, true);
+        return wait && !querying ? 2 : 1;
+    }
+    finally {
+        stream?.close();
+        clearTimeout(timer);
+        process.removeListener("SIGINT", interrupt);
+        process.removeListener("SIGTERM", terminate);
+    }
+}
+export async function reportThread(id, opts, cmd, wait, watch = false) {
+    if (opts.full && opts.compact)
+        throw new Error("Use only one of --full and --compact");
+    let signature = "";
+    process.exitCode = await observeThread(id, opts, wait, (snapshot, final) => {
+        const data = projectSnapshot(snapshot, !opts.full && (opts.compact || watch));
+        if (!watch) {
+            if (final)
+                print(getFormat(cmd), safeOutput(data));
+            return;
+        }
+        // Cursor-only changes should not flood agents with identical snapshots.
+        const next = JSON.stringify({ ...data, cursor: undefined });
+        if (next !== signature || final) {
+            process.stdout.write(JSON.stringify(safeOutput({ type: final ? "result" : "snapshot", ...data })) + "\n");
+            signature = next;
+        }
     });
-});
+}
+for (const [name, timeout, description] of [
+    ["status", "30", "Read one task snapshot; never wait for completion"],
+    ["wait", "10", "Wait for an action or terminal state using events with polling fallback"],
+    ["watch", "60", "Stream meaningful state changes as NDJSON; exit on pending actions or terminal state"],
+]) {
+    threadCmd.command(`${name} <project_id>`).description(description)
+        .option("--turn <n>", "Select a fixed turn number")
+        .option("--task-id <id>", "Follow exactly the task returned by chat/approve, including queue time")
+        .option("--chat-id <id>", "Scope turn lookup and events to a chat")
+        .option("--cursor <id>", "Resume stream after an event ID")
+        .option("--transport <mode>", "auto: WebSocket with fallback; poll: HTTP only", "auto")
+        .option("--require-build", "Require a matching successful build before reporting completion")
+        .option("--compact", "Return only monitoring fields (default for watch)")
+        .option("--full", "Include full sanitized metadata (default for status/wait)")
+        .option("--timeout <seconds>", "Bound the entire call without cancelling Enter", timeout)
+        .action(async (id, opts, cmd) => reportThread(id, opts, cmd, name !== "status", name === "watch"));
+}
 threadCmd
     .command("diff <project_id> <turn_number>")
     .description("Get diff for a turn")
@@ -424,12 +633,25 @@ threadCmd
     .description("Restore thread to a specific turn (1-based turn number from `thread turns`)")
     .requiredOption("--turn <n>", "1-based turn number to restore to (NOT a turn UUID)")
     .action(async (id, opts, cmd) => {
-    const turn = parseInt(opts.turn, 10);
-    if (!Number.isFinite(turn) || turn < 1) {
-        throw new Error("--turn must be a positive integer (1-based turn number)");
+    const turn = positiveNumber(opts.turn, "--turn", true);
+    try {
+        const data = await client.post(`/v1/projects/${id}/thread/restore`, { turn });
+        print(getFormat(cmd), data);
+    }
+    catch (error) {
+        print(getFormat(cmd), {
+            ...errorEnvelope(error),
+            project_id: id,
+            requested_turn: turn,
+            restored: "unknown",
+            verification_commands: [
+                `enter-cli --output json thread tasks ${id}`,
+                `enter-cli --output json thread status ${id}`,
+                `enter-cli --output json project get ${id}`,
+            ],
+        });
+        process.exitCode = 1;
     }
-    const data = await client.post(`/v1/projects/${id}/thread/restore`, { turn: turn });
-    print(getFormat(cmd), data);
 });
 threadCmd
     .command("actions <project_id>")
@@ -465,23 +687,27 @@ threadCmd
     ]);
     printTable(["Action ID", "Tool", "Status", "Turn", "Created"], rows);
 });
-async function resolveActionId(projectId, explicit) {
-    if (explicit)
-        return { kind: "ok", action_id: explicit };
-    const pending = await fetchPendingActions(projectId);
+async function resolveAction(projectId, explicit) {
+    const pending = await fetchPendingActions(projectId, explicit ? [explicit] : []);
+    if (explicit) {
+        const action = pending.find((candidate) => candidate.action_id === explicit);
+        if (!action)
+            throw new Error(`Pending action not found: ${explicit}`);
+        return { kind: "ok", action };
+    }
     if (pending.length === 0)
         return { kind: "none", pending };
     if (pending.length > 1)
         return { kind: "ambiguous", pending };
-    return { kind: "ok", action_id: pending[0].action_id };
+    return { kind: "ok", action: pending[0] };
 }
 // Emit a structured no-op result + return null (caller should not call the API),
-// or return the resolved action_id when ok. Exits non-zero on ambiguity since
+// or return the resolved action when ok. Exits non-zero on ambiguity since
 // it's a real error that scripts need to notice.
 function handleResolution(projectId, verb, result, format) {
     switch (result.kind) {
         case "ok":
-            return result.action_id;
+            return result.action;
         case "none": {
             const past = verb === "approve" ? "approved" : "rejected";
             printResult(format, { [past]: false, reason: "no_pending_actions", project_id: projectId }, `Nothing to ${verb} (no pending actions on this project's thread).`);
@@ -517,60 +743,189 @@ threadCmd
     .description([
     "Approve a pending tool action. action_id is optional when exactly one pending action exists.",
     "Tool-specific options:",
-    "  supabase_add_secret : --secret-name <name> --secret-value <value>",
-    "  stripe_enable       : --secret-name STRIPE_SECRET_KEY --secret-value sk_...",
+    "  supabase_add_secret : --secret-name <name> --secret-value-stdin",
+    "  stripe_enable       : --secret-value-stdin",
+    "  stripe_update_key_and_migrate: --secret-value-stdin",
     "  ask_user_question   : --answers '<json>' or --skip-answers",
-    "  others (supabase_enable, stripe_create_products_and_prices,",
-    "          enable_ai_capability, confirm_skill): no extra flags needed",
+    "  supabase_configure_auth_provider: verify saved configuration, or save provider JSON with --auth-config-stdin first",
+    "  feature enable cards: run their dedicated backend flow before resolving the action",
+    "  other actions       : no extra flags unless thread wait says otherwise",
 ].join("\n"))
-    .option("--secret-name <name>", "Secret variable name (supabase_add_secret / stripe_enable)")
-    .option("--secret-value <value>", "Secret variable value (supabase_add_secret / stripe_enable)")
+    .option("--secret-name <name>", "Secret variable name (supabase_add_secret)")
+    .option("--secret-value <value>", "Legacy secret argument; prefer --secret-value-stdin")
+    .option("--secret-value-stdin", "Read the secret value from stdin instead of process arguments")
+    .option("--auth-config-stdin", "Read configuration JSON for the action's auth provider from stdin; credentials never go into the approval response")
     .option("--tool-result <result>", "Custom tool result string")
     .option("--answers <json>", 'Answers for ask_user_question, JSON: \'{"Q text": {"selected_options": ["A"], "other_text": ""}}\'')
     .option("--skip-answers", "Skip all questions for ask_user_question (sets skipped: true)")
     .action(async (projectId, actionIdArg, opts, cmd) => {
     const format = getFormat(cmd);
-    const resolved = await resolveActionId(projectId, actionIdArg);
-    const actionId = handleResolution(projectId, "approve", resolved, format);
-    if (!actionId)
+    const resolved = await resolveAction(projectId, actionIdArg);
+    const action = handleResolution(projectId, "approve", resolved, format);
+    if (!action)
         return;
+    if (opts.secretValue !== undefined && opts.secretValueStdin) {
+        throw new Error("Use only one of --secret-value or --secret-value-stdin");
+    }
+    if (opts.answers !== undefined && opts.skipAnswers)
+        throw new Error("Use only one of --answers or --skip-answers");
+    if (opts.authConfigStdin && action.tool_name !== "supabase_configure_auth_provider")
+        throw new Error("--auth-config-stdin is only supported for auth provider actions");
+    if (action.tool_name === "supabase_configure_auth_provider") {
+        if (opts.secretName !== undefined || opts.secretValue !== undefined || opts.secretValueStdin || opts.toolResult !== undefined || opts.answers !== undefined || opts.skipAnswers) {
+            throw new Error("Auth provider actions do not accept secret, tool-result or question-answer flags; use --auth-config-stdin or Enter's secure form");
+        }
+        const provider = await authProviderFor(projectId, action);
+        const configPath = `/v1/projects/${projectId}/entercloud/auth/config`;
+        if (opts.authConfigStdin) {
+            const config = parseObjectJSON(readFileSync(0, "utf8"), "--auth-config-stdin");
+            for (const key of Object.keys(config)) {
+                if (!AUTH_PROVIDER_FIELDS[provider].includes(key))
+                    throw new Error("Unsupported field in auth provider configuration");
+                if (["enabled", "skip_nonce_checks"].includes(key) ? typeof config[key] !== "boolean" : typeof config[key] !== "string") {
+                    throw new Error("Invalid value type in auth provider configuration");
+                }
+            }
+            if (config.enabled === false)
+                throw new Error("Cannot approve a disabled auth provider");
+            await client.patch(configPath, { providers: { [provider]: { ...config, enabled: true } } });
+        }
+        const data = await client.get(configPath);
+        if (data.config?.providers?.[provider]?.enabled !== true) {
+            throw new Error(`Auth provider ${provider} is not enabled. Configure it through Enter's secure form or --auth-config-stdin before approval.`);
+        }
+        // The backend additionally verifies stored credentials and the card's
+        // ExpectedProvider before claiming the action. Never send credentials here.
+        const result = await client.post(`/v1/projects/${projectId}/thread/chat`, {
+            action_response: { action_id: action.action_id, response: "approved", auth_provider_result: { provider } },
+        });
+        print(format, safeOutput({
+            ...result, approved: true,
+            action_id: action.action_id, tool_name: action.tool_name,
+            ...threadInteraction(projectId, { taskId: String(result.task_id ?? "") }),
+        }));
+        return;
+    }
+    const secretValue = opts.secretValueStdin
+        ? readFileSync(0, "utf8").replace(/\r?\n$/, "")
+        : opts.secretValue;
+    if (action.tool_name === "supabase_add_secret" && (!opts.secretName?.trim() || !secretValue)) {
+        throw new Error("--secret-name and a non-empty --secret-value-stdin (or --secret-value) are required for supabase_add_secret");
+    }
+    if (action.tool_name === "ask_user_question" && opts.answers === undefined && !opts.skipAnswers) {
+        throw new Error("--answers or --skip-answers is required for ask_user_question");
+    }
+    const answers = opts.answers !== undefined ? parseObjectJSON(opts.answers, "--answers") : undefined;
+    if (answers) {
+        for (const answer of Object.values(answers)) {
+            if (!answer || typeof answer !== "object" || Array.isArray(answer))
+                throw new Error("Each answer must be an object");
+            const value = answer;
+            if (!Array.isArray(value.selected_options) || !value.selected_options.every(item => typeof item === "string") || (value.other_text !== undefined && typeof value.other_text !== "string")) {
+                throw new Error("Each answer requires selected_options as a string array and optional other_text as a string");
+            }
+        }
+    }
+    let featureResult;
+    let handledFeature = false;
+    const featureRoute = FEATURE_ENABLE_ROUTES.get(action.tool_name);
+    if (featureRoute) {
+        handledFeature = true;
+        // AI All's legacy default flow requires an absent body. An empty object
+        // is parsed as an explicit request with no mode and rejected by the API.
+        featureResult = await client.post(`/v1/projects/${projectId}/${featureRoute}`, action.tool_name === "enable_ai_capability" ? undefined : {});
+    }
+    else if (action.tool_name === "stripe_enable") {
+        if (!secretValue)
+            throw new Error("--secret-value or --secret-value-stdin is required for stripe_enable");
+        handledFeature = true;
+        featureResult = await client.post(`/v1/projects/${projectId}/connect-stripe`, {
+            stripe_secret_key: secretValue,
+        });
+    }
+    else if (action.tool_name === "stripe_update_key_and_migrate") {
+        if (!secretValue)
+            throw new Error("--secret-value or --secret-value-stdin is required for stripe_update_key_and_migrate");
+        if (!action.tool_call_id)
+            throw new Error("tool_call_id is required for stripe_update_key_and_migrate");
+        const args = await loadToolCallArgs(projectId, action, "stripe_update_key_and_migrate");
+        const productIDs = args.kind === "ok" && args.value !== null && !Array.isArray(args.value)
+            ? args.value.product_ids
+            : undefined;
+        if (!Array.isArray(productIDs) || !productIDs.every((id) => typeof id === "string" && id.trim() !== "")) {
+            throw new Error("Unable to read product_ids from the stripe_update_key_and_migrate action");
+        }
+        const normalizedProductIDs = productIDs.map((id) => id.trim());
+        handledFeature = true;
+        featureResult = await client.post(`/v1/projects/${projectId}/stripe/update-and-migrate`, {
+            new_secret_key: secretValue,
+            product_ids: normalizedProductIDs,
+        });
+    }
+    if (handledFeature) {
+        const confirmation = AbortSignal.timeout(10000);
+        let actions;
+        try {
+            actions = await pollUntil(() => fetchActions(projectId, [action.action_id], confirmation), (items) => {
+                const candidate = items.find((item) => item.action_id === action.action_id);
+                return candidate !== undefined && candidate.status !== "waiting_response";
+            }, { intervalMs: 250, timeoutMs: 10000 });
+        }
+        catch (error) {
+            if (error instanceof TimeoutError || confirmation.aborted) {
+                throw new Error(`Feature flow completed but action status is still pending: ${action.action_id}. Do not retry automatically.`);
+            }
+            throw error;
+        }
+        const resolvedAction = actions.find((candidate) => candidate.action_id === action.action_id);
+        if (resolvedAction?.status !== "approved") {
+            throw new Error(`Dedicated feature flow did not approve action: ${action.action_id} (${resolvedAction?.status ?? "missing"})`);
+        }
+        print(format, safeOutput({
+            ...(featureResult && typeof featureResult === "object" ? featureResult : { result: featureResult }),
+            approved: true, action_id: action.action_id, tool_name: action.tool_name,
+            ...threadInteraction(projectId),
+        }));
+        return;
+    }
     const actionResponse = {
-        action_id: actionId,
+        action_id: action.action_id,
         response: "approved",
     };
     if (opts.secretName)
         actionResponse.secret_name = opts.secretName;
-    if (opts.secretValue)
-        actionResponse.secret_value = opts.secretValue;
+    if (secretValue)
+        actionResponse.secret_value = secretValue;
     if (opts.toolResult)
         actionResponse.tool_result = opts.toolResult;
     if (opts.skipAnswers) {
         actionResponse.question_answers = { answers: {}, skipped: true };
     }
-    else if (opts.answers) {
-        try {
-            const parsed = JSON.parse(opts.answers);
-            actionResponse.question_answers = { answers: parsed, skipped: false };
-        }
-        catch {
-            console.error("Error: --answers must be valid JSON");
-            process.exit(1);
-        }
+    else if (answers) {
+        actionResponse.question_answers = { answers, skipped: false };
     }
     const data = await client.post(`/v1/projects/${projectId}/thread/chat`, {
         action_response: actionResponse,
     });
-    print(format, data);
+    print(format, safeOutput({
+        ...data, approved: true,
+        action_id: action.action_id, tool_name: action.tool_name,
+        ...threadInteraction(projectId, { taskId: String(data.task_id ?? "") }),
+    }));
 });
 threadCmd
     .command("reject <project_id> [action_id]")
     .description("Reject a pending tool action. action_id is optional when exactly one pending action exists.")
     .action(async (projectId, actionIdArg, _opts, cmd) => {
     const format = getFormat(cmd);
-    const resolved = await resolveActionId(projectId, actionIdArg);
-    const actionId = handleResolution(projectId, "reject", resolved, format);
-    if (!actionId)
-        return;
+    let actionId = actionIdArg;
+    if (!actionId) {
+        const resolved = await resolveAction(projectId, undefined);
+        const action = handleResolution(projectId, "reject", resolved, format);
+        if (!action)
+            return;
+        actionId = action.action_id;
+    }
     const data = await client.post(`/v1/projects/${projectId}/thread/chat`, {
         action_response: { action_id: actionId, response: "rejected" },
     });