2 Commits

Author	SHA1	Message	Date
Siddharth Balyan	0e927c914d	Guided first launch behind HERMES_GUEST_ONBOARDING: intro, guided chat, first task in default (NS-848, PR B1) (#107958) ... * feat(desktop): port guided onboarding substrate Add seeded session creation, transcript directives, profile routing, and the shared window and pane primitives needed by the guided flow. Keep later-step mounts deferred and exclude provider selection and retry machinery. * refactor(desktop): anti-slop cleanup for substrate Assemble seed parameters in the existing create helper and use the owning transcript attribute type. Read the guaranteed gateway and connection contracts directly to remove runtime type probes and unchecked assertions. * test(desktop): create-overrides invariants Verify that reasoning and title overrides do not select a provider or model. Empty overrides and seeds add no parameters. * feat(desktop): port first-run cinematic window Play the cinematic behind the guest onboarding launch flag using bundled Collapse and JetBrains Mono. Give the native window its own controller and restore the app on skip, renderer deadman or native watchdog. Drop the perf scenario because it depends on the removed replay hook. Guided chat kickoff and app-shell gate wiring remain with their later steps. * refactor(desktop): anti-slop cleanup for cinematic Preserve audio and canvas behavior through named types and inferred results. Split the viewport node and frame drawing to keep control flow bounded. Cut comments that only repeat the code. * feat(desktop): add onboarding gate and answers stores Track cinematic, guided chat, handoff and completion in one phase record. Queue the guide after the intro and share pending kickoff work between callers. Keep existing saved answers while dropping retired preferences. Leave intro seen-state ownership with the cinematic store. * feat(desktop): port guided onboarding chat Add guided setup cards, runbooks, machine context, and onboarding presence. Connect transcript rendering and first-build progress to the desktop behind the onboarding flag. Leave session kickoff and handoff execution for the next step. * refactor(desktop): anti-slop cleanup for guided chat Keep directive and layout lookups typed. Remove unsafe test casts and isolate onboarding transcript calculations without changing the flow. * feat(desktop): connect guided onboarding to durable first-build handoff Start the guide only after its profile backend confirms bootstrap readiness. Seed or adopt the welcome chat, then transfer the first build to default with a durable receipt and explicit retry. Wire cinematic completion, screen stand-down, layout growth and progress check-ins. Save agreed preferences before creating the build and release prompt slots after storage refusal. * refactor(desktop): anti-slop cleanup for onboarding handoff Reuse the gateway request and error contracts. Isolate guide adoption and snapshot validation while preserving receipt recovery and reasoning overrides. Validate persisted receipt fields at the JSON boundary without coercion. Keep corrupt identities rejected and retain only the permitted test mocks. * fix(desktop): guided chat review fixes Wire the native machine probe so guided setup can suggest a name and offer the right first task. Restore the comments that explain the flow boundaries. The directive registration uses the launch flag to preserve ordinary chat. Ruling 6 folds active.ts into assembly to keep activity ownership together and removes the second greeting source so the seeded and visible greetings agree. * fix(desktop): handoff review fixes Probe the guide backend before switching profiles so a readiness refusal keeps classic onboarding on the current backend. Restore list-valued personalization coverage and routing rationale. Remove the obsolete setup status fixture. * chore(desktop): onboarding script cull and rehearsal recipe Document a temporary-state rehearsal using the existing onboarding flag and optional portal stand-in. Keep the main scripts unchanged and retain window growth for the guided chat. * fix(connectors): reject incomplete catalog responses * feat(gateway): scope connector controls to the owning session * feat(desktop): connect apps through native session-owned controls * feat(desktop): gate connector cards and enable free-tier access Use the launch flag before mounting connector controls so classic transcripts add no status requests. Allow existing free-tier identities through the read-only tool gateway gate and test the owning-profile RPC path with A’s launch gate. Keep authorization links out of previews. * style(desktop): format connector translations Apply Prettier to the connector copy blocks while preserving upstream translations and free-tier wording. * refactor(desktop): anti-slop cleanup for connector card Use the transcript JSON contract and concrete RPC parameters. Preserve malformed-value filtering at one string boundary and make the fixture and row types explicit. Keep connector execution and cancellation behavior unchanged. * feat(desktop): detect initial language from the OS Use the native machine locale when no supported language is saved. Preserve explicit choices and leave inferred languages out of config. * refactor(desktop): anti-slop cleanup for initial locale detection Keep unvalidated config values at the existing validation boundary. Pass no saved choice after that boundary has ruled it out, preserving locale precedence. * test(desktop): onboarding port test set Make native window tests reject duplicate IPC handlers and isolate disabled onboarding. Assert the active gate mock when onboarding re-enables. Keep the test set limited to behavior carried by the port. * fix(desktop): recover failed guide kickoff and reveal once The review found that a failed guide create stranded the solo shell and draft profile, and solo boot faded an already visible window a second time. Restore the prior route and layout, release onboarding through its existing phase record, and surface create failures. Let the film own the reveal while solo boot animates the visible resize. * fix(desktop): preserve transcript ownership across cards and handoff The review reproduced answers submitted to the focused chat, repeated questions disabled across sessions, handoff recovery using foreground identity, and mount-dependent progress history. Target each card’s own composer, scope settlement to its message and session, carry the issuing guide through handoff, and derive progress from its transcript with streaming activity. Reuse the existing owner ladder for exact and profile-only routes. * fix(gateway): preserve connector ownership with profile routing The review found that shared-primary profile metadata was rejected before connector dispatch, while desktop controls treated a missing registry id as missing ownership. Accept profile only as routing metadata and keep the live transport as authorization. Resolve card ownership through the existing exact/profile ladder, retaining ambient routing only for the single-backend case. * fix(desktop): resolve plugin roots and gate the Basic layout The review found that the first plugin build was seeded with a different installation’s fixed path, and the director ruled that flag-off layouts must match main. Resolve the running desktop’s plugin root before seeding a plugin build and register Basic only when onboarding is enabled. Keep the runbook wording and the ordinary four layout presets intact. * fix(desktop): clear review-fix slop findings The slop gate flagged an undocumented layout-data assertion and unknown-return types in the new test selectors. Record the layout registry invariant and preserve each selector’s return type. The only remaining production finding is the accepted connector-tools baseline. * fix(desktop): detect the OS language on a fresh install The review found that the merged English config default prevented the desktop from probing the OS language on a fresh install. Add an opt-in saved-values read so an absent choice remains distinct from saved English. Preserve default-valued English only for explicit language saves; unrelated settings saves must not turn a merged default into a language choice. Older backends ignore the new query options and keep returning merged English, preserving their existing desktop behavior. * test(desktop): make the flag-off layout registry test deterministic The flag-off test awaited the full controller import, pulling in the UI graph and installing application watchers just to read layout presets. That import took 9.5 seconds locally and timed out in the director's run. Move the existing trees and registration into a small layout-presets module. Production and the synchronous test use the same flag-gated registration, without starting the controller in the test. Keep the real registry invariant and dispose the test's contributions after completion. * fix(desktop): keep the transcript parser and ::ask behind the onboarding flag Register the guided chat's question card only with onboarding enabled. Restore main's whole-paragraph parser and contribution rendering when the flag is off, including its streaming prose behavior. Keep segmentation for the guided flow until B4 decides the parser's wider use. Restore main's two parser test files so its existing product and plugin contracts remain the flag-off check. * test: drop the onboarding and connector tests pending a later ticket Apply the director's ruling to remove B1's added test files and restore main's existing suites. Keep only the gateway route-reader mock contract that main's profile tests need against the shipped activation behavior; their cases and assertions stay intact. The flow's shape is not settled and B3/B4 rewrite it. The connector layer will also be reworked. The live CDP run is the flow check until a follow-up ticket brings tests back. --------- Co-authored-by: brooklyn! <brooklyn.bb.nicholson@gmail.com>	2026-09-11 15:45:43 +05:30
Siddharth Balyan	b4d04eb8fd	Connector tools (Gmail, Linear, Notion, ...) are searchable and callable through tool_search for signed-in Nous users (#106842) ... * feat: add session-scoped connector access for onboarding * fix(connectors): availability is the config flag AND the portal entitlement — no free-tier leg The port carried a third availability leg from hermes-magic: a stored guest (free-tier) identity short-circuits the managed-tool entitlement check. That leg reads hermes_cli.anon_auth, which does not exist on hermes-agent main, so connectors_available() raised ImportError inside its fail-closed try and the whole connector surface was silently dark on a plain upstream checkout. On this tree availability is the two-leg AND the design started with: tools.connectors.enabled AND managed_nous_tools_enabled(). The free-tier leg is a hermes-magic concern and belongs in hermes-magic's own delta over this branch, next to the identity it depends on. Its integration test goes with it. * docs(tool-search): connectors section — remote tools through the bridge The squashed port carried the code but not the user-facing docs. Restores the Connectors section of the Tool Search page and the connector-gateway host / CONNECTOR_GATEWAY_URL override on the Tool Gateway page, updated for the manage_connections tool and the pure-connector batch rule. * fix(tool-search): connector tools rank with local tools in one pass instead of taking leftover slots dispatch_tool_search ran BM25 over the local catalog, filled `limit` slots, then appended connector hits only into slots left empty. On a 300-tool catalog no slot was ever empty, so with Gmail and Google Calendar connected "send gmail email" returned five betterstack tools and zero connector tools. The gateway's hits for a query now become catalog entries (connector name, slug words, description as the search text) and join the local catalog for that query's BM25 pass. One ranking, one rarest-token admission rule for both sources, `limit` as the total per query. The merge loop and the separate record builder for connector hits are gone; `_shared_tool_record` serves both sources. The gateway search timeout rises from 8 s to 30 s. One request with six use_cases measured 7 s, so 8 s sat on the edge and cut real answers off; the failure path is unchanged (local-only results, no error to the model). Live, 311 local tools + gateway, before -> after: "send gmail email": 5 betterstack tools -> gmail SEND_EMAIL, CREATE_EMAIL_DRAFT "read google calendar events": 5 betterstack tools -> googlecalendar EVENTS_LIST_ALL_CALENDARS "linear create issue", "betterstack incident": unchanged Benchmark (25 labelled queries): connector recall 0.09 -> 0.82, precision@5 0.18 -> 0.59, false positives on absent intents 17 -> 2. * refactor(tool-search): connector leg into tools/connector_search.py tools/tool_search.py is a facade. The connector leg (gateway hits as catalog entries for tool_search, remote schemas for tool_describe, the connections_in_scope gate) was appended to it by the port. It now lives in its own sibling, tools/connector_search.py, and the facade imports the three entry points: connections_in_scope, connector_entries_by_group, remote_schemas_for. No behaviour change. The tool_describe remote block became remote_schemas_for(names, current_tool_defs, connector_describe) with the same inputs, the same silent-degradation contract and the same injection seam the tests already use. * fix(tool-search): at most 7 queries per call, the gateway's search limit One tool_search call sends all its queries to the connector gateway as one search request. The gateway answers 7 use_cases per request and returns HTTP 502 for 8 or more (measured 2026-09-09, re-measured with one-word use_cases: it is a count limit, not a size limit). With the client cap at 10, a model sending 8 to 10 queries lost every connector hit for that call and saw local-only results with no error. The shared constant splits: _MAX_QUERIES_PER_CALL = 7 for search, _MAX_DESCRIBE_NAMES_PER_CALL = 10 for describe, which has no remote count limit. Eight or more queries now get the existing "too many queries" retry hint before any request is made. No chunking: one call, one request. * fix(tool-search): the model is told that connectors__ names are manage_connections accounts tool_search results carry names like connectors__gmail__CREATE_EMAIL_DRAFT and manage_connections is the tool that checks and connects those accounts, but nothing told the model the two are the same thing. A model that hit CONNECTION_REQUIRED had to infer the fix on its own. The tool_search description gains one sentence making the link, added at assembly only when manage_connections is in the session's tools. Signed out or with connectors off the tool is absent and the description is unchanged, so it never names a tool the model cannot call. This follows the existing rule for cross-tool references (tools/AGENTS.md): they are added dynamically from the session's actual tool set, never hardcoded in a schema. Tool defs are fixed for the life of a conversation, so the description is byte-stable per conversation; this is a one-time prefix change. Live, real get_tool_definitions() against a signed-in home: sentence present. Same home with auth.json removed: manage_connections absent, sentence absent. * fix(connectors): /stop halts a connector batch before the next remote call dispatch_connector_batch runs every remote entry of a tool_call batch in sequence. The executor only checks the interrupt flag between tools, and the whole batch is one tool to it, so a /stop landing during entry 1 of 20 still sent the other 19 to the gateway. The loop now reads tools.interrupt.is_interrupted before each dispatch. Once set, it stops calling handle_function_call and fills every unstarted slot with the loop's existing error-slot shape, code INTERRUPTED and the message "Stopped by the user before this call was made.", so the result envelope stays valid and the counts stay honest. Entries already dispatched keep their real results. Test: three connector calls where the fake client sets the interrupt on the first execute. The client sees exactly one call and slots 2 and 3 carry INTERRUPTED. Red on the base branch, green with the fix. * test(connections): schema assertions become dispatch contracts test_schema_documents_wait_and_its_timeout froze description fragments ("REQUIRED", "can NOT disconnect", "Nous Portal"). A wording edit fails it while a real regression (a disconnect that reaches the gateway) does not. That is a snapshot of prose, not a behaviour contract. Delete it. The requirement that wait needs connectors is already covered by test_wait_requires_connectors. The user-only disconnect boundary is now asserted as behaviour: action disconnect with a connector returns an error and the fake client records no call. That replaces the earlier de-authenticate test, which only checked that the word "dashboard" appeared in the error text. Test count in the file goes from 26 to 25. * docs(tool-search): connector batches are one gateway request per entry The user guide said a connector batch travels as one gateway request. It does not: model_tools_connectors.dispatch_connector_batch re-enters core dispatch per entry, and each entry becomes its own execute request in bridge._run_remote (plus at most one literal-slug retry when the gateway reports TOOL_NOT_FOUND under the conventional slug). The docstrings in tools/tool_gateway/bridge.py and tools/tool_gateway/__init__.py still described the abandoned V1 plan and claimed nothing outside the package imports it. Rewrite those sentences to match the code: one request per entry, in input order, dispatched from model_tools_connectors.py, with the per-entry approval and interrupt behaviour that motivated the split. The guide also still showed the single-call shape tool_call(name, arguments); both places now show the `calls: [{name, arguments}]` array the schema advertises and note that a single local call is an array of one. Docs only, no test. * fix(tools): the between-turns refresh never rewrites the bridge tools The per-turn MCP refresh folds a fresh tool snapshot into the live array with preserve_prefix: order and membership stay, but a name present in both takes the fresh schema. That is right for ordinary tools, whose schema is a constant. tool_search is the one tool whose description is derived from the session: the deferred-tool count, the embedded listing, and, on this branch, whether manage_connections was present. A late MCP server or one failed portal lookup (manage_connections' check_fn fails closed) changed those bytes on the next turn, and every byte after tool_search in the cached prefix was re-prefilled. The array also contradicted itself in that case: the flapping manage_connections was carried forward while the description lost its hint. The bridge entries now keep the bytes they were built with for the life of the conversation. Nothing is lost: tool_search reads the live catalog at dispatch, so tools that arrived late are still found; connector availability is checked at dispatch too. The compaction-boundary rebuild (content_aware, the one sanctioned cache break) still refreshes the description. Consequence: connector exposure in the prompt is decided once, at agent build, by whether the user was signed in then. That is the intended contract. * refactor(tool-search): normalize_tool_call_entries lives with the other argument validation The port appended the tool_call argument parser to the tool_search facade. The family already has tools/tool_search_validation.py for exactly this work (schema validation of deferred call arguments), so the parser moves there and the facade imports it. No behaviour change; the one test that imported it now imports from the defining module. * refactor(connectors): delete the unused batch dispatcher; _run_remote becomes run_remote bridge.dispatch_calls and its helpers (_dispatch_calls_inner, _run_pre_dispatch, _run_local, _error_slot, _maybe_parse_json) and the LocalDispatch / PreDispatch seams had no production caller. Connector dispatch runs through model_tools_connectors: dispatch_connector_batch re-enters handle_function_call once per entry, so scope, hook, approval and middleware policy fire against each composed name inside core dispatch, and dispatch_connector_call hands the single planned entry to the bridge's transport function. Only tests called the batch dispatcher, and they exercised policy seams that production never wires. The transport function is the module's real entry point, so it drops the underscore: _run_remote becomes run_remote, body unchanged. The module docstring now describes the two legs that exist (availability with D32 silent degradation, and run_remote) instead of the injected seams. Imports that only the deleted code used are gone; merge.py is untouched because every export still has a caller. Tests that drove dispatch_calls are deleted where they covered the removed seams (pre_dispatch blocks and rewrites, local_dispatch classification, mixed batches). The literal-slug fallback, the per-entry transport failure, and the hook rewrite reaching the gateway request body are re-targeted at handle_function_call('tool_call', ...) with the fake client swapped in at bridge._default_client_factory, the same seam test_connector_dispatch_policy uses. Each re-targeted test fails when the retry is disabled in run_remote. * fix(connectors): search keeps the twin a colliding name reaches, and says so format_connector_name strips the toolkit prefix, so GMAIL_FETCH_PROFILE and a literal FETCH_PROFILE on gmail both compose to connectors__gmail__FETCH_PROFILE. describe and execute decode that name to the prefixed slug first, so the literal twin is unreachable under it. If a vendor ever shipped both, search could describe the literal under a name that runs the prefixed tool. Search is the one place that sees both twins in one response. It now keeps the twin the name reaches and drops the other with a WARNING that names both slugs, whichever the gateway listed first. Short names stay; no marker, no per-process map, no change to describe or execute. No such pair exists in the live catalog today; the guard turns a silent alias into a logged one.	2026-09-10 02:21:16 +05:30