[PromptResolver] inline vs promptFile

[pyadav]

Parent

#1

What to build

First module of the prompt pipeline. Resolves the prompt input: either an inline prompt (passed through to the agent as-is) or a prompt template (file loaded from disk; substitution + expansion happen in later slices). Validates mutual exclusion and the inline-prompt-bypass contract (per ADR 0008).

Vocabulary: this module is the PromptResolver per the project's module map.

Acceptance criteria

• PromptResolver accepts { prompt } or { promptFile } and returns a tagged result indicating which path the prompt came from (so downstream stages can decide whether to substitute/expand)
• prompt and promptFile are mutually exclusive at the type level (already enforced in [Types] Public types, interfaces, entry-point stubs (no implementation) #3); runtime check throws if both are passed (defense in depth)
• promptArgs combined with inline prompt throws (per CONTEXT.md and ADR 0008)
• promptFile resolves relative paths against process.cwd() (caller's perspective, NOT the run's cwd option)
• Missing promptFile throws an actionable error naming the resolved absolute path
• Inline prompt path returns the string verbatim with no processing
• Unit tests cover: inline path, file path, both passed, neither passed, promptArgs + inline, missing file
• bun test and bun run typecheck pass

Blocked by

• [Tracer bullet] run() with Docker + Claude Code + head + inline prompt #4

[pyadav]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Build the PromptResolver module — first stage of the prompt pipeline that distinguishes an inline prompt from a prompt template and produces a tagged result for downstream stages.

Current behavior:
The implemented entry point (run() → runProgram) hard-rejects anything other than an inline prompt with the message "promptFile is not yet supported". The PromptOption type in @missingstudio/sanddune-core already encodes the discriminated union (inline vs template + optional promptArgs), and compile-time mutual-exclusion tests already exist. There is no runtime resolver and no template-loading path.

Desired behavior:
A PromptResolver module that, given the prompt-related fields of any options type composing PromptOption, returns a discriminated-union tagged result:

• Inline path — tag indicates inline; result carries the verbatim string. No {{KEY}} scan, no shell-expression scan, no built-in prompt argument injection (per ADR-0008's "inline = literal").
• Template path — tag indicates template; result carries the file contents read from disk plus the user-supplied promptArgs map untouched. Prompt argument substitution and prompt expansion are explicitly out of scope for this slice — they consume the tag in later slices.

The resolver also enforces, at runtime:

• prompt and promptFile mutually exclusive (defense in depth on the existing compile-time guard).
• promptArgs combined with an inline prompt is an error (same rationale; matches ADR-0008).
• A missing promptFile raises an actionable error whose message names the resolved absolute path the resolver attempted to read.

Path resolution — read carefully:
promptFile resolves against process.cwd() (the caller's perspective), NOT against RunOptions.cwd (the run's working directory). This matches CONTEXT.md's "Path resolution follows two perspectives" rule. Note: runProgram already resolves options.cwd ?? process.cwd() and threads cwd everywhere — do not reuse that resolved value for promptFile. The two perspectives are deliberately different.

Key interfaces:

• PromptOption in @missingstudio/sanddune-core — already defines the input shape; do not change its public type.
• New module — per the project's module map, the concept is PromptResolver. Should live in core so every entry point that takes a PromptOption can share it (not just runProgram).
• The tagged result is the new public type. Suggested shape: discriminated union on kind: "inline" | "template". Inline carries text. Template carries text plus the untouched promptArgs map (built-in prompt argument injection happens during substitution, not here).

Integration point:
The current ad-hoc check at the top of runProgram (the typeof options.prompt !== "string" branch that throws "promptFile is not yet supported") is the seam. Replace it with a call to the resolver. Downstream — the iteration loop, the agent invoker, the agent provider — all currently take prompt: string and should keep doing so for this slice. The tag itself is consumed by future slices, not by this one.

Acceptance criteria:

• PromptResolver accepts the prompt-related fields of RunOptions (prompt, promptFile, promptArgs) and returns a discriminated-union result tagged by source.
• Inline prompt path returns the string verbatim — no scanning, no transformation.
• promptFile resolves relative paths against process.cwd(), not against RunOptions.cwd.
• Passing both prompt and promptFile throws at runtime (do NOT remove the type-level negative tests in packages/sanddune/src/types.test.ts).
• Passing prompt together with promptArgs throws at runtime.
• A missing promptFile throws an error whose message includes the resolved absolute path.
• runProgram calls the resolver in place of the current "promptFile is not yet supported" branch. The existing integration test for the inline path continues to pass.
• Unit tests cover: inline path returns string verbatim; template path returns file contents from a fixture; prompt + promptFile rejected; prompt + promptArgs rejected; missing promptFile error names the absolute path; relative promptFile resolved against process.cwd() even when RunOptions.cwd is set to a different directory.
• bun test and bun run typecheck pass.
• Changeset added under .changeset/ (patch, per CLAUDE.md).

Out of scope:

• Prompt argument substitution ({{KEY}} replacement) — later slice.
• Prompt expansion (!`command` shell expressions) — later slice.
• Built-in prompt arguments ({{SOURCE_BRANCH}}, {{TARGET_BRANCH}}) — injected during substitution, not resolution.
• Interactive missing-key prompting — only relevant once substitution lands.
• Wiring the resolver into interactive(), Sandbox.run(), Worktree.run(), createSandbox() — those entry points are still NotImplementedError stubs and will adopt the resolver as they get implemented.
• Modifying the existing PromptOption public type or the type-level negative tests in types.test.ts.