@trailstep/sub-agents 0.2.0

package/dist/index.js

@@ -0,0 +1,1062 @@
+// src/delegate/workflow.ts
+import { defineWorkflow } from "@trailstep/authoring";
+
+// src/delegate/schema.ts
+import { jsonSchema } from "@trailstep/authoring";
+var delegateArtifactShape = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    path: { type: "string" },
+    mediaType: { type: "string" }
+  },
+  required: ["name", "path"],
+  additionalProperties: false
+};
+var delegateInputShape = jsonSchema({
+  type: "object",
+  properties: {
+    task: { type: "string" },
+    context: { type: "string" },
+    mode: { type: "string", enum: ["explore", "implement", "review", "general"] },
+    cwd: { type: "string" },
+    maxTurns: { type: "number" },
+    summarize: { type: "boolean" },
+    worktree: {
+      type: "object",
+      properties: {
+        enabled: { type: "boolean" },
+        path: { type: "string" },
+        baseRef: { type: "string" },
+        baseBranch: { type: "string" },
+        branch: { type: "string" },
+        cleanup: { type: "string", enum: ["auto", "never", "always"] },
+        forceCleanup: { type: "boolean" }
+      },
+      additionalProperties: false
+    }
+  },
+  required: ["task"],
+  additionalProperties: false
+});
+var delegateOutputShape = jsonSchema({
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["completed", "blocked", "cancelled"] },
+    summary: { type: "string" },
+    result: { type: "string" },
+    changedFiles: { type: "array", items: { type: "string" } },
+    artifacts: { type: "array", items: delegateArtifactShape },
+    worktreePath: { type: "string" },
+    worktreeBranch: { type: "string" },
+    worktreeCleanup: {
+      type: "object",
+      properties: {
+        requested: { type: "string", enum: ["auto", "never", "always"] },
+        status: {
+          type: "string",
+          enum: ["not-managed", "kept", "removed", "kept-dirty", "failed"]
+        },
+        reason: { type: "string" }
+      },
+      required: ["requested", "status"],
+      additionalProperties: false
+    },
+    questionsAsked: { type: "number" },
+    turns: { type: "number" }
+  },
+  required: ["status", "summary", "questionsAsked", "turns"],
+  additionalProperties: false
+});
+var delegateTurnOutputShape = jsonSchema({
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["completed", "continue", "question", "blocked"] },
+    summary: { type: "string" },
+    memoryPatch: { type: "string" },
+    question: { type: "string" },
+    result: { type: "string" },
+    changedFiles: { type: "array", items: { type: "string" } },
+    artifacts: { type: "array", items: delegateArtifactShape }
+  },
+  required: ["status", "summary"],
+  additionalProperties: false
+});
+var parentAnswerShape = jsonSchema({
+  type: "object",
+  properties: {
+    answer: { type: "string" }
+  },
+  required: ["answer"],
+  additionalProperties: false
+});
+function normalizeDelegateInput(input, defaults = {}) {
+  const mode = input.mode ?? defaults.mode ?? "general";
+  return {
+    task: input.task,
+    ...nonEmptyOptional(input.context) === void 0 ? {} : { context: nonEmptyOptional(input.context) },
+    mode,
+    ...nonEmptyOptional(input.cwd) === void 0 ? {} : { cwd: nonEmptyOptional(input.cwd) },
+    maxTurns: normalizeMaxTurns(input.maxTurns ?? defaults.maxTurns),
+    summarize: input.summarize ?? defaults.summarize ?? (mode === "explore" || mode === "general"),
+    worktree: {
+      enabled: input.worktree?.enabled ?? false,
+      ...nonEmptyOptional(input.worktree?.path) === void 0 ? {} : { path: nonEmptyOptional(input.worktree?.path) },
+      ...nonEmptyOptional(input.worktree?.baseRef ?? input.worktree?.baseBranch) === void 0 ? {} : { baseRef: nonEmptyOptional(input.worktree?.baseRef ?? input.worktree?.baseBranch) },
+      ...nonEmptyOptional(input.worktree?.baseBranch) === void 0 ? {} : { baseBranch: nonEmptyOptional(input.worktree?.baseBranch) },
+      ...nonEmptyOptional(input.worktree?.branch) === void 0 ? {} : { branch: nonEmptyOptional(input.worktree?.branch) },
+      cleanup: input.worktree?.cleanup ?? "auto",
+      forceCleanup: input.worktree?.forceCleanup ?? false
+    }
+  };
+}
+function normalizeMaxTurns(value) {
+  if (value === void 0) {
+    return 10;
+  }
+  if (!Number.isFinite(value)) {
+    return 10;
+  }
+  return Math.max(1, Math.floor(value));
+}
+function nonEmptyOptional(value) {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : void 0;
+}
+
+// src/delegate/steps.ts
+import { execFile } from "child_process";
+import { mkdir } from "fs/promises";
+import { dirname, resolve } from "path";
+import { promisify } from "util";
+import { done, notify, state, step } from "@trailstep/authoring";
+
+// src/delegate/prompts.ts
+import { list, promptSections, section } from "@trailstep/authoring";
+function delegateTurnPrompt({ input }) {
+  return promptSections(
+    section(
+      "Role",
+      "You are a continued delegate agent working inside one TrailStep run. Preserve continuity from the run-local memory below, but do not assume or use memory from any separate run."
+    ),
+    section("Original task", input.task),
+    section("Original context", input.context),
+    section("Mode", `${input.mode}: ${modeGuidance(input.mode)}`),
+    section(
+      "Execution location",
+      [
+        `CWD/worktree path: ${input.worktreePath ?? input.executionCwd}`,
+        "Honor this directory for any project inspection or file edits."
+      ].join("\n")
+    ),
+    section("Accumulated run-local memory summary", input.memory || "No prior delegate memory."),
+    section("Previous questions and parent/human answers", formatQuestionsAndAnswers(input)),
+    section("Latest summary", input.latestSummary ?? "No prior summary."),
+    section(
+      "Current turn",
+      [
+        `Turn: ${input.turn} of ${input.maxTurns}`,
+        `Summarize mode: ${String(input.summarize)}`
+      ].join("\n")
+    ),
+    section(
+      "Instructions",
+      list([
+        "Do one focused turn of delegated work; keep the work bounded and observable.",
+        "Use the run-local memory summary and previous Q/A as continuity, not an unlimited transcript.",
+        "If you can finish the task now, return status `completed` with a concise summary and final result.",
+        "If more delegated work is needed and no parent answer is required, return status `continue` and a memory patch for the next turn.",
+        "If blocked on a parent/human decision, return status `question`, include exactly one clear question, and summarize why it is needed.",
+        "If the task cannot proceed safely, return status `blocked` with the reason in the summary/result.",
+        "When you learn durable facts for this run, include a compact `memoryPatch`; do not copy large transcripts, files, or diffs.",
+        "Report changed files and artifacts only when you actually changed or produced them."
+      ])
+    ),
+    section("Exact output contract", outputContract)
+  );
+}
+function modeGuidance(mode) {
+  switch (mode) {
+    case "explore":
+      return "investigate, summarize findings, and avoid code changes unless explicitly needed.";
+    case "implement":
+      return "make the smallest safe implementation progress and report changed files.";
+    case "review":
+      return "review existing work, identify issues, and avoid unnecessary edits.";
+    case "general":
+      return "use judgment to complete the delegated task with focused, bounded work.";
+  }
+}
+function formatQuestionsAndAnswers(input) {
+  if (input.questionsAndAnswers.length === 0) {
+    return "No parent/human questions have been asked in this run.";
+  }
+  return input.questionsAndAnswers.map(
+    (item, index) => [`${index + 1}. Question: ${item.question}`, `   Answer: ${item.answer}`].join("\n")
+  ).join("\n");
+}
+var outputContract = `Return the structured JSON object requested by the wrapper.
+
+Status meanings:
+- completed: the delegated task is finished; include result when useful.
+- continue: more bounded work is needed in another turn; include memoryPatch for durable continuity.
+- question: parent/human input is required; include exactly one clear question.
+- blocked: the task cannot proceed safely; summarize why and include result details when useful.
+
+Only report changedFiles/artifacts that you actually changed or produced.`;
+
+// src/delegate/steps.ts
+var MEMORY_LIMIT = 12e3;
+var execFileAsync = promisify(execFile);
+var DELEGATE_STATE_KEYS = {
+  initialized: "delegate.initialized",
+  input: "delegate.input",
+  memory: "delegate.memory",
+  turns: "delegate.turns",
+  questions: "delegate.questions",
+  answers: "delegate.answers",
+  latestSummary: "delegate.latestSummary",
+  artifacts: "delegate.artifacts",
+  changedFiles: "delegate.changedFiles",
+  result: "delegate.result",
+  worktreePath: "delegate.worktreePath",
+  worktreeBranch: "delegate.worktreeBranch",
+  worktreeCleanup: "delegate.worktreeCleanup"
+};
+function initializeDelegateStep(input, defaults = {}) {
+  return initializeDelegateStepFactory({ input, defaults });
+}
+var initializeDelegateStepFactory = step({
+  id: "initialize-delegate",
+  title: "Initialize delegate"
+}).display(({ input }) => `Delegating: ${input.input.task}`).do(async ({ input, defaults }) => {
+  const initialized = await state.get(DELEGATE_STATE_KEYS.initialized) ?? false;
+  if (initialized) {
+    return prepareDelegateTurnStep({ turn: 1 });
+  }
+  const normalized = normalizeDelegateInput(input, defaults);
+  if (normalized.cwd !== void 0 && normalized.worktree.enabled) {
+    return await finalDone({
+      status: "blocked",
+      summary: "Delegate input cannot specify both cwd and worktree.enabled. Choose an existing cwd or managed worktree creation, not both.",
+      questionsAsked: 0,
+      turns: 0
+    });
+  }
+  const managedWorktree = normalized.worktree.enabled ? await createManagedWorktree(normalized) : void 0;
+  const executionCwd = managedWorktree?.path ?? resolveDelegateCwd(normalized.cwd);
+  const normalizedInput = {
+    ...normalized,
+    ...normalized.cwd !== void 0 || managedWorktree !== void 0 ? { cwd: executionCwd } : {}
+  };
+  await state.set(DELEGATE_STATE_KEYS.initialized, true);
+  await state.set(DELEGATE_STATE_KEYS.input, normalizedInput);
+  await state.set(DELEGATE_STATE_KEYS.memory, "");
+  await state.set(DELEGATE_STATE_KEYS.turns, 0);
+  await state.set(DELEGATE_STATE_KEYS.questions, 0);
+  await state.set(DELEGATE_STATE_KEYS.answers, []);
+  await state.set(DELEGATE_STATE_KEYS.latestSummary, null);
+  await state.set(DELEGATE_STATE_KEYS.artifacts, []);
+  await state.set(DELEGATE_STATE_KEYS.changedFiles, []);
+  await state.set(DELEGATE_STATE_KEYS.result, null);
+  await state.set(DELEGATE_STATE_KEYS.worktreePath, managedWorktree?.path ?? null);
+  await state.set(DELEGATE_STATE_KEYS.worktreeBranch, managedWorktree?.branch ?? null);
+  await state.set(DELEGATE_STATE_KEYS.worktreeCleanup, null);
+  await notify.progress("Initialized delegate memory", {
+    mode: normalizedInput.mode,
+    maxTurns: normalizedInput.maxTurns,
+    cwd: executionCwd,
+    ...managedWorktree === void 0 ? {} : { worktreePath: managedWorktree.path, worktreeBranch: managedWorktree.branch }
+  });
+  return prepareDelegateTurnStep({ turn: 1 });
+});
+var prepareDelegateTurnStep = step({
+  id: "prepare-delegate-turn",
+  title: "Prepare delegate turn"
+}).do(async (turnRequest) => {
+  const input = await requiredState(DELEGATE_STATE_KEYS.input);
+  const turns = await state.get(DELEGATE_STATE_KEYS.turns) ?? 0;
+  const questionsAsked = await state.get(DELEGATE_STATE_KEYS.questions) ?? 0;
+  if (turnRequest.turn > input.maxTurns) {
+    await notify.warning("Delegate exceeded maxTurns", { maxTurns: input.maxTurns, turns });
+    return await finalDone({
+      status: "blocked",
+      summary: "Delegate exceeded maxTurns without completing.",
+      ...await finalOptionalOutputFields(),
+      questionsAsked,
+      turns
+    });
+  }
+  const executionCwd = input.cwd ?? state.executionCwd ?? state.cwd ?? process.cwd();
+  const turnInput = {
+    task: input.task,
+    ...input.context === void 0 ? {} : { context: input.context },
+    mode: input.mode,
+    executionCwd,
+    ...input.worktree.enabled ? { worktreePath: executionCwd } : {},
+    memory: await state.get(DELEGATE_STATE_KEYS.memory) ?? "",
+    questionsAndAnswers: await state.get(DELEGATE_STATE_KEYS.answers) ?? [],
+    latestSummary: await state.get(DELEGATE_STATE_KEYS.latestSummary) ?? void 0,
+    turn: turnRequest.turn,
+    maxTurns: input.maxTurns,
+    summarize: input.summarize
+  };
+  return delegateTurnStep(turnInput);
+});
+var delegateTurnStep = step({
+  id: "delegate-turn",
+  title: "Delegate turn",
+  cwd: ({ input }) => input.executionCwd
+}).display(({ input }) => `Delegating: ${input.task}`).prompt(delegateTurnPrompt, {
+  agent: "delegateAgent",
+  output: delegateTurnOutputShape
+}).display(({ output }) => output.summary).do(async (turnOutput, input) => {
+  const storedTurns = await state.get(DELEGATE_STATE_KEYS.turns) ?? 0;
+  const alreadyProcessed = storedTurns >= input.turn;
+  const turns = alreadyProcessed ? storedTurns : storedTurns + 1;
+  if (!alreadyProcessed) {
+    await state.set(DELEGATE_STATE_KEYS.turns, turns);
+    await state.set(DELEGATE_STATE_KEYS.latestSummary, turnOutput.summary);
+    await appendMemory(turns, turnOutput);
+    await mergeChangedFiles(turnOutput.changedFiles ?? []);
+    await mergeArtifacts(turnOutput.artifacts ?? []);
+    await state.set(DELEGATE_STATE_KEYS.result, turnOutput.result ?? null);
+    await notify.progress("Updated delegate memory", { turn: turns });
+    for (const artifact of turnOutput.artifacts ?? []) {
+      await notify.artifact(artifact.name, {
+        path: artifact.path,
+        ...artifact.mediaType === void 0 ? {} : { mediaType: artifact.mediaType }
+      });
+    }
+  }
+  if (turnOutput.status === "completed") {
+    const questionsAsked = await state.get(DELEGATE_STATE_KEYS.questions) ?? 0;
+    return await finalDone({
+      status: "completed",
+      summary: turnOutput.summary,
+      ...await finalOptionalOutputFields(turnOutput),
+      questionsAsked,
+      turns
+    });
+  }
+  if (turnOutput.status === "blocked") {
+    const questionsAsked = await state.get(DELEGATE_STATE_KEYS.questions) ?? 0;
+    return await finalDone({
+      status: "blocked",
+      summary: turnOutput.summary,
+      ...await finalOptionalOutputFields(turnOutput),
+      questionsAsked,
+      turns
+    });
+  }
+  if (turnOutput.status === "question") {
+    const question = turnOutput.question?.trim();
+    if (!question) {
+      const questionsAsked2 = await state.get(DELEGATE_STATE_KEYS.questions) ?? 0;
+      return await finalDone({
+        status: "blocked",
+        summary: "Delegate requested a parent answer but did not provide a question.",
+        ...await finalOptionalOutputFields(turnOutput),
+        questionsAsked: questionsAsked2,
+        turns
+      });
+    }
+    const storedQuestions = await state.get(DELEGATE_STATE_KEYS.questions) ?? 0;
+    const questionsAsked = alreadyProcessed ? storedQuestions : storedQuestions + 1;
+    if (!alreadyProcessed) {
+      await state.set(DELEGATE_STATE_KEYS.questions, questionsAsked);
+      await notify.progress("Delegate asked parent question", {
+        turn: input.turn,
+        questionsAsked
+      });
+    }
+    return askParentStep({ question, nextTurn: input.turn + 1 });
+  }
+  return prepareDelegateTurnStep({ turn: input.turn + 1 });
+});
+var askParentStep = step({
+  id: "ask-parent",
+  title: "Ask parent"
+}).display(({ input }) => input.question).wait(({ input }) => ({
+  id: "parent-answer",
+  kind: "input",
+  message: input.question,
+  output: parentAnswerShape
+})).do(async (context, input) => {
+  const waitContext = context;
+  const answerOutput = waitContext.waits?.["parent-answer"];
+  const answer = answerOutput?.answer ?? "";
+  const answers = await state.get(DELEGATE_STATE_KEYS.answers) ?? [];
+  const alreadyRecorded = answers.some(
+    (item) => item.question === input.question && item.answer === answer
+  );
+  if (answerOutput !== void 0 && !alreadyRecorded) {
+    await state.set(DELEGATE_STATE_KEYS.answers, [
+      ...answers,
+      { question: input.question, answer }
+    ]);
+    await appendMemoryNote(`Parent answered: ${answer}`);
+    await notify.progress("Recorded parent answer", { questionsAnswered: answers.length + 1 });
+  }
+  return prepareDelegateTurnStep({ turn: input.nextTurn });
+});
+async function createManagedWorktree(input) {
+  const base = state.projectCwd ?? state.executionCwd ?? state.cwd ?? process.cwd();
+  const safeRunName = sanitizeRefSegment(state.name);
+  const worktreePath = resolve(base, input.worktree.path ?? `.trailstep/worktrees/${safeRunName}`);
+  const branch = input.worktree.branch ?? `trailstep/delegate/${safeRunName}`;
+  const baseRef = input.worktree.baseRef ?? input.worktree.baseBranch ?? "HEAD";
+  await mkdir(dirname(worktreePath), { recursive: true });
+  await git(base, ["worktree", "add", "-b", branch, worktreePath, baseRef]);
+  await notify.progress("Created delegate worktree", { path: worktreePath, branch, baseRef });
+  return { path: worktreePath, branch };
+}
+async function cleanupManagedWorktree(finalStatus) {
+  const input = await state.get(DELEGATE_STATE_KEYS.input);
+  const worktreePath = await state.get(DELEGATE_STATE_KEYS.worktreePath);
+  const worktreeBranch = await state.get(DELEGATE_STATE_KEYS.worktreeBranch);
+  if (input?.worktree.enabled !== true || worktreePath === void 0 || worktreePath === null) {
+    return void 0;
+  }
+  const requested = input.worktree.cleanup;
+  const keep = async (status, reason) => {
+    const details2 = { requested, status, reason };
+    await state.set(DELEGATE_STATE_KEYS.worktreeCleanup, details2);
+    await notify.progress("Kept delegate worktree", { path: worktreePath, reason });
+    return details2;
+  };
+  if (requested === "never") {
+    return keep("kept", "cleanup=never");
+  }
+  if (requested === "auto" && finalStatus !== "completed") {
+    return keep("kept", "auto cleanup keeps worktree because delegate did not complete");
+  }
+  let clean = false;
+  try {
+    clean = (await git(worktreePath, ["status", "--porcelain"])).trim().length === 0;
+  } catch (error) {
+    return keep("failed", `could not prove worktree cleanliness: ${errorMessage(error)}`);
+  }
+  if (!clean && !input.worktree.forceCleanup) {
+    return keep("kept-dirty", "worktree has changes and forceCleanup is false");
+  }
+  const repoCwd = state.projectCwd ?? state.executionCwd ?? state.cwd ?? process.cwd();
+  try {
+    const args = [
+      "worktree",
+      "remove",
+      ...input.worktree.forceCleanup ? ["--force"] : [],
+      worktreePath
+    ];
+    await git(repoCwd, args);
+  } catch (error) {
+    return keep("failed", `git worktree remove failed: ${errorMessage(error)}`);
+  }
+  const branchCleanupReason = await cleanupManagedWorktreeBranch({
+    repoCwd,
+    branch: worktreeBranch,
+    createdByRun: input.worktree.branch === void 0
+  });
+  const details = {
+    requested,
+    status: branchCleanupReason?.startsWith("managed branch cleanup failed") ? "failed" : "removed",
+    ...branchCleanupReason === void 0 ? {} : { reason: branchCleanupReason }
+  };
+  await state.set(DELEGATE_STATE_KEYS.worktreeCleanup, details);
+  await notify.progress("Removed delegate worktree", {
+    path: worktreePath,
+    reason: branchCleanupReason
+  });
+  return details;
+}
+async function cleanupManagedWorktreeBranch({
+  repoCwd,
+  branch,
+  createdByRun
+}) {
+  if (branch === void 0 || branch === null) {
+    return void 0;
+  }
+  if (!createdByRun) {
+    return "user-supplied branch retained";
+  }
+  let currentBranch;
+  try {
+    currentBranch = (await git(repoCwd, ["branch", "--show-current"])).trim();
+  } catch (error) {
+    return `managed branch cleanup failed after worktree removal: could not determine current branch: ${errorMessage(error)}`;
+  }
+  if (currentBranch === branch) {
+    return "managed branch retained because it is currently checked out";
+  }
+  try {
+    await git(repoCwd, ["branch", "-d", branch]);
+    return void 0;
+  } catch (error) {
+    return `managed branch cleanup failed after worktree removal: ${errorMessage(error)}`;
+  }
+}
+async function git(cwd, args) {
+  const { stdout } = await execFileAsync("git", args, { cwd });
+  return stdout;
+}
+function resolveDelegateCwd(cwd) {
+  const base = state.projectCwd ?? state.executionCwd ?? state.cwd ?? process.cwd();
+  return cwd === void 0 ? base : resolve(base, cwd);
+}
+function sanitizeRefSegment(value) {
+  return value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "run";
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function appendMemory(turn, output) {
+  const lines = [`Turn ${turn}: ${output.summary}`];
+  if (output.memoryPatch?.trim()) {
+    lines.push(`Memory patch: ${output.memoryPatch.trim()}`);
+  }
+  await appendMemoryNote(lines.join("\n"));
+}
+async function appendMemoryNote(note) {
+  const existing = await state.get(DELEGATE_STATE_KEYS.memory) ?? "";
+  const updated = [existing.trim(), note.trim()].filter(Boolean).join("\n\n");
+  await state.set(DELEGATE_STATE_KEYS.memory, trimRollingMemory(updated));
+}
+function trimRollingMemory(memory) {
+  if (memory.length <= MEMORY_LIMIT) {
+    return memory;
+  }
+  return `[older delegate memory trimmed]
+${memory.slice(-MEMORY_LIMIT)}`;
+}
+async function mergeChangedFiles(changedFiles) {
+  if (changedFiles.length === 0) {
+    return;
+  }
+  const existing = await state.get(DELEGATE_STATE_KEYS.changedFiles) ?? [];
+  await state.set(DELEGATE_STATE_KEYS.changedFiles, uniqueStrings([...existing, ...changedFiles]));
+}
+async function mergeArtifacts(artifacts) {
+  if (artifacts.length === 0) {
+    return;
+  }
+  const existing = await state.get(DELEGATE_STATE_KEYS.artifacts) ?? [];
+  const byPath = new Map(existing.map((artifact) => [artifact.path, artifact]));
+  for (const artifact of artifacts) {
+    byPath.set(artifact.path, artifact);
+  }
+  await state.set(DELEGATE_STATE_KEYS.artifacts, [...byPath.values()]);
+}
+async function finalOptionalOutputFields(latest) {
+  const result = latest?.result ?? await state.get(DELEGATE_STATE_KEYS.result);
+  const changedFiles = await state.get(DELEGATE_STATE_KEYS.changedFiles) ?? [];
+  const artifacts = await state.get(DELEGATE_STATE_KEYS.artifacts) ?? [];
+  const worktreePath = await state.get(DELEGATE_STATE_KEYS.worktreePath);
+  const worktreeBranch = await state.get(DELEGATE_STATE_KEYS.worktreeBranch);
+  const worktreeCleanup = await state.get(
+    DELEGATE_STATE_KEYS.worktreeCleanup
+  );
+  return {
+    ...result === void 0 || result === null ? {} : { result },
+    ...changedFiles.length === 0 ? {} : { changedFiles },
+    ...artifacts.length === 0 ? {} : { artifacts },
+    ...worktreePath === void 0 || worktreePath === null ? {} : { worktreePath },
+    ...worktreeBranch === void 0 || worktreeBranch === null ? {} : { worktreeBranch },
+    ...worktreeCleanup === void 0 || worktreeCleanup === null ? {} : { worktreeCleanup }
+  };
+}
+async function finalDone(output) {
+  const cleanup = await cleanupManagedWorktree(output.status);
+  const finalOutput = cleanup === void 0 ? output : { ...output, worktreeCleanup: cleanup };
+  return done(finalOutput, { message: delegateTerminalMessage(finalOutput) });
+}
+function delegateTerminalMessage(output) {
+  const lines = [
+    `Delegate ${output.status}: ${output.summary}`,
+    `Turns: ${output.turns}; questions asked: ${output.questionsAsked}`
+  ];
+  if (output.changedFiles && output.changedFiles.length > 0) {
+    lines.push(`Changed files: ${output.changedFiles.join(", ")}`);
+  }
+  if (output.worktreePath) {
+    lines.push(`Worktree: ${output.worktreePath}`);
+  }
+  if (output.worktreeBranch) {
+    lines.push(`Worktree branch: ${output.worktreeBranch}`);
+  }
+  if (output.worktreeCleanup) {
+    lines.push(
+      `Worktree cleanup: ${output.worktreeCleanup.status} (${output.worktreeCleanup.requested})${output.worktreeCleanup.reason ? ` - ${output.worktreeCleanup.reason}` : ""}`
+    );
+  }
+  if (output.result?.trim()) {
+    lines.push(output.result.trim());
+  }
+  return lines.join("\n");
+}
+async function requiredState(key) {
+  const value = await state.get(key);
+  if (value === void 0 || value === null) {
+    throw new Error(`Delegate state is missing required key: ${key}`);
+  }
+  return value;
+}
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => value.trim().length > 0))];
+}
+
+// src/delegate/workflow.ts
+function defineDelegateWorkflow(config) {
+  return defineWorkflow({
+    id: config.id,
+    description: config.description,
+    skill: delegateSkill(config),
+    inputShape: delegateInputShape,
+    outputShape: delegateOutputShape,
+    agents: {
+      delegateAgent: {
+        size: config.agentSize ?? "medium",
+        thinking: config.agentThinking ?? "medium",
+        description: config.description
+      }
+    },
+    start(input) {
+      return initializeDelegateStep(input, {
+        mode: config.defaultMode,
+        maxTurns: config.defaultMaxTurns,
+        ...config.summarize === void 0 ? {} : { summarize: config.summarize }
+      });
+    }
+  });
+}
+var delegate = defineDelegateWorkflow({
+  id: "delegate",
+  description: "Runs delegated focused work while preserving run-local continuity.",
+  skillName: "trst-delegate",
+  skillDescription: "Use as a flexible sub-agent for focused TrailStep delegate work with run-local continuity.",
+  skillFocus: "Use for general delegated work when the parent agent wants to choose the task, mode, turn budget, and context shape explicitly.",
+  defaultMode: "general",
+  defaultMaxTurns: 10
+});
+var delegateExplore = defineDelegateWorkflow({
+  id: "delegateExplore",
+  description: "Runs read-oriented delegated exploration while preserving run-local continuity.",
+  skillName: "trst-delegate-explore",
+  skillDescription: "Use as a sub-agent for bounded read-oriented investigation and findings summaries.",
+  skillFocus: "Explore mode is read-oriented: inspect code, commands, docs, and artifacts; summarize findings and avoid edits unless the task explicitly asks for them.",
+  defaultMode: "explore",
+  defaultMaxTurns: 6,
+  summarize: true
+});
+var delegateSimpleExplore = defineDelegateWorkflow({
+  id: "delegateSimpleExplore",
+  description: "Runs narrow, low-cost read-only exploration while preserving run-local continuity.",
+  skillName: "trst-delegate-simple-explore",
+  skillDescription: "Use as a sub-agent for quick, bounded read-only lookups and summaries.",
+  skillFocus: "Simple explore is read-only and narrow: answer focused repo questions, inspect one area, summarize concise findings, and avoid edits.",
+  defaultMode: "explore",
+  defaultMaxTurns: 4,
+  summarize: true,
+  agentSize: "small",
+  agentThinking: "low"
+});
+var delegateArchitectPlanner = defineDelegateWorkflow({
+  id: "delegateArchitectPlanner",
+  description: "Scouts the codebase to identify the few files or seams likely needing edits.",
+  skillName: "trst-delegate-architect-planner",
+  skillDescription: "Use as a read-only scout that maps a bug or feature request to likely edit targets.",
+  skillFocus: "Architect planner is read-only: grep/read the repo, identify the 3-4 files or seams most likely to need edits, explain why, and do not write code.",
+  defaultMode: "explore",
+  defaultMaxTurns: 6,
+  summarize: true,
+  agentSize: "medium",
+  agentThinking: "medium"
+});
+var delegateReview = defineDelegateWorkflow({
+  id: "delegateReview",
+  description: "Runs delegated review work while preserving run-local continuity.",
+  skillName: "trst-delegate-review",
+  skillDescription: "Use as a sub-agent for focused code, plan, or change review without unnecessary edits.",
+  skillFocus: "Review mode should inspect existing work, identify concrete issues and risks, and avoid edits unless the parent task explicitly requests a fix.",
+  defaultMode: "review",
+  defaultMaxTurns: 6,
+  summarize: false
+});
+var delegateImplement = defineDelegateWorkflow({
+  id: "delegateImplement",
+  description: "Runs delegated implementation work while preserving run-local continuity.",
+  skillName: "trst-delegate-implement",
+  skillDescription: "Use as a sub-agent for bounded implementation tasks that may edit files.",
+  skillFocus: "Implement mode may edit files. Make the smallest safe change, run focused checks when practical, and always report changedFiles/artifacts that were actually produced.",
+  defaultMode: "implement",
+  defaultMaxTurns: 12,
+  summarize: false,
+  agentThinking: "medium"
+});
+var delegateQuickImplementor = defineDelegateWorkflow({
+  id: "delegateQuickImplementor",
+  description: "Runs strict localized implementation work for mechanical changes.",
+  skillName: "trst-delegate-quick-implementor",
+  skillDescription: "Use as a sub-agent for strict, localized boilerplate implementation tasks.",
+  skillFocus: "Quick implementor is the typist: follow concrete instructions, make localized edits only, avoid broad architecture decisions, run focused checks when practical, and report changedFiles.",
+  defaultMode: "implement",
+  defaultMaxTurns: 8,
+  summarize: false,
+  agentSize: "medium",
+  agentThinking: "medium"
+});
+var delegateSmartImplementor = defineDelegateWorkflow({
+  id: "delegateSmartImplementor",
+  description: "Runs complex implementation, algorithmic work, or cross-file refactors.",
+  skillName: "trst-delegate-smart-implementor",
+  skillDescription: "Use as a sub-agent for complex logic, cross-file refactoring, or algorithmic design.",
+  skillFocus: "Smart implementor is the heavy-lifter: handle complex interconnected changes, refactors, algorithms, and non-trivial systems; keep scope bounded and report changedFiles.",
+  defaultMode: "implement",
+  defaultMaxTurns: 14,
+  summarize: false,
+  agentSize: "large",
+  agentThinking: "high"
+});
+var delegateRelentlessDebugger = defineDelegateWorkflow({
+  id: "delegateRelentlessDebugger",
+  description: "Diagnoses and fixes validation, lint, test, or runtime failures.",
+  skillName: "trst-delegate-relentless-debugger",
+  skillDescription: "Use as a sub-agent for repairing linter failures, test failures, stack traces, and diagnostics.",
+  skillFocus: "Relentless debugger is the janitor: consume diagnostics, preserve the intended change, fix failures iteratively, and avoid redesign unless required by the failure evidence.",
+  defaultMode: "implement",
+  defaultMaxTurns: 12,
+  summarize: false,
+  agentSize: "large",
+  agentThinking: "high"
+});
+var delegateSchemaFormatter = defineDelegateWorkflow({
+  id: "delegateSchemaFormatter",
+  description: "Produces exact structured output for schema-bound handoffs.",
+  skillName: "trst-delegate-schema-formatter",
+  skillDescription: "Use as a sub-agent for exact JSON/XML/schema-constrained formatting tasks.",
+  skillFocus: "Schema formatter is the translator: prioritize exact requested structure, avoid extra prose, and do not perform broad implementation work unless explicitly requested.",
+  defaultMode: "general",
+  defaultMaxTurns: 4,
+  summarize: false,
+  agentSize: "small",
+  agentThinking: "low"
+});
+function delegateSkill(config) {
+  return `---
+name: ${config.skillName}
+description: ${config.skillDescription}
+x-trailstep-user-facing: false
+---
+# TrailStep ${config.id} workflow
+
+${config.skillFocus}
+
+Use this workflow as a parent-agent/delegate tool when a parent agent needs bounded work in a repository. The delegate keeps continuity only inside one TrailStep run; separate runs do not share memory.
+
+## Parent-agent usage
+
+- For simple tasks, pass direct flags: \`trailstep @trailstep/sub-agents#${config.id} --task "..."\`.
+- For one-shot JSON, pipe it to \`trailstep @trailstep/sub-agents#${config.id} --input-file -\`; for long/reusable context, write an input JSON file and run \`trailstep @trailstep/sub-agents#${config.id} --input-file delegate-input.json\`.
+- Use unique run names for parallel delegates so their run-local state stays separate.
+- Use \`cwd\` for an existing worktree or subdirectory that TrailStep should not manage. Use \`worktree.enabled=true\` when the delegate should create a managed git worktree and safely clean it up/report it.
+- Do not pass both \`cwd\` and \`worktree.enabled=true\`; choose one execution location strategy.
+- If a delegate asks a question, answer with \`trailstep answer <runName> parent-answer --json '{"answer":"..."}'\`, then resume with \`trailstep continue <runName>\`.
+- Retry a failed turn with \`trailstep retry <workflowRef> <runName>\` when appropriate.
+- Read final typed output with \`trailstep output <runName>\`; read the terminal summary with \`trailstep output <runName> --message\`.
+- Package reference: \`@trailstep/sub-agents#${config.id}\`; built dist reference: \`./packages/sub-agents/dist/index.js#${config.id}\`.
+
+This skill is intended for delegated working-agent use rather than direct end-user planning chat. Preserve the run-local memory supplied in the workflow prompt, keep work bounded to the requested turn, and return the JSON contract requested by the workflow prompt.`;
+}
+
+// src/delegate-parallel/workflow.ts
+import { defineWorkflow as defineWorkflow2, done as done2, parallel, state as state2, step as step2 } from "@trailstep/authoring";
+
+// src/delegate-parallel/schema.ts
+import { jsonSchema as jsonSchema2 } from "@trailstep/authoring";
+var delegateParallelInputShape = jsonSchema2({
+  type: "object",
+  properties: {
+    context: { type: "string" },
+    cwd: { type: "string" },
+    maxTurns: { type: "number" },
+    summarize: { type: "boolean" },
+    worktree: {
+      type: "object",
+      properties: {
+        enabled: { type: "boolean" },
+        path: { type: "string" },
+        baseRef: { type: "string" },
+        baseBranch: { type: "string" },
+        branch: { type: "string" },
+        cleanup: { type: "string", enum: ["auto", "never", "always"] },
+        forceCleanup: { type: "boolean" }
+      },
+      additionalProperties: false
+    },
+    tasks: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          mode: { type: "string", enum: ["explore", "implement", "review", "general"] },
+          delegate: {
+            type: "string",
+            enum: [
+              "delegate",
+              "simple-explore",
+              "architect-planner",
+              "quick-implementor",
+              "smart-implementor",
+              "relentless-debugger",
+              "fixer",
+              "schema-formatter"
+            ]
+          },
+          task: { type: "string" },
+          context: { type: "string" },
+          cwd: { type: "string" },
+          maxTurns: { type: "number" },
+          summarize: { type: "boolean" },
+          worktree: {
+            type: "object",
+            properties: {
+              enabled: { type: "boolean" },
+              path: { type: "string" },
+              baseRef: { type: "string" },
+              baseBranch: { type: "string" },
+              branch: { type: "string" },
+              cleanup: { type: "string", enum: ["auto", "never", "always"] },
+              forceCleanup: { type: "boolean" }
+            },
+            additionalProperties: false
+          }
+        },
+        anyOf: [{ required: ["mode"] }, { required: ["delegate"] }],
+        required: ["id", "task"],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ["tasks"],
+  additionalProperties: false
+});
+var delegateParallelOutputShape = jsonSchema2({
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["completed", "blocked"] },
+    summary: { type: "string" },
+    branches: { type: "object", additionalProperties: true }
+  },
+  required: ["status"],
+  additionalProperties: false
+});
+
+// src/delegate-parallel/workflow.ts
+var delegateParallel = defineWorkflow2({
+  id: "delegateParallel",
+  description: "Fans out required delegate tasks across parallel delegate workflows.",
+  skill: delegateParallelSkill(),
+  inputShape: delegateParallelInputShape,
+  outputShape: delegateParallelOutputShape,
+  start(input) {
+    return initializeDelegateParallelStep(input);
+  }
+});
+var initializeDelegateParallelStep = step2({
+  id: "initialize-delegate-parallel",
+  title: "Initialize parallel delegates"
+}).display(({ input }) => `Preparing ${input.tasks.length} delegates`).do((input) => {
+  const normalized = normalizeDelegateParallelTasks(input, state2.name);
+  if (normalized.status === "blocked") {
+    return done2({ status: "blocked", summary: normalized.summary });
+  }
+  return parallel(
+    normalized.tasks.map(
+      (task) => delegateWorkflowForTask(task)(task.input, { branchId: task.branchId })
+    )
+  );
+});
+function normalizeDelegateParallelTasks(input, runName) {
+  if (input.tasks.length === 0) {
+    return { status: "blocked", summary: "delegateParallel requires at least one task." };
+  }
+  const seenIds = /* @__PURE__ */ new Set();
+  const seenBranches = /* @__PURE__ */ new Set();
+  const tasks = [];
+  for (const task of input.tasks) {
+    const id = task.id.trim();
+    const taskText = task.task.trim();
+    if (id.length === 0) {
+      return { status: "blocked", summary: "delegateParallel task ids must be non-empty." };
+    }
+    if (taskText.length === 0) {
+      return {
+        status: "blocked",
+        summary: `delegateParallel task ${id} must include non-empty task text.`
+      };
+    }
+    if (seenIds.has(id)) {
+      return { status: "blocked", summary: `delegateParallel task id '${id}' is duplicated.` };
+    }
+    seenIds.add(id);
+    const branchId = `delegate-${stableSegment(id)}`;
+    if (seenBranches.has(branchId)) {
+      return {
+        status: "blocked",
+        summary: `delegateParallel task id '${id}' normalizes to duplicate branch id '${branchId}'.`
+      };
+    }
+    seenBranches.add(branchId);
+    const delegateSelection = normalizeDelegateSelection(task.delegate);
+    const mode = task.mode ?? defaultModeForDelegate(delegateSelection);
+    const cwd = nonEmpty(task.cwd) ?? nonEmpty(input.cwd);
+    const worktree = normalizeTaskWorktree({
+      parent: input.worktree,
+      task: task.worktree,
+      cwd,
+      runName,
+      taskSegment: stableSegment(id)
+    });
+    const context = combineContext(input.context, task.context);
+    const maxTurns = task.maxTurns ?? input.maxTurns;
+    const summarize = task.summarize ?? input.summarize;
+    tasks.push({
+      id,
+      mode,
+      ...delegateSelection === void 0 ? {} : { delegate: delegateSelection },
+      branchId,
+      input: {
+        task: taskText,
+        mode,
+        ...context === void 0 ? {} : { context },
+        ...cwd === void 0 ? {} : { cwd },
+        ...maxTurns === void 0 ? {} : { maxTurns },
+        ...summarize === void 0 ? {} : { summarize },
+        ...worktree === void 0 ? {} : { worktree }
+      }
+    });
+  }
+  return { status: "ready", tasks };
+}
+function delegateWorkflowForTask(task) {
+  switch (task.delegate) {
+    case "simple-explore":
+      return delegateSimpleExplore;
+    case "architect-planner":
+      return delegateArchitectPlanner;
+    case "quick-implementor":
+      return delegateQuickImplementor;
+    case "smart-implementor":
+      return delegateSmartImplementor;
+    case "relentless-debugger":
+    case "fixer":
+      return delegateRelentlessDebugger;
+    case "schema-formatter":
+      return delegateSchemaFormatter;
+    case "delegate":
+    case void 0:
+      return delegateWorkflowForMode(task.mode);
+  }
+}
+function delegateWorkflowForMode(mode) {
+  switch (mode) {
+    case "explore":
+      return delegateExplore;
+    case "implement":
+      return delegateImplement;
+    case "review":
+      return delegateReview;
+    case "general":
+      return delegate;
+  }
+}
+function normalizeDelegateSelection(value) {
+  return value === void 0 ? void 0 : value;
+}
+function defaultModeForDelegate(delegateSelection) {
+  switch (delegateSelection) {
+    case "simple-explore":
+    case "architect-planner":
+      return "explore";
+    case "quick-implementor":
+    case "smart-implementor":
+    case "relentless-debugger":
+    case "fixer":
+      return "implement";
+    case "schema-formatter":
+    case "delegate":
+    case void 0:
+      return "general";
+  }
+}
+function normalizeTaskWorktree(input) {
+  if (input.cwd !== void 0) {
+    return input.task?.enabled === true ? input.task : void 0;
+  }
+  const enabled = input.task?.enabled ?? input.parent?.enabled;
+  if (enabled !== true) {
+    return input.task ?? input.parent;
+  }
+  const merged = { ...input.parent, ...input.task, enabled: true };
+  return {
+    ...merged,
+    path: nonEmpty(merged.path) ?? `.trailstep/worktrees/${input.runName}/${input.taskSegment}`,
+    branch: nonEmpty(merged.branch) ?? `trailstep/delegate/${input.runName}/${input.taskSegment}`
+  };
+}
+function combineContext(parent, task) {
+  const parentContext = nonEmpty(parent);
+  const taskContext = nonEmpty(task);
+  if (parentContext === void 0) {
+    return taskContext;
+  }
+  if (taskContext === void 0) {
+    return parentContext;
+  }
+  return `${parentContext}
+
+${taskContext}`;
+}
+function nonEmpty(value) {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : void 0;
+}
+function stableSegment(value) {
+  const segment = value.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return segment.length > 0 ? segment : `task-${hashString(value)}`;
+}
+function hashString(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16);
+}
+function delegateParallelSkill() {
+  return `---
+name: trst-delegate-parallel
+description: Use as a parent-agent fan-out tool for required TrailStep delegate tasks that can run in parallel.
+x-trailstep-user-facing: false
+---
+# TrailStep delegateParallel workflow
+
+Use this workflow when a parent agent already has a set of concrete, independent delegate tasks. It fans out directly to the existing delegate, delegateExplore, delegateReview, and delegateImplement workflows based on each task mode. It does not add a planning agent and does not merge results beyond returning the parallel branch outputs.
+
+Each task must provide a stable \`id\`, \`mode\`, and \`task\` text. Shared \`context\`, \`cwd\`, \`maxTurns\`, \`summarize\`, and \`worktree\` values are applied as defaults; task-level values override them. Managed worktrees under \`worktree.enabled=true\` default per task to \`.trailstep/worktrees/<runName>/<taskId>\` and \`trailstep/delegate/<runName>/<taskId>\` to avoid collisions.`;
+}
+export {
+  delegate,
+  delegateArchitectPlanner,
+  delegateExplore,
+  delegateImplement,
+  delegateParallel,
+  delegateQuickImplementor,
+  delegateRelentlessDebugger,
+  delegateReview,
+  delegateSchemaFormatter,
+  delegateSimpleExplore,
+  delegateSmartImplementor
+};
+//# sourceMappingURL=index.js.map