import type { z } from "zod";
/**
 * Shared plumbing for jinn MCP tools (GRS-015): the tool/context contracts and the
 * thin gateway HTTP client every tool group builds on. Extracted from `server.ts`
 * so tool groups (`workflow-tools.ts`, later org/session groups) and the protocol
 * server can share them without an import cycle. `server.ts` re-exports everything
 * here, so existing importers are unaffected.
 *
 * The KISS guardrail stands: tools are deterministic HTTP wrappers over gateway
 * routes — no state, no scheduler, no LLM inside the tool server
 * (`reports/research/GRS-012d-0-typed-mcp-catalog.md` admission rule 1).
 */
/** Runtime context handed to every tool: how to reach the gateway. */
export interface JinnMcpContext {
    /** Base URL of the local gateway, e.g. `http://127.0.0.1:7777`. */
    gatewayUrl: string;
    /** Bearer token for privileged gateway endpoints. Undefined when the gateway
     *  runs with auth disabled (sandbox/QA). Read from inherited env, never argv. */
    token?: string;
    /** The calling session's id (GRS-017a identity seam — from the JINN_SESSION_ID
     *  env the gateway stamps on the per-session server spec). */
    callerSessionId?: string;
    /** Per-session capability minted by the gateway and stamped into the built-in
     *  jinn server env. Scoped write routes verify this value against
     *  callerSessionId before treating a tool-marked call as that session. */
    sessionCapability?: string;
    /** One immutable operation identity minted by handleMcpRequest for this
     * tools/call and forwarded only with a fully bound Session capability. */
    activityOperation?: {
        id: string;
        toolName: string;
    };
    /** Injectable fetch for tests; defaults to the global `fetch`. */
    fetchFn?: typeof fetch;
    /** Per-request budget in ms (default {@link GATEWAY_TIMEOUT_MS}); tests shrink it. */
    timeoutMs?: number;
}
/**
 * Default per-request budget (Codex GRS-015 finding 3 — a wedged gateway must
 * never hang a tool call forever). 30s, argued: the slowest tool-backed route is
 * POST …/run, which drives a full advancement pass INCLUDING a real engine-session
 * spawn — seconds on a loaded machine, never minutes — so 30s clears every honest
 * request with wide margin while still bounding a stalled socket within one
 * conversational beat. Everything else on the belt is a file-backed read/write
 * that answers in milliseconds.
 */
export declare const GATEWAY_TIMEOUT_MS = 30000;
/** A Jinn MCP tool. `handler` throws `JinnMcpToolError` (or any Error) on failure;
 *  the dispatcher converts that into an MCP `isError` tool result. */
export interface JinnMcpTool {
    name: string;
    description: string;
    inputSchema: {
        type: "object";
        properties: Record<string, unknown>;
        required?: string[];
        $defs?: Record<string, unknown>;
        additionalProperties?: boolean;
        [key: string]: unknown;
    };
    runtimeSchema?: z.ZodType;
    handler: (args: Record<string, unknown>, ctx: JinnMcpContext) => Promise<unknown>;
}
/** A tool-level failure surfaced to the engine as an MCP error result (not a
 *  protocol error) so the model can read and react to it. */
export declare class JinnMcpToolError extends Error {
}
export declare function assertBoundCaller(ctx: JinnMcpContext): asserts ctx is JinnMcpContext & {
    callerSessionId: string;
    sessionCapability: string;
};
/**
 * Send one gateway request and parse the JSON response (non-JSON bodies come back
 * as raw text). Never throws on HTTP status — callers decide what each status
 * means for their tool (a 400's structured validation errors are DATA the agent
 * self-corrects from, not an exception to swallow).
 *
 * TRANSPORT failures, however, are wrapped here (Codex GRS-015 findings 2+3):
 *   - the whole request INCLUDING the response body is raced against a timeout
 *     (Promise.race + AbortController — the race bounds even a fetch stub/impl
 *     that ignores the signal; the abort lets real implementations clean up);
 *   - a fetch rejection (ECONNREFUSED, socket reset mid-upload, DNS) is rethrown
 *     as a structured JinnMcpToolError carrying method/route/gateway context —
 *     a bare "fetch failed" never reaches the agent.
 */
export declare function gatewayRequest(ctx: JinnMcpContext, method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", pathAndQuery: string, body?: unknown): Promise<{
    status: number;
    body: unknown;
}>;
/** GET a gateway path (already including any query string) and parse JSON. */
export declare function gatewayGet(ctx: JinnMcpContext, pathAndQuery: string): Promise<{
    status: number;
    body: unknown;
}>;
//# sourceMappingURL=toolkit.d.ts.map