// agents: the conversation fleet
import { LandingDeliverySchema } from "./project-delivery.js";
import { AgentNextSchema } from "./agent-next.js";
import { z } from "zod";
import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema, FreshSessionSchema } from "./agent.js";
import { LoopStateSchema } from "./loops.js";
import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
import { KeepWarmSchema } from "./keep-warm.js";
import { AgentNeedSchema } from "./needs.js";
import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
import { ProgramAskSchema } from "../events/requests.js";
import { ReviewTallySchema, TurnProofSchema } from "./work-assurance.js";
import { AgentReactionSchema, SessionOwnerSchema } from "./agent-people.js";
export { AgentReactionSchema, ReactorSchema, SessionOwnerSchema, type AgentReaction, type Reactor, type SessionOwner } from "./agent-people.js";
// A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
// (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.

// idle/running/awaiting: turn lifecycle (awaiting = paused on a plan or question)
// ready/landed/conflict: land-flow outcomes (ready = clean completion held on the branch, auto-land off)
// error: terminal turn failure
// interrupted: the daemon died under the turn (crash, OOM, rebuild); without it such a turn rehydrates as idle and its
// parked question disappears
// stopping/stopped: the two halves of a user's Stop, since a hard-cancel is not instant (`stopping` the moment the
// abort lands, `stopped` once the turn's generator has unwound)
// dismissing: the same window for waving away a parked question; settles in Finished rather than Attention, since
// nothing is left half-done
// `stopped` is its own value, never `error` (a deliberate stop is not a failure) or `interrupted` (which allows an
// automatic re-run)
// resuming: the turn was killed by something the daemon is already undoing (a credential re-mint, an outage backoff);
// never persisted, since a daemon restart forgets the resume and the turn's own last-written ending becomes true again
export const AgentStatusSchema = z.enum([
    "idle",
    "running",
    "awaiting",
    "stopping",
    "dismissing",
    "stopped",
    "resuming",
    "landing",
    "ready",
    "landed",
    "conflict",
    "error",
    "interrupted",
]);
export type AgentStatus = z.infer<typeof AgentStatusSchema>;
// The card's live activity snippet: the last tool the agent used (with its target) and the in-progress todo.
export const AgentActivitySchema = z.object({
    tool: z.string().optional().describe("The last tool it reached for."),
    target: z.string().optional().describe("What it reached for that tool with: a file, a command, a URL."),
    todo: z.string().optional().describe("The item on its own list that it is working through."),
});
export type AgentActivity = z.infer<typeof AgentActivitySchema>;
// Where the agent is on its own checklist right now, unlike UnfinishedWorkSchema's account of where a turn stopped.
// Counts items, never segments: how a rim or a bar divides them is the reader's business.
export const AgentChecklistSchema = z.object({
    done: z.number().describe("Items it has completed."),
    total: z.number().describe("Items on the list. Never zero: a conversation that kept no list carries no clause at all."),
});
export type AgentChecklist = z.infer<typeof AgentChecklistSchema>;
// Which "needs you" flags are raised, the fleet badge aggregates these across all agents.
export const AgentAttentionSchema = z.object({
    plan: z.boolean().describe("It has proposed a plan and is waiting for a yes."),
    question: z.boolean().describe("It has asked you something."),
    permission: z.boolean().describe("It wants to use a tool it needs permission for."),
    // A missing capability on a card from before needs (docs/architecture/needs.md); lets the lane say "setup needed" rather than a generic
    // pause.
    capability: z.boolean().describe("It needs something connected that is not connected yet."),
    // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear themselves.
    credential: z
        .boolean()
        .describe("It is waiting for a named person to release a credential. The one pause that may not be yours to clear, whatever your role."),
    conflict: z.boolean().describe("Its work cannot be merged without somebody resolving a clash."),
    // A need outlives its turn (docs/architecture/needs.md), so this can stand on a card that is not running at all.
    need: z
        .boolean()
        .optional()
        .describe("It asked a person for something it still needs: a connection, a secret, wider reach, a tool. Absent from a daemon older than needs."),
});
export type AgentAttention = z.infer<typeof AgentAttentionSchema>;
// What the last turn left open, measured at the moment it ended, unlike AgentAttentionSchema's live parked waits.
// Derived from finish frames every harness sends, never self-reported; absent for a turn that closed its list and
// passed its checks.
export const UnfinishedWorkSchema = z.object({
    // Epoch ms the turn ended; not `updatedAt`, which moves on a land or rename without the work moving.
    at: z.number().describe("When the turn that left this ended, in milliseconds."),
    // The agent's own checklist as of that turn's last word on it; `open`/`total` count items, `next` is the
    // in-progress or first pending one.
    steps: z
        .object({
            open: z.number().describe("Items on it that were never completed."),
            total: z.number().describe("Items on the whole list."),
            next: z.string().optional().describe("The one it would have done next: what it was working through, or the first still waiting."),
        })
        .optional()
        .describe("The agent's own checklist where that turn left it. Absent for a conversation that kept no list."),
    // Name of the `turn.ending` check still failing when the turn ended, from when a failing one left the work unfinished.
    // Nothing writes it now, and it stays so entries written before still read.
    check: z
        .string()
        .optional()
        .describe(
            "The end-of-turn check that was still failing when the turn ended, by name. No longer written: what a check finds as a turn ends is said back to the model and never leaves its work unfinished.",
        ),
});
export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
// What has looked at a conversation's work (its last turn's own checks, its latest code review): work-assurance.ts.
export * from "./work-assurance.js";
// How many entries each of a reach's lists carries; past it, the list's `…More` count says how many were left out.
export const TURN_REACH_LIST_MAX = 10;
// Where the last turn's work went when it went somewhere other than its own branch, read off what the turn touched and
// never asked of the model. Lists only the exceptions: a turn whose work all lives on its branch leaves no reach at all.
export const TurnReachSchema = z.object({
    at: z.number().describe("When the turn that left this ended, in milliseconds."),
    live: z
        .array(
            z.object({
                path: z
                    .string()
                    .describe(
                        "What it wrote, as it named it: relative to the workspace for the sandbox's shared state, absolute for the owner's own checkout.",
                    ),
                extension: z
                    .string()
                    .optional()
                    .describe("The extension, by its manifest id, when what it changed is the installed copy of one. Absent for anything else."),
            }),
        )
        .max(TURN_REACH_LIST_MAX)
        .optional()
        .describe(
            "Files it changed in place where every conversation reads them, outside its own branch: an installed extension's copy, the sandbox's shared state, the owner's own checkout. Live the moment they were written, never reviewed, and an installed extension's next update replaces them.",
        ),
    liveMore: z.number().optional().describe("How many more such files there were beyond the ones listed. Absent when all are listed."),
    stranded: z
        .array(
            z.object({
                dir: z.string().describe("The clone, as a folder relative to its own copy of the workspace."),
                uncommitted: z.number().describe("Files changed in it and never committed."),
                unpushed: z.number().describe("Commits in it its upstream does not have, or that no remote has when it follows none."),
            }),
        )
        .max(TURN_REACH_LIST_MAX)
        .optional()
        .describe(
            "Repositories it cloned inside its own copy and left work in. A clone of its own never rides its land, so what is in one stays there.",
        ),
    strandedMore: z.number().optional().describe("How many more such clones there were beyond the ones listed. Absent when all are listed."),
    published: z
        .array(
            z.object({
                dir: z.string().optional().describe("The folder it pushed from, as the command named it. Absent for its own working folder."),
                remote: z.string().optional().describe("The remote it pushed to, as the command named it. Absent when the command named none."),
                branch: z.string().optional().describe("The branch it pushed to, as the command named it. Absent when the command named none."),
                command: z.string().describe("The push itself, trimmed to one line."),
            }),
        )
        .max(TURN_REACH_LIST_MAX)
        .optional()
        .describe("Pushes it made with git that went through: work it sent out of the sandbox itself, never through a land."),
    publishedMore: z.number().optional().describe("How many more such pushes there were beyond the ones listed. Absent when all are listed."),
});
export type TurnReach = z.infer<typeof TurnReachSchema>;
// A landing's commit message: subject plus the two trailer sentences a changelog repo gets. One schema, not three
// duplicated fields, since both the live roster and the review carrier must read the same shape and can't disagree.
export const LandedMessageSchema = z.object({
    // Written from the landed diff, not the opening prompt: a session that drifts from its title still needs an accurate subject.
    subject: z
        .string()
        .describe(
            "One line saying what the merged work did, read off the code rather than off the opening request. A conversation that asks for an audit and then spends four turns fixing what it found needs a subject about the fixes.",
        ),
    // Usually absent by design: the model omits it rather than inventing a note for an unremarkable change.
    note: z
        .string()
        .optional()
        .describe(
            "The same change said to somebody who uses the product, for a repository that keeps a changelog. Usually absent, because most changes are not ones a user would notice.",
        ),
    // Nearly always absent (removals only); required and mechanically guaranteed when a landing shrinks a wire-contract lock.
    breaking: z
        .string()
        .optional()
        .describe("What this change takes away, for anything already relying on it. Nearly always absent: it is for removals, not for additions."),
    // Present only when the conversation said why a test it weakened should stay weaker; the push gate reads it as the
    // weakening's declaration.
    testNote: z
        .string()
        .optional()
        .describe("Why a test this change weakened is meant to be weaker, in the conversation's own words. Nearly always absent."),
    // Present only when the conversation declared an exception a check should grant this change (`Allow: <check> — <reason>`);
    // the push reads it off the commit.
    allows: z
        .array(z.string())
        .optional()
        .describe("Exceptions the conversation declared for this change, each `<check> — <reason>` in its own words. Nearly always absent."),
});
export type LandedMessage = z.infer<typeof LandedMessageSchema>;
// One model's turn in the drafting walk (agent/role-model.ts tries connected models in order), in spend order:
// asking: in flight, `ms` absent
// answered: wrote the sentence, in `ms`
// refused: failed or declined, in `ms`, with `reason`
// skipped: not asked, since it refused recently and the walk stepped over it
export const LandedMessageStepSchema = z.object({
    provider: z.string().min(1).describe("Which provider was asked."),
    model: z.string().min(1).describe("Which of its models."),
    status: z
        .enum(["asking", "answered", "refused", "skipped"])
        .describe("How this one went. Skipped means it was not asked at all, because it refused a few minutes ago and the walk stepped over it."),
    // Epoch ms it started; client-measures an in-flight step's ticking display. Absent for `skipped`, which cost no time.
    at: z.number().optional().describe("When it started being asked, in milliseconds. Absent for one that was skipped, which cost no time."),
    ms: z.number().optional().describe("How long it took. Absent while it is still being asked."),
    reason: z.string().optional().describe("Why it refused, in its own words."),
});
export type LandedMessageStep = z.infer<typeof LandedMessageStepSchema>;
// Full account of one landing's commit message being drafted: started, which models were asked, how each went, and how
// it ended. `outcome` absent means still running; `written` puts the sentence on the card, `failed` carries a one-line
// `reason`.
export const LandedMessageDraftSchema = z.object({
    startedAt: z.number().describe("When the drafting began, in milliseconds."),
    steps: z
        .array(LandedMessageStepSchema)
        .describe(
            "Each model that was asked, in the order they were spent, so the list is the timeline. Empty with no outcome means the diff is still being read.",
        ),
    outcome: z.enum(["written", "failed"]).optional().describe("How it ended. Absent means it is still going."),
    reason: z
        .string()
        .optional()
        .describe("The one-line account of a failure, for a screen with one line to spend. The steps carry each model's own words."),
    finishedAt: z.number().optional().describe("When it ended, in milliseconds."),
});
export type LandedMessageDraft = z.infer<typeof LandedMessageDraftSchema>;
// Why a path would not land:
// workspace: your own uncommitted edits are on that path
// diverged: the main tree's committed content moved under the agent since it branched; nothing of yours is at risk
// binary: git cannot three-way merge the file at all
// Declared here rather than beside the conflict report below, since the roster carries the causes too: a card cannot
// offer the press that clears a refusal without knowing whose refusal it is.
export const LandConflictReasonSchema = z.enum(["workspace", "diverged", "binary"]);
export type LandConflictReason = z.infer<typeof LandConflictReasonSchema>;
export const AgentSummarySchema = z.object({
    id: z.string().describe("The conversation id, which is how every other call addresses it."),
    sessionId: z.string().optional().describe("The provider session behind the last turn. It is retired whenever the model or account changes."),
    title: z.string().optional().describe("What to call it: the first prompt cut to one line, unless somebody renamed it."),
    titleAction: z
        .string()
        .optional()
        .describe(
            "One word for the kind of work the naming pass read in it (fix, audit, redesign). Never part of the displayed name: a board tints and glyphs a card by it. Absent for a title nothing named an action for.",
        ),
    status: AgentStatusSchema.describe(
        "What it is doing. Stopping and stopped are the two halves of somebody pressing stop, because a cancel is not instant; dismissing is the same window for a question waved away, which ends the turn too but owes the user nothing; resuming means the sandbox is already putting right whatever killed the turn; landing means its work is being carried into the workspace right now, and nothing may act on its branch until that settles.",
    ),
    // Sentence the last turn died on; carried since `error` status alone isn't an answer, especially for an unwatched run.
    failure: z
        .string()
        .optional()
        .describe(
            "Why the last turn failed, in the words it died on. Absent unless it did, and cleared the moment it runs again. Carried here because the word error on its own is not an answer, least of all for a run nobody was watching.",
        ),
    // The error frame's own code, so the board can distinguish e.g. a rate limit from a crash the way chat already does.
    failureCode: z
        .string()
        .optional()
        .describe(
            "Which kind of failure it was, as the turn's own error frame coded it. Absent for a failure nothing could classify, which reads as the plain red line it is.",
        ),
    // Who worded `failure`, as the turn's error frame said (its `own`): a card leads with those words only when they are
    // the sandbox's own sentence, as the chat's notice does (failureView), and with its kind's line otherwise.
    failureOwn: z
        .boolean()
        .optional()
        .describe(
            "Whether `failure` is the sandbox's own sentence rather than the provider's or the harness's words. Absent for theirs, and for an ending recorded before it was said.",
        ),
    // Epoch seconds the spent allowance reopens; absent means genuinely unknown (Grok, Cursor) — never guess one.
    limitResetsAt: z.number().optional().describe("When the spent allowance reopens, in epoch seconds. Absent when the provider publishes no instant."),
    limitHeld: z.boolean().optional().describe("Whether the refused turn is held whole, so sending again re-runs it instead of appending to it."),
    // What a sandbox older than `next` (before 1.343.0) said in its place, read so the editor can derive `next` from it
    // (agentStatus-standing.ts, withNext): the hosted editor meets such a sandbox for as long as it stays off the release
    // that dropped them, which carried a Breaking-Note and so is never taken by itself. No sandbox sends them since.
    limitScheduled: z.boolean().optional().describe("Sent only by sandboxes older than `next`: whether the held turn was booked to go again by itself."),
    limitMoving: z.string().optional().describe("Sent only by sandboxes older than `next`: the account a booked move was taking the held turn to."),
    limitNextAt: z.number().optional().describe("Sent only by sandboxes older than `next`: when the booked re-run went, in epoch seconds."),
    // The one answer to "does it go by itself, and when" (agent-next.ts), derived from what it holds every time it is read.
    next: AgentNextSchema.optional().describe(
        "What carries it on next with nobody pressing anything, and when: a held turn re-run, a message held for memory, or messages booked for later. Absent when only a press moves it.",
    ),
    provider: AgentProviderSchema.describe("Which model provider it runs on."),
    harness: AgentHarnessSchema.describe("Which agentic loop it runs on."),
    // Latched with the conversation, so the card can say where work runs without asking anything else.
    runner: z.string().optional().describe("The runner this conversation runs on. Absent means this sandbox."),
    // Both latched at the first turn, so a board scoped to one project can say which conversations are its own.
    startIn: z.string().optional().describe("Which folder it opened in, relative to the workspace root. Absent means the root."),
    actsAs: z.string().optional().describe("Which persona its first turn acted as. Absent for an ordinary chat."),
    lastActsAs: z
        .string()
        .optional()
        .describe(
            "Which persona its last turn acted as: each turn runs as the persona it names, so this is who the conversation speaks as now, and what a view groups it under. Absent for an ordinary chat.",
        ),
    // Per-conversation, so opening it restores its own choices rather than another tab's; `fast` here is what was asked
    // for, not what was served.
    model: z
        .string()
        .optional()
        .describe(
            "What its last turn ran with. Kept per conversation so opening it restores the choices made in it, rather than whatever some other tab last picked.",
        ),
    effort: z.string().optional().describe("How hard that turn was told to think."),
    thinking: z.boolean().optional().describe("Whether that turn showed its reasoning."),
    fast: z.boolean().optional().describe("Whether that turn asked for higher speed. What was asked for, not what was served."),
    account: z.string().optional().describe("Which connected account paid for it."),
    // The worktree branch (agent/<id>); absent for a non-isolated (main-tree) conversation.
    branch: z.string().optional().describe("The branch its private copy works on. Absent for a conversation that works directly in the shared tree."),
    // Per-agent override of the sandbox-wide `autoLand`; absent means inherit, the common case that keeps the toggle
    // meaningful.
    autoLand: z
        .boolean()
        .optional()
        .describe(
            "This conversation's own answer to whether its work merges automatically. Absent means it follows the sandbox-wide setting, which is the common case.",
        ),
    // This conversation's own answer to each ending's one question, written by the in-chat control (not the settings
    // row) so one late-night click can't arm every agent; absent inherits the sandbox-wide policy.
    limitPolicy: LimitPolicySchema.optional(),
    outagePolicy: RetryPolicySchema.optional(),
    stopPolicy: RetryPolicySchema.optional(),
    memoryPolicy: RoomPolicySchema.optional(),
    // A collaborator's ask to land (collaborators can't merge themselves); cleared by whichever merge or discard
    // answers it.
    landRequested: z
        .object({
            email: z.string().describe("Who asked."),
            name: z.string().optional().describe("Their display name."),
            at: z.number().describe("When they asked, in milliseconds."),
        })
        .optional()
        .describe(
            "A collaborator has asked a maintainer to merge this work. Cleared by whichever merge or discard answers it. Absent means nobody is waiting.",
        ),
    // Beside `landRequested` because both are marks people left on the card rather than anything the agent did. Ordered
    // by when each emoji was first used, so a chip never jumps out from under the cursor when a second person presses
    // the same one.
    reactions: z
        .array(AgentReactionSchema)
        .optional()
        .describe(
            "What people have marked this conversation with, one entry per emoji, in the order the emoji were first used. Absent means nobody has marked it, which is most conversations.",
        ),
    // The card's provenance line when an outside message opened the conversation; absent means a person started it.
    origin: AgentOriginSchema.optional().describe(
        "Where the conversation came from when nobody typed it: a chat mention, a visitor's message, a webhook. Absent means a person started it.",
    ),
    // The other provenance line: who asked for the first turn directly (vs `origin`, which names the automation);
    // latched, never rewritten by a later turn.
    startedBy: z
        .string()
        .optional()
        .describe(
            "Who asked for the first turn, as the sandbox verified it: a member's email, token:<label> for a program's control token, or agent:<conversation id> for a child another conversation spawned. Absent when nothing was verified (a wake, a loopback caller).",
        ),
    // The fence it was born with. Rides the summary because it is what decides who may see the row at all
    // (auth/fleet-scope.ts visibleTo); without it here a fenced reader's board would be empty of even their own work.
    areas: z
        .array(z.string())
        .optional()
        .describe(
            "Which named areas of the workspace this conversation was started within, latched from whoever asked for the first turn. Absent means its starter held the whole workspace, which is why a fenced member is not shown it.",
        ),
    // Responsibility, beside provenance: the starter says who asked, this says who answers for it now. Absent means
    // nobody has claimed it, which is what a program's or an automation's conversation is until somebody does.
    owner: SessionOwnerSchema.optional().describe(
        "The member answerable for this conversation: set from whoever started it, inherited from the parent by a spawned child, moved by handing it over. Absent means nobody has claimed it yet.",
    ),
    // Recorded once on the fork's first turn and never cleared; rides the summary so the link survives closing and
    // reopening either tab.
    forkedFrom: ForkedFromSchema.optional().describe(
        "The conversation this one was cut from. Recorded once and never cleared: it is the relationship, not a pending state.",
    ),
    // Recorded once on a fresh session's first turn and never cleared; `startedBy` names the same origin as its parent.
    fresh: FreshSessionSchema.optional().describe(
        "Set on a conversation started on another conversation's work without its messages (a code review, a test pass, a person's own ask): which one, for what, and when. Absent for every other conversation.",
    ),
    // Latched on the opening turn (ids/conversation-ids.ts homeConversationId). Rides the summary because it decides who
    // may see the row at all (auth/fleet-scope.ts visibleTo): its owner, and the sandbox's owner.
    home: z
        .literal(true)
        .optional()
        .describe(
            "This is its owner's home conversation in this sandbox: the one long-running chat the master view opens, which orchestrates its own subagents, holds their work until it accepts it, and lands and commits by itself. Only its owner and the sandbox's owner see it. Absent for every other conversation.",
        ),
    // Root repo's short base sha; per-repo bases stay daemon-internal.
    base: z.string().optional().describe("The commit its private copy started from, shortened."),
    costUsd: z.number().optional().describe("What it has cost so far, in dollars. A subagent's spend is its own and is not folded in here."),
    inputTokens: z.number().optional().describe("Uncached input tokens, excluding cache reads and cache writes."),
    outputTokens: z.number().optional().describe("Tokens received."),
    contextTokens: z.number().optional().describe("How much of the window the conversation currently fills."),
    contextWindow: z.number().optional().describe("How large that window is."),
    // The pair travels whole or not at all: an instant with no lifetime, or a lifetime with no instant, names no
    // deadline. Absent for every provider whose prompt-cache TTL the daemon cannot ground in a measurement or a
    // documented rule (prompt-cache.ts), which is most of them.
    promptCache: z
        .object({
            at: z.number().describe("When its last request touched the provider's prompt cache, in milliseconds."),
            ttlMs: z.number().describe("How long that entry lives from `at`, in milliseconds."),
            rollsAt: z
                .number()
                .optional()
                .describe(
                    "When the date written into the agent's prompt next changes, in milliseconds (midnight where the agent runs). Past it the next turn sends a different prompt, so nothing kept before it is read again.",
                ),
            keepableUntil: z
                .number()
                .optional()
                .describe(
                    "Present when this sandbox can keep this cache warm (its provider can replay the last turn's prefix): the furthest instant a hold can reach, in milliseconds, where refreshing would cost more than the cold resume it saves or the date in the prompt changes, whichever comes first.",
                ),
        })
        .optional()
        .describe(
            "When this conversation's prompt cache was last kept alive and how long it lasts, which together say when picking the conversation up stops being cheap. Absent when the provider publishes nothing to ground it on.",
        ),
    keepWarm: KeepWarmSchema.optional().describe(
        "Whether the sandbox is keeping this conversation's prompt cache warm while it sits idle, how that is going, or why it stopped. Absent when nobody asked for it.",
    ),
    activity: AgentActivitySchema.optional().describe("What it is doing at this moment."),
    // Beside `activity` because both answer "where is it", one in a sentence and one as a fraction. Live while a turn
    // runs, and left standing after it, so a settled card still says how far the work got.
    checklist: AgentChecklistSchema.optional().describe(
        "How far it is through its own checklist. Absent for a conversation that kept no list, which is most short ones.",
    ),
    // The whole drafting story (which models, how long, what refused), replacing a boolean that hid all of it;
    // runtime-only, forgotten on restart like the draft itself.
    landedMessageDraft: LandedMessageDraftSchema.optional().describe(
        "The whole story of this merge's commit message being written: which models were asked, how long each took, what refused and in what words. Forgotten on restart, which is right, because a restart also killed the drafting it describes.",
    ),
    // The finished sentence, on the same push that ends `landedMessageDraft` above so the promise and the answer arrive
    // together; absent until then, replaced wholesale by the next land.
    landedMessage: LandedMessageSchema.optional().describe(
        "What this conversation's merged work is called, once the drafting above has finished. It arrives on the same push that ends the draft, so the promise and the answer travel together.",
    ),
    startedAt: z.number().optional().describe("When the running turn started, in milliseconds. Absent when none is running."),
    run: z
        .string()
        .optional()
        .describe(
            "The run under way right now: what a stop names, so it cannot cancel a turn that started after it was pressed. Absent when none is running, and for a turn with no run to attach to.",
        ),
    // On the card because every window and the board read it here: the queue is the conversation's, not any window's.
    queue: ConversationQueueSchema.optional().describe(
        "Messages waiting for its next turn, and whether they are held. Absent for a conversation nothing has ever waited for.",
    ),
    updatedAt: z.number().describe("When it last did something, in milliseconds. Reading it does not count."),
    // Daemon-side, not browser-side: read state is a fact about the work, so clearing site data or switching devices
    // can't resurrect a badge.
    seenAt: z
        .number()
        .optional()
        .describe(
            "When somebody last opened it, in milliseconds. Newer activity than this is what makes it unread. Kept by the sandbox rather than by a browser, so clearing site data or picking up a phone does not resurrect every badge.",
        ),
    // Derived from the drafts the sandbox holds (composer-drafts.ts), or reported by a client that keeps its own, so the
    // unattended archive sweep never files away a conversation somebody is still writing to.
    unsentAt: z
        .number()
        .optional()
        .describe(
            "Since when somebody's composer has held a message for it that they have not sent yet, in milliseconds. While set, the sandbox never archives it on its own for being idle.",
        ),
    attention: AgentAttentionSchema.describe("Which kinds of waiting-for-you it is doing."),
    // Beside `attention.permission`, which says only that one waits: the id an answer names and what it asks, so a card
    // can offer the answer itself instead of a trip to the chat. The oldest one, while its turn runs.
    permissionAsk: z
        .object({
            requestId: z.string().describe("Which request this is: the id an answer to it names."),
            ask: z.string().describe("What it asks to do, on one line: the runtime's own sentence, else the tool's short name."),
            program: ProgramAskSchema.optional().describe(
                "The program it is holding, as its own request shows it, so the card can show what would run before anyone answers. Absent on a request about no program.",
            ),
        })
        .optional()
        .describe(
            "The oldest permission its running turn is waiting on, so it can be answered where the conversation is listed. Absent when none waits, and from a sandbox older than it.",
        ),
    // Kept on the record until a land goes through, unlike `failure`, which the next turn clears: a land that broke
    // leaves the work stuck on its branch however many turns run after it.
    landFailure: z
        .object({
            reason: z.string().describe("Why it failed, in the words it failed with."),
            code: z
                .string()
                .optional()
                .describe("Which kind of failure it was, when the sandbox could tell: unlinked when its copy lost its link to the workspace. Absent otherwise."),
            at: z.number().describe("When it failed, in milliseconds."),
        })
        .optional()
        .describe(
            "The last attempt to bring its work into the workspace failed, and why. Cleared by the next land that goes through. Absent when nothing failed, and from a sandbox older than it.",
        ),
    // The land's own last word on the owner's folder, for a sandbox made for one folder: written there,
    // partly kept out, waiting for the computer, or refused (schemas/project-delivery.ts).
    delivery: LandingDeliverySchema.optional().describe(
        "What became of its last land in the folder on the owner's computer, for a sandbox made for one folder. Absent for any other land, and from a sandbox older than it.",
    ),
    // Only the causes that still hold, re-read live (conversations/land/standing.ts), never the stored report's own list: a
    // blocker the user has since cleared is not something to offer them an action about.
    conflictCauses: z
        .array(LandConflictReasonSchema)
        .optional()
        .describe(
            "Why its work will not merge, and so who can clear it: your own uncommitted edits, which only you can commit or stash, against a moved main line or an unmergeable binary, which the conversation can redo on its own copy. Absent unless it is refusing to merge.",
        ),
    // Beside `attention` since a reader asks both at a glance, but opposite in shape: a turn gone, not one still parked
    // and waiting.
    unfinished: UnfinishedWorkSchema.optional().describe(
        "What its last turn left open: steps it never completed. Absent for a turn that finished what it started.",
    ),
    // Written by the turn's own settle from its tool calls; nothing is asked of the model to earn or clear it.
    proof: TurnProofSchema.optional().describe(
        "What its last turn showed of its work: whether a check it ran passed after its last edit, and whether it looked at interface files it changed. Absent until a turn that edited or checked anything has ended.",
    ),
    // Written by the settle of the turn that reported a review, from its review frames; never asked of the model.
    review: ReviewTallySchema.optional().describe(
        "The latest code review this conversation reported: how many findings, and how many are still open. Absent until one has.",
    ),
    // Written by the turn's own settle from its tool calls and a read of the clones and installs it could have touched;
    // replaced by every turn, so it says where the LAST turn's work went.
    reach: TurnReachSchema.optional().describe(
        "Where its last turn's work went when it went somewhere besides its own branch: files changed live outside it, clones of its own holding work that will not land, pushes it made itself. Absent when everything it did is on its branch.",
    ),
    // Completed turns and lifetime tool calls, the card's msgs/tools counters.
    turns: z.number().optional().describe("Turns it has finished."),
    toolUses: z.number().optional().describe("Tools it has used, over its whole life."),
    // `running` reads the live subagent roster, `total` counts on the agent's own entry; a child's spend is its own,
    // never folded into the parent's cost.
    subagents: z
        .object({
            running: z.number().describe("Subagents working right now."),
            total: z.number().describe("Subagents it has started over its whole life."),
        })
        .optional()
        .describe(
            "Subagents this one started, in-process and spawned alike. Absent means it never has, which is most conversations. Their spend is their own and is not folded into this conversation's cost.",
        ),
    // Cumulative output across every repo (base → branch tip), refreshed on each land; independent of what has actually
    // landed.
    diff: z
        .object({
            files: z.number().describe("Files touched."),
            insertions: z.number().describe("Lines added."),
            deletions: z.number().describe("Lines removed."),
        })
        .optional()
        .describe("Everything it has written, measured from where it started. Independent of how much has been merged."),
    // How much of what this agent landed is still in the working tree, since a discard after landing is invisible to
    // commit-based readings; absent is the steady state and carries no line.
    landedPresence: z
        .object({
            landed: z.number().describe("Paths this conversation merged in."),
            present: z.number().describe("How many of them are still there, either pending or committed."),
            // Read off who acted on the tree between the land and the moment it was found missing; only a sole candidate
            // is named, so an unattributed removal says nothing rather than guessing.
            removedBy: z
                .discriminatedUnion("kind", [
                    z.object({
                        kind: z.literal("agent"),
                        id: z.string().describe("The conversation that took them out."),
                        title: z.string().optional().describe("What that conversation is called."),
                    }),
                    z.object({
                        kind: z.literal("person"),
                        email: z.string().optional().describe("Who it was, as the sandbox verified them. Absent when the request carried no identity."),
                        name: z.string().optional().describe("What to call them, when their sign-in carried a name."),
                    }),
                ])
                .optional()
                .describe(
                    "Who took them out, when the sandbox could tell: an agent working in the workspace, or a person throwing the changes away. Absent when it could not tell, and from a sandbox older than it.",
                ),
        })
        .optional()
        .describe(
            "Present only when some of what it merged has since been thrown away. Absent is the steady state: its presence is the signal, so an ordinary card spends no line on it.",
        ),
    // The loop driving this conversation, projected here rather than fetched separately, since a looping agent's status
    // and spend are already the card's own.
    loop: z
        .object({
            state: LoopStateSchema.describe("How the loop is going."),
            iteration: z.number().int().min(0).describe("Which round it is on."),
            maxIterations: z.number().int().min(1).describe("How many rounds it will attempt before giving up."),
            goal: z.string().describe("What it is looping towards."),
        })
        .optional()
        .describe("The loop driving this conversation, if one is. Absent for an ordinary conversation, which is nearly all of them."),
    // Which workflow run and step this conversation is; projected so a multi-step run reads as one job, not unrelated
    // cards started minutes apart.
    workflow: z
        .object({
            runId: z.string().describe("The run this belongs to, which is how a board groups its steps together."),
            name: z.string().describe("The workflow's name."),
            step: z.string().describe("Which step this conversation is on now. It moves when steps are chained."),
            index: z.number().int().min(1).describe("This step's place in the workflow, counting from one."),
            total: z.number().int().min(1).describe("How many steps the workflow has."),
        })
        .optional()
        .describe(
            "The workflow run this conversation is a step of. Without it, a four-step run reads as four unrelated conversations that happen to have started together.",
        ),
    // The one reading of "runs again by itself" (the daemon's awaitingWake, conversation-state.ts): status, fixStance and
    // the card read it, never the watch list, which is only what the card lists. Absent from a daemon older than it.
    awaitingWake: z
        .boolean()
        .optional()
        .describe(
            "Whether this conversation runs again by itself with nobody pressing anything: a watch is armed on it, or words the sandbox or another agent sent wait for it. A finished-looking card that is awaiting a wake is not finished yet.",
        ),
    // Outside conditions a conversation is parked on; a finished-looking card can restart itself when one fires, and an
    // armed watch keeps a hosted machine (and its bill) awake. The check command itself never rides the wire, since it
    // may hold a secret.
    watches: z
        .array(
            z.object({
                id: z.string().describe("The daemon's handle for this watch, the same one the agent was given when it armed it."),
                note: z.string().describe("The agent's own line on what it is waiting for."),
                intervalSeconds: z.number().int().min(1).describe("How often the check runs."),
                deadlineAt: z.number().describe("When it gives up and wakes the conversation anyway, in milliseconds. Every watch has one."),
            }),
        )
        .optional()
        .describe(
            "Outside conditions this conversation is parked on, each of which will wake it. Absent means none, which is nearly every conversation: an armed watch is why a finished-looking agent starts working by itself, and why a hosted machine will not go idle.",
        ),
    // Kept in the needs store, so unlike `jobs` this survives a restart and stands while the conversation is idle.
    needs: z
        .array(AgentNeedSchema)
        .optional()
        .describe(
            "What it is waiting on people for and has not got yet, oldest first. Absent means nothing: an open need is why an idle-looking agent still needs you.",
        ),
    // In memory only: a daemon restart leaves transcript rows naming jobs this list no longer carries.
    jobs: z
        .array(
            z.object({
                id: z.string().describe("The daemon's handle for this job, the one its transcript row names."),
                label: z.string().describe("What the job is, in the agent's own words when it gave any, else its command on one line."),
                session: z.string().describe("The terminal session its pane runs in, which is what opening it focuses."),
                startedAt: z.number().describe("When it started, in milliseconds."),
                endedAt: z.number().optional().describe("When the command exited, in milliseconds. Absent while it runs."),
                exitCode: z.number().int().optional().describe("The code it exited with. Absent while it runs, or when its exit left none."),
                // What the turn that left it running decided about it (agent/tools/jobs/job-fates.ts): one of these, or none
                // while its turn is still going.
                watch: z
                    .string()
                    .optional()
                    .describe(
                        "The watch its exit wakes this conversation through. Present once the turn that left it running has ended and the conversation is waiting on it.",
                    ),
                handed: z
                    .boolean()
                    .optional()
                    .describe(
                        "Left running for the person: the agent kept it for them with the `keep` tool (or it holds a port this conversation already left them), so it outlives the turn, wakes nothing and is theirs to stop.",
                    ),
                ports: z.array(z.number().int()).optional().describe("The ports it was listening on when its turn ended."),
                stoppedBy: z
                    .enum(["turn", "person", "agent"])
                    .optional()
                    .describe(
                        "Who stopped it: the sandbox, when the turn that used it ended without handing it over; a person; or the agent itself. Present from the moment the stop is asked. Absent for a job that exited by itself.",
                    ),
                // agent/tools/jobs/input-wait.ts: told from /proc, never from what it printed, since a prompt can go
                // straight to the terminal or sit in a pipe.
                inputWait: z
                    .object({
                        since: z.number().describe("When it went still, in milliseconds."),
                        program: z.string().describe("The process blocked reading the terminal, as its command line."),
                    })
                    .optional()
                    .describe(
                        "Present while it sits blocked reading its terminal with nothing moving: a prompt nobody in the sandbox will answer, which only stopping it or a person typing into its terminal ends. Absent while it runs on, and once it ends.",
                    ),
            }),
        )
        .optional()
        .describe(
            "Commands this conversation left running in the background, and how the most recent ones ended. Absent means none since the daemon started. A job is running exactly while it has no end.",
        ),
    // Epoch ms it was archived; nothing is lost (branch, transcript, counters stay), and unarchiving re-attaches a
    // fresh worktree from the branch.
    archivedAt: z
        .number()
        .optional()
        .describe(
            "When it was put away, in milliseconds. Nothing was lost: its branch, its record and every counter stayed, and bringing it back gives it a fresh working copy. Absent means it is live on the board.",
        ),
});
export type AgentSummary = z.infer<typeof AgentSummarySchema>;
// Whether a conversation runs again by itself: the daemon's own reading, never guessed from its armed watches.
export const awaitsWake = (agent: { readonly awaitingWake?: boolean | undefined }): boolean => agent.awaitingWake === true;
// One armed watch as a card carries it; derived from AgentSummarySchema.watches so the two shapes can't drift apart.
export type AgentWatch = NonNullable<AgentSummary["watches"]>[number];
// One background job as a card carries it.
export type AgentJob = NonNullable<AgentSummary["jobs"]>[number];
// Who took landed work out of the workspace, as the card names them.
export type LandedRemover = NonNullable<NonNullable<AgentSummary["landedPresence"]>["removedBy"]>;
// A land that broke, kept on the card until one goes through.
export type LandFailure = NonNullable<AgentSummary["landFailure"]>;
// The permission a running turn waits on, as a card can answer it.
export type WaitingPermission = NonNullable<AgentSummary["permissionAsk"]>;
// AgentsListSchema lives in agents-list.ts, since the fleet list carries held wakes (automations.ts).
export const AgentIdSchema = z.object({ id: z.string().min(1).describe("Which conversation.") });

