@bigbinary/neeto-assist-frontend 1.2.0 → 1.3.0-beta1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/README.md +430 -21
  2. package/app/javascript/src/translations/ar.json +7 -1
  3. package/app/javascript/src/translations/bg.json +7 -1
  4. package/app/javascript/src/translations/ca.json +7 -1
  5. package/app/javascript/src/translations/cs.json +7 -1
  6. package/app/javascript/src/translations/da.json +7 -1
  7. package/app/javascript/src/translations/de.json +7 -1
  8. package/app/javascript/src/translations/en.json +39 -2
  9. package/app/javascript/src/translations/es-MX.json +7 -1
  10. package/app/javascript/src/translations/es.json +7 -1
  11. package/app/javascript/src/translations/et.json +7 -1
  12. package/app/javascript/src/translations/fi.json +7 -1
  13. package/app/javascript/src/translations/fil.json +7 -1
  14. package/app/javascript/src/translations/fr.json +7 -1
  15. package/app/javascript/src/translations/he.json +7 -1
  16. package/app/javascript/src/translations/hi.json +7 -1
  17. package/app/javascript/src/translations/hr.json +7 -1
  18. package/app/javascript/src/translations/hu.json +7 -1
  19. package/app/javascript/src/translations/id.json +7 -1
  20. package/app/javascript/src/translations/it.json +7 -1
  21. package/app/javascript/src/translations/ja.json +7 -1
  22. package/app/javascript/src/translations/ko.json +7 -1
  23. package/app/javascript/src/translations/lv.json +7 -1
  24. package/app/javascript/src/translations/nl.json +7 -1
  25. package/app/javascript/src/translations/pl.json +7 -1
  26. package/app/javascript/src/translations/pt-BR.json +7 -1
  27. package/app/javascript/src/translations/pt.json +7 -1
  28. package/app/javascript/src/translations/ro.json +7 -1
  29. package/app/javascript/src/translations/ru.json +7 -1
  30. package/app/javascript/src/translations/sk.json +7 -1
  31. package/app/javascript/src/translations/sl.json +7 -1
  32. package/app/javascript/src/translations/sv.json +7 -1
  33. package/app/javascript/src/translations/th.json +7 -1
  34. package/app/javascript/src/translations/tr.json +7 -1
  35. package/app/javascript/src/translations/uk.json +7 -1
  36. package/app/javascript/src/translations/vi.json +7 -1
  37. package/app/javascript/src/translations/zh-CN.json +7 -1
  38. package/app/javascript/src/translations/zh-TW.json +7 -1
  39. package/dist/.ready +1 -1
  40. package/dist/NeetoAssistButton.js +13 -6
  41. package/dist/NeetoAssistButton.js.map +1 -1
  42. package/dist/NeetoAssistPane.js +1469 -166
  43. package/dist/NeetoAssistPane.js.map +1 -1
  44. package/dist/cjs/NeetoAssistButton.js +16 -9
  45. package/dist/cjs/NeetoAssistButton.js.map +1 -1
  46. package/dist/cjs/NeetoAssistPane.js +1491 -188
  47. package/dist/cjs/NeetoAssistPane.js.map +1 -1
  48. package/dist/cjs/index.js +11 -5
  49. package/dist/cjs/index.js.map +1 -1
  50. package/dist/cjs/useNeetoAssistAssistant.js +43 -0
  51. package/dist/cjs/useNeetoAssistAssistant.js.map +1 -0
  52. package/dist/cjs/useNeetoAssistStatus.js +3 -1
  53. package/dist/cjs/useNeetoAssistStatus.js.map +1 -1
  54. package/dist/index.js +10 -5
  55. package/dist/index.js.map +1 -1
  56. package/dist/neeto_assist-COp7BR77.js +249 -0
  57. package/dist/neeto_assist-COp7BR77.js.map +1 -0
  58. package/dist/neeto_assist-D1wzZ3ou.js +219 -0
  59. package/dist/neeto_assist-D1wzZ3ou.js.map +1 -0
  60. package/dist/useNeetoAssistAssistant.js +41 -0
  61. package/dist/useNeetoAssistAssistant.js.map +1 -0
  62. package/dist/useNeetoAssistStatus.js +3 -1
  63. package/dist/useNeetoAssistStatus.js.map +1 -1
  64. package/dist/useNeetoAssistStore-Bj6niQdc.js +103 -0
  65. package/dist/useNeetoAssistStore-Bj6niQdc.js.map +1 -0
  66. package/dist/useNeetoAssistStore-Dgt8aV52.js +101 -0
  67. package/dist/useNeetoAssistStore-Dgt8aV52.js.map +1 -0
  68. package/dist/{useNeetoAssistStore-InICsbe8.js → useRunsApi-BgsICthX.js} +228 -113
  69. package/dist/useRunsApi-BgsICthX.js.map +1 -0
  70. package/dist/{useNeetoAssistStore-VaZp3268.js → useRunsApi-Rh6xXOwm.js} +232 -112
  71. package/dist/useRunsApi-Rh6xXOwm.js.map +1 -0
  72. package/package.json +4 -4
  73. package/types.d.ts +81 -8
  74. package/dist/neeto_assist-CpUBA-3Z.js +0 -135
  75. package/dist/neeto_assist-CpUBA-3Z.js.map +0 -1
  76. package/dist/neeto_assist-CznTN_YY.js +0 -157
  77. package/dist/neeto_assist-CznTN_YY.js.map +0 -1
  78. package/dist/useNeetoAssistStore-InICsbe8.js.map +0 -1
  79. package/dist/useNeetoAssistStore-VaZp3268.js.map +0 -1
