@cubicecho/agent-core 4.1.0 → 4.3.0

package/README.md

@@ -588,7 +588,7 @@ one just over it means the ranking chose arbitrarily, which is the case a model
 on. Matching nothing is not confident either, since the words cannot tell a request that needs no
 tools from one whose words are not in the catalogue. An empty `toolSelectModel` still means no
 preselection at all, words included. `preselect` also takes a `temperature` and a
-`reasoningEffort`, read as `ask` reads them, and `runAgentLoop({ preselect: true })` makes the call
+`reasoningEffort` and an `extraBody`, read as `ask` reads them, and `runAgentLoop({ preselect: true })` makes the call
 itself — see "Its side tasks" below.
 
 A turn cut off at `maxTokens` is said so as a notice, and with `maxContinuations` above zero it is
@@ -1165,6 +1165,24 @@ applies `resolveApiKey` afterwards, so a document naming somebody else's endpoin
 host send its own provider key there. `exportSpec(spec)` strips a bundled server's `env` and
 `headers`, and a redacted document is still a valid one.
 
+Those two fields are where the format puts a bundled server's credentials, and not the only place a
+pasted `.mcp.json` has them: an `--api-key` among the `args`, a `?token=` or a `user:pass@` in the
+`url`. `exportSpec` keeps those, since a server with its query string cut off is a different
+server, and `findSpecSecrets` says where they may be so a host can warn before it calls a file safe
+to share:
+
+```ts
+const out = exportSpec(spec);
+for (const { path, server, sign } of findSpecSecrets(out)) {
+  warn(`${server}: ${path} may hold a credential (${sign})`); // bundle.mcpServers[0].args[2] … (flag)
+}
+```
+
+A hint is a place and a reason — `SecretSign.Userinfo`, `Query`, `Flag`, `Value` or `Field` — and
+never the value. It is a guess in both directions: a credential in a positional argument with no
+telling prefix is missed, and a flag called `--keyboard` is named. A `${VAR}` is a reference, and is
+not reported.
+
 `bundle.mcpServers` is parsed only under `parseSpec(document, { bundle: true })`. A bundled server
 is a command line and an environment map, so importing one is equivalent to running a program, and
 that is a decision a host makes rather than inherits from a default.
@@ -1178,7 +1196,7 @@ comes from.
 ### Its side tasks
 
 `tasks.<key>` configures a side task apart from the main model — its own model, endpoint, ceiling,
-temperature and reasoning effort — and resolution hands each back as a `ResolvedTask` holding only
+temperature, reasoning effort and `extraBody` — and resolution hands each back as a `ResolvedTask` holding only
 what a layer stated. `taskCall` turns one into the arguments `ask`, `askJson`, `summariser` and
 `preselect` already take, so a setting added to a task later arrives without the host's call
 changing:
