@iowarp/clio-coder 0.3.1 → 0.3.3

package/dist/chunk-DUYJ5IO6.js

@@ -0,0 +1,644 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  DISPATCH_BRIEFING_MAX_BYTES,
+  TOOL_PROFILE_NAMES,
+  classifyAgentTask,
+  cloneApprovedAssignmentRoute,
+  isApprovedAssignmentRoute,
+  isToolProfileName
+} from "./chunk-LWLEKMDQ.js";
+import {
+  ROUTE_POLICY_VERSION,
+  isExecutionRole,
+  isRouteDecisionAgentSelection,
+  isRoutingIntent,
+  parseRoutingIntent,
+  requestExecutionRole
+} from "./chunk-GGXXDWE4.js";
+import {
+  AGENT_AUTOMATION_AUTHORITIES
+} from "./chunk-5UUP6MWO.js";
+import {
+  init_esm_shims
+} from "./chunk-3R73A4XB.js";
+
+// src/tools/dispatch-plan.ts
+init_esm_shims();
+import { createHash } from "node:crypto";
+
+// src/tools/dispatch-arguments.ts
+init_esm_shims();
+var DEFAULT_AGENT_ID = "coder";
+var AUTO_BASELINE_BY_TASK_TYPE = {
+  // Mutating shapes: capability class first, specialization second.
+  code_write: "coder",
+  debug: "coder",
+  refactor: "coder",
+  config: "coder",
+  test: "tester",
+  docs: "documenter",
+  // Read-only shapes.
+  code_review: "verifier",
+  research: "researcher",
+  code_read: "scout",
+  unknown: "scout"
+};
+var AUTO_BASELINE_FALLBACK_AGENT_ID = "scout";
+function autoBaselineAgentId(task, hasAgent) {
+  const mapped = AUTO_BASELINE_BY_TASK_TYPE[classifyAgentTask(task).taskType] ?? AUTO_BASELINE_FALLBACK_AGENT_ID;
+  if (hasAgent === void 0) return mapped;
+  if (hasAgent(mapped)) return mapped;
+  if (hasAgent(AUTO_BASELINE_FALLBACK_AGENT_ID)) return AUTO_BASELINE_FALLBACK_AGENT_ID;
+  return mapped;
+}
+var DEFAULT_MAX_OUTPUT_BYTES = 2e4;
+var PERSONA_MAX_CHARS = 8e3;
+var THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+var VALID_THINKING = new Set(THINKING_LEVELS);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringArg(args, ...names) {
+  for (const name of names) {
+    const value = args[name];
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+  }
+  return void 0;
+}
+function maxOutputBytesArg(args) {
+  const value = args.max_output_bytes;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : DEFAULT_MAX_OUTPUT_BYTES;
+}
+function timeoutMsArg(args) {
+  const value = args.timeout_ms;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : void 0;
+}
+function dispatchRequestFromArgs(args, options) {
+  const task = stringArg(args, "task");
+  if (!task) return { ok: false, message: "missing task (pass list:true to see available agents)" };
+  if (Object.hasOwn(args, "agent_id")) return { ok: false, message: "agent_id is unsupported; use agent" };
+  const requestedAgent = stringArg(args, "agent") ?? DEFAULT_AGENT_ID;
+  const auto = requestedAgent === "auto";
+  const agentId = auto ? autoBaselineAgentId(task, options.hasAgent) : requestedAgent;
+  const request = {
+    agentId,
+    executionRole: requestExecutionRole({
+      agentId,
+      ...options.resolveFacts ? { resolveFacts: options.resolveFacts } : {}
+    }),
+    task,
+    ...auto ? {
+      agentSelection: {
+        version: 1,
+        mode: "auto",
+        baselineAgentId: agentId,
+        approvedAuthorities: [...options.auto.approvedAuthorities],
+        authorityBasis: options.auto.authorityBasis
+      }
+    } : {}
+  };
+  if ("briefing" in args && args.briefing !== void 0) {
+    if (typeof args.briefing !== "string") return { ok: false, message: "briefing must be a string" };
+    const briefing = args.briefing.trim();
+    if (Buffer.byteLength(briefing, "utf8") > DISPATCH_BRIEFING_MAX_BYTES) {
+      return { ok: false, message: `briefing must be ${DISPATCH_BRIEFING_MAX_BYTES} UTF-8 bytes or fewer` };
+    }
+    if (briefing.length > 0) request.briefing = briefing;
+  }
+  const target = stringArg(args, "target");
+  if (target) request.target = target;
+  const model = stringArg(args, "model");
+  if (model) request.model = model;
+  const node = stringArg(args, "node");
+  if (node) request.node = node;
+  if (args.failover !== void 0 || args.allowed_candidates !== void 0 || args.allowedCandidates !== void 0) {
+    return { ok: false, message: "use routing.failover; model-authored candidate envelopes are not accepted" };
+  }
+  const routing = parseRoutingIntent(args.routing, {
+    ...target ? { target } : {},
+    ...model ? { model } : {},
+    ...node ? { node } : {}
+  });
+  if (!routing.ok) return { ok: false, message: routing.errors.join("; ") };
+  request.routingIntent = routing.intent;
+  request.failover = routing.intent.failover;
+  request.requiredCapabilities = routing.intent.requiredCapabilities;
+  const cwd = stringArg(args, "cwd");
+  if (cwd) request.cwd = cwd;
+  if ("persona" in args && args.persona !== void 0) {
+    if (typeof args.persona !== "string") return { ok: false, message: "persona must be a string" };
+    const persona = args.persona.trim();
+    if (persona.length > PERSONA_MAX_CHARS) {
+      return { ok: false, message: `persona must be ${PERSONA_MAX_CHARS} characters or fewer` };
+    }
+    if (persona.length > 0) request.systemPrompt = persona;
+  }
+  const toolProfile = stringArg(args, "tool_profile");
+  if (toolProfile) {
+    if (!isToolProfileName(toolProfile)) {
+      return { ok: false, message: `tool_profile must be one of ${TOOL_PROFILE_NAMES.join("|")}` };
+    }
+    request.toolProfile = toolProfile;
+  }
+  const thinkingLevel = stringArg(args, "thinking_level");
+  if (thinkingLevel) {
+    if (!VALID_THINKING.has(thinkingLevel)) {
+      return { ok: false, message: "thinking_level must be one of off|minimal|low|medium|high|xhigh|max" };
+    }
+    request.thinkingLevel = thinkingLevel;
+  }
+  return { ok: true, request };
+}
+function dispatchRequestsFromArgs(args, options) {
+  if (Object.hasOwn(args, "task") && Object.hasOwn(args, "tasks")) {
+    return { ok: false, message: "dispatch: pass either task for one run or tasks for a batch, not both" };
+  }
+  const tasks = args.tasks;
+  if (!Array.isArray(tasks) || tasks.length === 0) {
+    return {
+      ok: false,
+      message: args.tasks === void 0 ? 'dispatch: missing task; pass task="..." for one run or tasks=[...] for a batch. briefing is optional context and cannot replace task. Example: {"agent":"auto","task":"map the modules that read fleet config and cite file paths"}' : "dispatch: tasks must be a non-empty array of task strings or {agent, task} objects"
+    };
+  }
+  const shared = { ...args };
+  Reflect.deleteProperty(shared, "tasks");
+  const requests = [];
+  for (let index = 0; index < tasks.length; index += 1) {
+    const item = tasks[index];
+    const itemArgs = isRecord(item) ? { ...shared, ...item } : { ...shared, task: item };
+    const parsed = dispatchRequestFromArgs(itemArgs, options);
+    if (!parsed.ok) return { ok: false, message: `dispatch: task ${index + 1}: ${parsed.message}` };
+    requests.push(parsed.request);
+  }
+  return { ok: true, requests };
+}
+function prepareDispatchArguments(args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) return args;
+  const next = { ...args };
+  if (typeof next.tasks === "string") {
+    const raw = next.tasks.trim();
+    if (raw.startsWith("[") || raw.startsWith("{")) {
+      try {
+        next.tasks = JSON.parse(raw);
+      } catch {
+      }
+    }
+  }
+  if (isRecord(next.tasks)) next.tasks = [next.tasks];
+  if (typeof next.tasks === "string") next.tasks = [next.tasks];
+  if (next.tasks === void 0 && typeof next.task === "string") {
+    const { task: _task, ...rest } = next;
+    return { ...rest, tasks: [{ task: next.task }] };
+  }
+  return next;
+}
+
+// src/tools/dispatch-plan.ts
+var RESOLVED_DISPATCH_PLAN_ARGUMENT = "__clio_resolved_dispatch_plan";
+var DISPATCH_PLAN_PREPARATION_ERROR_ARGUMENT = "__clio_dispatch_plan_preparation_error";
+function withResolvedPlanTaskPin(request, task, options = {}) {
+  if (task === void 0) return request;
+  const {
+    briefing: _briefing,
+    failover: _failover,
+    allowedCandidates: _candidates,
+    agentSelection: _agentSelection,
+    routeApproval: _approval,
+    assignmentDeadlineAt: _deadline,
+    executionRole: _executionRole,
+    ...base
+  } = request;
+  return {
+    ...base,
+    agentId: task.agent,
+    executionRole: task.executionRole,
+    ...request.reservation !== void 0 && (task.stepId !== null || task.role !== void 0 && task.position !== void 0) ? {
+      reservation: {
+        ownerId: request.reservation.ownerId,
+        memberId: task.stepId ?? `${task.role}-${task.position}`
+      }
+    } : {},
+    routingIntent: structuredClone(task.routingIntent),
+    failover: task.failover,
+    ...task.agentSelection === null ? {} : { agentSelection: structuredClone(task.agentSelection) },
+    ...task.routeApproval === null ? {} : { routeApproval: cloneApprovedAssignmentRoute(task.routeApproval) },
+    ...task.allowedCandidates === void 0 ? {} : { allowedCandidates: task.allowedCandidates.map((candidate) => ({ ...candidate })) },
+    task: options.pinTask === false ? request.task : task.task,
+    ...task.briefing !== void 0 ? { briefing: task.briefing } : {},
+    target: task.target,
+    model: task.model,
+    node: task.node,
+    plannedNode: {
+      id: task.node,
+      kind: task.nodeKind,
+      ...task.nodeHost !== void 0 ? { host: task.nodeHost } : {}
+    }
+  };
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function str(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function safeField(value) {
+  let result = "";
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    result += code < 32 || code >= 127 && code <= 159 ? "?" : character;
+    if (result.length >= 256) return `${result.slice(0, 255)}\u2026`;
+  }
+  return result;
+}
+function taskViews(args) {
+  const tasks = Array.isArray(args.tasks) ? args.tasks : [];
+  const sharedAgent = str(args.agent) ?? "coder";
+  const sharedModel = str(args.model);
+  const sharedNode = str(args.node);
+  const sharedTarget = str(args.target);
+  return tasks.map((item) => {
+    const record = isRecord2(item) ? item : {};
+    const view = {
+      agent: str(record.agent) ?? sharedAgent,
+      task: str(item) ?? str(record.task) ?? "(invalid task)",
+      routeApproval: null,
+      agentSelection: null,
+      stepId: null,
+      dependencies: [],
+      executionRole: "builder",
+      expectedResultContract: null,
+      authorityGrant: null,
+      agentDecision: null,
+      wave: null
+    };
+    const briefing = "briefing" in record ? str(record.briefing) : str(args.briefing);
+    if (briefing !== void 0) view.briefing = briefing;
+    const model = str(record.model) ?? sharedModel;
+    if (model !== void 0) view.model = model;
+    const node = str(record.node) ?? sharedNode;
+    if (node !== void 0) view.node = node;
+    const target = str(record.target) ?? sharedTarget;
+    if (target !== void 0) view.target = target;
+    const failover = failoverModeOf(record.failover) ?? failoverModeOf(args.failover);
+    if (failover !== void 0) view.failover = failover;
+    const rawCandidates = "allowedCandidates" in record ? record.allowedCandidates : args.allowedCandidates;
+    const candidates = canonicalCandidates(rawCandidates);
+    if (failover === "approved" && candidates !== null) view.allowedCandidates = candidates;
+    return view;
+  });
+}
+function failoverModeOf(value) {
+  return value === "none" || value === "approved" ? value : void 0;
+}
+function canonicalCandidates(value) {
+  if (!Array.isArray(value)) return null;
+  const out = [];
+  for (const item of value) {
+    if (!isRecord2(item)) return null;
+    const agentId = str(item.agentId);
+    const target = str(item.target);
+    const model = str(item.model);
+    const node = str(item.node);
+    if (!agentId || !target || !model || !node) return null;
+    out.push({ agentId, target, model, node });
+  }
+  return out.length > 0 ? out : null;
+}
+function topologyOf(args) {
+  if (isRecord2(args.apply_winner)) return "compete";
+  if (args.mode === "compete") return "compete";
+  if (args.review === true || isRecord2(args.review)) return "review";
+  if (args.detach === true) return "detached";
+  if (args.mode === "sequential") return "sequential";
+  if (args.mode === "pipeline") return "pipeline";
+  return "parallel";
+}
+function renderPlanText(topology, tasks, costCeilingUsd, deadlineMs, source, maxWorkers, onFailure, confirmation) {
+  const lines = [
+    `dispatch plan: topology=${topology} tasks=${tasks.length}`,
+    `cost ceiling: ${costCeilingUsd === void 0 ? "unavailable" : `$${costCeilingUsd.toFixed(4)}`}`,
+    `deadline: ${deadlineMs === null ? "per-assignment" : `${deadlineMs}ms whole-plan`}`
+  ];
+  if (confirmation !== void 0) {
+    lines.push(
+      `winner confirmation: group=${safeField(confirmation.group)} candidate=${confirmation.index} branch=${safeField(confirmation.branch)}${confirmation.cwd === void 0 ? "" : ` cwd=${safeField(confirmation.cwd)}`}`
+    );
+  }
+  if (source !== null) {
+    lines.push(
+      `source: scout-transition run=${safeField(source.runId)} receipt=${source.receiptDigest} execution-plan=${source.executionPlanHash} max-workers=${maxWorkers ?? "?"} on-failure=${onFailure ?? "?"}`
+    );
+  }
+  for (const [index, task] of tasks.entries()) {
+    const model = task.model !== void 0 ? ` model=${safeField(task.model)}` : "";
+    const target = task.target !== void 0 ? ` target=${safeField(task.target)}` : "";
+    const node = ` node=${safeField(task.node ?? "local")}${task.nodeKind !== void 0 ? ` kind=${task.nodeKind}` : ""}${task.nodeHost !== void 0 ? ` host=${safeField(task.nodeHost)}` : ""}`;
+    const role = task.role !== void 0 ? ` role=${task.role}${task.position !== void 0 ? `#${task.position}` : ""}` : "";
+    const failover = task.failover !== void 0 ? ` failover=${task.failover}` : "";
+    const routing = task.routingIntent;
+    const routingText = routing === void 0 ? "" : ` posture=${routing.posture} maxCostUsd=${routing.maxCostUsd ?? "none"} deadlineMs=${routing.deadlineMs ?? "none"} minimumQuality=${routing.minimumQuality ?? "none"} locality=${routing.locality}`;
+    lines.push(
+      `  ${index + 1}.${role} agent=${safeField(task.agent)}${target}${model}${node}${failover}${routingText} task=${JSON.stringify(safeField(task.task))}`
+    );
+    if (task.allowedCandidates !== void 0) {
+      for (const [candidateIndex, candidate] of task.allowedCandidates.entries()) {
+        lines.push(
+          `    candidate#${candidateIndex + 1} agent=${safeField(candidate.agentId)} target=${safeField(candidate.target)} model=${safeField(candidate.model)} node=${safeField(candidate.node)}`
+        );
+      }
+    }
+    if (task.routeApproval !== null) {
+      const approval = task.routeApproval;
+      const selected = approval.decision.selected;
+      lines.push(
+        `    active policy=${safeField(approval.decision.policyVersion)} decision=${approval.decision.decisionHash} runtime=${safeField(selected.runtimeId)} thinking=${safeField(selected.thinkingLevel ?? "default")} totalCostUpperBoundUsd=${approval.totalCostUpperBoundUsd.toFixed(6)} deadlineMs=${approval.deadlineMs} maxAttempts=${approval.maxAttempts}`
+      );
+    }
+    if (task.agentSelection !== null) {
+      lines.push(
+        `    agent-selection=auto baseline=${safeField(task.agentSelection.baselineAgentId)} authority=${task.agentSelection.approvedAuthorities.map(safeField).join(",")} basis=${task.agentSelection.authorityBasis}`
+      );
+    }
+    if (task.stepId !== null) {
+      lines.push(
+        `    step=${safeField(task.stepId)} wave=${task.wave ?? "?"} role=${task.executionRole} dependencies=${task.dependencies.map(safeField).join(",") || "none"} result=${task.expectedResultContract ?? "none"} authority=${task.authorityGrant?.requested ?? "none"} basis=${task.authorityGrant?.basis ?? "none"}`
+      );
+      const agentReasons = task.agentDecision?.agentSelection.evaluations.filter((evaluation) => evaluation.rejections.length > 0).slice(0, 8).map(
+        (evaluation) => `${safeField(evaluation.agentId)}:${evaluation.rejections.slice(0, 4).map(safeField).join(",")}`
+      );
+      if (agentReasons !== void 0 && agentReasons.length > 0)
+        lines.push(`    agent-exclusions=${agentReasons.join(";")}`);
+    }
+    if (task.briefing !== void 0) {
+      lines.push(
+        `    briefing_bytes=${Buffer.byteLength(task.briefing, "utf8")} briefing_sha256=${createHash("sha256").update(task.briefing, "utf8").digest("hex")} briefing_preview=${JSON.stringify(safeField(task.briefing))}`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+function isResolvedTask(value) {
+  if (!isRecord2(value)) return false;
+  const allowedKeys = /* @__PURE__ */ new Set([
+    "agent",
+    "task",
+    "briefing",
+    "model",
+    "node",
+    "nodeKind",
+    "nodeHost",
+    "target",
+    "role",
+    "position",
+    "routingIntent",
+    "failover",
+    "allowedCandidates",
+    "routeApproval",
+    "agentSelection",
+    "stepId",
+    "dependencies",
+    "executionRole",
+    "expectedResultContract",
+    "authorityGrant",
+    "agentDecision",
+    "wave"
+  ]);
+  if (Object.keys(value).some((key) => !allowedKeys.has(key))) return false;
+  for (const key of [
+    "agent",
+    "task",
+    "model",
+    "node",
+    "nodeKind",
+    "target",
+    "routingIntent",
+    "failover",
+    "routeApproval",
+    "agentSelection",
+    "stepId",
+    "dependencies",
+    "executionRole",
+    "expectedResultContract",
+    "authorityGrant",
+    "agentDecision",
+    "wave"
+  ])
+    if (!Object.hasOwn(value, key)) return false;
+  if (value.role !== void 0 && value.role !== "task" && value.role !== "builder" && value.role !== "reviewer" && value.role !== "candidate" && value.role !== "judge") {
+    return false;
+  }
+  if (value.position !== void 0 && (!Number.isInteger(value.position) || Number(value.position) < 1)) return false;
+  if (value.nodeKind !== "local" && value.nodeKind !== "ssh") return false;
+  if (value.nodeKind === "ssh" && (typeof value.nodeHost !== "string" || value.nodeHost.trim().length === 0))
+    return false;
+  if (value.nodeKind === "local" && value.nodeHost !== void 0) return false;
+  if (value.briefing !== void 0 && (typeof value.briefing !== "string" || value.briefing.trim().length === 0))
+    return false;
+  if (failoverModeOf(value.failover) === void 0) return false;
+  if (!isRoutingIntent(value.routingIntent)) return false;
+  if (value.routeApproval !== null && !isApprovedAssignmentRoute(value.routeApproval)) return false;
+  if (value.routeApproval !== null && value.failover !== "approved") return false;
+  if (value.agentSelection !== null && !isResolvedAgentSelection(value.agentSelection)) return false;
+  if (!isExecutionRole(value.executionRole) || !Array.isArray(value.dependencies) || !value.dependencies.every((dependency) => typeof dependency === "string" && dependency.length > 0) || new Set(value.dependencies).size !== value.dependencies.length)
+    return false;
+  if (value.stepId !== null && (typeof value.stepId !== "string" || value.stepId.length === 0)) return false;
+  if (value.wave !== null && (!Number.isInteger(value.wave) || Number(value.wave) < 0)) return false;
+  if (value.expectedResultContract !== null && !RESULT_CONTRACT_KINDS.has(value.expectedResultContract))
+    return false;
+  if (value.authorityGrant !== null && !isAuthorityGrant(value.authorityGrant)) return false;
+  if (value.agentDecision !== null && !isAgentDecision(value.agentDecision)) return false;
+  if (value.failover === "approved") {
+    if (canonicalCandidates(value.allowedCandidates) === null) return false;
+  } else if (value.allowedCandidates !== void 0) {
+    return false;
+  }
+  return [value.agent, value.task, value.model, value.node, value.target].every(
+    (candidate) => typeof candidate === "string" && candidate.trim().length > 0
+  );
+}
+var RESULT_CONTRACT_KINDS = /* @__PURE__ */ new Set([
+  "architect-plan",
+  "scout-report",
+  "verifier-report",
+  "debugger-report",
+  "research-report",
+  "mutation-report",
+  "provenance-report",
+  "external-delegation"
+]);
+function isAuthorityGrant(value) {
+  return isRecord2(value) && Object.keys(value).sort().join("\0") === "basis\0requested" && AGENT_AUTOMATION_AUTHORITIES.includes(value.requested) && (value.basis === "operator-plan-approval" || value.basis === "full-auto-policy");
+}
+function isAgentDecision(value) {
+  return isRecord2(value) && value.policyVersion === ROUTE_POLICY_VERSION && (value.mode === "shadow" || value.mode === "active" || value.mode === "fixed") && isRecord2(value.selected) && isRecord2(value.executedRoute) && Array.isArray(value.approvedFallbacks) && Array.isArray(value.candidateEvaluations) && Array.isArray(value.hardConstraints) && Array.isArray(value.reasonCodes) && typeof value.decisionHash === "string" && /^[0-9a-f]{64}$/u.test(value.decisionHash) && isRouteDecisionAgentSelection(value.agentSelection);
+}
+function isResolvedAgentSelection(value) {
+  if (!isRecord2(value)) return false;
+  if (Object.keys(value).sort().join("\0") !== ["approvedAuthorities", "authorityBasis", "baselineAgentId", "mode", "version"].sort().join("\0"))
+    return false;
+  if (value.version !== 1 || value.mode !== "auto") return false;
+  if (typeof value.baselineAgentId !== "string" || value.baselineAgentId.trim().length === 0) return false;
+  if (value.authorityBasis !== "operator-plan-approval" && value.authorityBasis !== "full-auto-policy") return false;
+  if (!Array.isArray(value.approvedAuthorities) || value.approvedAuthorities.length === 0 || value.approvedAuthorities.some(
+    (authority) => typeof authority !== "string" || !AGENT_AUTOMATION_AUTHORITIES.includes(authority)
+  ) || new Set(value.approvedAuthorities).size !== value.approvedAuthorities.length)
+    return false;
+  return true;
+}
+function resolvedDispatchPlanFromArgs(args) {
+  const value = args[RESOLVED_DISPATCH_PLAN_ARGUMENT];
+  if (!isRecord2(value) || value.version !== 3) return null;
+  const artifactKeys = /* @__PURE__ */ new Set([
+    "version",
+    "topology",
+    "source",
+    "maxWorkers",
+    "onFailure",
+    "tasks",
+    "costCeilingUsd",
+    "deadlineMs",
+    "confirmation"
+  ]);
+  if (Object.keys(value).some((key) => !artifactKeys.has(key))) return null;
+  for (const key of [
+    "version",
+    "topology",
+    "source",
+    "maxWorkers",
+    "onFailure",
+    "tasks",
+    "costCeilingUsd",
+    "deadlineMs"
+  ]) {
+    if (!Object.hasOwn(value, key)) return null;
+  }
+  if (!Array.isArray(value.tasks) || !value.tasks.every(isResolvedTask)) return null;
+  let confirmation;
+  if (value.confirmation !== void 0) {
+    if (!isRecord2(value.confirmation) || !["branch\0group\0index", "branch\0cwd\0group\0index"].includes(
+      Object.keys(value.confirmation).sort().join("\0")
+    ) || typeof value.confirmation.branch !== "string" || value.confirmation.branch.trim().length === 0 || typeof value.confirmation.group !== "string" || value.confirmation.group.trim().length === 0 || value.confirmation.cwd !== void 0 && (typeof value.confirmation.cwd !== "string" || value.confirmation.cwd.trim().length === 0) || !Number.isInteger(value.confirmation.index) || Number(value.confirmation.index) < 1) {
+      return null;
+    }
+    confirmation = {
+      branch: value.confirmation.branch.trim(),
+      group: value.confirmation.group.trim(),
+      index: Number(value.confirmation.index),
+      ...value.confirmation.cwd === void 0 ? {} : { cwd: value.confirmation.cwd.trim() }
+    };
+  }
+  if (value.tasks.length === 0 && confirmation === void 0) return null;
+  if (value.topology !== "parallel" && value.topology !== "sequential" && value.topology !== "pipeline" && value.topology !== "review" && value.topology !== "compete" && value.topology !== "detached" && value.topology !== "fleet") {
+    return null;
+  }
+  if (typeof value.costCeilingUsd !== "number" || !Number.isFinite(value.costCeilingUsd) || value.costCeilingUsd <= 0) {
+    return null;
+  }
+  const source = parsePlanSource(value.source);
+  if (source === void 0) return null;
+  const fleet = value.topology === "fleet";
+  if (fleet !== (source !== null)) return null;
+  if (fleet) {
+    if (!Number.isInteger(value.maxWorkers) || Number(value.maxWorkers) < 1 || value.onFailure !== "stop" && value.onFailure !== "continue" || !Number.isInteger(value.deadlineMs) || Number(value.deadlineMs) < 1)
+      return null;
+    if (value.tasks.some(
+      (task) => task.stepId === null || task.expectedResultContract === null || task.authorityGrant === null || task.agentDecision === null || task.wave === null || task.agentSelection === null || task.role !== "task" || task.position === void 0
+    ))
+      return null;
+  } else if (value.maxWorkers !== null || value.onFailure !== null || value.deadlineMs !== null || value.tasks.some(
+    (task) => task.stepId !== null || task.dependencies.length > 0 || task.expectedResultContract !== null || task.authorityGrant !== null || task.agentDecision !== null || task.wave !== null
+  ))
+    return null;
+  return {
+    version: 3,
+    topology: value.topology,
+    source,
+    maxWorkers: value.maxWorkers,
+    onFailure: value.onFailure,
+    tasks: value.tasks.map((task) => ({
+      agent: task.agent.trim(),
+      task: task.task.trim(),
+      ...task.briefing !== void 0 ? { briefing: task.briefing.trim() } : {},
+      model: task.model.trim(),
+      node: task.node.trim(),
+      nodeKind: task.nodeKind,
+      target: task.target.trim(),
+      failover: task.failover,
+      routingIntent: structuredClone(task.routingIntent),
+      routeApproval: task.routeApproval === null ? null : cloneApprovedAssignmentRoute(task.routeApproval),
+      agentSelection: task.agentSelection === null ? null : structuredClone(task.agentSelection),
+      stepId: task.stepId,
+      dependencies: [...task.dependencies],
+      executionRole: task.executionRole,
+      expectedResultContract: task.expectedResultContract,
+      authorityGrant: task.authorityGrant === null ? null : { ...task.authorityGrant },
+      agentDecision: task.agentDecision === null ? null : structuredClone(task.agentDecision),
+      wave: task.wave,
+      ...task.failover === "approved" && canonicalCandidates(task.allowedCandidates) !== null ? { allowedCandidates: canonicalCandidates(task.allowedCandidates) } : {},
+      ...task.nodeHost !== void 0 ? { nodeHost: task.nodeHost.trim() } : {},
+      ...task.role !== void 0 ? { role: task.role } : {},
+      ...task.position !== void 0 ? { position: task.position } : {}
+    })),
+    costCeilingUsd: value.costCeilingUsd,
+    deadlineMs: value.deadlineMs,
+    ...confirmation !== void 0 ? { confirmation } : {}
+  };
+}
+function parsePlanSource(value) {
+  if (value === null) return null;
+  if (!isRecord2(value) || Object.keys(value).sort().join("\0") !== "executionPlanHash\0kind\0receiptDigest\0runId")
+    return void 0;
+  if (value.kind !== "scout-transition" || typeof value.runId !== "string" || value.runId.length === 0 || typeof value.receiptDigest !== "string" || !/^[0-9a-f]{64}$/u.test(value.receiptDigest) || typeof value.executionPlanHash !== "string" || !/^[0-9a-f]{64}$/u.test(value.executionPlanHash))
+    return void 0;
+  return {
+    kind: "scout-transition",
+    runId: value.runId,
+    receiptDigest: value.receiptDigest,
+    executionPlanHash: value.executionPlanHash
+  };
+}
+function withResolvedDispatchPlan(args, artifact) {
+  return { ...args, [RESOLVED_DISPATCH_PLAN_ARGUMENT]: structuredClone(artifact) };
+}
+function describeDispatchPlan(rawArgs) {
+  const args = prepareDispatchArguments(rawArgs ?? {});
+  const preparationFailed = typeof args[DISPATCH_PLAN_PREPARATION_ERROR_ARGUMENT] === "string";
+  const resolved = resolvedDispatchPlanFromArgs(args);
+  const topology = resolved?.topology ?? topologyOf(args);
+  const tasks = resolved?.tasks ?? taskViews(args);
+  const costCeilingUsd = resolved?.costCeilingUsd;
+  const deadlineMs = resolved?.deadlineMs ?? null;
+  const confirmation = resolved?.confirmation;
+  const source = resolved?.source ?? null;
+  const maxWorkers = resolved?.maxWorkers ?? null;
+  const onFailure = resolved?.onFailure ?? null;
+  const remote = tasks.some((task) => task.node !== void 0 && task.node !== "local");
+  const planScale = !preparationFailed && args.list !== true && (tasks.length > 1 || source !== null || topology === "compete" || remote || tasks.some((task) => task.failover === "approved") || confirmation !== void 0 || isRecord2(args.apply_winner));
+  const text = renderPlanText(topology, tasks, costCeilingUsd, deadlineMs, source, maxWorkers, onFailure, confirmation);
+  return {
+    topology,
+    taskCount: Math.max(1, tasks.length),
+    planScale,
+    tasks,
+    text,
+    hash: createHash("sha256").update(text, "utf8").digest("hex"),
+    ...costCeilingUsd !== void 0 ? { costCeilingUsd } : {},
+    ...deadlineMs !== null ? { deadlineMs } : {},
+    ...confirmation !== void 0 ? { confirmation } : {}
+  };
+}
+
+export {
+  stringArg,
+  maxOutputBytesArg,
+  timeoutMsArg,
+  dispatchRequestsFromArgs,
+  prepareDispatchArguments,
+  RESOLVED_DISPATCH_PLAN_ARGUMENT,
+  DISPATCH_PLAN_PREPARATION_ERROR_ARGUMENT,
+  withResolvedPlanTaskPin,
+  resolvedDispatchPlanFromArgs,
+  withResolvedDispatchPlan,
+  describeDispatchPlan
+};
+//# sourceMappingURL=chunk-DUYJ5IO6.js.map

package/dist/chunk-ECH6PKUQ.js

@@ -0,0 +1,39 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  init_esm_shims
+} from "./chunk-3R73A4XB.js";
+
+// src/core/path-canonical.ts
+init_esm_shims();
+import { realpathSync } from "node:fs";
+import path from "node:path";
+function canonicalizeExistingPath(absPath) {
+  const resolved = path.resolve(absPath);
+  try {
+    return path.resolve(realpathSync(resolved));
+  } catch {
+  }
+  const tail = [];
+  let cursor = resolved;
+  while (true) {
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      try {
+        return path.resolve(realpathSync(cursor), ...tail);
+      } catch {
+        return resolved;
+      }
+    }
+    tail.unshift(path.basename(cursor));
+    cursor = parent;
+    try {
+      return path.resolve(realpathSync(cursor), ...tail);
+    } catch {
+    }
+  }
+}
+
+export {
+  canonicalizeExistingPath
+};
+//# sourceMappingURL=chunk-ECH6PKUQ.js.map