import type { FileStat, SandboxEnv, SandboxOrphanSettlement } from "./sandbox.js";
import type { ApprovalGrant, FabricActor, JsonObject, PackagedSkillDirectory, ResultValidator, ShellResult } from "./types.js";
export interface ToolContext {
    sandbox: SandboxEnv;
    /** Stable identity of the logical call, preserved across durable retries. */
    toolCallId?: string;
    /** Cancels provider work when the owning prompt, task, or submission is aborted. */
    signal?: AbortSignal;
    /** Runtime observer for a command that settles after cancellation returned. */
    onOrphanSettled?: (settlement: SandboxOrphanSettlement) => void | Promise<void>;
    /** Present only when this logical tool operation passed an approval gate. */
    approval?: ApprovalGrant;
    /** Authenticated actor requesting the operation, when execution crosses a server boundary. */
    actor?: FabricActor;
    /** Authenticated tenant selected for this operation. */
    tenantId?: string;
    /** Version or revision of the policy evaluated for this operation. */
    policyVersion?: string;
    /** Canonical digest of the tool input, suitable for approval and evidence correlation. */
    inputDigest?: string;
    /** Durable sub-step journal. Present only for tools declared `durable: true`. */
    step?: ToolStep;
    /** Runtime-scoped progress logger. Progress never becomes model context. */
    log?: ToolProgressLogger;
    /** Narrow runtime surface for hook-authored tools. */
    harness?: ToolHarness;
}
export interface ToolStep {
    /**
     * Persist the completed JSON value under a deterministic name. Recovery
     * replays a recorded value instead of invoking `run` again. The callback
     * remains at-least-once executable across a crash before its record lands.
     */
    do<T>(name: string, run: () => T | Promise<T>): Promise<T>;
}
export interface ToolProgressLogger {
    info(message: string, data?: JsonObject): void;
    warn(message: string, data?: JsonObject): void;
    error(message: string, data?: JsonObject): void;
}
export interface ToolHarness {
    readonly sandbox: SandboxEnv;
}
export interface ToolCall<TInput = unknown> {
    tool: string;
    input: TInput;
    id?: string;
}
export interface ToolCallResult<TOutput = unknown> {
    tool: string;
    input: unknown;
    output?: TOutput;
    /** Conditional tool definitions introduced at this result boundary. */
    addedToolNames?: string[];
    /** End the current agent turn after every call in the batch requests termination. */
    terminate?: boolean;
    error?: string;
    id?: string;
}
export type ToolEffect = "read" | "write" | "execute" | "none";
export interface ToolDef<TInput = unknown, TOutput = unknown> {
    name: string;
    /** Canonical policy identity when this public name is an alias (for example `save_file` -> `write`). */
    policyAlias?: string;
    description?: string;
    inputSchema?: unknown;
    /** Runtime output validator for hook-authored tools. */
    outputSchema?: unknown;
    metadata?: JsonObject & {
        effect?: ToolEffect;
    };
    /** Re-execute interrupted calls and replay completed `step.do()` records. */
    durable?: boolean;
    execute?(input: TInput, context?: ToolContext): Promise<TOutput> | TOutput;
}
export type HookToolContext<TInput, THarness extends boolean, TDurable extends boolean> = {
    data: TInput;
    toolCallId: string;
    signal?: AbortSignal;
    log: ToolProgressLogger;
} & (THarness extends true ? {
    harness: ToolHarness;
} : {
    harness?: never;
}) & (TDurable extends true ? {
    step: ToolStep;
} : {
    step?: never;
});
/** Hook-oriented tool declaration supported by `defineTool()` and `useTool()`. */
export interface HookToolDefinition<TInput = unknown, TOutput = unknown, THarness extends boolean = false, TDurable extends boolean = false> {
    name: string;
    description?: string;
    input?: unknown;
    output?: unknown;
    metadata?: JsonObject & {
        effect?: ToolEffect;
    };
    durable?: TDurable;
    harness?: THarness;
    run(context: HookToolContext<TInput, THarness, TDurable>): Promise<TOutput | {
        output?: TOutput;
        terminate?: boolean;
    }> | TOutput | {
        output?: TOutput;
        terminate?: boolean;
    };
}
/** Internal bridge preserving the V2 hook-tool envelope through portable runtimes. */
export declare function unwrapHookToolRunResult(value: unknown): {
    output: unknown;
    terminate: boolean;
};
export interface SecretRef {
    kind: "secret";
    name: string;
}
export type CommandEnvValue = string | SecretRef | undefined;
export interface Command<TInput = CommandToolInput> {
    name: string;
    description?: string;
    executable?: string;
    args?: string[];
    argsSchema?: unknown;
    buildArgs?: (input: TInput) => string[];
    env?: Record<string, CommandEnvValue>;
    cwd?: string;
    metadata?: JsonObject;
}
export interface CommandToolInput {
    args?: string[];
    cwd?: string;
    timeout?: number;
}
export interface CommandToolOptions {
    resolveSecret?: (ref: SecretRef) => string | undefined | Promise<string | undefined>;
    /** Defaults to fail: command secrets are runtime-only and must not be silently omitted. */
    onMissingSecret?: "fail";
}
export interface ReadFileInput {
    path: string;
    /** 1-indexed line at which to start. */
    offset?: number;
    /** Maximum lines to return before framework output limits. */
    limit?: number;
}
export interface ReadFileBufferInput {
    path: string;
}
export interface WriteFileInput {
    path: string;
    content: string | Uint8Array;
}
export interface StatInput {
    path: string;
}
export interface ReaddirInput {
    path: string;
}
export interface ExistsInput {
    path: string;
}
export interface MkdirInput {
    path: string;
    recursive?: boolean;
}
export interface RmInput {
    path: string;
    recursive?: boolean;
    force?: boolean;
}
export interface EditInput {
    path: string;
    oldText: string;
    newText: string;
    replaceAll?: boolean;
}
export interface BashInput {
    command: string;
    cwd?: string;
    env?: Record<string, string>;
    timeout?: number;
}
export interface GrepInput {
    pattern: string;
    path?: string;
    include?: string;
    ignoreCase?: boolean;
    literal?: boolean;
    maxMatches?: number;
}
export interface GrepMatch {
    path: string;
    line: number;
    text: string;
}
export interface GlobInput {
    pattern: string;
    cwd?: string;
    maxMatches?: number;
}
export interface ActivateSkillInput {
    name: string;
}
/** Public built-in tool limits; documentation and tests consume these constants. */
export declare const BUILTIN_READ_MAX_LINES = 2000;
export declare const BUILTIN_READ_MAX_BYTES: number;
export declare const BUILTIN_BASH_MAX_LINES = 2000;
export declare const BUILTIN_BASH_MAX_BYTES: number;
export declare const BUILTIN_GREP_MAX_MATCHES = 100;
export declare const BUILTIN_GREP_MAX_LINE_LENGTH = 500;
export declare const BUILTIN_GLOB_MAX_RESULTS = 1000;
export declare function secret(name: string): SecretRef;
export declare function defineCommand<TInput = CommandToolInput>(name: string, options?: Omit<Command<TInput>, "name">): Command<TInput>;
export declare function defineTool<TInput = unknown, TOutput = unknown>(tool: ToolDef<TInput, TOutput>): ToolDef<TInput, TOutput>;
export declare function defineTool<TInput = unknown, TOutput = unknown, THarness extends boolean = false, TDurable extends boolean = false>(tool: HookToolDefinition<TInput, TOutput, THarness, TDurable>): ToolDef<TInput, TOutput>;
export type BuiltinTool = ToolDef<ReadFileInput, string> | ToolDef<ReadFileBufferInput, Uint8Array> | ToolDef<WriteFileInput, void> | ToolDef<EditInput, void> | ToolDef<StatInput, FileStat> | ToolDef<ReaddirInput, string[]> | ToolDef<ExistsInput, boolean> | ToolDef<MkdirInput, void> | ToolDef<RmInput, void> | ToolDef<BashInput, ShellResult> | ToolDef<GrepInput, GrepMatch[]> | ToolDef<GlobInput, string[]>;
export type BuiltinFileTool = Exclude<BuiltinTool, ToolDef<BashInput, ShellResult> | ToolDef<GrepInput, GrepMatch[]> | ToolDef<GlobInput, string[]>>;
export declare function createCommandTools(commands: Command[], options?: CommandToolOptions): ToolDef<CommandToolInput, ShellResult>[];
export declare function createBuiltinTools(sandbox: SandboxEnv, packagedSkills?: Record<string, PackagedSkillDirectory>): BuiltinTool[];
export declare function createFileTools(sandbox: SandboxEnv, packagedSkills?: Record<string, PackagedSkillDirectory>): BuiltinFileTool[];
export declare function readFileTool(sandbox?: SandboxEnv, packagedSkills?: Record<string, PackagedSkillDirectory>): ToolDef<ReadFileInput, string>;
export declare function readFileBufferTool(sandbox?: SandboxEnv): ToolDef<ReadFileBufferInput, Uint8Array>;
export declare function writeFileTool(sandbox?: SandboxEnv): ToolDef<WriteFileInput, void>;
export declare function editFileTool(sandbox?: SandboxEnv): ToolDef<EditInput, void>;
export declare function statTool(sandbox?: SandboxEnv): ToolDef<StatInput, FileStat>;
export declare function readdirTool(sandbox?: SandboxEnv): ToolDef<ReaddirInput, string[]>;
export declare function existsTool(sandbox?: SandboxEnv): ToolDef<ExistsInput, boolean>;
export declare function mkdirTool(sandbox?: SandboxEnv): ToolDef<MkdirInput, void>;
export declare function rmTool(sandbox?: SandboxEnv): ToolDef<RmInput, void>;
export declare function bashTool(sandbox?: SandboxEnv): ToolDef<BashInput, ShellResult>;
export declare function grepTool(sandbox?: SandboxEnv): ToolDef<GrepInput, GrepMatch[]>;
export declare function globTool(sandbox?: SandboxEnv): ToolDef<GlobInput, string[]>;
export declare function createActivateSkillTool(skillNames: string[], activate: (name: string) => Promise<string>): ToolDef<ActivateSkillInput, string>;
export type ResultOutcome<TResult> = {
    type: "pending";
} | {
    type: "finished";
    value: TResult;
} | {
    type: "gave_up";
    reason: string;
};
export interface ResultToolBundle<TResult> {
    tools: ToolDef[];
    getOutcome(): ResultOutcome<TResult>;
}
/**
 * Produce the per-call `finish` and `give_up` tool pair for a given ResultValidator.
 *
 * - `finish`'s parameters are a generic JSON Schema object because we can't derive
 *   a precise schema from `ResultValidator`. The validator's `safeParse` handles
 *   actual validation.
 * - First successful `finish` (or `give_up`) call wins. Subsequent calls return
 *   an error tool result rather than throwing, to keep the conversation transcript
 *   natural.
 */
export declare function createResultTools<TResult>(validator: ResultValidator<TResult>): ResultToolBundle<TResult>;
export declare function shellQuote(value: string): string;
//# sourceMappingURL=tools.d.ts.map