@cubicecho/agent-core 4.10.0 → 4.12.0

package/README.md

@@ -30,11 +30,11 @@ only, Node >=22.
 | `side-task` | One-shot calls that support a run without being one — small prompt, short answer, no tools, never worth failing the run over. `askJson` holds the answer to a schema where the server can, and `taskCall` turns the settings an agent spec gives a task into the call that honours them. |
 | `hooks` | The host's side of lifecycle hooks: `gather` before a request and `notify` after, the shared context budget, `withContext` to put what they add on the turn's question, `untrusted` to fence text nobody vouched for, and `turnMessages` to hand them a transcript. Running a hook is a runner the caller passes. |
 | `events` | The in-memory bus a watcher reads while a run happens: `emit`, `watch`, `history`, `fold`, and `runMetrics` for what a run cost. A watcher's backlog is capped and reports its own gaps. |
-| `client` | A pooled `OpenAI` client per endpoint, plus the context window: the served one where a local server says, the listed one otherwise, and their caches. And `resolveApiKey`, for a caller deciding which key an endpoint gets. |
+| `client` | A pooled `OpenAI` client per endpoint, plus the context window: the served one where a local server says, the listed one otherwise, and their caches. And `resolveApiKey`, for a caller deciding which key an endpoint gets, and `probeEndpoint`, for listing one a form has not saved yet. |
 | `retry` | What to do when a request is lost, refused or too big: `isTransient`, `isModelLoading`, `backoffMs`, `ContextOverflow`, `EndpointSilent`. |
 | `calibration` | How many characters a token is worth on one model, learned from the prompt counts its endpoint reports: `charsPerTokenFor`, `calibrate`. |
 | `continuation` | `continueTurn`: carries on an answer the token ceiling cut off, by prefilling it as a trailing assistant message. |
-| `config` | The structural interfaces every function here asks for. |
+| `config` | The structural interfaces every function here asks for, and `normalizeBaseUrl`, the one rule for when two base URLs are one endpoint. |
 | `run-turn` | `runTurn`: one turn with the retry loop around the negotiation around the stream. The whole loop, for a caller that wants it rather than its parts. Sizes the request against an opt-in `contextLimit`. |
 | `agent-loop` | `runAgentLoop`: the loop above a turn — `runTurn` per step, the tools between, `load_tools` and preselection handled, until the model stops asking. |
 | `request-body` | `buildBody`: the one place a streamed request's body is decided from a config and what the endpoint and the model have refused. |
