octwin-cli 0.1.7 → 0.1.9

package/README.md

@@ -66,13 +66,30 @@ octwin status               # "✓ live and current" once it's warm
 | `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
 | `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. |
 | `octwin status` | Report what the platform has live for this pack — installed vs. loaded version, and its flows. |
+| `octwin chat "msg"` | Drive a turn through the dev web channel and print **every render with its tap ids**. `--as <handle>` picks the test user; `--tap "<tap-id>"` presses a rendered button/list row; `--json` dumps the raw envelopes. |
+| `octwin logs` | List recent conversations (handle, status, last activity; `--as` filters), or show one conversation's full event timeline — including what each turn rendered. `--json` for raw payloads. |
+| `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. |
+| `octwin cases` | Inspect casework (support tickets): the inbox, one case + its timeline and decisions, or `--queues` for queue keys + open counts. |
 | `octwin platform-kb pull` | Pull the platform's capability reference (built-ins, primitives, render intents, flow-DSL — as markdown + JSON) into `.octwin/platform-kb/`, for the **`octwin-pack`** Claude Code authoring plugin to consult. |
-| `octwin test` | Validate locally and print how to try the pack on your tenant. |
-| `octwin help` | Show usage. |
+| `octwin test` | Alias for `octwin validate --remote` — the platform's full manifest + flow-DSL check. |
+| `octwin help` | Show usage. Every subcommand also answers `--help`. |
 
 Every command that talks to the platform accepts `--dir <path>` (the pack directory; defaults to
 the current directory) plus the target overrides `--url` / `--tenant` / `--project` / `--token`.
 
+### Debugging a live conversation
+
+The platform keeps **one open conversation per `--as` handle**, so consecutive `octwin chat` calls
+with the same handle **continue the same conversation** — agent memory, suspended flows, and all:
+
+```bash
+octwin chat "hi" --as tester1                 # turn 1 — prints the menu with each row's tap id
+octwin chat --tap "t:invoke:my-flow:x=1" --as tester1   # turn 2 — press a rendered row
+octwin chat "3 bedrooms" --as tester1         # turn 3 — free text into the running flow
+octwin logs --as tester1                      # find the conversation, then:
+octwin logs <conversationId>                  # the full timeline (taps, renders, tool events)
+```
+
 ## Configuration
 
 The deploy target has four settings. Three live in a committed **`pack.json`** at the root of your

package/dist/index.js

@@ -15,11 +15,18 @@
  *   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
  *   octwin status  [--dir .]        # did my deploy land? which version is live?
  *   octwin records [entity] [id]    # inspect the pack's XRM data (records:read token)
- *   octwin logs    [conversationId] # list conversations / show one's timeline
- *   octwin chat    "msg" [--as h]   # drive one turn via the web channel + print the reply
+ *   octwin cases   [caseId] [--queues]     # inspect casework (support tickets) — list / one case + timeline
+ *   octwin logs    [conversationId] [--as h] [--json]  # list conversations / show one's timeline
+ *   octwin chat    "msg" [--as h] [--tap <tap-id>] [--json]  # drive a turn via the web channel
  *   octwin platform-kb [pull] [--dir .]  # pull the platform capability reference for the authoring skill
  *   octwin test    [--dir .]        # = validate --remote (the full platform check)
  *
+ * Multi-turn testing: the platform keeps ONE open conversation per `--as` handle,
+ * so consecutive `octwin chat --as <h>` calls CONTINUE the same conversation
+ * (same agent memory, resumable flows). Renders print every row/button with its
+ * tap id; replay a tap with `--tap "<tap-id>"`. `--help` on any subcommand
+ * prints its usage without touching the network.
+ *
  * Config resolution (deploy): flags > pack.json (in the pack dir) > env
  * (PACK_PLATFORM_URL / PACK_TENANT / PACK_PROJECT / PACK_TOKEN) > saved login.
  *
@@ -72,6 +79,32 @@ function die(msg) {
     console.error(`✗ ${msg}`);
     process.exit(1);
 }
+// ── network helpers ─────────────────────────────────────────────────────────
+/** `fetch` that dies with the TARGET URL on a network failure — a bare
+ *  `✗ fetch failed` with no address helps nobody (author-feedback A9). */
+async function fetchOrDie(url, init, what) {
+    try {
+        return await fetch(url, init);
+    }
+    catch (err) {
+        die(`${what} — platform unreachable at ${url} (${err?.message ?? err})`);
+    }
+}
+/** One consistent explanation for auth failures on admin reads. A 401 can also
+ *  be a one-off transient (the platform treats an auth-backend hiccup as
+ *  unauthenticated), so say so instead of sending the author on a re-login hunt. */
+function authFailureHint(status, url) {
+    return status === 401
+        ? `the token was rejected — invalid / expired / revoked. If it JUST worked, this can be a one-off platform hiccup: retry once before re-logging in (octwin login --url ${url} --token oct_…)`
+        : `the token is valid but not authorized here (missing scope, plan feature, or role)`;
+}
+/** Pretty-print a JSON error body (or raw text) for an HTTP failure line. */
+function errDetail(json) {
+    if (json == null)
+        return '';
+    const msg = typeof json === 'string' ? json : (json.error ?? json.message ?? JSON.stringify(json));
+    return msg ? ` — ${msg}` : '';
+}
 // ── bundle collection ───────────────────────────────────────────────────────
 const SKIP_DIRS = new Set(['.git', 'node_modules', '.pack-bundles', 'dist', '.mastra']);
 /** Collect every text file under `packDir` into a `{ relPath: content }` map. */
@@ -177,11 +210,22 @@ async function latestPublishedVersion() {
         return null;
     }
 }
+/** True when running via `npx` — the CLI's own file lives in npx's cache dir, or npm
+ *  ran it as `npm exec`. Under npx there is no persistent install to upgrade
+ *  (`@latest` already resolves the newest), so an upgrade notice would be
+ *  misleading — stay silent. The notice is for a GLOBAL install (`npm i -g`). */
+function isNpx() {
+    try {
+        return fileURLToPath(import.meta.url).includes('_npx') || process.env.npm_command === 'exec';
+    }
+    catch {
+        return false;
+    }
+}
 /** Print a one-line upgrade notice (to stderr) when a newer octwin-cli is published.
- *  Skipped when not attached to a TTY (CI / piped) so it never adds noise to scripts.
- *  Never throws. */
+ *  Skipped when piped/CI (not a TTY) or run via npx (nothing to upgrade). Never throws. */
 async function notifyIfOutdated() {
-    if (!process.stdout.isTTY)
+    if (!process.stdout.isTTY || isNpx())
         return;
     try {
         const latest = await latestPublishedVersion();
@@ -257,11 +301,11 @@ async function cmdValidate(flags) {
     // every flow (schema/expression/structure) — returning ALL errors at once.
     const { url, tenant, project, token } = resolveTarget(flags, packDir);
     console.log(`→ Validating against ${tenant}/${project} @ ${url} …`);
-    const res = await fetch(`${url}/api/admin/tenants/${tenant}/projects/${project}/packs/validate`, {
+    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/projects/${project}/packs/validate`, {
         method: 'POST',
         headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
         body: JSON.stringify({ files }),
-    });
+    }, 'remote validate');
     const text = await res.text();
     let json;
     try {
@@ -323,7 +367,7 @@ function resolveTarget(flags, packDir) {
 async function cmdWhoami(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { url, tenant, token } = resolveTarget(flags, packDir);
-    const res = await fetch(`${url}/api/admin/tenants/${tenant}/packs`, { headers: { authorization: `Bearer ${token}` } });
+    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/packs`, { headers: { authorization: `Bearer ${token}` } }, 'token check');
     if (res.ok) {
         console.log(`✓ Token valid for tenant '${tenant}' at ${url} (${token.startsWith('oct_') ? 'deploy token' : 'session token'})`);
         return;
@@ -400,13 +444,13 @@ async function cmdDeploy(flags) {
     const endpoint = `${url}/api/admin/tenants/${tenant}/projects/${project}/packs/deploy`;
     const seed = flags.seed === true;
     console.log(`→ Deploying ${id}@${version} (${Object.keys(files).length} files) to ${tenant}/${project}${seed ? ' — with demo seed' : ''} …`);
-    const res = await fetch(endpoint, {
+    const res = await fetchOrDie(endpoint, {
         method: 'POST',
         // Ask for a progress stream; the platform falls back to plain JSON if it
         // (or an error before any progress) can't stream — handled below.
         headers: { 'content-type': 'application/json', accept: 'text/event-stream', authorization: `Bearer ${token}` },
         body: JSON.stringify({ files, seed }),
-    });
+    }, 'deploy');
     // Streaming path — live install + seed progress (image generation can take a
     // while, so `--seed` prints per-record / per-image lines as they happen).
     if (res.ok && (res.headers.get('content-type') ?? '').includes('text/event-stream') && res.body) {
@@ -444,9 +488,9 @@ async function cmdStatus(flags) {
         die('manifest.yaml must declare a string `id`');
     const id = doc.id;
     const localVersion = typeof doc?.version === 'string' ? doc.version : '?';
-    const res = await fetch(`${url}/api/admin/tenants/${tenant}/projects/${project}/packs/${id}/runtime`, {
+    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/projects/${project}/packs/${id}/runtime`, {
         headers: { authorization: `Bearer ${token}` },
-    });
+    }, 'status check');
     const text = await res.text();
     let json;
     try {
@@ -482,9 +526,9 @@ async function cmdStatus(flags) {
 async function cmdPlatformKb(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { url, tenant, token } = resolveTarget(flags, packDir);
-    const res = await fetch(`${url}/api/admin/tenants/${tenant}/octwin-platform-kb`, {
+    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/octwin-platform-kb`, {
         headers: { authorization: `Bearer ${token}` },
-    });
+    }, 'platform-kb pull');
     const text = await res.text();
     if (!res.ok) {
         let j;
@@ -522,10 +566,12 @@ async function cmdPlatformKb(flags) {
     console.log(`  ${mdCount} markdown docs + ${jsonCount} JSON catalogs (reference version ${bundle.version ?? '?'})`);
     console.log('  The octwin-pack authoring skill reads these as the source of truth for what the platform supports.');
 }
-// ── records / logs / chat — headless inspect + test with the deploy token ────
-/** GET an admin endpoint with the deploy token; returns `{ status, json }`. */
+// ── records / cases / logs / chat — headless inspect + test with the deploy token ────
+/** GET an admin endpoint with the deploy token; returns `{ status, json }`.
+ *  Dies (with the URL) on a network failure; auth failures return so the
+ *  caller can add command-specific context on top of `authFailureHint`. */
 async function apiGet(endpoint, token) {
-    const res = await fetch(endpoint, { headers: { authorization: `Bearer ${token}` } });
+    const res = await fetchOrDie(endpoint, { headers: { authorization: `Bearer ${token}` } }, 'request');
     const text = await res.text();
     let json;
     try {
@@ -567,8 +613,14 @@ async function cmdRecords(flags) {
         const { status, json } = await apiGet(`${base}/xrm/records?entity=${encodeURIComponent(entity)}&limit=${limit}`, token);
         if (status === 403)
             die('forbidden — the paged record list needs the `records` plan feature on this tenant');
-        if (status !== 200)
-            die(`could not read records (HTTP ${status})`);
+        if (status !== 200) {
+            // Always show the server's reason (it names the unknown entity). Cases are
+            // casework (worklist), not pack-declared XRM — point at the right command.
+            if (entity === 'case' || entity === 'cases') {
+                console.error(`  '${entity}' is casework (worklist), not a pack-declared XRM entity — inspect tickets with: octwin cases`);
+            }
+            die(`could not read records (HTTP ${status})${errDetail(json)}${status === 401 ? ` — ${authFailureHint(status, url)}` : ''}`);
+        }
         const rows = (json?.records ?? []);
         console.log(`${entity}: ${json?.total ?? rows.length} record(s)`);
         if (rows.length === 0)
@@ -586,44 +638,191 @@ async function cmdRecords(flags) {
         die(`could not read record (HTTP ${status})`);
     console.log(JSON.stringify(json?.record ?? json, null, 2));
 }
-/** `octwin logs [conversationId]` — list conversations or show one's event timeline. */
+/** `octwin logs [conversationId] [--as <handle>] [--json]` — list conversations
+ *  or show one's event timeline (full text + the renders each turn produced). */
 async function cmdLogs(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { url, tenant, project, token } = resolveTarget(flags, packDir);
     const base = `${url}/api/admin/tenants/${tenant}/projects/${project}`;
     const convId = flags._[0];
+    const asJson = flags.json === true;
+    const asHandle = typeof flags.as === 'string' ? flags.as : undefined;
     if (!convId) {
-        const { status, json } = await apiGet(`${base}/conversations?limit=20`, token);
+        const { status, json } = await apiGet(`${base}/conversations?limit=50`, token);
         if (status !== 200)
-            die(`could not read conversations (HTTP ${status})`);
-        const convs = (json?.conversations ?? []);
+            die(`could not read conversations (HTTP ${status})${errDetail(json)} — ${authFailureHint(status, url)}`);
+        let convs = (json?.conversations ?? []);
+        if (asHandle)
+            convs = convs.filter((c) => c.contact?.channel_contact_handle === asHandle);
         if (convs.length === 0) {
-            console.log('No conversations yet — try `octwin chat "hi"` first.');
+            console.log(asHandle ? `No conversations for handle '${asHandle}'.` : 'No conversations yet — try `octwin chat "hi"` first.');
             return;
         }
-        console.log(`Recent conversations in ${tenant}/${project}:`);
-        for (const c of convs)
-            console.log(`  ${c.id}  ${c.contact?.display_name ?? c.contact?.channel_contact_handle ?? '?'}  [${c.status}]`);
-        console.log('\nView a timeline:  octwin logs <conversationId>');
+        if (asJson) {
+            console.log(JSON.stringify(convs, null, 2));
+            return;
+        }
+        console.log(`Recent conversations in ${tenant}/${project}${asHandle ? ` (handle: ${asHandle})` : ''}:`);
+        for (const c of convs) {
+            const handle = c.contact?.channel_contact_handle ?? '?';
+            const name = c.contact?.display_name && c.contact.display_name !== handle ? ` (${c.contact.display_name})` : '';
+            const when = c.last_event_at ?? c.created_at ?? '';
+            console.log(`  ${c.id}  ${handle}${name}  [${c.status}]  ${when}`);
+        }
+        console.log('\nView a timeline:  octwin logs <conversationId>   (add --json for full payloads)');
         return;
     }
     const { status, json } = await apiGet(`${base}/conversations/${encodeURIComponent(convId)}`, token);
     if (status === 404)
         die(`conversation '${convId}' not found`);
     if (status !== 200)
-        die(`could not read conversation (HTTP ${status})`);
+        die(`could not read conversation (HTTP ${status})${errDetail(json)} — ${authFailureHint(status, url)}`);
     const events = (json?.events ?? []);
+    if (asJson) {
+        console.log(JSON.stringify(events, null, 2));
+        return;
+    }
     console.log(`Timeline for ${convId} (${events.length} events):`);
     for (const e of events) {
         const isErr = e.type === 'tool' && e.subtype === 'platform_error';
         const tag = isErr ? '⚠ ERROR' : `${e.type}${e.subtype ? `/${e.subtype}` : ''}`;
         const body = typeof e.content === 'string' ? e.content : JSON.stringify(e.content ?? '');
-        console.log(`  ${e.ts ?? ''}  ${tag}: ${(body ?? '').slice(0, 240)}`);
+        console.log(`  ${e.ts ?? ''}  ${tag}: ${body ?? ''}`);
+        // The renders this turn actually sent (captured outbound payloads) — the
+        // other half of the story next to the structured tap lines.
+        const captured = Array.isArray(e.metadata?.raw) ? e.metadata.raw : [];
+        for (const p of captured) {
+            if (!p?.rendered)
+                continue;
+            console.log(`      ↳ rendered ${p.rendered.type ?? '?'}`);
+            printHint(p.rendered, '      ');
+        }
     }
+    console.log('\nVerbatim LLM-thread payloads: --json, or GET …/conversations/<id>/mastra-messages');
 }
-/** `octwin chat "message" [--as <handle>]` — drive ONE turn through the dev web
- *  channel and print the agent's reply. The web channel is unauthenticated, so no
- *  token is required here. */
+// ── chat: render printing + SSE frame plumbing ──────────────────────────────
+/** Print a render hint's FULL interactive content — every row/button with its
+ *  tap id, so a follow-up `octwin chat --tap "<id>"` can press it. */
+function printHint(hint, indent = '   ') {
+    if (!hint || typeof hint !== 'object')
+        return;
+    const out = (s) => console.log(`${indent}${s}`);
+    if (hint.header)
+        out(`─ ${hint.header}`);
+    switch (hint.type) {
+        case 'buttons':
+            for (const b of hint.buttons ?? [])
+                out(`[btn] ${b.title}   tap: ${b.id}`);
+            break;
+        case 'list':
+            for (const s of hint.sections ?? []) {
+                if (s.title)
+                    out(`── ${s.title}`);
+                for (const r of s.rows ?? []) {
+                    out(`[row] ${r.title}${r.description ? ` — ${r.description}` : ''}`);
+                    out(`      tap: ${r.id}`);
+                }
+            }
+            if (hint.button_text)
+                out(`(list button: ${hint.button_text})`);
+            break;
+        case 'carousel':
+            (hint.cards ?? []).forEach((c, i) => {
+                out(`[card ${i + 1}] ${c.body}`);
+                for (const b of c.buttons ?? []) {
+                    if (b.type === 'url')
+                        out(`          [link] ${b.title} → ${b.url}`);
+                    else
+                        out(`          [btn] ${b.title}   tap: ${b.id}`);
+                }
+            });
+            break;
+        case 'cta_url':
+            out(`[link] ${hint.label} → ${hint.url}`);
+            break;
+        case 'flow':
+            out(`[flow form] ${hint.cta_text}   (flow_id: ${hint.flow_id})`);
+            break;
+        default:
+            // text / commerce variants — the body line already carries the substance.
+            break;
+    }
+    if (hint.footer)
+        out(`─ ${hint.footer}`);
+}
+/** Incremental SSE reader: buffers chunks, yields parsed `{ id, ev }` frames,
+ *  and supports racing a read against a settle-window timeout WITHOUT losing
+ *  data (the pending read is kept and re-raced — never issued twice). */
+class SseFrameReader {
+    reader;
+    buf = '';
+    decoder = new TextDecoder();
+    pending = null;
+    queue = [];
+    constructor(reader) {
+        this.reader = reader;
+    }
+    /** Release the underlying stream (the body is locked to our reader). */
+    async cancel() {
+        try {
+            await this.reader.cancel();
+        }
+        catch { /* already closed */ }
+    }
+    /** Next frame, or 'timeout' after `ms` of silence, or 'done' when the stream ends. */
+    async next(ms) {
+        for (;;) {
+            const queued = this.queue.shift();
+            if (queued)
+                return queued;
+            this.pending ??= this.reader.read();
+            const TIMEOUT = Symbol('timeout');
+            const winner = await Promise.race([
+                this.pending,
+                new Promise((res) => setTimeout(() => res(TIMEOUT), ms).unref?.()),
+            ]);
+            if (winner === TIMEOUT)
+                return 'timeout';
+            this.pending = null;
+            const { done, value } = winner;
+            if (done)
+                return 'done';
+            this.buf += this.decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = this.buf.indexOf('\n\n')) >= 0) {
+                const frame = this.buf.slice(0, idx);
+                this.buf = this.buf.slice(idx + 2);
+                const lines = frame.split('\n');
+                const dataLine = lines.find((l) => l.startsWith('data:'));
+                if (!dataLine)
+                    continue; // heartbeat comments etc.
+                const idLine = lines.find((l) => l.startsWith('id:'));
+                const id = idLine ? parseInt(idLine.slice(3).trim(), 10) : null;
+                let ev;
+                try {
+                    ev = JSON.parse(dataLine.slice(5).trim());
+                }
+                catch {
+                    continue;
+                }
+                this.queue.push({ id: Number.isFinite(id) ? id : null, ev });
+            }
+        }
+    }
+}
+const REPLAY_SETTLE_MS = 400; // quiet gap that marks the end of the connect replay burst
+const TURN_SETTLE_MS = 2_000; // quiet gap after a render = the turn finished sending
+const REPLY_TIMEOUT_MS = 45_000; // hard cap waiting for the first render of the turn
+/** `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--json]` — drive one
+ *  turn through the dev web channel and print everything it rendered.
+ *
+ *  Multi-turn works: the platform keeps ONE open conversation per handle, so the
+ *  same `--as` continues the same conversation. Two traps this command handles:
+ *  (1) the platform dedups inbound on `local_id` for 5 minutes — so we mint a
+ *  FRESH id per call (a constant id made consecutive calls silent no-ops);
+ *  (2) a fresh SSE connect REPLAYS recent history (the ring buffer) — so we
+ *  drain the replay first and only accept frames newer than it as the reply
+ *  (naively printing the first render showed LAST turn's message again). */
 async function cmdChat(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const cfg = readPackConfig(packDir);
@@ -635,84 +834,162 @@ async function cmdChat(flags) {
     if (!tenant)
         die('no tenant — set it in pack.json, --tenant, or PACK_TENANT');
     const from = flags.as ?? 'cli-tester';
+    const asJson = flags.json === true;
+    const tapId = typeof flags.tap === 'string' ? flags.tap : undefined;
     const message = flags._[0];
-    if (!message)
-        die('usage: octwin chat "your message" [--as <handle>]');
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), 30_000);
-    let evRes;
-    try {
-        evRes = await fetch(`${url}/api/web/events/${tenant}/${project}/${encodeURIComponent(from)}`, { headers: { accept: 'text/event-stream' }, signal: ctrl.signal });
-    }
-    catch (err) {
-        clearTimeout(timer);
-        die(`could not open chat stream: ${err?.message ?? err}`);
-        return;
-    }
-    if (!evRes.ok || !evRes.body) {
-        clearTimeout(timer);
+    if (!message && !tapId)
+        die('usage: octwin chat "your message" [--as <handle>] [--tap <tap-id>] [--json]');
+    // Fresh idempotency key per call (see the command doc above).
+    const localId = `cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const evRes = await fetchOrDie(`${url}/api/web/events/${tenant}/${project}/${encodeURIComponent(from)}`, { headers: { accept: 'text/event-stream' } }, 'open chat stream');
+    if (!evRes.ok || !evRes.body)
         die(`could not open chat stream (HTTP ${evRes.status})`);
-        return;
+    const frames = new SseFrameReader(evRes.body.getReader());
+    const cancel = () => frames.cancel();
+    // Phase 1 — drain the connect replay; remember the highest sequence id.
+    // Frames at or below it are history, not this turn's reply.
+    let boundary = 0;
+    for (;;) {
+        const f = await frames.next(REPLAY_SETTLE_MS);
+        if (f === 'timeout')
+            break;
+        if (f === 'done') {
+            await cancel();
+            die('chat stream closed before the message was sent');
+        }
+        if (f.id != null && f.id > boundary)
+            boundary = f.id;
     }
-    console.log(`→ [${from}] ${message}`);
-    await fetch(`${url}/api/web/inbound/${tenant}/${project}`, {
+    // Phase 2 — send the inbound (text, or an interactive tap).
+    console.log(`→ [${from}] ${tapId ? `(tap) ${tapId}` : message}`);
+    const body = tapId
+        ? { type: 'interactive', from, tap_id: tapId, ...(message ? { raw_title: message } : {}), local_id: localId }
+        : { type: 'text', from, text: message, local_id: localId };
+    const postRes = await fetchOrDie(`${url}/api/web/inbound/${tenant}/${project}`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ type: 'text', from, text: message, local_id: `cli-${from}` }),
-    }).catch((err) => { clearTimeout(timer); die(`could not send message: ${err?.message ?? err}`); });
-    const reader = evRes.body.getReader();
-    const decoder = new TextDecoder();
-    let buf = '';
-    let gotReply = false;
-    try {
-        outer: for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
+        body: JSON.stringify(body),
+    }, 'send message');
+    if (!postRes.ok) {
+        await cancel();
+        die(`send rejected (HTTP ${postRes.status}): ${await postRes.text()}`);
+    }
+    // Phase 3 — collect THIS turn's renders (id > boundary). A turn can send
+    // several messages, so keep reading until a quiet gap after the last render.
+    const deadline = Date.now() + REPLY_TIMEOUT_MS;
+    let rendersSeen = 0;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        const f = await frames.next(rendersSeen > 0 ? TURN_SETTLE_MS : Math.min(remaining, REPLY_TIMEOUT_MS));
+        if (f === 'timeout') {
+            if (rendersSeen > 0)
                 break;
-            buf += decoder.decode(value, { stream: true });
-            let idx;
-            while ((idx = buf.indexOf('\n\n')) >= 0) {
-                const frame = buf.slice(0, idx);
-                buf = buf.slice(idx + 2);
-                const line = frame.split('\n').find((l) => l.startsWith('data:'));
-                if (!line)
-                    continue;
-                let ev;
-                try {
-                    ev = JSON.parse(line.slice(5).trim());
-                }
-                catch {
-                    continue;
-                }
-                if (ev.kind === 'render') {
-                    console.log(`← ${ev.body ?? '(no text body)'}`);
-                    const hint = ev.hint;
-                    if (hint?.buttons?.length)
-                        console.log(`   [buttons: ${hint.buttons.map((b) => b.title).join(' | ')}]`);
-                    if (hint?.sections?.length || hint?.rows?.length)
-                        console.log('   [a list picker was rendered]');
-                    gotReply = true;
-                    break outer;
-                }
-            }
+            else
+                continue;
+        }
+        if (f === 'done')
+            break;
+        if (f.id != null && f.id <= boundary)
+            continue; // late replay stragglers
+        if (asJson) {
+            console.log(JSON.stringify(f.ev));
+            if (f.ev?.kind === 'render')
+                rendersSeen++;
+            continue;
         }
+        if (f.ev?.kind !== 'render')
+            continue; // status/typing noise
+        rendersSeen++;
+        console.log(`← ${f.ev.body ?? '(no text body)'}${f.ev.hint?.type && f.ev.hint.type !== 'text' ? `   (render: ${f.ev.hint.type})` : ''}`);
+        printHint(f.ev.hint);
     }
-    catch (err) {
-        if (ctrl.signal.aborted)
-            console.error('  (timed out after 30s waiting for a reply)');
-        else
-            console.error(`  (stream error: ${err?.message ?? err})`);
+    await cancel();
+    if (rendersSeen === 0) {
+        console.error(`  no reply after ${Math.round(REPLY_TIMEOUT_MS / 1000)}s — the pack may not be warm yet, or the turn produced no render.`);
+        process.exit(1);
     }
-    finally {
-        clearTimeout(timer);
-        try {
-            await reader.cancel();
+    console.log(`\n(same --as '${from}' continues this conversation — timeline: octwin logs --as ${from})`);
+}
+/** `octwin cases [caseId] [--queues]` — inspect casework (support tickets):
+ *  the aggregate inbox, one case + its timeline, or the queue list. */
+async function cmdCases(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const { url, tenant, project, token } = resolveTarget(flags, packDir);
+    const base = `${url}/api/admin/tenants/${tenant}/projects/${project}`;
+    const caseId = flags._[0];
+    const asJson = flags.json === true;
+    const caseFail = (what, status, json) => {
+        if (status === 403)
+            die(`forbidden — casework needs the 'cases' plan feature on this tenant, and a role whose grants reach the queue`);
+        die(`could not read ${what} (HTTP ${status})${errDetail(json)}${status === 401 ? ` — ${authFailureHint(status, url)}` : ''}`);
+    };
+    if (flags.queues === true) {
+        const { status, json } = await apiGet(`${base}/case-queues`, token);
+        if (status !== 200)
+            caseFail('case queues', status, json);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
         }
-        catch { /* ignore */ }
+        const queues = (json?.queues ?? []);
+        console.log(`Case queues in ${tenant}/${project}:`);
+        for (const q of queues)
+            console.log(`  ${q.key}${q.name ? `  (${q.name})` : ''}  ${q.open_count} open`);
+        if (json?.unrouted_open_count)
+            console.log(`  (unrouted: ${json.unrouted_open_count} open)`);
+        return;
     }
-    if (!gotReply) {
-        console.error('  no reply — the pack may not be warm yet, or the turn produced no render.');
-        process.exit(1);
+    if (!caseId) {
+        const limit = flags.limit ?? '50';
+        const { status, json } = await apiGet(`${base}/cases?limit=${limit}`, token);
+        if (status !== 200)
+            caseFail('cases', status, json);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const rows = (json?.cases ?? []);
+        console.log(`Cases in ${tenant}/${project}: ${json?.total ?? rows.length} total`);
+        if (rows.length === 0)
+            console.log('  (none)');
+        for (const c of rows) {
+            const sla = c.sla_due_at ? `  sla:${c.sla_due_at}` : '';
+            console.log(`  #${c.case_number ?? '?'}  ${c.type}  [${c.status}]  ${c.priority}${c.queue_key ? `  q:${c.queue_key}` : ''}${sla}  ${c.id}`);
+        }
+        console.log('\nOne case + timeline:  octwin cases <caseId>    queues:  octwin cases --queues');
+        return;
+    }
+    const { status, json } = await apiGet(`${base}/cases/${encodeURIComponent(caseId)}`, token);
+    if (status === 404)
+        die(`case '${caseId}' not found`);
+    if (status !== 200)
+        caseFail('case', status, json);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const c = json?.case ?? {};
+    console.log(`Case #${c.case_number ?? '?'}  ${c.type}  [${c.status}]  ${c.priority}`);
+    console.log(`  id: ${c.id}   queue: ${c.queue_key ?? '(unrouted)'}   assignee: ${c.assignee_principal ?? '(none)'}`);
+    if (json?.contact)
+        console.log(`  contact: ${json.contact.display_name ?? json.contact.channel_contact_handle ?? json.contact.id}`);
+    if (c.conversation_id)
+        console.log(`  conversation: ${c.conversation_id}   (octwin logs ${c.conversation_id})`);
+    if (c.sla_due_at)
+        console.log(`  sla due: ${c.sla_due_at}`);
+    if (c.fields && Object.keys(c.fields).length > 0)
+        console.log(`  fields: ${JSON.stringify(c.fields)}`);
+    const events = (json?.events ?? []);
+    console.log(`  Timeline (${events.length}):`);
+    for (const e of events) {
+        const payload = e.payload && Object.keys(e.payload).length > 0 ? `  ${JSON.stringify(e.payload)}` : '';
+        console.log(`    ${e.ts ?? ''}  ${e.kind}${e.actor ? ` (${e.actor})` : ''}${payload}`);
+    }
+    const dispositions = (json?.dispositions ?? []);
+    if (dispositions.length > 0) {
+        console.log(`  Decisions: ${dispositions.map((d) => `${d.action}${d.next_status ? `→${d.next_status}` : ''}`).join(', ')}`);
     }
 }
 function help() {
@@ -726,18 +1003,67 @@ function help() {
   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
   octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
   octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
-  octwin logs    [conversationId]                        # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>]               # drive one turn through the web channel + print the reply
+  octwin cases   [caseId] [--queues] [--json]            # inspect casework (support tickets) + timelines
+  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
+  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--json]  # drive a turn + print every render
   octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   octwin test    [--dir .]                               # = validate --remote (the full platform check)
 
+Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
+\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
+button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
 Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
 octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
-Config (deploy): flags > pack.json > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login.`);
+Config (deploy): flags > pack.json > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login.
+Per-command usage: octwin <command> --help`);
 }
+/** Per-subcommand usage — printed for `octwin <cmd> --help|-h` BEFORE any
+ *  network/auth work (a --help that 401s is worse than no help at all). */
+const COMMAND_HELP = {
+    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+  Scaffold a pure-YAML starter pack into <dir>.`,
+    validate: `octwin validate [--dir .] [--remote]
+  Offline structural check; --remote additionally runs the platform's FULL
+  manifest + flow-DSL validation (all errors at once) — same check as deploy.`,
+    login: `octwin login --url <platformUrl> --token oct_…
+  Save a deploy token (console → Settings → API tokens) for that platform url.`,
+    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
+  Verify the resolved token authenticates against the tenant.`,
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+  Upload the pack bundle, validate server-side, install onto the project.
+  --seed additionally applies the pack's demo seed (streams progress).`,
+    status: `octwin status [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+  Show installed vs live version + the flow list for this pack.`,
+    records: `octwin records [entity] [id] [--limit 50]
+  Inspect the pack's XRM data. No args = list entities. Cases/tickets are
+  casework, not XRM — use \`octwin cases\` for those.`,
+    cases: `octwin cases [caseId] [--queues] [--limit 50] [--json]
+  Inspect casework (support tickets): the inbox, one case + its timeline
+  (+ applicable decisions), or --queues for queue keys + open counts.`,
+    logs: `octwin logs [conversationId] [--as <handle>] [--json]
+  No id = recent conversations (handle, status, last activity; --as filters).
+  With id = the full event timeline including what each turn rendered.
+  --json = raw events (verbatim payloads).`,
+    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--json]
+  Drive one turn through the dev web channel and print every render with its
+  tap ids. Same --as handle = same conversation (multi-turn works).
+  --tap presses a rendered button/list row instead of sending text.
+  --json dumps the raw SSE envelopes for the turn.`,
+    'platform-kb': `octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
+  Pull the platform capability reference (markdown + JSON catalogs) into
+  .octwin/platform-kb/ for the octwin-pack authoring skill.`,
+    test: `octwin test [--dir .]
+  Alias for \`octwin validate --remote\` — the full platform check.`,
+};
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
+    // Per-subcommand --help/-h — intercepted BEFORE the command runs, so help can
+    // never hit the network or die on auth (author-feedback A8).
+    if (command && command in COMMAND_HELP && (flags.help === true || flags._.includes('-h'))) {
+        console.log(COMMAND_HELP[command]);
+        return;
+    }
     switch (command) {
         case 'init':
             cmdInit(flags);
@@ -760,6 +1086,9 @@ async function main() {
         case 'records':
             await cmdRecords(flags);
             break;
+        case 'cases':
+            await cmdCases(flags);
+            break;
         case 'logs':
             await cmdLogs(flags);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {