sfora-cli 0.12.1 → 0.13.1

package/dist/api-client.d.ts

@@ -573,7 +573,9 @@ export declare class SforaApiClient {
     /** `GET /api/rooms/:id/messages` — history, newest first (server cap: 100). */
     listRoomMessages(roomId: string, limit?: number): Promise<MessagesPage>;
     /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
-    sendRoomMessage(roomId: string, body: string): Promise<{
+    sendRoomMessage(roomId: string, body: string, 
+    /** Terminal client slug — stamped on the message ("sent via Claude Code"). */
+    client?: string): Promise<{
         messageId: string;
     }>;
     /**
@@ -588,6 +590,25 @@ export declare class SforaApiClient {
         roomId?: string;
         client?: string;
     }): Promise<void>;
+    /**
+     * `POST /api/asks` — post a coordination ask, or (with `options`) a
+     * QUESTION: 2–4 short answers for a human to pick from. `target` is a
+     * member NAME (or id), resolved server-side; an ambiguous name comes back
+     * as a 400 listing the candidates. Only humans can answer a question —
+     * enforced in the mutation, not here.
+     */
+    createAsk(params: {
+        text: string;
+        options?: string[];
+        /** Member name or id the question is for — a human. */
+        target?: string;
+        /** Project slug the ask belongs to. */
+        project?: string;
+        /** Room to announce the ask into. */
+        roomId?: string;
+    }): Promise<{
+        askId: string;
+    }>;
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     readInbox(): Promise<string>;
     /** `GET /v1/fs/me/api-key` — text identity (no key material). */

package/dist/api-client.js

@@ -631,10 +631,12 @@ export class SforaApiClient {
         return this.#json(`/api/rooms/${encodeURIComponent(roomId)}/messages?limit=${limit}`);
     }
     /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
-    async sendRoomMessage(roomId, body) {
+    async sendRoomMessage(roomId, body, 
+    /** Terminal client slug — stamped on the message ("sent via Claude Code"). */
+    client) {
         // Through #request like every other call, so network failures surface as
         // SforaApiError(0, "network_error") and `--as` rides the shared headers.
-        const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body }), undefined, "application/json");
+        const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body, client }), undefined, "application/json");
         return this.#jsonFrom(res);
     }
     /**
@@ -648,6 +650,26 @@ export class SforaApiClient {
     async heartbeat(params = {}) {
         await this.#request("POST", "/api/presence", JSON.stringify(params), undefined, "application/json");
     }
+    /**
+     * `POST /api/asks` — post a coordination ask, or (with `options`) a
+     * QUESTION: 2–4 short answers for a human to pick from. `target` is a
+     * member NAME (or id), resolved server-side; an ambiguous name comes back
+     * as a 400 listing the candidates. Only humans can answer a question —
+     * enforced in the mutation, not here.
+     */
+    async createAsk(params) {
+        const body = { text: params.text };
+        if (params.options)
+            body.options = params.options;
+        if (params.target)
+            body.target = params.target;
+        if (params.project)
+            body.project = params.project;
+        if (params.roomId)
+            body.roomId = params.roomId;
+        const res = await this.#request("POST", "/api/asks", JSON.stringify(body), undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     async readInbox() {
         return this.#text("/v1/fs/inbox/mentions.md");

package/dist/ask.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `sfora ask` — an agent asks a human, from the terminal.
+ *
+ * An ask with options is a QUESTION: 2–4 short answers for a human to pick
+ * from, optionally aimed at one person with `--for`. Only humans can answer —
+ * the server enforces that in the mutation, this module just says it in the
+ * error copy. Everything decision-shaped lives here as pure functions
+ * (validation, the wait loop, the ambiguity reformat) so it can be tested with
+ * canned data; `cli.ts` owns the process — signals, the real streams.
+ *
+ * The wait loop rides `/v1/events`, the same long-poll `sfora watch` and
+ * `sfora chat` use: the feed carries an `ask` event for every state change of
+ * an ask the caller created, and a resolved one carries `chosenOption` (the
+ * picked answer) and `resolution`. So waiting is a wake, not a poll schedule.
+ */
+import type { AgentEventsPage } from "./api-client.js";
+export declare const ASK_OPTIONS_MIN = 2;
+export declare const ASK_OPTIONS_MAX = 4;
+export declare const ASK_OPTION_MAX_LENGTH = 80;
+/**
+ * The options as they will be sent, or a thrown explanation.
+ *
+ * Mirrors the server's write-door rule (2–4 entries, trimmed nonempty, ≤80
+ * chars) so a typo fails at the prompt with a usable message instead of as a
+ * 400 after a round trip. The server still validates — this is a courtesy,
+ * not the gate.
+ */
+export declare function validateAskOptions(raw: string[]): string[];
+/**
+ * A server refusal that lists candidates, reshaped for a terminal.
+ *
+ * The `/api/asks` door answers an ambiguous `--for` with one line:
+ * `Ambiguous target 'sam' (candidates: Sam One <id>, Sam Two <id>)`. Reshaped
+ * to the same say-which layout `sfora join` uses for rooms — one candidate per
+ * line, so the retype is a copy. Any message without the candidates suffix is
+ * returned unchanged.
+ */
+export declare function reshapeCandidatesError(message: string): string;
+/** Everything the wait loop needs from the outside world. */
+export interface AskWaitDeps {
+    /** One `/v1/events` long-poll. Rejects on a drop — the loop backs off. */
+    poll(since: number): Promise<AgentEventsPage>;
+    /** A warning, on stderr — never mixed into stdout. */
+    warn(text: string): void;
+    sleep(ms: number): Promise<void>;
+    /** The clock, injectable for tests. */
+    now?(): number;
+}
+export interface AskWaitOptions {
+    askId: string;
+    /** Events cursor to start from — BEFORE the ask was created, with slack. */
+    since: number;
+    /** Absolute deadline (ms epoch); absent means wait forever. */
+    deadlineMs?: number;
+    stopped?: () => boolean;
+    backoffMs?: number;
+}
+export type AskWaitResult = {
+    outcome: "answered";
+    chosenOption?: string;
+    resolution?: string;
+} | {
+    outcome: "timeout";
+} | {
+    outcome: "stopped";
+};
+/**
+ * Poll until the ask resolves, the deadline passes, or the caller stops.
+ *
+ * The same rules the other loops hold: the cursor survives reconnects and
+ * only moves forward, drops back off (doubling to {@link MAX_BACKOFF_MS}) and
+ * recover fast. Only a `resolved` event for THIS ask ends the wait — claims
+ * and other asks' traffic pass through silently.
+ */
+export declare function askWaitLoop(deps: AskWaitDeps, options: AskWaitOptions): Promise<AskWaitResult>;

package/dist/ask.js

@@ -0,0 +1,119 @@
+/**
+ * `sfora ask` — an agent asks a human, from the terminal.
+ *
+ * An ask with options is a QUESTION: 2–4 short answers for a human to pick
+ * from, optionally aimed at one person with `--for`. Only humans can answer —
+ * the server enforces that in the mutation, this module just says it in the
+ * error copy. Everything decision-shaped lives here as pure functions
+ * (validation, the wait loop, the ambiguity reformat) so it can be tested with
+ * canned data; `cli.ts` owns the process — signals, the real streams.
+ *
+ * The wait loop rides `/v1/events`, the same long-poll `sfora watch` and
+ * `sfora chat` use: the feed carries an `ask` event for every state change of
+ * an ask the caller created, and a resolved one carries `chosenOption` (the
+ * picked answer) and `resolution`. So waiting is a wake, not a poll schedule.
+ */
+import { MAX_BACKOFF_MS } from "./watch.js";
+// ─── Option validation (the client-side half of the write gate) ──────
+export const ASK_OPTIONS_MIN = 2;
+export const ASK_OPTIONS_MAX = 4;
+export const ASK_OPTION_MAX_LENGTH = 80;
+/**
+ * The options as they will be sent, or a thrown explanation.
+ *
+ * Mirrors the server's write-door rule (2–4 entries, trimmed nonempty, ≤80
+ * chars) so a typo fails at the prompt with a usable message instead of as a
+ * 400 after a round trip. The server still validates — this is a courtesy,
+ * not the gate.
+ */
+export function validateAskOptions(raw) {
+    const options = raw.map((o) => o.trim());
+    const empty = options.findIndex((o) => !o);
+    if (empty !== -1) {
+        throw new Error(`option ${empty + 1} is empty — every option needs text`);
+    }
+    if (options.length < ASK_OPTIONS_MIN || options.length > ASK_OPTIONS_MAX) {
+        throw new Error(`a question carries ${ASK_OPTIONS_MIN}–${ASK_OPTIONS_MAX} options — you gave ${options.length}. ` +
+            'Repeat --option for each answer: --option "Basic" --option "Business"');
+    }
+    const long = options.find((o) => o.length > ASK_OPTION_MAX_LENGTH);
+    if (long) {
+        throw new Error(`an option is a short answer, not a paragraph — keep each under ${ASK_OPTION_MAX_LENGTH} characters ` +
+            `("${long.slice(0, 40)}…" is ${long.length})`);
+    }
+    const seen = new Set();
+    for (let i = 0; i < options.length; i++) {
+        if (seen.has(options[i])) {
+            throw new Error(`option ${i + 1} repeats "${options[i]}" — every option must be distinct`);
+        }
+        seen.add(options[i]);
+    }
+    return options;
+}
+/**
+ * A server refusal that lists candidates, reshaped for a terminal.
+ *
+ * The `/api/asks` door answers an ambiguous `--for` with one line:
+ * `Ambiguous target 'sam' (candidates: Sam One <id>, Sam Two <id>)`. Reshaped
+ * to the same say-which layout `sfora join` uses for rooms — one candidate per
+ * line, so the retype is a copy. Any message without the candidates suffix is
+ * returned unchanged.
+ */
+export function reshapeCandidatesError(message) {
+    const m = /^(.*?)\s*\(candidates:\s*(.+)\)\s*$/.exec(message);
+    if (!m)
+        return message;
+    return (`${m[1].trim()} — say which:\n` +
+        m[2]
+            .split(", ")
+            .map((c) => `  ${c}`)
+            .join("\n"));
+}
+/**
+ * Poll until the ask resolves, the deadline passes, or the caller stops.
+ *
+ * The same rules the other loops hold: the cursor survives reconnects and
+ * only moves forward, drops back off (doubling to {@link MAX_BACKOFF_MS}) and
+ * recover fast. Only a `resolved` event for THIS ask ends the wait — claims
+ * and other asks' traffic pass through silently.
+ */
+export async function askWaitLoop(deps, options) {
+    const stopped = options.stopped ?? (() => false);
+    const now = deps.now ?? Date.now;
+    const firstBackoff = options.backoffMs ?? 1_000;
+    let cursor = options.since;
+    let backoff = firstBackoff;
+    while (!stopped()) {
+        if (options.deadlineMs !== undefined && now() >= options.deadlineMs) {
+            return { outcome: "timeout" };
+        }
+        let page;
+        try {
+            page = await deps.poll(cursor);
+        }
+        catch (error) {
+            if (stopped())
+                break;
+            const message = error instanceof Error ? error.message : String(error);
+            deps.warn(`reconnecting in ${Math.round(backoff / 1000)}s — ${message}`);
+            await deps.sleep(backoff);
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+            continue;
+        }
+        backoff = firstBackoff;
+        for (const event of page.events) {
+            if (event.type !== "ask" || event.askId !== options.askId)
+                continue;
+            if (event.askState !== "resolved")
+                continue;
+            return {
+                outcome: "answered",
+                chosenOption: typeof event.chosenOption === "string" ? event.chosenOption : undefined,
+                resolution: typeof event.resolution === "string" ? event.resolution : undefined,
+            };
+        }
+        // Never backwards: an empty page holds the cursor where it was.
+        cursor = Math.max(cursor, page.cursor);
+    }
+    return { outcome: "stopped" };
+}

package/dist/chat.d.ts

@@ -23,14 +23,25 @@ import type { AgentEventsPage, ChatMessage, Room } from "./api-client.js";
  * the caller falls through to its next guess.
  */
 export declare function sanitizeClientSlug(raw: string | undefined): string | undefined;
+/**
+ * The client slugs sfora knows by name — the shared vocabulary with the web
+ * app's client marks. Unknown slugs stay valid everywhere; they just render
+ * the generic terminal glyph in the app.
+ */
+export declare const KNOWN_CLIENTS: readonly ["claude-code", "codex", "cursor", "gemini", "windsurf", "aider", "opencode", "cli"];
 /**
  * What kind of client is on the line, for the presence label.
  *
- * Order: an explicit `--client` flag wins; then `AI_AGENT` (the part before
- * the first underscore — `claude-code_2-1-233_agent` names "claude-code");
- * then `CLAUDE_CODE_ENTRYPOINT` being set at all means Claude Code is
- * driving; else this is a plain terminal — "cli". Env is passed in, not
- * read, so every rung is testable.
+ * Order: an explicit `--client` flag wins; then the per-client env markers in
+ * {@link CLIENT_MARKERS}; then `AI_AGENT` (the part before the first
+ * underscore — `claude-code_2-1-233_agent` names "claude-code"); then
+ * `CLAUDE_CODE_ENTRYPOINT` or `CLAUDECODE` being set at all means Claude Code
+ * is driving (kept below `AI_AGENT`, its long-standing rung); then
+ * `CURSOR_TRACE_ID` — set by Cursor's integrated TERMINAL and inherited by
+ * everything launched from it, so it sits at the bottom: Claude Code run
+ * inside Cursor must read as claude-code, not as the window around it. Else
+ * this is a plain terminal — "cli". Env is passed in, not read, so every rung
+ * is testable.
  */
 export declare function detectClient(env: Record<string, string | undefined>, flag?: string): string;
 /** How `sfora rooms` and `sfora join` spell a room name as an argument. */

package/dist/chat.js

@@ -31,24 +31,71 @@ export function sanitizeClientSlug(raw) {
     const slug = raw.toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 32);
     return slug || undefined;
 }