@@ -306,7 +306,7 @@ const turn = await runTurn(client, supports, build, {
 
 `contextLimitFor` answers the operator's number when there is one. Otherwise it reads the
 `/v1/models` listing first. A window at the top of the model's entry (`context_length`,
-`max_context_window`, `max_model_len`, `context_window` or `n_ctx`: vLLM's `max_model_len`,
+`max_context_length`, `max_context_window`, `max_model_len`, `context_window` or `n_ctx`: vLLM's `max_model_len`,
 OpenRouter's `context_length`) is taken as the one being served, and nothing else is asked.
 
 Where the listing does not settle it, the server's own API is asked (`servedWindow`): llama.cpp's
@@ -316,7 +316,10 @@ listed with only `meta.n_ctx_train`, which is llama.cpp. The trained window diff
 one in the case the guard exists for, a 256k model started at `-c 16384`, so it is used only when
 neither native route gives a number. A server with neither route is latched and not asked again.
 `/api/v0/models` is also dropped on its own: for the life of the process once it answers 404, 405
-or 501, and for `listingMissMs` after any other error.
+or 501, and for `listingMissMs` after any other error. A 200 that is not JSON counts as a missing
+route: it is what a proxy with a web app of its own (llm-router) answers on every path it does not
+route. Neither route is sent `NO_KEY` as a bearer; an endpoint with no key is asked with no
+`Authorization` header at all.
 
 A host that sizes the window before each run passes the run's signal as the third argument, so a
 stopped run does not wait on the lookup:
@@ -335,6 +338,33 @@ nothing would otherwise hold the lookup for that long, or for ever where there i
 bound `contextLimitFor` answers zero, as it does for a server it could not reach, and
 `listModels` rejects with a `TimeoutError`.
 
+### Listing an endpoint that is not saved yet
+
+`listModels` is for an endpoint that is configured: it pools a client per URL and remembers what
+came back. A settings form asking at each keystroke would leave a client behind for every
+half-typed URL, so it asks `probeEndpoint` instead, which makes one plain request and remembers
+nothing:
+
+```ts
+import { EndpointProbeError, ProbeFailure, probeEndpoint } from "@cubicecho/agent-core";
+
+try {
+  const models = await probeEndpoint({ baseUrl: typed, apiKey: typedKey }, { signal });
+} catch (error) {
+  if (error instanceof EndpointProbeError) {
+    // error.kind: invalid-url, unreachable, timeout, unauthorized, redirected, not-openai, failed.
+    // error.message is a sentence naming the endpoint by its origin, fit to show under the field.
+    return { problem: error.message };
+  }
+  throw error; // the signal's own reason
+}
+```
+
+It refuses a URL `normalizeBaseUrl` refuses before asking anybody, follows no redirect (so a typed
+key is never carried on to a host nobody typed), reads both OpenAI's `{ data: [...] }` and
+Ollama's native `{ models: [...] }` (by `name` where an entry has no `id`), and hands back each id
+once, sorted, at most `limit` of them (500 unless told). It is bounded as a lookup is.
+
 A top-level listing key is trusted without a second opinion, so on a server that puts a trained
 window there, pass `contextLength`. Ollama reports no window on any route this reads, and truncates
 an over-long prompt rather than refusing it, so on Ollama pass `contextLength` or there is no guard
@@ -532,6 +562,41 @@ its calls made on the error too, read off with `failedRun`.
 A link meant for the model alone — one whose MCP `audience` leaves out `"user"` — is the
 dispatcher's to drop, since that is MCP's rule and this package knows nothing of MCP.
 
+### A call that ends the run
+
+A tool whose call is the end of the job — handing off, asking a person — says so with `end` on
+its `ToolAnswer`, `true` or `{ reason }`. The loop answers every call of that step, sends no
+further request, and resolves with `ended`; aborting the run's signal from inside `dispatch` was
+the way out before, and that is a failure the host then has to dig the run back out of.
+
+```ts
+const result = await runAgentLoop({
+  // ...
+  dispatch: async ({ name, args }, signal) =>
+    name === "ask_person"
+      ? { text: "Asked. This run ends here.", end: { reason: String(args.question) } }
+      : pool.call(name, args, { signal }),
+});
+if (result.ended) {
+  // { callId, name: "ask_person", reason }
+  const { callId, name, reason = "" } = result.ended;
+  emit(runId, { kind: RunEventKind.Done, ok: true, id: callId, name, text: reason });
+}
+```
+
+The step's other calls still run, whichever side of the end the model asked for them and however
+`parallel` batches them: they were asked for in the same turn, and a model that says "write the
+file, then hand off" wants the file written in either order. Where two calls end it, `ended` is
+the first in the order asked. Everything else is a finished run's — `usage`, `metrics`,
+`messages`, `artifacts`, the `afterTurn` hooks — with `metrics.outcome` `ended` and a notice
+saying which tool ended it. `turn` is the turn that made the call, so its `content` is whatever
+the model wrote beside its calls, often nothing; the run's answer is what the ending tool took.
+The tool, its definition and its wording stay the host's: this is only the exit.
+
+A host's `done` that carries the call — `id`, `name` the tool, `text` the reason — is read by
+`runMetrics` as `ended` too, so the outcome is the same whether it is read off the result or the
+events.
+
 Arguments go through `parseToolArguments`, which is lenient where the model's meaning is plain:
 JSON held in a string is opened, and the almost-JSON local models write — single quotes, Python's
 `True` and `None`, bare keys, a trailing comma — is repaired, without touching what is inside a
@@ -874,6 +939,12 @@ it encodes is the conservative one: an endpoint's own key wins; one that names a
 own, different from the settings it inherits from, gets `NO_KEY` rather than the operator's key or
 `$OPENAI_API_KEY`; anything else inherits.
 
+"Different" is decided by `normalizeBaseUrl`, the same rule `endpointKey` and every cache here
+compares by: http or https, no credentials, query or fragment, scheme and host in lower case, no
+default port and no trailing slash. A host storing a base URL should store what it returns, and
+refuse a URL it answers `null` for. A URL it refuses still equals itself, trimmed of whitespace
+and trailing slashes, so a row saved before the rule still finds its own key.
+
 ## Fields this interface cannot spell
 
 `ModelParams` has `temperature`, `maxTokens` and `reasoningEffort`. Everything else a model card or
@@ -1438,7 +1509,7 @@ call returns everything in force. Lowering `maxClients` below the pool's current
 it at once, least recently used first. `resetClients` (and `resetAll`) puts the defaults back.
 
 A host that keeps per-endpoint state of its own should key it on `endpointKey` — the JSON of the base
-URL and the key, an absent key read as `NO_KEY` — rather than rebuilding that string, so the two
+URL as `normalizeBaseUrl` writes it and the key, an absent key read as `NO_KEY` — rather than rebuilding that string, so the two
 cannot drift. `endpointKey` holds the key in the clear; `endpointId`, its SHA-256 digest, is the one
 that is safe to write down.
 

package/dist/core/config.d.ts

@@ -57,11 +57,44 @@ export interface Endpoint {
  * not in it, since a different patience is not a different server.
  */
 export interface EndpointIdentity {
-    /** The base URL as given. Compared as written, so a trailing slash is another endpoint. */
+    /**
+     * The base URL as given. Compared as `baseUrlKey` has it, so a trailing slash, a host's case and
+     * a default port are the same endpoint, and a path's case and a `/v1` are not.
+     */
     baseUrl: string;
     /** Absent and empty mean the same: no key, which `endpointKey` reads as `NO_KEY`. */
     apiKey?: string;
 }
+/**
+ * A base URL worth storing: http or https, no credentials, query or fragment, no trailing slash.
+ *
+ * @param raw - The URL as typed. Surrounding whitespace is trimmed.
+ * @returns The URL as the WHATWG parser writes it, less its trailing slashes — scheme and host in
+ * lower case, a default port dropped — or `null` for anything that is not such a URL.
+ *
+ * @remarks
+ * One rule for every host, because "a stored key only goes to its own endpoint" is decided by
+ * comparing two of these, and four hosts writing four rules had begun to disagree about it. A key
+ * in the URL is a credential nobody meant to store; a query or a fragment is one more thing two
+ * copies of the same endpoint could differ in, and the SDK appends its paths after it.
+ *
+ * A host that stores a base URL stores this, and a form that refuses one refuses on `null`, so what
+ * is saved is already in the form every comparison here reads.
+ */
+export declare function normalizeBaseUrl(raw: string): string | null;
+/**
+ * A base URL in the form two of them are compared in, valid or not.
+ *
+ * @param raw - The URL as configured.
+ * @returns `normalizeBaseUrl`'s answer where it has one, and otherwise the URL trimmed of
+ * whitespace and trailing slashes, which is the rule every comparison here used before.
+ *
+ * @remarks
+ * A URL the normaliser refuses is still somebody's endpoint — an old settings row, a key written
+ * into the URL — and it still has to equal itself, so it falls back to the older, looser rule
+ * rather than to "unequal to everything".
+ */
+export declare const baseUrlKey: (raw: string) => string;
 /**
  * The request fields `extraBody` may not set, because the loop's request is built around them.
  *

package/dist/core/config.js

@@ -11,6 +11,51 @@
  * it structurally. Nothing imports a config *type* from a consumer, and no consumer has to grow
  * a field it has no use for in order to call `getClient`.
  */
+/**
+ * A base URL worth storing: http or https, no credentials, query or fragment, no trailing slash.
+ *
+ * @param raw - The URL as typed. Surrounding whitespace is trimmed.
+ * @returns The URL as the WHATWG parser writes it, less its trailing slashes — scheme and host in
+ * lower case, a default port dropped — or `null` for anything that is not such a URL.
+ *
+ * @remarks
+ * One rule for every host, because "a stored key only goes to its own endpoint" is decided by
+ * comparing two of these, and four hosts writing four rules had begun to disagree about it. A key
+ * in the URL is a credential nobody meant to store; a query or a fragment is one more thing two
+ * copies of the same endpoint could differ in, and the SDK appends its paths after it.
+ *
+ * A host that stores a base URL stores this, and a form that refuses one refuses on `null`, so what
+ * is saved is already in the form every comparison here reads.
+ */
+export function normalizeBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return null;
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        return null;
+    }
+    return url.toString().replace(/\/+$/, '');
+}
+/**
+ * A base URL in the form two of them are compared in, valid or not.
+ *
+ * @param raw - The URL as configured.
+ * @returns `normalizeBaseUrl`'s answer where it has one, and otherwise the URL trimmed of
+ * whitespace and trailing slashes, which is the rule every comparison here used before.
+ *
+ * @remarks
+ * A URL the normaliser refuses is still somebody's endpoint — an old settings row, a key written
+ * into the URL — and it still has to equal itself, so it falls back to the older, looser rule
+ * rather than to "unequal to everything".
+ */
+export const baseUrlKey = (raw) => normalizeBaseUrl(raw) ?? raw.trim().replace(/\/+$/, '');
 /**
  * The request fields `extraBody` may not set, because the loop's request is built around them.
  *

package/dist/endpoint/client.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { Endpoint, EndpointIdentity, RetryPolicy } from '../core/config.ts';
+import { type Endpoint, type EndpointIdentity, type RetryPolicy } from '../core/config.ts';
 /**
  * The SDK insists on a non-empty key even where the server will not look at it. This is what it
  * gets. It also reads as "this endpoint has no key" at a call site, which an empty string does
@@ -112,13 +112,15 @@ export interface ModelInfo {
  * `Endpoint` requires it — `capabilitiesFor` is handed a URL and maybe a key rather than a whole
  * config, and absent and empty already mean the same thing. The timeout is deliberately not in
  * it; see `listings`.
- * @returns The URL and the key as one JSON string, the key in the clear.
+ * @returns The URL as `baseUrlKey` writes it and the key, as one JSON string, the key in the clear.
  *
  * @remarks
  * The URL and the key together, because the key is part of what is on the other end rather than
  * only how it is paid for: a router is free to send two keys to two different backends, and then
  * what one of them refused is not a fact about the other. Absent reads as `NO_KEY`, so an
- * endpoint with no key and one that passes `undefined` are one entry rather than two.
+ * endpoint with no key and one that passes `undefined` are one entry rather than two. The URL is
+ * normalised for the same reason: `…/v1/` and `…/v1` are one server, and two entries for it would
+ * learn every refusal twice.
  *
  * Stringified rather than joined on a separator, for the reason `getClient` gives: no character
  * is impossible in a URL or a key, and two endpoints must never collide on one entry. A host
@@ -207,6 +209,72 @@ export declare function servedSlots(config: Endpoint & {
  * request's own error otherwise.
  */
 export declare function listModels(config: Endpoint, { signal }?: LookupOptions): Promise<ModelInfo[]>;
+/** Why `probeEndpoint` could not list an endpoint's models, in words a form can branch on. */
+export declare const ProbeFailure: {
+    /** Not an http or https URL, or one with credentials, a query or a fragment in it. */
+    readonly InvalidUrl: 'invalid-url';
+    /** Nothing answered: no such host, a refused connection, a TLS failure. */
+    readonly Unreachable: 'unreachable';
+    /** Something answered, but not inside the lookup's bound. */
+    readonly Timeout: 'timeout';
+    /** A 401 or a 403: the key is wrong, or one is needed. */
+    readonly Unauthorized: 'unauthorized';
+    /** A redirect, which is not followed, so the key is never carried to a host nobody typed. */
+    readonly Redirected: 'redirected';
+    /** An answer that is not a model listing: no such route, a web page, JSON of another shape. */
+    readonly NotOpenAi: 'not-openai';
+    /** Any other error status, which is on the error as `status`. */
+    readonly Failed: 'failed';
+};
+export type ProbeFailure = (typeof ProbeFailure)[keyof typeof ProbeFailure];
+/**
+ * `probeEndpoint` could not list an endpoint's models; `kind` says why.
+ *
+ * @remarks
+ * The message is a sentence for a person, naming the endpoint by its origin only, so it can go
+ * under a form field as it is. `kind` is for a form that words it itself.
+ */
+export declare class EndpointProbeError extends Error {
+    readonly name: string;
+    readonly kind: ProbeFailure;
+    /** The HTTP status, where the endpoint answered with one. */
+    readonly status?: number;
+    /**
+     * @param kind - Why the listing failed.
+     * @param message - The same, as a sentence.
+     * @param [status] - The status the endpoint answered with, where it answered.
+     */
+    constructor(kind: ProbeFailure, message: string, status?: number);
+}
+/** What `probeEndpoint` takes besides the endpoint. */
+export interface ProbeOptions extends LookupOptions {
+    /** How many models come back at most, the first by id. Defaults to `PROBE_MODEL_LIMIT`. */
+    limit?: number;
+}
+/**
+ * Asks an endpoint nobody has saved yet which models it serves, for a form a person is typing it
+ * into.
+ *
+ * @param endpoint - The endpoint as typed. Its key goes as a bearer token where it has one other
+ * than `NO_KEY`; its `requestTimeoutSeconds` bounds the request where that is shorter than
+ * `lookupTimeoutMs`.
+ * @param [options] - Cancellation, and how many models to hand back. See `ProbeOptions`.
+ * @returns The models in order of id, one entry per id, at most `options.limit` of them. Rejects
+ * with the reason of `options.signal` where that stopped it, and with an `EndpointProbeError`
+ * for every other failure.
+ *
+ * @remarks
+ * `listModels` is for an endpoint that is configured: it pools a client per URL and remembers the
+ * listing, and a form asking at every keystroke would leave a client and a listing behind for
+ * each half-typed URL. This makes one plain request and remembers nothing, so asking again asks
+ * again.
+ *
+ * Redirects are not followed, so a typed key is never carried on to a host nobody typed. Both
+ * listing shapes are read: OpenAI's `{ data: [...] }` by `id`, and Ollama's native
+ * `{ models: [...] }` by `name` where an entry has no `id`. A window is read from the keys
+ * `contextLimitFor` reads, and an id listed twice keeps the window one of its entries stated.
+ */
+export declare function probeEndpoint(endpoint: EndpointIdentity & Pick<Endpoint, 'requestTimeoutSeconds'>, { signal, limit }?: ProbeOptions): Promise<ModelInfo[]>;
 /**
  * How much a model will read, in tokens. Zero means nobody knows.
  *
@@ -245,12 +313,12 @@ export declare function contextLimitFor(config: Endpoint & {
  */
 export declare function resetClients(): void;
 /**
- * A base URL as two settings rows would agree on it: trimmed, without the trailing slash.
+ * Whether two base URLs are one endpoint, by `baseUrlKey`.
  *
  * @param a - The URL as one row has it.
  * @param b - The URL as the other has it.
- * @returns `true` where the two differ in nothing but surrounding whitespace and trailing slashes.
- * Case counts, and so does a `/v1`.
+ * @returns `true` where the two differ in nothing but surrounding whitespace, trailing slashes, the
+ * case of the scheme and host, and a default port. A path's case counts, and so does a `/v1`.
  */
 export declare const sameUrl: (a: string, b: string) => boolean;
 /**

package/dist/endpoint/client.js

@@ -1,4 +1,5 @@
 import OpenAI from 'openai';
+import { baseUrlKey, normalizeBaseUrl, } from '../core/config.js';
 import { digestOf } from '../core/digest.js';
 import { byCodeUnit, isPositive } from '../core/guards.js';
 import { MS_PER_SECOND } from '../core/platform.js';
@@ -192,7 +193,14 @@ export function getClient(config) {
  * reporting the same number twice. llama.cpp puts its number under `meta` instead, and LM Studio
  * and Ollama put none on this route at all; see `servedWindow`.
  */
-const CONTEXT_KEYS = ['context_length', 'max_context_window', 'max_model_len', 'context_window', 'n_ctx'];
+const CONTEXT_KEYS = [
+    'context_length',
+    'max_context_length',
+    'max_context_window',
+    'max_model_len',
+    'context_window',
+    'n_ctx',
+];
 /**
  * A number above zero as itself and anything else as zero, which here means "not stated".
  *
@@ -276,20 +284,22 @@ const misses = scoped(() => new Map());
  * `Endpoint` requires it — `capabilitiesFor` is handed a URL and maybe a key rather than a whole
  * config, and absent and empty already mean the same thing. The timeout is deliberately not in
  * it; see `listings`.
- * @returns The URL and the key as one JSON string, the key in the clear.
+ * @returns The URL as `baseUrlKey` writes it and the key, as one JSON string, the key in the clear.
  *
  * @remarks
  * The URL and the key together, because the key is part of what is on the other end rather than
  * only how it is paid for: a router is free to send two keys to two different backends, and then
  * what one of them refused is not a fact about the other. Absent reads as `NO_KEY`, so an
- * endpoint with no key and one that passes `undefined` are one entry rather than two.
+ * endpoint with no key and one that passes `undefined` are one entry rather than two. The URL is
+ * normalised for the same reason: `…/v1/` and `…/v1` are one server, and two entries for it would
+ * learn every refusal twice.
  *
  * Stringified rather than joined on a separator, for the reason `getClient` gives: no character
  * is impossible in a URL or a key, and two endpoints must never collide on one entry. A host
  * keeping its own per-endpoint state keys it on this rather than on a copy of it, so the two
  * cannot drift apart. It holds the key in the clear; `endpointId` is the one to write down.
  */
-export const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
+export const endpointKey = (config) => JSON.stringify([baseUrlKey(config.baseUrl), config.apiKey || NO_KEY]);
 /**
  * One model on one endpoint, as every per-model cache keys it: stringified, so neither half runs
  * into the other.
@@ -402,23 +412,39 @@ const NOT_THERE = new Set([
     HttpStatus.MethodNotAllowed,
     HttpStatus.NotImplemented,
 ]);
+/**
+ * The headers that carry an endpoint's key, and none where it has none.
+ *
+ * @param apiKey - The key as configured. Empty, absent and `NO_KEY` all mean there is none.
+ * @returns A bearer `authorization` header, or no headers at all.
+ *
+ * @remarks
+ * `NO_KEY` is the SDK's placeholder, not a credential, and a request made outside the SDK has no
+ * reason to send it: a server that checks keys refuses `Bearer agent-core` as it refuses a wrong
+ * one, where it might have answered an unauthenticated route.
+ */
+const authHeaders = (apiKey) => apiKey && apiKey !== NO_KEY ? { authorization: `Bearer ${apiKey}` } : {};
 /**
  * Asks one native endpoint.
  *
- * @param config - The endpoint. Its key goes as a bearer token where it has one.
+ * @param config - The endpoint. Its key goes as a bearer token where it has one other than `NO_KEY`.
  * @param path - The route and its query, from the server root rather than from the base URL.
  * @param within - The lookup's signal. Fired, the request throws as an unreachable server does.
  * @returns How the server answered, with `body` only for a 2xx that parsed as JSON.
  *
  * @remarks
- * `failed` is any answer that was not a 2xx and `missing` the ones among them that mean a server
- * without the route; `body` is absent for both, and for a 2xx that was not JSON. A server that
- * could not be reached throws.
+ * `failed` is any answer that was not a 2xx, or was not JSON, and `missing` the ones among them
+ * that mean a server without the route; `body` is absent for all of them. A server that could not
+ * be reached throws.
+ *
+ * A 2xx that is not JSON is a missing route rather than a route with nothing to say. It is what a
+ * proxy with a web app of its own answers on every path it does not route — llm-router serves its
+ * `index.html` for `/props` with a 200 — and read as "no window" it was asked again every
+ * `listingMissMs` instead of being latched as a server without the route.
  */
 async function probe(config, path, within) {
-    const apiKey = config.apiKey || undefined;
     const response = await fetch(`${rootOf(config.baseUrl)}${path}`, {
-        headers: apiKey ? { authorization: `Bearer ${apiKey}` } : {},
+        headers: authHeaders(config.apiKey),
         signal: within,
     });
     if (!response.ok) {
@@ -428,7 +454,9 @@ async function probe(config, path, within) {
         return { failed: false, missing: false, body: await response.json() };
     }
     catch {
-        return { failed: false, missing: false };
+        // A fired signal surfaces here too, mid-body, and is a server that stopped answering.
+        within.throwIfAborted();
+        return { failed: true, missing: true };
     }
 }
 /**
@@ -594,6 +622,144 @@ async function readListing(config, within) {
     trainedOnly().set(key, trained);
     return models;
 }
+/** Why `probeEndpoint` could not list an endpoint's models, in words a form can branch on. */
+export const ProbeFailure = {
+    /** Not an http or https URL, or one with credentials, a query or a fragment in it. */
+    InvalidUrl: 'invalid-url',
+    /** Nothing answered: no such host, a refused connection, a TLS failure. */
+    Unreachable: 'unreachable',
+    /** Something answered, but not inside the lookup's bound. */
+    Timeout: 'timeout',
+    /** A 401 or a 403: the key is wrong, or one is needed. */
+    Unauthorized: 'unauthorized',
+    /** A redirect, which is not followed, so the key is never carried to a host nobody typed. */
+    Redirected: 'redirected',
+    /** An answer that is not a model listing: no such route, a web page, JSON of another shape. */
+    NotOpenAi: 'not-openai',
+    /** Any other error status, which is on the error as `status`. */
+    Failed: 'failed',
+};
+/**
+ * `probeEndpoint` could not list an endpoint's models; `kind` says why.
+ *
+ * @remarks
+ * The message is a sentence for a person, naming the endpoint by its origin only, so it can go
+ * under a form field as it is. `kind` is for a form that words it itself.
+ */
+export class EndpointProbeError extends Error {
+    name = 'EndpointProbeError';
+    kind;
+    /** The HTTP status, where the endpoint answered with one. */
+    status;
+    /**
+     * @param kind - Why the listing failed.
+     * @param message - The same, as a sentence.
+     * @param [status] - The status the endpoint answered with, where it answered.
+     */
+    constructor(kind, message, status) {
+        super(message);
+        this.kind = kind;
+        if (status !== undefined) {
+            this.status = status;
+        }
+    }
+}
+/** How many models `probeEndpoint` hands back unless told otherwise: enough for any picker. */
+const PROBE_MODEL_LIMIT = 500;
+/** The statuses that mean the key, not the server, is what is wrong. */
+const UNAUTHORIZED = new Set([HttpStatus.Unauthorized, HttpStatus.Forbidden]);
+/** The range a redirect is answered in. */
+const REDIRECT_MIN = 300;
+const REDIRECT_MAX = 399;
+/**
+ * Asks an endpoint nobody has saved yet which models it serves, for a form a person is typing it
+ * into.
+ *
+ * @param endpoint - The endpoint as typed. Its key goes as a bearer token where it has one other
+ * than `NO_KEY`; its `requestTimeoutSeconds` bounds the request where that is shorter than
+ * `lookupTimeoutMs`.
+ * @param [options] - Cancellation, and how many models to hand back. See `ProbeOptions`.
+ * @returns The models in order of id, one entry per id, at most `options.limit` of them. Rejects
+ * with the reason of `options.signal` where that stopped it, and with an `EndpointProbeError`
+ * for every other failure.
+ *
+ * @remarks
+ * `listModels` is for an endpoint that is configured: it pools a client per URL and remembers the
+ * listing, and a form asking at every keystroke would leave a client and a listing behind for
+ * each half-typed URL. This makes one plain request and remembers nothing, so asking again asks
+ * again.
+ *
+ * Redirects are not followed, so a typed key is never carried on to a host nobody typed. Both
+ * listing shapes are read: OpenAI's `{ data: [...] }` by `id`, and Ollama's native
+ * `{ models: [...] }` by `name` where an entry has no `id`. A window is read from the keys
+ * `contextLimitFor` reads, and an id listed twice keeps the window one of its entries stated.
+ */
+export async function probeEndpoint(endpoint, { signal, limit = PROBE_MODEL_LIMIT } = {}) {
+    const baseUrl = normalizeBaseUrl(endpoint.baseUrl);
+    if (baseUrl === null) {
+        throw new EndpointProbeError(ProbeFailure.InvalidUrl, 'A base URL is http:// or https://, with no credentials, query or fragment in it.');
+    }
+    const url = new URL(`${baseUrl}/models`);
+    const within = lookupSignal(endpoint, signal);
+    /** The failure for a request that threw: the caller's stop, the bound, or no answer at all. */
+    const thrown = () => {
+        signal?.throwIfAborted();
+        return within.aborted
+            ? new EndpointProbeError(ProbeFailure.Timeout, `${url.origin} did not answer in time.`)
+            : new EndpointProbeError(ProbeFailure.Unreachable, `Could not reach ${url.origin}.`);
+    };
+    let response;
+    try {
+        response = await fetch(url, { headers: authHeaders(endpoint.apiKey), signal: within, redirect: 'manual' });
+    }
+    catch {
+        throw thrown();
+    }
+    const { status } = response;
+    // A browser hands a refused redirect back as an opaque response with status zero.
+    if (response.type === 'opaqueredirect' || (status >= REDIRECT_MIN && status <= REDIRECT_MAX)) {
+        const location = response.headers.get('location');
+        throw new EndpointProbeError(ProbeFailure.Redirected, `${url.origin} redirected the request${location ? ` to ${location}` : ''}; use the URL it redirects to.`, status || undefined);
+    }
+    if (UNAUTHORIZED.has(status)) {
+        throw new EndpointProbeError(ProbeFailure.Unauthorized, `${url.origin} refused the key (${status}).`, status);
+    }
+    if (NOT_THERE.has(status)) {
+        throw new EndpointProbeError(ProbeFailure.NotOpenAi, `${url.origin} has no model listing there (${status}); is the base URL missing a /v1?`, status);
+    }
+    if (response.ok === false) {
+        throw new EndpointProbeError(ProbeFailure.Failed, `${url.origin} answered ${status} when asked for its models.`, status);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        if (within.aborted) {
+            throw thrown();
+        }
+        body = undefined;
+    }
+    const { data, models } = (body ?? {});
+    const rows = Array.isArray(data) ? data : Array.isArray(models) ? models : undefined;
+    if (rows === undefined) {
+        throw new EndpointProbeError(ProbeFailure.NotOpenAi, `${url.origin} did not answer with a list of models.`);
+    }
+    const found = new Map();
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object') {
+            continue;
+        }
+        const entry = row;
+        const id = typeof entry.id === 'string' ? entry.id : typeof entry.name === 'string' ? entry.name : '';
+        if (id === '') {
+            continue;
+        }
+        const { contextLength } = contextLengthOf(row);
+        found.set(id, { id, contextLength: contextLength || (found.get(id)?.contextLength ?? 0) });
+    }
+    return [...found.values()].sort((a, b) => byCodeUnit(a.id, b.id)).slice(0, limit);
+}
 /**
  * How much a model will read, in tokens. Zero means nobody knows.
  *
@@ -692,14 +858,14 @@ export function resetClients() {
     refusals().clear();
 }
 /**
- * A base URL as two settings rows would agree on it: trimmed, without the trailing slash.
+ * Whether two base URLs are one endpoint, by `baseUrlKey`.
  *
  * @param a - The URL as one row has it.
  * @param b - The URL as the other has it.
- * @returns `true` where the two differ in nothing but surrounding whitespace and trailing slashes.
- * Case counts, and so does a `/v1`.
+ * @returns `true` where the two differ in nothing but surrounding whitespace, trailing slashes, the
+ * case of the scheme and host, and a default port. A path's case counts, and so does a `/v1`.
  */