// Naming no watch disarms every one, which is what a press made about the whole card means; a press made about one
// watch's own transcript row names it, and leaves the conversation's other watches armed.
export const AgentStopWatchingSchema = AgentIdSchema.extend({
    watchId: z.string().optional().describe("Which watch to disarm. Absent disarms every watch this conversation is parked on."),
});

export const AgentStopJobSchema = AgentIdSchema.extend({
    jobId: z.string().min(1).describe("Which of its background jobs, by the id its card and transcript row carry."),
});

// Pages a transcript: a read returns its most recent turns and where they start (`from`); handing that back as `before`
// asks for the page above. A stale cursor (a rewind, a fork) is clamped, never refused.
export const AgentTranscriptQuerySchema = AgentIdSchema.extend({
    before: z.coerce
        .number()
        .int()
        .optional()
        .describe("Return the messages before this position in the record: the `from` of the page below. Absent asks for the most recent turns."),
    turns: z.coerce.number().int().min(1).max(200).optional().describe("How many of the user's turns to return, newest first. Absent takes the daemon's default."),
    // Reading forward from the reader's cursor, checked by the row it names: a rewind since reuses positions.
    after: z.coerce
        .number()
        .int()
        .nonnegative()
        .optional()
        .describe(
            "Return what the record holds from this position on: the `through` of the reader's last page. Answered `continuous` when it still runs through there; otherwise with its latest page. Ignored beside `before`.",
        ),
    afterRow: z
        .string()
        .optional()
        .describe("The `rowId` of the row just before `after`, as the reader holds it: how a record rewound since is told apart from one that only grew."),
});

