octwin-cli 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# 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.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/README.md

@@ -143,7 +143,8 @@ needs **no database of its own**.
 ## Links
 
 - **npm:** <https://www.npmjs.com/package/octwin-cli>
-- **Command help:** `octwin help`
+- **Command help:** `octwin help` (each subcommand also answers `--help`)
+- **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
 
 ## License
 

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)
@@ -236,6 +243,66 @@ async function notifyIfOutdated() {
     }
     catch { /* a version check must never break the CLI */ }
 }
+// ── platform-KB drift check (observe the pulled reference, TTY-only, fail-silent) ──
+/** The `content_hash` of a previously-pulled KB in `<packDir>/.octwin/platform-kb/`,
+ *  or null if nothing has been pulled yet. */
+function readLocalKbHash(packDir) {
+    try {
+        const idx = JSON.parse(readFileSync(join(packDir, '.octwin', 'platform-kb', 'index.json'), 'utf8'));
+        return typeof idx.content_hash === 'string' ? idx.content_hash : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Nudge (to stderr) when the platform's capability KB has changed since the last
+ *  `octwin platform-kb pull`. The sibling of `notifyIfOutdated`, for the KB instead
+ *  of the CLI: run only after commands that already hit the platform, so this adds
+ *  a single tiny `?meta=1` GET on top of work that was networked anyway. Never
+ *  throws — observing must never break a command. No-op until the author has pulled
+ *  once (nothing to compare) or if the target/token can't be resolved. */
+async function notifyIfKbStale(flags) {
+    if (!process.stdout.isTTY)
+        return;
+    try {
+        const packDir = resolve(flags.dir ?? '.');
+        const localHash = readLocalKbHash(packDir);
+        if (!localHash)
+            return; // never pulled → the skill already says to pull
+        const t = resolveTargetOrNull(flags, packDir);
+        if (!t)
+            return;
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 2_000);
+        const res = await fetch(`${t.url}/api/admin/tenants/${t.tenant}/octwin-platform-kb?meta=1`, {
+            headers: { authorization: `Bearer ${t.token}` }, signal: ctrl.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            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');
+        }
+    }
+    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`). */
+function commandTouchesPlatform(command, flags) {
+    switch (command) {
+        case 'validate': return flags.remote === true; // offline validate stays offline
+        case 'deploy':
+        case 'status':
+        case 'test':
+        case 'records':
+        case 'cases':
+        case 'logs':
+        case 'whoami': return true;
+        default: return false;
+    }
+}
 // ── commands ────────────────────────────────────────────────────────────────
 function cmdInit(flags) {
     const target = flags._[0] ?? die('usage: octwin init <dir> [--id my-pack]');
@@ -319,6 +386,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);
     }
@@ -364,6 +432,19 @@ function resolveTarget(flags, packDir) {
         die('no token — generate a deploy token in the console (Settings → API tokens), then `octwin login --url <url> --token oct_…` or pass --token');
     return { url, tenant, project, token };
 }
+/** Non-fatal `resolveTarget`: returns null (never dies) when any of url/tenant/token
+ *  is missing. Used by the fail-silent KB-staleness observer, which must never
+ *  interrupt a command over a config gap. */
+function resolveTargetOrNull(flags, packDir) {
+    const cfg = readPackConfig(packDir);
+    const url = (flags.url ?? process.env.PACK_PLATFORM_URL ?? cfg.platform_url ?? '').replace(/\/$/, '');
+    const tenant = flags.tenant ?? process.env.PACK_TENANT ?? cfg.tenant ?? '';
+    const project = flags.project ?? process.env.PACK_PROJECT ?? cfg.project ?? 'main';
+    const token = flags.token ?? process.env.PACK_TOKEN ?? readCreds()[url] ?? '';
+    if (!url || !tenant || !token)
+        return null;
+    return { url, tenant, project, token };
+}
 async function cmdWhoami(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { url, tenant, token } = resolveTarget(flags, packDir);
@@ -472,6 +553,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);
     }
@@ -503,6 +585,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);
     }
@@ -561,7 +644,9 @@ async function cmdPlatformKb(flags) {
         writeFileSync(join(outDir, `${key}.json`), JSON.stringify(val, null, 2) + '\n', 'utf8');
         jsonCount++;
     }
-    writeFileSync(join(outDir, 'index.json'), JSON.stringify({ version: bundle.version, generated_at: bundle.generated_at, index: bundle.index }, null, 2) + '\n', 'utf8');
+    // Persist `content_hash` too — the staleness observer (`notifyIfKbStale`) reads
+    // it back and compares against the platform's current hash to nudge a re-pull.
+    writeFileSync(join(outDir, 'index.json'), JSON.stringify({ version: bundle.version, content_hash: bundle.content_hash, generated_at: bundle.generated_at, index: bundle.index }, null, 2) + '\n', 'utf8');
     console.log(`✓ Pulled the Octwin platform KB → ${outDir}`);
     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.');
@@ -634,6 +719,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));
@@ -1114,6 +1201,11 @@ async function main() {
             break;
         default: die(`unknown command '${command}' — run \`octwin help\``);
     }
-    await notifyIfOutdated(); // trailing, fail-silent, TTY-only "newer version available" notice
+    // Trailing, fail-silent, TTY-only notices. KB-drift only after commands that
+    // already hit the platform (so it's one extra tiny GET, never a new call on
+    // offline paths); CLI-upgrade always.
+    if (commandTouchesPlatform(command, flags))
+        await notifyIfKbStale(flags);
+    await notifyIfOutdated();
 }
 main().catch((err) => die(err?.message ?? String(err)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "dist",
     "templates",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {

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