package/README.md CHANGED
@@ -20,6 +20,7 @@ something up in the host for a rep.
20
20
  - [Host adapter](#host-adapter)
21
21
  - [Asking for a reply suggestion](#asking-for-a-reply-suggestion)
22
22
  - [Lookups and actions](#lookups-and-actions)
23
+ - [The assistant and product lookups](#the-assistant-and-product-lookups)
23
24
  - [The grant, and what a host trusts](#the-grant-and-what-a-host-trusts)
24
25
  - [Endpoints](#endpoints)
25
26
  2. [Frontend package](#frontend-package)
@@ -80,9 +81,17 @@ NeetoAssistEngine.configure do |config|
80
81
  # Optional, in seconds. How long a click on one of NeetoAssist's own actions
81
82
  # waits for NeetoAssist to run it. This is the default.
82
83
  config.own_action_read_timeout = 20
84
+ # Optional, in seconds. How long one of the product's own lookups may run
85
+ # before the engine stops it and tells NeetoAssist it failed. This is the
86
+ # default.
87
+ config.product_lookup_timeout = 20
83
88
  # Optional. How long NeetoAssist may look things up as the rep who asked.
84
89
  # 15 minutes is the default and the most: a host can only shorten it.
85
90
  config.grant_ttl = 15.minutes
91
+ # Only for a product that shares its lookups with people who ask NeetoAssist
92
+ # in another Neeto product: NeetoAssist's public key for passes (Ed25519,
93
+ # PEM). Line breaks written as the two characters \n are read as line breaks.
94
+ config.pass_public_key = ENV["NEETO_ASSIST_PASS_PUBLIC_KEY"]
86
95
  end
87
96
  ```
88
97
 
@@ -107,8 +116,8 @@ subclass of `NeetoAssistEngine::HostAdapter`:
107
116
  | Method | Returns |
108
117
  | --- | --- |
109
118
  | `enabled?(organization)` | Whether NeetoAssist is on for the workspace: the host's rollout gate, such as a Flipper flag on `Organization`. |
110
- | `find_conversation(organization, conversation_id)` | The conversation with that id in that workspace, or `nil`. |
111
- | `can_use?(user, conversation)` | Whether this rep may see NeetoAssist on the conversation. |
119
+ | `find_conversation(organization, conversation_id)` | The conversation with that id in that workspace, or `nil`. Defaults to `nil`, for a product that offers only the assistant. |
120
+ | `can_use?(user, conversation)` | Whether this rep may see NeetoAssist on the conversation. Defaults to `false`. |
112
121
  | `can_buy_credits?(user)` | Whether this rep may buy NeetoAssist credits, such as a workspace admin. Defaults to `false`. Only they get the link to buy more once the workspace runs out. |
113
122
  | `conversation_payload(conversation)` | The conversation as NeetoAssist takes it (below), built when it is sent. |
114
123
  | `conversation_external_id(conversation)` | The conversation's id in NeetoAssist. Defaults to `conversation.id.to_s`. |
@@ -117,6 +126,14 @@ subclass of `NeetoAssistEngine::HostAdapter`:
117
126
  | `actions(user, conversation)` | The `NeetoAssistEngine::Action` classes NeetoAssist may suggest to this rep. Defaults to `[]`. |
118
127
  | `find_user(organization, user_id)` | The workspace's person with that id, or `nil`. Defaults to `organization.users.find_by(id: user_id)`. The engine finds the rep again with it for every lookup. |
119
128
  | `user_role(user)` | The rep's role in a word or two, such as "Admin". Defaults to `nil`. NeetoAssist is told who it is talking to. |
129
+ | `user_time_zone(user)` | The person's time zone, an IANA name such as "Asia/Kolkata" or one of Rails' zone names. Defaults to `user.try(:time_zone)`. NeetoAssist reads "tomorrow" in it. |
130
+ | `product_lookups(user, conversation)` | The product's own MCP read tools NeetoAssist may use as this person ([below](#the-assistant-and-product-lookups)). Defaults to `ProductLookups.none`. `conversation` is `nil` in the assistant. |
131
+ | `shared_lookups(user)` | The product's own MCP read tools for a person who is asking NeetoAssist in another Neeto product ([below](#shared-lookups-for-a-person-asking-in-another-product)). Defaults to `ProductLookups.none`. |
132
+ | `find_user_by_guid(organization, guid)` | The workspace's person with that NeetoAuth guid, in lower case, or `nil`. Defaults to `organization.users.find_by(guid:)`. |
133
+ | `assistant?(user)` | Whether this person may open NeetoAssist as their own assistant. Defaults to `false`. |
134
+ | `assistant_context(user, page)` | What the person is looking at in the assistant, from `page` (`{ "path" => ..., "title" => ... }`, from the browser). Defaults to `{}`. |
135
+ | `assistant_tools(user)` | The Tool classes NeetoAssist may look things up with in the assistant, built with `conversation: nil`. Defaults to `[]`. |
136
+ | `assistant_suggestions(user)` | The first questions the pane offers on an empty thread, at most six short sentences. Defaults to `[]`. |
120
137
 
121
138
  ```ruby
122
139
  module NeetoAssist
@@ -165,8 +182,13 @@ end
165
182
  each with `id`, `author` (`visitor`, `agent` or `bot`), `author_name`, `body` (plain text, at most 4,000 characters)
166
183
  and `created_at`. Leave private notes out.
167
184
 
168
- If `context`, `tools`, `actions` or `user_role` raises, the rep's question still goes to NeetoAssist, without that
169
- part, and the error goes to Honeybadger.
185
+ If `context`, `tools`, `actions`, `product_lookups`, `user_role` or `user_time_zone` raises, the rep's question still
186
+ goes to NeetoAssist, without that part, and the error goes to Honeybadger.
187
+
188
+ A host that has conversations and no assistant, such as NeetoChat, overrides none of the assistant methods and
189
+ `product_lookups`, and nothing changes for it. With every question the engine also tells NeetoAssist the asker's
190
+ NeetoAuth `guid`, when the user has one, and their `time_zone`. A host that shares nothing overrides neither
191
+ `shared_lookups` nor `find_user_by_guid` and sets no `pass_public_key`.
170
192
 
171
193
  ### Asking for a reply suggestion
172
194
 
@@ -241,6 +263,8 @@ end
241
263
  nothing and goes to Honeybadger.
242
264
  - `summary(result)` is a few words about the result for the pane, such as "3 people". The rep reads them, so
243
265
  translate them as the host translates its own screens ([below](#the-language-of-a-lookup-and-a-card)).
266
+ - `sources(result)` names the records of the result a person can be pointed to, so an answer built on one can
267
+ show it under the answer as a link ([below](#a-tool-that-names-its-sources)). None by default.
244
268
  - `available?` says whether this rep may use the tool on this conversation. NeetoAssist is never told about a tool
245
269
  that is not available, and cannot call it.
246
270
 
@@ -251,7 +275,70 @@ A tool has `organization`, `user` (the rep who asked) and `conversation`. Three
251
275
  finder the host's screens use.
252
276
  2. **Only read.** The engine runs a lookup with writes to the database refused, so a tool that tries to change
253
277
  something raises `ActiveRecord::ReadOnlyError`. A change is an action.
254
- 3. **Be quick.** NeetoAssist waits 8 seconds for a lookup.
278
+ 3. **Be quick.** NeetoAssist waits 8 seconds for a lookup on a conversation and 25 in the assistant, and less when
279
+ its answer is nearly out of time.
280
+
281
+ #### A tool that names its sources
282
+
283
+ An answer lists what it rests on under it. A tool that returns records with pages of their own, such as earlier
284
+ conversations, names each of them in `sources`, and the answer can then say "in the conversation of 3 November
285
+ about the refund" and link to it. A tool that names none is listed by itself, with its label and summary.
286
+
287
+ ```ruby
288
+ module NeetoAssist
289
+ module Tools
290
+ class SearchConversations < NeetoAssistEngine::Tool
291
+ description "Finds the customer's earlier conversations by words in them, newest first, at most 10."
292
+ label "Searching earlier conversations"
293
+ param :query, :string, description: "Words to look for."
294
+
295
+ def call(query:)
296
+ ConversationPolicy::Scope.new(user, organization.conversations).resolve.search(query).limit(10).map do |found|
297
+ { id: found.id, contact: found.contact.name, started_at: found.created_at.iso8601 }
298
+ end
299
+ end
300
+
301
+ def sources(result)
302
+ result.map do |found|
303
+ title = I18n.t(
304
+ "neeto_assist.sources.conversation", name: found[:contact],
305
+ date: I18n.l(Time.zone.parse(found[:started_at]).to_date, format: :long))
306
+ {
307
+ kind: "conversation",
308
+ id: found[:id],
309
+ title: title.truncate(NeetoAssistEngine::Sources::MAX_TITLE_LENGTH),
310
+ url: Rails.application.routes.url_helpers.admin_conversation_url(found[:id], subdomain: organization.subdomain)
311
+ }
312
+ end
313
+ end
314
+ end
315
+ end
316
+ end
317
+ ```
318
+
319
+ - `sources(result)` gets what `call` returned and returns at most 25 hashes of `kind:`, `id:`, `title:` and `url:`. `title`
320
+ is what a person reads under the answer, at most 200 characters. `id` is how the record is named in the result,
321
+ a text or a whole number of at most 100 characters, so that NeetoAssist can tell which source is which record.
322
+ `url` is the record's own page in the product, `http` or `https`. `kind` is `"conversation"` for an exchange with
323
+ a customer and `"record"` for anything else that has a page of its own, such as an issue. `kind`, `id` and `url`
324
+ may be left out. Without a `kind`, NeetoAssist works it out for itself.
325
+ - **Build `url` from the record and the product's own routes. It must never be a text a customer wrote**, such as a
326
+ link from a message or a website from a contact's traits: a link under an answer is trusted for being the
327
+ product's own.
328
+ - A title is read by the rep, so translate it as the host translates its own screens. Cut a title built from a
329
+ customer's name to 200 characters, since a longer one is left out.
330
+ - The engine checks every source before it leaves the host. A title loses the characters that turn the direction
331
+ of text around (U+202A to U+202E, U+2066 to U+2069, U+200E, U+200F, U+061C) and its runs of white space first.
332
+ One that is not a hash, has no title (nothing but those characters is none), a title over 200 characters, a
333
+ `kind` other than `"conversation"` or `"record"` (a symbol of either is read as the text), an id that is neither
334
+ a text nor a whole number or is over 100 characters, or a `url` that is not an `http` or `https` address of at
335
+ most 2,000 characters without a username or a password is left out, and so is every one after the 25th. Only the first 100 a tool names are looked at, and the rest count as left out. Each call
336
+ that leaves one out is reported to Honeybadger once, with how many and why, never with a title or an address.
337
+ `sources` that raise, or that are not a list, mean none, and are reported too. The lookup's result goes either
338
+ way: a mistake here costs a person the link, never the answer.
339
+ - `sources` runs where `call` runs, as the rep, with writes to the database refused.
340
+ - An `id` goes to NeetoAssist as a text: `412` is `"412"`.
341
+ - A [product lookup](#the-assistant-and-product-lookups) names no sources: it is listed by itself.
255
342
 
256
343
  #### An action
257
344
 
@@ -405,7 +492,8 @@ end
405
492
 
406
493
  - With every question it sends NeetoAssist the definitions of the tools and actions that are `available?` for the
407
494
  rep, along with the rep's role and the `context`.
408
- - NeetoAssist takes at most 24 tools and 24 actions, with names that are unique across both. A class that breaks
495
+ - NeetoAssist takes at most 64 tools (the host's own and the [product lookups](#the-assistant-and-product-lookups)
496
+ together) and 24 actions, with names that are unique across all of them. A class that breaks
409
497
  one of NeetoAssist's limits, that cannot be described or that raises is left out and reported to Honeybadger, and
410
498
  the rep still gets an answer. What makes a tool or an action unusable:
411
499
  - a name that is not like `list_teammates` (a lower case letter, then letters, digits and underscores, at most
@@ -413,7 +501,7 @@ end
413
501
  - no description, or one over 1,000 characters;
414
502
  - a label that is not a text of at most 120 characters;
415
503
  - params over 4,000 bytes as JSON;
416
- - being the 25th tool or the 25th action;
504
+ - being the 65th tool or the 25th action;
417
505
  - for an action: a name over 56 characters, or a param called `reason`;
418
506
  - for an action that `writes`: a kind whose name is not like `github_issue`, no field or more than five, or a
419
507
  field that is not one of the action's own `:string` params;
@@ -443,6 +531,178 @@ no class, no adapter method and no setup.
443
531
  no answer in time, the rep is told that NeetoAssist cannot be reached, and the card says what became of the
444
532
  action once NeetoAssist knows.
445
533
 
534
+ ### The assistant and product lookups
535
+
536
+ A product can offer NeetoAssist anywhere in it as each person's own assistant: a thread that belongs to the person
537
+ who asks, with no conversation and no customer. And NeetoAssist can use the product's own read tools there, and on a
538
+ conversation: its MCP tools, which the product's teams keep. These are **product lookups**.
539
+
540
+ ```ruby
541
+ module NeetoAssist
542
+ class HostAdapter < NeetoAssistEngine::HostAdapter
543
+ def enabled?(organization)
544
+ organization.neeto_assist_enabled?
545
+ end
546
+
547
+ def assistant?(user)
548
+ user.active?
549
+ end
550
+
551
+ def product_lookups(_user, _conversation)
552
+ NeetoAssistEngine::ProductLookups.all
553
+ end
554
+
555
+ def assistant_context(user, page)
556
+ booking = find_booking_from_path(user, page["path"])
557
+ booking ? { booking: { id: booking.id, sid: booking.sid } } : {}
558
+ end
559
+
560
+ def assistant_suggestions(_user)
561
+ [I18n.t("neeto_assist.suggestions.bookings_last_week")]
562
+ end
563
+ end
564
+ end
565
+ ```
566
+
567
+ - `ProductLookups.all` offers every tool of the product's MCP registry (`Rails.application.config.mcp_tools`, which
568
+ neeto-commons-backend builds at boot) whose annotations say `readOnlyHint: true`, except the workspace chooser
569
+ `ListWorkspaces`. A read tool whose annotations say `openWorldHint: true` is not offered either: that is how a
570
+ product marks a tool with effects outside the workspace, such as an export that mails a file. MCP reads a missing
571
+ hint as true, and a tool built on neeto-commons-backend always says one or the other.
572
+ `ProductLookups.all(except: %w[GetX])` leaves tools out by name. `ProductLookups.none` offers none. The registry
573
+ is read on every question, so a read tool the product ships reaches NeetoAssist with its next deploy and no
574
+ change here.
575
+ - A tool is offered as the product wrote it: its name, its description (cut to 1,000 characters), a label from its
576
+ `invocation_messages(invoking:)`, else its title, and its arguments without the `workspace` argument and
577
+ `$schema`. A tool whose name NeetoAssist would not take (`/\A[A-Za-z][A-Za-z0-9_]{1,62}\z/`), with no
578
+ description, or with arguments over 4,000 bytes is left out and reported. The host's own tools come first, and a
579
+ product lookup with the name of one of them is left out.
580
+ - With them goes the product's own guidance for a model, `NeetoCommonsBackend::Mcp.config.instructions`, cut to
581
+ 8,000 characters, when at least one product lookup is offered.
582
+ - A product lookup is asked for and run through the `mcp` gem's own server, in-process, as the hosted MCP endpoint
583
+ runs it after sign-in: with the person, their workspace as the only granted one, and the `read` scope alone. No
584
+ HTTP and no token. A tool that needs more than the read scope says so and runs nothing.
585
+ - **It never runs without a person.** In a product's MCP tools a missing user means an admin, so the engine refuses
586
+ before anything is built when there is no user, the user is inactive or belongs to another workspace.
587
+ - Its result is the tool's structured content, or `{ "text": "..." }` for a tool that answers in words, and its
588
+ summary for the pane is "12 found" when the result has a `total_count`. Arguments the MCP layer refuses are
589
+ `422 invalid_arguments`, and a tool that runs and reports an error is `422 failed` with its text (500 characters
590
+ at most). Each run is logged with the tool's name, the person's id and the run id, never the arguments.
591
+ - Unlike a host's tool, a product lookup runs with writes to the database allowed, since some product tools store a
592
+ refreshed calendar token while they read. The read scope and the read-only list are the guard.
593
+ - A product lookup has a limit of the engine's own, `config.product_lookup_timeout`, 20 seconds by default. The
594
+ product's MCP layer gives a tool a minute, and NeetoAssist stops waiting long before that, so a lookup that runs
595
+ past the limit is stopped and is `422 failed`, with words that tell NeetoAssist to ask for less. Write protection
596
+ is back as it was either way.
597
+ - The registry is another team's code, so a mistake in it costs only the tool it is in. Each tool is listed through
598
+ a server of its own: one whose annotations or listing raise is left out and reported once, and of two tools with
599
+ one name the first is offered and the second reported. A registry that cannot be read at all is reported and
600
+ gives no product lookups; the host's own tools are offered all the same.
601
+ - The engine never requires the `mcp` gem. A host without it, or without a registry, simply has no product lookups.
602
+
603
+ The assistant's thread is named by a key (`/\A[a-z0-9]{8,40}\z/`). Its id at NeetoAssist is
604
+ `assistant-<the signed-in person's id>-<key>`, built from the session on every request and never from the browser,
605
+ so a person only ever reaches their own threads. A question in it carries the host's `assistant_tools` and the
606
+ product lookups (`product_lookups(user, nil)`), a grant for the thread,
607
+ `conversation: { kind: "assistant", owner_id:, messages: [] }`, and as its context `assistant_context(user, page)`
608
+ with the page under `"page"` unless the host put one there (the path cut to 500 characters, the title to 200).
609
+ Before the host's `assistant_context` or NeetoAssist sees the page, its path loses everything from the first `?`
610
+ or `#`: query strings and fragments can hold a client's name or email.
611
+ The assistant only looks things up: it offers no actions, the host's or NeetoAssist's own, so a question there says
612
+ `"actions": []` and offers no commands.
613
+
614
+ ### Shared lookups for a person asking in another product
615
+
616
+ A rep who asks NeetoAssist on a conversation in one Neeto product can have it look things up in another Neeto
617
+ product of the same workspace, as the same person there. "Has this customer booked with us this week?" asked in
618
+ NeetoChat is answered with NeetoCal's own read tools, run in NeetoCal as the rep's NeetoCal self. These are
619
+ **shared lookups**. Two engines take part: the one in the product the person asks in (the host) and the one in the
620
+ product whose data is read (the data product).
621
+
622
+ **In the host**, nothing needs to be written. The engine answers `POST /neeto_assist/api/v1/server/identity` for
623
+ NeetoAssist: for one of the host's own grants, checked as for any lookup, it says which workspace and which person
624
+ the grant stands for, by their NeetoAuth guids, and nothing else about them:
625
+
626
+ ```json
627
+ { "workspace": { "guid": "…", "subdomain": "acme" }, "person": { "guid": "…" }, "locale": "en" }
628
+ ```
629
+
630
+ Both guids are in lower case, and `locale` is the grant's. A workspace or a person without a `guid` (blank, or a
631
+ user model with no such method) is `422 { "error": "no_identity" }`, and that person gets no shared lookups. So who
632
+ is asking is always confirmed by the product that signed the grant, never taken from what the ask says.
633
+
634
+ **In the data product**, two things:
635
+
636
+ ```ruby
637
+ # config/initializers/neeto_assist.rb
638
+ config.pass_public_key = ENV["NEETO_ASSIST_PASS_PUBLIC_KEY"]
639
+
640
+ # The host adapter: what a person who asks elsewhere gets here. Give them what they would get in this
641
+ # product's own assistant, and nothing more.
642
+ def shared_lookups(user)
643
+ user.neeto_assist_user? ? NeetoAssistEngine::ProductLookups.all : NeetoAssistEngine::ProductLookups.none
644
+ end
645
+ ```
646
+
647
+ NeetoAssist then signs a pass for one person, one workspace, this product and one run, and calls two endpoints with
648
+ `Authorization: Bearer <product token>` and `X-Neeto-Assist-Pass: <pass>`:
649
+
650
+ | Endpoint | Body | Answer |
651
+ | --- | --- | --- |
652
+ | `POST /neeto_assist/api/v1/server/shared/catalog` | `{ "run_id": "..." }` | `200 { "product": "cal", "tools": [ ... ], "guidance": "..." }`. `tools` are the shared lookups' definitions, as a question carries product lookups. `guidance` is `null` when none is shared. |
653
+ | `POST /neeto_assist/api/v1/server/shared/tool_calls` | `{ "tool": "ListBookings", "arguments": { ... }, "run_id": "..." }` | As `server/tool_calls` answers a product lookup. |
654
+
655
+ A call is allowed only when all of these hold, and anything else is `403 { "error": "forbidden" }`, the same answer
656
+ for every check, so a caller learns nothing about which one failed. A missing or wrong token is `401`.
657
+
658
+ 1. The product token is this product's own, and the call names no `Origin`.
659
+ 2. `pass_public_key` is set and is an Ed25519 public key, and the pass's signature verifies with it.
660
+ 3. The pass says `"v": 1`, its `aud` is this product's `config.product`, and its `exp` is in the future and at most
661
+ 15 minutes away.
662
+ 4. The workspace with the pass's `workspace_guid` exists, carries that guid, is the one the call is addressed to by
663
+ its subdomain, is not disabled in the product, and the adapter's `enabled?` is true for it.
664
+ 5. `find_user_by_guid` finds a person who carries the pass's `person_guid`, belongs to that workspace and is active.
665
+ Nothing is built before that: in the product's MCP tools a missing person means an admin.
666
+ 6. For a tool call, `shared_lookups(user)` offers the tool. A tool that is not shared, a write, the product's own
667
+ `tools`, actions, a name the product does not have: all `403`, never `404`.
668
+
669
+ The catalog holds the product lookups `shared_lookups` gives, by every rule of product lookups above (read-only, no
670
+ `openWorldHint`, the person's own access, the read scope alone, `product_lookup_timeout`), and never the host's
671
+ own tools or actions. A lookup runs as that person, in the pass's language (one the product does not have means
672
+ its default one), with writes allowed as for any product lookup. Each run is logged with the tool's name, the
673
+ person's id, the product they asked in and the run, never the arguments.
674
+
675
+ The pass is two parts joined by a full stop, each base64url without padding (padded parts are read too): a JSON
676
+ object `{ "v": 1, "aud", "host", "workspace_guid", "person_guid", "run_id", "locale", "exp" }`, and the Ed25519
677
+ signature over the first part as it was sent. Verifying it never raises, whatever arrives. Guids are compared in
678
+ lower case.
679
+
680
+ Without `pass_public_key`, or with one that cannot be read, is not Ed25519 or holds a private key, the two shared
681
+ endpoints answer `403` and everything else works as before. A key that cannot be used is reported to Honeybadger
682
+ once, without its text, when it is first needed. The key may come straight from an environment variable: the two
683
+ characters `\n` are read as line breaks and white space around it does not count.
684
+
685
+ A test in the data product makes its own key pair and signs a pass as NeetoAssist does:
686
+
687
+ ```ruby
688
+ key = OpenSSL::PKey.generate_key("ED25519")
689
+ NeetoAssistEngine.configuration.pass_public_key = key.public_to_pem # put the old value back after the test
690
+
691
+ payload = {
692
+ v: 1, aud: "cal", workspace_guid: organization.guid, person_guid: user.guid, host: "chat",
693
+ run_id: "run-1", locale: "en", exp: 10.minutes.from_now.to_i
694
+ }
695
+ signed = Base64.urlsafe_encode64(payload.to_json, padding: false)
696
+ pass = "#{signed}.#{Base64.urlsafe_encode64(key.sign(nil, signed), padding: false)}"
697
+
698
+ post "/neeto_assist/api/v1/server/shared/tool_calls",
699
+ params: { tool: "ListBookings", arguments: {}, run_id: "run-1" }.to_json,
700
+ headers: {
701
+ "Content-Type" => "application/json", "Authorization" => "Bearer #{NeetoAssistEngine.configuration.api_token}",
702
+ "X-Neeto-Assist-Pass" => pass
703
+ }
704
+ ```
705
+
446
706
  ### The grant, and what a host trusts
447
707
 
448
708
  NeetoAssist's servers are not signed in to the host. What lets them look something up is a grant.
@@ -457,12 +717,17 @@ On every call from NeetoAssist's servers the engine checks, in this order:
457
717
 
458
718
  1. The product token is the host's own `config.api_token`, compared in constant time. Otherwise the answer is `401`.
459
719
  2. The grant verifies: signed by this host, for lookups, not expired.
460
- 3. Its workspace exists, and the call is addressed to that workspace's subdomain.
461
- 4. `enabled?` is true for the workspace.
720
+ 3. Its workspace exists, is not disabled in the product, and the call is addressed to that workspace's subdomain.
721
+ 4. The adapter's `enabled?` is true for the workspace.
462
722
  5. `find_user` finds the rep, and the rep has not been deactivated.
463
723
  6. `find_conversation` finds the conversation, by the id it found it by when the rep asked.
464
724
  7. `can_use?` is true for that rep on that conversation.
465
725
 
726
+ A grant for one of a person's assistant threads names `assistant-<the grant's person's id>-<key>` instead of a
727
+ conversation. For it, steps 6 and 7 are: the key is a key, and `assistant?` is true for the person. Its lookups are
728
+ the host's `assistant_tools` and the product lookups. It has no actions, so an action preview asked for with it is
729
+ `404 unknown_action`.
730
+
466
731
  Anything else is `403`. Nothing is taken from a session or a cookie. A rep who loses the conversation, or the
467
732
  workspace, loses the lookups at once, not when the grant expires.
468
733
 
@@ -482,10 +747,16 @@ What a host is trusting when it installs the engine:
482
747
  - **A grant is signed with the host's `secret_key_base`.** Rotating that ends every grant.
483
748
  - **A workspace's IP restriction does not stop NeetoAssist.** Its servers are on no workspace's list of allowed
484
749
  addresses, so when the host boots the engine adds a Rack::Attack safelist, named "NeetoAssist lookups", for a
485
- `POST` to one of the two server endpoints that carries the product token. Nothing else is safelisted, and a host
486
- without Rack::Attack gets none.
487
- - **The grant stays out of error reports.** When the host boots the engine adds `neeto_assist_grant` to the host's
488
- `filter_parameters`, which Honeybadger also applies to a request's headers.
750
+ `POST` to one of the server endpoints (`tool_calls`, `action_previews`, `identity`, `shared/catalog` and
751
+ `shared/tool_calls`) that carries the product token. Nothing else is safelisted, and a host without Rack::Attack
752
+ gets none.
753
+ - **The grant and the pass stay out of error reports.** When the host boots the engine adds `neeto_assist_grant`
754
+ and `neeto_assist_pass` to the host's `filter_parameters`, which Honeybadger also applies to a request's headers.
755
+ - **A lookup's arguments stay out of the host's request log.** They can hold what a customer wrote. On the
756
+ engine's server endpoints alone, each request filters the parameter `arguments` (that exact key) out of what
757
+ Rails logs and of anything else built from the request's filtered parameters, such as lograge or an error
758
+ report. The tool or the preview still gets them whole. The host's own `filter_parameters` is not changed, so a
759
+ parameter of that name on the host's other endpoints is logged as the host decides.
489
760
 
490
761
  The safelist and the filter entry are the only two things the engine changes in the host by itself. Neither needs
491
762
  any setup, and neither can be switched off.
@@ -514,16 +785,32 @@ The pane calls these for the signed-in rep, under the mount path:
514
785
 
515
786
  | Endpoint | Does |
516
787
  | --- | --- |
517
- | `GET /neeto_assist/api/v1/status` | `200 { "enabled": true }` or `{ "enabled": false }`, for any signed-in rep. |
788
+ | `GET /neeto_assist/api/v1/status` | `200 { "enabled": true, "assistant": true }`, for any signed-in rep. `assistant` says whether NeetoAssist is on and `assistant?` is true for this person. |
518
789
  | `GET /neeto_assist/api/v1/conversations/:conversation_id/runs` | NeetoAssist's runs for the conversation as the signed-in rep may see them, newest first: every reply suggestion, and the rep's own questions, each with the lookups it made (`steps`) and the actions it suggested (`actions`). Another rep's questions are not among them. With them come the workspace's credits and the commands the rep can pick in the box: `{ "runs": [...], "credits": { "exhausted", "remaining", "buy_url" }, "commands": [{ "name", "title", "description" }] }`. `buy_url` is `null` unless `can_buy_credits?` is true for the rep. |
519
790
  | `POST /neeto_assist/api/v1/conversations/:conversation_id/runs` | Asks NeetoAssist the rep's question: `{ "run": { "question": "..." } }`. The engine adds the rep's role, the tools and actions the rep may use, a grant and the `context`. |
520
791
  | `PUT /neeto_assist/api/v1/conversations/:conversation_id/runs/:run_id/feedback` | Rates a run: `{ "feedback": { "rating": "up", "note": "..." } }`. |
792
+ | `POST /neeto_assist/api/v1/conversations/:conversation_id/runs/:id/stop` | Stops the rep's own question while NeetoAssist is still on it. No body. Answers `{ "run": { ... } }`, the run as it now stands: `stopped`, or as it ended when its answer came first. |
521
793
  | `POST /neeto_assist/api/v1/conversations/:conversation_id/actions/:id/apply` | Runs a suggested action as the signed-in rep, or has NeetoAssist run one of its own for that rep. |
522
794
  | `POST /neeto_assist/api/v1/conversations/:conversation_id/actions/:id/dismiss` | Dismisses a suggested action. |
523
-
524
- - The conversation endpoints answer 404 unless `enabled?`, `find_conversation` and `can_use?` all pass.
525
- - Who asks, rates, applies or dismisses is always the signed-in rep (id, name, email), never anything in the
795
+ | `GET /neeto_assist/api/v1/assistant/thread` | `{ "thread": { "id": "<key>" }, "suggestions": [...] }`: the person's latest assistant thread, or a fresh key when they have none or NeetoAssist cannot be reached, with `assistant_suggestions`. |
796
+ | `POST /neeto_assist/api/v1/assistant/thread` | `201 { "thread": { "id": "<new key>" } }`, a new chat. Nothing is stored until its first question. |
797
+ | `GET /neeto_assist/api/v1/assistant/threads/:thread_id/runs` | The thread's runs, as on a conversation. |
798
+ | `POST /neeto_assist/api/v1/assistant/threads/:thread_id/runs` | Asks in the thread: `{ "run": { "question": "...", "request_id": "..." }, "page": { "path": "...", "title": "..." } }`. |
799
+ | `PUT /neeto_assist/api/v1/assistant/threads/:thread_id/runs/:run_id/feedback` | Rates a run, as on a conversation. |
800
+ | `POST /neeto_assist/api/v1/assistant/threads/:thread_id/runs/:id/stop` | Stops the person's own question in the thread, as on a conversation. |
801
+
802
+ - The conversation endpoints answer 404 unless `enabled?`, `find_conversation` and `can_use?` all pass. The
803
+ assistant endpoints answer 404 unless `enabled?` and `assistant?` pass, and for a thread key that is no key.
804
+ - Who asks, rates, applies, dismisses or stops is always the signed-in rep (id, name, email), never anything in the
526
805
  request.
806
+ - Every list of runs that NeetoAssist answered, on a conversation and in a thread, carries `"can_stop": true`, added
807
+ by the engine whatever NeetoAssist sent, so that a pane shows its stop button only with an engine that has these
808
+ two endpoints. A list that failed does not carry it.
809
+ - A stop says who wants the question stopped (`stopped_by`, the rep's id), and NeetoAssist stops only a question
810
+ that rep asked and that is still queued or running. The engine does not know who asked, and does not guess. A run
811
+ that is not the rep's own ask on this conversation is `404`. Any other answer of NeetoAssist's that is no success
812
+ is `503 unavailable`. A stopped run has the status `stopped`, keeps its
813
+ question and the steps made so far, and has no answer.
527
814
  - An answer to a question is built from lookups made with the asker's access, so only the rep who asked is shown
528
815
  it. The engine tells NeetoAssist who is looking with every list (`requested_by_id`, the signed-in rep's id as
529
816
  it was sent when they asked), and NeetoAssist leaves out the questions of everyone else.
@@ -573,9 +860,17 @@ NeetoAssist's own servers call the next two, with `Authorization: Bearer <produc
573
860
 
574
861
  | Endpoint | Body | Answer |
575
862
  | --- | --- | --- |
576
- | `POST /neeto_assist/api/v1/server/tool_calls` | `{ "tool": "list_teammates", "arguments": { ... }, "run_id": "..." }` | `200 { "result": ..., "summary": "3 people" }`. `summary` is `null` when the tool has none. |
863
+ | `POST /neeto_assist/api/v1/server/tool_calls` | `{ "tool": "list_teammates", "arguments": { ... }, "run_id": "..." }` | `200 { "result": ..., "summary": "3 people", "sources": [{ "kind": "conversation", "id": "412", "title": "...", "url": "https://..." }] }`. `summary` is `null` when the tool has none, and `sources` is `[]` ([its rules](#a-tool-that-names-its-sources)). A source has no `kind`, `id` or `url` key when the tool gave none. For a product lookup `result` is the tool's structured content, or `{ "text": "..." }`, and `sources` is `[]`. |
577
864
  | `POST /neeto_assist/api/v1/server/action_previews` | `{ "name": "assign_conversation", "arguments": { ... }, "run_id": "..." }` | `200 { "preview": { "title": "Assign to Priya Sharma", "details": ["Team: Billing"] } }`. The preview has a `content` too when the action's `Preview` has one. |
578
865
 
866
+ NeetoAssist also asks `POST /neeto_assist/api/v1/server/identity` with the same two headers and `{ "run_id": "..." }`
867
+ ([above](#shared-lookups-for-a-person-asking-in-another-product)), and, in a product that shares its lookups,
868
+ the two `shared/` endpoints with a pass in place of the grant.
869
+
870
+ Every server endpoint refuses a disabled workspace with `403 { "error": "forbidden" }`, on both the grant and
871
+ pass paths, even when its NeetoAssist flag is still on. Hosts whose workspace model has no `enabled` state are
872
+ unaffected.
873
+
579
874
  Both only read, and neither looks at a session or a cookie. Their errors are
580
875
  `{ "error": "<code>", "message": "<a sentence, for some>" }`:
581
876
 
@@ -658,7 +953,7 @@ const TicketHeader = ({
658
953
  such as "Sam Smith's conversation". The pane shows "Looking at Sam Smith's conversation" under its header, as plain
659
954
  text, so the rep knows what NeetoAssist's answers are about. Leave it out to show no such line.
660
955
  - The pane shows what NeetoAssist did on the ticket, oldest first: what the customer wrote with the suggested
661
- reply, "Use reply", "Copy" and the help articles it came from; the rep's own questions as a chat, each with what
956
+ reply, "Use reply", "Copy" and the sources it came from; the rep's own questions as a chat, each with what
662
957
  NeetoAssist looked up to answer it, its answer and a card for every action it suggests; the reason it skipped or
663
958
  found no answer; thumbs up or down with an optional note; then a box to ask more. Another rep's questions and
664
959
  their answers are not shown. A ticket with none of these starts with a short introduction and a few suggested
@@ -675,6 +970,27 @@ const TicketHeader = ({
675
970
  without commands gets no menu and no such line, and the box is the plain one it always was.
676
971
  - A question that NeetoAssist read as a command shows as it was typed, with the command a little heavier than the
677
972
  words after it.
973
+ - When the list of runs says `can_stop` (this engine always does), and while the rep's own latest question is
974
+ queued or running, the send button is a stop button, as in Neeti. One
975
+ click stops the question (the `stop` [endpoints](#endpoints)); the button shows it is working until the list says the
976
+ question has ended, and a second click meanwhile sends nothing. A stop that failed shows the pane's usual error
977
+ under the box and leaves the button to try again. The box stays open, and the keyboard stays in it, but Enter
978
+ sends nothing until the question has ended. A reply suggestion that is being written has no stop button and
979
+ holds nothing up. A stopped question shows what was asked, what was looked up folded into one line, and the
980
+ muted line "Stopped before NeetoAssist answered.", which a screen reader reads out. It has no thumbs. A list
981
+ without `can_stop`, from an older engine, leaves the box as it always was: the send button stays, a second
982
+ question can be sent while the first runs, and there is no stop button.
983
+ - Under an answer, "Sources" lists what it rests on, one to a line: what kind of thing it is in a muted word ("Help
984
+ article", "API docs", nothing for a conversation, whose title says it is one, or another record, the product's
985
+ name for a lookup), then its title. A title with an `http` or `https` address opens it in a new tab; any other
986
+ address, and one with a name or password before an `@`, is never a link, and a
987
+ source without one, such as a lookup, is plain text. A source with no `kind`, as an older NeetoAssist sends,
988
+ is a help article, and one with neither a title nor a web address is left out. Everything in the list is shown as
989
+ text.
990
+ - Beside the thumbs of the rep's own answered question, "Copy answer" copies the answer as plain text: the words
991
+ without the light markdown around them, a list with its numbers or dashes, a table as the lines it was written
992
+ in, and a block of code as its lines. The button turns into a check for a moment, only when the copy went
993
+ through; where the browser refuses, the shared copy helper tries its own way and says in a toast how it went.
678
994
  - What NeetoAssist looked up shows as a quiet list while it works: each lookup's label with a spinner, a check or a
679
995
  cross, and a few words on what it found. Once the answer is there the list folds into one line, such as "Looked at 3
680
996
  things", that opens to the same list.
@@ -709,10 +1025,103 @@ const TicketHeader = ({
709
1025
  `**bold**`, `1.` numbered and `-` bulleted lists, `##` headings). `html` is the same reply for a rich-text
710
1026
  composer: escaped text inside only `p`, `br`, `strong`, `ol`, `ul`, `li` and `h2`, with no attributes, so no
711
1027
  markup from the conversation survives as HTML. A name the model set off in backticks, such as a file name,
712
- arrives in `html` as plain words. Leave `onUseReply` out to show only "Copy".
1028
+ arrives in `html` as plain words. A fenced block of code arrives as its lines: in `text` with only the lines of
1029
+ three backticks around it left out, in `html` as a paragraph of its escaped lines. Leave `onUseReply` out to show
1030
+ only "Copy".
1031
+ - A workspace whose team reads English can have NeetoAssist send a reply in English and in the language the
1032
+ customer is sent it in. That is switched on in NeetoAssist, per workspace, and the engine hands a run to the pane
1033
+ as it came, so a host does nothing for it. Such a run carries up to five more fields. `suggestedReplyInEnglish`
1034
+ and `suggestedReplyInCustomerLanguage` are the reply both ways, and `suggestedReplyLanguage` is the BCP 47 tag of
1035
+ the language the second one is in, such as `es` or `pt-BR`, never English. The three are there together or not at
1036
+ all. The reply as written is what the customer is sent, unless it is English: a reply written in another language
1037
+ is `suggestedReplyInCustomerLanguage`, word for word, and `suggestedReplyInEnglish` is its translation, while a
1038
+ reply written in English is `suggestedReplyInEnglish`, and `suggestedReplyInCustomerLanguage` is its translation
1039
+ into the customer's language. No reply is translated twice. `customerLanguage` is the tag of the language the
1040
+ customer writes in, when NeetoAssist could tell and it is not English. It can be missing beside a reply's
1041
+ readings, when the customer wrote too little to tell by, and it can be another language than the reply's, when a
1042
+ rep asked for the reply in one of their choosing. `questionInEnglish` is what the customer wrote, in English, on
1043
+ a reply suggestion only. `suggestedReply` and `question` stay what they always were. A run without the fields
1044
+ looks and works as it always did.
1045
+ - The card of a reply that has `suggestedReplyLanguage` and both readings shows the English one. Under it, a muted
1046
+ line says "The customer writes in Spanish." when `customerLanguage` names the same language as the reply's (the
1047
+ first parts of the two tags match, so `pt-PT` beside `pt-BR` does), and "This reply is in French." when it names
1048
+ another or is missing. The link beside it, "Show in Spanish", turns the card to the reading the customer is sent
1049
+ and then reads "Show in English". The buttons are "Use in Spanish", which is the main one and keeps the test id
1050
+ of "Use reply" (`neeto-assist-use-reply-button`), "Use in English" and "Copy". The link and the buttons name the
1051
+ reply's language. `onUseReply(text, html)` gets the reading the rep picked, made into `text` and `html` as above,
1052
+ whichever reading is showing, and "Copy" copies the one that is showing. Without `onUseReply` there is "Copy"
1053
+ alone, and the link still turns the card. With one reading alone, or without `suggestedReplyLanguage`, the card
1054
+ is the one it always was.
1055
+ - "Customer wrote" shows the customer's words in English when a reply suggestion has `questionInEnglish`, with
1056
+ "Translated from Spanish." under them and the link "Show original". The link turns them to the customer's own
1057
+ words, and the line then says "Original in Spanish." and the link "Show in English". The language is
1058
+ `customerLanguage` alone, whatever the reply is in, and without it the lines are "Translated." and "Original.".
1059
+ Both readings are plain text. A rep's own question is never translated.
1060
+ - A language's name comes from the browser (`Intl.DisplayNames`), in the language the pane is in, and English is
1061
+ named the same way. Where the browser has no name for a tag, or throws at it, the sentences have a form without
1062
+ a name ("The customer writes in another language.", "This reply is in another language.", "Use in their
1063
+ language", "Show in their language", "Translated.", "Original."), and a tag is never shown to the rep.
1064
+ - The block that shows a reading has `lang` (the tag, or `en`), so a screen reader picks the right voice, and reads
1065
+ the other reading out when the rep turns it. Its direction comes from the language and its letters, not from
1066
+ the reading's first letter: `dir="rtl"` when the language is Arabic, Hebrew, Persian, Urdu, Pashto, Sindhi,
1067
+ Uyghur, Yiddish, Dhivehi or Sorani (`ar`, `he`, `fa`, `ur`, `ps`, `sd`, `ug`, `yi`, `dv` and `ckb`, by the first
1068
+ part of the tag) and the reading holds a letter of a right-to-left script, `dir="ltr"` for the English reading,
1069
+ and `dir="auto"` for any other. So an Arabic reply that opens with the name of a product still reads right to
1070
+ left, and Urdu written in Latin letters is left to the text. The link is a button that keeps the keyboard
1071
+ through a turn. Each card and each "Customer wrote" remembers its turn only while it is on screen: nothing is
1072
+ stored.
713
1073
  - The pane shows replies and notes with the same formatting, built as React elements around plain text. It
714
1074
  shows a name in backticks as code, and a numbered list that carries on after bullets counts on from where it
715
- stopped.
1075
+ stopped. A fenced block (three backticks on a line, with or without a language word after them, and three
1076
+ backticks to close it) shows as a block of code in a monospace font, its lines exactly as written and nothing in
1077
+ them read as markdown or coloured. A long line scrolls sideways inside the block, and a block that scrolls takes
1078
+ the keyboard. A fence that nothing closes shows as the text it was.
1079
+ - A markdown pipe table in an answer shows as a table, in a conversation and in the assistant alike. A wide table
1080
+ scrolls sideways in its own box, so the pane never does, and the box takes the keyboard so the arrow keys scroll
1081
+ it too. A table needs its header row and the line of dashes under it with as many cells; the pipes at the ends are
1082
+ optional, a short row gets empty cells, cells past the header's count are dropped, and a pipe inside backticks or
1083
+ escaped as `\|` stays in its cell. Anything short of that, or a table of more than 12 columns or 200 rows, shows
1084
+ as the text it was. Cells are formatted like any other text. What `onUseReply`'s `html` gets is unchanged by
1085
+ tables: the same as before the pane drew them, so a composer without tables loses nothing.
1086
+
1087
+ ### The assistant
1088
+
1089
+ A product can also give its people NeetoAssist as their own assistant, anywhere in the product: no conversation and
1090
+ no customer, a thread that belongs to the person who asks, and the product's own read tools as lookups (see the
1091
+ host adapter's `assistant?`, `product_lookups` and `assistant_suggestions`). It opens in the same `NeetoAssistPane`,
1092
+ so a product that already mounts the pane adds only its own way in:
1093
+
1094
+ ```jsx
1095
+ import { useNeetoAssistAssistant } from "@bigbinary/neeto-assist-frontend";
1096
+
1097
+ const AssistantMenuItem = () => {
1098
+ const { isAvailable, isOpen, toggle } = useNeetoAssistAssistant();
1099
+
1100
+ if (!isAvailable) return null;
1101
+
1102
+ return <MenuItem active={isOpen} label="NeetoAssist" onClick={toggle} />;
1103
+ };
1104
+ ```
1105
+
1106
+ - `useNeetoAssistAssistant()` returns `{ isAvailable, isOpen, open, close, toggle }`. `isAvailable` is the status
1107
+ endpoint's `assistant`: NeetoAssist is on and the host adapter's `assistant?` holds for this person. It is false
1108
+ while the status loads and after it failed. `isOpen` is true while the pane shows the assistant.
1109
+ - The pane shows whichever was opened last. Opening the assistant takes the pane from a ticket's conversation, and a
1110
+ click on that ticket's `NeetoAssistButton` brings the conversation back. `close` only closes the assistant. A
1111
+ product that never calls the hook gets exactly the conversation pane, and no request about the assistant is made.
1112
+ - The first time the assistant opens on a page, it asks the engine for the person's latest thread and the first
1113
+ questions the host offers. The header has New chat, expand and close. New chat starts an empty thread, and is off
1114
+ while NeetoAssist is still working on a question: stopping the question is the way to it sooner. An empty thread shows a few words on what the assistant is for
1115
+ and the host's questions as buttons that ask on a click; with none there is no list. After New chat and after a
1116
+ question is picked, the keyboard goes to the box.
1117
+ - The thread then reads like a conversation: each question, what NeetoAssist looked up while it worked, its answer
1118
+ with sources, and thumbs. There is no suggested reply, a card only when a run has one, and a command menu only when
1119
+ the engine lists commands. When credits are used up, the box and Stop stay while the person's ask is pending;
1120
+ the credits banner takes the box's place after it ends, as on a conversation. A failed request shows the pane's
1121
+ usual error in the pane, never a blank pane and never a toast.
1122
+ - Every question carries the page it was asked on: `location.pathname` and `document.title`, without a query
1123
+ string or fragment. The engine strips both again before the host adapter's `assistant_context` reads the page
1124
+ to say what the person is looking at, and before it goes to NeetoAssist.
716
1125
 
717
1126
  ## Development
718
1127
 
@@ -95,7 +95,13 @@
95
95
  "errors": {
96
96
  "forbidden": "ليس لديك إذن للقيام بذلك. اطلب من مسؤول.",
97
97
  "unavailable": "لا يمكن الوصول إلى NeetoAssist الآن. حاول مرة أخرى بعد قليل."
98
- }
98
+ },
99
+ "showAll": "عرض الكل",
100
+ "showLess": "عرض أقل"
101
+ },
102
+ "commands": {
103
+ "hint": "اكتب / للأوامر",
104
+ "label": "الأوامر"
99
105
  }
100
106
  }
101
107
  }
@@ -95,7 +95,13 @@
95
95
  "errors": {
96
96
  "forbidden": "Нямате разрешение да направите това. Попитайте администратор.",
97
97
  "unavailable": "NeetoAssist не може да бъде достигнат в момента. Опитайте отново след малко."
98
- }
98
+ },
99
+ "showAll": "Показване на всички",
100
+ "showLess": "Показване на по-малко"
101
+ },
102
+ "commands": {
103
+ "hint": "Напишете / за команди",
104
+ "label": "Команди"
99
105
  }
100
106
  }
101
107
  }