import type { LoggerFn } from './logger';
/**
 * Mirrors the `conversation_id` session handle into `structuredContent`, in two
 * halves that must stay in that order:
 *
 *   1. declare `_mcp_instructions` on the tool's advertised `outputSchema`
 *   2. write it into the result's `structuredContent`
 *
 * Needed because clients that read `structuredContent` — which they do whenever
 * a tool declares an `outputSchema` — never see the `content` text block that
 * carries the handle (ADR-0004).
 *
 * The declaration is what makes the write safe. The MCP client ajv-validates
 * `structuredContent` against the schema from `tools/list`, and
 * `zod-to-json-schema` emits `additionalProperties: false` for a plain
 * `z.object`, so an undeclared key is not ignored — it fails the entire tool
 * result. Only tools that got the declaration are ever written to.
 */
export declare const MCP_INSTRUCTIONS_KEY = "_mcp_instructions";
export interface OutputInstructionsInjectableTool {
    name?: string;
    outputSchema?: unknown;
    [key: string]: unknown;
}
/**
 * True when we can safely declare {@link MCP_INSTRUCTIONS_KEY} on this tool's
 * advertised output schema.
 *
 * Requires a plain-object schema we can extend. A tool with no `outputSchema`
 * has nothing to mirror into and keeps working through `content`; a composed
 * schema (`oneOf`/`allOf`/`anyOf`/`$ref`) has no single `properties` bag to add
 * to. Both stay content-only, matching the policy on the input side.
 */
export declare function canDeclareOutputInstructions(outputSchema: unknown): boolean;
/**
 * Returns a copy of the tool with an optional {@link MCP_INSTRUCTIONS_KEY}
 * property added to its output schema, or the tool untouched when it has no
 * output schema to extend.
 *
 * The property is never added to `required` — a result without it must stay
 * valid, since every tool result predating this change lacks it.
 */
export declare function addInstructionsToOutputSchema<TTool extends OutputInstructionsInjectableTool>(tool: TTool, logger?: LoggerFn): TTool;
/**
 * Declares {@link MCP_INSTRUCTIONS_KEY} across a tool listing. Tools without an
 * output schema, and tools whose schema we cannot extend, pass through unchanged.
 */
export declare function addInstructionsToOutputSchemas<TTool extends OutputInstructionsInjectableTool>(tools: TTool[], logger?: LoggerFn): TTool[];
export interface ConversationInstructions {
    conversation_id: string;
}
/** The payload mirrored into `structuredContent` for a tool we declared the key on. */
export declare function buildConversationInstructions(conversationId: string): ConversationInstructions;
/**
 * Adds {@link MCP_INSTRUCTIONS_KEY} to a result's `structuredContent`, which is
 * where clients look once a tool declares an `outputSchema` — the `content` text
 * block carrying the session handle is invisible to them.
 *
 * Unlike the text block, this rides *every* response rather than only the one
 * that minted the session handle, so an agent that drops it can read it back.
 *
 * Returns the result untouched when there is no plain-object `structuredContent`
 * to extend, or when the tool already produced its own key — customer data wins.
 * Never mutates the input.
 */
export declare function mirrorInstructionsIntoStructuredContent(result: unknown, conversationId: string): unknown;
//# sourceMappingURL=output-instructions.d.ts.map