@@ -1199,6 +1217,13 @@ no-thinking hints by default, and absent or `"off"` keeps them; a level — `"lo
 sent as `reasoning_effort` in their place, for a compaction model an operator pointed at a model
 that should deliberate.
 
+`extraBody` carries the sampler fields a model card asks for, as it does on the main model: `ask`,
+`askJson`, `summariser` and `preselect` all take one in their options, merge it in after the
+temperature, and offer its keys to `negotiate` as `droppable`, so a field the endpoint refuses by
+name is latched off for that model and the request is sent again without it. The agent's own
+`model.extraBody` is never sent to a side task, and `taskCall` lays a task's over the host's key by
+key.
+
 The third argument is the endpoint the main turn uses. Given it, a task on the same endpoint is
 sent the agent's spelling of the URL and, having no key of its own, the agent's key, so the two
 share one entry in `capabilitiesFor` and a refusal learned by either is known to both; a task on

package/dist/endpoint/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointIdentity } from '../core/config.ts';
+import { type EndpointIdentity } from '../core/config.ts';
 import type { Produced } from '../wire/stream.ts';
 /**
  * What an endpoint turned out not to support, and answering it when it says so.
@@ -307,6 +307,20 @@ export declare const ceilingAndTemperature: (refused: ModelCapabilities | undefi
 } | {
     temperature?: number | undefined;
 };
+/**
+ * The request fields an `extraBody` adds as this model takes them, to spread into a request body.
+ *
+ * @param refused - What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param [extraBody] - The fields to add. Absent adds none.
+ * @returns A fresh object of the fields, less the `RESERVED_BODY_FIELDS` and those the model has
+ * refused by name.
+ *
+ * @remarks
+ * The keys are what a caller hands `negotiate` as `droppable`, so a field the endpoint has never
+ * heard of is latched into `refusedFields` and left out of the next send.
+ */
+export declare const extraFields: (refused: ModelCapabilities | undefined, extraBody?: Record<string, unknown>) => Record<string, unknown>;
 /** What `negotiate` takes besides the request. All optional. */
 export interface NegotiateOptions {
     /**

package/dist/endpoint/capabilities.js

@@ -1,3 +1,4 @@
+import { RESERVED_BODY_FIELDS } from '../core/config.js';
 import { getOrCreate } from '../core/guards.js';
 import { scoped } from '../core/scope.js';
 import { errorMessage } from '../wire/errors.js';
@@ -353,6 +354,20 @@ export const ceilingAndTemperature = (refused, maxTokens, temperature) => {
         ...(refused?.chosenTemperature === false ? {} : { temperature }),
     };
 };
+/**
+ * The request fields an `extraBody` adds as this model takes them, to spread into a request body.
+ *
+ * @param refused - What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param [extraBody] - The fields to add. Absent adds none.
+ * @returns A fresh object of the fields, less the `RESERVED_BODY_FIELDS` and those the model has
+ * refused by name.
+ *
+ * @remarks
+ * The keys are what a caller hands `negotiate` as `droppable`, so a field the endpoint has never
+ * heard of is latched into `refusedFields` and left out of the next send.
+ */
+export const extraFields = (refused, extraBody = {}) => Object.fromEntries(Object.entries(extraBody).filter(([field]) => !RESERVED_BODY_FIELDS.includes(field) && !refused?.refusedFields.has(field)));
 /**
  * How to answer a refused effort *value*, or `undefined` when there is nothing new to learn or
  * nowhere left to go — in which case the refusal is the caller's, as it was before this existed.

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export { preview } from './run/run-calls.ts';
 export { resetAll } from './runtime/reset.ts';
 export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from './runtime/runtime.ts';
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from './runtime/snapshot.ts';
-export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from './spec/spec.ts';
+export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, findSpecSecrets, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, type SecretHint, SecretSign, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from './spec/spec.ts';
 export type { CatalogServer } from './tools/catalog.ts';
 export { type KeywordPreselection, type KeywordPreselectOptions, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, type ToolMatch, } from './tools/preselect.ts';
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, type ToolOrder, } from './tools/tool-loading.ts';

package/dist/index.js

@@ -25,7 +25,7 @@ export { preview } from './run/run-calls.js';
 export { resetAll } from './runtime/reset.js';
 export { createRuntime, defaultRuntime } from './runtime/runtime.js';
 export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from './runtime/snapshot.js';
-export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from './spec/spec.js';
+export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, findSpecSecrets, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SecretSign, SPEC_EVENTS, } from './spec/spec.js';
 export { PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, } from './tools/preselect.js';
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from './tools/tool-loading.js';
 export { continueTurn, } from './turn/continuation.js';

package/dist/run/request-body.d.ts

@@ -1,5 +1,5 @@
 import type OpenAI from 'openai';
-import { type ModelParams } from '../core/config.ts';
+import type { ModelParams } from '../core/config.ts';
 import { type Capabilities, type ModelCapabilities } from '../endpoint/capabilities.ts';
 import { type ToolOrder } from '../tools/tool-loading.ts';
 /**

package/dist/run/request-body.js

@@ -1,5 +1,4 @@
-import { RESERVED_BODY_FIELDS } from '../core/config.js';
-import { ceilingAndTemperature, effortFor, } from '../endpoint/capabilities.js';
+import { ceilingAndTemperature, effortFor, extraFields, } from '../endpoint/capabilities.js';
 import { relaxTools, sanitizeTools } from '../endpoint/schema-compat.js';
 import { orderTools } from '../tools/tool-loading.js';
 /**
@@ -33,12 +32,11 @@ export function buildBody(config, supports, refused, messages, tools = [], order
     const sorted = orderTools(tools, order);
     const declared = supports.strictSchemas ? sanitizeTools(sorted) : relaxTools(sanitizeTools(sorted));
     const effort = effortFor(refused, config.reasoningEffort);
-    const extra = Object.entries(config.extraBody ?? {}).filter(([field]) => !RESERVED_BODY_FIELDS.includes(field) && !refused?.refusedFields.has(field));
     return {
         ...ceilingAndTemperature(refused, config.maxTokens, config.temperature),
         ...(effort ? { reasoning_effort: effort } : {}),
         ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
-        ...Object.fromEntries(extra),
+        ...extraFields(refused, config.extraBody),
         model: config.model,
         messages,
         stream: true,

package/dist/spec/spec.d.ts

@@ -151,6 +151,8 @@ export interface TaskSpec {
      * side task is sent by default; see `SideTaskOptions.reasoningEffort`.
      */
     reasoningEffort?: string;
+    /** Request fields the interface cannot spell, as `model.extraBody` but for this task alone. */
+    extraBody?: Record<string, unknown>;
 }
 /** A tool call bound to a lifecycle event, run by the host rather than the model. */
 export interface AgentHook {
@@ -198,7 +200,7 @@ export interface SpecBundle {
  * One side task, resolved: a model, and the endpoint it is reached through.
  *
  * @remarks
- * The three settings are present only where a layer stated them, and nothing is filled in from
+ * The settings are present only where a layer stated them, and nothing is filled in from
  * the agent's own model — `taskCall` turns one into a call, and what is absent there is left to
  * the side task's default.
  */
@@ -209,6 +211,8 @@ export interface ResolvedTask {
     maxTokens?: number;
     temperature?: number;
     reasoningEffort?: string;
+    /** Merged key by key across the layers. `model.extraBody` is the agent's and never reaches it. */
+    extraBody?: Record<string, unknown>;
 }
 /**
  * What layered documents resolve to: the flat shape the loop already takes, plus the parts of an
@@ -359,7 +363,47 @@ export interface ExportSpecOptions {
  * The property worth keeping is that **a redacted spec is still a valid spec** — it parses, it
  * resolves, and what comes back is the same agent pointed at the same servers, needing only the
  * credentials the importing host supplies itself. So a bundled server loses its `env` and its
- * `headers` and nothing else, and nothing outside `bundle` is touched: the format has no
- * credential field at any depth, which is the reason there is nothing else to strip.
+ * `headers` and nothing else, and nothing outside `bundle` is touched: those two are the only
+ * fields the format gives a credential. A server can still carry one where the format gives it no
+ * field — an `--api-key` among its `args`, a token in its `url` — and that is kept, because
+ * cutting it would point the agent at a different server. `findSpecSecrets` says where to look.
  */
 export declare function exportSpec(spec: AgentSpec, { secrets }?: ExportSpecOptions): AgentSpec;
+/** Why `findSpecSecrets` named a place. */
+export declare const SecretSign: {
+    /** A URL with a user or a password before its host. */
+    readonly Userinfo: 'userinfo';
+    /** A URL query parameter whose name reads as a credential's. */
+    readonly Query: 'query';
+    /** The value of a command-line flag, or of a header written as `Name: value`, so named. */
+    readonly Flag: 'flag';
+    /** A value with the shape of a credential: a known key prefix, or `Bearer` and a token. */
+    readonly Value: 'value';
+    /** A key of the server itself whose name reads as a credential's. */
+    readonly Field: 'field';
+};
+/** Any one of the reasons in `SecretSign`. */
+export type SecretSign = (typeof SecretSign)[keyof typeof SecretSign];
+/** One place `findSpecSecrets` thinks a credential may be, and never the credential. */
+export interface SecretHint {
+    /** Where, in `parseSpec`'s spelling: `bundle.mcpServers[0].args[2]`. */
+    path: string;
+    /** The server's slug, or its id where it has no slug. */
+    server: string;
+    sign: SecretSign;
+}
+/**
+ * Where a document's bundled servers may still carry a credential after `exportSpec`.
+ *
+ * @param spec - A document, exported or not: `env` and `headers` are not reported either way,
+ * since `exportSpec` strips them.
+ * @returns One hint for each suspect place, in document order, each naming where and why and
+ * none holding the value. Empty for a document with no bundle.
+ *
+ * @remarks
+ * A host calls this before it offers an export as safe to share, and warns with what comes back.
+ * It reads a server's `url`, its `command` and `args`, and the names of its other keys, and is a
+ * guess both ways: a credential in a positional argument with no telling prefix is missed, and a
+ * flag called `--keyboard` is named. A `${VAR}` is a reference and is never named.
+ */
+export declare function findSpecSecrets(spec: AgentSpec): SecretHint[];

package/dist/spec/spec.js

@@ -241,10 +241,6 @@ const parseSampling = (report, path, value) => ({
  * @param value - What the document held under `model`.
  * @returns The fields that survived — an empty object where none did — or `undefined` where the
  * section is absent or is not an object.
- *
- * @remarks
- * `extraBody` comes back as a new object without the `RESERVED_BODY_FIELDS`, each of which is
- * warned about. An empty one survives as an empty one.
  */
 function parseModel(report, value) {
     if (absent(value)) {
@@ -253,31 +249,41 @@ function parseModel(report, value) {
     if (!isRecord(value)) {
         return void report.drop('model', 'must be an object');
     }
-    let extraBody;
-    if (!absent(value.extraBody)) {
-        if (!isRecord(value.extraBody)) {
-            report.drop('model.extraBody', 'must be an object');
-        }
-        else {
-            extraBody = {};
-            for (const [key, held] of Object.entries(value.extraBody)) {
-                // `buildBody` would overwrite them anyway; better to say so on import.
-                if (RESERVED_BODY_FIELDS.includes(key)) {
-                    report.drop(`model.extraBody.${key}`, "is the loop's to set");
-                }
-                else {
-                    extraBody[key] = held;
-                }
-            }
-        }
-    }
     return kept({
         model: report.string('model.model', value.model),
         ...parseSampling(report, 'model', value),
         contextLength: report.number('model.contextLength', value.contextLength, 0),
-        extraBody,
+        extraBody: parseExtraBody(report, 'model.extraBody', value.extraBody),
     });
 }
+/**
+ * Reads an `extraBody`, the agent's model's or a side task's.
+ *
+ * @param report - Where what is dropped is written.
+ * @param path - Where it sits in the document: `model.extraBody`, or `tasks.title.extraBody`.
+ * @param value - What the document held there.
+ * @returns A new object without the `RESERVED_BODY_FIELDS`, each of which is warned about, or
+ * `undefined` where it is absent or is not an object. An empty one survives as an empty one.
+ */
+function parseExtraBody(report, path, value) {
+    if (absent(value)) {
+        return undefined;
+    }
+    if (!isRecord(value)) {
+        return void report.drop(path, 'must be an object');
+    }
+    const extraBody = {};
+    for (const [key, held] of Object.entries(value)) {
+        // The request is built around them and they would be overwritten anyway; better to say so on import.
+        if (RESERVED_BODY_FIELDS.includes(key)) {
+            report.drop(`${path}.${key}`, "is the loop's to set");
+        }
+        else {
+            extraBody[key] = held;
+        }
+    }
+    return extraBody;
+}
 /**
  * Reads the `prompt` array, part by part.
  *
@@ -429,6 +435,7 @@ function parseTasks(report, value) {
             model: report.string(`${path}.model`, held.model),
             endpoint: parseEndpoint(report, `${path}.endpoint`, held.endpoint),
             ...parseSampling(report, path, held),
+            extraBody: parseExtraBody(report, `${path}.extraBody`, held.extraBody),
         });
     }
     return tasks;
@@ -767,16 +774,18 @@ function mergeById(items, idOf) {
  * @param layers - The documents, weakest first. None is written to.
  * @param endpoint - The agent's merged endpoint. Read, not written to.
  * @returns The tasks whose merged `model` is not empty, keyed as the documents keyed them — one a
- * layer declined with `model: ""` is not among them.
+ * layer declined with `model: ""` is not among them. A task's `extraBody` merges by key.
  */
 function resolveTasks(layers, endpoint) {
     const merged = new Map();
     for (const layer of layers) {
         for (const [key, task] of Object.entries(layer.tasks ?? {})) {
+            const below = merged.get(key);
             merged.set(key, {
-                ...(merged.get(key) ?? {}),
+                ...below,
                 ...task,
-                endpoint: mergeLayers([merged.get(key)?.endpoint, task.endpoint]),
+                endpoint: mergeLayers([below?.endpoint, task.endpoint]),
+                extraBody: mergeLayers([below?.extraBody, task.extraBody]),
             });
         }
     }
@@ -793,6 +802,7 @@ function resolveTasks(layers, endpoint) {
             maxTokens: task.maxTokens,
             temperature: task.temperature,
             reasoningEffort: task.reasoningEffort,
+            extraBody: task.extraBody && said(task.extraBody) ? task.extraBody : undefined,
         });
     }
     return tasks;
@@ -896,8 +906,10 @@ export function resolveAgentSpec(layers) {
  * The property worth keeping is that **a redacted spec is still a valid spec** — it parses, it
  * resolves, and what comes back is the same agent pointed at the same servers, needing only the
  * credentials the importing host supplies itself. So a bundled server loses its `env` and its
- * `headers` and nothing else, and nothing outside `bundle` is touched: the format has no
- * credential field at any depth, which is the reason there is nothing else to strip.
+ * `headers` and nothing else, and nothing outside `bundle` is touched: those two are the only
+ * fields the format gives a credential. A server can still carry one where the format gives it no
+ * field — an `--api-key` among its `args`, a token in its `url` — and that is kept, because
+ * cutting it would point the agent at a different server. `findSpecSecrets` says where to look.
  */
 export function exportSpec(spec, { secrets = false } = {}) {
     if (secrets || !spec.bundle?.mcpServers) {
@@ -911,3 +923,160 @@ export function exportSpec(spec, { secrets = false } = {}) {
         },
     };
 }
+/** Why `findSpecSecrets` named a place. */
+export const SecretSign = {
+    /** A URL with a user or a password before its host. */
+    Userinfo: 'userinfo',
+    /** A URL query parameter whose name reads as a credential's. */
+    Query: 'query',
+    /** The value of a command-line flag, or of a header written as `Name: value`, so named. */
+    Flag: 'flag',
+    /** A value with the shape of a credential: a known key prefix, or `Bearer` and a token. */
+    Value: 'value',
+    /** A key of the server itself whose name reads as a credential's. */
+    Field: 'field',
+};
+/** A name that reads as a credential's: `api-key`, `TOKEN`, `Authorization`. */
+const SECRET_NAME = /key|token|secret|passw|auth|credential|bearer/i;
+/** A value shaped like a credential, whatever it is called. */
+const SECRET_VALUE = /^(sk-|pk-|rk-|ghp_|gho_|ghs_|github_pat_|glpat-|xox[abprs]-|AKIA)|\b(bearer|basic)\s+\S/i;
+/** What an absolute URL opens with. */
+const URL_SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** A header as one string, `Name: value`, as `--header` takes it. */
+const HEADER = /^([\w-]+):\s*(\S.*)$/;
+/** A flag carrying its own value, `--name=value`. */
+const FLAG_WITH_VALUE = /^(-{1,2}[^=\s]+)=(.+)$/;
+/** The keys of a server `findSpecSecrets` reads for itself, or `exportSpec` strips. */
+const SERVER_KEYS_READ = new Set(['id', 'slug', 'url', 'command', 'args', 'env', 'headers']);
+/**
+ * Whether a string is a credential written out, as against a reference to one.
+ *
+ * @param value - What a field, a flag or a parameter holds.
+ * @returns `false` for an empty string and for one holding a `${VAR}`, which names where the
+ * credential is and is not it.
+ */
+const writtenOut = (value) => value !== '' && VARIABLE.test(value) === false;
+/**
+ * Why a URL may carry a credential.
+ *
+ * @param text - A string, which need not be a URL.
+ * @returns `Userinfo`, `Query`, or `undefined` for a URL that shows neither and for a string
+ * that is not an absolute URL.
+ */
+function urlSign(text) {
+    if (URL_SCHEME.test(text) === false || URL.canParse(text) === false) {
+        return undefined;
+    }
+    const url = new URL(text);
+    if (writtenOut(url.username) || writtenOut(url.password)) {
+        return SecretSign.Userinfo;
+    }
+    for (const [name, value] of url.searchParams) {
+        if (SECRET_NAME.test(name) && writtenOut(value)) {
+            return SecretSign.Query;
+        }
+    }
+    return undefined;
+}
+/**
+ * Why one word of a command line may be a credential, read on its own.
+ *
+ * @param word - One argument.
+ * @returns A sign, or `undefined` for a word that shows none. A flag with no value of its own
+ * shows none here: `argumentSigns` reads the word after it.
+ */
+function wordSign(word) {
+    if (writtenOut(word) === false) {
+        return undefined;
+    }
+    const flag = FLAG_WITH_VALUE.exec(word);
+    if (flag?.[1] !== undefined && SECRET_NAME.test(flag[1])) {
+        return SecretSign.Flag;
+    }
+    const header = HEADER.exec(word);
+    if (header?.[1] !== undefined && SECRET_NAME.test(header[1])) {
+        return SecretSign.Flag;
+    }
+    // A flag's own value is read as a word too: `--url=https://user:pass@host`.
+    const value = flag?.[2] ?? word;
+    return SECRET_VALUE.test(value) ? SecretSign.Value : urlSign(value);
+}
+/**
+ * The words of a command line that may be credentials.
+ *
+ * @param words - The arguments in order. One that is not a string is passed over.
+ * @returns Each suspect word's index and its sign, in order, at most one sign a word.
+ *
+ * @remarks
+ * A flag named like a credential marks the word after it, unless that word is another flag.
+ */
+function argumentSigns(words) {
+    const signs = [];
+    let flagged = false;
+    for (const [index, word] of words.entries()) {
+        if (typeof word !== 'string') {
+            flagged = false;
+            continue;
+        }
+        const isFlag = word.startsWith('-');
+        const sign = flagged && isFlag === false && writtenOut(word) ? SecretSign.Flag : wordSign(word);
+        if (sign) {
+            signs.push([index, sign]);
+        }
+        flagged = isFlag && word.includes('=') === false && SECRET_NAME.test(word);
+    }
+    return signs;
+}
+/**
+ * The places one bundled server may carry a credential, outside its `env` and `headers`.
+ *
+ * @param server - The server as the document holds it.
+ * @param path - Where the server is, which each hint's path opens with.
+ * @returns The hints in the order `url`, `command`, `args`, then the server's other keys.
+ */
+function serverSecrets(server, path) {
+    const name = server.slug ?? server.id ?? '';
+    const hints = [];
+    const hint = (at, sign) => {
+        if (sign) {
+            hints.push({ path: `${path}.${at}`, server: name, sign });
+        }
+    };
+    if (typeof server.url === 'string') {
+        hint('url', urlSign(server.url));
+    }
+    if (typeof server.command === 'string') {
+        // A command written as one line is read as its words, and named once.
+        hint('command', argumentSigns(server.command.split(/\s+/))[0]?.[1]);
+    }
+    if (Array.isArray(server.args)) {
+        for (const [index, sign] of argumentSigns(server.args)) {
+            hint(`args[${index}]`, sign);
+        }
+    }
+    for (const [key, value] of Object.entries(server)) {
+        const empty = absent(value) || value === '' || (typeof value === 'string' && writtenOut(value) === false);
+        if (SERVER_KEYS_READ.has(key) === false && SECRET_NAME.test(key) && empty === false) {
+            hint(key, SecretSign.Field);
+        }
+    }
+    return hints;
+}
+/**
+ * Where a document's bundled servers may still carry a credential after `exportSpec`.
+ *
+ * @param spec - A document, exported or not: `env` and `headers` are not reported either way,
+ * since `exportSpec` strips them.
+ * @returns One hint for each suspect place, in document order, each naming where and why and
+ * none holding the value. Empty for a document with no bundle.
+ *
+ * @remarks
+ * A host calls this before it offers an export as safe to share, and warns with what comes back.
+ * It reads a server's `url`, its `command` and `args`, and the names of its other keys, and is a
+ * guess both ways: a credential in a positional argument with no telling prefix is missed, and a
+ * flag called `--keyboard` is named. A `${VAR}` is a reference and is never named.
+ */
+export function findSpecSecrets(spec) {
+    const servers = spec.bundle?.mcpServers ?? [];
+    return servers.flatMap((server, index) => serverSecrets(server, `bundle.mcpServers[${index}]`));
+}