+/**
+ * The client slugs sfora knows by name — the shared vocabulary with the web
+ * app's client marks. Unknown slugs stay valid everywhere; they just render
+ * the generic terminal glyph in the app.
+ */
+export const KNOWN_CLIENTS = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini",
+    "windsurf",
+    "aider",
+    "opencode",
+    "cli",
+];
+/**
+ * Env markers the coding agents actually set, checked in order.
+ *
+ * Only markers verified in the wild are listed — naming the wrong client is
+ * worse than falling through to the generic label, so windsurf / aider /
+ * opencode (no reliable marker known) rely on `--client` or `AI_AGENT`.
+ * Being set at all counts, even empty, matching the Claude Code rung below.
+ *
+ *   CODEX_SANDBOX / CODEX_SANDBOX_NETWORK_DISABLED — OpenAI's Codex CLI sets
+ *     these on the commands it runs.
+ *   GEMINI_CLI — Google's Gemini CLI sets `GEMINI_CLI=1` in its shell tool.
+ *   CURSOR_AGENT — Cursor's agent CLI names itself this way.
+ */
+const CLIENT_MARKERS = [
+    ["CODEX_SANDBOX", "codex"],
+    ["CODEX_SANDBOX_NETWORK_DISABLED", "codex"],
+    ["GEMINI_CLI", "gemini"],
+    ["CURSOR_AGENT", "cursor"],
+];
 /**
  * What kind of client is on the line, for the presence label.
  *
- * Order: an explicit `--client` flag wins; then `AI_AGENT` (the part before
- * the first underscore — `claude-code_2-1-233_agent` names "claude-code");
- * then `CLAUDE_CODE_ENTRYPOINT` being set at all means Claude Code is
- * driving; else this is a plain terminal — "cli". Env is passed in, not
- * read, so every rung is testable.
+ * Order: an explicit `--client` flag wins; then the per-client env markers in
+ * {@link CLIENT_MARKERS}; then `AI_AGENT` (the part before the first
+ * underscore — `claude-code_2-1-233_agent` names "claude-code"); then
+ * `CLAUDE_CODE_ENTRYPOINT` or `CLAUDECODE` being set at all means Claude Code
+ * is driving (kept below `AI_AGENT`, its long-standing rung); then
+ * `CURSOR_TRACE_ID` — set by Cursor's integrated TERMINAL and inherited by
+ * everything launched from it, so it sits at the bottom: Claude Code run
+ * inside Cursor must read as claude-code, not as the window around it. Else
+ * this is a plain terminal — "cli". Env is passed in, not read, so every rung
+ * is testable.
  */
 export function detectClient(env, flag) {
     const fromFlag = sanitizeClientSlug(flag);
     if (fromFlag)
         return fromFlag;
+    for (const [envVar, slug] of CLIENT_MARKERS) {
+        if (env[envVar] !== undefined)
+            return slug;
+    }
     const fromAgent = sanitizeClientSlug(env.AI_AGENT?.split("_")[0]);
     if (fromAgent)
         return fromAgent;
-    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined)
+    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined ||
+        env.CLAUDECODE !== undefined) {
         return "claude-code";
+    }
+    if (env.CURSOR_TRACE_ID !== undefined)
+        return "cursor";
     return "cli";
 }
 // ─── Room resolution ─────────────────────────────────────────────────

