sfora-cli 0.12.0 → 0.12.1

package/dist/api-client.d.ts

@@ -576,6 +576,18 @@ export declare class SforaApiClient {
     sendRoomMessage(roomId: string, body: string): Promise<{
         messageId: string;
     }>;
+    /**
+     * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
+     *
+     * `client` is a short slug ("cli", "claude-code") that names what kind of
+     * client is on the line; the app reads it out next to the online dot. The
+     * server sanitizes and owns the field on every beat, so a beat without a
+     * label also clears a stale one.
+     */
+    heartbeat(params?: {
+        roomId?: string;
+        client?: string;
+    }): Promise<void>;
     /** `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

@@ -637,6 +637,17 @@ export class SforaApiClient {
         const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body }), undefined, "application/json");
         return this.#jsonFrom(res);
     }
+    /**
+     * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
+     *
+     * `client` is a short slug ("cli", "claude-code") that names what kind of
+     * client is on the line; the app reads it out next to the online dot. The
+     * server sanitizes and owns the field on every beat, so a beat without a
+     * label also clears a stale one.
+     */
+    async heartbeat(params = {}) {
+        await this.#request("POST", "/api/presence", JSON.stringify(params), undefined, "application/json");
+    }
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     async readInbox() {
         return this.#text("/v1/fs/inbox/mentions.md");

package/dist/chat.d.ts

@@ -17,6 +17,22 @@
  * print twice.
  */
 import type { AgentEventsPage, ChatMessage, Room } from "./api-client.js";
+/**
+ * A presence client label as the server stores it: lowercase, `[a-z0-9-]`
+ * only, at most 32 chars. Anything that sanitizes to nothing is nothing —
+ * the caller falls through to its next guess.
+ */
+export declare function sanitizeClientSlug(raw: string | undefined): string | undefined;
+/**
+ * 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.
+ */
+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. */
 export declare function roomSlug(name: string): string;
 export type RoomMatch = {

package/dist/chat.js

@@ -19,6 +19,38 @@
 import { colors } from "./render.js";
 import { MAX_BACKOFF_MS } from "./watch.js";
 const dim = (text) => `${colors.dim}${text}${colors.reset}`;
+// ─── Client identity (presence label) ────────────────────────────────
+/**
+ * A presence client label as the server stores it: lowercase, `[a-z0-9-]`
+ * only, at most 32 chars. Anything that sanitizes to nothing is nothing —
+ * the caller falls through to its next guess.
+ */
+export function sanitizeClientSlug(raw) {
+    if (!raw)
+        return undefined;
+    const slug = raw.toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 32);
+    return slug || undefined;
+}
+/**
+ * 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.
+ */
+export function detectClient(env, flag) {
+    const fromFlag = sanitizeClientSlug(flag);
+    if (fromFlag)
+        return fromFlag;
+    const fromAgent = sanitizeClientSlug(env.AI_AGENT?.split("_")[0]);
+    if (fromAgent)
+        return fromAgent;
+    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined)
+        return "claude-code";
+    return "cli";
+}
 // ─── Room resolution ─────────────────────────────────────────────────
 /** How `sfora rooms` and `sfora join` spell a room name as an argument. */
 export function roomSlug(name) {

package/dist/cli-args.d.ts

@@ -28,5 +28,6 @@ export interface CliArgs {
     wait?: number;
     message?: string;
     limit?: number;
+    client?: string;
 }
 export declare function parseArgs(argv: string[]): CliArgs;

package/dist/cli-args.js

@@ -77,6 +77,10 @@ export function parseArgs(argv) {
             args.limit = Number.parseInt(argv[++i] ?? "", 10);
         else if (a.startsWith("--limit="))
             args.limit = Number.parseInt(a.slice("--limit=".length), 10);
+        else if (a === "--client")
+            args.client = argv[++i];
+        else if (a.startsWith("--client="))
+            args.client = a.slice("--client=".length);
         else if (!a.startsWith("-")) {
             if (!args.command)
                 args.command = a;

package/dist/cli.js

@@ -20,7 +20,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, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
+import { chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
 const HELP = `sfora — the CLI for your sfora workspace
 
 Get started (no account needed):
@@ -69,6 +69,10 @@ Chat:
   sfora chat <room> -m "text"         Send one message and exit (for scripts
                                       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.
+
 Write, and watch others write:
   sfora blocks <path>                 List a document's addressable blocks
   sfora put <path> <file.md>          Write a file (add --block <id> for one block)
@@ -801,11 +805,19 @@ async function runChat(args, client) {
         await client.joinRoom(room._id);
         console.log(`${colors.green}✓${colors.reset} Joined ${tag}`);
     }
+    // Presence is decoration: a beat that fails changes nothing about the
+    // conversation, so every beat here is best-effort and silent. The label
+    // says WHAT is on the line — "cli", or "claude-code" when a coding agent
+    // is driving — so the app can show the terminal next to the online dot.
+    const clientLabel = detectClient(process.env, args.client);
+    const beat = () => client.heartbeat({ roomId: room._id, client: clientLabel }).catch(() => { });
     // One-shot send.
     if (args.message !== undefined) {
         const text = args.message.trim();
         if (!text)
             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);
         if (args.json) {
             console.log(JSON.stringify({ messageId, roomId: room._id }, null, 2));
@@ -831,6 +843,12 @@ async function runChat(args, client) {
     for (const msg of messages)
         console.log(renderChatMessage(msg, Date.now()));
     process.stderr.write(`${colors.dim}${tag} — type to send · /quit (or ^C) to leave${colors.reset}\n`);
+    // Sitting in the room is being present in it: beat now, then every ~45s
+    // (presence expires server-side, so the cadence just has to outrun the
+    // timeout). `unref` so the timer never keeps the process alive on its own.
+    void beat();
+    const pulse = setInterval(() => void beat(), 45_000);
+    pulse.unref?.();
     // The prompt and the tail share one screen: an arriving message clears the
     // prompt line, prints, and readline redraws the prompt with whatever was
     // being typed. `readline.clearLine` over anything fancier — robust beats
@@ -904,6 +922,10 @@ async function runChat(args, client) {
     stop = true;
     inFlight.abort();
     rl.close();
+    clearInterval(pulse);
+    // A parting beat, best-effort — awaited so quitting doesn't race process
+    // exit, but never allowed to hold the door.
+    await beat();
     await tail.catch(() => { });
     if (isTty)
         console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.12.0",
+  "version": "0.12.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": [