// Fills in what a page counted instead of carrying: a delegation's own calls, addressed by the card's id, which is
// unique within a conversation.
export const AgentToolChildrenQuerySchema = AgentIdSchema.extend({
    toolId: z.string().min(1).describe("Which tool call, by the id its card carries."),
});
export const AgentSubagentQuerySchema = AgentIdSchema.extend({
    subagentId: z.string().min(1).describe("Which subagent this conversation's runtime ran in-process, by the id of the call that started it."),
});
// Absent `ids` archives every archivable finished agent (the lane's "Clear"); unarchive always names its own ids.
export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).max(500).describe("Which conversations.") });
// What actually moved, not the roster afterward: two archives finishing at once would otherwise let a slower snapshot
// resurrect what a faster one just filed away. Whole summaries, since the receiving surfaces (archive list, detail
// page) have to show them, not just their ids.
export const AgentsMovedSchema = z.object({
    moved: z
        .array(AgentSummarySchema)
        .describe(
            "What actually moved, whole, rather than the fleet afterwards. Two archives finishing at once would each carry a snapshot from a different instant, and swapping one in wholesale would let the slower answer resurrect what the faster one just filed away.",
        ),
    rev: z
        .number()
        .describe(
            "The version of the fleet that includes this move, so a caller can hold its own optimistic change until it sees a list at least that new.",
        ),
});
export type AgentsMoved = z.infer<typeof AgentsMovedSchema>;
// Also reports what a release could not do (a deleted repo, a locked checkout); those agents stay on the board with the
// reason they failed, rather than the caller reading silence as "nothing to archive".
export const AgentsArchivedSchema = AgentsMovedSchema.extend({
    failed: z
        .array(
            z.object({
                id: z.string().describe("Which conversation stayed on the board."),
                reason: z.string().describe("Why its working copy could not be released, in the words the failure came with."),
            }),
        )
        .describe("The conversations this press could not put away, each with the reason, so the board can say it instead of reporting silence."),
});
export type AgentsArchived = z.infer<typeof AgentsArchivedSchema>;
// Ids, not summaries: a purged agent no longer exists anywhere, so there's nothing to show. No revision either, since
// archived agents are already off the broadcast roster.
export const AgentsRemovedSchema = z.object({
    removed: z
        .array(z.string())
        .describe(
            "Which conversations were deleted, as ids. Ids rather than whole cards, because these no longer exist anywhere: there is nothing left to show and nothing to put back.",
        ),
});
export type AgentsRemoved = z.infer<typeof AgentsRemovedSchema>;
// The user-chosen display title, bounded like sanitizeTitle's own cap.
export const AgentRenameSchema = z.object({
    id: z.string().min(1).describe("Which conversation."),
    title: z.string().trim().min(1).max(80).describe("What to call it from now on."),
});
// `to` is an address, not a name: authorization and membership both read emails, and a name is not unique.
export const AgentAssignSchema = z.object({
    id: z.string().min(1).describe("Which conversation."),
    to: z.string().trim().toLowerCase().email().describe("Who should answer for it from now on, by the address they sign in with. Must be the sandbox owner or a member."),
});
export type AgentAssign = z.infer<typeof AgentAssignSchema>;
// `on` states the intent rather than flipping whatever is stored: a double press, a retried request and two windows
// racing must all settle the same way, which a toggle cannot promise.
export const AgentReactSchema = z.object({
    id: z.string().min(1).describe("Which conversation."),
    emoji: z
        .string()
        .trim()
        .max(EMOJI_MAX_LENGTH)
        .refine(isSingleEmoji, { message: "not a single emoji" })
        .describe("The mark to leave, as the emoji character itself. Exactly one: a chip has room for one mark, and a press is one press."),
    on: z.boolean().describe("Whether to add your mark or take it back. Saying what you want rather than flipping what is there, so pressing twice lands where pressing once did."),
});
// `null` clears the override back to inheriting the sandbox setting, so an agent doesn't hold a frozen copy that stops
// following it.
export const AgentAutoLandSchema = z.object({
    id: z.string().min(1).describe("Which conversation."),
    autoLand: z
        .boolean()
        .nullable()
        .describe(
            "Whether its work merges automatically when a turn finishes. Null clears the override and goes back to following the sandbox-wide setting, so a conversation does not sit holding a frozen copy of a default it has quietly stopped following.",
        ),
});
// A composer's unsent words, reported by a client that keeps them to itself rather than writing them as a draft.
export const AgentUnsentSchema = z.object({
    id: z.string().min(1).describe("Which conversation."),
    at: z
        .number()
        .nullable()
        .describe("When the composer started holding the unsent message, in milliseconds. Null says it no longer holds one: it was sent or cleared."),
});
// Same `null`-clears-the-override shape as autoLand, for this conversation's own answer to one ending's question.
// One route rather than one per ending: they are the same decision asked about different walls, and three near-identical
// verbs is how the surfaces drifted apart in the first place.
export const AgentBreakPolicySchema = z.object({
    id: z.string().min(1).describe("Which conversation."),
    ending: TurnBreakSchema.describe(
        "Which wall this answers for: a spent usage limit, a provider outage, a turn that stopped short, or a message the sandbox held because it was short of memory.",
    ),
    policy: TurnBreakPolicySchema.nullable().describe(
        "What happens next for that ending. `wait` holds the turn for a press; `retry` re-runs it on a bounded ladder (outage, stop); `resend` sends it again at the published reset (limit) or once memory frees up (memory), and `move` also tries another account with room (limit only). An answer the ending does not allow is refused. Null clears the override and goes back to following the sandbox-wide policy, so a conversation does not sit holding a frozen copy of a default it has quietly stopped following.",
    ),
});
export const AgentFileDiffQuerySchema = z.object({
    id: z.string().min(1).describe("Which conversation."),
    repo: z.string().min(1).describe("Which repository."),
    path: z.string().min(1).describe("Which file, relative to that repository."),
});
export const LandConflictPathSchema = z.object({
    path: z.string().describe("Which file."),
    reason: LandConflictReasonSchema.describe(
        "Why it would not merge, and the three have nothing in common but the symptom. Your own uncommitted edits on that path, where yours is the copy at risk. The shared tree having moved under the conversation since it started, where nothing of yours is at risk. Or a file git cannot merge at all, where no automatic answer exists.",
    ),
});
// `paths` are files that genuinely failed to apply, not the whole delta; empty `paths` with `clean: 0` means the repo
// itself was unreachable.
export const LandConflictSchema = z.object({
    repo: z.string().describe("Which repository."),
    paths: z
        .array(LandConflictPathSchema)
        .describe(
            "The files that genuinely would not apply. Not the whole change: reporting everything whenever the cause could not be pinned down turned four real conflicts into a wall of fourteen.",
        ),
    clean: z
        .number()
        .describe(
            "How many files in this repository passed but remain held with the refused composition. Zero alongside an empty list means the repository could not be reached at all.",
        ),
    // The branch to rebase onto; carried since an isolated turn's worktree hides it from the agent's own view.
    mainBranch: z
        .string()
        .optional()
        .describe(
            "The branch your own checkout is on, which is what the conversation has to rebase onto. Carried because only the sandbox can see it. Absent where there is no name to give.",
        ),
});
export type LandConflict = z.infer<typeof LandConflictSchema>;
// Land's outcome for the whole composed change: the ordinary mode preflights every repo, all-or-nothing, so a refusal
// leaves the tree untouched. `resolving` only appears for a `merge` land, whose conflict markers the user finishes by
// hand.
export const LandResultSchema = z.object({
    landed: z.boolean().describe("Whether the entire composed change was applied."),
    // Merged and nothing moved is the one outcome with nothing to show for itself; without this the caller cannot tell
    // it from a merge that carried work, and a press that did nothing looked exactly like a press that worked.
    changed: z
        .boolean()
        .describe(
            "Whether anything actually moved. False alongside merged means there was nothing on the branch to apply: the work is already in your tree, or the branch never carried any.",
        ),
    conflicts: z.array(LandConflictSchema).optional().describe("What stopped the whole composed change, grouped per repository."),
    resolving: z
        .array(
            z.object({
                repo: z.string().describe("Which repository."),
                paths: z.array(z.string()).describe("Which files now hold conflict markers to sort out by hand."),
            }),
        )
        .optional()
        .describe("Files left half-merged when you asked to carry the whole composition with its conflicts marked for resolution."),
    // A `measure` outcome with work still on the branch; `landed: false` alone can't say that, since alone it means
    // refusal.
    held: z
        .boolean()
        .optional()
        .describe(
            "Nothing was applied and nothing failed: there is work waiting on the branch for a deliberate merge. Not merged on its own cannot say that, because on its own it means refused.",
        ),
});
export type LandResult = z.infer<typeof LandResultSchema>;
// check: safe default, preflights every repo and applies only if all of it does, so a refusal leaves the tree
// byte-identical
// merge: opt-in escape hatch; three-way applies the whole composition, leaving conflict markers to resolve in place
// measure: does everything but touch the main trees, so a held agent's card stays current while its delta waits
export const LandModeSchema = z.enum(["check", "merge", "measure"]);
export type LandMode = z.infer<typeof LandModeSchema>;
// outstanding: only what hasn't landed yet, from the last landed tip (the default; what a second land applies)
// cumulative: the agent's whole output from where its branch left main; what the review lists and what "Land again"
// applies. Not a double application: it's the way back when landed work was discarded from the tree, since paths
// already there drop out per file.
export const AgentSpanSchema = z.enum(["cumulative", "outstanding"]);
export type AgentSpan = z.infer<typeof AgentSpanSchema>;
// Overrides the guard against landing mid-turn; safe since a land arrives as uncommitted changes the user reviews, and
// the rest of the turn lands on top of it later. Doesn't apply to a turn parked on a question, which needs no override
// at all.
export const AgentLandSchema = z.object({
    includeDocuments: z.boolean().optional().describe("Include recorded result documents, even when ignored or classified as scratch."),
    id: z.string().min(1).describe("Which conversation's work to merge."),
    mode: LandModeSchema.optional().describe(
        "How to apply it. The default applies every repository or none, so a refusal leaves the workspace exactly as it was. The other carries the whole composition and leaves conflicted paths with markers to resolve by hand.",
    ),
    span: AgentSpanSchema.optional().describe("How much of the work to take. Leave it out for everything not yet merged."),
    force: z.boolean().optional().describe("Go ahead despite a check that would otherwise refuse."),
});