@enter-pro/enter-cli 0.4.1 → 0.4.2

package/README.md

@@ -0,0 +1,252 @@
+# Enter CLI
+
+## Production login
+
+`enter-cli login` uses the production Auth0 tenant `auth.converge.ai` and the
+production API at `https://api.enter.pro/code/api`. The web app's
+`enter.converge.ai` domain is not the API base URL. Log in again if existing
+credentials were issued by the former `auth.enter.pro` tenant.
+
+OAuth and API-key login verify the new token against `/v1/users/info` before
+saving credentials or reporting success. A rejected token leaves existing
+credentials unchanged.
+
+## Local verification
+
+```sh
+npm ci
+npm test
+```
+
+Tests start HTTP fixture servers on loopback and execute the built CLI in child
+processes with a dummy API key. They do not start Work, connect to Enter, create
+cloud resources, or prove end-to-end Work behavior.
+
+### Interactive local simulator
+
+Requires Node 18+ and npm; no Docker, Work server, database, or credentials are
+needed. From this repository, build once and start the fixture server:
+
+```sh
+npm run build
+npm run mock:serve
+```
+
+In another terminal in this repository:
+
+```sh
+npm run local:cli -- whoami
+npm run local:cli -- workspace list
+npm run local:cli -- thread status cloud
+npm run local:cli -- thread approve cloud cloud-action
+npm run local:cli -- thread wait cloud --timeout 3
+npm run local:cli -- project get cloud
+```
+
+The server binds only to `127.0.0.1:43180`. Set `MOCK_ENTER_PORT` in both terminals
+to use another port. `local:cli` always targets loopback and injects only the
+dummy mock key, even if the shell has real `ENTER_API_URL` or `ENTER_API_KEY`
+values. Prefer this wrapper for manual simulation; the normal CLI still uses
+its ordinary configuration. Stop the server with Ctrl-C. Restarting resets all
+in-memory scenarios; no resources are written to Enter or cloud providers.
+
+| Project ID | Scenario |
+| --- | --- |
+| `plan` | Plan approval (`plan-action`) with plan text |
+| `cloud` | Supabase dedicated enable flow (`cloud-action`) |
+| `ai` | AI capability dedicated enable flow (`ai-action`) |
+| `secret` | Secret input (`secret-action`); use fake values only |
+| `questions` | Structured question (`questions-action`) |
+| `subscription` | Feature enable returns `VIP_REQUIRED` |
+| `running` | Never completes; exercise wait timeout |
+| `failed` | Backend turn failed |
+| `http-error` | Backend HTTP 503 |
+| `stalled` | HTTP request never returns; exercise request deadline |
+
+Example input-card and timeout checks:
+
+```sh
+printf '%s\n' 'dummy-test-value' | npm run local:cli -- thread approve secret secret-action --secret-name LOCAL_TEST_KEY --secret-value-stdin
+npm run local:cli -- thread approve questions questions-action --skip-answers
+npm run local:cli -- thread wait running --timeout 1
+npm run local:cli -- thread wait stalled --timeout 1
+```
+
+`test/local-workflow.test.mjs` starts fresh ephemeral servers automatically and
+checks approval, simulated resource flags, continuation turns, rejection,
+subscription refusal, and errors. It is a CLI-to-simulator integration suite,
+not a real provisioning or Work UI test. The simulator intentionally supports
+only the listed workflows; unsupported routes fail instead of fabricating a
+successful response. It retains request methods/paths but never request bodies
+or secret values.
+
+For later real-backend testing, `.env.integration.example` documents the needed
+variables. Copy it to ignored `.env.integration.local` and configure a dedicated
+test backend only when ready. The file is not loaded automatically; neither the
+simulator nor the mock CLI wrapper reads it.
+
+## Agent integration: CLI + Skill
+
+The CLI executes Enter operations and streams structured state. The Skill guides
+agents on command selection, following tasks, presenting questions and handling
+approved actions. This works across agent hosts without host-specific hooks.
+Node 18+ is required. Authenticate with `enter-cli login`, or let the host inject
+`ENTER_API_KEY` through its secret environment mechanism.
+
+### CLI: submit once, observe the returned task
+
+```sh
+enter-cli --output json thread chat PROJECT_ID --file requirement.txt
+# Copy task_id from the receipt, including for queued follow-ups:
+enter-cli thread watch PROJECT_ID --task-id TASK_ID --timeout 60
+enter-cli --output json thread status PROJECT_ID --task-id TASK_ID
+enter-cli --output json thread wait PROJECT_ID --task-id TASK_ID --timeout 10
+```
+
+`chat --stdin` also accepts multiline input without shell escaping or putting the
+message into process arguments. Submission returns immediately with `task_id`,
+`submission_status: accepted`, and ready-to-use monitoring commands. You can
+submit follow-ups while Enter is running; acceptance is not completion.
+
+- `status` reads one snapshot, with a 30-second total deadline by default.
+- `wait` waits for a pending card or terminal state and emits one JSON result.
+  Its default lifetime is 10 seconds.
+- `watch` emits NDJSON snapshots only when meaningful state changes, followed
+  by a final `type: result` record. Its default lifetime is 60 seconds.
+
+Waiting uses authenticated WebSocket events to trigger authoritative HTTP state
+reads. It reconnects with `last_event_id`, deduplicates replay, and uses HTTP
+polling if the stream is unavailable. Healthy streams have a 30-second safety
+refresh; fallback checks are every 2 seconds plus reconnect transitions. Text
+and argument deltas do not cause repeated full snapshot queries. After a card
+event, a short reconciliation window accounts for delayed card persistence.
+Use `--transport poll` to force HTTP-only operation; `--cursor EVENT_ID` resumes
+a prior stream. Returned `transport` and `cursor` make the active mode visible.
+`transport_reason` distinguishes temporary connection failure, unavailable
+streams, and invalid events. Unsupported endpoints stop reconnecting for the
+current call and use HTTP polling. HTTP 401/403 on the stream returns
+`STREAM_AUTH_ERROR` instead of silently reconnecting. WebSockets honor proxy environment variables and `NO_PROXY`; set
+`NODE_USE_ENV_PROXY=0` to disable proxy use for the stream.
+
+Use `--task-id` for submissions and continuation receipts. It follows the exact
+task through queueing, even if an older turn already completed. `--turn N` selects
+a fixed turn instead; the two selectors are mutually exclusive. With neither,
+waiting pins the first observed turn. `--chat-id` scopes chat submission, lookup,
+and continuation commands.
+
+Enter can interject a mid-turn message into the active turn and return an external
+message ID instead of a new task ID. The current API does not map that receipt to
+its owning turn. In that case `status --task-id` returns `unknown`, with separate
+`project_activity` and a `project_status_command`; that activity never claims the
+submission succeeded. Inspect the echoed message and resulting change. Do not
+resubmit blindly or infer correlation from the newest turn.
+
+`project create` returns continuation commands. `project create --wait` uses the
+same bounded event monitor, yields on cards, and requires a matching successful
+build. `thread wait/status/watch --require-build` enables that build check for an
+existing project; stale successful builds cannot satisfy it. A matching failed
+build returns failure, and timeout preserves progress without cancelling Enter.
+
+| Status | Meaning |
+| --- | --- |
+| `idle` | No turn exists yet |
+| `queued` | The selected task is in the backend queue |
+| `unknown` | The selected submission cannot be correlated; this is not completion |
+| `running` | Selected turn has not terminated and has no pending actions |
+| `blocked` | Inspect `actions` for questions or approval requirements |
+| `completed` | Turn completed; build and deployment remain separate |
+| `failed` | Turn failed, errored or was cancelled |
+| `unknown` | Explicit turn missing or status unavailable |
+
+The existing `status` and `wait` commands retain full metadata by default; use
+`--compact` for monitoring fields only. `watch` defaults to compact snapshots
+and accepts `--full`. `build_matches_turn` only becomes true when the build commit matches
+the selected turn's commit; an older successful preview does not prove the new
+turn built successfully. Known credential fields are redacted in monitoring, approval and event output,
+including known JSON-encoded tool argument fields. Ordinary command output and
+arbitrary JSON strings are not rewritten by this monitoring feature.
+
+Exit 0 means a successful observation (including `blocked`), not build success.
+Exit 2 means the observation deadline elapsed while work remained pending:
+`wait_timed_out: true`. Exit 1 means failure, unknown state or a failed query.
+A query timeout includes `query_timed_out: true`; retained state is only the last
+complete snapshot. SIGINT/SIGTERM during status/wait/watch returns
+`interrupted: true` with exit 130/143, without labelling it a timeout or cancelling
+remote work.
+
+For raw events rather than state snapshots:
+
+```sh
+enter-cli thread messages PROJECT_ID --follow --timeout 60 --cursor EVENT_ID
+```
+
+This emits NDJSON on stdout, transport diagnostics on stderr, and supports
+`--max-events N`. It continues across turn boundaries until its deadline or limit.
+Unlike `watch`, raw follow does not synthesize HTTP state when the socket is down.
+
+### Skill and host responsibilities
+
+The Skill should direct agents to submit once, follow the returned task ID, and
+use bounded `thread watch` or `thread wait` calls. Forward questions with their
+options and selection mode, and approve only within the user's authorization.
+Provide secrets through Enter's secure form or direct CLI stdin.
+
+The host remains responsible for scheduling observation and handling incoming
+user messages concurrently. CLI events cannot wake an agent
+whose host has stopped the task. Continue bounded watch calls while work remains
+pending; if the host supports background tasks, schedule a watcher there. Forward
+questions without silently selecting answers, and continue with the task ID
+returned by approval. Do not auto-approve based only on `input_kind: none`.
+
+### Errors and retry boundaries
+
+`--request-timeout SECONDS` optionally bounds JSON API requests, including
+response bodies. Without this explicit option, ordinary operations retain their
+existing request lifetime; monitoring commands always enforce their own total
+`--timeout`. Transient network errors and HTTP 502/503/504 retry once only for
+thread observation reads (turns, actions, messages and queued tasks).
+Mutations are never automatically replayed. A timed-out write can already have
+reached Enter: `error.outcome_unknown: true` tells the caller to inspect task or
+action state before resubmitting.
+
+In JSON mode, command execution errors are JSON on stderr. Status/watch query
+errors accompany their last observed snapshot on stdout. Error fields include
+`code`, `message`, `retryable`, and `outcome_unknown`. Never infer success from a
+missing stderr message.
+
+`test/agent-ux.test.mjs` uses local HTTP/WebSocket fixtures to cover event-triggered
+cards, delayed persistence, reconnect and cursor replay, queue tracking, polling
+fallback, deadlines, safe read retries and redaction. These are protocol/CLI integration tests,
+not production cloud-provisioning or a host UI acceptance test.
+
+## Approval inputs
+
+Feature enable cards use the dedicated feature endpoint and verify that the
+selected action becomes approved. A failed enable request, subscription refusal,
+or failed action must remain an error. Secret cards require both a name and a
+nonempty value; question cards require `--answers` or an explicit `--skip-answers`.
+
+OAuth cards (`supabase_configure_auth_provider`) resolve their provider from the
+matching tool call. If the provider was already configured through Enter's secure
+form, ordinary `thread approve PROJECT_ID ACTION_ID` verifies it and submits only
+`auth_provider_result: {provider}`. Otherwise, `--auth-config-stdin` accepts a JSON
+object, saves it through the auth configuration endpoint, then requests approval.
+The backend verifies the stored configuration before accepting the action.
+
+| Provider | Configuration fields |
+| --- | --- |
+| `google` | `client_ids`, `client_secret`, optional `skip_nonce_checks` |
+| `wechat` | `client_id`, `client_secret` |
+| `alipay` | `app_id`, `private_key` |
+| `feishu` | `app_id`, `app_secret` |
+
+Use a secure input mechanism to supply stdin, or complete the secure form in
+Enter. Do not request credentials in ordinary agent chat or place them in process
+arguments. Verbose request logging redacts credential fields. Approval payloads
+contain no OAuth credentials. The host needs a secure input path or a link to Enter's
+form to make these cards usable from its UI.
+
+`test/auth-provider-approve.test.mjs` exercises all four provider contracts against
+local HTTP fixtures, including save failures, backend verification failures,
+incorrect provider binding, malformed inputs, and verbose output redaction.
+These tests do not validate a live OAuth login or cloud provisioning.