package/dist/tools/preselect.d.ts

@@ -158,6 +158,8 @@ export interface PreselectOptions {
     temperature?: number;
     /** As `SideTaskOptions.reasoningEffort`: absent keeps the no-thinking hints. */
     reasoningEffort?: string;
+    /** As `SideTaskOptions.extraBody`: sampler fields the options cannot spell. */
+    extraBody?: Record<string, unknown>;
     /**
      * The most tools the choice may name.
      *
@@ -181,8 +183,8 @@ export interface PreselectOptions {
  * `toolSelectModel: settings.toolSelectModel || settings.model`.
  * @param catalog - The servers to choose from.
  * @param prompt - The request being planned for. Only its head is read; see `preselectInput`.
- * @param [options] - Cancellation, notices, the reply ceiling, the temperature and reasoning effort
- * as `ask` reads them, the cap the choice is held to, and whether to try the words first.
+ * @param [options] - Cancellation, notices, the reply ceiling, the temperature, reasoning effort and
+ * extra fields as `ask` reads them, the cap the choice is held to, and whether to try the words first.
  * @returns Names as the catalogue spells them, never more than `maxPerLoad`. Empty where `model` is
  * empty, the catalogue has no tools, the call failed, or its reply named nothing in the catalogue.
  *
@@ -198,4 +200,4 @@ export interface PreselectOptions {
  * starting now and starting in a few seconds. The words have to be clear about it; see
  * `preselectByKeywords` for what that means.
  */
-export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, temperature, reasoningEffort, maxPerLoad, keywords, }?: PreselectOptions): Promise<string[]>;
+export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, temperature, reasoningEffort, extraBody, maxPerLoad, keywords, }?: PreselectOptions): Promise<string[]>;

