syntaur 0.74.0 → 0.76.0

package/dist/launch/index.d.ts

@@ -9,7 +9,7 @@ declare class OpenUrlError extends Error {
 }
 type SessionMode = 'resume' | 'fork';
 interface ParsedOpenUrl {
-    kind: 'assignment' | 'session';
+    kind: 'assignment' | 'session' | 'standalone';
     id: string;
     /**
      * Optional one-shot terminal override. When present, the launch plan uses
@@ -43,6 +43,13 @@ interface ParsedOpenUrl {
      * to the fallback seed), distinct from `undefined` (no override).
      */
     prompt?: string;
+    /**
+     * Optional one-shot Claude `--agent <name>` identity (the `agentName=` query
+     * param). The dashboard's discovered-agent picker sends a chosen agent
+     * definition here so the launched session adopts it. Only set for
+     * `kind === 'assignment'`. Length-bounded like `prompt`.
+     */
+    agentName?: string;
 }
 /**
  * Parse a `syntaur://open?assignment=<id>` or `syntaur://open?session=<id>` URL.
@@ -110,6 +117,24 @@ interface AgentConfig {
      * seed. Takes precedence over `playbook`. Single-line (see `serializeAgentsConfig`).
      */
     launchPrompt?: string;
+    /**
+     * Optional Claude agent identity, injected as `--agent <value>` (see
+     * `agentNameArgs`). When set, the launched session adopts that agent's
+     * definition (system prompt + its own model frontmatter), so any profile
+     * `model` is suppressed on a fresh launch (see `buildAgentArgv`). Mutually
+     * exclusive with `workdir`. Meaningful only for Claude-compatible runners;
+     * `--agent` is simply injected when present regardless of runner. Single-line.
+     */
+    agentName?: string;
+    /**
+     * Optional launch cwd override (absolute or `~`-prefixed) for directory-style
+     * agents (pi/codex) that load their identity from a launch directory. When set,
+     * the session is spawned from this directory instead of the worktree, and the
+     * worktree path is injected into the launch prompt (`@worktree` / a synthesized
+     * seed) so the agent can `cd` into the code. Mutually exclusive with
+     * `agentName`. Existence is validated at launch time, not at config-write time.
+     */
+    workdir?: string;
 }
 
 /**
@@ -371,7 +396,7 @@ interface LaunchPlan {
     };
 }
 interface ResolveLaunchPlanInput {
-    kind: 'assignment' | 'session';
+    kind: 'assignment' | 'session' | 'standalone';
     id: string;
     /**
      * Only consulted when `kind === 'session'`. Defaults to `'resume'` so
@@ -407,6 +432,14 @@ interface ResolveLaunchPlanInput {
      * reusing `agent.launchPrompt`). Per-launch only — never written to config.
      */
     promptOverride?: string;
+    /**
+     * Only consulted when `kind === 'assignment'`. A one-shot Claude `--agent
+     * <name>` identity, wired from `?agentName=<name>` on the incoming
+     * `syntaur://` URL (the dashboard's discovered-agent picker). When defined it
+     * is applied over the resolved agent before argv assembly, so the launched
+     * session adopts that agent definition. Presence-significant; per-launch only.
+     */
+    agentName?: string;
 }
 /**
  * Pick the agent the "Open in agent" flow should use. Order of preference:
@@ -558,11 +591,28 @@ interface ResolveLaunchPromptInput {
     playbook?: string | null;
     /** Assignment id (optional only to represent the rare slug-fallback seed). */
     id?: string;
-    /** Records directory (where assignment.md lives), for `@assignment`. */
-    assignmentDir: string;
-    /** Null for a standalone assignment. */
+    /**
+     * Records directory (where assignment.md lives), for `@assignment`. Optional:
+     * standalone launches have no assignment, so `@assignment` warns + stays
+     * literal when this is absent.
+     */
+    assignmentDir?: string;
+    /** Null for a standalone assignment (required-but-nullable — pass `null`). */
     projectSlug: string | null;