package/dist/auth.d.ts

@@ -6,6 +6,7 @@ export interface Credentials {
     expires_at?: string;
 }
 export declare function saveCredentials(creds: Credentials): void;
+export declare function verifyAccessToken(token: string): Promise<void>;
 export declare function loadCredentials(): Credentials | null;
 export declare function clearCredentials(): void;
 export declare function getToken(): string;

package/dist/auth.js

@@ -1,15 +1,33 @@
-import { readFileSync, writeFileSync, unlinkSync } from "fs";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "fs";
 import { join } from "path";
-import { configDir } from "./config.js";
+import { baseURL, configDir } from "./config.js";
 const CREDENTIALS_FILE = "credentials.json";
 function credentialsPath() {
     return join(configDir(), CREDENTIALS_FILE);
 }
 export function saveCredentials(creds) {
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
     writeFileSync(credentialsPath(), JSON.stringify(creds, null, 2), {
         mode: 0o600,
     });
 }
+// Validate the newly issued token, not an older saved token or ENTER_API_KEY.
+// Do not persist it or claim login success until the configured API accepts it.
+export async function verifyAccessToken(token) {
+    if (!token)
+        throw new Error("Login did not return an access token");
+    const response = await fetch(`${baseURL()}/v1/users/info`, {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(15000),
+    });
+    if (!response.ok) {
+        throw new Error(`Login verification failed (HTTP ${response.status}); credentials were not saved`);
+    }
+    const result = await response.json();
+    if (result?.code !== 0) {
+        throw new Error("Login verification failed: API did not confirm authentication; credentials were not saved");
+    }
+}
 export function loadCredentials() {
     try {
         const data = readFileSync(credentialsPath(), "utf-8");

package/dist/client.d.ts

@@ -1,6 +1,7 @@
+export declare function setRequestTimeout(seconds: number): void;
 export declare function setVerbose(v: boolean): void;
-export declare function get(path: string, params?: Record<string, string>): Promise<unknown>;
-export declare function post(path: string, body?: unknown): Promise<unknown>;
+export declare function get(path: string, params?: Record<string, string>, signal?: AbortSignal): Promise<unknown>;
+export declare function post(path: string, body?: unknown, signal?: AbortSignal): Promise<unknown>;
 export declare function del(path: string): Promise<unknown>;
 export declare function put(path: string, body?: unknown): Promise<unknown>;
 export declare function patch(path: string, body?: unknown): Promise<unknown>;

package/dist/client.js

@@ -1,8 +1,16 @@
 import { baseURL, workURL } from "./config.js";
 import { getToken } from "./auth.js";
-import { APIError } from "./errors.js";
+import { safeOutput } from "./safe-output.js";
+import { APIError, RequestError } from "./errors.js";
+import { setTimeout as delay } from "node:timers/promises";
 const CODE_SUCCESS = 0;
 let verbose = false;
+let requestTimeoutMs;
+export function setRequestTimeout(seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 2147483)
+        throw new Error("--request-timeout must be a positive number of seconds");
+    requestTimeoutMs = seconds * 1000;
+}
 export function setVerbose(v) {
     verbose = v;
 }
@@ -19,51 +27,97 @@ async function request(method, path, options, base) {
     const token = getToken();
     if (token)
         headers["Authorization"] = `Bearer ${token}`;
-    const init = { method, headers };
+    const init = { method, headers, signal: options?.signal };
     if (options?.body !== undefined) {
         init.body = JSON.stringify(options.body);
     }
     if (verbose) {
         console.error(`> ${method} ${url}`);
         if (options?.body)
-            console.error(`> Body: ${JSON.stringify(options.body)}`);
+            console.error(`> Body: ${JSON.stringify(safeOutput(options.body, { redactIdentifiers: true }))}`);
     }
-    const resp = await fetch(url, init);
-    if (verbose) {
-        console.error(`< ${resp.status} ${resp.statusText}`);
-    }
-    if (resp.status === 401) {
-        throw new Error("Authentication required. Run `enter login` or set ENTER_API_KEY environment variable.");
-    }
-    const text = await resp.text();
-    let apiResp;
+    // A single deadline covers retries and reading the response body as well as
+    // connecting. Never replay writes after an ambiguous transport failure.
+    const readOnly = method === "GET" || (method === "POST" && path.endsWith("/thread/actions"));
+    const retryRead = readOnly && /\/thread\/(turns|actions|messages|tasks)$/.test(path);
+    const controller = new AbortController();
+    const abort = () => controller.abort(options?.signal?.reason);
+    options?.signal?.addEventListener("abort", abort, { once: true });
+    if (options?.signal?.aborted)
+        abort();
+    const timer = requestTimeoutMs === undefined ? undefined : setTimeout(() => controller.abort(), requestTimeoutMs);
+    init.signal = controller.signal;
     try {
-        apiResp = JSON.parse(text);
-    }
-    catch {
-        if (resp.status >= 400) {
-            throw new Error(`HTTP ${resp.status}: ${text}`);
+        for (let attempt = 0;; attempt++) {
+            let resp;
+            let text;
+            try {
+                resp = await fetch(url, init);
+                text = await resp.text();
+            }
+            catch (error) {
+                if (options?.signal?.aborted)
+                    throw error;
+                const timedOut = controller.signal.aborted;
+                const cause = error.cause?.code;
+                if (retryRead && !timedOut && attempt < 1) {
+                    await delay(200, undefined, { signal: controller.signal });
+                    continue;
+                }
+                throw new RequestError(timedOut ? "REQUEST_TIMEOUT" : "NETWORK_ERROR", timedOut ? "Enter request exceeded its deadline." : `Could not reach Enter${cause ? ` (${cause})` : ""}. Check connectivity and proxy settings.`, readOnly, !readOnly, cause);
+            }
+            if (verbose) {
+                console.error(`< ${resp.status} ${resp.statusText}`);
+            }
+            if (resp.status === 401) {
+                throw new Error("Authentication required. Run `enter login` or set ENTER_API_KEY environment variable.");
+            }
+            if (retryRead && [502, 503, 504].includes(resp.status) && attempt < 1) {
+                await delay(200, undefined, { signal: controller.signal });
+                continue;
+            }
+            let apiResp;
+            try {
+                apiResp = JSON.parse(text);
+            }
+            catch {
+                if (resp.status >= 400) {
+                    throw new RequestError(`HTTP_${resp.status}`, `Enter returned HTTP ${resp.status}.`, readOnly && resp.status >= 500, !readOnly && resp.status >= 500);
+                }
+                throw new RequestError("INVALID_RESPONSE", "Enter returned a non-JSON response.", readOnly, !readOnly);
+            }
+            if (apiResp.code === undefined) {
+                // Endpoint returns raw JSON without the standard {code,message,data} envelope.
+                // Surface the parsed body as-is.
+                if (resp.status >= 400) {
+                    throw new RequestError(`HTTP_${resp.status}`, `Enter returned HTTP ${resp.status}.`, readOnly && resp.status >= 500, !readOnly && resp.status >= 500);
+                }
+                return apiResp;
+            }
+            if (resp.status >= 500)
+                throw new RequestError(apiResp.code ? String(apiResp.code) : `HTTP_${resp.status}`, `Enter returned HTTP ${resp.status}${apiResp.message ? `: ${apiResp.message}` : ""}.`, readOnly, !readOnly);
+            if (apiResp.code !== CODE_SUCCESS) {
+                throw new APIError(apiResp.code, apiResp.message ?? "", apiResp.detail ?? "");
+            }
+            return apiResp.data;
         }
-        return JSON.parse(text);
     }
-    if (apiResp.code === undefined) {
-        // Endpoint returns raw JSON without the standard {code,message,data} envelope.
-        // Surface the parsed body as-is.
-        if (resp.status >= 400) {
-            throw new Error(`HTTP ${resp.status}: ${text}`);
+    catch (error) {
+        if (controller.signal.aborted && !options?.signal?.aborted) {
+            throw new RequestError("REQUEST_TIMEOUT", "Enter request exceeded its deadline.", readOnly, !readOnly);
         }
-        return apiResp;
+        throw error;
     }
-    if (apiResp.code !== CODE_SUCCESS) {
-        throw new APIError(apiResp.code, apiResp.message ?? "", apiResp.detail ?? "");
+    finally {
+        clearTimeout(timer);
+        options?.signal?.removeEventListener("abort", abort);
     }
-    return apiResp.data;
 }
-export async function get(path, params) {
-    return request("GET", path, { params });
+export async function get(path, params, signal) {
+    return request("GET", path, { params, signal });
 }
-export async function post(path, body) {
-    return request("POST", path, { body });
+export async function post(path, body, signal) {
+    return request("POST", path, { body, signal });
 }
 export async function del(path) {
     return request("DELETE", path);

package/dist/commands/login.js

@@ -2,10 +2,10 @@ import { Command } from "commander";
 import { createServer } from "http";
 import { randomBytes, createHash } from "crypto";
 import { execSync } from "child_process";
-import { saveCredentials } from "../auth.js";
+import { saveCredentials, verifyAccessToken } from "../auth.js";
 import { printMessage } from "../output.js";
-const AUTH0_DOMAIN = "auth.enter.pro";
-const CLIENT_ID = "TZvnfnosSwQh9UmOTxmcWiIJ7CqFrsln";
+const AUTH0_DOMAIN = "auth.converge.ai";
+const CLIENT_ID = "anCisSaaIA36fTZ2DUMiTMro3bYuptrf";
 const AUTHORIZE_URL = `https://${AUTH0_DOMAIN}/authorize`;
 const TOKEN_URL = `https://${AUTH0_DOMAIN}/oauth/token`;
 const AUDIENCE = "https://api.enter.pro";
@@ -83,6 +83,7 @@ function startOAuthFlow() {
             }
             try {
                 const tokens = await exchangeCodeForTokens(code, codeVerifier);
+                await verifyAccessToken(tokens.access_token);
                 const expiresAt = new Date(Date.now() + tokens.expires_in * 1000).toISOString();
                 saveCredentials({
                     access_token: tokens.access_token,
@@ -132,6 +133,7 @@ export const loginCmd = new Command("login")
     .option("--api-key <key>", "Authenticate with a workspace API key instead of OAuth")
     .action(async (opts) => {
     if (opts.apiKey) {
+        await verifyAccessToken(opts.apiKey);
         saveCredentials({
             access_token: opts.apiKey,
             token_type: "Bearer",

package/dist/commands/project.js

@@ -3,6 +3,8 @@ import { writeFileSync } from "fs";
 import * as client from "../client.js";
 import { print, printMessage, printResult, printTable, pickList, getFormat } from "../output.js";
 import { pollUntil, TimeoutError } from "../poll.js";
+import { reportThread, threadInteraction } from "./thread.js";
+import { safeOutput } from "../safe-output.js";
 import { resolveLifecycleStatus } from "../lifecycle.js";
 export const projectCmd = new Command("project")
     .alias("proj")
@@ -89,6 +91,9 @@ projectCmd
     .option("--wait", "Wait until the first build completes")
     .option("--timeout <seconds>", "Timeout for --wait in seconds", "300")
     .action(async (id, opts, cmd) => {
+    const seconds = Number(opts.timeout);
+    if (opts.wait && (!Number.isFinite(seconds) || seconds <= 0 || seconds * 1000 > 2147483647))
+        throw new Error("--timeout must be a positive bounded number");
     const body = {};
     if (opts.name)
         body.name = opts.name;
@@ -99,38 +104,15 @@ projectCmd
     if (opts.planMode)
         body.plan_mode = true;
     const data = await client.post(`/v1/workspaces/${id}/projects`, body);
-    if (!opts.wait) {
-        print(getFormat(cmd), data);
-        return;
-    }
-    const created = data;
+    const created = unwrapProject(data);
     const projectId = String(created.project_id ?? created.id ?? "");
-    if (!projectId) {
-        print(getFormat(cmd), data);
+    if (!projectId)
+        throw new Error("Creation response is missing project ID; creation outcome is unknown. Inspect project list before retrying.");
+    if (!opts.wait) {
+        print(getFormat(cmd), safeOutput({ ...data, submission_status: "accepted", ...threadInteraction(projectId) }));
         return;
     }
-    console.error("Waiting for first build to complete...");
-    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
-    const buildingStatuses = new Set(["initializing", "building"]);
-    try {
-        const result = await pollUntil(() => client.get(`/v1/projects/${projectId}/detail`), (d) => !buildingStatuses.has(String(d.status ?? "")), {
-            intervalMs: 3000,
-            timeoutMs,
-            onTick: (elapsed) => {
-                process.stderr.write(`\rWaiting... ${Math.round(elapsed / 1000)}s elapsed`);
-            },
-        });
-        process.stderr.write("\n");
-        const enriched = { ...result, lifecycle_status: resolveLifecycleStatus(result) };
-        print(getFormat(cmd), enriched);
-    }
-    catch (err) {
-        if (err instanceof TimeoutError) {
-            console.error(`\nTimed out after ${opts.timeout}s. Project may still be building.`);
-            process.exit(1);
-        }
-        throw err;
-    }
+    await reportThread(projectId, { timeout: String(seconds), requireBuild: true, compact: true }, cmd, true);
 });
 projectCmd
     .command("rename <project_id> <new_name>")

package/dist/commands/thread-tasks.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerThreadTasks(parent: Command): void;

package/dist/commands/thread-tasks.js

@@ -0,0 +1,23 @@
+import * as client from "../client.js";
+import { getFormat, print, printTable } from "../output.js";
+// Queue payloads can contain prompts, attachments and credentials. Expose only
+// the metadata needed to diagnose accepted tasks that have no turn yet.
+export function registerThreadTasks(parent) {
+    parent.command("tasks <project_id>")
+        .description("List queued/running tasks without exposing prompts or credentials")
+        .option("--chat-id <id>", "Scope the queue lookup to a chat")
+        .action(async (projectId, opts, cmd) => {
+        const data = await client.get(`/v1/projects/${projectId}/thread/tasks`, opts.chatId ? { chat_id: opts.chatId } : undefined);
+        if (!Array.isArray(data?.tasks))
+            throw new Error("Invalid task queue response: expected tasks array");
+        const tasks = data.tasks.map(task => Object.fromEntries(["id", "task_type", "task_status", "created_at", "project_id", "chat_id"]
+            .filter(key => typeof task[key] === "string")
+            .map(key => [key, task[key]])));
+        if (getFormat(cmd) === "table") {
+            printTable(["ID", "Type", "Status", "Created", "Chat"], tasks.map(task => ["id", "task_type", "task_status", "created_at", "chat_id"].map(key => String(task[key] ?? ""))));
+        }
+        else {
+            print(getFormat(cmd), { project_id: projectId, ...(opts.chatId ? { chat_id: opts.chatId } : {}), tasks, total: tasks.length });
+        }
+    });
+}

package/dist/commands/thread.d.ts

@@ -1,2 +1,29 @@
 import { Command } from "commander";
 export declare const threadCmd: Command;
+type InteractionOptions = {
+    taskId?: string;
+    chatId?: string;
+    turn?: number;
+    requireBuild?: boolean;
+};
+export declare function threadInteraction(id: string, { taskId, chatId, turn, requireBuild }?: InteractionOptions): {
+    monitoring_required: boolean;
+    wait_command: string;
+    watch_command: string;
+    status_command: string;
+    follow_up_command: string;
+    instructions: string;
+};
+type MonitorOptions = {
+    turn?: string;
+    taskId?: string;
+    chatId?: string;
+    cursor?: string;
+    timeout: string;
+    transport?: string;
+    full?: boolean;
+    compact?: boolean;
+    requireBuild?: boolean;
+};
+export declare function reportThread(id: string, opts: MonitorOptions, cmd: Command, wait: boolean, watch?: boolean): Promise<void>;
+export {};