@luckydraw/cumulus 0.31.65 → 1.0.0

package/examples/web-app-agent/public/agent/commands.js

@@ -0,0 +1,250 @@
+/* The command registry — your app's capability surface.
+
+   This is the file you actually write for your own app. Everything else in
+   this directory is plumbing you copy once and forget.
+
+   The registry is the ONLY thing the model can do to your app. Whatever isn't
+   registered here doesn't exist, no matter how the visitor phrases it. And
+   commands act through window.HostApp — the app's own adapter over its own
+   actions — never by poking the DOM, so persistence, validation, and re-render
+   keep working no matter who is driving.
+
+   Frozen contract:
+     command   { name, description, params, risk, execute(params) }
+     risk      "read"    — answers a question, changes nothing
+               "display" — changes what's on screen only, trivially undoable
+               "mutate"  — changes stored data
+               "export"  — irreversible or leaves the app. ALWAYS routed
+                           through the confirm chip by the gateway; the model
+                           cannot bypass it, and neither can this file.
+     execute   -> { summary, data?, affected? }  (may be async)
+     call()    never throws — failures become { ok: false, summary }
+
+   Write descriptions for a reader who cannot see your UI. The description is
+   the entire basis on which the model decides to call the thing. */
+(function () {
+  'use strict';
+  var defs = new Map();
+
+  function register(def) {
+    defs.set(def.name, def);
+  }
+
+  async function call(name, params) {
+    var def = defs.get(name);
+    if (!def) return { ok: false, summary: 'Unknown command: ' + name };
+    if (!window.HostApp) return { ok: false, summary: 'App not ready' };
+    try {
+      var r = await def.execute(params || {});
+      return Object.assign({ ok: true }, r);
+    } catch (e) {
+      return { ok: false, summary: name + ' failed: ' + ((e && e.message) || e) };
+    }
+  }
+
+  /* Synchronous variant, for hooks that need a value immediately — the
+     bridge's describeView is called during send() and cannot await. Only valid
+     for commands whose execute() is synchronous. */
+  function callNow(name, params) {
+    var def = defs.get(name);
+    if (!def || !window.HostApp) return { ok: false, summary: 'Unavailable: ' + name };
+    try {
+      var r = def.execute(params || {});
+      if (r && typeof r.then === 'function')
+        return { ok: false, summary: name + ' is async — use call()' };
+      return Object.assign({ ok: true }, r);
+    } catch (e) {
+      return { ok: false, summary: name + ' failed: ' + ((e && e.message) || e) };
+    }
+  }
+
+  window.AgentRegistry = {
+    register: register,
+    call: call,
+    callNow: callNow,
+    list: function () {
+      return Array.from(defs.keys());
+    },
+    manifest: function () {
+      return Array.from(defs.values()).map(function (d) {
+        return { name: d.name, description: d.description, risk: d.risk, input_schema: d.params };
+      });
+    },
+  };
+
+  var NO_PARAMS = { type: 'object', properties: {} };
+  function app() {
+    return window.HostApp;
+  }
+
+  /* ---- the agent's eyes -------------------------------------------------- */
+
+  register({
+    name: 'app.describe',
+    risk: 'read',
+    description:
+      'Static knowledge about this app: what it is, what a note is, and what you can do here. ' +
+      'Call once per conversation for grounding. For what is on screen right now, use app.describeView.',
+    params: NO_PARAMS,
+    execute: function () {
+      return {
+        summary: 'Demo Notes — a single-list note taker.',
+        data: {
+          app: 'Demo Notes',
+          concepts: {
+            note: 'A short piece of text with a "done" flag and a created timestamp. Notes have integer ids.',
+            filter:
+              'A text box above the list. When non-empty, only notes containing that text are shown. It is a view setting, not a deletion.',
+          },
+          recipes: [
+            'To find something: call notes.list and read it. Do NOT set the filter just to answer a question — the filter changes what the human sees.',
+            'To highlight a subset for the human: notes.setFilter.',
+            'To tick something off: notes.setDone with done=true, not notes.delete.',
+          ],
+        },
+      };
+    },
+  });
+
+  register({
+    name: 'app.describeView',
+    risk: 'read',
+    description:
+      'What is on the screen right now: the active filter, how many notes are visible, and the visible notes themselves. ' +
+      'Recomputed on every call — never cached. Use this before acting so you act on what the human is actually looking at.',
+    params: NO_PARAMS,
+    execute: function () {
+      var state = app().getState();
+      var visible = app().visibleNotes();
+      return {
+        summary:
+          visible.length +
+          ' of ' +
+          state.notes.length +
+          ' notes visible' +
+          (state.filter ? ' (filter: "' + state.filter + '")' : ''),
+        data: {
+          filter: state.filter,
+          totalNotes: state.notes.length,
+          visibleNotes: visible,
+        },
+      };
+    },
+  });
+
+  register({
+    name: 'notes.list',
+    risk: 'read',
+    description:
+      'Every note, ignoring the on-screen filter. { done?: boolean } narrows to done or not-done notes. ' +
+      'This is how you answer questions — it changes nothing the human can see.',
+    params: {
+      type: 'object',
+      properties: { done: { type: 'boolean', description: 'Only notes with this done state.' } },
+    },
+    execute: function (p) {
+      var notes = app().getState().notes;
+      if (typeof p.done === 'boolean')
+        notes = notes.filter(function (n) {
+          return !!n.done === p.done;
+        });
+      return { summary: notes.length + ' note(s)', data: { notes: notes } };
+    },
+  });
+
+  /* ---- display: changes the view, not the data --------------------------- */
+
+  register({
+    name: 'notes.setFilter',
+    risk: 'display',
+    description:
+      'Set the on-screen filter text so the human sees a subset. { text: string } — pass "" to clear it. ' +
+      'This hides nothing permanently and deletes nothing. Use it to SHOW someone something, not to look something up yourself.',
+    params: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Filter text; empty string clears the filter.' },
+      },
+      required: ['text'],
+    },
+    execute: function (p) {
+      app().setFilter(String(p.text || ''));
+      var visible = app().visibleNotes();
+      return {
+        summary: p.text
+          ? 'Filtered to "' + p.text + '" — ' + visible.length + ' shown'
+          : 'Filter cleared',
+        data: { visibleCount: visible.length },
+        affected: ['filter'],
+      };
+    },
+  });
+
+  /* ---- mutate: changes stored data, but reversibly ----------------------- */
+
+  register({
+    name: 'notes.create',
+    risk: 'mutate',
+    description: 'Add a note. { text: string }. Returns the new note including its id.',
+    params: {
+      type: 'object',
+      properties: { text: { type: 'string', description: 'The note body.' } },
+      required: ['text'],
+    },
+    execute: function (p) {
+      var text = String(p.text || '').trim();
+      if (!text) throw new Error('text is required');
+      var note = app().createNote(text);
+      return {
+        summary: 'Created note #' + note.id,
+        data: { note: note },
+        affected: ['note:' + note.id],
+      };
+    },
+  });
+
+  register({
+    name: 'notes.setDone',
+    risk: 'mutate',
+    description:
+      'Tick a note off or un-tick it. { id: number, done?: boolean (default true) }. ' +
+      'Get ids from notes.list — never guess one.',
+    params: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Note id from notes.list.' },
+        done: { type: 'boolean', description: 'Default true.' },
+      },
+      required: ['id'],
+    },
+    execute: function (p) {
+      var note = app().setDone(Number(p.id), p.done !== false);
+      if (!note) throw new Error('no note with id ' + p.id);
+      return {
+        summary: 'Note #' + note.id + (note.done ? ' marked done' : ' reopened'),
+        data: { note: note },
+        affected: ['note:' + note.id],
+      };
+    },
+  });
+
+  /* ---- export: irreversible. The gateway stops for a human here. ---------- */
+
+  register({
+    name: 'notes.deleteAllDone',
+    risk: 'export',
+    description:
+      'Permanently delete every note already marked done. This cannot be undone. ' +
+      'The human confirms with a chip before it runs — say what you are about to delete first, ' +
+      'and prefer notes.list so they can see the count.',
+    params: NO_PARAMS,
+    execute: function () {
+      var removed = app().deleteAllDone();
+      return {
+        summary: 'Deleted ' + removed + ' completed note(s)',
+        data: { removed: removed },
+        affected: ['notes'],
+      };
+    },
+  });
+})();

