/**
 * Types for the delegateTask code execution feature.
 *
 * This module defines the interfaces and schemas used when an AI agent
 * delegates a task to a subordinate agent process running in a sandboxed
 * environment. The delegated process has access to tools, can read/write
 * files, and streams progress back to the caller.
 */
import { z } from 'zod';
/**
 * Configures resource limits for a single delegateTask invocation.
 * Defaults are intentionally conservative to prevent runaway costs.
 */
export interface ExecutionLimits {
    /** Maximum spend in USD for a single task (default: 10.00) */
    maxBudgetPerTask?: number;
    /** Maximum agent turns before the task is forcibly stopped. Omit to use CLI default. */
    maxTurnsPerTask?: number;
    /** Maximum wall-clock time expressed as a duration string, e.g. "1h" (default: "1h") */
    maxDurationPerTask?: string;
    /**
     * Model to use for the sandbox agent, e.g. "claude-sonnet-4-6".
     * If omitted, the sandbox CLI picks its default model.
     */
    model?: string;
}
/**
 * A file to provide to the delegated agent process as part of the task
 * context.  Files are written into the sandbox before execution begins.
 */
export interface DelegateTaskInputFile {
    /** Relative path under which the file will be written inside the sandbox */
    name: string;
    /** Raw file content — either a UTF-8 string or a binary Buffer. Required if fileId is not set. */
    content?: string | Buffer;
    /**
     * Platform file ID. When set, the framework resolves the file content
     * from the platform's file storage before sending to the sandbox.
     * Either content or fileId must be provided.
     */
    fileId?: string;
    /** Content encoding; defaults to 'utf-8' */
    encoding?: 'utf-8' | 'base64';
}
/**
 * A file produced by the delegated agent process and returned to the caller.
 * Which files are returned is controlled by `outputFilePatterns` in
 * {@link DelegateTaskOptions}.
 */
export interface DelegateTaskOutputFile {
    /** Relative path of the file within the sandbox */
    path: string;
    /** File content, already decoded to a string */
    content: string;
    /** Encoding that was used to transfer the content (typically "utf-8") */
    encoding: string;
}
/**
 * Options passed to a `delegateTask` call.  All fields except `prompt` are
 * optional and fall back to platform defaults or the agent's
 * {@link ExecutionLimits}.
 */
export interface DelegateTaskOptions {
    /** The instruction to pass to the subordinate agent process */
    prompt: string;
    /** Files to make available inside the sandbox before the task starts */
    inputFiles?: DelegateTaskInputFile[];
    /**
     * Glob patterns (relative to the sandbox workspace root) that identify which
     * files should be captured and returned in {@link DelegateTaskResult.outputFiles}.
     */
    outputFilePatterns?: string[];
    /** Maximum number of agent turns; overrides the agent-level limit */
    maxTurns?: number;
    /** Maximum spend in USD; overrides the agent-level limit */
    maxBudget?: number;
    /** Maximum wall-clock duration string, e.g. "30m"; overrides the agent-level limit */
    timeout?: string;
    /** When true the call returns a {@link DelegateTaskStream} instead of awaiting a full result */
    stream?: boolean;
    /**
     * Opaque session identifier.  Pass the value received in a previous result to
     * resume a task within the same sandbox session.
     */
    sessionId?: string;
    /**
     * Additional environment variables injected into the sandbox.
     * Variables listed in {@link RESERVED_ENV_VARS} are silently ignored.
     */
    env?: Record<string, string>;
    /** Model override for the sandbox agent, e.g. "claude-sonnet-4-6". Overrides agent-level model. */
    model?: string;
}
/** Token and cost accounting for a completed delegated task */
export interface DelegateTaskUsage {
    /** Total input tokens consumed across all turns */
    inputTokens: number;
    /** Total output tokens produced across all turns */
    outputTokens: number;
    /** Approximate cost in USD */
    cost: number;
}
/**
 * The final result returned once a delegated task completes (or fails).
 */
