@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/config/schema.d.ts

@@ -886,8 +886,6 @@ export interface PromptsConfig {
      * `insert` keeps the user's words; `replace` overwrites them.
      */
     insertMode: 'insert' | 'replace';
-    /** Whether the header's right-hand column may teach `^P prompts`. */
-    hint: boolean;
 }
 export declare const DEFAULT_PROMPTS_CONFIG: PromptsConfig;
 /**
@@ -899,6 +897,35 @@ export declare const DEFAULT_PROMPTS_CONFIG: PromptsConfig;
  * what the user has already typed into the composer.
  */
 export declare function clampPromptsConfig(raw: unknown): PromptsConfig;
+/**
+ * The task label's two switches (tui-shortcut-drawer-and-task-summary §4.8).
+ *
+ * ONE LEVEL DEEP, like every section beside it: `runConfigGet` splits on a single
+ * dot, so `taskSummary.enabled` resolves and a nested key would not (F-18).
+ *
+ * NEITHER KEY IS ABOUT THE LABEL'S CONTENT. `enabled` is the kill switch: off
+ * means no call is made and no cell is drawn. `fallback` decides what happens when
+ * the call cannot produce a label - the deterministic verbatim-prefix floor, or
+ * nothing at all. Both are BEHAVIOUR, which is why they are here rather than in
+ * `fast/limits.ts` (F-13).
+ */
+export interface TaskSummaryConfig {
+    /** The kill switch. `false` removes the header cell and the automatic call. */
+    enabled: boolean;
+    /** The deterministic verbatim-prefix floor (D-9). `false` = show nothing instead. */
+    fallback: boolean;
+}
+export declare const DEFAULT_TASK_SUMMARY_CONFIG: TaskSummaryConfig;
+/**
+ * THE single gate for every `taskSummary` read AND write, like the twelve sections
+ * above it.
+ *
+ * BOTH DEFAULTS ARE `true`, AND THE DIRECTION MATTERS: a corrupt or hand-edited
+ * section must not silently switch off a feature the user asked for, and - more
+ * importantly - it must not switch off the FLOOR, which is the only thing standing
+ * between a failed call and an empty header cell.
+ */
+export declare function clampTaskSummaryConfig(raw: unknown): TaskSummaryConfig;
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -1061,8 +1088,10 @@ export interface PersistedConfig {
     bash: BashConfig;
     /** Background jobs and bounded waiting. The ELEVENTH; scalars only (see JobsConfig). */
     jobs: JobsConfig;
-    /** Quick prompts. The TWELFTH; three scalars (see PromptsConfig). */
+    /** Quick prompts. The TWELFTH; two scalars (see PromptsConfig). */
     prompts: PromptsConfig;
+    /** The header task label. The THIRTEENTH; two scalars (see TaskSummaryConfig). */
+    taskSummary: TaskSummaryConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -1406,7 +1435,7 @@ export interface CliConfig {
      * scalars, one level deep.
      *
      * ON `CliConfig` AS WELL AS `PersistedConfig`, for the reason every section above
-     * records: `App` reads `cfg.prompts?.enabled` / `.hint` / `.insertMode` from a
+     * records: `App` reads `cfg.prompts?.enabled` / `.insertMode` from a
      * `CliConfig`, so a key added to the persisted shape alone would round-trip
      * through the `config` commands, appear in `config list`, and change nothing.
      *
@@ -1419,6 +1448,16 @@ export interface CliConfig {
      * disabled or destructive one.
      */
     prompts?: PromptsConfig;
+    /**
+     * The header task label (tui-shortcut-drawer-and-task-summary §4.8). The
+     * THIRTEENTH nested object; two scalars, one level deep.
+     *
+     * OPTIONAL HERE FOR THE SAME REASON AS `prompts` ABOVE: `CliConfig` is built by
+     * hand in many fixtures, and every reader uses `!== false`, so a missing section
+     * behaves exactly like a default session (label on, floor on) rather than like a
+     * switched-off feature.
+     */
+    taskSummary?: TaskSummaryConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -966,7 +966,6 @@ export function clampJobsConfig(raw) {
 export const DEFAULT_PROMPTS_CONFIG = {
     enabled: true,
     insertMode: 'insert',
-    hint: true,
 };
 const PROMPT_INSERT_MODES = ['insert', 'replace'];
 /**
@@ -985,7 +984,26 @@ export function clampPromptsConfig(raw) {
         insertMode: PROMPT_INSERT_MODES.includes(mode)
             ? mode
             : DEFAULT_PROMPTS_CONFIG.insertMode,
-        hint: bool(src.hint, DEFAULT_PROMPTS_CONFIG.hint),
+    };
+}
+export const DEFAULT_TASK_SUMMARY_CONFIG = {
+    enabled: true,
+    fallback: true,
+};
+/**
+ * THE single gate for every `taskSummary` read AND write, like the twelve sections
+ * above it.
+ *
+ * BOTH DEFAULTS ARE `true`, AND THE DIRECTION MATTERS: a corrupt or hand-edited
+ * section must not silently switch off a feature the user asked for, and - more
+ * importantly - it must not switch off the FLOOR, which is the only thing standing
+ * between a failed call and an empty header cell.
+ */
+export function clampTaskSummaryConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        enabled: bool(src.enabled, DEFAULT_TASK_SUMMARY_CONFIG.enabled),
+        fallback: bool(src.fallback, DEFAULT_TASK_SUMMARY_CONFIG.fallback),
     };
 }
 /**
@@ -1093,14 +1111,22 @@ export const DEFAULT_CONFIG = {
     // rather than quietly disabling something.
     jobs: DEFAULT_JOBS_CONFIG,
     // And one section later again, for the seventh time, and this one has BOTH
-    // failure directions at once: `prompts.enabled` and `prompts.hint` are `true` by
-    // default, so a `config.json` predating this feature would resolve them to
-    // `undefined` (falsy) and arrive with the key and its hint silently off - while
+    // failure directions at once: `prompts.enabled` is `true` by default, so a
+    // `config.json` predating this feature would resolve it to `undefined` (falsy)
+    // and arrive with the key silently off - while
     // `prompts.insertMode` would be `undefined`, which is neither `'insert'` nor
     // `'replace'` and would make `planPromptFill` fall through to its `replace`
     // branch. That branch discards the user's own words, so the miss would be a data
     // loss rather than a missing hint.
     prompts: DEFAULT_PROMPTS_CONFIG,
+    // And one section later again, for the eighth time - and this one has a silent
+    // DATA-LOSS-shaped miss: `taskSummary.enabled` and `.fallback` are both `true` by
+    // default, and `App` reads `cfg.taskSummary?.fallback !== false` at call time. A
+    // `config.json` predating this feature would resolve them to `undefined`, which
+    // happens to behave like the defaults in those two readers but NOT in
+    // `config list`, so the file would report a section it never wrote. One line
+    // here, like the seven above it.
+    taskSummary: DEFAULT_TASK_SUMMARY_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -17,7 +17,7 @@ import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerProfileSecrets, registerSecretsFrom } from '../logging/secret-registry.js';
 import { adaptLegacyConnectionPatch, ModelProfileConfigError, readModelSettingsDisk } from './model-profile-store.js';
 import { normalizeModelProfiles } from './model-profiles.js';
-import { clampBashConfig, clampJobsConfig, clampPromptsConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -200,6 +200,14 @@ export function normalizePersistedConfig(input) {
         // `'insert'` nor `'replace'`, so a fill into a non-empty draft would take the
         // branch that REPLACES what the user typed.
         prompts: clampPromptsConfig({ ...DEFAULT_CONFIG.prompts, ...(partial.prompts ?? {}) }),
+        // And the thirteenth, on the same line and for the same reason. Without it a
+        // `config.json` predating the header label resolves the whole section to
+        // `undefined`, and the two readers disagree: `App`'s `!== false` checks would
+        // treat it as ON while `config list` would report nothing at all.
+        taskSummary: clampTaskSummaryConfig({
+            ...DEFAULT_CONFIG.taskSummary,
+            ...(partial.taskSummary ?? {}),
+        }),
     };
 }
 /**
@@ -308,11 +316,18 @@ export function mergePersistedConfig(current, patch) {
         // user would never learn that their privacy switch had been turned back on.
         jobs: clampJobsConfig({ ...current.jobs, ...(patch.jobs ?? {}) }),
         // The twelfth section, and the seventh time this file records the same trap.
-        // `aragon config set prompts.hint false` sends `{ prompts: { hint: false } }`;
+        // `aragon config set prompts.insertMode replace` sends `{ prompts: { insertMode } }`;
         // without this line the shallow top-level spread REPLACES the section and
         // `insertMode` is written absent - which reads back as neither `'insert'` nor
         // `'replace'`, i.e. the next fill overwrites the user's own draft.
         prompts: clampPromptsConfig({ ...current.prompts, ...(patch.prompts ?? {}) }),
+        // The thirteenth section, and the eighth time this file records the same trap.
+        // `aragon config set taskSummary.fallback false` sends
+        // `{ taskSummary: { fallback: false } }`; without this line the shallow spread
+        // REPLACES the section and `enabled` is written absent - and the one direction
+        // that must never happen is a FAILED summary call landing on "show nothing"
+        // because a switch the user never touched defaulted away.
+        taskSummary: clampTaskSummaryConfig({ ...current.taskSummary, ...(patch.taskSummary ?? {}) }),
     };
     return merged;
 }

package/dist/diagnostics/doctor.d.ts

@@ -27,3 +27,12 @@ export interface DoctorOptions {
     probe?: boolean;
 }
 export declare function runDoctorChecks(flags: CliFlags, opts?: DoctorOptions): Promise<DoctorReport>;
+/**
+ * Is the optional JSON-Schema validator importable?
+ *
+ * ASKED ONCE, HERE, AND REUSED BY `aragon info` - because "how strict is my result
+ * schema validated" is a property of this MACHINE, not of the contract, and there must
+ * be exactly one answer to it. `createRequire().resolve()` rather than `import('ajv')`
+ * because `info` is synchronous: resolution is the question, not loading.
+ */
+export declare function hasAjvValidator(): boolean;

package/dist/diagnostics/doctor.js

@@ -10,6 +10,7 @@
  * the caller guess, which is the state this command exists to end.
  */
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import process from 'node:process';
 import { initProviders, ModelRegistry } from '@aragon-agent/core';
@@ -26,10 +27,43 @@ export async function runDoctorChecks(flags, opts = {}) {
     checks.push(checkProviderKey(config));
     checks.push(checkModel(config));
     checks.push(checkSessionsDir());
+    checks.push(checkValidationStrength());
     if (opts.probe)
         checks.push(await probeProvider(config));
     return { ok: checks.every((c) => c.verdict !== 'fail'), checks };
 }
+/**
+ * Is the optional JSON-Schema validator importable?
+ *
+ * ASKED ONCE, HERE, AND REUSED BY `aragon info` - because "how strict is my result
+ * schema validated" is a property of this MACHINE, not of the contract, and there must
+ * be exactly one answer to it. `createRequire().resolve()` rather than `import('ajv')`
+ * because `info` is synchronous: resolution is the question, not loading.
+ */
+export function hasAjvValidator() {
+    try {
+        createRequire(import.meta.url).resolve('ajv');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `ajv: present | absent` - a `pass`, never a `warn`.
+ *
+ * BOTH ANSWERS ARE CORRECT INSTALLS. `ajv` is an OPTIONAL dependency of Core, and its
+ * absence degrades validation honestly (the CLI's own belt still enforces `required`,
+ * recursive `properties`, `items` and `additionalProperties:false`). The check exists
+ * because the STRENGTH differs and nothing else in the product says so out loud.
+ */
+function checkValidationStrength() {
+    if (hasAjvValidator()) {
+        return pass('ajv', 'present: full JSON Schema keywords are enforced');
+    }
+    return pass('ajv', 'absent: required/properties/items/additionalProperties are still enforced by the ' +
+        'built-in validator; pattern/format/multipleOf are not');
+}
 function pass(name, detail) {
     return { name, verdict: 'pass', detail, remedy: '' };
 }

package/dist/diagnostics/info.d.ts

@@ -26,5 +26,76 @@ export interface ExecInfo {
     inputFormats: string[];
     permissionModes: string[];
     features: string[];
+    /**
+     * The bridge protocol, as data (headless-host-bridge section 4.6).
+     *
+     * THE POINT OF THIS BLOCK IS THAT A CALLER SHOULD NOT HAVE TO PROBE. The
+     * protocol version, which decision kinds exist, which tool names are gated and
+     * the limits it will be held to are all answered here, because the alternative
+     * is "send a frame and see whether an error comes back" - discovery by damage.
+     */
+    bridge: {
+        protocolVersion: number;
+        capabilities: string[];
+        decisionKinds: string[];
+        gatedTools: string[];
+        limits: {
+            maxCallerTools: number;
+            maxFrameBytes: number;
+            defaultDecisionTimeoutMs: number;
+        };
+        /**
+         * The per-request ceilings (headless-request-scope-and-typed-result section 4.6),
+         * BESIDE `limits` rather than inside it: `limits` is what one FRAME may carry,
+         * these bound one REQUEST. Both read their own `*_LIMITS` constant, so neither
+         * restates a number the enforcement does not use.
+         */
+        requestLimits: {
+            maxRequestTurns: number;
+            maxRequestTimeoutMs: number;
+        };
+        /**
+         * The thread ceilings (headless-threads-and-lifecycle-hooks section 4.6).
+         *
+         * A SIBLING OF `limits` / `requestLimits` RATHER THAN A MEMBER, because the three answer
+         * three different questions: what one frame carries, what one request may spend, and how
+         * many conversations this process can host.
+         */
+        threadLimits: {
+            maxOpenThreads: number;
+            defaultMaxOpenThreads: number;
+            defaultConcurrency: number;
+            maxThreadIdLength: number;
+        };
+        /** The hook ceilings and the four points, so a wrapper need not probe for them. */
+        hookLimits: {
+            maxHooks: number;
+            maxHooksPerPoint: number;
+            defaultTimeoutMs: number;
+            minTimeoutMs: number;
+            maxTimeoutMs: number;
+            allowModeMaxTimeoutMs: number;
+            points: string[];
+        };
+    };
+    /**
+     * The structured-result contract, as data (section 4.6).
+     *
+     * A NEW BLOCK, so an older consumer simply ignores it. It exists because the
+     * STRENGTH of the validation is machine-dependent (`ajv` is an optional dependency
+     * of Core), and "which strength am I on" is not something a caller can discover by
+     * sending a frame.
+     */
+    result: {
+        schemaBytes: number;
+        schemaDepth: number;
+        schemaRefs: number;
+        validationNodes: number;
+        maxViolations: number;
+        valueBytes: number;
+        defaultRepairTurns: number;
+        maxRepairTurns: number;
+        ajv: boolean;
+    };
 }
 export declare function buildInfo(flags: CliFlags, version: string): ExecInfo;

package/dist/diagnostics/info.js

@@ -15,8 +15,15 @@ import { readFileSync } from 'node:fs';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir, getUserDataDir } from '../config/app-paths.js';
 import { loadConfig, makeGetApiKey } from '../config/load.js';
-import { HOST_TOOL_NAMES } from '../tools/index.js';
-import { EXEC_SCHEMA_VERSION } from '../exec/events.js';
+import { CALLER_GATED_TOOLS, HOST_TOOL_NAMES } from '../tools/index.js';
+import { BRIDGE_CAPABILITIES, BRIDGE_PROTOCOL_VERSION } from '../exec/bridge/protocol.js';
+import { BRIDGE_LIMITS } from '../exec/bridge/limits.js';
+import { EXEC_SCHEMA_VERSION, execCapabilities } from '../exec/events.js';
+import { RESULT_LIMITS } from '../exec/result/limits.js';
+import { REQUEST_LIMITS } from '../exec/request/limits.js';
+import { THREAD_LIMITS } from '../exec/threads/limits.js';
+import { HOOK_LIMITS, HOOK_POINTS } from '../exec/hooks/limits.js';
+import { hasAjvValidator } from './doctor.js';
 /**
  * Everything this build can do, as names a wrapper can test for.
  *
@@ -52,11 +59,90 @@ export function buildInfo(flags, version) {
         // `HOST_TOOL_NAMES` means and exactly what `--allow-tool` validates against.
         tools: [...HOST_TOOL_NAMES],
         outputFormats: ['text', 'json', 'stream-json'],
-        inputFormats: ['text', 'stream-json'],
-        permissionModes: ['auto', 'plan', 'strict'],
-        features: [...FEATURES],
+        // THESE TWO LINES ARE THE ANSWER TO "WHAT DOES THIS BUILD ACCEPT", and this is
+        // the only place that answer exists in machine-readable form. Leaving them at
+        // three and three while `system/init` announces `bridge` and a run accepts
+        // `--permission-mode ask` would be two machine-readable answers that contradict
+        // each other, with nothing to tell a caller which one is true.
+        inputFormats: ['text', 'stream-json', 'bridge'],
+        permissionModes: ['auto', 'plan', 'strict', 'ask'],
+        features: buildFeatures(),
+        bridge: {
+            protocolVersion: BRIDGE_PROTOCOL_VERSION,
+            capabilities: [...BRIDGE_CAPABILITIES],
+            decisionKinds: ['tool', 'questions', 'plan', 'skill_install'],
+            // FROM THE CONSTANT THE GATE USES, so a caller never has to read the docs to
+            // learn that `skill_create` also asks it - and so this list cannot drift from
+            // the one enforcement is built on.
+            gatedTools: [...CALLER_GATED_TOOLS],
+            limits: {
+                maxCallerTools: BRIDGE_LIMITS.maxCallerTools,
+                maxFrameBytes: BRIDGE_LIMITS.maxFrameBytes,
+                defaultDecisionTimeoutMs: BRIDGE_LIMITS.defaultDecisionTimeoutMs,
+            },
+            requestLimits: {
+                maxRequestTurns: REQUEST_LIMITS.maxRequestTurns,
+                maxRequestTimeoutMs: REQUEST_LIMITS.maxRequestTimeoutMs,
+            },
+            // THREADS AND HOOKS (headless-threads-and-lifecycle-hooks section 4.6). REFERENCED
+            // from `THREAD_LIMITS` / `HOOK_LIMITS`, never restated: this block and the runtime's
+            // clamps have to be the same numbers, and a second literal is how they stop being.
+            threadLimits: {
+                maxOpenThreads: THREAD_LIMITS.maxOpenThreads,
+                defaultMaxOpenThreads: THREAD_LIMITS.defaultMaxOpenThreads,
+                defaultConcurrency: THREAD_LIMITS.defaultConcurrency,
+                maxThreadIdLength: THREAD_LIMITS.maxThreadIdLength,
+            },
+            hookLimits: {
+                maxHooks: HOOK_LIMITS.maxHooks,
+                maxHooksPerPoint: HOOK_LIMITS.maxHooksPerPoint,
+                defaultTimeoutMs: HOOK_LIMITS.defaultTimeoutMs,
+                minTimeoutMs: HOOK_LIMITS.minTimeoutMs,
+                maxTimeoutMs: HOOK_LIMITS.maxTimeoutMs,
+                allowModeMaxTimeoutMs: HOOK_LIMITS.allowModeMaxTimeoutMs,
+                points: [...HOOK_POINTS],
+            },
+        },
+        result: {
+            schemaBytes: RESULT_LIMITS.maxSchemaBytes,
+            schemaDepth: RESULT_LIMITS.maxSchemaDepth,
+            schemaRefs: RESULT_LIMITS.maxSchemaRefs,
+            validationNodes: RESULT_LIMITS.maxValidationNodes,
+            maxViolations: RESULT_LIMITS.maxViolations,
+            valueBytes: RESULT_LIMITS.maxResultValueBytes,
+            defaultRepairTurns: RESULT_LIMITS.defaultRepairTurns,
+            maxRepairTurns: RESULT_LIMITS.maxRepairTurns,
+            ajv: hasAjvValidator(),
+        },
     };
 }
+/**
+ * `features` = this build's own names PLUS the capability strings of one
+ * fully-featured run.
+ *
+ * DERIVED FROM `execCapabilities()`, NOT WRITTEN OUT BY HAND (review P0-4). The whole
+ * point of `info` is that a caller can read it BEFORE deciding which frames to send;
+ * if this list and `system/init.capabilities` were two hand-maintained literals, the
+ * first one to gain a member would silently make that strategy wrong.
+ * `{ bridge: true, structuredResult: true }` is the right argument here because this
+ * command answers "what can this build do", not "what did one run do".
+ */
+function buildFeatures() {
+    const features = [...FEATURES];
+    for (const capability of execCapabilities({
+        bridge: true,
+        structuredResult: true,
+        // THE SUPERSET ARGUMENT AGAIN: `info` answers "what can this build do", so the two new
+        // capabilities are declared here and only HERE - a run that does not open `--threads`
+        // still reports them in its own `init` as absent, from the same derivation point.
+        threads: true,
+        hooks: true,
+    })) {
+        if (!features.includes(capability))
+            features.push(capability);
+    }
+    return features;
+}
 /**
  * The installed `@aragon-agent/core` version, or `'unknown'`.
  *

package/dist/exec/bridge/caller-tools.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Caller-served tools: what a `tool_register` frame becomes, and how it runs.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * ## I-12: THESE TOOLS LIVE OUTSIDE THE HOST'S JURISDICTION, ON PURPOSE
+ *
+ * Everything below is built HERE and handed straight to the registry. That means a
+ * caller tool is NOT covered by the plan gate, NOT covered by a skill's
+ * `allowed-tools` ceiling, and has no job-notice tail - because it never passes
+ * through `createBuiltinTools`, which is where all three wrappers are applied.
+ *
+ * This is a decision, not an oversight, and it is written down because the next
+ * person to read this file will otherwise assume the wrappers are there. The
+ * defences that DO apply are: plan mode refuses the whole `tool_register` frame
+ * (`plan_mode_read_only`), and a caller tool may not shadow any host, team or
+ * skill tool name (`caller_tool_conflict`). Both are refusals at registration
+ * time, which is the only moment this module can still see the caller's intent.
+ *
+ * ## Why `validateCallerTools` REFUSES WHOLE FRAMES
+ *
+ * A partially accepted registration would leave the registry holding a mixture of
+ * two declarations - the caller's old `db_query` and its new `db_write` - with
+ * nothing anywhere saying which of the two the model is now using. The caller's
+ * natural recovery ("just send the fixed list again") only works if the previous
+ * frame left no trace, so every check below runs BEFORE the first write.
+ */
+import { type AgentTool, type ToolResult } from '@aragon-agent/core';
+import type { BridgeServer } from './server.js';
+import type { CallerToolSpec } from './protocol.js';
+export interface CallerToolValidation {
+    ok: true;
+    specs: CallerToolSpec[];
+    /** Non-fatal notes for `ack.warnings` - a clipped description, so far. */
+    warnings: string[];
+}
+export interface CallerToolRejection {
+    ok: false;
+    code: string;
+    message: string;
+}
+export type CallerToolValidationResult = CallerToolValidation | CallerToolRejection;
+/**
+ * Narrow whatever arrived in `tool_register.tools` into usable specs.
+ *
+ * `reserved` is a PARAMETER rather than an import so the caller decides what a
+ * name may not collide with - and so the test can hand over a two-name set instead
+ * of modelling the whole host.
+ */
+export declare function validateCallerTools(rawTools: readonly unknown[], reserved: ReadonlySet<string>): CallerToolValidationResult;
+/**
+ * The effective ceiling for one call: `min(spec.timeoutMs, --caller-tool-timeout)`.
+ *
+ * MIN, NOT MAX, because both numbers are ceilings on the same thing: the caller's
+ * own declaration is a promise about its implementation ("this query takes at most
+ * 20 s") and the flag is the run's budget. Taking the larger of the two would let
+ * a declared 600 s override a 10 s budget.
+ */
+export declare function resolveCallerToolTimeout(spec: CallerToolSpec | undefined, defaultTimeoutMs: number): number;
+/**
+ * Turn specs into `AgentTool`s that round-trip through the server.
+ *
+ * EVERY PATH RETURNS A `ToolResult`. Nothing here throws: `ToolExecutor` would
+ * convert a throw into an error result of its own wording, and that wording says
+ * nothing about which of the four refusals happened.
+ */
+export declare function createCallerTools(specs: readonly CallerToolSpec[], server: BridgeServer, defaultTimeoutMs: number): AgentTool[];
+/**
+ * Coerce a `tool_result.content` into text, or refuse it.
+ *
+ * TEXT ONLY, THIS ROUND. An image part would need `imageResult` and the provider's
+ * multimodal path, which is a separate feature with its own budget questions; a
+ * half-support that silently dropped the image would be worse than a named
+ * refusal (`bridge_unsupported_content`).
+ */
+export declare function contentToText(content: unknown): {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+};
+/**
+ * Clip to `maxCallerToolResultBytes` and SAY SO.
+ *
+ * The footer is not decoration: `ToolExecutor` already clips model-visible output
+ * at its own ceiling, so a silent second clip here would look like the tool
+ * returned less than it did, and the model would draw conclusions from a truncated
+ * table without being told it was truncated.
+ */
+export declare function clipCallerToolText(text: string): string;
+/** Build the result a `tool_result` frame becomes, or a named refusal. */
+export declare function callerToolResult(content: unknown, isError: boolean): ToolResult;
+/** Thrown only so `server.ts` can map it to one error code in one place. */
+export declare class UnsupportedContentError extends Error {
+    constructor();
+}