syntaur 0.41.3 → 0.43.0

package/dist/launch/index.d.ts

@@ -2,7 +2,7 @@ import { SpawnOptions, ChildProcess } from 'node:child_process';
 
 type TerminalChoice = 'terminal-app' | 'iterm' | 'ghostty' | 'alacritty' | 'warp' | 'kitty' | 'cmux';
 
-type OpenUrlErrorCode = 'bad-scheme' | 'bad-host' | 'missing-id' | 'both-ids' | 'malformed' | 'duplicate-param' | 'bad-terminal' | 'bad-mode';
+type OpenUrlErrorCode = 'bad-scheme' | 'bad-host' | 'missing-id' | 'both-ids' | 'malformed' | 'duplicate-param' | 'bad-terminal' | 'bad-mode' | 'invalid-prompt';
 declare class OpenUrlError extends Error {
     readonly code: OpenUrlErrorCode;
     constructor(code: OpenUrlErrorCode, message: string);
@@ -34,6 +34,15 @@ interface ParsedOpenUrl {
      * parsed-but-ignored rather than rejected (keeps the parser simple).
      */
     agent?: string;
+    /**
+     * Optional one-shot launch-prompt override (the `prompt=` query param) — the
+     * dashboard's editable prompt box sends the (possibly edited) template here.
+     * Only set for `kind === 'assignment'` (sessions take their first message
+     * from history). Single-line and length-bounded (`MAX_OPEN_PROMPT_LENGTH`).
+     * Presence-significant: an empty string is a deliberate override (re-resolves
+     * to the fallback seed), distinct from `undefined` (no override).
+     */
+    prompt?: string;
 }
 /**
  * Parse a `syntaur://open?assignment=<id>` or `syntaur://open?session=<id>` URL.
@@ -85,12 +94,22 @@ interface AgentConfig {
      */
     model?: string;
     /**
-     * Optional playbook slug for this runner profile. When set, a fresh "Open in
-     * agent" launch seeds a prompt that grabs the assignment AND runs this
-     * playbook end-to-end (see `INITIAL_PROMPT`). Blank/undefined keeps the plain
-     * `/grab-assignment` seed.
+     * Optional playbook slug for this runner profile. Back-compat shorthand: when
+     * set (and no `launchPrompt`), a fresh "Open in agent" launch synthesizes a
+     * prompt that grabs the assignment AND runs this playbook end-to-end (see
+     * `resolveLaunchPrompt`). Blank/undefined keeps the plain `/grab-assignment`
+     * seed. Ignored for seed assembly when `launchPrompt` is also set.
      */
     playbook?: string;
+    /**
+     * Editable, user-owned launch prompt: the literal first message handed to the
+     * agent on a fresh "Open in agent" launch, with `@`-tokens resolved at launch
+     * time (`@assignment` → assignment id + records-dir path + grab/read
+     * instructions; `@<playbook-slug>` → a `/run-playbook` reference). When unset,
+     * falls back to back-compat `playbook`, then to the bare `/grab-assignment`
+     * seed. Takes precedence over `playbook`. Single-line (see `serializeAgentsConfig`).
+     */
+    launchPrompt?: string;
 }
 
 interface WorkspaceVisibilityConfig {
@@ -114,10 +133,43 @@ interface StatusTransition {
     description?: string;
     requiresReason?: boolean;
 }
+/** One rung of the phase ladder (derived-status v3). Ordered low → high; the
+ * HIGHEST rung whose AQL `when` holds wins. Regressible by design (e.g. a
+ * replan invalidates approval and the phase drops). `phase` must be a defined
+ * status id; `next` is the human next-action label surfaced by views. */
+interface PhaseRung {
+    phase: string;
+    when: string;
+    next?: string;
+}
+/** One disposition rule (first match wins). `when: null` is the `else` arm.
+ * `is` ∈ active|blocked|parked (terminal is never a rule — terminal statuses
+ * defer derivation entirely). */
+interface DispositionRule {
+    when: string | null;
+    is: string;
+}
+/** Headline projection: which status id the single-column board shows.
+ * `terminal` is always passthrough and `active` always shows the phase; the
+ * configurable parts are which status ids represent parked/blocked. */
+interface HeadlineProjection {
+    terminal: 'passthrough';
+    parked: string;
+    blocked: string;
+    active: 'phase';
+}
+interface DeriveConfig {
+    phaseLadder: PhaseRung[];
+    disposition: DispositionRule[];
+    headline: HeadlineProjection;
+}
 interface StatusConfig {
     statuses: StatusDefinition[];
     order: string[];
     transitions: StatusTransition[];
+    /** Derived-status rules (v3). Null/absent → DEFAULT_DERIVE_CONFIG at resolve
+     * time. Persisted under `statuses:` so the Settings writer round-trips it. */
+    derive?: DeriveConfig | null;
 }
 interface TypeDefinition {
     id: string;
@@ -210,6 +262,8 @@ interface LaunchPlan {
     fallbackWarning: string | null;
     /** Non-fatal warning from shell-alias resolution falling back to /bin/sh. */
     shellFallbackWarning: string | null;
+    /** Non-fatal launch-prompt token warnings (unknown/malformed `@`-tokens). */
+    promptWarnings?: string[];
 }
 interface ResolveLaunchPlanInput {
     kind: 'assignment' | 'session';
@@ -238,6 +292,16 @@ interface ResolveLaunchPlanInput {
      * `LaunchError('agent-not-configured')`.
      */
     agentId?: string;
+    /**
+     * Only consulted when `kind === 'assignment'`. A one-shot launch-prompt
+     * override, wired from `?prompt=<text>` on the incoming `syntaur://` URL (the
+     * dashboard's editable prompt box). **Presence-significant:** when defined
+     * (including `''`) it is used as the `template` for `resolveLaunchPrompt`
+     * instead of `agent.launchPrompt`, so its `@`-tokens re-resolve and an empty
+     * value falls back through the normal empty-template path (never silently
+     * reusing `agent.launchPrompt`). Per-launch only — never written to config.
+     */
+    promptOverride?: string;
 }
 /**
  * Pick the agent the "Open in agent" flow should use. Order of preference:
@@ -340,6 +404,95 @@ declare const buildFreshArgv: typeof buildAgentArgv;
  */
 declare function buildSessionArgv(agent: AgentConfig, sessionId: string, mode: SessionMode, env?: NodeJS.ProcessEnv): BuiltArgv;
 
+/**
+ * Editable launch-prompt resolution.
+ *
+ * An agent profile may carry an editable `launchPrompt` template whose
+ * `@`-tokens are expanded at launch time. This module is the single, pure home
+ * for that expansion plus the low-level seed builders shared with the
+ * (deprecated) `INITIAL_PROMPT`. It deliberately imports nothing from
+ * `../tui/launch.js` so there is no import cycle (`argv.ts` imports `tui/launch`,
+ * and `launch/index.ts` re-exports `argv.ts`) — callers import this module
+ * directly, not via the `launch/index.js` barrel.
+ */
+/**
+ * The bare `/grab-assignment` seed — today's zero-config launch behavior. This
+ * is the single source of these strings, shared by `resolveLaunchPrompt`'s
+ * no-template fallback and `INITIAL_PROMPT`'s no-playbook branch (kept
+ * byte-identical for back-compat).
+ */
+declare function bareGrabSeed(params: {
+    projectSlug: string | null;
+    assignmentSlug: string;
+    id?: string;
+}): string;
+/**
+ * The noun phrase a `@<playbook-slug>` token resolves to. The template author
+ * writes the surrounding verbs. NOTE: this is the new "via the /run-playbook
+ * skill" wording used ONLY by the resolver — `INITIAL_PROMPT`'s legacy playbook
+ * branch keeps its own "using the /run-playbook skill" sentence.
+ */
+declare function runPlaybookClause(slug: string): string;
+interface ResolveLaunchPromptInput {
+    /** The agent's editable launch prompt template (may contain `@`-tokens). */
+    template?: string | null;
+    /** Back-compat playbook slug; used only when `template` is empty. */
+    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. */
+    projectSlug: string | null;
+    assignmentSlug: 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
+     * undefined, every well-formed slug resolves without validation.
+     */
+    knownPlaybookSlugs?: ReadonlySet<string>;
+}
+interface ResolveLaunchPromptResult {
+    prompt: string;
+    /** Non-fatal warnings (unknown/malformed `@`-tokens). Never throws. */
+    warnings: string[];
+}
+/**
+ * Resolve the launch seed for a fresh "Open in agent" launch. Pure: never reads
+ * the filesystem, never prints. The caller owns warning output.
+ *
+ * Fallback chain:
+ *   1. `template` (trimmed non-empty) → resolve its `@`-tokens.
+ *   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.
+ * `template` wins over `playbook`.
+ */
+declare function resolveLaunchPrompt(input: ResolveLaunchPromptInput): ResolveLaunchPromptResult;
+/**
+ * The editable **template** to prefill the dashboard's "Open in agent" prompt
+ * box — NOT the resolved text. Returns:
+ *   - `launchPrompt` verbatim when set (non-empty after trim); else
+ *   - a synth template `@assignment Run <runPlaybookClause(playbook)> end-to-end.`
+ *     when `playbook` is set — the playbook clause is LITERAL (only `@assignment`
+ *     is a token), so re-resolving this through `resolveLaunchPrompt` reproduces
+ *     this module's playbook synth (above) byte-for-byte for ANY playbook
+ *     (installed / disabled / uninstalled / the reserved `assignment`); else
+ *   - the bare `/grab-assignment` seed (no `@`-tokens).
+ *
+ * Prefilling the template (not resolved text) and resolving exactly once at
+ * launch avoids re-tokenizing an `@<slug>` that may appear inside an expanded
+ * records-dir path.
+ */
+declare function effectiveLaunchTemplate(input: {
+    launchPrompt?: string | null;
+    playbook?: string | null;
+    projectSlug: string | null;
+    assignmentSlug: string;
+    id?: string;
+}): string;
+
 type InstallKind = 'npx' | 'global' | 'local' | 'unknown';
 interface DetectOptions {
     realpath?: (p: string) => string;
@@ -387,4 +540,4 @@ declare function shouldNudgeForNpx(hash: string | null): Promise<boolean>;
  */
 declare function maybeNudgeForNpxInstall(scriptUrl: string): Promise<void>;
 
-export { type BuiltArgv, type InstallKind, LaunchError, type LaunchErrorCode, type LaunchPlan, OpenUrlError, type OpenUrlErrorCode, type ParsedOpenUrl, type ResolveLaunchPlanInput, type ResolvedArgv, type SessionMode, type SpawnFn, TerminalNotFoundError, buildFreshArgv, buildSessionArgv, buildShellCommandLine, buildTerminalInvocation, detectInstallKind, executeLaunchPlan, extractNpxHash, hasNudgedHash, isHandlerNudgeDisabled, maybeNudgeForNpxInstall, nudgeMessage, nudgeStampDir, nudgeStampPath, parseOpenUrl, pickAgent, recordNudge, resolveLaunchPlan, shouldNudgeForNpx };
+export { type BuiltArgv, type InstallKind, LaunchError, type LaunchErrorCode, type LaunchPlan, OpenUrlError, type OpenUrlErrorCode, type ParsedOpenUrl, type ResolveLaunchPlanInput, type ResolveLaunchPromptInput, type ResolveLaunchPromptResult, type ResolvedArgv, type SessionMode, type SpawnFn, TerminalNotFoundError, bareGrabSeed, buildFreshArgv, buildSessionArgv, buildShellCommandLine, buildTerminalInvocation, detectInstallKind, effectiveLaunchTemplate, executeLaunchPlan, extractNpxHash, hasNudgedHash, isHandlerNudgeDisabled, maybeNudgeForNpxInstall, nudgeMessage, nudgeStampDir, nudgeStampPath, parseOpenUrl, pickAgent, recordNudge, resolveLaunchPlan, resolveLaunchPrompt, runPlaybookClause, shouldNudgeForNpx };