export interface DelegateTaskResult {
    /** The final text response produced by the subordinate agent process */
    response: string;
    /** Files captured according to the `outputFilePatterns` option */
    outputFiles: DelegateTaskOutputFile[];
    /** Aggregated token usage and cost */
    usage: DelegateTaskUsage;
    /**
     * Exit code of the subordinate process; 0 indicates success, non-zero
     * indicates an error or an aborted task.
     */
    exitCode: number;
    /** The sandbox session identifier that can be passed to a subsequent call to resume */
    sessionId: string;
}
/** A text chunk emitted while the subordinate process is generating a response */
export interface DelegateTaskStreamTextEvent {
    type: 'text';
    text: string;
}
/** Notification that the subordinate process is invoking a tool */
export interface DelegateTaskStreamToolUseEvent {
    type: 'tool_use';
    toolName: string;
    toolInput: Record<string, unknown>;
}
/** The result returned by a tool call in the subordinate process */
export interface DelegateTaskStreamToolResultEvent {
    type: 'tool_result';
    toolName: string;
    result: unknown;
}
/** A fatal or non-fatal error raised during execution */
export interface DelegateTaskStreamErrorEvent {
    type: 'error';
    message: string;
    code?: string;
}
/** A status update about the overall execution progress */
export interface DelegateTaskStreamStatusEvent {
    type: 'status';
    status: 'starting' | 'running' | 'finishing' | 'done';
    message?: string;
}
/** Union of all events that can appear in a {@link DelegateTaskStream} */
export type DelegateTaskStreamEvent = DelegateTaskStreamTextEvent | DelegateTaskStreamToolUseEvent | DelegateTaskStreamToolResultEvent | DelegateTaskStreamErrorEvent | DelegateTaskStreamStatusEvent;
/**
 * An async iterable stream of {@link DelegateTaskStreamEvent} values.
 * Consuming the stream drives the subordinate process forward; the final
 * {@link DelegateTaskResult} is available via the `result` promise once the
 * stream is exhausted.
 */
export interface DelegateTaskStream extends AsyncIterable<DelegateTaskStreamEvent> {
    /** Resolves to the complete result after the stream has ended */
    result: Promise<DelegateTaskResult>;
}
/**
 * Sent to the sandbox bridge to prepare (or resume) a session before code
 * execution starts. Must include all context for CLAUDE.md, skills, etc.
 */
export interface PrepareSessionRequest {
    appId: string;
    agentName: string;
    /** Opaque session identifier; omit to start a new session */
    sessionId?: string;
    /** Files to write into the sandbox inputs/ directory */
    inputFiles?: Array<{
        name: string;
        content: string;
        encoding: string;
    }>;
    /** Session-level CLAUDE.md content */
    claudeMdContent: string;
    /** Workspace-level CLAUDE.md content */
    workspaceClaudeMdContent: string;
    /** .claude/settings.json content (MCP servers config) */
    settingsJsonContent: string;
    /** Skill files to write into .claude/skills/ */
    skillFiles?: Array<{
        name: string;
        content: string;
    }>;
}
/** Response from the sandbox bridge after session preparation */
export interface PrepareSessionResponse {
    /** The session identifier to use in subsequent requests */
    sessionId: string;
    /** Absolute path to the session directory in the sandbox */
    sessionPath: string;
    /** Absolute path to the agent sandbox working directory */
    workDir: string;
}
/**
 * Sent to the sandbox bridge to execute agent sandbox in the sandbox.
 */
