import type { ConversationPlan, Frame, Request } from "./index";

type KIND<K extends string> = Frame & { kind: K };

/**
 * Chat drives the agent.
 *
 * Shared, like everything else in a room: one transcript, one turn at a time,
 * and anything said while a turn is running joins a queue rather than being
 * refused. The composer stays live even when the plan does not — a turn owns
 * the document, not Chat.
 */
export declare namespace Chat {
	export type Incoming =
		| Request<Send>
		| Request<Abort>
		| Request<Resume>
		| Request<PauseRun>
		| Request<ResumeRun>
		| Request<Unqueue>;

	export type Outgoing = History | Message | Delta | Tool | State | Queue | Sent;

	/** Who said something. The agent is not a member, so it is named apart. */
	export type Author =
		| { kind: "member"; handle: string }
		| { kind: "agent" }
		| { kind: "system" };

	export type ToolStatus = "running" | "done" | "failed";

	export type ReferenceRequest =
		| { kind: "document"; channelId: string; start: number; end: number }
		| { kind: "research"; workspaceId: string; start: number; end: number };

	type ReferenceBase = {
		id: string;
		start: number;
		end: number;
		label: string;
		href: string;
		repositoryId: string;
		observedRevision: number;
	};

	export type DocumentReference = ReferenceBase & {
		kind: "document";
		channelId: string;
		observedSourceHash: string;
	};

	export type ResearchReference = ReferenceBase & {
		kind: "research";
		parentChannelId: string;
		workspaceId: string;
	};

	export type Reference = DocumentReference | ResearchReference;

	/** One tool call, as it appears beneath the message that made it. */
	export type Activity = {
		id: string;
		name: string;
		status: ToolStatus;
		/** Truncated and redacted; the arguments the model supplied, once its input finished. */
		args?: string;
		/** Truncated and redacted; partial output while running, final output once finished. */
		result?: string;
		/** Milliseconds since the epoch, set by the server when the tool's input began. */
		startedAt?: number;
		/** Present, with status "failed", when the Planner was refused permission to run the tool. */
		refused?: true;
		/** Milliseconds, once finished. */
		took?: number;
	};

	export type Entry = {
		id: string;
		author: Author;
		text: string;
		ts: number;
		/** A system notice about a decision card; text remains its fallback. */
		decision?:
			| {
				questionnaireId: string;
				kind: "prompt";
				generation: number;
				label?: string;
				/** Stable source identity for a refreshed advisory; absent on legacy prompts. */
				sourceMessageIds?: string[];
				suggestedOptionId?: string;
			}
			| {
				questionnaireId: string;
				kind: "scoped-choice";
				threadId: string;
				proposalId: string;
				cardId: string;
				optionId: string;
				label: string;
				scope: "spike";
				generation: number;
				triggerEventId: string;
				sources: ConversationPlan.SourceRef[];
			}
			| { questionnaireId: string; kind: "activity"; label?: string; generation?: never };
		/** True while the agent is still writing this one. */
		streaming?: boolean;
		tools?: Activity[];
		references?: Reference[];
		/** Present as `planner` on a member message sent to the Planner; the mention is stripped from `text`. */
		to?: "planner";
	};

	/** Transient Planner turn state. */
	export type Turn = {
		id: string;
		handle: string;
		started: number;
		/** Index of the first transcript entry after this turn began; transient like the turn. */
		entryOffset: number;
		/** Optional so earlier clients ignore it; milliseconds since the epoch, set by the server. */
		startedAt?: number;
		/** True after the Planner has sent non-empty prose. */
		responded: boolean;
	};

	/** One stage of a workflow run, in the order the run reached it. */
	export type RunStage = {
		id: string;
		name: string;
		/** A `ctx.tool` step rather than an agent stage. */
		kind?: "tool";
		status:
			| "pending"
			| "running"
			| "awaiting_input"
			| "paused"
			| "blocked"
			| "completed"
			| "failed"
			| "skipped";
		/** Seconds since the epoch. */
		started?: number;
		ended?: number;
	};

	/** An Atomic workflow run the Planner started and still carries after its turn. */
	export type Run = {
		id: string;
		name: string;
		status: "running" | "waiting" | "paused" | "finished" | "blocked" | "failed" | "stopped";
		/** Seconds since the epoch. */
		started: number;
		updated: number;
		ended?: number;
		/** The most recent stages, in the order the run reached them. */
		stages: RunStage[];
		/** Stages reached before the ones listed. */
		earlierStages?: number;
		/** Decisions questions the run is waiting on. */
		waiting: number;
	};

	export type Runs = Run[];

	/** Everything said so far, sent on join. */
	export type History = KIND<"chat:history"> & {
		entries: Entry[];
		busy: boolean;
		turn?: Turn;
		runs?: Runs;
		queued: Waiting[];
	};

	/** A new entry, or a finished one replacing its streaming self. */
	export type Message = KIND<"chat:message"> & { entry: Entry };

	/** Text appended to an entry still being written. */
	export type Delta = KIND<"chat:delta"> & { id: string; text: string };

	/** A tool call starting, or finishing. */
	export type Tool = KIND<"chat:tool"> & { entry: string; activity: Activity };

	/** Whether a turn is running, and for whom, and any workflow runs outliving it. */
	export type State = KIND<"chat:state"> & {
		busy: boolean;
		turn?: Turn;
		runs?: Runs;
	};

	/** A message waiting for the current turn to end. */
	export type Waiting = {
		id: string;
		handle: string;
		text: string;
		references?: Reference[];
	};

	export type Queue = KIND<"chat:queue"> & { waiting: Waiting[] };
	export type Destination = "room" | "planner";

	/**
	 * Say something.
	 *
	 * Accepted whether or not a turn is running. If one is, this joins the
	 * queue and runs in order when the turn ends — nobody is made to wait in
	 * silence because somebody else prompted first.
	 */
	export type Send = KIND<"chat:send"> & {
		requestId: string;
		text: string;
		to: Destination;
		references?: ReferenceRequest[];
	};

	/** The member message or queue entry is accepted by the server. */
	export type Sent = KIND<"chat:send"> & { id: string; queued: boolean };

	/**
	 * Stop the running turn and pause the Planner's workflow runs. Anyone may;
	 * the transcript records who did.
	 */
	export type Abort = KIND<"chat:abort">;

	/** Resume the workflow runs the Planner paused. Anyone may; the transcript records who did. */
	export type Resume = KIND<"chat:resume">;

	/** Pause one workflow run. Anyone may; the transcript records who did. */
	export type PauseRun = KIND<"chat:pause-run"> & { runId: string };

	/** Resume one paused workflow run. Anyone may; the transcript records who did. */
	export type ResumeRun = KIND<"chat:resume-run"> & { runId: string };

	/** Withdraw a queued message. Only its author may. */
	export type Unqueue = KIND<"chat:unqueue"> & { id: string };
}