@saadnvd1/agent-os 0.3.518 → 0.3.520

package/README.md

@@ -539,6 +539,21 @@ and **Usage → Compare** splits cost into planned and not. When the plan step
 finishes, the orchestrator gets one event with the plan file's path and a
 3-5 line summary; the handoff to implementation stays automatic.
 
+**Plan only.** A task started with `plan_only` (`start_task`'s `plan_only`,
+`aos task --plan-only`, or `plan_only: true` on `POST /api/tasks`) writes its
+plan on the planning model and then stops: no model switch, no implement
+prompt, even when one model does every role. It sits in a **Plan ready**
+state (`plan_phase` `awaiting`, stored on the task, so it survives a restart)
+that isn't blocked, doesn't count as needing you, and holds no agent process
+(its worker is released; the conversation resumes on approval). The
+orchestrator gets one event with the plan's path, a summary and that the task
+is waiting. **Approve** on the task row (plan viewable there), `POST
+/api/tasks/<id>/approve-plan`, or the orchestrator's `approve_plan(task,
+message?)` continues it on the implementation model, once; a message amends
+the plan and is recorded on the task's brief as a scope change, so the review
+judges against it. Reject with **Drop**. A chat task on this machine only; it
+can't move until approved.
+
 **Per task.** The task draft has a **Model** chip ("Routed by role", or one
 model); `POST /api/tasks` and the orchestrator's `start_task` take `model`, as
 `"provider/model"` for the task's own roles or a map such as
@@ -1587,7 +1602,10 @@ Once linked:
   judging the PR at its head, reads BLOCKED lines and open approvals from the
   task's chat there, and gets PR, CI, idle and plan events by polling that
   machine. Its messages arrive marked as from the orchestrator, never as
-  yours. Guards (write guard, shell deny list, attribution settings) run in
+  yours. The task can `aos send` its orchestrator back: the machine it runs
+  on only stores the message, and the orchestrator's machine pulls it and
+  delivers it as that task's own. Moving it back stops its agent there and
+  removes its worktree when nothing in it would be lost. Guards (write guard, shell deny list, attribution settings) run in
   the task's worker on either machine, and the task can't merge or push to
   the default branch. Moving counts toward the brakes and Pause refuses the
   tool.

package/app/api/bus/peers/route.ts

@@ -1,10 +1,16 @@
 import { NextRequest, NextResponse } from "next/server";
-import { listPeers, resolveTarget } from "@/lib/bus";
+import { listPeers, resolveHeldOrchestrator, resolveTarget } from "@/lib/bus";
 
 // ?ref=<name>: just the session that name reaches, the way aos send would.
 export async function GET(request: NextRequest) {
   const ref = request.nextUrl.searchParams.get("ref");
-  if (ref === null) return NextResponse.json({ peers: await listPeers() });
+  // from: the asking session, which a held task needs for its orchestrator.
+  const from = request.nextUrl.searchParams.get("from") ?? "";
+  if (ref === null)
+    return NextResponse.json({ peers: await listPeers(from || undefined) });
+  const held = from ? resolveHeldOrchestrator(from, ref) : null;
+  if (held)
+    return NextResponse.json({ peer: { id: held.id, name: held.name } });
   try {
     const { session, note } = resolveTarget(ref);
     return NextResponse.json({

package/app/api/bus/spawn/route.ts

@@ -29,12 +29,15 @@ export async function POST(request: NextRequest) {
       on,
       after,
       view,
+      planOnly,
       from,
     } = await request.json();
     const startedBy = orchestratorFrom(from);
     const given = typeof name === "string" ? name : undefined;
     if (after !== undefined && mode !== "task")
       throw new Error("--after works for tasks only");
+    if (planOnly !== undefined && mode !== "task")
+      throw new Error("--plan-only works for tasks only");
     if (mode === "task") {
       const task = {
         projectId: findProject(String(project ?? "")).id,
@@ -43,6 +46,7 @@ export async function POST(request: NextRequest) {
         model,
         hostId: on ? hostIdNamed(String(on)) : undefined,
         view: startView(view),
+        planOnly: planOnly === true ? true : undefined,
         startedBy,
       };
       const out = await startOrQueue(

package/app/api/tasks/[id]/approve-plan/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { approvePlanNow } from "@/lib/models/plan-step";
+
+// Approves a plan-only task's plan: it continues on the implementation
+// model. An optional message amends the plan (recorded as a scope change).
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const body = await request.json().catch(() => ({}));
+    const message =
+      typeof body?.message === "string" && body.message.trim()
+        ? body.message.trim().slice(0, 8000)
+        : undefined;
+    const out = await approvePlanNow((await params).id, message);
+    return NextResponse.json({ success: true, model: out.ref });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 409 });
+  }
+}

package/app/api/tasks/[id]/chat-facts/route.ts

@@ -0,0 +1,21 @@
+import { NextRequest } from "next/server";
+import { blockedReason } from "@/lib/tasks/state";
+import { saidSinceLastMessage } from "@/lib/chat/store";
+import { chatStateNow } from "@/lib/chat/runner";
+import { heldRoute } from "@/lib/tasks/held-routes";
+
+// GET /api/tasks/:id/chat-facts - what its chat says about being blocked
+// and whether a question is open, for the orchestrator that moved it here.
+// Cheap (no PR lookups), unlike the whole task list.
+export async function GET(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  return heldRoute(request, ctx, async (task) => {
+    if (task.view !== "chat") return { blocked: null, turn: null };
+    return {
+      blocked: blockedReason(saidSinceLastMessage(task.id)),
+      turn: await chatStateNow(task.id).catch(() => "unknown"),
+    };
+  });
+}

package/app/api/tasks/[id]/moved/route.ts

@@ -2,6 +2,8 @@ import { NextRequest, NextResponse } from "next/server";
 import { markMoved } from "@/lib/tasks/move";
 import { callingDevice } from "@/lib/security/device-me";
 import { heldRefusal } from "@/lib/tasks/held";
+import { cleanUpMovedAway } from "@/lib/tasks/moved-away";
+import { runInBackground } from "@/lib/async-operations";
 
 // POST /api/tasks/:id/moved - the task now runs on the machine named `to`
 export async function POST(
@@ -13,5 +15,10 @@ export async function POST(
   if (held) return NextResponse.json({ error: held }, { status: 403 });
   const { to } = await request.json().catch(() => ({}));
   markMoved(id, String(to || "another machine").slice(0, 100));
+  // A task its orchestrator took back: its agent and worktree here go.
+  if (held === null)
+    runInBackground(async () => {
+      await cleanUpMovedAway(id);
+    }, `moved-away-${id}`);
   return NextResponse.json({ success: true });
 }

package/app/api/tasks/held-replies/route.ts

@@ -0,0 +1,31 @@
+import { NextRequest, NextResponse } from "next/server";
+import { callingDevice } from "@/lib/security/device-me";
+import { ackReplies, pendingReplies } from "@/lib/bus/held-reply";
+
+// GET /api/tasks/held-replies - what the tasks this device moved here have
+// said to their orchestrator, for it to deliver there. Only that device's.
+export async function GET(request: NextRequest) {
+  const device = callingDevice(request);
+  if (!device)
+    return NextResponse.json(
+      { error: "Needs a paired device" },
+      { status: 403 }
+    );
+  return NextResponse.json({ messages: pendingReplies(device) });
+}
+
+// POST { ids } - those are delivered; they are not offered again.
+export async function POST(request: NextRequest) {
+  const device = callingDevice(request);
+  if (!device)
+    return NextResponse.json(
+      { error: "Needs a paired device" },
+      { status: 403 }
+    );
+  const { ids } = await request.json().catch(() => ({}));
+  const list = (Array.isArray(ids) ? ids : []).filter((n): n is number =>
+    Number.isSafeInteger(n)
+  );
+  ackReplies(device, list.slice(0, 200));
+  return NextResponse.json({ success: true });
+}

package/app/api/tasks/route.ts

@@ -36,6 +36,7 @@ export async function POST(request: NextRequest) {
       view,
       plan,
       plan_reason,
+      plan_only,
     } = await request.json();
     if (id !== undefined && !isSessionId(id)) throw new Error("Bad task id");
     const pid =
@@ -48,6 +49,7 @@ export async function POST(request: NextRequest) {
       // Checked now, so a queued task can't fail on it later.
       model: parseOverride(model) ?? undefined,
       plan: typeof plan === "boolean" ? plan : undefined,
+      planOnly: plan_only === true ? true : undefined,
       planReason:
         typeof plan_reason === "string" && plan_reason.trim()
           ? plan_reason.trim().slice(0, 200)

package/components/Tasks/TaskRow.tsx

@@ -10,7 +10,13 @@ import {
 import { Button } from "@/components/ui/button";
 import type { TaskView } from "@/lib/tasks";
 import { isFinished } from "@/lib/tasks/state";
-import { useArmTask, useDropTask, useSignOffTask } from "@/data/tasks";
+import {
+  useApprovePlan,
+  useArmTask,
+  useDropTask,
+  useSignOffTask,
+} from "@/data/tasks";
+import { Markdown } from "@/components/Chat/Markdown";
 import { tmuxAttachActions } from "@/stores/tmuxAttach";
 import { tasksUiActions } from "@/stores/tasksUi";
 import { cn } from "@/lib/utils";
@@ -23,6 +29,8 @@ export function TaskRow({ task }: { task: TaskView }) {
   const signOff = useSignOffTask();
   const drop = useDropTask();
   const arm = useArmTask();
+  const approve = useApprovePlan();
+  const [showPlan, setShowPlan] = useState(false);
   const [confirmDrop, setConfirmDrop] = useState(false);
   const [moveError, setMoveError] = useState<string | null>(null);
   const live = !isFinished(task.state);
@@ -30,6 +38,7 @@ export function TaskRow({ task }: { task: TaskView }) {
     signOff.error?.message ||
     drop.error?.message ||
     arm.error?.message ||
+    approve.error?.message ||
     moveError ||
     task.hostError;
   const settingUp = live && task.setup?.status === "running";
@@ -148,6 +157,26 @@ export function TaskRow({ task }: { task: TaskView }) {
               {task.armed ? "Armed" : "Arm merge"}
             </Button>
           )}
+          {task.state === "plan-ready" && (
+            <>
+              <Button
+                size="sm"
+                variant="outline"
+                aria-expanded={showPlan}
+                onClick={() => setShowPlan((v) => !v)}
+              >
+                {showPlan ? "Hide plan" : "View plan"}
+              </Button>
+              <Button
+                size="sm"
+                className="h-11 md:h-8"
+                disabled={approve.isPending}
+                onClick={() => approve.mutate({ id: task.id })}
+              >
+                {approve.isPending ? "Approving..." : "Approve"}
+              </Button>
+            </>
+          )}
           {task.state === "review" && (
             <Button
               size="sm"
@@ -159,6 +188,22 @@ export function TaskRow({ task }: { task: TaskView }) {
           )}
         </div>
       )}
+      {live && task.state === "plan-ready" && showPlan && (
+        <div className="bg-foreground/[0.04] max-h-80 overflow-y-auto rounded-lg p-3 text-sm">
+          {task.plan?.text ? (
+            <Markdown text={task.plan.text} />
+          ) : (
+            <p className="text-muted-foreground text-xs">
+              No plan file was written.
+            </p>
+          )}
+          {task.plan?.truncated && (
+            <p className="text-muted-foreground mt-2 font-mono text-[11px]">
+              Shortened; the whole plan is {task.plan.path} in the worktree.
+            </p>
+          )}
+        </div>
+      )}
       {error && <p className="text-destructive text-xs">{error}</p>}
     </div>
   );

package/components/Tasks/task-state-labels.ts

@@ -8,6 +8,7 @@ export const TASK_STATE: Record<TaskState, { label: string; tone: string }> = {
     tone: "text-amber-600 dark:text-amber-400",
   },
   blocked: { label: "Blocked", tone: "text-amber-600 dark:text-amber-400" },
+  "plan-ready": { label: "Plan ready", tone: "text-primary" },
   review: { label: "Ready for review", tone: "text-primary" },
   "checks-failing": { label: "Checks failing", tone: "text-destructive" },
   exited: { label: "Agent exited", tone: "text-amber-600 dark:text-amber-400" },

package/data/tasks/index.ts

@@ -85,6 +85,18 @@ export function useDropTask() {
   );
 }
 
+export function useApprovePlan() {
+  return useTaskMutation(async (input: { id: string; message?: string }) =>
+    json(
+      await fetch(`/api/tasks/${input.id}/approve-plan`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: input.message }),
+      })
+    )
+  );
+}
+
 export function useResumeTask() {
   return useTaskMutation(async (input: { id: string; force?: boolean }) =>
     json(

package/lib/bus/held-reply.ts

@@ -0,0 +1,89 @@
+/**
+ * A task its orchestrator moved here has no orchestrator on this machine to
+ * message, and this machine never reaches back to the one that holds it. Its
+ * message to the orchestrator is only stored here (relay_state 'pending');
+ * the holder pulls it (lib/tasks/held-replies.ts) and delivers it there as
+ * that task's own. This machine never delivers or attributes it, and the
+ * holder, not the sender, says who receives it.
+ */
+
+import { db, type Session } from "../db";
+import { resolveRef } from "./resolve";
+
+export interface HeldOrchestrator {
+  id: string;
+  name: string;
+  heldFrom: string;
+}
+
+/** The orchestrator a running held task messages, or null. */
+export function heldOrchestrator(
+  s: Session | undefined
+): HeldOrchestrator | null {
+  if (
+    !s ||
+    !s.held_by_device ||
+    !s.held_for ||
+    !s.held_for_name ||
+    s.task_status !== "running"
+  )
+    return null;
+  return {
+    id: s.held_for,
+    name: s.held_for_name,
+    heldFrom: s.held_from || "another machine",
+  };
+}
+
+/** The orchestrator `ref` names for this held sender: its name, id prefix or "orchestrator". */
+export function heldTarget(
+  from: Session | undefined,
+  ref: string
+): HeldOrchestrator | null {
+  const o = from && heldOrchestrator(from);
+  if (!o) return null;
+  if (ref.trim().toLowerCase() === "orchestrator") return o;
+  const r = resolveRef(ref, [
+    {
+      id: o.id,
+      name: o.name,
+      projectName: null,
+      tmuxName: "",
+      previousNames: [],
+    },
+  ]);
+  return r.ok ? o : null;
+}
+
+export interface PendingReply {
+  id: number;
+  fromId: string;
+  body: string;
+  createdAt: string;
+}
+
+/** What the calling device's held tasks have said to their orchestrators. */
+export function pendingReplies(device: string, limit = 50): PendingReply[] {
+  return (
+    db
+      .prepare(
+        `SELECT m.id, m.from_id AS fromId, m.body, m.created_at AS createdAt
+         FROM bus_messages m JOIN sessions s ON s.id = m.from_id
+         WHERE m.relay_state = 'pending' AND s.held_by_device = ?
+         ORDER BY m.id LIMIT ?`
+      )
+      .all(device, limit) as PendingReply[]
+  ).map((r) => ({ ...r, id: Number(r.id) }));
+}
+
+/** Marks them pulled; only the device's own are touched. */
+export function ackReplies(device: string, ids: number[]): void {
+  const mark = db.prepare(
+    `UPDATE bus_messages SET relay_state = 'relayed', delivered_at = datetime('now')
+     WHERE id = ? AND relay_state = 'pending'
+       AND from_id IN (SELECT id FROM sessions WHERE held_by_device = ?)`
+  );
+  db.transaction(() => {
+    for (const id of ids) mark.run(id, device);
+  })();
+}

package/lib/bus/index.ts

@@ -16,6 +16,7 @@ import { resolveRef, wasNames, type Candidate } from "./resolve";
 import { tmuxPane } from "./tmux-pane";
 import { hostLink } from "../hosts/remote-api";
 import { relayToHeldTask } from "../tasks/held-remote";
+import { heldOrchestrator, heldTarget } from "./held-reply";
 import { HUMAN, overRateLimit, wakeLine, type BusMessageView } from "./format";
 
 export * from "./format";
@@ -54,11 +55,21 @@ function candidates(sessions: Session[]): Candidate[] {
   }));
 }
 
-export async function listPeers(): Promise<Peer[]> {
+const sessionById = (id: string | null | undefined) =>
+  id
+    ? (db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id) as
+        | Session
+        | undefined)
+    : undefined;
+
+// `callerId`: the asking session. A task its orchestrator moved here also
+// sees that orchestrator, which it can message though it runs elsewhere.
+export async function listPeers(callerId?: string): Promise<Peer[]> {
   await statusDetector.refreshCache();
   const sessions = liveSessions();
   const named = candidates(sessions);
-  return Promise.all(
+  const orchestrator = heldOrchestrator(sessionById(callerId));
+  const listed = await Promise.all(
     sessions.map(async (s, i) => {
       const status = statusDetector.sessionExists(s.tmux_name)
         ? await statusDetector.getStatus(s.tmux_name)
@@ -76,6 +87,25 @@ export async function listPeers(): Promise<Peer[]> {
       };
     })
   );
+  if (!orchestrator) return listed;
+  return [
+    ...listed,
+    {
+      id: orchestrator.id,
+      name: orchestrator.name,
+      was: [],
+      projectName: null,
+      tmuxName: "",
+      hostId: "remote",
+      running: true,
+      doing: `your orchestrator, on ${orchestrator.heldFrom}`,
+    },
+  ];
+}
+
+// The orchestrator a held caller's ref names, if it names it.
+export function resolveHeldOrchestrator(callerId: string, ref: string) {
+  return heldTarget(sessionById(callerId), ref);
 }
 
 // A live session by name, old name, project/name, id or id prefix. The note
@@ -208,16 +238,18 @@ export async function sendMessage(opts: {
   // It's never left unread for `aos inbox` to show in another form; a
   // failed one is the sender's to retry.
   line?: string;
+  // A message pulled from a linked machine, by its key there: one already
+  // stored is not stored or delivered again.
+  relayKey?: string;
 }): Promise<{ message: BusMessageView; delivery: Delivery; note?: string }> {
   const body = opts.body.trim();
   if (!body) throw new Error("Message is empty");
-  const { session: to, note } = resolveTarget(opts.to);
-  const from = opts.fromId
-    ? (db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(opts.fromId) as
-        | Session
-        | undefined)
-    : undefined;
+  const from = sessionById(opts.fromId);
   if (opts.fromId && !from) throw new Error("Unknown sender session");
+  // A held task's message to its orchestrator is kept for the holder to pull.
+  const held = heldTarget(from, opts.to);
+  if (from && held) return storeForHolder(from, held, body);
+  const { session: to, note } = resolveTarget(opts.to);
   if (from && from.id === to.id)
     throw new Error("A session can't message itself");
   if (from && overRateLimit(pairTimestamps(from.id, to.id))) {
@@ -225,13 +257,32 @@ export async function sendMessage(opts: {
       `Too many messages between ${from.name} and ${to.name}; wait a few minutes`
     );
   }
+  if (opts.relayKey) {
+    const seen = db
+      .prepare(`SELECT id FROM bus_messages WHERE relay_key = ?`)
+      .get(opts.relayKey) as { id: number } | undefined;
+    if (seen)
+      return {
+        message: toView(
+          db.prepare(`${SELECT} WHERE m.id = ?`).get(seen.id) as Row
+        ),
+        delivery: { state: "delivered" },
+      };
+  }
 
   const fromName = from?.name ?? opts.fromLabel ?? HUMAN;
   const { lastInsertRowid } = db
     .prepare(
-      `INSERT INTO bus_messages (from_id, from_name, to_id, to_name, body) VALUES (?, ?, ?, ?, ?)`
+      `INSERT INTO bus_messages (from_id, from_name, to_id, to_name, body, relay_key) VALUES (?, ?, ?, ?, ?, ?)`
     )
-    .run(from?.id ?? null, fromName, to.id, to.name, body);
+    .run(
+      from?.id ?? null,
+      fromName,
+      to.id,
+      to.name,
+      body,
+      opts.relayKey ?? null
+    );
   const id = Number(lastInsertRowid);
 
   await statusDetector.refreshCache();
@@ -260,6 +311,31 @@ export async function sendMessage(opts: {
   return { message, delivery, note };
 }
 
+function storeForHolder(
+  from: Session,
+  to: { id: string; name: string; heldFrom: string },
+  body: string
+) {
+  if (overRateLimit(pairTimestamps(from.id, to.id)))
+    throw new Error(
+      `Too many messages between ${from.name} and ${to.name}; wait a few minutes`
+    );
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO bus_messages (from_id, from_name, to_id, to_name, body, relay_state)
+       VALUES (?, ?, ?, ?, ?, 'pending')`
+    )
+    .run(from.id, from.name, to.id, to.name, body);
+  const message = toView(
+    db.prepare(`${SELECT} WHERE m.id = ?`).get(Number(lastInsertRowid)) as Row
+  );
+  return {
+    message,
+    delivery: { state: "queued" as const },
+    note: `${to.name} runs on ${to.heldFrom}: it gets this when that machine next checks in, within a few seconds`,
+  };
+}
+
 // Unread messages for a session, marked read as they're returned.
 export function readInbox(sessionId: string): BusMessageView[] {
   const rows = db

package/lib/db/migrations.ts

@@ -1714,6 +1714,46 @@ const migrations: Migration[] = [
         add(col);
     },
   },
