agentwire-dev 1.48.0__tar.gz → 1.49.0__tar.gz

{agentwire_dev-1.48.0 → agentwire_dev-1.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.48.0
+Version: 1.49.0
 Summary: Multi-session voice web interface for AI coding agents
 Project-URL: Homepage, https://agentwire.dev
 Project-URL: Repository, https://github.com/dotdevdotdev/agentwire-dev

{agentwire_dev-1.48.0 → agentwire_dev-1.49.0}/agentwire/__init__.py

@@ -1,3 +1,3 @@
 """AgentWire - Multi-session voice web interface for AI coding agents."""
 
-__version__ = "1.48.0"
+__version__ = "1.49.0"

{agentwire_dev-1.48.0 → agentwire_dev-1.49.0}/agentwire/static/announcements.json

@@ -1,5 +1,22 @@
 {
   "announcements": [
+    {
+      "id": "2026-06-help-modal",
+      "placement": "modal",
+      "emoji": "⌨️",
+      "title": "Press F1 — there's more than you think",
+      "date": "2026-06-29",
+      "body": "AgentWire has a pile of keyboard shortcuts and features that were easy to miss. Now there's one place to see them all: press F1 (or ?) anytime for a cheat sheet of every shortcut, plus a quick tour of features worth knowing — council, push-to-talk, window collage, worktrees, scratchpad, and more. There's also a ? button in the sidebar header if you'd rather click.",
+      "highlights": [
+        "F1 or ? — keyboard shortcut cheat sheet, from anywhere",
+        "Doubles as a feature tour: discover what you're not using yet",
+        "Also in the sidebar header (?) and the command palette"
+      ],
+      "cta": {
+        "label": "Press F1 to try it",
+        "url": "https://github.com/dotdevdotdev/agentwire-dev/releases/tag/v1.49.0"
+      }
+    },
     {
       "id": "2026-06-worktree-sessions",
       "placement": "modal",

{agentwire_dev-1.48.0 → agentwire_dev-1.49.0}/agentwire/static/css/desktop.css

@@ -1209,6 +1209,145 @@ body {
     border-radius: 4px;
 }
 
+/* ── Help modal (F1 / "?") ─────────────────────────────────────────────── */
+.help-overlay {
+    z-index: 9500;  /* above the sidebar (9001) so the cheat sheet is never clipped */
+    animation: announcement-fade 180ms ease-out;
+}
+
+.help-overlay .help-modal {
+    width: 760px;
+    max-width: 94vw;
+    max-height: 86vh;
+    display: flex;
+    flex-direction: column;
+    padding: 24px 26px 16px;
+    border: 1px solid color-mix(in srgb, var(--accent) 28%, var(--chrome-border));
+    border-radius: 12px;
+    animation: announcement-rise 200ms cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+
+.help-dismiss {
+    position: absolute;
+    top: 12px;
+    right: 12px;
+    background: transparent;
+    border: none;
+    color: var(--text-muted);
+    font-size: 15px;
+    cursor: pointer;
+    line-height: 1;
+    padding: 4px 6px;
+    border-radius: 4px;
+}
+.help-dismiss:hover { color: var(--text); background: var(--chrome-border); }
+
+.help-title {
+    margin: 0 0 16px;
+    font-size: 17px;
+    font-weight: 600;
+    color: var(--accent);
+}
+
+.help-content {
+    display: grid;
+    grid-template-columns: 1.1fr 1fr;
+    gap: 24px;
+    overflow-y: auto;
+    padding-right: 4px;
+}
+@media (max-width: 640px) {
+    .help-content { grid-template-columns: 1fr; }
+}
+
+.help-group { margin-bottom: 16px; }
+
+.help-group-title {
+    margin: 0 0 8px;
+    font-size: 11px;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--text-muted);
+}
+
+.help-row {
+    display: flex;
+    align-items: baseline;
+    gap: 12px;
+    padding: 4px 0;
+}
+
+.help-keys {
+    flex: 0 0 132px;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 3px;
+}
+
+.help-desc { font-size: 13px; color: var(--text); line-height: 1.4; }
+
+.help-modal kbd,
+.help-footer kbd {
+    display: inline-block;
+    min-width: 16px;
+    padding: 1px 6px;
+    font-family: inherit;
+    font-size: 11px;
+    font-weight: 600;
+    text-align: center;
+    color: var(--text);
+    background: var(--background);
+    border: 1px solid var(--chrome-border);
+    border-bottom-width: 2px;
+    border-radius: 4px;
+}
+
+.help-or, .help-hold {
+    font-size: 10px;
+    color: var(--text-muted);
+    margin: 0 2px;
+}
+.help-hold { font-style: italic; }
+
+.help-feature {
+    display: flex;
+    gap: 10px;
+    padding: 6px 0;
+}
+
+.help-feature-icon { font-size: 16px; line-height: 1.3; flex: 0 0 auto; }
+
+.help-feature-text { display: flex; flex-direction: column; gap: 1px; }
+
+.help-feature-name { font-size: 13px; font-weight: 600; color: var(--text); }
+
+.help-feature-desc { font-size: 12px; color: var(--text-muted); line-height: 1.4; }
+
+.help-footer {
+    margin-top: 14px;
+    padding-top: 12px;
+    border-top: 1px solid var(--chrome-border);
+    font-size: 11px;
+    color: var(--text-muted);
+    text-align: center;
+}
+
+/* Sidebar header "?" help button — mirrors .sidebar-quicktask */
+.sidebar-help {
+    background: transparent;
+    border: none;
+    color: var(--text-muted);
+    cursor: pointer;
+    padding: 4px 7px;
+    border-radius: 4px;
+    font-size: 14px;
+    font-weight: 700;
+    line-height: 1;
+}
+.sidebar-help:hover { color: var(--accent); background: var(--chrome-border); }
+
 .announcement-dismiss:hover {
     color: var(--text);
     background: var(--background);

{agentwire_dev-1.48.0 → agentwire_dev-1.49.0}/agentwire/static/js/command-palette.js

@@ -44,6 +44,11 @@ const COMMANDS = [
         const { collage } = await import('./collage.js');
         collage.enter();
     } },
+    { id: 'help', icon: '⌨', label: 'Keyboard shortcuts & help', keywords: 'help shortcuts keys keyboard cheat sheet f1 bindings features guide', run: async () => {
+        closeCommandPalette();
+        const { openHelp } = await import('./help-modal.js');
+        openHelp();
+    } },
 ];
 
 // ---------------------------------------------------------------------------

{agentwire_dev-1.48.0 → agentwire_dev-1.49.0}/agentwire/static/js/desktop.js

@@ -32,6 +32,7 @@ import { notificationsPanel } from './notifications-panel.js';
 import { scratchpad } from './scratchpad.js';
 import { armDeadKeySuppressor, disarmDeadKeySuppressor } from './dead-key-suppressor.js';
 import { openCommandPalette, isCommandPaletteOpen } from './command-palette.js';
+import { setupHelp, openHelp, isHelpOpen } from './help-modal.js';
 import * as browserStt from './voice/browser-stt.js';
 import { voicePromptWrap } from './voice/prompt.js';
 import { isAutoSend } from './voice/autosend-prefs.js';
@@ -83,6 +84,11 @@ async function init() {
         sidebar.close();
         openCommandPalette({ view: 'new-idea' });
     });
+    document.getElementById('sidebarHelp')?.addEventListener('click', (e) => {
+        e.stopPropagation();
+        sidebar.close();
+        openHelp();
+    });
     sidebar.addSection('sessions', sessionsSection);
     sidebar.addSection('services', servicesSection);
     sidebar.addSection('machines', machinesSection);
@@ -98,6 +104,7 @@ async function init() {
     setupWindowCycling();
     setupWindowSwipeCycling();
     setupCollage();
+    setupHelp();
 
     // Set up event listeners BEFORE fetching data
     desktop.on('disconnect', () => updateConnectionStatus(false));
@@ -449,7 +456,7 @@ function setupCollage() {
         const isF3 = e.code === 'F3';
         const isAltBacktick = e.altKey && !e.metaKey && !e.ctrlKey && e.code === 'Backquote';
         if (!isF3 && !isAltBacktick) return;
-        if (isCommandPaletteOpen()) return;
+        if (isCommandPaletteOpen() || isHelpOpen()) return;
         e.preventDefault();
         e.stopPropagation();
         if (e.repeat) return;  // ignore auto-repeat while the key is held
@@ -1009,7 +1016,7 @@ function setupGlobalPtt() {
         // always intercepted.
         if ((e.ctrlKey || e.metaKey) && (e.key === 'k' || e.key === 'K')) {
             e.preventDefault();
-            if (!isCommandPaletteOpen()) openCommandPalette();
+            if (!isCommandPaletteOpen() && !isHelpOpen()) openCommandPalette();
         }
     });
     document.addEventListener('keyup', (e) => {

agentwire_dev-1.49.0/agentwire/static/js/help-modal.js

@@ -0,0 +1,133 @@
+/**
+ * Help modal — the F1 / "?" keyboard-shortcut cheat sheet and feature tour.
+ *
+ * Renders from the shortcuts.js registry (the single source of truth), mirrors
+ * the .modal-overlay > .modal pattern from announcement-modal.js, and wires the
+ * global triggers (F1, ?). The visible "?" button in the sidebar header and a
+ * command-palette entry call openHelp() directly.
+ */
+
+import { SHORTCUT_GROUPS, FEATURE_TOUR, comboKeys } from './shortcuts.js';
+
+let modalEl = null;
+let escHandler = null;
+
+function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, (c) => (
+        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+    ));
+}
+
+export function isHelpOpen() {
+    return modalEl !== null;
+}
+
+/** One combo → "<kbd>⌘</kbd><kbd>K</kbd>". */
+function renderCombo(combo) {
+    return comboKeys(combo).map((k) => `<kbd>${escapeHtml(k)}</kbd>`).join('');
+}
+
+/** A shortcut row: primary combo, optional "or" alt combo, optional (hold), desc. */
+function renderShortcutRow(item) {
+    const primary = renderCombo(item.combo);
+    const alt = item.alt ? `<span class="help-or">or</span>${renderCombo(item.alt)}` : '';
+    const hold = item.hold ? '<span class="help-hold">hold</span>' : '';
+    return `<div class="help-row">
+        <div class="help-keys">${primary}${alt}${hold}</div>
+        <div class="help-desc">${escapeHtml(item.desc)}</div>
+    </div>`;
+}
+
+function renderShortcutGroup(group) {
+    return `<div class="help-group">
+        <h3 class="help-group-title">${escapeHtml(group.title)}</h3>
+        ${group.items.map(renderShortcutRow).join('')}
+    </div>`;
+}
+
+function renderFeature(f) {
+    return `<div class="help-feature">
+        <span class="help-feature-icon">${escapeHtml(f.icon)}</span>
+        <div class="help-feature-text">
+            <span class="help-feature-name">${escapeHtml(f.name)}</span>
+            <span class="help-feature-desc">${escapeHtml(f.desc)}</span>
+        </div>
+    </div>`;
+}
+
+function renderModal() {
+    return `<div class="modal-overlay help-overlay" id="helpOverlay">
+        <div class="modal help-modal" role="dialog" aria-label="Keyboard shortcuts and features" aria-modal="true">
+            <button class="help-dismiss" data-action="dismiss" title="Close (Esc)" aria-label="Close help">✕</button>
+            <h2 class="help-title">Keyboard shortcuts &amp; features</h2>
+            <div class="help-content">
+                <div class="help-shortcuts">
+                    ${SHORTCUT_GROUPS.map(renderShortcutGroup).join('')}
+                </div>
+                <div class="help-features">
+                    <h3 class="help-group-title">Features worth knowing</h3>
+                    ${FEATURE_TOUR.map(renderFeature).join('')}
+                </div>
+            </div>
+            <div class="help-footer">
+                Press <kbd>F1</kbd> or <kbd>?</kbd> anytime · <kbd>Esc</kbd> to close
+            </div>
+        </div>
+    </div>`;
+}
+
+export function closeHelp() {
+    if (escHandler) { document.removeEventListener('keydown', escHandler, true); escHandler = null; }
+    modalEl?.remove();
+    modalEl = null;
+}
+
+export function openHelp() {
+    if (modalEl) return;
+    const wrapper = document.createElement('div');
+    wrapper.innerHTML = renderModal();
+    modalEl = wrapper.firstElementChild;
+    document.body.appendChild(modalEl);
+
+    modalEl.addEventListener('click', (e) => {
+        if (e.target === modalEl || e.target.closest('[data-action="dismiss"]')) {
+            closeHelp();
+        }
+    });
+    // Capture phase so Esc closes the help before xterm / other handlers see it.
+    escHandler = (e) => {
+        if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); closeHelp(); }
+    };
+    document.addEventListener('keydown', escHandler, true);
+}
+
+export function toggleHelp() {
+    if (modalEl) closeHelp(); else openHelp();
+}
+
+/** True when the event target is a text-editing surface (so "?" types normally). */
+function isEditableTarget(t) {
+    if (!t) return false;
+    const tag = t.tagName;
+    return tag === 'INPUT' || tag === 'TEXTAREA' || t.isContentEditable;
+}
+
+/**
+ * Wire the global F1 / "?" triggers. Capture phase + preventDefault so F1 never
+ * opens the browser's own help, and so the keystroke beats xterm. "?" is
+ * ignored while typing in an input/textarea/terminal so it can still be typed.
+ */
+export function setupHelp() {
+    window.addEventListener('keydown', (e) => {
+        const isF1 = e.code === 'F1';
+        // "?" is Shift+/ — accept the produced character, no modifiers beyond Shift.
+        const isQuestion = e.key === '?' && !e.metaKey && !e.ctrlKey && !e.altKey;
+        if (!isF1 && !isQuestion) return;
+        // Let people actually type "?" into inputs and terminals.
+        if (isQuestion && isEditableTarget(e.target)) return;
+        e.preventDefault();
+        e.stopPropagation();
+        if (e.repeat) return;
+        toggleHelp();
+    }, true);
+}

{agentwire_dev-1.48.0 → agentwire_dev-1.49.0}/agentwire/static/js/service-classification.js

@@ -11,6 +11,7 @@ const SERVICE_SESSIONS = new Set([
     'agentwire-portal',
     'agentwire-tts',
     'agentwire-stt',
+    'agentwire-kokoro',  // default-tier Kokoro TTS shim subprocess (:8102)
     'agentwire-scheduler',
     'agentwire-notifications',
 ]);

agentwire_dev-1.49.0/agentwire/static/js/shortcuts.js

@@ -0,0 +1,91 @@
+/**
+ * Keyboard-shortcut + feature registry — the single source of truth for the
+ * F1 help modal (help-modal.js), the command-palette "help" entry, and the
+ * `title=` hints we show on buttons.
+ *
+ * This module holds the *catalogue*, not the bindings. Each component still
+ * registers its own capture-phase keydown listener (there is no central
+ * dispatcher — see desktop.js setupCollage / setupGlobalPtt etc.). When you
+ * add or change a real binding, update its row here too: the `where` field
+ * names the handler so the two stay findable together.
+ *
+ * Combos are token arrays. `Mod` renders ⌘ on macOS, Ctrl elsewhere; `Alt`
+ * renders ⌥ on macOS, Alt elsewhere. Plain strings render verbatim.
+ */
+
+const IS_MAC = typeof navigator !== 'undefined'
+    && /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent || '');
+
+/** Render one combo token for display. */
+function renderToken(tok) {
+    if (tok === 'Mod') return IS_MAC ? '⌘' : 'Ctrl';
+    if (tok === 'Alt') return IS_MAC ? '⌥' : 'Alt';
+    return tok;
+}
+
+/** A combo (array of tokens) → array of display strings, for <kbd> rendering. */
+export function comboKeys(combo) {
+    return combo.map(renderToken);
+}
+
+// ---------------------------------------------------------------------------
+// Shortcut catalogue — grouped for the help modal.
+// where: the file:function that owns the real binding (keep in sync on change).
+// ---------------------------------------------------------------------------
+
+export const SHORTCUT_GROUPS = [
+    {
+        title: 'Global',
+        items: [
+            { combo: ['Mod', 'K'], desc: 'Open the command palette', where: 'desktop.js setupCommandPalette' },
+            { combo: ['F1'], alt: ['?'], desc: 'Show this help', where: 'help-modal.js setupHelp' },
+            { combo: ['Mod', '`'], desc: 'Toggle the sidebar', where: 'sidebar.js' },
+            { combo: ['Esc'], desc: 'Close the open modal, palette, collage, or sidebar', where: 'various' },
+        ],
+    },
+    {
+        title: 'Voice',
+        items: [
+            { combo: ['Mod', 'Space'], hold: true, desc: 'Push-to-talk — hold to speak to AgentWire (or the focused session)', where: 'desktop.js setupGlobalPtt / session-window.js' },
+        ],
+    },
+    {
+        title: 'Windows',
+        items: [
+            { combo: ['Tab'], alt: ['Shift', 'Tab'], desc: 'Cycle to the next / previous window', where: 'desktop.js setupWindowCycling' },
+            { combo: ['F3'], alt: ['Alt', '`'], desc: 'Window collage — Mission-Control grid of all windows', where: 'desktop.js setupCollage' },
+        ],
+    },
+    {
+        title: 'Panels',
+        items: [
+            { combo: ['Alt', 'N'], desc: 'Toggle the scratchpad drawer', where: 'scratchpad.js' },
+        ],
+    },
+    {
+        title: 'Command palette (while open)',
+        items: [
+            { combo: ['↑'], alt: ['↓'], desc: 'Move through the list', where: 'command-palette.js' },
+            { combo: ['Enter'], desc: 'Run the selected item', where: 'command-palette.js' },
+            { combo: ['Esc'], desc: 'Go back, or close the palette', where: 'command-palette.js' },
+        ],
+    },
+];
+
+// ---------------------------------------------------------------------------
+// Feature tour — the "you may not know this exists" half. Each row teaches a
+// capability and (where relevant) how to reach it.
+// ---------------------------------------------------------------------------
+
+export const FEATURE_TOUR = [
+    { icon: '🏛', name: 'Council', desc: 'Ask one question, get six lenses (brain, conscience, …) deliberating in parallel. Command palette → Ask council.' },
+    { icon: '🎙', name: 'Push-to-talk', desc: 'Hold Ctrl/⌘+Space to talk to a session. Or open /mobile to push-to-talk from your phone.' },
+    { icon: '▦', name: 'Window collage', desc: 'F3 fans every window into a grid — click one to dive in. Great for juggling many sessions.' },
+    { icon: '💡', name: 'New idea', desc: 'Capture a thought and AgentWire spins up a project with an agent already working on it.' },
+    { icon: '⎇', name: 'Worktrees', desc: 'Branch a session into an isolated git worktree for parallel work, from the palette or the Sessions panel.' },
+    { icon: '📋', name: 'Scratchpad', desc: 'Alt+N opens a quick notes drawer that travels with you across sessions.' },
+    { icon: '⏰', name: 'Scheduler', desc: 'Run recurring tasks on a cron — see and trigger them from the Scheduler panel.' },
+    { icon: '🧩', name: 'Artifacts', desc: 'Agents can render live HTML into artifact windows — dashboards, handoffs, reports.' },
+    { icon: '🛡', name: 'Safety', desc: 'Damage-control rules block dangerous commands. Review and tune them in the Safety panel.' },
+    { icon: '📡', name: 'Machines', desc: 'Attach remote machines and tunnels — run sessions on a GPU box or another host.' },
+];

{agentwire_dev-1.48.0 → agentwire_dev-1.49.0}/agentwire/templates/desktop.html

@@ -21,6 +21,9 @@
             <button class="sidebar-quicktask" id="sidebarQuicktask" title="Command palette (Cmd/Ctrl+K)" aria-label="Command palette">
                 <span class="sidebar-quicktask-icon">⚡</span>
             </button>
+            <button class="sidebar-help" id="sidebarHelp" title="Keyboard shortcuts &amp; help (F1)" aria-label="Keyboard shortcuts and help">
+                <span class="sidebar-help-icon">?</span>
+            </button>
             <button class="sidebar-pin" id="sidebarPin" title="Pin sidebar open" aria-label="Pin sidebar">
                 <span class="sidebar-pin-icon">📌</span>
             </button>