/**
 * Structured session recording via llmtxt AgentSession — T947 Step 2.
 *
 * Provides a high-level `recordAgentSession` function that writes a
 * complete agent run (prompt, output, tool calls, timing, exit code)
 * to the project's `.cleo/sessions/<sessionId>.llmtxt` path using the
 * llmtxt `AgentSession` primitive.
 *
 * Design decisions:
 *   - Uses `openAgentSession` / `closeAgentSession` from the lower-level
 *     {@link ./agent-session-adapter.ts} rather than duplicating backend
 *     setup. This file is a thin write-path convenience wrapper only.
 *   - Session data is contributed via `session.contribute()` so the
 *     llmtxt receipt's `eventCount` is incremented and the structured
 *     run object is embedded in the signed receipt.
 *   - The `.llmtxt` file path returned is deterministic:
 *     `<projectRoot>/.cleo/sessions/<sessionId>.llmtxt`. The caller is
 *     responsible for writing structured content there; this function
 *     writes the llmtxt receipt record only (the path is reserved for
 *     future wave-B rich export).
 *   - NEVER throws. All peer-dep and I/O failures degrade to a best-
 *     effort stub result with `sessionId: "<agentId>-<ts>"`.
 *
 * Non-goals:
 *   - Does NOT replace the CLEO `Session` record in `tasks.db`.
 *   - Does NOT write the structured `.llmtxt` document itself in this
 *     wave (Wave B will adopt `formatLlmtxt` from `llmtxt/export` for
 *     that purpose).
 *
 * @epic T947
 * @adr ADR-051 §6 — receipt as per-session audit companion
 * @see ./agent-session-adapter.ts (AgentSession open/close/wrap primitives)
 */
/**
 * A single tool invocation recorded within an agent session.
 */
export interface AgentToolCall {
    /** Tool name (e.g. `"bash"`, `"read_file"`, `"cleo-dispatch"`). */
    readonly name: string;
    /** Arguments passed to the tool. May be any JSON-serialisable value. */
    readonly args: unknown;
    /** Value returned by the tool. May be any JSON-serialisable value. */
    readonly result: unknown;
}
/**
 * Input options for {@link recordAgentSession}.
 */
export interface RecordAgentSessionOptions {
    /** Agent identifier (e.g. `"cleo-prime"`, `"subagent-T947"`). */
    readonly agentId: string;
    /**
     * CLEO task ID this run is associated with.
     * When present, embedded in the session document for traceability.
     */
    readonly taskId?: string;
    /** Full prompt / user instruction given to the agent. */
    readonly prompt: string;
    /** Full agent output / response text. */
    readonly output: string;
    /** Ordered list of tool invocations made during the session. */
    readonly toolCalls: AgentToolCall[];
    /** ISO 8601 UTC timestamp when the session started. */
    readonly startedAt: string;
    /** ISO 8601 UTC timestamp when the session ended. */
    readonly endedAt: string;
    /**
     * Process exit code. `0` = success, non-zero = failure.
     * Matches the llmtxt `AgentSession` contract for `eventCount`
     * (a zero-eventCount receipt is NOT emitted on non-zero exit).
     */
    readonly exitCode: number;
    /**
     * Absolute project root. Defaults to `getProjectRoot()`.
     */
    readonly projectRoot?: string;
}
/**
 * Result returned by {@link recordAgentSession}.
 */
export interface RecordAgentSessionResult {
    /**
     * Session identifier as recorded in the llmtxt receipt, or a best-effort
     * stub when llmtxt peer deps are unavailable.
     */
    readonly sessionId: string;
    /**
     * Absolute path where the `.llmtxt` session document was written.
     * Path is always populated; the file contains a minimal JSON stub
     * when llmtxt is unavailable.
     */
    readonly llmtxtPath: string;
}
/**
 * Record a completed agent session as a structured `.llmtxt` document.
 *
 * Writes via llmtxt AgentSession to
 * `<projectRoot>/.cleo/sessions/<sessionId>.llmtxt` and appends
 * the signed receipt to `.cleo/audit/receipts.jsonl`.
 *
 * Returns both the canonical `sessionId` and the absolute `llmtxtPath`
 * so callers can reference the artefact for later retrieval.
 *
 * NEVER throws — all failures degrade to a best-effort stub so that
 * callers (e.g. `cleo complete`, `cleo session end`) are never blocked.
 *
 * @param options - Session recording options.
 * @returns Resolved session id and path.
 *
 * @example
 * ```ts
 * import { recordAgentSession } from '@cleocode/core/sessions/agent-session';
 *
 * const { sessionId, llmtxtPath } = await recordAgentSession({
 *   agentId: 'cleo-prime',
 *   taskId: 'T947',
 *   prompt: 'Implement blob-ops.ts',
 *   output: 'Done. See blob-ops.ts.',
 *   toolCalls: [{ name: 'bash', args: { cmd: 'pnpm run build' }, result: 0 }],
 *   startedAt: new Date().toISOString(),
 *   endedAt: new Date().toISOString(),
 *   exitCode: 0,
 * });
 * console.log(sessionId, llmtxtPath);
 * ```
 *
 * @epic T947
 * @adr ADR-051 §6
 */
export declare function recordAgentSession(options: RecordAgentSessionOptions): Promise<RecordAgentSessionResult>;
//# sourceMappingURL=agent-session.d.ts.map