Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

style(agent): the comments told the story the commits already tell

yhhdb6aeef01779
diff --git a/desktop/electron/agent/anthropic.ts b/desktop/electron/agent/anthropic.ts
index 2a507b2c1..6bf5cb3c5 100644
--- a/desktop/electron/agent/anthropic.ts
+++ b/desktop/electron/agent/anthropic.ts
@@ -51,11 +51,9 @@ export interface AnthropicOptions {
/**
* Whether this endpoint's models can be handed an image.
*
- * A separate fact from the dialect, though the address once stood in for
- * both. The dialect is about which EXTENSIONS the request may carry; image
- * blocks are in the core format, so a gateway may well take them — and a
- * gateway that does had no way to say so. Omitted falls back to the guess
- * that fact replaced, for a caller with nothing to declare.
+ * Not the dialect: that is about which EXTENSIONS the request may carry, and
+ * image blocks are core format, so a gateway may well take them. Omitted falls
+ * back to the address, for a caller with nothing to declare.
*/
vision?: boolean;
/** How far the conversation may grow before the oldest runs are folded away.
@@ -137,9 +135,8 @@ export function buildStepRequest(opts: {
* happened: a model handed a silently dropped screenshot concludes the editor is
* broken, while one told the endpoint cannot carry it asks a different way.
*
- * Keyed on `vision` rather than on the dialect, which it once shared: image
- * blocks are core format, so a gateway that takes them is an ordinary case and
- * not an exception to be spotted from the address.
+ * Keyed on `vision`, not the dialect: image blocks are core format, so a gateway
+ * that takes them is an ordinary case and not one to spot from the address.
*/
export function toolResultContent(
outcome: ToolOutcome,
@@ -481,9 +478,9 @@ export function createAnthropicProvider(options: AnthropicOptions): AgentProvide
const effort = options.effort ?? DEFAULT_EFFORT;
const baseURL = options.baseURL || undefined;
const dialect: Dialect = baseURL ? 'compatible' : 'anthropic';
- // Declared by the provider that was picked. The fallback is the guess this
- // replaced — right for the API, and the safe way to be wrong for a caller
- // that says nothing, since a claimed sight an endpoint lacks costs the turn.
+ // Declared by the provider that was picked; the address is only the fallback
+ // for a caller that says nothing, since claimed sight an endpoint lacks costs
+ // the turn.
const vision = options.vision ?? dialect === 'anthropic';
const client = new Anthropic({ apiKey: options.apiKey, baseURL });
return {
diff --git a/desktop/electron/agent/openai.ts b/desktop/electron/agent/openai.ts
index a8d0bd927..7f6628c14 100644
--- a/desktop/electron/agent/openai.ts
+++ b/desktop/electron/agent/openai.ts
@@ -60,8 +60,7 @@ export interface OpenAIOptions {
* look at, and the answer is a property of the endpoint, not of the editor.
*
* The editor always says (src/agent/providers.ts declares it per provider);
- * omitted falls back to the guess that used to be the only answer — the
- * address — for a caller with nothing to declare.
+ * omitted falls back to the address, for a caller with nothing to declare.
*/
vision?: boolean;
/**
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 0c221514b..ee9923fa0 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -720,8 +720,7 @@ const agentHost = createAgentHost({
contextWindow: agentEndpoint.contextWindow,
vision: agentEndpoint.vision,
// An endpoint that has never heard of `reasoning_effort` refuses the
- // whole request over it, so whether to name the depth is the provider's
- // to declare — the same journey as the window and the sight.
+ // whole request over it, so the provider declares whether to name it.
reasoningEffort: agentEndpoint.reasoningEffort,
});
}
@@ -731,9 +730,8 @@ const agentHost = createAgentHost({
model: agentEndpoint.model,
effort,
contextWindow: agentEndpoint.contextWindow,
- // What the provider declared, not what its address implies. The window is
- // the side that knows which provider was picked, so it is the side that
- // says — for this the same as for the model and the window size.
+ // What the provider declared, not what its address implies. The window
+ // knows which provider was picked, so it is the side that says.
vision: agentEndpoint.vision,
});
},
diff --git a/desktop/src/agent/providers.ts b/desktop/src/agent/providers.ts
index 40323a594..ef390610d 100644
--- a/desktop/src/agent/providers.ts
+++ b/desktop/src/agent/providers.ts
@@ -59,10 +59,6 @@ export interface AgentProviderDef {
/**
* Whether a rendered frame can reach this endpoint's models at all.
*
- * DECLARED, never inferred. It was inferred once — "no baseUrl, therefore the
- * vendor's own API, therefore it can see" — which is only a statement about
- * the address, and it made every gateway blind with no way to say otherwise.
- *
* Per provider rather than per model, for {@link contextWindow}'s reason: a
* table with a row per model goes stale a model at a time. Absent means NO,
* deliberately — the two mistakes are not symmetrical. Claiming sight an
@@ -86,18 +82,14 @@ export interface AgentProviderDef {
*
* Only the OpenAI protocol carries it as a named argument (`reasoning_effort`),
* and an endpoint that has never heard of one refuses the whole request rather
- * than ignoring the field — so for a gateway this has to be a switch, not an
- * assumption. Absent means yes, which is right for every endpoint that
- * implements the parameter and is the behaviour that predates the field.
+ * than ignoring the field. Absent means yes.
*/
reasoningEffort?: boolean;
/**
* This def came from the person's own table rather than from this file.
*
- * Every OTHER field means the same thing whichever way it arrived — that is
- * the point of projecting the table into this registry instead of keeping it
- * beside it. This one exists so a reader that must not offer to edit a shipped
- * provider can tell the two apart.
+ * Every other field means the same thing whichever way it arrived; this one is
+ * for a reader that must not offer to edit a shipped provider.
*/
userDefined?: boolean;
}
@@ -108,11 +100,11 @@ export { DEFAULT_CONTEXT_WINDOW } from '@/settings/agentIds';
export const agentKeyId = (providerId: string): string => `agents.key.${providerId}`;
/**
- * The id the ONE custom provider had, back when there could only be one.
+ * The id reserved for a setup carried over from before providers were a list.
*
- * Kept because a key is filed under its provider's id: the row that setup
- * becomes on upgrade has to carry this id, or the credential already sealed on
- * the machine belongs to a provider that no longer exists (agent/userProviders.ts).
+ * A key is filed under its provider's id, so the migrated row must keep this one
+ * or the credential already sealed on the machine belongs to a provider that
+ * does not exist (agent/userProviders.ts).
*/
export const CUSTOM_PROVIDER = 'custom';
@@ -171,15 +163,12 @@ export const registerAgentProvider = (def: AgentProviderDef, owner: Owner = 'cor
/**
* Replace the set of providers the person defined themselves.
*
- * They arrive as a SET rather than one at a time because that is how they are
- * edited — a table, rewritten whole on each keystroke — and because the removals
- * matter as much as the additions: a provider deleted from the table must stop
- * being offered in the picker, and dispose-then-register is the only way to say
- * that without diffing. Everything downstream reads them through the same door
- * as the shipped ones; nothing but this function knows they were typed.
+ * A SET, because the removals matter as much as the additions: a provider
+ * deleted from the table must stop being offered, and dispose-then-register says
+ * that without diffing.
*
- * Kept here, taking finished defs, so this module stays free of the settings
- * store — the projection from one to the other lives in agent/userProviders.ts.
+ * Takes finished defs so this module stays free of the settings store — the
+ * projection lives in agent/userProviders.ts.
*/
export function setUserProviders(defs: readonly AgentProviderDef[]): void {
registry.disposeOwner(USER_OWNER);
diff --git a/desktop/src/agent/userProviders.ts b/desktop/src/agent/userProviders.ts
index 308751493..34fdd5414 100644
--- a/desktop/src/agent/userProviders.ts
+++ b/desktop/src/agent/userProviders.ts
@@ -1,21 +1,13 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file userProviders.ts — the providers a person defined, projected into the
- * same registry the shipped ones live in.
+ * @file userProviders.ts
+ * @brief The providers a person typed, projected into the registry the
+ * shipped ones live in.
*
- * There used to be exactly one, spelled out as four global settings
- * (`agents.customProtocol`, `…BaseUrl`, `…Models`, plus one key). That
- * contradicted the rule the shipped providers are built on — the unit of
- * configuration is a PROVIDER, and every one keeps its own key so switching back
- * to the one you used last week costs nothing. A local runner and a company
- * gateway could not both exist: configuring the second overwrote the first,
- * credential included.
- *
- * So they are a LIST now, and each row is a provider like any other: address,
- * protocol, models, its own key, and what it can do. This module is the only
- * place that knows a provider can come from a table — providers.ts stays a
- * registry, and every reader downstream sees one kind of provider.
+ * The only module that knows a provider can come from a settings table:
+ * providers.ts stays a registry, and every reader downstream sees one kind of
+ * provider.
*/
import { useSettings, dropPersisted } from '@/store/settingsStore';
import {
@@ -31,11 +23,9 @@ export const AGENT_PROVIDERS_SETTING = 'agents.providers';
/**
* One row of that table, as it is stored.
*
- * Flat and all-scalar because it IS the edited shape — the settings table writes
- * these fields directly, so a nested or derived form here would be a translation
- * layer between the control and the file. `models` is the raw text the person
- * typed for the same reason: splitting it on save would make the field fight the
- * cursor halfway through a comma.
+ * Flat and all-scalar because it IS the edited shape: the table writes these
+ * fields directly. `models` stays the raw text — splitting it on save would make
+ * the field fight the cursor halfway through a comma.
*/
export interface UserProviderRow {
/** Stable for the row's life — the key is filed under it. Never re-used. */
@@ -86,9 +76,7 @@ export function rowToDef(row: Record<string, unknown>): AgentProviderDef | null
baseUrl,
models: parseModelList(str(row.models)),
vision: row.vision === true,
- // Absent means yes for a shipped provider, so only an explicit `false` from
- // the table turns it off — a row written before the field existed must not
- // read as "this endpoint refuses the parameter".
+ // Absent means yes, so only an explicit `false` turns it off.
reasoningEffort: row.reasoningEffort !== false,
contextWindow: contextWindow > 0 ? contextWindow : DEFAULT_CONTEXT_WINDOW,
userDefined: true,
@@ -112,10 +100,9 @@ export const syncUserProviders = (): void => {
/**
* A row for a provider being added, with an id no earlier row has held.
*
- * Monotonic rather than "first free": ids that come back around would inherit
- * whatever is still filed under them, and a key belonging to a provider that was
- * deleted is not one to hand to its replacement. {@link forgetProviderSecret}
- * closes the same hole from the other side.
+ * Monotonic rather than "first free": a recycled id inherits whatever is still
+ * filed under it. {@link forgetProviderSecret} closes the same hole from the
+ * other side.
*/
export function newProviderRow(rows: readonly Record<string, unknown>[]): UserProviderRow {
let next = 1;
@@ -126,14 +113,13 @@ export function newProviderRow(rows: readonly Record<string, unknown>[]): UserPr
return {
id: `custom-${next}`,
label: '',
- // What most gateways and every local runner implement. Getting this wrong is
- // refused rather than degraded, so the likelier answer is the better default.
+ // Getting this wrong is refused rather than degraded, so default to what
+ // most gateways and every local runner implement.
protocol: 'openai',
baseUrl: '',
models: '',
vision: false,
- // Left out rather than zeroed: the cell then shows the default it would use
- // as its placeholder, instead of a 0 that reads like a window of nothing.
+ // Left out so the cell shows the fallback as its placeholder, not a 0.
reasoningEffort: true,
};
}
@@ -144,17 +130,15 @@ const LEGACY_IDS = [
] as const;
/**
- * Carry a pre-table setup across, once.
+ * Fold a pre-table setup into the table, once.
*
- * The row takes {@link CUSTOM_PROVIDER} as its id on purpose: a key is filed
- * under its provider's id, and this is the one migration step that cannot be
- * repaired by hand — main never hands a sealed credential back, so an id that
- * did not carry over is a key the person has to find again. The saved model pick
- * (`estella.agent.selection`) names the same id and so keeps resolving too.
+ * The row MUST take {@link CUSTOM_PROVIDER} as its id: a key is filed under its
+ * provider's id and main never hands a sealed one back, so an id that does not
+ * carry over is a credential the person has to find again. The saved model pick
+ * (`estella.agent.selection`) names the same id and keeps resolving too.
*
- * Runs only while the table has never been written. A person who has since
- * deleted every row means it, and re-adding what they removed on each boot is
- * the worst way for a migration to be wrong.
+ * Runs only while the table has never been written — someone who has since
+ * deleted every row meant it.
*/
export function migrateLegacyCustomProvider(): void {
const { values } = useSettings.getState();
@@ -162,8 +146,6 @@ export function migrateLegacyCustomProvider(): void {
const baseUrl = str(values['agents.customBaseUrl']).trim();
const models = str(values['agents.customModels']).trim();
if (!baseUrl && !models) {
- // Nothing was configured, but the legacy ids may still sit in the file as
- // defaults someone toggled and toggled back.
dropPersisted(LEGACY_IDS);
return;
}
diff --git a/desktop/src/components/AgentDrawer.tsx b/desktop/src/components/AgentDrawer.tsx
index 0872b7f27..6d3438b09 100644
--- a/desktop/src/components/AgentDrawer.tsx
+++ b/desktop/src/components/AgentDrawer.tsx
@@ -952,10 +952,9 @@ function ModelPicker() {
{open && (
<div className="ag-picker-menu">
{providers.map((p) => {
- // Its models, with the typed list filled in for the one vendor whose
- // names are not shippable. A provider the person defined arrives
- // whole — nothing here can tell it from a built-in, which is the
- // point of projecting the table into the same registry.
+ // Its models, with the typed list filled in for the one vendor
+ // whose names are not shippable. A provider the person defined
+ // arrives whole, and nothing here can tell it from a built-in.
const def = resolveProvider(p.id) ?? p;
const keyed = secretStatus(agentKeyId(p.id))?.configured === true;
if (def.models.length === 0 && !def.label) return null;
diff --git a/desktop/src/components/SettingsDialog.tsx b/desktop/src/components/SettingsDialog.tsx
index 2c82b8d28..335fb8d78 100644
--- a/desktop/src/components/SettingsDialog.tsx
+++ b/desktop/src/components/SettingsDialog.tsx
@@ -389,11 +389,9 @@ function writePath(row: Record<string, unknown>, path: string, v: unknown): Reco
* A credential belonging to one row of a list.
*
* The same bargain as {@link SecretControl} — typed once, never read back — in
- * the width of a table cell, so what it can show is which of the two states the
- * row is in. A row whose key is missing is the single most common reason a
- * configured-looking provider does nothing, so the unset state is a labelled
- * button rather than a blank field: it says what is absent, and asks for it in
- * place when clicked.
+ * the width of a table cell. The unset state is a labelled button rather than a
+ * blank field: a missing key is the likeliest reason a configured-looking row
+ * does nothing, so the cell says what is absent instead of looking empty.
*/
function ObjectListSecret({ id }: { id: string }) {
const status = useSyncExternalStore(subscribeSecrets, () => secretStatus(id));
@@ -501,9 +499,8 @@ function ObjectListField({
spellCheck={false}
placeholder={col.placeholder}
value={String(readPath(row, col.key) ?? '')}
- // A cleared number field is EMPTY, not zero — so it keeps showing the
- // placeholder (which is where a column says what it falls back to) instead
- // of a 0 the row never meant and the reader cannot tell from one it did.
+ // A cleared number field is EMPTY, not zero, so the placeholder keeps
+ // saying what the column falls back to.
onChange={(e) => onChange(
col.type !== 'number' ? e.target.value : (e.target.value === '' ? undefined : Number(e.target.value)),
)}
diff --git a/desktop/src/contrib/ContributionRegistry.ts b/desktop/src/contrib/ContributionRegistry.ts
index a34970f55..8eba9f03b 100644
--- a/desktop/src/contrib/ContributionRegistry.ts
+++ b/desktop/src/contrib/ContributionRegistry.ts
@@ -22,11 +22,9 @@
/**
* Who owns a contribution. `'core'` is the editor itself.
*
- * `'user'` is the person's own configuration — a set they edit in Settings that
- * is projected into a registry rather than kept beside it (agent providers are
- * the first). It disposes and re-registers as a group on every edit, which is
- * the same operation a plugin reload performs, so it belongs here rather than in
- * a parallel list that every reader would then have to remember to merge.
+ * `'user'` is a set the person edits in Settings and the editor projects into a
+ * registry (agent providers). It disposes and re-registers as a group on every
+ * edit — the same operation a plugin reload performs.
*/
export type Owner = 'core' | 'user' | `plugin:${string}`;
diff --git a/desktop/src/settings/editorSettings.ts b/desktop/src/settings/editorSettings.ts
index 3ae8e9f78..d29f82620 100644
--- a/desktop/src/settings/editorSettings.ts
+++ b/desktop/src/settings/editorSettings.ts
@@ -295,18 +295,13 @@ settingsRegistry.register({
effect: () => syncAgentEndpoint(),
});
-// Providers we have not heard of — which are exactly the ones we cannot ship an
-// address, a model list, or a word about what they accept.
+// Providers we have not heard of — exactly the ones we cannot ship an address, a
+// model list, or a word about what they accept.
//
-// A TABLE, not a set of fields, because the unit of configuration is a provider
-// and a person has more than one: a local runner and a company gateway are not
-// two states of one setting. Each row keeps its own key, for the same reason the
-// shipped rows above do.
-//
-// The main columns say where it is and what it speaks; the expander says what it
-// can DO. That split is the point — an endpoint that could only be given an
-// address had no way to tell the agent it accepts screenshots, and the agent
-// spent every session working blind without either side deciding that.
+// A TABLE, because the unit of configuration is a provider and a person has more
+// than one: a local runner and a company gateway are not two states of one
+// setting. Each row keeps its own key, as the shipped rows above do. The main
+// columns say where it is and what it speaks; the expander says what it can DO.
settingsRegistry.register({
id: AGENT_PROVIDERS_SETTING,
type: 'objectList',
diff --git a/desktop/src/settings/types.ts b/desktop/src/settings/types.ts
index 27b276771..9c0686a0c 100644
--- a/desktop/src/settings/types.ts
+++ b/desktop/src/settings/types.ts
@@ -201,9 +201,8 @@ export interface ObjectListColumn {
* Which credential a `secret` cell holds, derived from the row it sits in.
*
* The value never enters the row, the settings file or this process — main
- * seals it with the OS keychain, exactly as {@link SecretSetting} does. So the
- * column's `key` names the CELL and nothing else; a row carries the id the
- * credential is filed under, not the credential.
+ * seals it with the OS keychain, as {@link SecretSetting} does. The column's
+ * `key` therefore names the CELL only.
*/
secretId?: (row: Record<string, unknown>) => string;
}
@@ -234,9 +233,9 @@ export interface ObjectListSetting extends BaseSetting<Record<string, unknown>[]
/** Per-row validation → message, or null when the row is fine. */
rowError?: (row: Record<string, unknown>, all: Record<string, unknown>[]) => string | null;
/**
- * A row is on its way out, and it owned something the list does not hold — a
- * keychain entry, a file. Without this the thing outlives every reference to
- * it: unreachable from the UI, still on the machine, and inherited by whatever
+ * A row is on its way out and owned something the list does not hold — a
+ * keychain entry, a file. Without this it outlives every reference to it:
+ * unreachable from the UI, still on the machine, and inherited by whatever
* next takes the same row id.
*/
onRowRemoved?: (row: Record<string, unknown>) => void;
diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.ts
index b1a8e54b4..c4cd9b4f0 100644
--- a/desktop/src/store/AgentStore.ts
+++ b/desktop/src/store/AgentStore.ts
@@ -276,12 +276,9 @@ function loadSelection(): AgentSelection | null {
}
/**
- * A provider, with the one part of it that cannot be shipped filled in.
- *
- * Providers the person typed need nothing here — they are whole defs by the time
- * they reach the registry (agent/userProviders.ts), which is the point of
- * projecting them into it. What is left is the shipped vendor whose ADDRESS
- * holds still while its model names do not.
+ * A provider, with the one part of it that cannot be shipped filled in: the
+ * vendor whose ADDRESS holds still while its model names do not. Providers the
+ * person typed are whole defs already (agent/userProviders.ts).
*/
export function resolveProvider(id: string): AgentProviderDef | undefined {
const def = agentProvider(id);
@@ -293,10 +290,9 @@ export function resolveProvider(id: string): AgentProviderDef | undefined {
/**
* Whether the picked endpoint can be handed a picture.
*
- * The composer takes attachments whatever is selected, and an endpoint that
- * cannot carry them is not a failure — the turn goes out with the text and the
- * model is told what it was not shown. But that is a thing to learn BEFORE
- * sending, so this is read where the attachment is made too.
+ * The composer takes attachments whatever is selected; one that cannot carry
+ * them still sends the turn, with the model told what it was not shown. Read
+ * where the attachment is made so that is knowable before sending.
*/
export const agentAcceptsImages = (): boolean => {
const selection = effectiveSelection();
@@ -342,13 +338,11 @@ export function syncAgentEndpoint(): void {
// How far the conversation may grow before it is compacted. Travels with the
// endpoint because it is the same piece of knowledge: which provider this is.
contextWindow: def?.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
- // Whether a screenshot can reach it. Same journey as the window and for the
- // same reason: both are facts about which provider this is, and both were
- // once guessed from the address instead of being told.
+ // Whether a screenshot can reach it — the same journey as the window, and
+ // the same kind of fact: which provider this is.
vision: def?.vision === true,
- // Whether the depth below may be NAMED in the request. Its own fact because
- // an endpoint that has never heard of the argument refuses the call rather
- // than ignoring it — losing the turn over a field nobody asked for.
+ // Whether the depth below may be NAMED in the request: an endpoint that has
+ // never heard of the argument refuses the call rather than ignoring it.
reasoningEffort: def?.reasoningEffort !== false,
// How hard the model is asked to think. A setting rather than part of the
// model pick: the same model is worth running at different depths, and the
diff --git a/desktop/src/store/settingsStore.ts b/desktop/src/store/settingsStore.ts
index 5444cbf8a..e12873bf8 100644
--- a/desktop/src/store/settingsStore.ts
+++ b/desktop/src/store/settingsStore.ts
@@ -86,10 +86,9 @@ export const useSettings = create<SettingsState>((set, get) => ({
}));
/**
- * Forget persisted values outright — for a MIGRATION that has folded them into
- * some newer setting, where `reset` is not the operation: it writes the default
- * back under an id nothing reads any more, leaving the old shape in the file to
- * be puzzled over by whoever opens it next.
+ * Forget persisted values outright, for a migration that has folded them into a
+ * newer setting. `reset` is not the operation: it writes a default back under an
+ * id nothing reads any more.
*/
export function dropPersisted(ids: readonly string[]): void {
useSettings.setState((s) => {
diff --git a/desktop/tests/agent-dialect.test.ts b/desktop/tests/agent-dialect.test.ts
index accc5ddc4..0c6f9a8fa 100644
--- a/desktop/tests/agent-dialect.test.ts
+++ b/desktop/tests/agent-dialect.test.ts
@@ -166,11 +166,8 @@ describe('a tool result carrying a rendered frame', () => {
});
/**
- * Sight is DECLARED, not read off the address.
- *
- * It was read off the address once, and that made every gateway blind with no
- * way to say otherwise — including ones whose models see perfectly well, since
- * image blocks are core format and not one of the extensions the dialect gates.
+ * Sight is DECLARED, not read off the address — image blocks are core format,
+ * not one of the extensions the dialect gates, so a gateway may well take them.
*/
describe('whether the endpoint is told to be blind', () => {
const provider = (over = {}) => createAnthropicProvider({ apiKey: 'k', ...over });
@@ -287,8 +284,8 @@ describe('an image on the person\'s turn', () => {
expect(msg.content as string).toMatch(/cannot receive images|have not seen/);
});
- // And a gateway that DOES take them gets the picture, because what decides
- // this is what the provider declared and not where the endpoint lives.
+ // And a gateway that DOES take them gets the picture: what decides this is
+ // what the provider declared, not where the endpoint lives.
it('rides the turn on a gateway that declared it can see', () => {
const [msg] = messagesOf('https://gateway.example/anthropic', shot, 'like this', true);
expect((msg.content as Array<{ type: string }>).map((b) => b.type)).toEqual(['image', 'text']);
diff --git a/desktop/tests/agent-openai.test.ts b/desktop/tests/agent-openai.test.ts
index 827984a1d..83a949ace 100644
--- a/desktop/tests/agent-openai.test.ts
+++ b/desktop/tests/agent-openai.test.ts
@@ -121,9 +121,8 @@ describe('the provider', () => {
expect(provider({ baseURL: 'http://localhost:11434/v1' }).id).toBe('openai:http://localhost:11434/v1');
});
- // Declared by whoever picked the provider (src/agent/providers.ts). The
- // address is only the fallback for a caller that says nothing — reading it as
- // the answer is what left every gateway blind with no way to say otherwise.
+ // Declared by whoever picked the provider (src/agent/providers.ts); the
+ // address is only the fallback for a caller that says nothing.
it('takes the caller at its word, and falls back to the address', () => {
expect(provider({ baseURL: 'http://x/v1', vision: true }).acceptsImages).toBe(true);
expect(provider({ vision: false }).acceptsImages).toBe(false);
diff --git a/desktop/tests/agent-providers.test.ts b/desktop/tests/agent-providers.test.ts
index cd1776b96..89e900dba 100644
--- a/desktop/tests/agent-providers.test.ts
+++ b/desktop/tests/agent-providers.test.ts
@@ -46,9 +46,8 @@ describe('the shipped providers', () => {
expect(openai?.userDefined).toBeUndefined();
});
- // There is no reserved slot for "the custom one" any more. There cannot be:
- // the person has as many as they have endpoints, and a single slot meant
- // configuring the second overwrote the first, credential included.
+ // There is no reserved slot for "the custom one": a person has as many as
+ // they have endpoints.
it('ships no placeholder for the providers a person types', () => {
expect(agentProviders().every((p) => !p.userDefined)).toBe(true);
expect(agentProvider(CUSTOM_PROVIDER)).toBeUndefined();
@@ -56,9 +55,8 @@ describe('the shipped providers', () => {
});
/**
- * The typed providers arrive as a SET, because that is how they are edited — a
- * table rewritten whole — and because the removals matter as much as the
- * additions: one deleted from the table must stop being offered.
+ * They arrive as a SET, because the removals matter as much as the additions:
+ * one deleted from the table must stop being offered.
*/
describe('the providers a person defined', () => {
const def = (id: string, over = {}) => ({ id, label: id, baseUrl: `http://${id}/v1`, models: ['m'], ...over });
diff --git a/desktop/tests/agent-vision.test.ts b/desktop/tests/agent-vision.test.ts
index 8541cc033..cedd927a9 100644
--- a/desktop/tests/agent-vision.test.ts
+++ b/desktop/tests/agent-vision.test.ts
@@ -1,19 +1,14 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file What an endpoint can DO, from the row that declares it to the endpoint
- * main builds.
+ * @file agent-vision.test.ts
+ * @brief What an endpoint can DO, from the row that declares it to the
+ * endpoint main builds.
*
- * Sight used to be read off the address — no baseUrl, therefore the
- * vendor's own API, therefore it can see — which is a statement about
- * WHERE an endpoint is and not about what it accepts. Every gateway was
- * blind with no way to say otherwise, and the whole consequence was
- * silent: the agent was told each turn that screenshots could not reach
- * it, asked for `format: 'grid'` instead, and nobody could tell that
- * apart from a preference.
- *
- * The wire halves live with their protocols (agent-dialect, agent-openai);
- * what is checked here is that the facts travel.
+ * Every fact here is one an endpoint cannot be probed for, so a wrong one is
+ * silent: an agent told it cannot be sent screenshots asks for a text grid
+ * instead, and that reads as a preference. The wire halves live with their
+ * protocols (agent-dialect, agent-openai); this checks that the facts travel.
*/
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import '@/settings';
@@ -96,8 +91,7 @@ describe('an endpoint the person described', () => {
expect(sent.at(-1)).toMatchObject({ vision: true, baseUrl: 'http://localhost:11434/v1' });
});
- // A gateway address is not an answer to this question — that reading is the
- // bug. What matters is that the two facts travel separately.
+ // What matters is that the two facts travel separately.
it('carries the declaration alongside the address, not derived from it', () => {
configure(row({ vision: true }));
sent.length = 0;
@@ -138,11 +132,7 @@ describe('a provider that ships its own answer', () => {
});
});
-/**
- * The reason the table exists: a person has more than one of these, and the
- * shape it replaced could only hold one — configuring a second overwrote the
- * first, credential included.
- */
+/** The reason the table exists: a person has more than one of these. */
describe('more than one of them', () => {
it('keeps both, each with its own key id and its own capabilities', () => {
configure(
@@ -164,8 +154,7 @@ describe('more than one of them', () => {
expect(agentProvider('custom-1')).toBeDefined();
});
- // The registry is the one door: a shipped provider and a typed one are the
- // same kind of thing to everything downstream of it.
+ // The registry is the one door, and core holds its ids first.
it('does not let a typed row displace a shipped provider', () => {
configure(row({ id: 'anthropic', label: 'Impostor', baseUrl: 'http://evil/v1' }));
expect(agentProvider('anthropic')?.label).toBe('Anthropic');
@@ -173,9 +162,9 @@ describe('more than one of them', () => {
});
/**
- * A key is filed under its provider's id and lives outside the list, so the two
- * ends of a row's life both have to account for it: a deleted row's credential
- * must go, and a new row must never be handed an id that could still have one.
+ * A key is filed under its provider's id and lives outside the list, so both
+ * ends of a row's life have to account for it: a deleted row's credential must
+ * go, and a new row must never be handed an id that could still have one.
*/
describe('the credential a row owns', () => {
it('goes when the row does, under the id it was filed against', async () => {
@@ -196,15 +185,15 @@ describe('the credential a row owns', () => {
expect(newProviderRow([row({ id: 'custom-1' }), row({ id: 'custom-2' })]).id).toBe('custom-3');
// custom-2 was deleted; the next row must not step into its place.
expect(newProviderRow([row({ id: 'custom-3' })]).id).toBe('custom-4');
- // The migrated singleton carries a non-numbered id and must not confuse it.
+ // The migrated row carries a non-numbered id and must not confuse it.
expect(newProviderRow([row({ id: CUSTOM_PROVIDER })]).id).toBe('custom-1');
});
});
/**
- * A key is filed under its provider's id, and main never hands a sealed one
- * back — so an id that does not carry over is a credential the person has to
- * find again. This is the one migration step that cannot be repaired by hand.
+ * Main never hands a sealed key back, so an id that does not carry over is a
+ * credential the person has to find again — the one step here that cannot be
+ * repaired by hand.
*/
describe('a setup made before the table existed', () => {
it('keeps the id its key is filed under', async () => {
@@ -226,8 +215,7 @@ describe('a setup made before the table existed', () => {
'anthropic', 'https://gateway.example/anthropic', true,
]);
expect(def?.models).toEqual(['some-model']);
- // And the shape it replaced is gone from the file rather than left to be
- // puzzled over by whoever opens it next.
+ // And the ids it replaced are gone from the file.
expect(useSettings.getState().values['agents.customBaseUrl']).toBeUndefined();
});