@bigbinary/neeto-assist-frontend 1.0.2 → 1.1.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.
package/README.md CHANGED
@@ -1,12 +1,15 @@
1
1
  # neeto-assist-nano
2
2
 
3
3
  NeetoAssist for Neeto products: the `neeto-assist-engine` Rails engine and the `@bigbinary/neeto-assist-frontend`
4
- package. A host product, NeetoChat first, installs both to show its support reps what NeetoAssist would reply to a
5
- visitor, let them ask NeetoAssist about a conversation, and rate its answers. NeetoAssist never writes into the
6
- conversation and never talks to the visitor: a rep decides what to send.
4
+ package. A host product, NeetoChat first, installs both to give its support reps NeetoAssist beside a conversation.
5
+ It shows what NeetoAssist would reply to a visitor, answers a rep's questions about the conversation, looks things up
6
+ in the host as that rep while it answers, and suggests actions such as assigning the conversation, which run only
7
+ when a rep clicks. NeetoAssist never writes into the conversation by itself and never talks to the visitor: a rep
8
+ decides what to send and what to do.
7
9
 
8
10
  The engine calls NeetoAssist's product API (`https://{subdomain}.neetoassist.com`) for the workspace the rep works
9
- in, and passes NeetoAssist's answers through to the pane.
11
+ in and passes NeetoAssist's answers through to the pane. It also answers NeetoAssist's own servers when they look
12
+ something up in the host for a rep.
10
13
 
11
14
  ## Contents
12
15
 