package/dist/tools/preselect.js

@@ -248,8 +248,8 @@ export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD
  * `toolSelectModel: settings.toolSelectModel || settings.model`.
  * @param catalog - The servers to choose from.
  * @param prompt - The request being planned for. Only its head is read; see `preselectInput`.
- * @param [options] - Cancellation, notices, the reply ceiling, the temperature and reasoning effort
- * as `ask` reads them, the cap the choice is held to, and whether to try the words first.
+ * @param [options] - Cancellation, notices, the reply ceiling, the temperature, reasoning effort and
+ * extra fields as `ask` reads them, the cap the choice is held to, and whether to try the words first.
  * @returns Names as the catalogue spells them, never more than `maxPerLoad`. Empty where `model` is
  * empty, the catalogue has no tools, the call failed, or its reply named nothing in the catalogue.
  *
@@ -265,7 +265,7 @@ export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD
  * starting now and starting in a few seconds. The words have to be clear about it; see
  * `preselectByKeywords` for what that means.
  */
-export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, temperature, reasoningEffort, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
+export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, temperature, reasoningEffort, extraBody, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
     if (!model || !catalog.some((server) => server.tools.length > 0)) {
         return [];
     }
@@ -285,6 +285,7 @@ export async function preselect(config, model, catalog, prompt, { signal, onNoti
         maxTokens,
         temperature,
         reasoningEffort,
+        extraBody,
         signal,
         onNotice,
     }), { onNotice, signal });