-    assignmentSlug: string;
+    /** Optional: absent for standalone launches (no assignment). */
+    assignmentSlug?: string;
+    /**
+     * Absolute worktree path, for the `@worktree` token and the directory-agent
+     * (`workdir`) default seed. Absent for standalone launches and for plain
+     * launches with no worktree; `@worktree` warns + stays literal when absent.
+     */
+    worktreePath?: string;
+    /**
+     * The directory the agent process is actually spawned from. When it differs
+     * from `worktreePath` the agent is a directory-agent (`workdir` set), which
+     * triggers the worktree-injecting default seed. Absent → no workdir agent.
+     */
+    spawnCwd?: string;
     /**
      * Installed playbook slugs, injected by the call site. When provided, a
      * well-formed `@<slug>` not in this set warns and is left literal. When
@@ -584,7 +634,11 @@ interface ResolveLaunchPromptResult {
  *   2. else `playbook` set → synthesize `<@assignment pointer> Run <clause> end-to-end.`
  *      (built directly — no `@`-token re-resolution, so a playbook literally named
  *      `assignment` cannot collide with the reserved token).
- *   3. else → today's bare `/grab-assignment` seed.
+ *   3. else directory-agent (`worktreePath` set and != `spawnCwd`) → a plain-language
+ *      seed pointing at the worktree + a `cd`/grab instruction (plain language
+ *      because a single message fires only one leading slash-command).
+ *   4. else assignment context present → today's bare `/grab-assignment` seed.
+ *   5. else (standalone, no template/playbook) → empty prompt.
  * `template` wins over `playbook`.
  */
 declare function resolveLaunchPrompt(input: ResolveLaunchPromptInput): ResolveLaunchPromptResult;
@@ -609,6 +663,14 @@ declare function effectiveLaunchTemplate(input: {
     projectSlug: string | null;
     assignmentSlug: string;
     id?: string;
+    /**
+     * Set when the agent is a directory-agent (`workdir`). With no explicit
+     * `launchPrompt`/`playbook`, the box prefills a `@worktree`-based seed so that
+     * re-resolving it at launch (as `promptOverride`) injects the worktree path —
+     * a plain bare seed would drop it. The token (not the resolved path) is used
+     * so the single resolve at launch fills it in.
+     */
+    workdir?: string | null;
 }): string;
 
 type InstallKind = 'npx' | 'global' | 'local' | 'unknown';

package/dist/launch/index.js

@@ -1235,6 +1235,10 @@ function modelFlagArgs(agent) {
   const m = agent.model?.trim();
   return m ? ["--model", m] : [];
 }
+function agentNameArgs(agent) {
+  const n = agent.agentName?.trim();
+  return n ? ["--agent", n] : [];
+}
 function stripModelFlags(args) {
   const out = [];
   for (let i = 0; i < args.length; i++) {
@@ -2532,6 +2536,26 @@ function validateAgentList(agents) {
         `agent "${agent.id}" has invalid launchPrompt \u2014 must be a single line (no newlines)`
       );
     }
+    if (agent.agentName !== void 0 && /[\r\n]/.test(agent.agentName)) {
+      throw new AgentConfigError(
+        `agent "${agent.id}" has invalid agentName \u2014 must be a single line (no newlines)`
+      );
+    }
+    if (agent.workdir !== void 0 && /[\r\n]/.test(agent.workdir)) {
+      throw new AgentConfigError(
+        `agent "${agent.id}" has invalid workdir \u2014 must be a single line (no newlines)`
+      );
+    }
+    if (agent.agentName !== void 0 && agent.agentName.trim() !== "" && agent.workdir !== void 0 && agent.workdir.trim() !== "") {
+      throw new AgentConfigError(
+        `agent "${agent.id}" sets both agentName and workdir \u2014 these are mutually exclusive`
+      );
+    }
+    if (agent.agentName !== void 0 && agent.agentName.trim() !== "" && agent.model !== void 0 && agent.model.trim() !== "") {
+      throw new AgentConfigError(
+        `agent "${agent.id}" sets both agentName and model \u2014 the agent definition's own model is authoritative; remove the profile model`
+      );
+    }
     validateSessionInvocation(agent, "resume", agent.resume);
     validateSessionInvocation(agent, "fork", agent.fork);
     if (agent.default) defaults++;
@@ -3352,6 +3376,8 @@ function parseAgentsConfig(content) {
       ...current.model ? { model: current.model } : {},
       ...current.playbook ? { playbook: current.playbook } : {},
       ...current.launchPrompt ? { launchPrompt: current.launchPrompt } : {},
+      ...current.agentName ? { agentName: current.agentName } : {},
+      ...current.workdir ? { workdir: current.workdir } : {},
       ...current.resume ? { resume: current.resume } : {},
       ...current.fork ? { fork: current.fork } : {}
     });
