import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
import { ApprovalAction, ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
import type { McpServerUsage as ProtoMcpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
import type { WorkspaceEntry as ProtoWorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
import type { ApiResourceReference as ProtoApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
import type { AttachmentInput, EnvVarInput, McpServerUsageInput, ResourceRef, WorkspaceEntryInput } from "@stigmer/sdk";
/**
 * Options for {@link UseSessionConversationReturn.sendFollowUp}.
 *
 * Session-level fields (`workspaceEntries`, `mcpServerUsages`,
 * `skillRefs`) trigger a `session.update()` before the execution is
 * created. Only provided fields are overwritten; omitted fields
 * preserve the session's existing values.
 *
 * `runtimeEnv` is forwarded to the execution (Execution Flow). These
 * values are scoped to the single execution and deleted on completion.
 */
export interface SendFollowUpOptions {
    /** LLM model name to use for this execution. Overrides the session default. */
    readonly modelName?: string;
    /**
     * Override the session's agent instance for this and all future
     * executions. When provided, the session is updated before the
     * execution is created.
     */
    readonly agentInstanceId?: string;
    /** Workspace entries to attach to the execution. */
    readonly workspaceEntries?: WorkspaceEntryInput[];
    /** MCP server configurations to include for tool access. */
    readonly mcpServerUsages?: McpServerUsageInput[];
    /** Skill references to enable for this execution. */
    readonly skillRefs?: ResourceRef[];
    /**
     * Execution-scoped secrets and configuration (Execution Flow).
     *
     * Values are injected into the agent sandbox for this execution only
     * and deleted when the execution completes. They override both
     * Environment values and agent defaults.
     *
     * @see {@link CreateAgentExecutionInput.runtimeEnv}
     */
    readonly runtimeEnv?: Record<string, EnvVarInput>;
    /**
     * Pre-uploaded file attachments for this execution.
     *
     * Each entry must include a `storageKey` from
     * `agentExecution.uploadAttachment()`. Forwarded directly to
     * execution creation.
     *
     * @see {@link CreateAgentExecutionInput.attachments}
     */
    readonly attachments?: AttachmentInput[];
}
/**
 * Return value of {@link useSessionConversation}.
 *
 * Provides the full conversation state for a session: loaded data,
 * active stream, follow-up submission, approval handling, and
 * session-level context (workspace entries, MCP servers, skills).
 */
export interface UseSessionConversationReturn {
    /** The session object, or null while loading. */
    readonly session: Session | null;
    /** Executions in terminal phases, in chronological order. */
    readonly completedExecutions: readonly AgentExecution[];
    /** Currently streaming execution (stream or fetch fallback), or null. */
    readonly activeStreamExecution: AgentExecution | null;
    /** Phase of the active execution, or null if none active. */
    readonly activePhase: ExecutionPhase | null;
    /** True while the active execution's stream is delivering updates. */
    readonly isStreaming: boolean;
    /**
     * True after the stream subscription starts but before the first
     * snapshot arrives from the server. Platform builders can use this
     * to differentiate between "connecting to stream" and "execution is
     * PENDING but stream is established."
     */
    readonly isConnecting: boolean;
    /**
     * Submit a follow-up message. Internally creates an execution and
     * starts streaming it.
     *
     * When session-level fields (`agentInstanceId`, `workspaceEntries`,
     * `mcpServerUsages`, `skillRefs`) are provided in options, the
     * session is updated via `session.update()` before creating the
     * execution.
     */
    readonly sendFollowUp: (message: string, options?: SendFollowUpOptions) => Promise<void>;
    /** True when the input should be enabled (no active execution, not creating). */
    readonly canSendFollowUp: boolean;
    /** True during the create RPC call (between submit and execution ID). */
    readonly isSending: boolean;
    /** Error from the last sendFollowUp attempt, or null. */
    readonly sendError: Error | null;
    /** Reset `sendError` to `null`. */
    readonly clearSendError: () => void;
    /** The user's message text, shown in the thread before the stream delivers it. */
    readonly pendingUserMessage: string | null;
    /** Current workspace entries from the session spec. Empty array when session is not loaded. */
    readonly workspaceEntries: readonly ProtoWorkspaceEntry[];
    /** Current MCP server usages from the session spec. Empty array when session is not loaded. */
    readonly mcpServerUsages: readonly ProtoMcpServerUsage[];
    /** Current skill references from the session spec. Empty array when session is not loaded. */
    readonly skillRefs: readonly ProtoApiResourceReference[];
    /** Pending approval requests from the active execution, empty when none. */
    readonly pendingApprovals: readonly PendingApproval[];
    /** Submit an approval decision. The executionId is managed internally. */
    readonly submitApproval: (toolCallId: string, action: ApprovalAction, comment?: string) => Promise<void>;
    /** Set of tool call IDs currently being submitted for approval. */
    readonly submittingApprovalIds: ReadonlySet<string>;
    /** Error from the last approval submission, or `null` when healthy. */
    readonly approvalError: Error | null;
    /** Reset `approvalError` to `null`. */
    readonly clearApprovalError: () => void;
    /** `true` while the session or execution list is loading. */
    readonly isLoading: boolean;
    /** Error from session or execution list loading, or `null` when healthy. */
    readonly loadError: Error | null;
    /** Error from the execution stream, or `null` when healthy. */
    readonly streamError: Error | null;
    /** Reset the stream error and re-establish the execution stream subscription. */
    readonly reconnectStream: () => void;
}
/**
 * Behavior hook that encapsulates the full conversation lifecycle for
 * a session: loading data, streaming the active execution, submitting
 * follow-up messages, and updating session-level workspace entries.
 *
 * Composes {@link useSession}, {@link useSessionExecutions},
 * {@link useCreateAgentExecution}, {@link useExecutionStream}, and
 * {@link useUpdateSession} into a single return value that drives
 * both {@link MessageThread} and {@link SessionComposer}.
 *
 * Platform builders get the complete conversation loop without
 * reimplementing orchestration logic.
 *
 * @param sessionId - Session to display and converse in. Pass `null` to skip.
 * @param org - Organization slug for creating follow-up executions.
 *
 * @example
 * ```tsx
 * function Chat({ sessionId, org }: { sessionId: string; org: string }) {
 *   const conv = useSessionConversation(sessionId, org);
 *
 *   if (conv.isLoading) return <Spinner />;
 *
 *   return (
 *     <>
 *       <MessageThread
 *         executions={conv.completedExecutions}
 *         activeStreamExecution={conv.activeStreamExecution}
 *         pendingUserMessage={conv.pendingUserMessage}
 *         onApprovalSubmit={conv.submitApproval}
 *         submittingApprovalIds={conv.submittingApprovalIds}
 *       />
 *       <SessionComposer
 *         onSubmit={(msg, model) => conv.sendFollowUp(msg, { modelName: model })}
 *         disabled={!conv.canSendFollowUp}
 *         isSubmitting={conv.isSending}
 *       />
 *     </>
 *   );
 * }
 * ```
 */
export declare function useSessionConversation(sessionId: string | null, org: string): UseSessionConversationReturn;
//# sourceMappingURL=useSessionConversation.d.ts.map