package/dist/turn/side-task.d.ts

@@ -55,6 +55,16 @@ export interface SideTaskOptions {
      * refused it by value, and `chat_template_kwargs` is left out of the request altogether.
      */
     reasoningEffort?: string;
+    /**
+     * Request fields these options cannot spell, as `ModelParams.extraBody` is for the main model:
+     * `top_p`, `top_k`, `min_p` and the penalties a model card asks for.
+     *
+     * @remarks
+     * Merged in after the ceiling, temperature and thinking fields, so it may override them, and
+     * before `askJson`'s `response_format`. `model`, `messages`, `stream` and `tools` are dropped. A
+     * field the endpoint refuses by name is latched for the model and the request sent again without it.
+     */
+    extraBody?: Record<string, unknown>;
     /** Abandons the call, usually because the run it supports has gone away. */
     signal?: AbortSignal;
     /**
@@ -97,6 +107,8 @@ export interface SideTask {
     temperature?: number;
     /** As `SideTaskOptions.reasoningEffort`: a level replaces the no-thinking hints. */
     reasoningEffort?: string;
+    /** As `SideTaskOptions.extraBody`: the sampler fields a model card asks for, sent as given. */
+    extraBody?: Record<string, unknown>;
 }
 /**
  * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
@@ -105,7 +117,7 @@ export interface SideTask {
  * @param model - The model to ask, usually smaller than the one running the work.
  * @param system - The instruction.
  * @param user - The input it applies to. Content parts where the model is being shown an image.
- * @param [options] - Reply ceiling, temperature, a reasoning effort, cancellation, notices.
+ * @param [options] - Reply ceiling, temperature, a reasoning effort, extra fields, cancellation, notices.
  * @returns The reply's content, trimmed. Where that is empty once the thinking is stripped, a
  * `reasoning_content` the server sent beside it, stripped the same way, or an empty string.
  */