-export const sameUrl = (a, b) => a.trim().replace(/\/+$/, '') === b.trim().replace(/\/+$/, '');
+export const sameUrl = (a, b) => baseUrlKey(a) === baseUrlKey(b);
 /**
  * The key to send, where an endpoint may inherit one from the settings it overrides.
  *

package/dist/endpoint/slots.js

@@ -1,3 +1,4 @@
+import { baseUrlKey } from '../core/config.js';
 import { scoped } from '../core/scope.js';
 import { modelKey } from './client.js';
 /**
@@ -22,14 +23,14 @@ const pools = scoped(() => ({ slots: new Map(), clock: 0 }));
  *
  * @param endpoint - The server, read for `baseUrl` alone.
  * @param model - The model, which a llama.cpp router serves from a process with slots of its own.
- * @returns The key: the base URL less its trailing slashes, and the model.
+ * @returns The key: the base URL as `baseUrlKey` writes it, and the model.
  *
  * @remarks
  * The API key is left out where every other per-endpoint cache keys on it. Two keys reaching
  * different servers through one URL cost only a slot left unused; two keys reaching the same
  * server under two allocators hand one slot to two runs, which is the collision this exists to stop.
  */
-const poolKey = (endpoint, model) => modelKey(endpoint.baseUrl.trim().replace(/\/+$/, ''), model);
+const poolKey = (endpoint, model) => modelKey(baseUrlKey(endpoint.baseUrl), model);
 /**
  * The slot allocator for one endpoint and model, sized to what its `/props` said.
  *

package/dist/index.d.ts

@@ -11,10 +11,10 @@
  */
 export { applyCompaction, COMPACT_AT, type CompactionOptions, type CompactionPlan, type CompactionRecord, type CompactionRunOptions, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, } from './context/compaction.ts';
 export { estimateFrom, type LedgerEntry, type LedgerEstimateOptions, type LedgerRequest, rebaseLedger, recordRequest, type TokenLedger, tokensBetween, } from './context/ledger.ts';
