@cubicecho/agent-core 4.0.0 → 4.2.0

package/dist/{spec.js → spec/spec.js}

@@ -1,6 +1,6 @@
-import { RESERVED_BODY_FIELDS, ToolDiscovery } from './config.js';
-import { isRecord } from './guards.js';
-import { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hook-events.js';
+import { RESERVED_BODY_FIELDS, ToolDiscovery } from '../core/config.js';
+import { isRecord } from '../core/guards.js';
+import { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from '../hooks/hook-events.js';
 /**
  * A JSON document that defines an agent, and the rules for reading one.
  *
@@ -896,8 +896,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 +913,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/{preselect.d.ts → tools/preselect.d.ts}

@@ -1,6 +1,6 @@
-import type { OnNotice } from './capabilities.ts';
+import type { Endpoint } from '../core/config.ts';
+import type { OnNotice } from '../endpoint/capabilities.ts';
 import type { CatalogServer } from './catalog.ts';
-import type { Endpoint } from './config.ts';
 /**
  * The system prompt a preselector is given, holding it to the cap its answer will be held to.
  *
@@ -176,8 +176,9 @@ export interface PreselectOptions {
  * The tools a request is likely to need, picked by a small model before the run starts, or none.
  *
  * @param config - The endpoint the preselector is reached through.
- * @param model - The preselector. An empty name picks nothing, which is what `toolSelectModel`
- * means by empty.
+ * @param model - The preselector. An empty name picks nothing, silently, which is what
+ * `toolSelectModel` means by empty: a host whose settings read `""` as "the run's model" passes
+ * `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

package/dist/{preselect.js → tools/preselect.js}

@@ -1,7 +1,7 @@
-import { byCodeUnit, counted, isRecord } from './guards.js';
-import { askJson, tryAsk } from './side-task.js';
+import { byCodeUnit, counted, isRecord } from '../core/guards.js';
+import { askJson, tryAsk } from '../turn/side-task.js';
+import { SchemaType } from '../wire/wire.js';
 import { catalogList, expandNames, MAX_PER_LOAD } from './tool-loading.js';
-import { SchemaType } from './wire.js';
 /**
  * Choosing a run's tools before it starts, from the request and the catalogue's names.
  *
@@ -243,8 +243,9 @@ export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD
  * The tools a request is likely to need, picked by a small model before the run starts, or none.
  *
  * @param config - The endpoint the preselector is reached through.
- * @param model - The preselector. An empty name picks nothing, which is what `toolSelectModel`
- * means by empty.
+ * @param model - The preselector. An empty name picks nothing, silently, which is what
+ * `toolSelectModel` means by empty: a host whose settings read `""` as "the run's model" passes
+ * `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

package/dist/{tool-loading.js → tools/tool-loading.js}

@@ -1,6 +1,6 @@
-import { byCodeUnit, isRecord } from './guards.js';
-import { ARGUMENT_PREVIEW_CHARS } from './tool-calls.js';
-import { FUNCTION_TOOL, SchemaType } from './wire.js';
+import { byCodeUnit, isRecord } from '../core/guards.js';
+import { ARGUMENT_PREVIEW_CHARS } from '../wire/tool-calls.js';
+import { FUNCTION_TOOL, SchemaType } from '../wire/wire.js';
 /**
  * On-demand tool loading.
  *

package/dist/{continuation.d.ts → turn/continuation.d.ts}

@@ -1,7 +1,7 @@
 import type OpenAI from 'openai';
-import { type Capabilities } from './capabilities.ts';
+import { type Capabilities } from '../endpoint/capabilities.ts';
+import { type Turn } from '../wire/stream.ts';
 import { type RequestBuilder, type RunTurnOptions } from './run-turn.ts';
-import { type Turn } from './stream.ts';
 /**
  * Picking up an answer the token ceiling cut off, instead of keeping half of it.
  *

package/dist/{continuation.js → turn/continuation.js}

@@ -1,9 +1,9 @@
-import { modelCapabilitiesFor } from './capabilities.js';
-import { errorMessage } from './errors.js';
-import { ContextOverflow, refusesRequest } from './retry.js';
+import { modelCapabilitiesFor } from '../endpoint/capabilities.js';
+import { errorMessage } from '../wire/errors.js';
+import { ContextOverflow, refusesRequest } from '../wire/retry.js';
+import { addCounts } from '../wire/stream.js';
+import { FinishReason, Role } from '../wire/wire.js';
 import { modelLabel, runTurn } from './run-turn.js';
-import { addCounts } from './stream.js';
-import { FinishReason, Role } from './wire.js';
 /**
  * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
  * and no tool call in it.

package/dist/{run-turn.d.ts → turn/run-turn.d.ts}

@@ -1,6 +1,6 @@
 import type OpenAI from 'openai';
-import { type Capabilities, type ModelCapabilities, type OnNotice } from './capabilities.ts';
-import { type StreamTurnOptions, type Turn } from './stream.ts';
+import { type Capabilities, type ModelCapabilities, type OnNotice } from '../endpoint/capabilities.ts';
+import { type StreamTurnOptions, type Turn } from '../wire/stream.ts';
 /**
  * One turn, given as many attempts as the caller allows.
  *

package/dist/{run-turn.js → turn/run-turn.js}

@@ -1,10 +1,10 @@
-import { calibrate, charsPerTokenFor } from './calibration.js';
-import { negotiate } from './capabilities.js';
-import { errorMessage } from './errors.js';
-import { MS_PER_SECOND } from './platform.js';
-import { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, SMALLEST_LIKELY_WINDOW, sleep, } from './retry.js';
-import { streamTurn } from './stream.js';
-import { compact, requestTokens } from './tokens.js';
+import { MS_PER_SECOND } from '../core/platform.js';
+import { calibrate, charsPerTokenFor } from '../endpoint/calibration.js';
+import { negotiate } from '../endpoint/capabilities.js';
+import { errorMessage } from '../wire/errors.js';
+import { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, SMALLEST_LIKELY_WINDOW, sleep, } from '../wire/retry.js';
+import { streamTurn } from '../wire/stream.js';
+import { compact, requestTokens } from '../wire/tokens.js';
 /**
  * What a notice calls the model, where the caller did not say which one it is.
  *

package/dist/{side-task.d.ts → turn/side-task.d.ts}

@@ -1,6 +1,6 @@
 import type OpenAI from 'openai';
-import { type OnNotice } from './capabilities.ts';
-import type { Endpoint, EndpointIdentity } from './config.ts';
+import type { Endpoint, EndpointIdentity } from '../core/config.ts';
+import { type OnNotice } from '../endpoint/capabilities.ts';
 /**
  * The pairs that refused the hints, the live set, for `exportCapabilities` and
  * `importCapabilities`.

package/dist/{side-task.js → turn/side-task.js}

@@ -1,12 +1,12 @@
-import { capabilitiesFor, ceilingAndTemperature, EFFORT_NONE, effortFor, modelCapabilitiesFor, negotiate, } from './capabilities.js';
-import { endpointId, getClient, modelKey, resolveApiKey, sameUrl } from './client.js';
-import { errorMessage } from './errors.js';
-import { isAbort, refusesRequest } from './retry.js';
-import { relaxSchema, sanitizeSchema } from './schema-compat.js';
-import { scoped } from './scope.js';
-import { stripThinking } from './thinking.js';
-import { CODE_FENCE, looseJson } from './tool-calls.js';
-import { JSON_SCHEMA_FORMAT, Role } from './wire.js';
+import { scoped } from '../core/scope.js';
+import { capabilitiesFor, ceilingAndTemperature, EFFORT_NONE, effortFor, 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';
+import { isAbort, refusesRequest } from '../wire/retry.js';
+import { stripThinking } from '../wire/thinking.js';
+import { CODE_FENCE, looseJson } from '../wire/tool-calls.js';
+import { JSON_SCHEMA_FORMAT, Role } from '../wire/wire.js';
 /**
  * One-shot calls that support a run without being one: picking tools, naming a session,
  * summarising a transcript, proposing follow-ups. They share a shape — small prompt, short

package/dist/{errors.d.ts → wire/errors.d.ts}

@@ -38,6 +38,8 @@ export interface AgentLoopFailure {
     loaded: string[];
     /** The tools the model had called, `load_tools` excluded. */
     used: string[];
+    /** The shortlist the run opened with, as the result's `preselected` would have said it. */
+    preselected: string[];
 }
 /**
  * What `runAgentLoop` throws, carrying the run as it stood and what was caught as `cause`.
@@ -55,6 +57,7 @@ export declare class AgentLoopError extends Error implements AgentLoopFailure {
     readonly toolCalls: ToolCallOutcome[];
     readonly loaded: string[];
     readonly used: string[];
+    readonly preselected: string[];
     /**
      * @param message - What went wrong — the cause's own message, where there is a cause.
      * @param run - The run as it stood. Held, not copied.
@@ -87,6 +90,7 @@ export declare class AgentLoopOverflow extends ContextOverflow implements AgentL
     readonly toolCalls: ToolCallOutcome[];
     readonly loaded: string[];
     readonly used: string[];
+    readonly preselected: string[];
     /**
      * @param message - The overflow's own message.
      * @param run - The run as it stood. Held, not copied.

package/dist/{errors.js → wire/errors.js}

@@ -28,6 +28,7 @@ export class AgentLoopError extends Error {
     toolCalls;
     loaded;
     used;
+    preselected;
     /**
      * @param message - What went wrong — the cause's own message, where there is a cause.
      * @param run - The run as it stood. Held, not copied.
@@ -40,6 +41,7 @@ export class AgentLoopError extends Error {
         this.toolCalls = run.toolCalls;
         this.loaded = run.loaded;
         this.used = run.used;
+        this.preselected = run.preselected;
     }
 }
 /**
@@ -67,6 +69,7 @@ export class AgentLoopOverflow extends ContextOverflow {
     toolCalls;
     loaded;
     used;
+    preselected;
     /**
      * @param message - The overflow's own message.
      * @param run - The run as it stood. Held, not copied.
@@ -79,6 +82,7 @@ export class AgentLoopOverflow extends ContextOverflow {
         this.toolCalls = run.toolCalls;
         this.loaded = run.loaded;
         this.used = run.used;
+        this.preselected = run.preselected;
     }
 }
 /**

package/dist/{retry.js → wire/retry.js}

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { ABORT_ERROR, ABORT_EVENT } from './platform.js';
+import { ABORT_ERROR, ABORT_EVENT } from '../core/platform.js';
 import { HttpStatus } from './wire.js';
 /**
  * Everything about a request failing that is not about what the request said.

package/dist/{stream.js → wire/stream.js}

@@ -1,4 +1,4 @@
-import { MS_PER_SECOND } from './platform.js';
+import { MS_PER_SECOND } from '../core/platform.js';
 import { EndpointSilent } from './retry.js';
 import { DEFAULT_FENCES, FenceSplitter, SPLIT_REASONING } from './thinking.js';
 import { FUNCTION_TOOL } from './wire.js';

package/dist/{tool-calls.js → wire/tool-calls.js}

@@ -1,4 +1,4 @@
-import { isRecord } from './guards.js';
+import { isRecord } from '../core/guards.js';
 import { THINK_FENCE } from './thinking.js';
 import { FinishReason, FUNCTION_TOOL } from './wire.js';
 /**