@@ -219,6 +231,7 @@ export declare const listLines: (text: string, max: number, maxChars: number) =>
  * arrives through `options` without a host's call changing. What the task states wins over the
  * same field in `options`: the host's code is written once and the task is what an operator
  * configured over it, so a host passes its own ceiling as the value for a task that names none.
+ * `extraBody` is merged key by key, the task's keys winning, as layers merge it.
  * A setting the task leaves out and `options` does too is absent from the result, which is what
  * leaves it to the entry point's own default — 0.3, not the agent's temperature.
  *

package/dist/turn/side-task.js

@@ -1,5 +1,5 @@
 import { scoped } from '../core/scope.js';
-import { capabilitiesFor, ceilingAndTemperature, EFFORT_NONE, effortFor, modelCapabilitiesFor, negotiate, } from '../endpoint/capabilities.js';
+import { capabilitiesFor, ceilingAndTemperature, EFFORT_NONE, effortFor, extraFields, modelCapabilitiesFor, negotiate, } from '../endpoint/capabilities.js';
 import { endpointId, getClient, modelKey, resolveApiKey, sameUrl } from '../endpoint/client.js';
 import { relaxSchema, sanitizeSchema } from '../endpoint/schema-compat.js';
 import { errorMessage } from '../wire/errors.js';