+  {
+    id: 74,
+    name: "held_task_replies",
+    up: (db) => {
+      // held_for / held_for_name: the orchestrator (id, name there) a held
+      // task messages. relay_state: a held task's message to it, waiting for
+      // the holder to pull it (pending) or pulled (relayed). relay_key: a
+      // pulled message's key on the orchestrator's machine, so a repeat pull
+      // is not delivered twice.
+      const has = (table: string, col: string) =>
+        (
+          db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]
+        ).some((c) => c.name === col);
+      for (const col of ["held_for", "held_for_name"])
+        if (!has("sessions", col))
+          db.exec(`ALTER TABLE sessions ADD COLUMN ${col} TEXT`);
+      for (const col of ["relay_state", "relay_key"])
+        if (!has("bus_messages", col))
+          db.exec(`ALTER TABLE bus_messages ADD COLUMN ${col} TEXT`);
+      db.exec(
+        `CREATE UNIQUE INDEX IF NOT EXISTS idx_bus_relay_key ON bus_messages(relay_key) WHERE relay_key IS NOT NULL;
+         CREATE INDEX IF NOT EXISTS idx_bus_relay_pending ON bus_messages(relay_state) WHERE relay_state = 'pending'`
+      );
+    },
+  },
+  {
+    id: 75,
+    name: "plan_only_tasks",
+    up: (db) => {
+      // plan_only: 1 for a task that stops after its plan and waits for
+      // approval (plan_phase 'awaiting'); queued tasks keep it until they start.
+      const has = (table: string) =>
+        (
+          db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]
+        ).some((c) => c.name === "plan_only");
+      for (const table of ["sessions", "task_queue"])
+        if (!has(table))
+          db.exec(`ALTER TABLE ${table} ADD COLUMN plan_only INTEGER`);
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/db/types.ts

@@ -19,7 +19,9 @@ export interface Session {
   // A task's own models: "provider/model", or JSON of role to one.
   model_overrides?: string | null;
   // A task's plan step: planning on the planning model, then implementing.
-  plan_phase?: "planning" | "implementing" | null;
+  // 'awaiting': a plan-only task's plan is written; it waits for approval.
+  plan_phase?: "planning" | "awaiting" | "implementing" | null;
+  plan_only?: number | null;
   // The orchestrator session that started this one; null for a person.
   started_by?: string | null;
   // 1 planned, 0 no plan, null not stated; why, in the starter's words.
@@ -124,6 +126,8 @@ export interface Session {
   // The device and machine of the orchestrator that moved this task here.
   held_by_device?: string | null;
   held_from?: string | null;
+  held_for?: string | null;
+  held_for_name?: string | null;
   // A held task's "plan written" line, for its orchestrator to read.
   plan_note?: string | null;
   // Orchestration fields