-export { type AgentConfig, type Endpoint, type ModelParams, type RetryPolicy, ToolDiscovery, type ToolPolicy, } from './core/config.ts';
+export { type AgentConfig, type Endpoint, type ModelParams, normalizeBaseUrl, type RetryPolicy, ToolDiscovery, type ToolPolicy, } from './core/config.ts';
 export { calibrate, charsPerTokenFor, resetCalibration } from './endpoint/calibration.ts';
 export { type Capabilities, capabilitiesFor, EFFORT_LADDER, EFFORT_NONE, EFFORT_OFF, effortFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from './endpoint/capabilities.ts';
-export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, firstTokenMs, getClient, type LookupOptions, listModels, type ModelInfo, NO_KEY, resetClients, resolveApiKey, servedSlots, servedWindow, timeoutMs, } from './endpoint/client.ts';
+export { type ClientPoolOptions, configureClients, contextLimitFor, EndpointProbeError, endpointId, endpointKey, firstTokenMs, getClient, type LookupOptions, listModels, type ModelInfo, NO_KEY, ProbeFailure, type ProbeOptions, probeEndpoint, resetClients, resolveApiKey, servedSlots, servedWindow, timeoutMs, } from './endpoint/client.ts';
 export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from './endpoint/schema-compat.ts';
 export { CACHE_PROMPT_FIELD, resetSlots, SESSION_HEADER, SLOT_FIELD, type SlotAllocator, slotAllocator, } from './endpoint/slots.ts';
 export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hooks/hook-events.ts';