@@ -68,7 +68,7 @@ export const resetHints = () => noHints().clear();
  * @param model - The model to ask, usually smaller than the one running the work.
  * @param system - The instruction.
  * @param user - The input it applies to. Content parts where the model is being shown an image.
- * @param [options] - Reply ceiling, temperature, a reasoning effort, cancellation, notices.
+ * @param [options] - Reply ceiling, temperature, a reasoning effort, extra fields, cancellation, notices.
  * @returns The reply's content, trimmed. Where that is empty once the thinking is stripped, a
  * `reasoning_content` the server sent beside it, stripped the same way, or an empty string.
  */
@@ -86,13 +86,14 @@ export function ask(config, model, system, user, options = {}) {
  * @param user - The input, sent as the user message as it was given.
  * @param options - A side task's options. A `reasoningEffort` that is a level leaves the
  * no-thinking hints out; absent, `""` or `"off"` sends them unless this pair has refused them.
+ * An `extraBody` goes out less the fields this model has refused by name.
  * @param [format] - Builds the extra body fields from the endpoint's capabilities and the model's.
  * Called on every send, so a re-send is built from what has been latched since. Absent adds none.
  * @returns The first choice's message as `answerOf` reads it, empty when there was no answer.
  * Throws what the request throws, except that a 400 or 422 `negotiate` did not answer, on a
  * request that carried the hints or an effort, is retried once without either.
  */
-async function complete(config, model, system, user, { maxTokens = 512, temperature = 0.3, reasoningEffort, signal, onNotice }, format) {
+async function complete(config, model, system, user, { maxTokens = 512, temperature = 0.3, reasoningEffort, extraBody, signal, onNotice }, format) {
     // The effort the caller chose, or empty where it chose none: `""` and `"off"` read as absent,
     // since off is what the hints below already ask for.
     const level = effortFor(undefined, reasoningEffort);
@@ -120,6 +121,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
             // Not gated on `hints`: a model that refuses `chat_template_kwargs` may still read the
             // effort, and the two latches would otherwise contradict each other.
             ...(sentEffort ? { reasoning_effort: asked } : {}),
+            ...extraFields(refused, extraBody),
             ...(format && refused ? format(supports, refused) : {}),
         }, { signal });
     };
