import type { SessionId, TurnId } from '../../types/ids/index.js';
import { type Message, type UserMessage } from '../../types/message/index.js';
import type { ToolResult } from '../../types/tool/index.js';
/** One real registry execution, after retries and its terminal event. */
export interface ToolResultObservation {
    readonly sessionId: SessionId;
    readonly turnId: TurnId;
    readonly toolUseId: string;
    readonly toolName: string;
    readonly input: unknown;
    readonly result: ToolResult;
    /** Present when another tool dispatched this call. */
    readonly parentToolUseId?: string;
}
/** Authority and durable conversation visible to one host policy callback. */
export interface ProjectInstructionCallbackContext {
    /** A snapshot of the messages accepted before this callback starts. */
    readonly messages: readonly Message[];
    /** The turn-owned cancellation signal for any host I/O the callback starts. */
    readonly signal: AbortSignal;
}
export type ProjectInstructionSnapshotUpdate = UserMessage | null | undefined;
/**
 * Host-owned live project policy for one turn.
 *
 * Tool results are observed only after the registry has produced its final
 * result and the complete tool-result batch is in `context.messages`. Each
 * accepted observation returns its desired complete snapshot and the loop
 * persists it before entering the next observation. `undefined` means no
 * change; `null` explicitly removes the old snapshot.
 *
 * Callbacks must derive publication decisions from `context.messages`, not
 * advance a private "published" cursor before returning: cancellation may win
 * after host work finishes but before the returned value is accepted.
 */
export interface ProjectInstructionContext {
    /**
     * Rebuild the first-request snapshot from host authority. Persisted source
     * paths may guide discovery; persisted policy text must not be trusted.
     * `undefined` leaves history unchanged, while `null` removes stale state.
     */
    prepareInitialSnapshot?(context: ProjectInstructionCallbackContext): ProjectInstructionSnapshotUpdate | Promise<ProjectInstructionSnapshotUpdate>;
    observeToolResult(observation: ToolResultObservation, context: ProjectInstructionCallbackContext): ProjectInstructionSnapshotUpdate | Promise<ProjectInstructionSnapshotUpdate>;
}
/**
 * Await opaque host work without giving it ownership of run cancellation.
 *
 * The callback receives the signal for cooperative cleanup. The independent
 * settlement boundary is still required: a host implementation that ignores
 * the signal may continue its own work, but it cannot keep Namzu pending or
 * publish a value after authority was withdrawn.
 */
export declare function awaitProjectInstructionCallback<T>(signal: AbortSignal, start: () => T | Promise<T>): Promise<T>;
export declare function isProjectInstructionMessage(message: Message): message is UserMessage;
/**
 * Keep only the latest structurally valid project snapshot, at its own
 * chronological position. Invalid tagged provenance refuses before a provider
 * can be called; an untrusted persisted object cannot acquire policy status by
 * spelling one discriminator.
 */
export declare function collapseProjectInstructionSnapshots(messages: readonly Message[]): Message[];
/**
 * Replace project policy without mutating the caller's history.
 *
 * Runtime updates append after the finalized tool batch. A host seeding a new
 * human turn uses `before-latest-user`, so the policy is context for that
 * request rather than a reply after it.
 */
export declare function replaceProjectInstructionSnapshot(messages: readonly Message[], snapshot: UserMessage | null, placement?: 'append' | 'before-latest-user'): Message[];
//# sourceMappingURL=project-instructions.d.ts.map