octwin-cli 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -1,83 +1,107 @@
-# Changelog — octwin-cli
-
-All notable changes to the `octwin` CLI (npm package [`octwin-cli`](https://www.npmjs.com/package/octwin-cli)).
-Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucketed into
-**Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
-repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
-
-## [0.1.10] - 2026-07-21
-
-The capability reference is now **pulled, never bundled** — the authoring skill dropped its committed KB
-snapshot, so `octwin platform-kb pull` is the single source of truth, and the CLI watches it for drift.
-
-### Added
-- **KB-drift nudge** — after any command that already talks to the platform (`deploy` / `status` /
-  `test` / `validate --remote` / `records` / `cases` / `logs` / `whoami`), the CLI does one tiny
-  `octwin-platform-kb?meta=1` GET and prints a one-line "the platform capability reference changed —
-  `octwin platform-kb pull`" when the platform's `content_hash` no longer matches your last pull.
-  Fail-silent + TTY-only + no-op until you've pulled once — the sibling of the existing CLI-upgrade notice.
-
-### Changed
-- **`octwin platform-kb pull`** now records the reference's `content_hash` in `.octwin/platform-kb/index.json`
-  (the fingerprint the drift check compares against).
-
-The conversation-debugging release — driven by the second author-feedback round (xpeng-egypt),
-which found the author→validate→deploy loop solid but multi-turn debugging impossible from the CLI.
-
-### Added
-- **`octwin chat --tap "<tap-id>"`** — press a rendered button / list row (sends the web channel's
-  `type:'interactive'` inbound). Paired with full render printing, any tap-driven flow is now drivable headlessly.
-- **Full render printing** — every reply prints its complete interactive content: list sections/rows,
-  buttons, and carousel cards, each with its **tap id**; header/footer/list-button text included.
-- **`--json` on `chat` / `logs` / `cases`** — raw SSE envelopes (chat) or raw event/case payloads.
-- **`octwin cases [caseId] [--queues]`** — inspect casework (support tickets): the inbox, one case +
-  timeline + applicable decisions, or queue keys with open counts. Casework packs previously had zero
-  data-inspection path (`records case` was a dead end).
-- **Per-subcommand `--help`/`-h`** — intercepted before any network or auth work (previously
-  `octwin logs --help` made a network call and could die with a 401).
-- Multi-message turns: `chat` now collects **all** of a turn's renders (quiet-gap detection) instead
-  of cutting at the first one.
-
-### Changed
-- **`octwin logs`**: the conversation list shows contact handle + last activity and filters with
-  `--as <handle>`; the timeline prints **full** event text (no more 240-char truncation) plus the
-  renders each turn actually sent; footer points at `--json` / `mastra-messages` for verbatim payloads.
-- **Network failures name the target URL** (`platform unreachable at <url>`), and 401s explain
-  invalid-token vs one-off transient instead of a bare status code.
-- `octwin records` on an unknown entity now surfaces the server's error body, and for `case`/`cases`
-  points at `octwin cases`.
-
-### Fixed
-- **Multi-turn chat actually works.** Two bugs made consecutive `octwin chat` calls look like "every
-  call starts fresh": (1) the idempotency `local_id` was a **constant** per handle, so the platform's
-  5-minute inbound dedup silently dropped the second message — a fresh id is now minted per call;
-  (2) a fresh SSE connect **replays** recent history and the CLI printed the first render frame — i.e.
-  the *previous* turn's greeting — as the reply; the CLI now drains the replay and only accepts frames
-  newer than the connect boundary. The platform always kept one open conversation per `--as` handle —
-  the same handle genuinely continues the same conversation now.
-
-## [0.1.8] - 2026-07-21
-- Global-first install guidance (`npm i -g octwin-cli`); upgrade notice suppressed under `npx`.
-
-## [0.1.7] - 2026-07-21
-- `--version`/`-v` flag; daily fail-silent, TTY-only "newer version available" notice.
-
-## [0.1.6] - 2026-07-21
-- `octwin init` scaffolds a home-hub menu (`home` list_picker + example `browse` tool) instead of a bare greeting.
-
-## [0.1.5] - 2026-07-20
-- `octwin validate --remote` (the platform's FULL manifest + flow-DSL check, all errors at once);
-  headless debugging commands `octwin records` / `octwin logs` / `octwin chat`; `octwin test` became
-  an alias for `validate --remote`. First author-feedback round.
-
-## [0.1.4] - 2026-07-20
-- Authoring reliability + DX fixes from the first end-to-end external-pack test.
-
-## [0.1.3] - 2026-07-20
-- `octwin platform-kb pull` — pull the platform capability reference for the authoring skill.
-
-## [0.1.2] - 2026-07-20
-- Proper npm README.
-
-## [0.1.1] - 2026-07-20
-- Initial npm publish: `init` / `validate` / `login` / `whoami` / `deploy` / `status`, `oct_` deploy tokens.
+# Changelog — octwin-cli
+
+All notable changes to the `octwin` CLI (npm package [`octwin-cli`](https://www.npmjs.com/package/octwin-cli)).
+Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucketed into
+**Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
+repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
+
+## [0.1.12] - 2026-07-22
+
+### Fixed
+- **The KB-drift nudge now fires after `chat` too.** `chat` — the command a debugging session runs most —
+  was missing from the networked-command list, so a chat-heavy session never noticed the platform's
+  capability reference had moved. The nudge also now shows the concrete drift
+  (`old-hash → new-hash`) so you can see it's real, not a heuristic.
+
+### Changed
+- **Every networked command announces what it's doing before it does it.** `chat` prints
+  `→ Connecting to <tenant>/<project> as '<handle>' …` before opening the stream and
+  `… delivered — waiting for the reply (up to Ns)` after the send; `status` / `whoami` /
+  `platform-kb` / `records` / `logs` / `cases` each print a one-line `→ …` header naming the
+  action and target before the first network call — no more silent seconds followed by a result
+  (or a hang with no clue what was being attempted). JSON modes (`--json`) stay clean for piping.
+
+## [0.1.11] - 2026-07-21
+
+### Fixed
+- **Auth-failure hint on every command, not just the inspect family** (author-feedback A7). `validate`,
+  `deploy`, `status`, and the single-record read now print the scope/transient explanation on a 401/403
+  (the shared `authFailureHint`), instead of a bare `HTTP 401` that left it ambiguous whether the token
+  lacked a scope or the platform hiccupped.
+
+## [0.1.10] - 2026-07-21
+
+The capability reference is now **pulled, never bundled** — the authoring skill dropped its committed KB
+snapshot, so `octwin platform-kb pull` is the single source of truth, and the CLI watches it for drift.
+
+### Added
+- **KB-drift nudge** — after any command that already talks to the platform (`deploy` / `status` /
+  `test` / `validate --remote` / `records` / `cases` / `logs` / `whoami`), the CLI does one tiny
+  `octwin-platform-kb?meta=1` GET and prints a one-line "the platform capability reference changed —
+  `octwin platform-kb pull`" when the platform's `content_hash` no longer matches your last pull.
+  Fail-silent + TTY-only + no-op until you've pulled once — the sibling of the existing CLI-upgrade notice.
+
+### Changed
+- **`octwin platform-kb pull`** now records the reference's `content_hash` in `.octwin/platform-kb/index.json`
+  (the fingerprint the drift check compares against).
+
+The conversation-debugging release — driven by the second author-feedback round (xpeng-egypt),
+which found the author→validate→deploy loop solid but multi-turn debugging impossible from the CLI.
+
+### Added
+- **`octwin chat --tap "<tap-id>"`** — press a rendered button / list row (sends the web channel's
+  `type:'interactive'` inbound). Paired with full render printing, any tap-driven flow is now drivable headlessly.
+- **Full render printing** — every reply prints its complete interactive content: list sections/rows,
+  buttons, and carousel cards, each with its **tap id**; header/footer/list-button text included.
+- **`--json` on `chat` / `logs` / `cases`** — raw SSE envelopes (chat) or raw event/case payloads.
+- **`octwin cases [caseId] [--queues]`** — inspect casework (support tickets): the inbox, one case +
+  timeline + applicable decisions, or queue keys with open counts. Casework packs previously had zero
+  data-inspection path (`records case` was a dead end).
+- **Per-subcommand `--help`/`-h`** — intercepted before any network or auth work (previously
+  `octwin logs --help` made a network call and could die with a 401).
+- Multi-message turns: `chat` now collects **all** of a turn's renders (quiet-gap detection) instead
+  of cutting at the first one.
+
+### Changed
+- **`octwin logs`**: the conversation list shows contact handle + last activity and filters with
+  `--as <handle>`; the timeline prints **full** event text (no more 240-char truncation) plus the
+  renders each turn actually sent; footer points at `--json` / `mastra-messages` for verbatim payloads.
+- **Network failures name the target URL** (`platform unreachable at <url>`), and 401s explain
+  invalid-token vs one-off transient instead of a bare status code.
+- `octwin records` on an unknown entity now surfaces the server's error body, and for `case`/`cases`
+  points at `octwin cases`.
+
+### Fixed
+- **Multi-turn chat actually works.** Two bugs made consecutive `octwin chat` calls look like "every
+  call starts fresh": (1) the idempotency `local_id` was a **constant** per handle, so the platform's
+  5-minute inbound dedup silently dropped the second message — a fresh id is now minted per call;
+  (2) a fresh SSE connect **replays** recent history and the CLI printed the first render frame — i.e.
+  the *previous* turn's greeting — as the reply; the CLI now drains the replay and only accepts frames
+  newer than the connect boundary. The platform always kept one open conversation per `--as` handle —
+  the same handle genuinely continues the same conversation now.
+
+## [0.1.8] - 2026-07-21
+- Global-first install guidance (`npm i -g octwin-cli`); upgrade notice suppressed under `npx`.
+
+## [0.1.7] - 2026-07-21
+- `--version`/`-v` flag; daily fail-silent, TTY-only "newer version available" notice.
+
+## [0.1.6] - 2026-07-21
+- `octwin init` scaffolds a home-hub menu (`home` list_picker + example `browse` tool) instead of a bare greeting.
+
+## [0.1.5] - 2026-07-20
+- `octwin validate --remote` (the platform's FULL manifest + flow-DSL check, all errors at once);
+  headless debugging commands `octwin records` / `octwin logs` / `octwin chat`; `octwin test` became
+  an alias for `validate --remote`. First author-feedback round.
+
+## [0.1.4] - 2026-07-20
+- Authoring reliability + DX fixes from the first end-to-end external-pack test.
+
+## [0.1.3] - 2026-07-20
+- `octwin platform-kb pull` — pull the platform capability reference for the authoring skill.
+
+## [0.1.2] - 2026-07-20
+- Proper npm README.
+
+## [0.1.1] - 2026-07-20
+- Initial npm publish: `init` / `validate` / `login` / `whoami` / `deploy` / `status`, `oct_` deploy tokens.

package/dist/index.js

@@ -98,6 +98,13 @@ function authFailureHint(status, url) {
         ? `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)`;
 }
+/** Print the auth-scope hint below an HTTP-failure line when it's a 401/403 —
+ *  so every command explains a token problem, not just the inspect family
+ *  (author-feedback A7). No-op for other statuses. */
+function printAuthHint(status, url) {
+    if (status === 401 || status === 403)
+        console.error(`  → ${authFailureHint(status, url)}`);
+}
 /** Pretty-print a JSON error body (or raw text) for an HTTP failure line. */
 function errDetail(json) {
     if (json == null)
@@ -275,20 +282,22 @@ async function notifyIfKbStale(flags) {
             return;
         const meta = await res.json();
         if (meta.content_hash && meta.content_hash !== localHash) {
-            console.error('\n⬆ the platform capability reference changed since you last pulled it.');
-            console.error('  Refresh it: octwin platform-kb pull');
+            console.error(`\n⬆ the platform capability reference changed since you last pulled it (${localHash} → ${meta.content_hash}).`);
+            console.error('  Refresh it: octwin platform-kb');
         }
     }
     catch { /* a KB check must never break the CLI */ }
 }
-/** Which commands already made an authed platform call, so the trailing KB-drift
- *  poll rides on existing network work (never on offline `validate` / `init`). */
+/** Which commands already made a platform call, so the trailing KB-drift poll
+ *  rides on existing network work (never on offline `validate` / `init`;
+ *  `platform-kb` refreshes the reference itself, so it needs no nudge). */
 function commandTouchesPlatform(command, flags) {
     switch (command) {
         case 'validate': return flags.remote === true; // offline validate stays offline
         case 'deploy':
         case 'status':
         case 'test':
+        case 'chat':
         case 'records':
         case 'cases':
         case 'logs':
@@ -379,6 +388,7 @@ async function cmdValidate(flags) {
         if (res.status === 404)
             die('this platform has no /packs/validate endpoint yet (older version) — deploy runs the full check');
         console.error(`✗ remote validate failed (HTTP ${res.status})`);
+        printAuthHint(res.status, url);
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         process.exit(1);
     }
@@ -440,6 +450,7 @@ function resolveTargetOrNull(flags, packDir) {
 async function cmdWhoami(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { url, tenant, token } = resolveTarget(flags, packDir);
+    console.log(`→ Checking the saved token against '${tenant}' @ ${url} …`);
     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'})`);
@@ -545,6 +556,7 @@ async function cmdDeploy(flags) {
     }
     if (!res.ok) {
         console.error(`✗ deploy failed (HTTP ${res.status})`);
+        printAuthHint(res.status, url);
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         process.exit(1);
     }
@@ -561,6 +573,7 @@ async function cmdStatus(flags) {
         die('manifest.yaml must declare a string `id`');
     const id = doc.id;
     const localVersion = typeof doc?.version === 'string' ? doc.version : '?';
+    console.log(`→ Checking ${id}@${localVersion} on ${tenant}/${project} @ ${url} …`);
     const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/projects/${project}/packs/${id}/runtime`, {
         headers: { authorization: `Bearer ${token}` },
     }, 'status check');
@@ -576,6 +589,7 @@ async function cmdStatus(flags) {
         if (res.status === 404)
             die(`'${id}' is not installed on ${tenant}/${project} yet — run \`octwin deploy\` first`);
         console.error(`✗ status check failed (HTTP ${res.status})`);
+        printAuthHint(res.status, url);
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         process.exit(1);
     }
@@ -599,6 +613,7 @@ async function cmdStatus(flags) {
 async function cmdPlatformKb(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { url, tenant, token } = resolveTarget(flags, packDir);
+    console.log(`→ Pulling the platform capability reference from '${tenant}' @ ${url} …`);
     const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/octwin-platform-kb`, {
         headers: { authorization: `Bearer ${token}` },
     }, 'platform-kb pull');
@@ -664,6 +679,7 @@ async function cmdRecords(flags) {
     const base = `${url}/api/admin/tenants/${tenant}/projects/${project}`;
     const entity = flags._[0];
     const recordId = flags._[1];
+    console.log(`→ Reading ${recordId ? `${entity} record ${recordId}` : entity ? `${entity} records` : 'the entity catalog'} from ${tenant}/${project} …`);
     if (!entity) {
         const { status, json } = await apiGet(`${base}/xrm/entities`, token);
         if (status !== 200)
@@ -709,6 +725,8 @@ async function cmdRecords(flags) {
         die('forbidden — mint a token with the `records:read` scope');
     if (status === 404)
         die(`record '${recordId}' not found`);
+    if (status === 401)
+        die(`could not read record — ${authFailureHint(401, url)}`);
     if (status !== 200)
         die(`could not read record (HTTP ${status})`);
     console.log(JSON.stringify(json?.record ?? json, null, 2));
@@ -722,6 +740,8 @@ async function cmdLogs(flags) {
     const convId = flags._[0];
     const asJson = flags.json === true;
     const asHandle = typeof flags.as === 'string' ? flags.as : undefined;
+    if (!asJson)
+        console.log(`→ Reading ${convId ? `conversation ${convId}` : 'recent conversations'} from ${tenant}/${project} …`);
     if (!convId) {
         const { status, json } = await apiGet(`${base}/conversations?limit=50`, token);
         if (status !== 200)
@@ -916,6 +936,8 @@ async function cmdChat(flags) {
         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)}`;
+    if (!asJson)
+        console.log(`→ Connecting to ${tenant}/${project} as '${from}' …`);
     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})`);
@@ -949,6 +971,8 @@ async function cmdChat(flags) {
         await cancel();
         die(`send rejected (HTTP ${postRes.status}): ${await postRes.text()}`);
     }
+    if (!asJson)
+        console.log(`  … delivered — waiting for the reply (up to ${Math.round(REPLY_TIMEOUT_MS / 1000)}s)`);
     // 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;
@@ -995,6 +1019,8 @@ async function cmdCases(flags) {
     const base = `${url}/api/admin/tenants/${tenant}/projects/${project}`;
     const caseId = flags._[0];
     const asJson = flags.json === true;
+    if (!asJson)
+        console.log(`→ Reading ${flags.queues === true ? 'case queues' : caseId ? `case ${caseId}` : 'the case inbox'} from ${tenant}/${project} …`);
     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`);

package/package.json

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

package/templates/starter/manifest.yaml

@@ -41,3 +41,14 @@ agents:
     # relative; `.md` files may use built-in placeholders like {{pack.id}}.
     instructions:
       - file: prompts/identity.md
+    # No working_memory block — deliberate, and you should keep it that way.
+    # Declaring one makes the platform add Mastra's updateWorkingMemory tool +
+    # a "call it every turn" instruction: an extra LLM generation on most turns,
+    # and small models (like the lite default above) parrot the
+    # <working_memory_data> envelope straight into user-visible replies. Session
+    # identity (name/lang/phone) already reaches the model via the platform's
+    # first-turn [ctx: …] header, and tools read it from the request context —
+    # so you gain nothing here. Leave it off unless you're on a large model and
+    # have a concrete slot schema to maintain.
+    default_memory:
+      lastMessages: 10   # size of the recalled message window