@@ -131,6 +133,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
     const attempt = (hints, effort) => negotiate(supports, (latched, _produced, refused) => send(hints, effort, latched, refused), {
         model,
         onNotice,
+        droppable: Object.keys(extraBody ?? {}),
     });
     const key = modelKey(endpointId(config), model);
     // A chosen effort replaces the template hint rather than riding beside it: `enable_thinking:
@@ -333,6 +336,7 @@ export const listLines = (text, max, maxChars) => text
  * arrives through `options` without a host's call changing. What the task states wins over the
  * same field in `options`: the host's code is written once and the task is what an operator
  * configured over it, so a host passes its own ceiling as the value for a task that names none.
+ * `extraBody` is merged key by key, the task's keys winning, as layers merge it.
  * A setting the task leaves out and `options` does too is absent from the result, which is what
  * leaves it to the entry point's own default — 0.3, not the agent's temperature.
  *
@@ -356,6 +360,9 @@ export function taskCall(task, options, agent) {
     if (task.reasoningEffort !== undefined) {
         stated.reasoningEffort = task.reasoningEffort;
     }
+    if (task.extraBody !== undefined) {
+        stated.extraBody = { ...options?.extraBody, ...task.extraBody };
+    }
     return {
         endpoint: agent
             ? {

package/llms.txt

@@ -220,6 +220,7 @@ A JSON document that defines an agent, and the rules for reading one.
 - `EndpointSpec` (type) — Where a model is reached, and how long to wait for it.
 - `ExportSpecOptions` (type) — What `exportSpec` takes besides the document.
 - `exportSpec` — A document fit to leave the host: the same agent, with the secrets of its bundled servers gone.
+- `findSpecSecrets` — Where a document's bundled servers may still carry a credential after `exportSpec`.
 - `ModelSpec` (type) — Which model answers and how, including the request fields this interface cannot spell.
 - `ParsedSpec` (type) — What `parseSpec` hands back.
 - `ParseSpecOptions` (type) — What `parseSpec` takes besides the document.
@@ -232,6 +233,8 @@ A JSON document that defines an agent, and the rules for reading one.
 - `ResolvedTask` (type) — One side task, resolved: a model, and the endpoint it is reached through.
 - `RetrySpec` (type) — What to do about a request lost before the model produced anything.
 - `resolveAgentSpec` — Layers documents into the flat object the loop takes, weakest first.
+- `SecretHint` (type) — One place `findSpecSecrets` thinks a credential may be, and never the credential.
+- `SecretSign` — Any one of the reasons in `SecretSign`.
 - `SPEC_EVENTS` — Every event a hook may be bound to: `HOOK_EVENTS`, under the name a document's reader knows.
 - `SpecBundle` (type) — What an agent carries so it can travel whole: the definitions of the servers it names.
 - `SpecServer` (type) — A bundled MCP server, validated only as far as a round trip needs and otherwise passed through.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "4.1.0",
+  "version": "4.3.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",