@@ -15,6 +18,8 @@ in, and passes NeetoAssist's answers through to the pane.
15
18
  - [Configuration](#configuration)
16
19
  - [Host adapter](#host-adapter)
17
20
  - [Asking for a reply suggestion](#asking-for-a-reply-suggestion)
21
+ - [Lookups and actions](#lookups-and-actions)
22
+ - [The grant, and what a host trusts](#the-grant-and-what-a-host-trusts)
18
23
  - [Endpoints](#endpoints)
19
24
  2. [Frontend package](#frontend-package)
20
25
  - [Installation](#installation-1)
@@ -48,7 +53,9 @@ in, and passes NeetoAssist's answers through to the pane.
48
53
  mount NeetoAssistEngine::Engine, at: "/neeto_assist"
49
54
  ```
50
55
 
51
- The engine has no tables, so there are no migrations to copy.
56
+ The engine has no tables, so there are no migrations to copy. When the host boots, the engine adds two things to
57
+ it by itself: one Rack::Attack safelist and one entry in `filter_parameters`. Both are explained
58
+ [below](#the-grant-and-what-a-host-trusts).
52
59
 
53
60
  ### Configuration
54
61
 
@@ -61,21 +68,27 @@ NeetoAssistEngine.configure do |config|
61
68
  # NeetoAssist's address. %{subdomain} becomes the workspace's subdomain.
62
69
  # Development: "http://%{subdomain}.lvh.me:9050".
63
70
  config.api_base_url = Rails.application.vault.neeto_assist_api_base_url
64
- # The token NeetoAssist issued to this product.
71
+ # The token NeetoAssist issued to this product. NeetoAssist's own servers
72
+ # send the same token when they look something up in the host.
65
73
  config.api_token = Rails.application.vault.neeto_assist_api_token
66
74
  # The host's adapter, by class name so it is loaded on use.
67
75
  config.host_adapter = "NeetoAssist::HostAdapter"
68
76
  # Optional, in seconds. These are the defaults.
69
77
  config.open_timeout = 2
70
78
  config.read_timeout = 10
79
+ # Optional. How long NeetoAssist may look things up as the rep who asked.
80
+ # 15 minutes is the default and the most: a host can only shorten it.
81
+ config.grant_ttl = 15.minutes
71
82
  end
72
83
  ```
73
84
 
74
85
  Until `product`, `api_base_url`, `api_token` and `host_adapter` are all set, the engine stays off: the job does
75
- nothing, the status endpoint answers `{ "enabled": false }` and the conversation endpoints answer 404.
86
+ nothing, the status endpoint answers `{ "enabled": false }`, the conversation endpoints answer 404 and the server
87
+ endpoints answer 401.
76
88
 
77
89
  After a call times out or cannot connect, the engine's calls fail at once for 30 seconds, so a NeetoAssist that stops
78
- answering cannot tie up the host's threads. The cool off is kept in `Rails.cache`.
90
+ answering cannot tie up the host's threads. The cool off is kept in `Rails.cache`. One call is sent all the same:
91
+ the report on how an action a rep applied ended, which NeetoAssist has to hear.
79
92
 
80
93
  ### Host adapter
81
94
 
@@ -90,6 +103,11 @@ subclass of `NeetoAssistEngine::HostAdapter`:
90
103
  | `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. |
91
104
  | `conversation_payload(conversation)` | The conversation as NeetoAssist takes it (below), built when it is sent. |
92
105
  | `conversation_external_id(conversation)` | The conversation's id in NeetoAssist. Defaults to `conversation.id.to_s`. |
106
+ | `context(user, conversation)` | What the rep is looking at beyond the messages, in the host's own words: the conversation's status, who has it, its tags, who the customer is. A hash that turns into JSON, at most 16,000 bytes. Defaults to `{}`. NeetoAssist reads it as data with every question. |
107
+ | `tools(user, conversation)` | The `NeetoAssistEngine::Tool` classes NeetoAssist may look things up with for this rep ([below](#lookups-and-actions)). Defaults to `[]`. |
108
+ | `actions(user, conversation)` | The `NeetoAssistEngine::Action` classes NeetoAssist may suggest to this rep. Defaults to `[]`. |
109
+ | `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. |
110
+ | `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. |
93
111
 
94
112
  ```ruby
95
113
  module NeetoAssist
@@ -110,6 +128,25 @@ module NeetoAssist
110
128
  def conversation_payload(conversation)
111
129
  ConversationPayloadService.new(conversation).process
112
130
  end
131
+
132
+ def context(user, conversation)
133
+ {
134
+ conversation: { status: conversation.status, tags: conversation.tags.pluck(:name) },
135
+ customer: { name: conversation.visitor_name }
136
+ }
137
+ end
138
+
139
+ def tools(_user, _conversation)
140
+ [Tools::ListCustomerConversations, Tools::ListTeammates]
141
+ end
142
+
143
+ def actions(_user, _conversation)
144
+ [Actions::AssignConversation]
145
+ end
146
+
147
+ def user_role(user)
148
+ user.organization_role&.name
149
+ end
113
150
  end
114
151
  end
115
152
  ```
@@ -119,6 +156,9 @@ end
119
156
  each with `id`, `author` (`visitor`, `agent` or `bot`), `author_name`, `body` (plain text, at most 4,000 characters)
120
157
  and `created_at`. Leave private notes out.
121
158
 
159
+ If `context`, `tools`, `actions` or `user_role` raises, the rep's question still goes to NeetoAssist, without that
160
+ part, and the error goes to Honeybadger.
161
+
122
162
  ### Asking for a reply suggestion
123
163
 
124
164
  Enqueue the job after every visitor message, for example from the message's `after_create_commit`:
@@ -135,6 +175,220 @@ NeetoAssist for a `reply_suggestion`. When NeetoAssist is down, too slow or answ
135
175
  (a 4xx, such as `409 disabled` once the workspace switched NeetoAssist off) is only logged, since a retry would get
136
176
  the same answer.
137
177
 
178
+ ### Lookups and actions
179
+
180
+ With every question, the engine tells NeetoAssist what it may look up and what it may suggest for this rep on this
181
+ conversation. A host writes both as small classes:
182
+
183
+ - A **tool** looks something up in the host, such as the customer's earlier conversations. NeetoAssist calls it while
184
+ it answers, and it runs as the rep who asked.
185
+ - An **action** changes something in the host, such as assigning the conversation. NeetoAssist never runs one. It
186
+ suggests it, the pane shows a card that says what will happen, and the action runs when a rep clicks "Apply", as
187
+ the rep who clicked.
188
+
189
+ #### A tool
190
+
191
+ ```ruby
192
+ module NeetoAssist
193
+ module Tools
194
+ class ListTeammates < NeetoAssistEngine::Tool
195
+ description "Lists the people on the support team with their ids, at most 50. Use it to find who to assign to."
196
+ label "Looking up the team"
197
+ param :query, :string, required: false, description: "Part of a name."
198
+
199
+ def available?
200
+ TeamPolicy.new(user, organization).index?
201
+ end
202
+
203
+ def call(query: nil)
204
+ organization.users.search(query).limit(50).map { |teammate| { id: teammate.id, name: teammate.name } }
205
+ end
206
+
207
+ def summary(result)
208
+ "#{result.size} people"
209
+ end
210
+ end
211
+ end
212
+ end
213
+ ```
214
+
215
+ - `description` is for the model: what the tool is for, when to use it and what comes back. At most 1,000
216
+ characters.
217
+ - `label` is what the pane shows while the tool runs, at most 120 characters. Give it a block to translate it:
218
+ `label { I18n.t("neeto_assist.tools.list_teammates") }`.
219
+ - `param name, type, required: true, description:, enum:, minimum:, maximum:, max_length:, items:, max_items:`
220
+ declares an argument. The types are `:string`, `:integer`, `:number`, `:boolean` and `:array` (of `items:`, one of
221
+ the other types). For an `:array`, `enum:`, `minimum:`, `maximum:` and `max_length:` are limits on each item, and
222
+ the model is told them that way. A string is at most 2,000 characters unless `max_length:` says otherwise, and
223
+ a list takes at most 50 items, or fewer with `max_items:`. The model is told every limit, so it does not send
224
+ what would be refused. The engine checks what the model sent against the params, then gives them to `call` as
225
+ keywords.
226
+ - `tool_name "find_teammate"` sets the name NeetoAssist calls the tool by. It defaults to the class name:
227
+ `ListTeammates` is `list_teammates`.
228
+ - `call` returns something that turns into JSON, at most 60,000 bytes. Put ids and names in it, so NeetoAssist can
229
+ use them in an action. Raise `Failed` with a sentence when it cannot be done, and `InvalidArguments` with a
230
+ sentence when the arguments name something that is not there. NeetoAssist reads both and may try again. An
231
+ `ActiveRecord::RecordNotFound` reaches it as "That record was not found.". Any other error tells NeetoAssist
232
+ nothing and goes to Honeybadger.
233
+ - `summary(result)` is a few words about the result for the pane, such as "3 people". The rep reads them, so
234
+ translate them as the host translates its own screens ([below](#the-language-of-a-lookup-and-a-card)).
235
+ - `available?` says whether this rep may use the tool on this conversation. NeetoAssist is never told about a tool
236
+ that is not available, and cannot call it.
237
+
238
+ A tool has `organization`, `user` (the rep who asked) and `conversation`. Three rules:
239
+
240
+ 1. **Show the rep only what the host's own screens would show them.** The model chooses the arguments, so treat
241
+ every id as hostile. Scope every query to `organization`, then to what `user` may open, with the same policy or
242
+ finder the host's screens use.
243
+ 2. **Only read.** The engine runs a lookup with writes to the database refused, so a tool that tries to change
244
+ something raises `ActiveRecord::ReadOnlyError`. A change is an action.
245
+ 3. **Be quick.** NeetoAssist waits 8 seconds for a lookup.
246
+
247
+ #### An action
248
+
249
+ ```ruby
250
+ module NeetoAssist
251
+ module Actions
252
+ class AssignConversation < NeetoAssistEngine::Action
253
+ description "Assigns this conversation to a teammate."
254
+ label "Assign conversation"
255
+ param :user_id, :string, description: "The teammate's id, from list_teammates."
256
+
257
+ def available?
258
+ ConversationPolicy.new(user, conversation).update?
259
+ end
260
+
261
+ def preview(user_id:)
262
+ Preview.new(title: "Assign to #{teammate(user_id).name}", details: ["Team: #{teammate(user_id).team_name}"])
263
+ end
264
+
265
+ def call(user_id:)
266
+ Conversations::AssignmentService.new(conversation, teammate(user_id), assigned_by: user).process
267
+ "Assigned to #{teammate(user_id).name}"
268
+ end
269
+
270
+ private
271
+
272
+ def teammate(user_id)
273
+ organization.users.find_by(id: user_id) ||
274
+ raise(InvalidArguments, "There is no teammate with that id. Use list_teammates to find one.")
275
+ end
276
+ end
277
+ end
278
+ end
279
+ ```
280
+
281
+ An action is declared like a tool, with two limits of its own. Its name is at most 56 characters, since
282
+ NeetoAssist offers it to the model as `suggest_<name>` and a model takes a name of 64. And it has no param called
283
+ `reason`: NeetoAssist adds one to every suggestion, for the model's sentence on why. An action adds two methods:
284
+
285
+ - `preview` returns the card's words: a `Preview` with a `title` for what will happen and `details` for anything
286
+ worth a line of its own. Build them from the records the arguments name, so a rep reads exactly what will run and
287
+ never the model's account of it. Raise `InvalidArguments` when it cannot be done, in words NeetoAssist can act
288
+ on. It only reads. The engine calls it when NeetoAssist suggests the action and again right before the action
289
+ runs, since things change between a suggestion and a click. The action runs only if `preview` then still
290
+ returns the title and the details the card was made from (rule 4).
291
+ - `call` makes the change as `user`, the rep who clicked, and returns a sentence that says what was done. Raise
292
+ `Failed` with a sentence when it could not be done.
293
+
294
+ Four rules here too:
295
+
296
+ 1. **An action must check what the host's own screen checks.** `available?` answers as the screen's own filter for
297
+ the same change would, and `call` goes through the same service the screen uses, as that rep. The engine asks
298
+ `available?` before it offers the action and again when a rep clicks, since what a rep may do can change
299
+ between a suggestion and a click.
300
+ 2. **Nothing an action does may reach the customer.** NeetoAssist must not put anything in front of a customer, so
301
+ leave out whatever sends a message or an email, or changes what the customer sees.
302
+ 3. **Refuse in `preview` what `call` would refuse.** A rep should not get a card for something that cannot be done.
303
+ 4. **Keep what changes by itself out of a card's words.** A card runs only if `preview` still returns the title and
304
+ the details it returned when the card was made. If either reads differently at the click, nothing runs and the
305
+ card says so, since the rep agreed to the words on the card and not to what the same arguments mean by now. So
306
+ name in them what will change and for whom ("Unassign Priya Sharma", not "Unassign"), and leave out the time of
307
+ day, a running count, or anything else that differs from one call to the next. `preview` runs once for
308
+ NeetoAssist's servers and once in the rep's own request, and has to give the same words both times, so do not
309
+ lean on what only a signed-in request sets, such as the rep's time zone, and list things in a fixed order.
310
+
311
+ #### What the engine does with them
312
+
313
+ - With every question it sends NeetoAssist the definitions of the tools and actions that are `available?` for the
314
+ rep, along with the rep's role and the `context`.
315
+ - NeetoAssist takes at most 24 tools and 24 actions, with names that are unique across both. A class that breaks
316
+ one of NeetoAssist's limits, that cannot be described or that raises is left out and reported to Honeybadger, and
317
+ the rep still gets an answer. What makes a tool or an action unusable:
318
+ - a name that is not like `list_teammates` (a lower case letter, then letters, digits and underscores, at most
319
+ 63 characters in all), or one another tool or action already has;
320
+ - no description, or one over 1,000 characters;
321
+ - a label that is not a text of at most 120 characters;
322
+ - params over 4,000 bytes as JSON;
323
+ - being the 25th tool or the 25th action;
324
+ - for an action: a name over 56 characters, or a param called `reason`.
325
+ - An `Action` listed among `tools` is left out: nothing that changes the host is ever run as a lookup.
326
+ - When NeetoAssist calls a tool or a rep clicks a card, the engine finds the class by name among the same list, for
327
+ the rep it is acting for, and asks `available?` again.
328
+
329
+ ### The grant, and what a host trusts
330
+
331
+ NeetoAssist's servers are not signed in to the host. What lets them look something up is a grant.
332
+
333
+ When a rep asks a question, the engine issues a grant and sends it along: a message signed with
334
+ `Rails.application.message_verifier("neeto_assist_engine/grant")` for the purpose `:lookups`. It names the
335
+ workspace, the rep, the conversation and the language of the rep's screen, nothing else, and stops working after
336
+ `config.grant_ttl`, which is 15 minutes at most. NeetoAssist sends it back with every lookup, next to the product
337
+ token. A rep with neither a tool nor an action gets no grant.
338
+
339
+ On every call from NeetoAssist's servers the engine checks, in this order:
340
+
341
+ 1. The product token is the host's own `config.api_token`, compared in constant time. Otherwise the answer is `401`.
342
+ 2. The grant verifies: signed by this host, for lookups, not expired.
343
+ 3. Its workspace exists, and the call is addressed to that workspace's subdomain.
344
+ 4. `enabled?` is true for the workspace.
345
+ 5. `find_user` finds the rep, and the rep has not been deactivated.
346
+ 6. `find_conversation` finds the conversation, by the id it found it by when the rep asked.
347
+ 7. `can_use?` is true for that rep on that conversation.
348
+
349
+ Anything else is `403`. Nothing is taken from a session or a cookie. A rep who loses the conversation, or the
350
+ workspace, loses the lookups at once, not when the grant expires.
351
+
352
+ What a host is trusting when it installs the engine:
353
+
354
+ - **NeetoAssist can read through the host's tools as a rep, and nothing more.** It needs the product token and a
355
+ grant. With both it can call the tools the host wrote, for 15 minutes after a rep asked, as that rep, on the
356
+ conversation that rep asked about. What it can read is what those tools return, so a tool is as careful as its
357
+ queries.
358
+ - **NeetoAssist cannot change anything.** The two server endpoints only read, with writes to the database refused.
359
+ An action runs only from a rep's click, in the host's own session, after `available?` said that rep may.
360
+ - **The product token is the secret to guard.** Whoever holds it and a grant can read as that rep. A grant alone
361
+ opens nothing, and neither does the token alone. NeetoAssist keeps a grant encrypted and erases it when it has
362
+ answered.
363
+ - **A grant is signed with the host's `secret_key_base`.** Rotating that ends every grant.
364
+ - **A workspace's IP restriction does not stop NeetoAssist.** Its servers are on no workspace's list of allowed
365
+ addresses, so when the host boots the engine adds a Rack::Attack safelist, named "NeetoAssist lookups", for a
366
+ `POST` to one of the two server endpoints that carries the product token. Nothing else is safelisted, and a host
367
+ without Rack::Attack gets none.
368
+ - **The grant stays out of error reports.** When the host boots the engine adds `neeto_assist_grant` to the host's
369
+ `filter_parameters`, which Honeybadger also applies to a request's headers.
370
+
371
+ The safelist and the filter entry are the only two things the engine changes in the host by itself. Neither needs
372
+ any setup, and neither can be switched off.
373
+
374
+ The grant names the conversation by the id the host found it by when the rep asked, the one in the pane's
375
+ address, and the engine finds it again with `find_conversation`. A host whose conversations have another id in
376
+ NeetoAssist (`conversation_external_id`) needs nothing extra.
377
+
378
+ #### The language of a lookup and a card
379
+
380
+ A lookup's `summary` and a card's `title` and `details` are read by the rep, and NeetoAssist's servers have no
381
+ screen and no language of their own. So the grant carries the language the host had set for the rep's request when
382
+ they asked (`I18n.locale`), and the engine runs a call from NeetoAssist's servers inside `I18n.with_locale` with
383
+ it. A language that is not among the host's `I18n.available_locales` means the host's default one. In `summary`
384
+ and `preview`, use `I18n.t` as on any of the host's screens. A `label` is read when the rep asks, in the rep's own
385
+ request, so a `label` block is translated too.
386
+
387
+ A click on a card is the rep's own request, so `preview` then runs in the language the host has set for that
388
+ request. For a rep who has not changed their language since they asked, that is the card's language, and the words
389
+ match. A rep who has changed it reads a card in the old language: its words no longer match, so it does not run
390
+ and tells them to ask again.
391
+
138
392
  ### Endpoints
139
393
 
140
394
  The pane calls these for the signed-in rep, under the mount path:
@@ -142,12 +396,18 @@ The pane calls these for the signed-in rep, under the mount path:
142
396
  | Endpoint | Does |
143
397
  | --- | --- |
144
398
  | `GET /neeto_assist/api/v1/status` | `200 { "enabled": true }` or `{ "enabled": false }`, for any signed-in rep. |
145
- | `GET /neeto_assist/api/v1/conversations/:conversation_id/runs` | NeetoAssist's runs for the conversation, newest first, and the workspace's credits: `{ "runs": [...], "credits": { "exhausted", "remaining", "buy_url" } }`. `buy_url` is `null` unless `can_buy_credits?` is true for the rep. |
146
- | `POST /neeto_assist/api/v1/conversations/:conversation_id/runs` | Asks NeetoAssist the rep's question: `{ "run": { "question": "..." } }`. |
399
+ | `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: `{ "runs": [...], "credits": { "exhausted", "remaining", "buy_url" } }`. `buy_url` is `null` unless `can_buy_credits?` is true for the rep. |
400
+ | `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`. |
147
401
  | `PUT /neeto_assist/api/v1/conversations/:conversation_id/runs/:run_id/feedback` | Rates a run: `{ "feedback": { "rating": "up", "note": "..." } }`. |
402
+ | `POST /neeto_assist/api/v1/conversations/:conversation_id/actions/:id/apply` | Runs a suggested action as the signed-in rep. |
403
+ | `POST /neeto_assist/api/v1/conversations/:conversation_id/actions/:id/dismiss` | Dismisses a suggested action. |
148
404
 
149
405
  - The conversation endpoints answer 404 unless `enabled?`, `find_conversation` and `can_use?` all pass.
150
- - Who asks or rates is always the signed-in rep (id, name, email), never anything in the request.
406
+ - Who asks, rates, applies or dismisses is always the signed-in rep (id, name, email), never anything in the
407
+ request.
408
+ - An answer to a question is built from lookups made with the asker's access, so only the rep who asked is shown
409
+ it. The engine tells NeetoAssist who is looking with every list (`requested_by_id`, the signed-in rep's id as
410
+ it was sent when they asked), and NeetoAssist leaves out the questions of everyone else.
151
411
  - A blank question, one over 2,000 characters, or a rating other than `up` or `down` is
152
412
  `422 { "error": "invalid", "details": { ... } }`, without calling NeetoAssist.
153
413
  - NeetoAssist being down, slow, answering with a 5xx, or refusing the product token is
@@ -155,6 +415,48 @@ The pane calls these for the signed-in rep, under the mount path:
155
415
  host.
156
416
  - Any other answer from NeetoAssist passes through with its status and body, such as `404 not_found`,
157
417
  `409 disabled` or `422 invalid`.
418
+ - A suggested action's `arguments` never reach the browser. The card shows the host's own `title` and `details`.
419
+
420
+ Applying an action takes these steps:
421
+
422
+ 1. The engine claims the action at NeetoAssist, so two clicks cannot both run it. A refusal passes through, such as
423
+ `409 not_suggested` for an action that was applied or dismissed already, or `409 expired`.
424
+ 2. It finds the action among `actions(current_user, conversation)` and asks `available?`. A rep who may not do it
425
+ gets `403 { "error": "forbidden" }`, and the action goes back to being a suggestion, since nothing ran.
426
+ 3. It calls `preview` again and compares the title and the details with the card's. When they are no longer the
427
+ same, nothing runs and the action fails with "This has changed since it was suggested, so nothing was done. Ask
428
+ NeetoAssist again." A card with no details matches a preview with none. Otherwise it calls `call`.
429
+ 4. The answer is `200 { "action": { ... } }` with the action as applied. When the action refused or broke, it is
430
+ `422 { "error": "failed", "message": "...", "action": { ... } }`. The message is the action's own sentence, or
431
+ "Something went wrong." for an error nobody expected, which goes to Honeybadger.
432
+ 5. NeetoAssist is told how it ended. If that report does not get through, the rep is still told what happened in
433
+ the host, and `NeetoAssistEngine::ReportActionJob` sends the same report again from the `within_5_seconds`
434
+ queue, with five retries over seven to nine and a half minutes. It carries ids, the host's sentence and who
435
+ clicked, never the action's arguments. Until NeetoAssist hears, it shows the action as being applied. If it
436
+ never does, it marks the action after ten minutes as one nobody could confirm. Every report names the claim it
437
+ is for (`claim`, as NeetoAssist answered the claim), so a report that arrives after the rep clicked once more
438
+ is not taken for the new click's.
439
+
440
+ NeetoAssist's own servers call the next two, with `Authorization: Bearer <product token>` and
441
+ `X-Neeto-Assist-Grant: <grant>`:
442
+
443
+ | Endpoint | Body | Answer |
444
+ | --- | --- | --- |
445
+ | `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. |
446
+ | `POST /neeto_assist/api/v1/server/action_previews` | `{ "name": "assign_conversation", "arguments": { ... }, "run_id": "..." }` | `200 { "preview": { "title": "Assign to Priya Sharma", "details": ["Team: Billing"] } }` |
447
+
448
+ Both only read, and neither looks at a session or a cookie. Their errors are
449
+ `{ "error": "<code>", "message": "<a sentence, for some>" }`:
450
+
451
+ | Status | Code | When |
452
+ | --- | --- | --- |
453
+ | 400 | `bad_request` | The body is not JSON. The token and the grant are checked first, so only a call that carries both is told. |
454
+ | 401 | `unauthorized` | The product token is missing or wrong, or the engine is not configured. |
455
+ | 403 | `forbidden` | The grant is missing, forged, expired or for another workspace, or the rep may no longer use NeetoAssist on the conversation. Also a call that names an `Origin`, as a browser does. |
456
+ | 404 | `unknown_tool`, `unknown_action` | The rep has no tool or action by that name. |
457
+ | 422 | `invalid_arguments` | The arguments do not fit, or name something that does not exist. The message says what. |
458
+ | 422 | `failed` | The tool or the preview raised `Failed`: the message is its sentence. Also a result over 60,000 bytes. |
459
+ | 500 | `error` | Anything else. No message, and the error goes to Honeybadger. |
158
460
 
159
461
  ## Frontend package
160
462
 
@@ -190,7 +492,12 @@ const Layout = ({ children }) => (
190
492
  </div>
191
493
  );
192
494
 
193
- const TicketHeader = ({ conversationId, insertIntoComposer }) => {
495
+ const TicketHeader = ({
496
+ conversationId,
497
+ customerName,
498
+ insertIntoComposer,
499
+ refetchConversation,
500
+ }) => {
194
501
  const { data: neetoAssistStatus } = useNeetoAssistStatus();
195
502
 
196
503
  if (!neetoAssistStatus?.enabled) return null;
@@ -198,6 +505,8 @@ const TicketHeader = ({ conversationId, insertIntoComposer }) => {
198
505
  return (
199
506
  <NeetoAssistButton
200
507
  {...{ conversationId }}
508
+ contextLabel={`${customerName}'s conversation`}
509
+ onActionApplied={() => refetchConversation()}
201
510
  onUseReply={(text, html) => insertIntoComposer({ text, html })}
202
511
  />
203
512
  );
@@ -211,20 +520,47 @@ const TicketHeader = ({ conversationId, insertIntoComposer }) => {
211
520
  remembered), and a close button. While open it sets `data-neeto-assist-open` on the document's root element, to
212
521
  `default` or `expanded`, for a host that needs CSS to make room. It follows the ticket: moving to another ticket moves it along, and leaving the
213
522
  tickets tucks it away until the rep comes back to one.
214
- - `NeetoAssistButton` takes `conversationId`, the host's own conversation id, and `onUseReply`. It opens and closes
215
- the pane, tells the pane which ticket it is about for as long as the button is on screen, and shows a dot when a
216
- suggested reply is waiting.
217
- - The pane shows everything NeetoAssist did on the ticket, oldest first: what the customer wrote with the suggested
218
- reply, "Use reply", "Copy" and the help articles it came from; the rep's own questions as a chat; the reason it
219
- skipped or found no answer; thumbs up or down with an optional note; then a box to ask more. A ticket with none of
220
- these starts with a short introduction and a few suggested questions. It polls every 3 seconds while a run is pending
221
- and every 30 seconds otherwise, and shows its errors inside the pane, never as a toast or an error page.
523
+ - `NeetoAssistButton` takes `conversationId`, the host's own conversation id, and three optional props:
524
+ `contextLabel`, `onActionApplied` and `onUseReply`. It opens and closes the pane, tells the pane which ticket it is
525
+ about for as long as the button is on screen, and shows a dot when a suggested reply is waiting.
526
+ - `contextLabel` is a short phrase, in the host's own words and the rep's language, for what the rep is looking at,
527
+ such as "Sam Smith's conversation". The pane shows "Looking at Sam Smith's conversation" under its header, as plain
528
+ text, so the rep knows what NeetoAssist's answers are about. Leave it out to show no such line.
529
+ - The pane shows what NeetoAssist did on the ticket, oldest first: what the customer wrote with the suggested
530
+ reply, "Use reply", "Copy" and the help articles it came from; the rep's own questions as a chat, each with what
531
+ NeetoAssist looked up to answer it, its answer and a card for every action it suggests; the reason it skipped or
532
+ found no answer; thumbs up or down with an optional note; then a box to ask more. Another rep's questions and
533
+ their answers are not shown. A ticket with none of these starts with a short introduction and a few suggested
534
+ questions. It polls every 2 seconds while NeetoAssist is working on a run and every 30 seconds otherwise, and
535
+ shows its errors inside the pane, never as a toast or an error page. A card that is being applied does not speed
536
+ the polling up: the rep who clicked reads what became of it from the answer to the click.
537
+ - What NeetoAssist looked up shows as a quiet list while it works: each lookup's label with a spinner, a check or a
538
+ 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
539
+ things", that opens to the same list.
540
+ - A card is one action NeetoAssist suggests, such as assigning the conversation. It says what will happen in the
541
+ host's own words (the `title` and `details` the action's `describe` returns), then the model's one-line reason in
542
+ muted text, then "Apply" and "Dismiss". Nothing happens until a rep clicks "Apply". The engine then runs the action
543
+ as that rep, through the host's own code and permission checks, and the card shows the host's sentence on what was
544
+ done and who applied it. A card that failed says why and has no retry: the rep can ask again. A dismissed or expired
545
+ card steps back to a muted line, and a dismissed one says who dismissed it. A card never shows the action's
546
+ arguments or an id, and everything on it is shown as text, never as HTML.
547
+ - `onActionApplied(action)` is called once after "Apply" worked. The change was made on the server by the host's own
548
+ code, so the page still shows what was there before: fetch the conversation again (with React Query, invalidate its
549
+ queries), or whatever `action.name` says was changed, so the rep sees it without a reload. `action` is the applied
550
+ action with `id`, `name`, `title`, `details`, `reason`, `status`, `result`, `actedBy`, `actedAt` and `expiresAt`,
551
+ and never its arguments. It is not called for an action that failed or was dismissed. It is called even when the
552
+ rep has opened another conversation before the answer to the click arrived. The handler called is then the one
553
+ the host last gave for the conversation the action was applied on, so let a handler refresh the conversation it
554
+ was given for, which need not be the one on screen any more.
222
555
  - `onUseReply(text, html)` is called when the rep clicks "Use reply". Put the reply in the composer and send
223
556
  nothing. `text` is the reply as NeetoAssist wrote it, in light markdown (paragraphs split by blank lines,
224
557
  `**bold**`, `1.` numbered and `-` bulleted lists, `##` headings). `html` is the same reply for a rich-text
225
558
  composer: escaped text inside only `p`, `br`, `strong`, `ol`, `ul`, `li` and `h2`, with no attributes, so no
226
- markup from the conversation survives as HTML. Leave `onUseReply` out to show only "Copy".
227
- - The pane shows replies and notes with the same formatting, built as React elements around plain text.
559
+ markup from the conversation survives as HTML. A name the model set off in backticks, such as a file name,
560
+ arrives in `html` as plain words. Leave `onUseReply` out to show only "Copy".
561
+ - The pane shows replies and notes with the same formatting, built as React elements around plain text. It
562
+ shows a name in backticks as code, and a numbered list that carries on after bullets counts on from where it
563
+ stopped.
228
564
 
229
565
  ## Development
230
566
 
@@ -2,21 +2,23 @@
2
2
  "neetoAssist": {
3
3
  "title": "NeetoAssist",
4
4
  "beta": "BETA",
5
- "betaNote": "NeetoAssist drafts replies from your help articles for your reps. It runs next to your current setup and never writes to a customer.",
5
+ "betaNote": "NeetoAssist drafts replies, looks things up and suggests actions for your reps. It never writes to a customer, and nothing changes until a rep clicks.",
6
6
  "askButton": "Ask NeetoAssist",
7
7
  "draftReady": "A suggested reply is ready",
8
8
  "expand": "Expand",
9
9
  "collapse": "Collapse",
10
10
  "close": "Close NeetoAssist",
11
11
  "shadowNote": "Customers never see this chat.",
12
+ "lookingAt": "Looking at {{label, anyCase}}",
12
13
  "intro": {
13
14
  "title": "Hi, I'm NeetoAssist.",
14
- "description": "When the customer writes, I draft a reply from your help articles. Ask me anything about this conversation, or try one of these."
15
+ "description": "When the customer writes, I draft a reply from your help articles. Ask me anything about this conversation, or tell me what you need done. Nothing changes until you click Apply."
15
16
  },
16
17
  "suggestions": {
17
18
  "summarize": "Summarize this conversation",
18
19
  "whatToReply": "What should I reply?",
19
- "whatToCheck": "What should I check first?"
20
+ "writtenBefore": "Has this customer written before?",
21
+ "whatNext": "What should I do next?"
20
22
  },
21
23
  "run": {
22
24
  "repAsked": "{{name, anyCase}} asked",
@@ -32,6 +34,26 @@
32
34
  "sources": "From your help articles",
33
35
  "needsFollowUp": "This reply tells the customer the team will act on their request, so someone needs to follow up."
34
36
  },
37
+ "steps": {
38
+ "lookedAt_one": "Looked at {{count}} thing",
39
+ "lookedAt_other": "Looked at {{count}} things",
40
+ "completed": "Done",
41
+ "failed": "Failed"
42
+ },
43
+ "actions": {
44
+ "apply": "Apply",
45
+ "dismiss": "Dismiss",
46
+ "applying": "Applying...",
47
+ "applied": "Applied",
48
+ "by": "by {{name, anyCase}}",
49
+ "failed": "This could not be done.",
50
+ "dismissed": "Dismissed",
51
+ "expired": "Expired",
52
+ "errors": {
53
+ "forbidden": "You don't have permission to do this. Ask an admin.",
54
+ "unavailable": "NeetoAssist cannot be reached right now. Try again shortly."
55
+ }
56
+ },
35
57
  "skippedReasons": {
36
58
  "greeting": "Skipped: the customer only said hello.",
37
59
  "acknowledgment": "Skipped: the customer only acknowledged or said thanks, so there was nothing to answer.",
@@ -61,7 +83,7 @@
61
83
  "ratedNotHelpful": "{{name, anyCase}} found this not helpful"
62
84
  },
63
85
  "ask": {
64
- "placeholder": "Ask about this conversation...",
86
+ "placeholder": "Ask anything, or say what you need done",
65
87
  "submit": "Send to NeetoAssist"
66
88
  },
67
89
  "errors": {
package/dist/.ready CHANGED
@@ -1 +1 @@
1
- Built at 2026-11-06T05:09:03.544Z
1
+ Built at 2026-11-11T16:00:06.311Z
@@ -2,12 +2,12 @@ import _defineProperty from '@babel/runtime/helpers/defineProperty';
2
2
  import { useRef, useEffect } from 'react';
3
3
  import { Button } from '@bigbinary/neeto-atoms';
4
4
  import { useTranslation } from 'react-i18next';
5
- import { u as useNeetoAssistStore, a as useFetchRuns, l as latestDraftId, S as Sparkle } from './useNeetoAssistStore-B5U7FFgQ.js';
5
+ import { u as useNeetoAssistStore, a as useFetchRuns, l as latestDraftId, S as Sparkle } from './useNeetoAssistStore--JwP_Upt.js';
6
6
  import { jsxs, jsx } from 'react/jsx-runtime';
7
7
  import '@babel/runtime/helpers/objectWithoutProperties';
8
8
  import '@tanstack/react-query';
9
9
  import '@bigbinary/neeto-commons-frontend/v2/react-utils';
10
- import './neeto_assist-Ha049T0Q.js';
10
+ import './neeto_assist-CpUBA-3Z.js';
11
11
  import 'axios';
12
12
  import 'ramda';
13
13
  import '@bigbinary/neeto-commons-frontend/v2/utils';
@@ -22,10 +22,13 @@ var NeetoAssistIcon = function NeetoAssistIcon(props) {
22
22
  };
23
23
 
24
24
  // Goes on the ticket: it opens the pane, and tells the pane which ticket it is
25
- // about for as long as the button is on screen. A dot says a suggested reply is
26
- // waiting, since the pane is closed until the rep asks for it.
25
+ // about for as long as the button is on screen, along with the host's words
26
+ // for what the rep is looking at. A dot says a suggested reply is waiting,
27
+ // since the pane is closed until the rep asks for it.
27
28
  var NeetoAssistButton = function NeetoAssistButton(_ref) {
28
29
  var conversationId = _ref.conversationId,
30
+ contextLabel = _ref.contextLabel,
31
+ onActionApplied = _ref.onActionApplied,
29
32
  onUseReply = _ref.onUseReply;
30
33
  var _useTranslation = useTranslation(),
31
34
  t = _useTranslation.t;
@@ -52,25 +55,40 @@ var NeetoAssistButton = function NeetoAssistButton(_ref) {
52
55
  var draftId = latestDraftId(runs);
53
56
  var hasUnseenDraft = !isOpen && !!draftId && draftId !== seenDraftId;
54
57
 
55
- // The host's handler changes on every render, and only whether there is one
56
- // matters to the pane.
58
+ // The host's handlers change on every render. Only whether there is one for
59
+ // "Use reply" matters to the pane, and one for an applied action changes
60
+ // nothing it shows, so the pane gets stand-ins that call the latest.
57
61
  var useReplyRef = useRef(onUseReply);
62
+ var actionAppliedRef = useRef(onActionApplied);
58
63
  var canUseReply = !!onUseReply;
59
64
  useEffect(function () {
60
65
  useReplyRef.current = onUseReply;
66
+ actionAppliedRef.current = onActionApplied;
61
67
  });
62
68
  useEffect(function () {
69
+ // The answer to a click on Apply can arrive after the button has moved on
70
+ // to another ticket. It then goes to the handler the host last gave for
71
+ // this ticket, not to the one for the ticket now on screen.
72
+ var handlerOnLeaving;
73
+ var hasLeft = false;
63
74
  setConversation({
64
75
  id: conversationId,
76
+ contextLabel: contextLabel,
65
77
  onUseReply: canUseReply ? function (text, html) {
66
78
  var _useReplyRef$current;
67
79
  return (_useReplyRef$current = useReplyRef.current) === null || _useReplyRef$current === void 0 ? void 0 : _useReplyRef$current.call(useReplyRef, text, html);
68
- } : undefined
80
+ } : undefined,
81
+ onActionApplied: function onActionApplied(action) {
82
+ var _ref2;
83
+ return (_ref2 = hasLeft ? handlerOnLeaving : actionAppliedRef.current) === null || _ref2 === void 0 ? void 0 : _ref2(action);
84
+ }
69
85
  });
70
86
  return function () {
71
- return clearConversation(conversationId);
87
+ handlerOnLeaving = actionAppliedRef.current;
88
+ hasLeft = true;
89
+ clearConversation(conversationId);
72
90
  };
73
- }, [canUseReply, clearConversation, conversationId, setConversation]);
91
+ }, [canUseReply, clearConversation, contextLabel, conversationId, setConversation]);
74
92
  return /*#__PURE__*/jsxs("span", {
75
93
  className: "relative inline-flex",
76
94
  children: [/*#__PURE__*/jsx(Button, {