@@ -39,5 +39,5 @@ export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow,
 export { CacheBreakReason, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from './wire/stream.ts';
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, SPLIT_OUTPUT, SPLIT_REASONING, type Split, stripThinking, THINK_FENCE, } from './wire/thinking.ts';
 export { type ContextBreakdown, type ContextBreakdownOptions, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, type TokenEstimateOptions, } from './wire/tokens.ts';
-export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, type ResourceLink, type RunArtifact, recoverToolCalls, type ServerLogEntry, ServerLogLevel, type ToolAnswer, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';
+export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, type EndedBy, parseToolArguments, type ResourceLink, type RunArtifact, recoverToolCalls, type ServerLogEntry, ServerLogLevel, type ToolAnswer, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';
 export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire/wire.ts';

package/dist/index.js

@@ -11,10 +11,10 @@
  */
 export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, } from './context/compaction.js';
 export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from './context/ledger.js';
-export { ToolDiscovery, } from './core/config.js';
+export { normalizeBaseUrl, ToolDiscovery, } from './core/config.js';
 export { calibrate, charsPerTokenFor, resetCalibration } from './endpoint/calibration.js';
 export { capabilitiesFor, EFFORT_LADDER, EFFORT_NONE, EFFORT_OFF, effortFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from './endpoint/capabilities.js';
-export { configureClients, contextLimitFor, endpointId, endpointKey, firstTokenMs, getClient, listModels, NO_KEY, resetClients, resolveApiKey, servedSlots, servedWindow, timeoutMs, } from './endpoint/client.js';
+export { configureClients, contextLimitFor, EndpointProbeError, endpointId, endpointKey, firstTokenMs, getClient, listModels, NO_KEY, ProbeFailure, probeEndpoint, resetClients, resolveApiKey, servedSlots, servedWindow, timeoutMs, } from './endpoint/client.js';
 export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from './endpoint/schema-compat.js';
 export { CACHE_PROMPT_FIELD, resetSlots, SESSION_HEADER, SLOT_FIELD, slotAllocator, } from './endpoint/slots.js';
 export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hooks/hook-events.js';

package/dist/run/agent-loop.d.ts

@@ -10,7 +10,7 @@ import { type KeywordPreselectOptions } from '../tools/preselect.ts';
 import { type ToolOrder } from '../tools/tool-loading.ts';
 import { type SideTask } from '../turn/side-task.ts';
 import { type Turn, type TurnUsage } from '../wire/stream.ts';
-import { type RunArtifact, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { type EndedBy, type RunArtifact, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
 import { type RunEventInput, type RunMetrics } from './events.ts';
 import { type ToolDispatch } from './run-calls.ts';
 /**
@@ -243,7 +243,8 @@ export interface AgentLoopOptions {
      * @remarks
      * A `ToolAnswer` in place of the string adds what the call produced: its `text` is the whole of
      * what goes into the transcript, and its `links` become the result's `artifacts`, an `artifact`
-     * event the first time each uri is seen, and `links` on what `onToolResult` is handed.
+     * event the first time each uri is seen, and `links` on what `onToolResult` is handed. Its `end`
+     * ends the run once the step's calls are answered; see `AgentLoopResult.ended`.
      */
     dispatch: ToolDispatch;
     /**
@@ -395,8 +396,29 @@ export interface AgentLoopOptions {
 }
 /** What a finished loop hands back. */
 export interface AgentLoopResult {
-    /** The last turn: the one that asked for no tools, as `onTurn` was handed it. */
+    /**
+     * The last turn, as `onTurn` was handed it: the one that asked for no tools, or — where a call
+     * `ended` the run — the one that made that call.
+     *
+     * @remarks
+     * Ended by a call, its `content` is what the model wrote beside its calls, which is often
+     * nothing, and its `toolCalls` are not empty. The run's answer is then whatever the ending tool
+     * took — the question it asked, the work it handed off — and not this text.
+     */
     turn: Turn;
+    /**
+     * The call whose answer said `end`, where one did: the first in the order the model asked, once
+     * every call of its step was answered. Absent where the run ended on a turn that asked for no
+     * tools.
+     *
+     * @remarks
+     * Every other field is as a finished run has it: `messages` close on the step's tool results
+     * with no assistant turn after them, the hooks are told `afterTurn` with `turn.content`, and
+     * `metrics.outcome` is `ended`. No `beforeStep` or `compact` runs after the end, since no request
+     * follows it. A host saying `done` passes the call on it — `id` the call, `name` the tool, `text`
+     * the reason — which is how `runMetrics` reads the same outcome off the events.
+     */
+    ended?: EndedBy;
     /** The transcript, with every assistant turn and tool result the run added. No system prompt. */
     messages: OpenAI.ChatCompletionMessageParam[];
     /** Summed over every turn of the run. */
@@ -463,14 +485,16 @@ export interface AgentLoopResult {
 }
 /**
  * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
- * until a turn asks for none. Throws when `maxToolIterations` is spent, when stopped, and on
- * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
+ * until a turn asks for none or a call's answer ends the run. Throws when `maxToolIterations` is
+ * spent, when stopped, and on whatever `runTurn` throws — `ContextOverflow` among them, however it
+ * was found out.
  *
  * @param options - The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
- * @returns The turn that asked for no tools and the run around it: the transcript with what the
- * run added, usage, every call, what is loaded and used, the hooks' notes and context, metrics
- * and the ledger. See `AgentLoopResult`.
+ * @returns The turn that asked for no tools — or made the call that ended the run, with `ended`
+ * naming it — and the run around it: the transcript with what the run added, usage, every call,
+ * what is loaded and used, the hooks' notes and context, metrics and the ledger. See
+ * `AgentLoopResult`.
  *
  * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
@@ -482,6 +506,11 @@ export interface AgentLoopResult {
  * well-formed: the results that came back are kept, and each call without one is answered with a
  * line saying it was stopped or never run, since a call with no result is refused on replay.
  *
+ * A tool that finishes the job — a hand-off, a question for a person — ends the run with a
+ * `ToolAnswer` whose `end` is set, rather than by aborting it: the step's calls are all run and
+ * answered, no further request is sent, and the loop resolves with `ended`. An end in the last step
+ * `maxToolIterations` allows resolves too, since nothing was left undone.
+ *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
  * prompt unchanged from step to step, a load adds to the tool array — which every request sends
  * in the stable order `toolOrder` asks for — and

package/dist/run/agent-loop.js

@@ -63,14 +63,16 @@ function cacheDiagnosis(previous, next, usage) {
 }
 /**
  * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
- * until a turn asks for none. Throws when `maxToolIterations` is spent, when stopped, and on
- * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
+ * until a turn asks for none or a call's answer ends the run. Throws when `maxToolIterations` is
+ * spent, when stopped, and on whatever `runTurn` throws — `ContextOverflow` among them, however it
+ * was found out.
  *
  * @param options - The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
- * @returns The turn that asked for no tools and the run around it: the transcript with what the
- * run added, usage, every call, what is loaded and used, the hooks' notes and context, metrics
- * and the ledger. See `AgentLoopResult`.
+ * @returns The turn that asked for no tools — or made the call that ended the run, with `ended`
+ * naming it — and the run around it: the transcript with what the run added, usage, every call,
+ * what is loaded and used, the hooks' notes and context, metrics and the ledger. See
+ * `AgentLoopResult`.
  *
  * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
@@ -82,6 +84,11 @@ function cacheDiagnosis(previous, next, usage) {
  * well-formed: the results that came back are kept, and each call without one is answered with a
  * line saying it was stopped or never run, since a call with no result is refused on replay.
  *
+ * A tool that finishes the job — a hand-off, a question for a person — ends the run with a
+ * `ToolAnswer` whose `end` is set, rather than by aborting it: the step's calls are all run and
+ * answered, no further request is sent, and the loop resolves with `ended`. An end in the last step
+ * `maxToolIterations` allows resolves too, since nothing was left undone.
+ *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
  * prompt unchanged from step to step, a load adds to the tool array — which every request sends
  * in the stable order `toolOrder` asks for — and
@@ -471,8 +478,8 @@ function turnCalls(turn, recoverable, notice) {
  * @param standing - Written to: once the steps have set themselves up, its `read` is theirs, so the
  * caller can read the run as it stands whether they return or throw.
  * @param [pin] - What the run's session adds to each request. Absent adds nothing.
- * @returns The result of the turn that asked for no tools, or `undefined` when `maxToolIterations`
- * is spent.
+ * @returns The result of the turn that asked for no tools or whose calls ended the run, or
+ * `undefined` when `maxToolIterations` is spent.
  */
 async function runSteps(options, standing, pin) {
     const { config, system = '', tools = [], catalog = [], dispatch, hooks, signal } = options;
@@ -706,13 +713,27 @@ async function runSteps(options, standing, pin) {
         const assistant = assistantMessage(content, parsed);
         messages.push(assistant);
         await announce(assistant, step, shown);
-        if (!calls.length) {
+        const isAnswer = calls.length === 0;
+        const ended = isAnswer ? undefined : await runCalls(calling, parsed, messages, step);
+        if (ended) {
+            const by = ended.reason ? `: ${ended.reason}` : '';
+            notice(`${ended.name} ended the run${by}`);
+        }
+        if (isAnswer || ended) {
             // Not awaited: the answer is ready, and remembering it is not something to hold it for.
             // Handed back instead, for a host that wants its notes.
             const afterTurn = hooks ? tellAfterTurn(hooks, messages, questionAt(), turn.content) : Promise.resolve([]);
             const metrics = runMetrics(recorded, { contextLength: config.contextLength });
+            let outcome = RunOutcome.Answered;
+            if (ended) {
+                outcome = RunOutcome.Ended;
+            }
+            else if (turn.finishReason === FinishReason.Length) {
+                outcome = RunOutcome.Truncated;
+            }
             return {
                 turn: shown,
+                ...(ended ? { ended } : {}),
                 messages,
                 usage,
                 toolCalls,
@@ -728,12 +749,11 @@ async function runSteps(options, standing, pin) {
                     ...metrics,
                     ...(onDemand ? loads : {}),
                     wallMs: Date.now() - started,
-                    outcome: turn.finishReason === FinishReason.Length ? RunOutcome.Truncated : RunOutcome.Answered,
+                    outcome,
                 },
                 ledger,
             };
         }
-        await runCalls(calling, parsed, messages, step);
     }
     return undefined;
 }

package/dist/run/events.d.ts

@@ -109,7 +109,10 @@ export declare const RunEventKind: {
      * measured either way.
      */
     readonly Usage: 'usage';
-    /** The run ended. Always last, and always sent. */
+    /**
+     * The run ended. Always last, and always sent. A run a tool call ended carries that call: `id`
+     * the call's, `name` the tool, and `text` the reason, as `AgentLoopResult.ended` has them.
+     */
     readonly Done: 'done';
 };
 /** Any one of the kinds in `RunEventKind`. */
@@ -171,7 +174,7 @@ export interface RunEvent {
     kind: RunEventKind;
     /** The delta, the arguments, the result, or the reason — whatever the kind carries. */
     text: string;
-    /** Tool name on the tool kinds, otherwise empty. */
+    /** Tool name on the tool kinds, and on a `done` the tool that ended the run; otherwise empty. */
     name: string;
     /**
      * The call's id on the tool kinds, which pairs a `tool-result` with its `tool-call` when one
@@ -390,6 +393,11 @@ export declare const RunOutcome: {
     readonly Answered: 'answered';
     /** The run did not fail, and its last turn is an answer the reply ceiling cut off. */
     readonly Truncated: 'truncated';
+    /**
+     * The run did not fail, and a tool call ended it: `AgentLoopResult.ended` says which, and so
+     * does a `done` that names the tool.
+     */
+    readonly Ended: 'ended';
     /**
      * `done` said the run was not ok. Whether that was an error, a stop or the tool budget is in
      * the host's own `done` text and not here.

package/dist/run/events.js

@@ -76,7 +76,10 @@ export const RunEventKind = {
      * measured either way.
      */
     Usage: 'usage',
-    /** The run ended. Always last, and always sent. */
+    /**
+     * The run ended. Always last, and always sent. A run a tool call ended carries that call: `id`
+     * the call's, `name` the tool, and `text` the reason, as `AgentLoopResult.ended` has them.
+     */
     Done: 'done',
 };
 /**
@@ -471,6 +474,11 @@ export const RunOutcome = {
     Answered: 'answered',
     /** The run did not fail, and its last turn is an answer the reply ceiling cut off. */
     Truncated: 'truncated',
+    /**
+     * The run did not fail, and a tool call ended it: `AgentLoopResult.ended` says which, and so
+     * does a `done` that names the tool.
+     */
+    Ended: 'ended',
     /**
      * `done` said the run was not ok. Whether that was an error, a stop or the tool budget is in
      * the host's own `done` text and not here.
@@ -480,15 +488,21 @@ export const RunOutcome = {
 /**
  * How a run that reported `done` ended.
  *
- * @param ok - What the `done` event said. Only `false` is a failure; anything else is read off the turn.
+ * @param done - The `done` event. Only an `ok` of `false` is a failure; one that names a tool was
+ * ended by it; anything else is read off the turn.
  * @param last - The last turn a `usage` event reported, if any did.
- * @returns `failed` for a `done` that was not ok, `truncated` where the last turn ran into the
- * reply ceiling, and `answered` otherwise.
+ * @returns `failed` for a `done` that was not ok, `ended` for one that names the tool that ended
+ * the run, `truncated` where the last turn ran into the reply ceiling, and `answered` otherwise.
  */
-function outcomeOf(ok, last) {
+function outcomeOf({ ok, name }, last) {
     if (ok === false) {
         return RunOutcome.Failed;
     }
+    // Read as a truthy string, so an event put together by hand without one is not ended.
+    const isEnded = Boolean(name);
+    if (isEnded) {
+        return RunOutcome.Ended;
+    }
     if (last?.finishReason === FinishReason.Length) {
         return RunOutcome.Truncated;
     }
@@ -614,7 +628,7 @@ export function runMetrics(events, { contextLength } = {}) {
             }
         }
         else if (event.kind === RunEventKind.Done) {
-            metrics.outcome = outcomeOf(event.ok, last);
+            metrics.outcome = outcomeOf(event, last);
         }
     }
     if (events.length > 1) {

package/dist/run/run-calls.d.ts

@@ -1,7 +1,7 @@
 import type OpenAI from 'openai';
 import type { CatalogServer } from '../tools/catalog.ts';
 import type { Turn } from '../wire/stream.ts';
-import { type RunArtifact, type ToolAnswer, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { type EndedBy, type RunArtifact, type ToolAnswer, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
 import type { RunEventInput } from './events.ts';
 /**
  * The tools between two turns: a step's calls read, run and written into the transcript.
@@ -114,13 +114,21 @@ export interface Calling {
  * @param parsed - The step's calls, with their arguments read.
  * @param messages - The transcript the results are written into.
  * @param step - Which step this is, for the host told of each result.
+ * @returns The first call, in the order asked, whose answer ended the run, or `undefined` where
+ * none did.
  *
  * @remarks
  * A failure part-way leaves the transcript well-formed before it is rethrown: a call with no
  * result is a transcript no endpoint takes back, so every call of the step is answered — with what
  * it returned where it had, and otherwise with a line saying it was stopped, or never run.
+ *
+ * An answer that ends the run does not end the step. The calls after it still run, in whatever
+ * batch `parallel` puts them, because the model asked for them in the same breath and how a host
+ * schedules calls is not what they mean: a reply that says "write the file, then hand off" in one
+ * turn wants the file written whichever order it named the two in, and a call batched beside the
+ * end was running already. A tool that must have nothing after it says so in its description.
  */
-export declare function runCalls(run: Calling, parsed: ReadCall[], messages: OpenAI.ChatCompletionMessageParam[], step: number): Promise<void>;
+export declare function runCalls(run: Calling, parsed: ReadCall[], messages: OpenAI.ChatCompletionMessageParam[], step: number): Promise<EndedBy | undefined>;
 /**
  * Writes a proxied preselection into the transcript as a `load_tools` exchange: the tool array is
  * fixed, so a shortlist has nowhere else to go, and it is answered as though the model had loaded

package/dist/run/run-calls.js

@@ -128,9 +128,19 @@ function reportFor(run, id, name) {
  * A dispatcher's answer in the one shape, whichever it gave.
  *
  * @param answer - What `dispatch` resolved to.
- * @returns The text and the links, a string answer's being none.
+ * @returns The text, the links and whether it ends the run, a string answer having no links and
+ * ending nothing.
  */
-const answerOf = (answer) => typeof answer === 'string' ? { text: answer, links: [] } : { text: answer.text, links: answer.links ?? [] };
+function answerOf(answer) {
+    if (typeof answer === 'string') {
+        return { text: answer, links: [], end: false };
+    }
+    const { text, links = [], end = false } = answer;
+    if (typeof end === 'object') {
+        return { text, links, end: { reason: end.reason } };
+    }
+    return { text, links, end: end ? {} : false };
+}
 /**
  * What a call is shown, counted and dispatched as: a `call_tool` as the tool it names.
  *
@@ -322,9 +332,9 @@ function batchEnd(run, ready, from, total, answered) {
  * @param prepared - The call, with its request built.
  * @param answered - The step's calls already made, by tool and arguments, for `dedupeToolCalls`.
  * @param step - Which step this is, for the artifacts the call's links become.
- * @returns The call's id, the name it was shown under, whether it worked, the whole of what the
- * model reads, and the links its answer carried, where it carried any. Rejects where the run was
- * stopped or a host callback threw.
+ * @returns The result — the call's id, the name it was shown under, whether it worked, the whole
+ * of what the model reads, and the links its answer carried, where it carried any — and whether
+ * the answer ended the run. Rejects where the run was stopped or a host callback threw.
  */
 async function runCall(run, prepared, answered, step) {
     const { catalog, onDemand, proxied, signal } = run;
@@ -336,6 +346,7 @@ async function runCall(run, prepared, answered, step) {
     const { report, close } = reportFor(run, call.id, name);
     let content;
     let links = [];
+    let end = false;
     let ok = true;
     // Answered from an earlier identical call of the step, whose links are already counted.
     let shared = false;
@@ -364,7 +375,7 @@ async function runCall(run, prepared, answered, step) {
             const answer = dedupable
                 ? await once(answered, key, () => run.dispatch(request, signal, report))
                 : await run.dispatch(request, signal, report);
-            ({ text: content, links } = answerOf(answer));
+            ({ text: content, links, end } = answerOf(answer));
         }
     }
     catch (error) {
@@ -384,7 +395,7 @@ async function runCall(run, prepared, answered, step) {
     }
     const result = { id: call.id, name, ok, content, ...(links.length ? { links } : {}) };
     run.onToolResult?.(result);
-    return result;
+    return { result, end };
 }
 /**
  * Runs a step's calls and writes each result into the transcript, in the order asked.
@@ -393,11 +404,19 @@ async function runCall(run, prepared, answered, step) {
  * @param parsed - The step's calls, with their arguments read.
  * @param messages - The transcript the results are written into.
  * @param step - Which step this is, for the host told of each result.
+ * @returns The first call, in the order asked, whose answer ended the run, or `undefined` where
+ * none did.
  *
  * @remarks
  * A failure part-way leaves the transcript well-formed before it is rethrown: a call with no
  * result is a transcript no endpoint takes back, so every call of the step is answered — with what
  * it returned where it had, and otherwise with a line saying it was stopped, or never run.
+ *
+ * An answer that ends the run does not end the step. The calls after it still run, in whatever
+ * batch `parallel` puts them, because the model asked for them in the same breath and how a host
+ * schedules calls is not what they mean: a reply that says "write the file, then hand off" in one
+ * turn wants the file written whichever order it named the two in, and a call batched beside the
+ * end was running already. A tool that must have nothing after it says so in its description.
  */
 export async function runCalls(run, parsed, messages, step) {
     const { signal, toolCalls } = run;
@@ -406,6 +425,7 @@ export async function runCalls(run, parsed, messages, step) {
     const answered = new Map();
     // By position, so a call that came back while another was being stopped is still found.
     const outcomes = parsed.map(() => undefined);
+    const ends = parsed.map(() => false);
     // How many of the step's calls were handed off, and how many have their result in the
     // transcript. Both count from the front, since results are written in the order asked.
     let begun = 0;
@@ -436,7 +456,9 @@ export async function runCalls(run, parsed, messages, step) {
             const to = batchEnd(run, ready, start, parsed.length, answered);
             begun = to;
             await Promise.all(parsed.slice(start, to).map(async (_, offset) => {
-                outcomes[start + offset] = await runCall(run, ready(start + offset), answered, step);
+                const { result, end } = await runCall(run, ready(start + offset), answered, step);
+                outcomes[start + offset] = result;
+                ends[start + offset] = end;
             }));
             for (const { id, name, ok, content } of outcomes.slice(from, to).flatMap((outcome) => outcome ?? [])) {
                 toolCalls.push({ id, name, ok });
@@ -444,6 +466,15 @@ export async function runCalls(run, parsed, messages, step) {
             }
             from = to;
         }
+        // The first by position rather than by finishing: a batch's calls end in no order worth
+        // reporting, and a deduplicated repeat shares its answer's `end` with the call before it.
+        const at = ends.findIndex((end) => end !== false);
+        const end = ends[at];
+        const outcome = outcomes[at];
+        if (end === undefined || end === false || outcome === undefined) {
+            return undefined;
+        }
+        return { callId: outcome.id, name: outcome.name, ...(end.reason === undefined ? {} : { reason: end.reason }) };
     }
     catch (error) {
         // Only a call that was made counts in `toolCalls`.

package/dist/wire/tool-calls.d.ts

@@ -188,6 +188,27 @@ export interface ToolAnswer {
     text: string;
     /** What the call produced, in the order the tool gave them. Never sent to the model. */
     links?: ResourceLink[];
+    /**
+     * Ends the run once this step's calls are answered: no further request is sent, and the loop
+     * resolves with `ended` rather than throwing. An object says why, for the host and its `done`.
+     *
+     * @remarks
+     * The step's other calls still run and are answered, so the transcript stays one an endpoint
+     * will take back. For a tool whose call is the end of the job — handing off, asking a person —
+     * where the alternative is an abort, which the loop reads as a failure.
+     */
+    end?: boolean | {
+        reason: string;
+    };
+}
+/** The call that ended a run through its answer's `end`, as `AgentLoopResult.ended` says it. */
+export interface EndedBy {
+    /** The call's id. */
+    callId: string;
+    /** The tool, under the name it was announced by: for a `call_tool`, the tool it names. */
+    name: string;
+    /** Why, where the answer said: absent for `end: true`. */
+    reason?: string;
 }
 /**
  * The levels a server's log message is sent at, quietest first: MCP's, which are syslog's.

package/dist/wire/wire.d.ts

@@ -68,6 +68,7 @@ export declare const HttpStatus: {
     readonly Ok: 200;
     readonly BadRequest: 400;
     readonly Unauthorized: 401;
+    readonly Forbidden: 403;
     readonly NotFound: 404;
     readonly MethodNotAllowed: 405;
     readonly RequestTimeout: 408;

package/dist/wire/wire.js

@@ -60,6 +60,7 @@ export const HttpStatus = {
     Ok: 200,
     BadRequest: 400,
     Unauthorized: 401,
+    Forbidden: 403,
     NotFound: 404,
     MethodNotAllowed: 405,
     RequestTimeout: 408,

package/llms.txt

@@ -50,6 +50,7 @@ What this package needs to know about a caller's configuration.
 - `AgentConfig` (type) — A whole agent configuration — every part, plus the two fields that belong to no group.
 - `Endpoint` (type) — Where to send a request and how long to wait.
 - `ModelParams` (type) — What to ask the model for.
+- `normalizeBaseUrl` — A base URL worth storing: http or https, no credentials, query or fragment, no trailing slash.
 - `RetryPolicy` (type) — How many times a lost or refused request is worth sending again.
 - `ToolDiscovery` — Any one of the modes in `ToolDiscovery`.
 - `ToolPolicy` (type) — How tools reach the model, and how long it may keep calling them.
@@ -84,6 +85,7 @@ What an endpoint turned out not to support, and answering it when it says so.
 - `ClientPoolOptions` (type) — What the client pool is held to across a process.
 - `configureClients` — Changes what the client pool is held to, for a process whose endpoints are not shaped like the deployments these defaults were chosen for.
 - `contextLimitFor` — How much a model will read, in tokens.
+- `EndpointProbeError` — `probeEndpoint` could not list an endpoint's models; `kind` says why.
 - `endpointId` — `endpointKey` hashed, for the remembered facts that can leave the process.
 - `endpointKey` — What counts as one endpoint, everywhere in this package that has to remember something about one — the model listings, `capabilities`, and the no-thinking hints in `side-task`.
 - `firstTokenMs` — The wait for a streamed turn's first chunk, in the SDK's spelling: `undefined` is no limit.
@@ -92,6 +94,9 @@ What an endpoint turned out not to support, and answering it when it says so.
 - `listModels` — Asks an endpoint what it serves, and remembers the answer.
 - `ModelInfo` (type) — A model an endpoint offers, and what it says the model will read.
 - `NO_KEY` — The SDK insists on a non-empty key even where the server will not look at it.
+- `ProbeFailure` — Why `probeEndpoint` could not list an endpoint's models, in words a form can branch on.
+- `ProbeOptions` (type) — What `probeEndpoint` takes besides the endpoint.
+- `probeEndpoint` — Asks an endpoint nobody has saved yet which models it serves, for a form a person is typing it into.
 - `resetClients` — Forgets every cached client and listing, and puts `configureClients` back to the defaults.
 - `resolveApiKey` — The key to send, where an endpoint may inherit one from the settings it overrides.
 - `servedSlots` — How many slots a llama.cpp server runs a model in, for pinning a session to one of them.
@@ -163,7 +168,7 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 - `PRESELECT_APPEND` — The `preselectRouting` that loads the shortlist after what was carried, and sends the first step like any other.
 - `PRESELECT_EXCLUSIVE` — The `preselectRouting` that sends the first step the shortlist alone.
 - `PRESELECTED_NOTICE` — What opens the notice naming the loop's own picks, ahead of the names.
-- `runAgentLoop` — Runs a question to its answer: one `runTurn` per step, the tools it asks for between them, until a turn asks for none.
+- `runAgentLoop` — Runs a question to its answer: one `runTurn` per step, the tools it asks for between them, until a turn asks for none or a call's answer ends the run.
 - `StepWindow` (type) — How full the window is as a step is about to be sent, as `beforeStep` is told it.
 
 ### events
@@ -402,6 +407,7 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 
 - `ARGUMENTS_MALFORMED` — The `ToolArgumentsError` kind for a call the model wrote wrongly.
 - `ARGUMENTS_TRUNCATED` — The `ToolArgumentsError` kind for a call cut off at the reply ceiling.
+- `EndedBy` (type) — The call that ended a run through its answer's `end`, as `AgentLoopResult.ended` says it.
 - `parseToolArguments` — A tool call's arguments as the object the tool is handed.
 - `ResourceLink` (type) — A handle to something a tool call made or found — a document it wrote, a file it saved.
 - `RunArtifact` (type) — One thing a run's tool calls produced: the first link to a uri, and where it came from.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "4.10.0",
+  "version": "4.12.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",