argus-hermes-bridge 0.0.0-stage → 0.1.0

package/HermesSetupPrompt.txt

@@ -0,0 +1,16 @@
+I downloaded the Argus iPhone beta from TestFlight. Please connect it to my existing Hermes on this Mac or Linux/VPS host. Do the setup for me and keep the steps I need to do myself short.
+
+Use the published Argus bridge package from npm with this exact command on the host where Hermes runs:
+npx --yes argus-hermes-bridge@0.1.0 setup
+The command includes the installer. You do not need to ask me for a separate download or private repository access. Use exactly this package name and version. If npm cannot retrieve it, report the actual error.
+
+1. Inspect this host and locate the existing working Hermes installation, its Python runtime and config home. The beta supports macOS with a logged-in desktop user, or Linux with a working systemd user service manager. If Hermes runs in a container, Windows, or a restricted environment without these capabilities, explain the blocker before making changes. Use the same user account as Hermes; do not run the installer as root or reinstall Hermes.
+2. Check Node.js 22+ and Tailscale. Help me install missing prerequisites using their official instructions. I need Tailscale on my iPhone and the Hermes host, signed into the same tailnet. Let me complete sign-in, HTTPS enablement, or administrator prompts myself. Preserve existing Tailscale routes. Use private Tailscale Serve, never public Funnel or an open internet port.
+3. Inspect the package README from npm, then run the exact pinned setup command above. If a bridge already runs on this host, inspect its service before updating it and preserve existing device access. Finish active phone requests before a service restart. Pass ARGUS_HERMES_HOME, ARGUS_HERMES_SOURCE or ARGUS_HERMES_PYTHON only if auto-discovery needs the paths from this installation. Do not copy provider keys or passwords into chat, the phone, or the package. Keep the default strict phone approvals. Do not enable monitoring, automatic tool approvals, vault writes, or change my model/provider settings for setup.
+4. Resolve setup errors, then run npx --yes argus-hermes-bridge@0.1.0 doctor. On Linux, check user-service lingering and help me enable it if needed so the bridge survives logout/reboot. On a Mac the user must stay logged in and the host must stay awake; explain any macOS file-access prompt. Do not claim a successful HTTPS check proves inference or tool approvals.
+5. Issue the pairing code last, using npx --yes argus-hermes-bridge@0.1.0 pair if the setup code is close to expiry. Return its exact three-line block in one copyable code block:
+ARGUS-PAIR/1
+https://<actual-host>.<actual-tailnet>.ts.net:8443
+<actual 12-character pairing code>
+Do not invent these values. The code is single-use and expires in five minutes. Tell me to open Argus → Set up Argus, tap Paste, review the address and tap Pair this iPhone. If it expires, generate a fresh code without reinstalling.
+6. Have me ask a harmless question in Argus using text first, then optionally set up voice. Confirm I received a real Hermes reply. Before testing tools, help me check a harmless tool request with Deny and then Approve once; do not execute external actions merely to test pairing. If anything cannot be verified, say exactly what is still needed.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# Argus beta bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect the Argus TestFlight app to **your own existing Hermes**. Supports a
+logged-in macOS desktop user or Linux with systemd user services. Containers,
+Windows, and hosts without a systemd user manager are outside this beta path.
+
+## Start here
+
+Open Argus → **Set up Argus** → **Copy setup prompt**. Send that prompt to
+Hermes. The prompt includes the pinned npm command. Hermes can do the host setup and
+return a three-line connection block for the phone. Install Tailscale on your
+iPhone and sign in to the same tailnet as your Hermes host.
+
+The companion package has no npm dependencies or install hooks. Downloading it
+does not start a service; `setup` explicitly installs the bridge. It copies only
+the bridge runtime into `~/.config/argus/service`, so it survives npx cache cleanup.
+It does not need the private Argus repository.
+
+## Run with npx
+
+On the Hermes host, using its normal user account and Node.js 22 or newer:
+
+```sh
+npx --yes argus-hermes-bridge@0.1.0 setup
+```
+
+The package is [argus-hermes-bridge on npm](https://www.npmjs.com/package/argus-hermes-bridge).
+Use `npx --yes argus-hermes-bridge@0.1.0` followed by any command below.
+A supplied tarball also works with `npx --yes --package /path/to/package.tgz argus-bridge setup`.
+
+`setup` finds the actual Tailscale hostname, checks runtime imports, installs a
+user service, and adds a private HTTPS Serve route on port 8443 to the loopback
+API on port 4179. It checks the authenticated API boundary locally and through
+HTTPS before issuing a five-minute, one-use code. Review any system permission
+or Tailscale HTTPS sign-in prompt yourself, then rerun `setup`.
+
+On the phone, copy the **three-line ARGUS-PAIR/1 block**, open **Set up Argus**,
+tap **Paste**, review the host and tap **Pair this iPhone**.
+Only tapping Pair connects the phone; pasting does not make a request. Start
+with a text question to confirm a real Hermes reply, then optionally enable voice.
+
+## Runtime discovery and persistence
+
+Hermes must already work. The installer checks `~/.hermes/hermes-agent` and its
+virtual environments, then Hermes-managed Python under `~/.hermes/tools`. For a
+custom installation, set these **paths** before the setup command:
+
+```sh
+ARGUS_HERMES_HOME=/path/to/hermes-config \
+ARGUS_HERMES_SOURCE=/path/to/hermes-agent \
+ARGUS_HERMES_PYTHON=/path/to/venv/bin/python3 \
+npx --yes argus-hermes-bridge@0.1.0 setup
+```
+
+These selections persist in the service definition and `~/.config/argus/bridge.json`.
+Provider credentials stay in your existing Hermes configuration. Setup does not
+select a different provider, enable monitoring, or authorize phone vault writes.
+
+- **macOS:** LaunchAgent `com.tachyon.argus.mobile` starts at user login. Keep
+  the user logged in and the Mac awake. Logs are
+  `~/.config/argus/mobile-service{,-error}.log`. A Hermes installation under
+  Documents may require macOS file access; the installer cannot bypass it.
+- **Linux/VPS:** `systemctl --user` manages `argus-mobile.service`; logs are
+  available with `journalctl --user -u argus-mobile.service`. To survive logout
+  and reboot, check `loginctl show-user "$(id -u)" --property=Linger --value`.
+  If needed, an administrator can run `sudo loginctl enable-linger "$(id -u)"`.
+  Setup reports when this step remains. Use the same user as Hermes, not root.
+
+Keep Tailscale running on both devices. Setup preserves other Serve routes and
+refuses a conflicting 8443 route or public Funnel on that port. It never
+uses Funnel or opens the API on an internet-facing address. See the official
+[Tailscale Serve command](https://tailscale.com/docs/reference/tailscale-cli/serve).
+
+## Recovery and access
+
+```text
+argus-bridge pair           New code without reinstalling (invalidates the previous code)
+argus-bridge doctor         Service, runtime import and private HTTPS diagnostics
+argus-bridge devices        List paired devices
+argus-bridge revoke ID      Remove access for one listed device
+```
+
+Run these with the same npx package prefix as setup. Transport and import checks
+do not prove inference, each tool, or approval compatibility. Before beta tool
+use and after every Hermes update, try a harmless tool request with **Deny** and
+then **Approve once** in Argus. A blocked phone policy must be fixed on the
+host; do not turn off Hermes approvals to bypass it.
+
+To update the bridge, run `setup` with the new invitation package after finishing
+active phone requests. Existing device access is retained. Updates are manual.
+
+## Remove the bridge
+
+Stop the service on macOS with
+`launchctl bootout gui/$(id -u)/com.tachyon.argus.mobile`, then remove
+`~/Library/LaunchAgents/com.tachyon.argus.mobile.plist`. On Linux use
+`systemctl --user disable --now argus-mobile.service`, remove
+`~/.config/systemd/user/argus-mobile.service`, and run
+`systemctl --user daemon-reload`.
+
+If 8443 still points only to Argus, remove that dedicated route with
+`tailscale serve --https=8443 off` using your installed Tailscale executable.
+Do not reset the host's other Serve routes. Remove `~/.config/argus/service`
+and `bridge.json` if desired. `mobile-devices.json` contains the separate
+device registry; deleting it revokes all phones. Hermes itself stays installed.

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "argus-hermes-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Private Tailscale connection between the Argus iPhone beta and your existing Hermes",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "bin": {
+    "argus-bridge": "scripts/argus-bridge.mjs"
+  },
+  "files": [
+    "scripts",
+    "prototypes",
+    "HermesSetupPrompt.txt",
+    "README.md"
+  ]
+}

package/prototypes/iphone-voice-spike/argus_admin.py

@@ -0,0 +1,55 @@
+"""Small adapters to Hermes' public model catalog and encrypted vault store.
+
+Used by hermes-admin.py (phone model settings and Add Login) and by
+hermes-worker.py (validating a per-phone model choice before a request runs).
+No credential value or conversation content is returned by these operations.
+"""
+from urllib.parse import urlsplit
+
+
+def catalog(default, provider, models):
+    def valid(value):
+        return isinstance(value, str) and 0 < len(value) <= 200 and not any(ord(c) < 32 for c in value)
+    if not valid(default) or not valid(provider):
+        raise ValueError('Invalid configured model')
+    choices = list(dict.fromkeys([default] + [m for m in models if valid(m)]))[:120]
+    return {'provider': provider, 'defaultModel': default, 'models': choices}
+
+
+def selected_model(default, provider, override, provider_model_ids):
+    """Validate a stale per-phone override before a conversation runs."""
+    if not override or override == default:
+        return default
+    if override not in provider_model_ids(provider):
+        raise ValueError('The selected model is no longer available for this configured provider')
+    return override
+
+
+def save_login(payload, store):
+    if set(payload) != {'origin', 'label', 'identifier', 'password'}:
+        raise ValueError('Invalid login fields')
+    for key, limit in [('origin', 500), ('label', 80), ('identifier', 320), ('password', 4096)]:
+        value = payload[key]
+        if not isinstance(value, str) or not value or len(value) > limit or '\x00' in value:
+            raise ValueError('Invalid login')
+    origin = urlsplit(payload['origin'])
+    if origin.scheme != 'https' or not origin.hostname or origin.username or origin.password or origin.query or origin.fragment or origin.path not in ('', '/'):
+        raise ValueError('HTTPS origin required')
+    identifier = payload['identifier'].strip()
+    if not identifier or not payload['label'].strip():
+        raise ValueError('Login identifier and label required')
+    secret = {'identifier': identifier, 'identifier_type': 'email' if '@' in identifier else 'username', 'password': payload['password']}
+    try:
+        meta = store.add_item('login', payload['label'].strip(), secret, origin=payload['origin'])
+        return {'status': 'saved', 'handle': meta.id, 'origin': meta.origin, 'storage': 'hermes-local'}
+    finally:
+        secret.clear()
+        payload.clear()
+
+
+def existing_vault_guard(store):
+    """Require existing storage and prohibit key generation even if the key disappears mid-save."""
+    from unittest.mock import patch
+    if not store._key_path.is_file() or not store._vault_path.is_file():
+        raise RuntimeError('Initialize the Hermes vault on the Mac before granting phone writes')
+    return patch('cryptography.fernet.Fernet.generate_key', side_effect=RuntimeError('Phone saves cannot provision a vault key'))

package/prototypes/iphone-voice-spike/argus_phone_policy.py

@@ -0,0 +1,164 @@
+"""Argus phone policy for full Hermes tools: fail closed, and ask the phone first.
+
+A paired iPhone reaches Hermes with the Hermes host's configured toolsets. On its own,
+Hermes prompts only for actions its pattern checks flag, and `approvals.mode: off`
+or yolo approve everything without asking. This module refuses to run in those
+states and registers a `pre_tool_call` hook that sends every tool outside a short
+read-only list through Hermes's own human-approval gate, which the phone answers
+with Approve once / Deny. Hook escalations skip Hermes's smart (LLM) approver, so
+a person always decides. In host-selected personal monitor mode, the hook
+records only tool identifiers/classifications and returns no directive; Hermes
+keeps its own configured approvals and other plugin policies. Both modes refuse
+bypass/unattended configurations. Anything this module cannot verify refuses.
+
+Checked against hermes-agent main at b2360086; an installed Hermes that lacks
+these interfaces refuses phone mode instead of running ungated.
+"""
+import json
+import uuid
+
+# Tools that only read public information or manage Hermes's own turn. Reading
+# local files is not here: file contents could leave the Hermes host through the model
+# provider or a later web request.
+READ_ONLY_TOOLS = frozenset({
+    'clarify', 'todo_list', 'web_search', 'web_extract', 'x_search', 'skills_list', 'skill_view',
+})
+
+PLAIN_ACTIONS = {
+    'terminal': 'run a command on your Hermes host',
+    'execute_code': 'run a program on your Hermes host',
+    'write_file': 'change a file on your Hermes host',
+    'patch': 'change a file on your Hermes host',
+    'read_file': 'read a file on your Hermes host',
+    'search_files': 'search the files on your Hermes host',
+    'computer_use': "control your host's screen, mouse and keyboard",
+    'memory': "change what Hermes remembers",
+    'session_search': 'search your past Hermes conversations',
+    'cronjob_manage': 'schedule a task on your Hermes host',
+    'delegate_task': 'start a helper agent',
+    'send_message': 'send a message',
+    'react_to_message': 'react to a message',
+}
+
+
+def describe(tool_name, args):
+    """Plain words for the approval card, followed by the exact arguments."""
+    name = str(tool_name)
+    if name in PLAIN_ACTIONS:
+        action = PLAIN_ACTIONS[name]
+    elif name.startswith('browser'):
+        action = 'use the web browser on your Hermes host'
+    else:
+        action = f'use the tool "{name}"'
+    try:
+        detail = json.dumps(args, ensure_ascii=False, default=str)
+    except (TypeError, ValueError):
+        detail = repr(args)
+    if len(detail) > 600:
+        detail = detail[:600] + '…'
+    return f'Hermes wants to {action}. Details: {detail}'
+
+
+def gate(tool_name='', args=None, **_):
+    """`pre_tool_call` hook. Must never raise: Hermes treats a failing guard as no decision."""
+    try:
+        if tool_name in READ_ONLY_TOOLS:
+            return None
+        # A fresh rule key per call: no earlier "always" or session approval can match it.
+        return {'action': 'approve', 'message': describe(tool_name, args),
+                'rule_key': 'argus-phone-' + uuid.uuid4().hex}
+    except Exception:
+        return {'action': 'block', 'message': 'Argus could not describe this action for approval, so it did not run.'}
+
+
+def refusal():
+    """Why phone mode must not run right now, or None. Any doubt refuses."""
+    try:
+        from tools import approval, approval_context
+        from tools.terminal_tool import _get_approval_callback
+        mode = approval_context._get_approval_mode()
+        if mode not in ('manual', 'smart'):
+            return (f'Hermes approvals.mode is "{mode}", which approves actions without asking. '
+                    'Set approvals.mode to manual or smart in ~/.hermes/config.yaml.')
+        if approval._YOLO_MODE_FROZEN or approval.is_current_session_yolo_enabled():
+            return 'Hermes yolo mode is on, which approves actions without asking. Remove HERMES_YOLO_MODE from the service.'
+        aggregate = getattr(approval_context, '_no_user_can_answer', None)
+        if aggregate is not None:
+            unattended = aggregate()
+        else:
+            # Some Hermes releases expose the three context checks separately.
+            # Require all three: missing checks still fail closed below.
+            checks = [approval_context._is_single_query_approval_context,
+                      approval_context._is_cron_approval_context,
+                      approval_context._is_unattended_platform_approval_context]
+            unattended = any(check() for check in checks)
+        if unattended:
+            return 'This Hermes process is marked single-query, cron or unattended, so no one could answer an approval.'
+        if not approval_context._is_interactive_cli():
+            return 'Hermes is not in interactive mode, so approvals could not reach the phone.'
+        if _get_approval_callback() is None:
+            return 'No phone approval callback is registered.'
+    except Exception as error:
+        return f'Could not verify Hermes approval settings ({type(error).__name__}). This Hermes version may not match Argus.'
+    return None
+
+
+def _hooks():
+    from hermes_cli import plugins
+    return plugins.get_plugin_manager()._hooks.setdefault('pre_tool_call', [])
+
+
+class MonitorGate:
+    """Observe Argus's tool classification without adding an approval directive."""
+    def __init__(self, report):
+        self.report = report
+        self.probing = False
+        self.probe_seen = False
+
+    def __call__(self, tool_name='', args=None, **_):
+        if self.probing:
+            self.probe_seen = True
+        else:
+            # No argument values, command text, transcript or credentials in observations.
+            self.report({'tool': str(tool_name)[:80],
+                         'outcome': 'read_only' if tool_name in READ_ONLY_TOOLS else 'would_request_approval'})
+        return None
+
+
+def install(mode='strict', report=None):
+    """Install only the host-selected mode; Hermes's approvals remain unchanged."""
+    if mode == 'monitor' and not callable(report):
+        raise ValueError('Monitor requires an observation callback')
+    if mode not in ('strict', 'monitor'):
+        raise ValueError('Unknown Argus guardrail mode')
+    from hermes_cli import plugins
+    plugins.get_plugin_manager().discover_and_load()
+    hook = gate if mode == 'strict' else MonitorGate(report)
+    hooks = _hooks()
+    if hook not in hooks:
+        hooks.append(hook)
+    verify(hook)
+    return hook
+
+
+def verify(hook=gate):
+    from hermes_cli.plugins import _get_pre_tool_call_directive_details
+    if not still_installed(hook):
+        raise RuntimeError('Argus phone hook is not registered')
+    if isinstance(hook, MonitorGate):
+        hook.probing, hook.probe_seen = True, False
+        try:
+            _get_pre_tool_call_directive_details('terminal', {'command': 'true'})
+            if not hook.probe_seen:
+                raise RuntimeError('Hermes did not dispatch the Argus monitor')
+        finally:
+            hook.probing = False
+    elif _get_pre_tool_call_directive_details('terminal', {'command': 'true'}).action not in ('approve', 'block'):
+        raise RuntimeError('Hermes did not route a tool call through the Argus approval gate')
+
+
+def still_installed(hook=gate):
+    try:
+        return hook in _hooks()
+    except Exception:
+        return False

package/prototypes/iphone-voice-spike/argus_task_ui.py

@@ -0,0 +1,153 @@
+"""Bounded presentation contract; no layouts, code, styles or action authority.
+
+Hermes answers the phone with {answer, ui}. `ui` is `argus-ui/1`: a title, up to
+six label/value cards, and one question with visible reply choices. Four
+optional sections extend a finished answer: `steps`, `list`, `notice` and
+`sources`. Everything is plain text that the phone draws with its own styles.
+The only URLs allowed anywhere are the https pages Hermes actually read with a
+tool while answering (or that the spoken answer already names), so a card can
+never invent a citation. Anything that breaks a bound is dropped, never repaired
+into a guess, and the plain answer still arrives.
+"""
+import json
+import re
+from urllib.parse import urlsplit
+
+# Decorative SF Symbols a card may name. The Mac removes unknown names before the
+# phone sees them; the phone and bridge treat any other name as invalid.
+SYMBOLS = frozenset({
+    'thermometer', 'cloud.sun', 'cloud.rain', 'sun.max', 'moon', 'wind', 'drop',
+    'clock', 'calendar', 'bell', 'mappin', 'figure.walk', 'car', 'bus', 'tram',
+    'fork.knife', 'cup.and.saucer', 'leaf', 'house', 'bed.double', 'pills', 'heart',
+    'stethoscope', 'dollarsign', 'creditcard', 'phone', 'envelope', 'message',
+    'person', 'person.2', 'globe', 'book', 'checkmark', 'exclamationmark.triangle',
+    'info.circle', 'questionmark.circle', 'star', 'tag', 'lightbulb', 'shield',
+})
+
+PRESENTATION_PROMPT = '''For your final response, return only a JSON object with keys answer and ui.
+answer is your concise plain-text spoken answer (at most 120 words). Argus reads it aloud and shows it as the lead paragraph, so put no headings, bullet lists, tables, code or links in it.
+ui is {"schema":"argus-ui/1","title":"Short task-specific title","cards":[{"label":"Short label","value":"Useful factual detail","symbol":"thermometer"}],"steps":["First step","Second step"],"list":[{"title":"Option","detail":"Why it fits"}],"notice":"What was not checked live, or a caveat","sources":[{"title":"Page title","url":"https://example.org/page"}],"question":"The single next useful preference question, or null","choices":["Visible reply one","Visible reply two"]}.
+Use at most 6 cards (label <=80 characters, value <=600), a title <=120, a question <=240, and at most 6 distinct choices <=160 characters. Empty cards/choices are fine.
+steps, list, notice and sources are optional: leave each out unless this answer needs it. steps: up to 8 short strings in order. list: up to 8 items with a short title (<=80) and an optional detail (<=200). notice: one sentence (<=240) naming what was not checked live or a caveat. sources: up to 5 pages you actually read with a tool while answering this request, with their exact https URLs; never invent a source, and never put URLs anywhere else in ui. symbol is optional on a card and must be one of: ''' + ', '.join(sorted(SYMBOLS)) + '''.
+The spoken answer should include the next question when there is one. Use unique card labels. Compose only what this actual task currently needs; preserve user choices from the conversation. Do not repeat the spoken answer in every card. Never invent live facts or completed actions. Choices are conversational preferences, not commands or confirmations: no approve, confirm, send, delete, purchase, pay, book, execute or run-command choices. Actions and approvals must use the existing clarify/approval tools, never presentation data. No Markdown fences, HTML, code, colors, layout instructions or extra keys in ui. If structure is unsuitable, ui may be null.'''
+
+CONVERSATION_ONLY_NOTE = ' No tools are available in this connection: never include sources, and say in notice when a live fact was not checked.'
+
+FORBIDDEN_CHOICE = re.compile(r'\b(approve|confirm|send|delete|purchase|pay|book|execute|run command)\b', re.I)
+_URL = re.compile(r'https://[^\s<>"\'\]\)\}]+')
+
+
+def plain(value, limit):
+    return isinstance(value, str) and bool(value.strip()) and len(value) <= limit and not re.search(r'[<>\x00-\x1f]', value)
+
+
+def source_url(value):
+    """An https URL without credentials, whitespace or quote characters, or None."""
+    if not isinstance(value, str) or len(value) > 300 or re.search(r'[\s<>"\']', value):
+        return None
+    parts = urlsplit(value)
+    if parts.scheme != 'https' or not parts.hostname or parts.username or parts.password:
+        return None
+    return value
+
+
+def urls_in(value, limit=20000):
+    """https URLs mentioned in a tool result or answer. Only a bounded prefix is scanned."""
+    if value is None:
+        return set()
+    if not isinstance(value, str):
+        try:
+            value = json.dumps(value, ensure_ascii=False, default=str)
+        except (TypeError, ValueError):
+            value = repr(value)
+    found = set()
+    for match in _URL.findall(value[:limit]):
+        url = source_url(match.rstrip('.,;:!?'))
+        if url:
+            found.add(url)
+    return found
+
+
+def _unique_texts(values, limit, count):
+    return (isinstance(values, list) and 1 <= len(values) <= count
+            and all(plain(v, limit) for v in values) and len(set(values)) == len(values))
+
+
+def valid_ui(ui):
+    return (isinstance(ui, dict) and set(ui) <= {'schema', 'title', 'cards', 'question', 'choices', 'steps', 'list', 'notice', 'sources'}
+        and ui.get('schema') == 'argus-ui/1' and plain(ui.get('title'), 120)
+        and isinstance(ui.get('cards'), list) and len(ui['cards']) <= 6
+        and all(isinstance(c, dict) and {'label', 'value'} <= set(c) <= {'label', 'value', 'symbol'}
+                and plain(c['label'], 80) and plain(c['value'], 600) and ('symbol' not in c or c['symbol'] in SYMBOLS) for c in ui['cards'])
+        and len(set(c['label'] for c in ui['cards'])) == len(ui['cards'])
+        and ('steps' not in ui or _unique_texts(ui['steps'], 200, 8))
+        and ('list' not in ui or (isinstance(ui['list'], list) and 1 <= len(ui['list']) <= 8
+             and all(isinstance(i, dict) and {'title'} <= set(i) <= {'title', 'detail'} and plain(i['title'], 80)
+                     and ('detail' not in i or plain(i['detail'], 200)) for i in ui['list'])))
+        and ('notice' not in ui or plain(ui['notice'], 240))
+        and ('sources' not in ui or (isinstance(ui['sources'], list) and 1 <= len(ui['sources']) <= 5
+             and all(isinstance(s, dict) and set(s) == {'title', 'url'} and plain(s['title'], 80) and source_url(s['url']) for s in ui['sources'])
+             and len(set(s['url'] for s in ui['sources'])) == len(ui['sources'])))
+        and (ui.get('question') is None or plain(ui['question'], 240))
+        and isinstance(ui.get('choices'), list) and len(ui['choices']) <= 6
+        and all(plain(c, 160) and not FORBIDDEN_CHOICE.search(c) for c in ui['choices'])
+        and len(set(ui['choices'])) == len(ui['choices'])
+        and (not ui['choices'] or plain(ui.get('question'), 240)))
+
+
+def prune(ui, allowed_urls=()):
+    """Remove what the model does not get to decide, then leave the rest to valid_ui.
+
+    Empty optional sections disappear, an unknown symbol is removed from its card,
+    and a source survives only when Hermes read that page (or the spoken answer
+    names it). Nothing else is repaired: a bound that is still broken drops the
+    whole ui and the plain answer stands alone.
+    """
+    if not isinstance(ui, dict):
+        return ui
+    ui = dict(ui)
+    for key in ('steps', 'list', 'notice', 'sources'):
+        if key in ui and not ui[key]:
+            del ui[key]
+    if isinstance(ui.get('cards'), list):
+        ui['cards'] = [{k: v for k, v in card.items() if k != 'symbol' or v in SYMBOLS} if isinstance(card, dict) else card
+                       for card in ui['cards']]
+    if isinstance(ui.get('sources'), list):
+        allowed, kept, seen = set(allowed_urls), [], set()
+        for source in ui['sources']:
+            url = source_url(source.get('url')) if isinstance(source, dict) else None
+            if not url or url not in allowed or url in seen:
+                continue
+            title = source.get('title') if plain(source.get('title'), 80) else (urlsplit(url).hostname or url)[:80]
+            kept.append({'title': title, 'url': url})
+            seen.add(url)
+        if kept:
+            ui['sources'] = kept
+        else:
+            del ui['sources']
+    return ui
+
+
+def presentation(final_response, allowed_urls=()):
+    """Split Hermes' final response into the spoken answer and a validated ui.
+
+    `allowed_urls` are the https pages Hermes actually read with a tool during
+    this request; together with any URL the spoken answer names, they are the
+    only sources a card may cite.
+    """
+    text = final_response.strip()
+    candidate = text
+    if text.startswith('```') and text.endswith('```'):
+        candidate = text.split('\n', 1)[-1].rsplit('```', 1)[0].strip()
+    try:
+        envelope = json.loads(candidate)
+    except (ValueError, TypeError):
+        envelope = None
+    if isinstance(envelope, dict) and isinstance(envelope.get('answer'), str) and envelope['answer'].strip():
+        answer = envelope['answer'].strip()
+        ui = envelope.get('ui')
+    else:
+        answer, ui = text, None
+    ui = prune(ui, set(allowed_urls) | urls_in(answer))
+    return {'answer': answer if len(answer) <= 4000 else answer[:3900] + '\n[Long answer shortened on iPhone.]',
+            'ui': ui if valid_ui(ui) else None}

package/prototypes/iphone-voice-spike/hermes-admin-host.mjs

@@ -0,0 +1,7 @@
+import { parentPort,workerData } from 'node:worker_threads';
+import { runHermesAdminDirect } from './hermes-admin.mjs';
+let run,cancelled=false;
+parentPort.on('message',message=>{if(message.cancel){cancelled=true;run?.cancel();}});
+try{run=runHermesAdminDirect(workerData);if(cancelled)run.cancel();const value=await run.result;parentPort.postMessage({value});}
+catch(error){parentPort.postMessage({failed:true,terminationConfirmed:!run||error?.terminationConfirmed===true});}
+parentPort.close();

package/prototypes/iphone-voice-spike/hermes-admin.mjs

@@ -0,0 +1,41 @@
+import { Worker } from 'node:worker_threads';
+import { spawn } from 'node:child_process';
+import { readdirSync,existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const unconfirmed=(terminationConfirmed=false)=>Object.assign(new Error('Administrative outcome unconfirmed.'),{terminationConfirmed});
+export function runHermesAdminDirect(input) {
+  const home=process.env.ARGUS_HERMES_HOME||resolve(homedir(),'.hermes');
+  const executable=process.env.ARGUS_HERMES_PYTHON||readdirSync(resolve(home,'tools')).filter(n=>n.startsWith('python-')).sort().reverse().map(n=>resolve(home,'tools',n,'bin/python3')).find(existsSync);
+  if(!executable)throw unconfirmed(true);
+  const child=spawn(executable,['-I',fileURLToPath(new URL('./hermes-admin.py',import.meta.url))],{stdio:['pipe','pipe','pipe']});
+  let output='',stopping=false,cancelRun;
+  const result=new Promise((accept,reject)=>{
+    let killTimer;
+    const stop=()=>{if(stopping)return;stopping=true;child.kill('SIGTERM');killTimer=setTimeout(()=>child.kill('SIGKILL'),2000);};
+    cancelRun=stop;
+    const timer=setTimeout(stop,20000);
+    child.stdout.on('data',chunk=>{output+=chunk;if(output.length>64000)stop();});
+    child.stderr.resume();
+    child.stdin.on('error',stop);child.on('error',stop);
+    // Settle only after close: cancellation is not proof that the child can no longer write.
+    child.on('close',code=>{clearTimeout(timer);clearTimeout(killTimer);if(stopping){reject(unconfirmed(true));return;}
+      try{const value=JSON.parse(output);if(code!==0||!value||value.error)throw new Error();accept(value);}catch{reject(unconfirmed(true));}});
+    child.stdin.end(JSON.stringify(input)+'\n');
+  });
+  return {result,cancel:()=>cancelRun(),pid:child.pid};
+}
+const activeHosts=new Set();
+export function runHermesAdmin(input) {
+  if(activeHosts.size>=2)throw unconfirmed(true);
+  const host=new Worker(new URL('./hermes-admin-host.mjs',import.meta.url),{workerData:input});activeHosts.add(host);
+  let settled=false;
+  const result=new Promise((accept,reject)=>{
+    const timer=setTimeout(()=>{if(!settled)host.postMessage({cancel:true});},25000);
+    host.on('message',message=>{if(settled)return;settled=true;clearTimeout(timer);message.value?accept(message.value):reject(unconfirmed(message.terminationConfirmed===true));});
+    host.on('error',()=>{clearTimeout(timer);if(!settled){settled=true;reject(unconfirmed(false));}});
+    host.on('exit',()=>{activeHosts.delete(host);clearTimeout(timer);if(!settled){settled=true;reject(unconfirmed(false));}});
+  });
+  return {result,cancel:()=>host.postMessage({cancel:true})};
+}

package/prototypes/iphone-voice-spike/hermes-admin.py

@@ -0,0 +1,40 @@
+"""Isolated administrative operations. Secret input uses stdin only; output is metadata only."""
+import contextlib
+import json
+import os
+from pathlib import Path
+import sys
+
+wire = sys.stdout
+home = Path(os.environ.get('ARGUS_HERMES_HOME', Path.home() / '.hermes')).resolve()
+source = Path(os.environ.get('ARGUS_HERMES_SOURCE', home / 'hermes-agent')).resolve()
+os.environ['HERMES_HOME'] = str(home)
+sys.path.insert(0, str(source))
+sys.path.append(str(Path(__file__).resolve().parent))  # -I omits the script folder
+value = None
+try:
+    request = json.loads(sys.stdin.readline(64001))
+    with contextlib.redirect_stdout(sys.stderr):
+        import hermes_bootstrap  # the same dependency activation hermes-worker.py uses
+        from argus_admin import catalog, save_login, existing_vault_guard
+        action = request.get('action')
+        if action == 'save_login':
+            from agent.vault_store import get_vault_store
+            store = get_vault_store()
+            with existing_vault_guard(store):
+                value = save_login(request['login'], store)
+        elif action == 'catalog':
+            from hermes_cli.config import load_config
+            from hermes_cli.runtime_provider import resolve_runtime_provider
+            from hermes_cli.models import provider_model_ids
+            config = load_config()
+            default = config['model']['default']
+            runtime = resolve_runtime_provider(requested=config['model'].get('provider'), target_model=default)
+            value = catalog(default, runtime['provider'], provider_model_ids(runtime['provider']))
+        else:
+            raise ValueError('Unknown administrative operation')
+except Exception:
+    # Never serialize exceptions: provider/vault failures may contain sensitive values.
+    value = {'error': 'Hermes administrative operation did not complete.'}
+wire.write(json.dumps(value, ensure_ascii=False) + '\n')
+wire.flush()