@bevel-software/platform-core-frontend 0.13.6 → 0.14.0

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.
@@ -1,12 +1,16 @@
1
- import { useState } from 'react';
1
+ import { useRef, useState } from 'react';
2
2
  import { Link, useNavigate } from 'react-router-dom';
3
3
  import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
4
4
  import { Banner, Button, buttonClasses } from '../../../../shared/components';
5
5
  import { useWorkspace } from '../../../workspace/state/workspace.context';
6
6
  import { kbFileUrl } from '../../../workspace/routing/kb-routes';
7
- import type { ToolSecrets } from '../../../secrets-vault/services/tool-secrets.api';
7
+ import {
8
+ checkToolConnection,
9
+ type ProbeVerdict,
10
+ type ToolSecrets,
11
+ } from '../../../secrets-vault/services/tool-secrets.api';
8
12
  import { pathForTool } from '../../routes/library-paths';
9
- import { toolVariableStatuses } from '../../utils/status';
13
+ import { toolStatus, toolVariableStatuses } from '../../utils/status';
10
14
  import { ToolVarRow } from './ToolVarRow';
11
15
 
12
16
  /**
@@ -24,16 +28,76 @@ import { ToolVarRow } from './ToolVarRow';
24
28
 
25
29
  export interface ToolConnectionSectionProps {
26
30
  tool: ToolSecrets;
31
+ /**
32
+ * Bumped whenever the tool's DEFINITION changes — today, an mcp.json server
33
+ * edit. A verdict describes the endpoint and headers it was probed against,
34
+ * so changing those makes it a statement about a server that is no longer
35
+ * configured; the badge must stop claiming it. Deliberately NOT bumped by a
36
+ * credential write: that path clears and re-probes on its own, and bumping
37
+ * here would discard the answer it is in the middle of fetching.
38
+ */
39
+ configRevision: number;
27
40
  /** A write landed — the caller refetches so the chips catch up. */
28
41
  onChanged(): void;
29
42
  onError(message: string): void;
30
43
  }
31
44
 