@@ -3543,6 +3569,12 @@ function assignAgentField(target, key, rawValue) {
     case "launchPrompt":
       target.launchPrompt = value;
       break;
+    case "agentName":
+      target.agentName = value;
+      break;
+    case "workdir":
+      target.workdir = value;
+      break;
   }
 }
 function yamlQuoteScalar(value) {
@@ -3572,6 +3604,12 @@ function serializeAgentsConfig(agents) {
     if (a.launchPrompt) {
       lines.push(`    launchPrompt: ${yamlQuoteScalar(a.launchPrompt)}`);
     }
+    if (a.agentName) {
+      lines.push(`    agentName: ${yamlQuoteScalar(a.agentName)}`);
+    }
+    if (a.workdir) {
+      lines.push(`    workdir: ${yamlQuoteScalar(a.workdir)}`);
+    }
     if (a.args && a.args.length > 0) {
       lines.push(`    args:`);
       for (const arg of a.args) {
@@ -4219,7 +4257,9 @@ var init_config2 = __esm({
       "resolveFromShellAliases",
       "model",
       "playbook",
-      "launchPrompt"
+      "launchPrompt",
+      "agentName",
+      "workdir"
     ]);
     migratedConfigPaths = /* @__PURE__ */ new Set();
     TerminalConfigError = class extends Error {
@@ -4463,6 +4503,21 @@ function resolveWorkspaceCwd(input) {
     invalidReason: `workspace path invalid for ${assignmentSlug}: tried worktreePath ${shown(worktreePath)} and repository ${shown(repository)} \u2014 neither is an existing directory`
   };
 }
+function resolveLaunchCwd(agent, worktreeCwd) {
+  const wd = agent.workdir?.trim();
+  if (wd) {
+    const expanded = expandHome(wd);
+    if (!isExistingDir(expanded)) {
+      return {
+        spawnCwd: worktreeCwd,
+        worktreePath: worktreeCwd,
+        invalidReason: `agent "${agent.id}" workdir ${agent.workdir} (resolved ${expanded}) is not an existing directory`
+      };
+    }
+    return { spawnCwd: expanded, worktreePath: worktreeCwd, invalidReason: null };
+  }
+  return { spawnCwd: worktreeCwd, worktreePath: worktreeCwd, invalidReason: null };
+}
 function formatFallbackCwdWarning(opts) {
   const missing = [];
   if (!opts.worktreePath) missing.push("worktreePath");
@@ -4474,6 +4529,7 @@ function formatFallbackCwdWarning(opts) {
 var init_cwd = __esm({
   "src/launch/cwd.ts"() {
     "use strict";
+    init_paths();
   }
 });
 
@@ -6982,6 +7038,7 @@ function parseOpenUrl(input) {
   }
   const assignmentVals = url.searchParams.getAll("assignment");
   const sessionVals = url.searchParams.getAll("session");
+  const standaloneVals = url.searchParams.getAll("standalone");
   if (assignmentVals.length > 1) {
     throw new OpenUrlError(
       "duplicate-param",
@@ -6994,10 +7051,17 @@ function parseOpenUrl(input) {
       "URL has more than one `session` query param"
     );
   }
-  if (assignmentVals.length === 1 && sessionVals.length === 1) {
+  if (standaloneVals.length > 1) {
+    throw new OpenUrlError(
+      "duplicate-param",
+      "URL has more than one `standalone` query param"
+    );
+  }
+  const kindsPresent = assignmentVals.length + sessionVals.length + standaloneVals.length;
+  if (kindsPresent > 1) {
     throw new OpenUrlError(
       "both-ids",
-      "URL has both `assignment` and `session` query params \u2014 only one is allowed"
+      "URL has more than one of `assignment`, `session`, `standalone` \u2014 only one is allowed"
     );
   }
   const terminalVals = url.searchParams.getAll("terminal");
@@ -7047,6 +7111,37 @@ function parseOpenUrl(input) {
     }
     prompt = value;
   }
+  const agentNameVals = url.searchParams.getAll("agentName");
+  if (agentNameVals.length > 1) {
+    throw new OpenUrlError(
+      "duplicate-param",
+      "URL has more than one `agentName` query param"
+    );
+  }
+  let agentName;
+  if (agentNameVals.length === 1 && agentNameVals[0].trim() !== "") {
+    const value = agentNameVals[0];
+    if (value.length > MAX_OPEN_PROMPT_LENGTH) {
+      throw new OpenUrlError(
+        "invalid-prompt",
+        `\`agentName\` query param exceeds ${MAX_OPEN_PROMPT_LENGTH} characters`
+      );
+    }
+    agentName = value;
+  }
+  if (standaloneVals.length === 1) {
+    const id = standaloneVals[0];
+    if (id.trim() === "") {
+      throw new OpenUrlError("missing-id", "`standalone` query param is empty");
+    }
+    return {
+      kind: "standalone",
+      id,
+      ...terminal ? { terminal } : {},
+      // standalone identifies the agent by `id`; keep an optional prompt override.
+      ...prompt !== void 0 ? { prompt } : {}
+    };
+  }
   if (assignmentVals.length === 1) {
     const id = assignmentVals[0];
     if (id.trim() === "") {
@@ -7061,7 +7156,8 @@ function parseOpenUrl(input) {
       ...terminal ? { terminal } : {},
       ...agent ? { agent } : {},
       // assignment-only; keep '' (presence-significant) — hence !== undefined.
-      ...prompt !== void 0 ? { prompt } : {}
+      ...prompt !== void 0 ? { prompt } : {},
+      ...agentName ? { agentName } : {}
     };
   }
   if (sessionVals.length === 1) {
@@ -7097,7 +7193,7 @@ function parseOpenUrl(input) {
   }
   throw new OpenUrlError(
     "missing-id",
-    "URL must include either `assignment=<id>` or `session=<id>`"
+    "URL must include one of `assignment=<id>`, `session=<id>`, or `standalone=<agentId>`"
   );
 }
 
@@ -7129,8 +7225,19 @@ function resolveTemplate(template, ctx) {
   const warnings = [];
   const prompt = template.replace(TOKEN_RE, (_match, boundary, token) => {
     if (token === "assignment") {
+      if (!ctx.assignmentDir) {
+        warnings.push(`launchPrompt: "@assignment" has no assignment context here \u2014 left as literal text.`);
+        return boundary + "@assignment";
+      }
       return boundary + assignmentPointer(ctx.id, ctx.assignmentDir);
     }
+    if (token === "worktree") {
+      if (!ctx.worktreePath) {
+        warnings.push(`launchPrompt: "@worktree" has no worktree path here \u2014 left as literal text.`);
+        return boundary + "@worktree";
+      }
+      return boundary + ctx.worktreePath;
+    }
     if (!isValidSlug(token)) {
       warnings.push(`launchPrompt: "@${token}" is not a valid playbook token \u2014 left as literal text.`);
       return boundary + "@" + token;
@@ -7144,16 +7251,37 @@ function resolveTemplate(template, ctx) {
   return { prompt, warnings };
 }
 function resolveLaunchPrompt(input) {
-  const { template, playbook, id, assignmentDir, projectSlug, assignmentSlug, knownPlaybookSlugs } = input;
+  const {
+    template,
+    playbook,
+    id,
+    assignmentDir,
+    projectSlug,
+    assignmentSlug,
+    worktreePath,
+    spawnCwd,
+    knownPlaybookSlugs
+  } = input;
   if (template && template.trim()) {
-    return resolveTemplate(template, { id, assignmentDir, knownPlaybookSlugs });
+    return resolveTemplate(template, { id, assignmentDir, worktreePath, knownPlaybookSlugs });
   }
   const pb = playbook?.trim();
   if (pb) {
-    const pointer = assignmentPointer(id, assignmentDir);
-    return { prompt: `${pointer} Run ${runPlaybookClause(pb)} end-to-end.`, warnings: [] };
+    const clause = runPlaybookClause(pb);
+    const prompt = assignmentDir ? `${assignmentPointer(id, assignmentDir)} Run ${clause} end-to-end.` : `Run ${clause} end-to-end.`;
+    return { prompt, warnings: [] };
   }
-  return { prompt: bareGrabSeed({ projectSlug, assignmentSlug, id }), warnings: [] };
+  if (worktreePath && spawnCwd && worktreePath !== spawnCwd) {
+    const grab = bareGrabSeed({ projectSlug, assignmentSlug: assignmentSlug ?? "", id });
+    return {
+      prompt: `The assignment's worktree is at ${worktreePath}. cd there, then grab the assignment with ${grab} and work it end-to-end.`,
+      warnings: []
+    };
+  }
+  if (!assignmentSlug && !id) {
+    return { prompt: "", warnings: [] };
+  }
+  return { prompt: bareGrabSeed({ projectSlug, assignmentSlug: assignmentSlug ?? "", id }), warnings: [] };
 }
 function effectiveLaunchTemplate(input) {
   if (input.launchPrompt && input.launchPrompt.trim()) {
@@ -7163,6 +7291,14 @@ function effectiveLaunchTemplate(input) {
   if (pb) {
     return `@assignment Run ${runPlaybookClause(pb)} end-to-end.`;
   }
+  if (input.workdir && input.workdir.trim()) {
+    const grab = bareGrabSeed({
+      projectSlug: input.projectSlug,
+      assignmentSlug: input.assignmentSlug,
+      id: input.id
+    });
+    return `The assignment's worktree is at @worktree. cd there, then grab the assignment with ${grab} and work it end-to-end.`;
+  }
   return bareGrabSeed({
     projectSlug: input.projectSlug,
     assignmentSlug: input.assignmentSlug,
@@ -7196,8 +7332,10 @@ function shellQuote(arg) {
 }
 function buildAgentArgv(agent, prompt, env = process.env) {
   const position = agent.promptArgPosition ?? "first";
-  const baseArgs = applyModelFlag(agent, [...agent.args ?? []]);
-  const agentArgs = position === "first" ? [prompt, ...baseArgs] : position === "last" ? [...baseArgs, prompt] : baseArgs;
+  const prefix = agentNameArgs(agent);
+  const baseArgs = agent.agentName ? [...agent.args ?? []] : applyModelFlag(agent, [...agent.args ?? []]);
+  const positioned = position === "first" ? [prompt, ...baseArgs] : position === "last" ? [...baseArgs, prompt] : baseArgs;
+  const agentArgs = [...prefix, ...positioned];
   if (agent.resolveFromShellAliases) {
     const requested = env.SHELL;
     let shell = requested;
@@ -7277,8 +7415,60 @@ async function resolveLaunchPlan(input) {
   if (input.kind === "assignment") {
     return resolveAssignmentPlan(input, terminal);
   }
+  if (input.kind === "standalone") {
+    return resolveStandalonePlan(input, terminal);
+  }
   return resolveSessionPlan(input, terminal);
 }
+async function resolveStandalonePlan(input, terminal) {
+  const agentId = input.agentId ?? input.id;
+  if (!agentId) {
+    throw new LaunchError(
+      "agent-not-configured",
+      "A standalone launch requires an agent id."
+    );
+  }
+  const agent = getAgents(input.config).find((a) => a.id === agentId);
+  if (!agent) {
+    throw new LaunchError(
+      "agent-not-configured",
+      `Agent "${agentId}" requested for a standalone launch is not in your agents list.`
+    );
+  }
+  const wd = agent.workdir?.trim();
+  if (!wd) {
+    throw new LaunchError(
+      "workspace-path-invalid",
+      `Agent "${agent.id}" has no workdir \u2014 a standalone launch requires a valid workdir.`
+    );
+  }
+  const expanded = expandHome(wd);
+  if (!isExistingDir(expanded)) {
+    throw new LaunchError(
+      "workspace-path-invalid",
+      `Agent "${agent.id}" workdir ${agent.workdir} (resolved ${expanded}) is not an existing directory \u2014 a standalone launch requires a valid workdir.`
+    );
+  }
+  const knownPlaybookSlugs = await listPlaybookSlugs(playbooksDir());
+  const template = input.promptOverride !== void 0 ? input.promptOverride : agent.launchPrompt;
+  const { prompt, warnings: promptWarnings } = resolveLaunchPrompt({
+    template,
+    playbook: agent.playbook,
+    projectSlug: null,
+    knownPlaybookSlugs
+  });
+  const { argv, shellFallbackWarning } = buildFreshArgv(agent, prompt);
+  return {
+    terminal,
+    cwd: expanded,
+    argv,
+    env: process.env,
+    agentId: agent.id,
+    fallbackWarning: null,
+    shellFallbackWarning,
+    promptWarnings
+  };
+}
 async function resolveAssignmentPlan(input, terminal) {
   const resolved = await resolveAssignmentById(
     input.projectsDir,
@@ -7302,17 +7492,6 @@ async function resolveAssignmentPlan(input, terminal) {
       `Assignment ${input.id} resolver returned a directory but detail could not be loaded`
     );
   }
-  const picked = resolveWorkspaceCwd({
-    worktreePath: detail.workspace.worktreePath,
-    repository: detail.workspace.repository,
-    branch: detail.workspace.branch,
-    assignmentSlug: resolved.assignmentSlug
-  });
-  if (picked.cwd === null) {
-    throw new LaunchError("workspace-path-invalid", picked.invalidReason);
-  }
-  const cwd = picked.cwd;
-  const fallbackWarning = picked.fallbackWarning;
   let agent;
   if (input.agentId) {
     const found = getAgents(input.config).find((a) => a.id === input.agentId);
@@ -7326,6 +7505,30 @@ async function resolveAssignmentPlan(input, terminal) {
   } else {
     agent = pickAgent(input.config);
   }
+  if (input.agentName !== void 0) {
+    agent = { ...agent, agentName: input.agentName };
+  }
+  const picked = resolveWorkspaceCwd({
+    worktreePath: detail.workspace.worktreePath,
+    repository: detail.workspace.repository,
+    branch: detail.workspace.branch,
+    assignmentSlug: resolved.assignmentSlug
+  });
+  if (picked.cwd === null) {
+    throw new LaunchError("workspace-path-invalid", picked.invalidReason);
+  }
+  const launchCwd = resolveLaunchCwd(agent, picked.cwd);
+  if (launchCwd.invalidReason) {
+    throw new LaunchError("workspace-path-invalid", launchCwd.invalidReason);
+  }
+  const cwd = launchCwd.spawnCwd;
+  const fallbackWarning = picked.fallbackWarning;
+  const promptWarningsExtra = [];
+  if (input.agentName !== void 0 && input.agentName.trim() && agent.model?.trim()) {
+    promptWarningsExtra.push(
+      `profile model "${agent.model.trim()}" suppressed: agent "${input.agentName.trim()}" defines its own model`
+    );
+  }
   const knownPlaybookSlugs = await listPlaybookSlugs(playbooksDir());
   const template = input.promptOverride !== void 0 ? input.promptOverride : agent.launchPrompt;
   const { prompt, warnings: promptWarnings } = resolveLaunchPrompt({
@@ -7335,6 +7538,8 @@ async function resolveAssignmentPlan(input, terminal) {
     assignmentDir: resolved.assignmentDir,
     projectSlug: resolved.projectSlug,
     assignmentSlug: resolved.assignmentSlug,
+    worktreePath: launchCwd.worktreePath,
+    spawnCwd: launchCwd.spawnCwd,
     knownPlaybookSlugs
   });
   const { argv, shellFallbackWarning } = buildFreshArgv(agent, prompt);
@@ -7346,7 +7551,7 @@ async function resolveAssignmentPlan(input, terminal) {
     agentId: agent.id,
     fallbackWarning,
     shellFallbackWarning,
-    promptWarnings
+    promptWarnings: [...promptWarningsExtra, ...promptWarnings]
   };
 }
 async function resolveSessionPlan(input, terminal) {