package/examples/web-app-agent/public/agent/device-thread.js

@@ -0,0 +1,48 @@
+/* Per-visitor thread identity.
+
+   The thread name IS the capability. A scoped key cannot enumerate threads, so
+   knowing the name is what grants access to a conversation — which means the
+   name must be unguessable and must never be minted server-side and broadcast.
+
+   This mints 16 hex characters (64 bits) once per browser, keeps it in
+   localStorage, and pins THREAD_ID = <base>-<deviceId>. The base the server
+   sends is "demoapp-v" — a sub-namespace under "demoapp", so visitor threads
+   get their own gateway config (cheap model, tight prompt) while the base
+   "demoapp" thread stays yours for working on the app.
+
+   Do not shorten the id. 8 hex characters is 32 bits, which is brute-forceable
+   against a live gateway. */
+(function () {
+  'use strict';
+  var KEY = 'demoapp.deviceId';
+
+  window.agentDeviceThread = function (cfg) {
+    if (!cfg || !cfg.THREAD_ID) return null;
+    if (/-[0-9a-f]{16,}$/.test(cfg.THREAD_ID)) return cfg.THREAD_ID; // already suffixed
+
+    var id = null;
+    try {
+      id = localStorage.getItem(KEY);
+    } catch {
+      /* private mode — fall through and mint an ephemeral id */
+    }
+
+    if (!id || !/^[0-9a-f]{16,}$/.test(id)) {
+      var bytes = new Uint8Array(8); // 8 bytes -> 16 hex chars
+      crypto.getRandomValues(bytes);
+      id = Array.prototype.map
+        .call(bytes, function (b) {
+          return ('0' + b.toString(16)).slice(-2);
+        })
+        .join('');
+      try {
+        localStorage.setItem(KEY, id);
+      } catch {
+        /* ignore — the visitor gets a fresh thread each load */
+      }
+    }
+
+    cfg.THREAD_ID = cfg.THREAD_ID + '-' + id;
+    return cfg.THREAD_ID;
+  };
+})();