32
- export function ToolConnectionSection({ tool, onChanged, onError }: ToolConnectionSectionProps) {
45
+ export function ToolConnectionSection({
46
+ tool,
47
+ configRevision,
48
+ onChanged,
49
+ onError,
50
+ }: ToolConnectionSectionProps) {
33
51
  const navigate = useNavigate();
34
52
  const { kbDirName } = useWorkspace();
35
53
  /** `{varName, n}` — bumping `n` opens that variable's editor from the banner. */
36
54
  const [edit, setEdit] = useState<{ name: string; n: number }>({ name: '', n: 0 });
55
+ /**
56
+ * The revision of the probe in flight, or null. `checking` is DERIVED: an
57
+ * in-flight probe owns the Test button only while the definition it dials
58
+ * is still the one on screen, so a config edit mid-probe re-enables the
59
+ * button for the new definition immediately instead of waiting for the
60
+ * orphan to settle.
61
+ */
62
+ const [inFlight, setInFlight] = useState<{ rev: number } | null>(null);
63
+ const checking = inFlight !== null && inFlight.rev === configRevision;
64
+
65
+ /**
66
+ * A probe's TRANSPORT failure (network, access — not a verdict about the
67
+ * credential), held here rather than raised to the page's shared error
68
+ * banner. Page-level state outlived its subject twice over: another
69
+ * action's error could be cleared by a probe that happened to recover,
70
+ * and a probe of the PREVIOUS tool (this section is keyed by slug) could
71
+ * clear or raise it after unmount. Section state dies with the section,
72
+ * and the revision stamp makes it self-invalidating, exactly like the
73
+ * verdict: shown only while it describes the configuration on screen.
74
+ */
75
+ const [probeError, setProbeError] = useState<{ rev: number; message: string } | null>(null);
76
+ const shownProbeError = probeError && probeError.rev === configRevision ? probeError.message : null;
77
+ /**
78
+ * The last probe's answer, and the ONLY place one exists.
79
+ *
80
+ * Nothing persists a verdict, so this state IS the evidence behind the word
81
+ * "Connected" — which is why the claim can be trusted: it cannot outlive the
82
+ * page that watched the call succeed.
83
+ *
84
+ * Stored WITH the config revision it was probed under, and read back only
85
+ * when that still matches. Comparing rather than clearing keeps it pure: an
86
+ * effect that cleared on change would race the probe it is meant to protect,
87
+ * since a credential save starts a probe and a refetch at the same moment.
88
+ */
89
+ const [probed, setProbed] = useState<{ rev: number; value: ProbeVerdict } | null>(null);
90
+ const verdict = probed && probed.rev === configRevision ? probed.value : null;
91
+
92
+ /**
93
+ * Which probe is allowed to publish. Two saves in quick succession start two
94
+ * probes, and the first can answer last — so a result is applied only while
95
+ * it is still the newest one asked for. Without it the older credential's
96
+ * verdict wins by finishing late, which is the same stale-answer bug this
97
+ * whole feature exists to remove, one layer up.
98
+ */
99
+ const probeSeq = useRef(0);
100
+
37
101
 
38
102
  const setupKind = tool.setup?.kind ?? null;
39
103
  // Not just "kind is oauth-manual": once the owner declares the provider and
@@ -92,15 +156,145 @@ export function ToolConnectionSection({ tool, onChanged, onError }: ToolConnecti
92
156
  </Button>
93
157
  ) : null;
94
158
 
159
+ /**
160
+ * The health line, shown only once every variable is provided.
161
+ *
162
+ * While something is still missing, the amber banner above already names it,
163
+ * and a second line saying the connection is untested would be answering a
164
+ * question nobody has reached yet. Once nothing is missing, this is the only
165
+ * remaining question — and the one the badge used to answer by guessing.
166
+ */
167
+ const health = toolStatus(tool, verdict);
168
+ // Every variable genuinely provided — NOT merely `missing.length === 0`, which
169
+ // excludes a pending sign-in on a configured provider. A tool nobody has
170
+ // signed into yet has no credential to test, and saying so would put a health
171
+ // line above a row that already says "Needs your sign-in".
172
+ // Vacuously true for a tool that declares no variables: a no-auth MCP server
173
+ // has nothing to set up and is still worth probing — its handshake is exactly
174
+ // the kind of thing that can be reachable one day and not the next.
175
+ //
176
+ // But `!setupUnfinished` first: an `oauth-manual` server whose sign-in nobody
177
+ // has declared YET also has no variables, and `every([])` would call that
178
+ // settled — offering Test connection and the words "No key needed" directly
179
+ // above a banner telling the owner to go configure OAuth.
180
+ const settled =
181
+ !setupUnfinished && toolVariableStatuses(tool).every(({ status }) => status.state === 'ok');
182
+
183
+ /**
184
+ * Run a probe and keep its answer.
185
+ *
186
+ * `checking` lives here, beside the button it disables, so it is still true
187
+ * while the request is in flight — the reason a save no longer blanks the
188
+ * page (see `useToolPage`): a remount would drop both this flag and the
189
+ * verdict, leaving an enabled "Test connection" over a probe already running.
190
+ */
191
+ async function runCheck() {
192
+ const mine = ++probeSeq.current;
193
+ const rev = configRevision;
194
+ setInFlight({ rev });
195
+ // A replacement probe makes the previous transport failure history the
196
+ // moment it starts — leaving the alert up while "Testing…" runs reads as
197
+ // the new attempt already having failed.
198
+ setProbeError(null);
199
+ try {
200
+ const value = await checkToolConnection(tool.slug);
201
+ // Newest-probe guard only: everything published is REVISION-STAMPED
202
+ // and compared at render, so a probe that raced a definition change
203
+ // stores state that simply never shows — no clock to synchronise, no
204
+ // ref to read mid-render.
205
+ if (probeSeq.current === mine) {
206
+ setProbed({ rev, value });
207
+ setProbeError(null);
208
+ }
209
+ } catch (err) {
210
+ // A rejected credential resolves with `status: 'failed'`; only a
211
+ // transport or access failure lands here, and that is not a verdict about
212
+ // the credential — so the badge keeps saying "untested" rather than
213
+ // inventing a result from our own network trouble.
214
+ // Inside the guard too: an older probe rejecting after a newer one has
215
+ // already answered would otherwise raise a transport error over a verdict
216
+ // that is currently correct.
217
+ if (probeSeq.current === mine) {
218
+ setProbed(null);
219
+ setProbeError({ rev, message: err instanceof Error ? err.message : "Couldn't test this connection." });
220
+ }
221
+ } finally {
222
+ // Only the newest probe releases the slot: an older one finishing late
223
+ // must not clear a newer probe's in-flight marker.
224
+ if (probeSeq.current === mine) setInFlight(null);
225
+ }
226
+ }
227
+
228
+ /**
229
+ * A credential write LANDED (save or delete, from the banner's editor or a
230
+ * row). Everything a pending probe could still say is about a credential
231
+ * that no longer exists in that form, so the write ORPHANS it outright —
232
+ * the sequence bump takes its voice (a delete starts no replacement probe,
233
+ * so nothing else would), the in-flight slot is released, and the old
234
+ * transport alert goes with them.
235
+ */
236
+ function changed() {
237
+ probeSeq.current++;
238
+ setInFlight(null);
239
+ setProbeError(null);
240
+ // The VERDICT too: after a delete, “Connected” would otherwise keep
241
+ // describing a credential that no longer exists while the refetch is
242
+ // still in flight.
243
+ setProbed(null);
244
+ onChanged();
245
+ }
246
+
247
+ /**
248
+ * A credential was just SAVED: whatever the last probe concluded was about
249
+ * the key it replaced, so drop it and test the new one straight away —
250
+ * while the user still has it to hand, which is when a wrong key is
251
+ * cheapest to fix. (The row calls `changed` too, which orphans the old
252
+ * probe; the fresh `runCheck` claims the sequence for the new key.)
253
+ */
254
+ function onSaved() {
255
+ setProbed(null);
256
+ void runCheck();
257
+ }
258
+
95
259
  return (
96
260
  <section className="mt-8">
97
261
  <div className="mb-2.5 flex items-center justify-between gap-3">
98
262
  <h2 className="text-label font-semibold uppercase text-ink-faint">Your connection</h2>
99
- <Link to="/secrets" className={buttonClasses({ variant: 'quiet', size: 'tiny' })}>
100
- Open Secrets
101
- </Link>
263
+ <div className="flex items-center gap-2">
264
+ {/* A healthy connection stays QUIET — this section's rule is that only
265
+ things needing a person get a banner, and a working tool needs
266
+ nobody. But it still has to be sayable: the word plus its evidence
267
+ on hover is how "Connected" stops being an assumption, and the
268
+ button is the only way to ask the question on demand. A REJECTED
269
+ credential does need a person, so it escalates to a banner below. */}
270
+ {settled && health.state !== 'err' && (
271
+ <span className="text-meta text-ink-faint" title={health.hint} data-testid="tool-health">
272
+ {health.text}
273
+ </span>
274
+ )}
275
+ {settled && (
276
+ <Button
277
+ variant="quiet"
278
+ size="tiny"
279
+ disabled={checking}
280
+ onClick={() => void runCheck()}
281
+ aria-label={`Test connection: ${tool.name}`}
282
+ >
283
+ {checking ? 'Testing…' : 'Test connection'}
284
+ </Button>
285
+ )}
286
+ <Link to="/secrets" className={buttonClasses({ variant: 'quiet', size: 'tiny' })}>
287
+ Open Secrets
288
+ </Link>
289
+ </div>
102
290
  </div>
103
291
 
292
+ {shownProbeError && (
293
+ <Banner tone="danger" role="alert" className="mb-2.5" data-testid="tool-probe-error">
294
+ {shownProbeError}
295
+ </Banner>
296
+ )}
297
+
104
298
  {setupUnfinished && (
105
299
  <Banner tone="wait" role="status" className="mb-2.5">
106
300
  {tool.canWrite && signInDeclared ? (
@@ -167,6 +361,22 @@ export function ToolConnectionSection({ tool, onChanged, onError }: ToolConnecti
167
361
  </Banner>
168
362
  )}
169
363
 
364
+ {/* The one health state that needs a person: the provider tested this
365
+ credential and refused it. Everything is configured, so no other
366
+ banner covers it, and the row below cannot know — only a real call
367
+ could tell us. `alert`, not `status`: this is the case the whole
368
+ feature exists to surface. */}
369
+ {settled && health.state === 'err' && (
370
+ <Banner tone="danger" role="alert" className="mb-2.5" data-testid="tool-health-failed">
371
+ <div className="flex items-center gap-3">
372
+ <span className="min-w-0 flex-1">
373
+ <span className="font-semibold">{health.text}.</span>
374
+ {health.hint && <span> {health.hint}</span>}
375
+ </span>
376
+ </div>
377
+ </Banner>
378
+ )}
379
+
170
380
  {tool.variables.length === 0 ? (
171
381
  <p className="text-body text-ink-muted">Nothing to set up</p>
172
382
  ) : (
@@ -180,7 +390,12 @@ export function ToolConnectionSection({ tool, onChanged, onError }: ToolConnecti
180
390
  setupKind={setupKind}
181
391
  returnTo={pathForTool(tool.slug)}
182
392
  editSignal={edit.name === variable.name ? edit.n : undefined}
183
- onChanged={onChanged}
393
+ onChanged={changed}
394
+ // Test the moment a key is entered — while the user still has it
395
+ // to hand, which is when a typo is cheapest to fix. Waiting for
396
+ // an agent to trip over it is how the wrong key got to look
397
+ // connected in the first place.
398
+ onSaved={onSaved}
184
399
  onError={onError}
185
400
  />
186
401
  ))}
@@ -50,6 +50,13 @@ export function ToolPage({
50
50
  // `actionError` so a successful reload can't clear a callback failure.
51
51
  const [oauthOutcome] = useState(readOAuthFragment);
52
52
  const [actionError, setActionError] = useState<string | null>(null);
53
+ /**
54
+ * Bumped when the tool's DEFINITION changes — an mcp.json server edit. Lives
55
+ * here rather than in the connection section because the section is not the
56
+ * component that knows a server was edited, and a probe verdict about the old
57
+ * endpoint must not survive the change.
58
+ */
59
+ const [serverRevision, setServerRevision] = useState(0);
53
60
 
54
61
  useEffect(() => {
55
62
  // Consume the OAuth `#…` fragment, KEEPING the query string: on an
@@ -143,8 +150,15 @@ export function ToolPage({
143
150
  </Banner>
144
151
  )}
145
152
 
153
+ {/* Keyed by slug: the section's probe verdict and `checking` flag are
154
+ component state about THIS tool. Navigating between two canonical
155
+ tools re-renders the same component instance, and without the key
156
+ the previous tool's "Connected" (or its failure banner) survives
157
+ under the next tool's heading. */}
146
158
  <ToolConnectionSection
159
+ key={tool.slug}
147
160
  tool={tool}
161
+ configRevision={serverRevision}
148
162
  onChanged={() => {
149
163
  setActionError(null);
150
164
  page.reload();
@@ -160,8 +174,13 @@ export function ToolPage({
160
174
  <McpServerSection
161
175
  slug={tool.slug}
162
176
  configuredCount={tool.variables.filter((v) => v.adminConfigured || v.userConfigured || v.authorized === true).length}
177
+ reloadSignal={page.revision}
163
178
  onSaved={() => {
164
179
  setActionError(null);
180
+ // The endpoint or headers may have just changed, so any verdict the
181
+ // connection section is holding describes a server that is no
182
+ // longer configured.
183
+ setServerRevision((r) => r + 1);
165
184
  page.reload();
166
185
  }}
167
186
  onError={setActionError}
@@ -50,6 +50,13 @@ export interface ToolVarRowProps {
50
50
  */
51
51
  editSignal?: number;
52
52
  onChanged(): void;
53
+ /**
54
+ * A credential was WRITTEN (not deleted) — a typed value or an owner's client
55
+ * secret. The one moment worth testing the connection, because it is the only
56
+ * one that can turn a broken tool into a working one. Deletes still call
57
+ * `onChanged`; they just have nothing to prove.
58
+ */
59
+ onSaved?(): void;
53
60
  onError(message: string): void;
54
61
  }
55
62
 
@@ -63,6 +70,7 @@ export function ToolVarRow({
63
70
  returnTo,
64
71
  editSignal,
65
72
  onChanged,
73
+ onSaved,
66
74
  onError,
67
75
  }: ToolVarRowProps) {
68
76
  const [editor, setEditor] = useState<Editor>(null);
@@ -108,12 +116,13 @@ export function ToolVarRow({
108
116
  }
109
117
 
110
118
  /** Every write funnels through here so busy/close/report is identical. */
111
- async function run(action: () => Promise<void>) {
119
+ async function run(action: () => Promise<void>, saved = false) {
112
120
  setBusy(true);
113
121
  try {
114
122
  await action();
115
123
  close();
116
124
  onChanged();
125
+ if (saved) onSaved?.();
117
126
  } catch (err) {
118
127
  onError(err instanceof Error ? err.message : String(err));
119
128
  } finally {
@@ -152,8 +161,12 @@ export function ToolVarRow({
152
161
  <Button key="reconnect" size="tiny" variant="quiet" disabled={busy} onClick={() => void signIn()}>
153
162
  Reconnect
154
163
  </Button>,
164
+ // "Signed in", not "Connected": at ROW level all we know is that a token
165
+ // exists. Whether it still works is the tool-level health line's claim,
166
+ // and it is the only place in the UI allowed to say "Connected" — one
167
+ // word, one meaning, backed by a real call.
155
168
  <Badge key="chip" tone="ok">
156
- Connected
169
+ Signed in
157
170
  </Badge>,
158
171
  );
159
172
  if (mayEditClientSecret) {
@@ -242,8 +255,12 @@ export function ToolVarRow({
242
255
  description = 'Each person sets their own';
243
256
  if (variable.userConfigured) {
244
257
  meta.push(
258
+ // "Key saved", not "Connected": a stored value is the whole of what
259
+ // this row knows. Whether it WORKS is the tool-level health line's
260
+ // claim, and letting a row make it was how a mistyped key came to
261
+ // render as a connection.
245
262
  <Badge key="chip" tone="ok">
246
- Connected
263
+ Key saved
247
264
  </Badge>,
248
265
  );
249
266
  } else {
@@ -259,12 +276,17 @@ export function ToolVarRow({
259
276
  const save = () => {
260
277
  const secret = value;
261
278
  if (isClientSecret) {
262
- return run(() => setOAuthClientSecret(slug, variable.name, secret));
279
+ // Also a credential change: a replaced client secret can invalidate the
280
+ // tokens minted under the old one, so the tool's health is now unknown
281
+ // and worth re-testing — same as any other saved value.
282
+ return run(() => setOAuthClientSecret(slug, variable.name, secret), true);
263
283
  }
264
- return run(() =>
265
- variable.scope === 'admin'
266
- ? setAdminVar(slug, variable.name, secret)
267
- : setUserVar(slug, variable.name, secret),
284
+ return run(
285
+ () =>
286
+ variable.scope === 'admin'
287
+ ? setAdminVar(slug, variable.name, secret)
288
+ : setUserVar(slug, variable.name, secret),
289
+ true,
268
290
  );
269
291
  };
270
292
 
@@ -41,6 +41,12 @@ export interface ToolPageState {
41
41
  skillsLoaded: boolean;
42
42
  /** Skills whose `allowed-tools` reach this tool. */
43
43
  poweredSkills: LibrarySkillSummary[];
44
+ /**
45
+ * Bumped by every `reload()`. A same-slug reload no longer remounts the page,
46
+ * so a child that fetches its own data on `[slug]` would never refetch —
47
+ * this is the signal it puts in its dependency list instead.
48
+ */
49
+ revision: number;
44
50
  reload(): void;
45
51
  }
46
52
 
@@ -64,15 +70,23 @@ export function useToolPage(slug: string): ToolPageState {
64
70
  const [revision, setRevision] = useState(0);
65
71
  const requestRef = useRef(0);
66
72
 
67
- // Switching tools (or reloading) has to clear the PREVIOUS tool's spine and
68
- // detail, or the page paints stale content under the new slug's heading. That
69
- // reset is state derived from a changed input, so it happens during render
70
- // against the previous key rather than in the effect body — an effect resets
71
- // after paint, which is both a frame of the old tool showing through and the
72
- // synchronous setState that `react-hooks/set-state-in-effect` flags.
73
- // `useState(key)` seeds the key so a fresh mount, already holding LOADING,
74
- // does not reset itself on the first render.
75
- const key = `${slug}:${revision}`;
73
+ // Switching tools has to clear the PREVIOUS tool's spine and detail, or the
74
+ // page paints stale content under the new slug's heading. That reset is state
75
+ // derived from a changed input, so it happens during render against the
76
+ // previous key rather than in the effect body — an effect resets after paint,
77
+ // which is both a frame of the old tool showing through and the synchronous
78
+ // setState that `react-hooks/set-state-in-effect` flags. `useState(key)` seeds
79
+ // the key so a fresh mount, already holding LOADING, does not reset itself on
80
+ // the first render.
81
+ //
82
+ // Keyed on the SLUG ALONE, so a same-tool `reload()` refetches WITHOUT
83
+ // blanking the page. There is no stale-slug hazard when the slug hasn't
84
+ // changed, and blanking had a cost: it dropped the page to `loading`, which
85
+ // unmounts the whole tool page — taking with it the connection section's
86
+ // probe verdict, which is held in component state precisely because it is not
87
+ // stored anywhere. Saving a key and then being told nothing about whether it
88
+ // works is the outcome that made this worth fixing.
89
+ const key = slug;
76
90
  const [seenKey, setSeenKey] = useState(key);
77
91
  if (key !== seenKey) {
78
92
  setSeenKey(key);
@@ -106,7 +120,10 @@ export function useToolPage(slug: string): ToolPageState {
106
120
  if (current()) setDetail(d);
107
121
  })
108
122
  .catch(() => {
109
- // Degraded, not broken: no lede and no capabilities section.
123
+ // Degraded, not broken: no lede and no capabilities section — and on
124
+ // a same-slug reload, degraded NOW: the previous fetch's description
125
+ // must not stand in for one this fetch could not vouch for.
126
+ if (current()) setDetail(null);
110
127
  });
111
128
 
112
129
  listSkills()
@@ -141,5 +158,5 @@ export function useToolPage(slug: string): ToolPageState {
141
158
 
142
159
  const reload = useCallback(() => setRevision((r) => r + 1), []);
143
160
 
144
- return { ...spine, detail, skillsLoaded, poweredSkills, reload };
161
+ return { ...spine, detail, skillsLoaded, poweredSkills, revision, reload };
145
162
  }
@@ -1,4 +1,5 @@
1
- import type { ToolSecrets, ToolVarStatus } from '../../secrets-vault/services/tool-secrets.api';
1
+ import { formatRelativeTime } from '../../../lib/utils';
2
+ import type { ProbeVerdict, ToolSecrets, ToolVarStatus } from '../../secrets-vault/services/tool-secrets.api';
2
3
 
3
4
  /**
4
5
  * Status derivation for the Library. Everything the cards, gems and loadout
@@ -25,15 +26,43 @@ export interface AttentionStatus {
25
26
  state: GemState;
26
27
  /** User-facing state line (glossary-compliant plain words). */
27
28
  text: string;
29
+ /**
30
+ * The sentence behind the word, for a tooltip: what the provider said, or why
31
+ * we couldn't ask. Absent when the word is the whole story.
32
+ *
33
+ * This is where a status EARNS its claim. "Connected" backed by "checked 2
34
+ * minutes ago" is a different assertion from "Connected" backed by nothing,
35
+ * and the difference is exactly what used to be missing.
36
+ */
37
+ hint?: string;
28
38
  }
29
39
 
40
+ /**
41
+ * Stored, and PROVEN to work by a real call.
42
+ *
43
+ * Reachable ONLY from a passing probe verdict. Nothing derived from what is
44
+ * merely stored may return this — that inference is the entire bug.
45
+ */
30
46
  const OK: AttentionStatus = { state: 'ok', text: 'Connected' };
31
47
 
48
+ /**
49
+ * In place, and untested — all a STORED value can ever support.
50
+ *
51
+ * Two words rather than one because they describe two different things the
52
+ * reader did. Green, because nothing here needs a person.
53
+ */
54
+ const SIGNED_IN: AttentionStatus = { state: 'ok', text: 'Signed in' };
55
+ const KEY_SAVED: AttentionStatus = { state: 'ok', text: 'Key saved' };
56
+
32
57
  /** Severity order for aggregation: broken sign-in beats anything merely unset. */
33
58
  const RANK: Record<GemState, number> = { ok: 0, warn: 1, err: 2 };
34
59
 
35
60
  /**
36
- * Two states, and the words for them: `Connected`, or `Needs <the thing>`.
61
+ * What ONE variable is: in place, or `Needs <the thing>`.
62
+ *
63
+ * Never `Connected`. This reads the vault, which knows only whether a value
64
+ * exists — so the strongest true statement it can make is that something was
65
+ * saved or signed into. Only a probe earns the other word.
37
66
  *
38
67
  * There is deliberately no middle. "Not set up yet", "Sign in again to keep
39
68
  * this working" and "Needs your sign-in" were three ways of saying one thing —
@@ -53,22 +82,82 @@ function varStatus(v: ToolVarStatus, canWrite: boolean): AttentionStatus {
53
82
  if (!v.adminConfigured) return notSetUp;
54
83
  if (v.authorized && v.needsReauth) return { state: 'err', text: 'Needs signing in again' };
55
84
  if (!v.authorized) return { state: 'warn', text: 'Needs your sign-in' };
56
- return OK;
85
+ return SIGNED_IN;
57
86
  }
58
87
  if (v.scope === 'user') {
59
- return v.userConfigured ? OK : { state: 'warn', text: 'Needs a key from you' };
88
+ return v.userConfigured ? KEY_SAVED : { state: 'warn', text: 'Needs a key from you' };
89
+ }
90
+ return v.adminConfigured ? KEY_SAVED : notSetUp;
91
+ }
92
+
93
+ /**
94
+ * The word for a tool that is fully SET UP, decided by whether the credential
95
+ * has actually been tested.
96
+ *
97
+ * Three outcomes, and the reason there are three: `Connected` is a claim we can
98
+ * back — something called the provider and it answered. `Key saved` is the
99
+ * narrower claim we can back when nothing tested it: a value is stored, and
100
+ * that is genuinely all we know. `Not working` is the provider's own verdict.
101
+ *
102
+ * `Key saved` stays GREEN. It is a complete, true statement about a tool that
103
+ * needs nothing from anybody, and painting it amber would put a permanent
104
+ * warning on every integration that simply has no way to be tested — which
105
+ * teaches people that amber means nothing.
106
+ *
107
+ * A tool whose vars are oauth-backed says `Signed in` instead: the user did not
108
+ * give us a key, they signed in, and telling them a key was saved is a small
109
+ * lie in a component whose entire job is to stop telling small lies.
110
+ */
111
+ function healthStatus(tool: ToolSecrets, verdict?: ProbeVerdict | null): AttentionStatus {
112
+ if (verdict?.status === 'ok') {
113
+ // The app's one relative-time formatter, not a local dialect of it. A
114
+ // verdict with no usable timestamp still just happened — it cannot outlive
115
+ // the component holding it — so "just now" is the honest fallback.
116
+ return { ...OK, hint: `Checked ${formatRelativeTime(verdict.checkedAt) || 'just now'}.` };
117
+ }
118
+ if (verdict?.status === 'failed') {
119
+ return {
120
+ state: 'err',
121
+ text: 'Not working',
122
+ hint: verdict.detail ?? 'The provider rejected this credential.',
123
+ };
60
124
  }
61
- return v.adminConfigured ? OK : notSetUp;
125
+ // The word has to match what the user actually did. A tool with no variables
126
+ // asked nothing of them, so "Key saved" would name a key that does not exist;
127
+ // an oauth-backed one got a sign-in, not a key. Same claim in all three cases
128
+ // — something is in place, nothing has tested it — said in the reader's terms.
129
+ const allOAuth = tool.variables.length > 0 && tool.variables.every((v) => v.oauth);
130
+ const text =
131
+ tool.variables.length === 0 ? 'No key needed' : allOAuth ? 'Signed in' : 'Key saved';
132
+ return {
133
+ state: 'ok',
134
+ text,
135
+ hint: verdict?.detail ?? "Not verified — this tool hasn't been tested yet.",
136
+ };
62
137
  }
63
138
 
64
- /** Aggregate connection state of one integration for the current user. */
65
- export function toolStatus(tool: ToolSecrets): AttentionStatus {
66
- let worst = OK;
139
+ /**
140
+ * Aggregate connection state of one integration for the current user.
141
+ *
142
+ * Setup comes FIRST: a tool still missing a key is `Needs a key from you`, never
143
+ * `Not working`. Both are unhealthy, but only one names something the user can
144
+ * act on, and a probe verdict from before the key was entered must not outrank
145
+ * the thing actually in the way. Only once every variable is provided does the
146
+ * question become whether what was provided works.
147
+ *
148
+ * `verdict` is the result of a probe the CALLER just ran and is holding, so only
149
+ * the tool page passes one. Every other surface — the library cards, the skill
150
+ * page's tool list — renders the untested green, because nothing there has
151
+ * tested anything: no verdict is stored, so claiming `Connected` on a list built
152
+ * from what is merely saved is the exact lie this module exists to stop.
153
+ */
154
+ export function toolStatus(tool: ToolSecrets, verdict?: ProbeVerdict | null): AttentionStatus {
155
+ let worst: AttentionStatus | null = null;
67
156
  for (const v of tool.variables) {
68
157
  const s = varStatus(v, tool.canWrite);
69
- if (RANK[s.state] > RANK[worst.state]) worst = s;
158
+ if (s.state !== 'ok' && (worst === null || RANK[s.state] > RANK[worst.state])) worst = s;
70
159
  }
71
- return worst;
160
+ return worst ?? healthStatus(tool, verdict);
72
161
  }
73
162
 
74
163
  /** Per-variable status rows for the integration detail dialog. */