export interface ExecuteAgentRequest {
    /** The session identifier returned by {@link PrepareSessionResponse} */
    sessionId: string;
    /** Absolute path to the agent sandbox working directory */
    workDir: string;
    /** The prompt to pass to the subordinate agent process */
    prompt: string;
    /** Maximum number of agent turns. Omit to use CLI default. */
    maxTurns?: number;
    /** Execution timeout as a duration string, e.g. "1h" */
    timeout?: string;
    /** Environment variables to set for the agent sandbox process */
    envVars: Record<string, string>;
    /** Model override, e.g. "claude-sonnet-4-6". Omit to use CLI default. */
    model?: string;
    /** When true the bridge streams events back rather than buffering */
    stream: boolean;
}
/** Response from the sandbox bridge after (non-streaming) execution */
export interface ExecuteAgentResponse {
    /** Raw stdout from the agent sandbox process (stream-json lines) */
    stdout: string;
    /** Exit code of the subordinate process */
    exitCode: number;
    /** Whether the process was killed due to timeout */
    timedOut: boolean;
}
/**
 * Sent to the sandbox bridge to read output files from a completed session.
 */
export interface ReadOutputsRequest {
    /** Absolute path to the session directory */
    sessionPath: string;
    /** Glob patterns identifying which files to capture */
    patterns: string[];
}
/** Response from the sandbox bridge containing the requested output files */
export interface ReadOutputsResponse {
    /** The captured files matching the requested patterns */
    files: DelegateTaskOutputFile[];
}
/**
 * Workspace context fetched from the WorkspaceAgent at runtime.
 * Used to populate CLAUDE.md, MCP settings, and skills for delegated tasks.
 */
export interface DelegateWorkspaceContext {
    workspaceName: string;
    workspaceId: string;
    apps: Array<{
        name: string;
        id: string;
        description: string;
        mcpUrl?: string;
    }>;
    workspaceMcpUrl?: string;
    externalMcpServers: Array<{
        name: string;
        url?: string;
        command?: string;
        args?: string[];
    }>;
    skills: Array<{
        name: string;
        content: string;
    }>;
}
/**
 * The full event log persisted to R2 after a streaming execution completes.
 * Used for replay and debugging.
 */
export interface ExecutionStreamLog {
    /** The session/execution identifier */
    executionId: string;
    /** All events emitted during the streaming execution */
    events: DelegateTaskStreamEvent[];
    /** Summary result of the execution */
    result: {
        response: string;
        usage: DelegateTaskUsage;
        exitCode: number;
    };
    /** ISO timestamp when the log was persisted */
    timestamp: string;
}
/**
 * Zod schema for the `delegateTask` LLM tool parameters.
 * Used when exposing delegateTask as a tool to the orchestrating agent.
 */
export declare const delegateTaskToolSchema: z.ZodObject<{
    prompt: z.ZodString;
    inputFiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
        name: z.ZodString;
        content: z.ZodString;
        encoding: z.ZodOptional<z.ZodEnum<["utf-8", "base64"]>>;
    }, "strip", z.ZodTypeAny, {
        name: string;
        content: string;
        encoding?: "utf-8" | "base64" | undefined;
    }, {
        name: string;
        content: string;
        encoding?: "utf-8" | "base64" | undefined;
    }>, "many">>;
    outputFilePatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
    maxTurns: z.ZodOptional<z.ZodNumber>;
    timeout: z.ZodOptional<z.ZodString>;
    sessionId: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    prompt: string;
    inputFiles?: {
        name: string;
        content: string;
        encoding?: "utf-8" | "base64" | undefined;
    }[] | undefined;
    outputFilePatterns?: string[] | undefined;
    maxTurns?: number | undefined;
    timeout?: string | undefined;
    sessionId?: string | undefined;
}, {
    prompt: string;
    inputFiles?: {
        name: string;
        content: string;
        encoding?: "utf-8" | "base64" | undefined;
    }[] | undefined;
    outputFilePatterns?: string[] | undefined;
    maxTurns?: number | undefined;
    timeout?: string | undefined;
    sessionId?: string | undefined;
}>;
/**
 * Environment variable names that the platform always controls.  Any values
 * supplied via {@link DelegateTaskOptions.env} for these keys are silently
 * discarded to prevent callers from overriding critical platform credentials.
 */
export declare const RESERVED_ENV_VARS: string[];