package/dist/cli-args.d.ts

@@ -26,8 +26,12 @@ export interface CliArgs {
     block?: string;
     self: boolean;
     wait?: number;
+    waitFlag: boolean;
     message?: string;
     limit?: number;
     client?: string;
+    option: string[];
+    target?: string;
+    room?: string;
 }
 export declare function parseArgs(argv: string[]): CliArgs;

package/dist/cli-args.js

@@ -6,7 +6,7 @@
  * process — argv in, a parsed shape out.
  */
 export function parseArgs(argv) {
-    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false };
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false, waitFlag: false, option: [] };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mcp")
@@ -65,10 +65,22 @@ export function parseArgs(argv) {
             args.block = a.slice("--block=".length);
         else if (a === "--self")
             args.self = true;
-        else if (a === "--wait")
-            args.wait = Number.parseInt(argv[++i] ?? "", 10);
-        else if (a.startsWith("--wait="))
+        // `--wait` doubles as a bare flag (`ask --wait` blocks until the answer)
+        // and a valued one (`watch --wait 10`, `ask --wait 300`). The next token
+        // is consumed only when it is a number, so `ask --wait --json` keeps its
+        // `--json` — the historical "missing value means NaN" shape survives as
+        // `wait: undefined` (every reader already treats non-finite as unset).
+        else if (a === "--wait") {
+            args.waitFlag = true;
+            const next = argv[i + 1];
+            if (next !== undefined && /^\d+$/.test(next)) {
+                args.wait = Number.parseInt(argv[++i], 10);
+            }
+        }
+        else if (a.startsWith("--wait=")) {
+            args.waitFlag = true;
             args.wait = Number.parseInt(a.slice("--wait=".length), 10);
+        }
         else if (a === "-m" || a === "--message")
             args.message = argv[++i];
         else if (a.startsWith("--message="))
@@ -81,6 +93,21 @@ export function parseArgs(argv) {
             args.client = argv[++i];
         else if (a.startsWith("--client="))
             args.client = a.slice("--client=".length);
+        else if (a === "--option") {
+            const value = argv[++i];
+            if (value !== undefined)
+                args.option.push(value);
+        }
+        else if (a.startsWith("--option="))
+            args.option.push(a.slice("--option=".length));
+        else if (a === "--for")
+            args.target = argv[++i];
+        else if (a.startsWith("--for="))
+            args.target = a.slice("--for=".length);
+        else if (a === "--room")
+            args.room = argv[++i];
+        else if (a.startsWith("--room="))
+            args.room = a.slice("--room=".length);
         else if (!a.startsWith("-")) {
             if (!args.command)
                 args.command = a;

package/dist/cli.js

@@ -11,7 +11,8 @@ import { spawn } from "node:child_process";
 import { readFile as readLocalFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { taskUploadFilename } from "./format/taskUploadFilename.js";
-import { createSforaShell, createLocalShell, } from "./index.js";
+import { createSforaShell, createLocalShell, SforaApiError, } from "./index.js";
+import { askWaitLoop, reshapeCandidatesError, validateAskOptions, } from "./ask.js";
 import { openerCommand } from "./opener.js";
 import { blocksCommand, presenceNotice, putCommand, } from "./block-commands.js";
 import { colors, ndjson, presenceRecords, renderPresence, renderWriteEffect, urlLine, PRESENCE_NOTE, } from "./render.js";
@@ -20,7 +21,7 @@ import { LocalWorkspace, initWorkspace, findWorkspace, migrateWorkspaceStages, }
 import { runMcpServer } from "./mcp-server.js";
 import { readConfig, writeConfig, resolveSettings, upsertProfile, effectiveProfiles, DEFAULT_URL, } from "./config.js";
 import { parseArgs } from "./cli-args.js";
-import { chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
+import { capitalizeName, chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
 const HELP = `sfora — the CLI for your sfora workspace
 
 Get started (no account needed):
@@ -70,8 +71,21 @@ Chat:
                                       and agents)
 
   Chat shows others what's on the line: the CLI reports itself in presence,
-  and a coding agent is named automatically (Claude Code sets its own
-  environment). Add --client <name> to say it yourself.
+  and a coding agent is named automatically (Claude Code, Codex, Cursor and
+  Gemini set their own environment). Add --client <name> to say it yourself.
+
+Ask a human:
+  sfora ask "<question>" --option "A" --option "B"
+                                      Post a question with 2–4 answers to
+                                      pick from — only humans can answer
+  sfora ask "…" --option … --for <member>
+                                      Aim it at one person (any human may
+                                      still answer)
+  sfora ask "…" --option … --wait [secs]
+                                      Block until someone answers, then print
+                                      the choice (give secs to stop waiting)
+  Add --project <slug> or --room <room> to say where it belongs; --json for
+  scripts (--wait prints a second JSON line when the answer lands).
 
 Write, and watch others write:
   sfora blocks <path>                 List a document's addressable blocks
@@ -366,6 +380,7 @@ const VERBS = new Set([
     "rooms",
     "join",
     "chat",
+    "ask",
 ]);
 async function runVerb(args, fs, client) {
     const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
@@ -528,6 +543,9 @@ async function runVerb(args, fs, client) {
         }
         return runChat(args, client);
     }
+    if (args.command === "ask") {
+        return runAsk(args, client);
+    }
     if (args.command === "me" || args.command === "whoami") {
         const text = (await client.readMe()).trim();
         if (args.json) {
@@ -818,7 +836,7 @@ async function runChat(args, client) {
             throw new Error('usage: sfora chat <room> -m "text"');
         // One beat alongside the send — a script that speaks was here, briefly.
         void beat();
-        const { messageId } = await client.sendRoomMessage(room._id, text);
+        const { messageId } = await client.sendRoomMessage(room._id, text, clientLabel);
         if (args.json) {
             console.log(JSON.stringify({ messageId, roomId: room._id }, null, 2));
             return;
@@ -909,7 +927,7 @@ async function runChat(args, client) {
         try {
             // The send's own echo is the typed line still on screen; recording the
             // id keeps the tail's refetch from printing it a second time.
-            const { messageId } = await client.sendRoomMessage(room._id, line);
+            const { messageId } = await client.sendRoomMessage(room._id, line, clientLabel);
             seen.add(messageId);
         }
         catch (e) {
@@ -930,6 +948,154 @@ async function runChat(args, client) {
     if (isTty)
         console.log("");
 }
+/**
+ * `sfora ask` — how an agent asks a human, wired to the real process.
+ *
+ * With `--option` flags the ask is a QUESTION: 2–4 short answers a human
+ * picks from in the app — only humans can answer, and the server enforces
+ * that in the mutation, not the UI. `--for` aims it at one person by name
+ * (resolved server-side; any human may still answer). Everything
+ * decision-shaped (validation, the wait loop, the ambiguity reformat) lives
+ * in `ask.ts` where it is tested; this owns signals and the streams.
+ */
+async function runAsk(args, client) {
+    const text = args.rest.join(" ").trim();
+    if (!text) {
+        throw new Error('usage: sfora ask "<question>" --option "A" --option "B" ' +
+            "[--for <member>] [--project <slug>] [--room <room>] [--wait [secs]] [--json]");
+    }
+    const options = args.option.length > 0 ? validateAskOptions(args.option) : undefined;
+    let roomId;
+    let roomTag;
+    if (args.room) {
+        const room = await resolveRoomOrThrow(client, args.room);
+        roomId = room._id;
+        roomTag = `#${roomSlug(room.name)}`;
+    }
+    // The wait cursor is taken BEFORE the create, with generous skew slack: an
+    // answer landing between the create and the first poll must not fall into a
+    // blind window, and overlap is harmless — the loop matches on this ask's id
+    // and resolved state only.
+    const since = Date.now() - 5 * 60_000;
+    let created;
+    try {
+        created = await client.createAsk({
+            text,
+            options,
+            target: args.target,
+            project: args.project,
+            roomId,
+        });
+    }
+    catch (e) {
+        // An ambiguous `--for` comes back as a 400 listing the candidates on one
+        // line — reshape it to the say-which layout `sfora join` uses for rooms.
+        if (e instanceof SforaApiError && e.status === 400) {
+            throw new Error(reshapeCandidatesError(e.message));
+        }
+        throw e;
+    }
+    const { url } = client.takeResponseInfo();
+    const where = [
+        args.project ? `project ${args.project}` : undefined,
+        roomTag,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    if (args.json) {
+        // NDJSON-shaped under --wait: this line says it landed; a second line
+        // (below) says how it resolved. A script reads each as it arrives.
+        console.log(JSON.stringify({
+            askId: created.askId,
+            ...(url ? { url } : {}),
+            ...(options ? { options } : {}),
+            ...(args.target ? { for: args.target } : {}),
+        }));
+    }
+    else {
+        console.log(`${colors.green}✓${colors.reset} Asked${where ? ` in ${where}` : ""} · ${created.askId}`);
+        if (options) {
+            console.log(`  ${colors.dim}options: ${options.join(" · ")}${colors.reset}`);
+        }
+        if (args.target) {
+            console.log(`  ${colors.dim}for ${capitalizeName(args.target)} — only a human can answer${colors.reset}`);
+        }
+        if (url)
+            process.stderr.write(`  ${urlLine(url)}\n`);
+    }
+    if (!args.waitFlag)
+        return;
+    // `--wait [secs]`: block on the events long-poll until a human answers.
+    // ^C has to reach the socket, same as `watch`: the poll hangs for tens of
+    // seconds, and a flag alone would leave a terminal that says it stopped and
+    // hasn't. Second ^C stands down and lets the default behaviour end things.
+    const deadlineMs = Number.isFinite(args.wait) && args.wait > 0
+        ? Date.now() + args.wait * 1000
+        : undefined;
+    let stop = false;
+    const inFlight = new AbortController();
+    let signalled = false;
+    const onSignal = (signal) => {
+        stop = true;
+        inFlight.abort();
+        if (signalled) {
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            process.kill(process.pid, signal);
+            return;
+        }
+        signalled = true;
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    if (!args.json) {
+        process.stderr.write(`${colors.dim}waiting for an answer${deadlineMs ? ` (up to ${args.wait}s)` : ""} — ^C to stop${colors.reset}\n`);
+    }
+    try {
+        const result = await askWaitLoop({
+            // With a deadline, cap each poll's server-side budget to what is left
+            // so the last poll returns near the deadline instead of long after it.
+            poll: (cursor) => client.pollEvents({
+                since: cursor,
+                wait: deadlineMs
+                    ? Math.max(1, Math.ceil((deadlineMs - Date.now()) / 1000))
+                    : undefined,
+                signal: inFlight.signal,
+            }),
+            warn: (t) => process.stderr.write(`${colors.dim}${t}${colors.reset}\n`),
+            sleep,
+        }, { askId: created.askId, since, deadlineMs, stopped: () => stop });
+        if (result.outcome === "answered") {
+            const answer = result.chosenOption ?? result.resolution;
+            if (args.json) {
+                console.log(JSON.stringify({
+                    askId: created.askId,
+                    state: "resolved",
+                    chosenOption: result.chosenOption ?? null,
+                    resolution: result.resolution ?? null,
+                }));
+            }
+            else {
+                console.log(`${colors.green}✓${colors.reset} Answered${answer ? `: ${answer}` : ""}`);
+            }
+        }
+        else if (result.outcome === "timeout") {
+            if (args.json) {
+                console.log(JSON.stringify({ askId: created.askId, state: "open", timedOut: true }));
+            }
+            else {
+                process.stderr.write(`${colors.dim}no answer within ${args.wait}s — the ask stays open${colors.reset}\n`);
+            }
+            // A script waiting on an answer needs to branch on not getting one.
+            process.exitCode = 1;
+        }
+        // stopped (^C): say nothing — the ask stays open and the app still has it.
+    }
+    finally {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    }
+}
 /**
  * A shared command's result, on the real streams.
  *

package/dist/index.d.ts

@@ -69,3 +69,5 @@ export { blocksCommand, putCommand, urlCommand, resolveFsPath, presenceNotice, t
 export { sforaShellCommands, parseShellArgs } from "./shell-commands.js";
 export { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, type WatchDeps, type WatchOptions, type WatchTarget, } from "./watch.js";
 export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, type DocPing, } from "./render.js";
+export { KNOWN_CLIENTS, detectClient, sanitizeClientSlug } from "./chat.js";
+export { validateAskOptions, reshapeCandidatesError, askWaitLoop, ASK_OPTIONS_MIN, ASK_OPTIONS_MAX, ASK_OPTION_MAX_LENGTH, type AskWaitDeps, type AskWaitOptions, type AskWaitResult, } from "./ask.js";

package/dist/index.js

@@ -57,3 +57,5 @@ export { blocksCommand, putCommand, urlCommand, resolveFsPath, presenceNotice, }
 export { sforaShellCommands, parseShellArgs } from "./shell-commands.js";
 export { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, } from "./watch.js";
 export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, } from "./render.js";
+export { KNOWN_CLIENTS, detectClient, sanitizeClientSlug } from "./chat.js";
+export { validateAskOptions, reshapeCandidatesError, askWaitLoop, ASK_OPTIONS_MIN, ASK_OPTIONS_MAX, ASK_OPTION_MAX_LENGTH, } from "./ask.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "type": "module",
   "description": "Your sfora workspace as a markdown filesystem — a CLI + MCP server. Post/task/doc, ls/cat/grep, and a shell so agents operate sfora natively.",
   "keywords": [