package/examples/web-app-agent/public/agent/panel.css

@@ -0,0 +1,107 @@
+/* Agent panel styling. Everything is expressed through the host app's CSS
+   variables (--panel, --panel2, --panel3, --line, --text, --muted, --accent),
+   so the panel follows your theme — including light/dark — with no work.
+   Define those six variables in your app and this file needs no edits. */
+
+#agent-root {
+  position: fixed;
+  z-index: 900;
+  left: 50%;
+  bottom: 0;
+  transform: translateX(-50%);
+  width: min(560px, 100vw - 32px);
+  font-size: 13.5px;
+}
+
+@media (max-width: 720px) {
+  #agent-root { width: calc(100vw - 16px); bottom: env(safe-area-inset-bottom, 0px); }
+  #agent-root .agbar { margin-bottom: 8px; padding: 8px 12px; }
+  #agent-root.open .agwin { height: min(520px, 68dvh); margin-bottom: 8px; }
+}
+
+/* --- minimized home bar --- */
+#agent-root .agbar {
+  display: flex; align-items: center; gap: 8px;
+  margin-bottom: 10px; padding: 9px 14px;
+  background: var(--panel2); border: 1px solid var(--line); border-radius: 22px;
+  box-shadow: 0 4px 18px rgba(0, 0, 0, .25);
+  cursor: text;
+}
+#agent-root.open .agbar { display: none; }
+#agent-root .agstar { color: var(--accent); flex: none; }
+#agent-root .agbarin {
+  flex: 1; background: none; border: none; outline: none;
+  color: var(--text); font: inherit;
+}
+#agent-root .agbarin::placeholder { color: var(--muted); }
+
+/* --- expanded window (grows upward from the bar's slot) --- */
+#agent-root .agwin { display: none; }
+#agent-root.open .agwin {
+  display: flex; flex-direction: column;
+  margin-bottom: 16px;
+  height: min(520px, 72vh);
+  background: var(--panel); border: 1px solid var(--line); border-radius: 12px;
+  box-shadow: 0 10px 34px rgba(0, 0, 0, .35);
+  overflow: hidden;
+}
+#agent-root .aghead {
+  display: flex; align-items: center; gap: 8px; flex: none;
+  padding: 10px 14px; border-bottom: 1px solid var(--line);
+}
+#agent-root .agtitle { font-weight: 600; }
+#agent-root .agdot { width: 8px; height: 8px; border-radius: 50%; background: var(--muted); }
+#agent-root .agdot.open { background: #47c98a; }
+#agent-root .agdot.connecting { background: #f2b13e; }
+#agent-root .agdot.closed { background: #f2665e; }
+#agent-root .agmin {
+  margin-left: auto; background: none; border: none; color: var(--muted);
+  cursor: pointer; font: inherit; padding: 2px 6px; border-radius: 6px;
+}
+#agent-root .agmin:hover { background: var(--panel3); color: var(--text); }
+
+/* --- log --- */
+#agent-root .aglog { flex: 1; overflow-y: auto; padding: 14px; display: flex; flex-direction: column; gap: 10px; }
+#agent-root .agmsg { max-width: 88%; padding: 8px 12px; border-radius: 10px; line-height: 1.45; overflow-wrap: break-word; }
+#agent-root .agmsg.user { align-self: flex-end; background: var(--accent); color: #fff; border-bottom-right-radius: 4px; }
+#agent-root .agmsg.assistant { align-self: flex-start; background: var(--panel2); color: var(--text); border-bottom-left-radius: 4px; white-space: pre-wrap; }
+#agent-root .agmsg.assistant p,
+#agent-root .agmsg.assistant ul,
+#agent-root .agmsg.assistant h4,
+#agent-root .agmsg.assistant table,
+#agent-root .agmsg.assistant pre { white-space: normal; margin: 0 0 8px; }
+#agent-root .agmsg.assistant > :last-child { margin-bottom: 0; }
+#agent-root .agmsg.assistant ul { padding-left: 18px; }
+#agent-root .agmsg.system { align-self: center; color: var(--muted); font-size: 12px; background: none; }
+#agent-root .agmsg.error { align-self: flex-start; background: rgba(242, 102, 94, .12); color: #f2665e; }
+#agent-root .agmsg pre { background: var(--panel3); border: 1px solid var(--line); border-radius: 8px; padding: 8px 10px; overflow-x: auto; font-size: 12px; }
+#agent-root .agmsg code { background: var(--panel3); border-radius: 4px; padding: 1px 5px; font-size: 12.5px; }
+#agent-root .agmsg table { border-collapse: collapse; font-size: 12.5px; }
+#agent-root .agmsg th, #agent-root .agmsg td { border: 1px solid var(--line); padding: 4px 8px; text-align: left; }
+
+#agent-root .agactivity { align-self: flex-start; color: var(--muted); font-size: 12px; padding: 0 4px; animation: agpulse 1.4s ease-in-out infinite; }
+@keyframes agpulse { 0%, 100% { opacity: .55; } 50% { opacity: 1; } }
+/* Browser tests set data-test-mode to kill animation timing races. */
+[data-test-mode="true"] #agent-root .agactivity { animation: none; }
+
+/* --- export-tier confirm chip --- */
+#agent-root .agconfirm { align-self: stretch; background: var(--panel2); border: 1px solid #f2b13e88; border-radius: 10px; padding: 10px 12px; }
+#agent-root .agconfirmrow { display: flex; gap: 8px; margin-top: 8px; }
+#agent-root .agconfirmdone { color: var(--muted); margin-top: 6px; font-size: 12px; }
+#agent-root .agbtn {
+  font: inherit; padding: 5px 14px; border-radius: 8px; cursor: pointer;
+  background: var(--panel3); color: var(--text); border: 1px solid var(--line);
+}
+#agent-root .agbtn.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+
+/* --- composer row --- */
+#agent-root .aginrow { display: flex; gap: 8px; flex: none; padding: 10px 12px; border-top: 1px solid var(--line); }
+#agent-root .again {
+  flex: 1; resize: none; background: var(--panel2); border: 1px solid var(--line);
+  border-radius: 10px; padding: 8px 10px; color: var(--text); font: inherit; outline: none;
+}
+#agent-root .again:focus { border-color: var(--accent); }
+#agent-root .agsend {
+  align-self: flex-end; width: 34px; height: 34px; border-radius: 50%;
+  background: var(--accent); color: #fff; border: none; cursor: pointer; font-size: 15px;
+}