Skip to content

feat(dream): add --prompt and --system reflection overrides#3313

Merged
carenthomas merged 1 commit into
mainfrom
feat/dream-prompt-system-overrides
Jul 13, 2026
Merged

feat(dream): add --prompt and --system reflection overrides#3313
carenthomas merged 1 commit into
mainfrom
feat/dream-prompt-system-overrides

Conversation

@carenthomas

Copy link
Copy Markdown
Collaborator

What

Two advanced override flags on letta dream, for callers (e.g. dreambench) that need to steer the reflection engine directly:

  • --prompt <text> — replace the reflection task prompt entirely. --instruction stays additive (folded into the default prompt, subordinated to "only persist durable memory"); --prompt is the full-replacement escape hatch. The caller owns the mechanics: the default prompt's $TRANSCRIPT_PATH (read the payload) and $MEMORY_DIR (write + commit) env vars are still injected by the harness, so an override must reference them.
  • --system <text> — replace the reflection subagent's system prompt / persona. Passed to the child as --system-custom <text> instead of the built-in --system <type>, so the default reflection.md persona (and its "durable memory, not transient task state" framing) is bypassed.

Omitting both preserves current behavior exactly.

Motivation

letta dream's reflection is doubly biased toward general durable memory: the reflection.md persona (system prompt) and the base task prompt's "only persist durable memory-worthy learnings, do not store transient task state" line. --instruction can't override that (it's inserted as a subordinated "focus" lens). For benchmarks/consumers that want task-specific distillation, these two flags provide full control without touching the default path.

How (threaded like #3306's --model)

dream.ts (--prompt/--system) → launchReflectionSubagent (reflectionPromptOverride / reflectionSystemPromptOverride) →

  • task prompt: prepareReflectionMemoryWorktreeLaunch uses reflectionPromptOverride ?? buildReflectionSubagentPrompt(...) (the builder is bypassed, incl. the parent-memory snapshot).
  • persona: spawnBackgroundSubagentTask({ systemPromptOverride })spawnSubagentexecuteSubagentbuildSubagentArgs, which emits --system-custom <text> instead of --system <type> for new agents.

buildReflectionSubagentPrompt is untouched. This PR lands cleanly now that manager.ts is under the 1,000-line ceiling (after #3308/#3310/#3312); it adds ~15 lines there (888 total, no baseline entry).

Notes / caveats

  • --prompt and --system have no short flags (avoids clashing with -m/-i/-h).
  • A --prompt override that forgets $TRANSCRIPT_PATH/$MEMORY_DIR will silently produce no memory — documented in the help text and a code comment (acceptable for the advanced/internal use case).
  • --system replaces reflection.md wholesale, so its built-in guardrails/output-format go with it — that's the point.

Test

  • bun run check — 12/12 pass.
  • bun test src/cli/subcommands/dream.test.ts — parse + help-text coverage for both flags.
  • bun test on the three subagent suites (model-resolution, env-composition, parent-id-propagation) — 84/84 pass (covers buildSubagentArgs).

Add two advanced flags to `letta dream`:
- --prompt <text>: replace the reflection task prompt entirely (the caller
  supplies the transcript/memory mechanics via $TRANSCRIPT_PATH/$MEMORY_DIR).
  --instruction stays additive; --prompt is a full-replacement escape hatch.
- --system <text>: replace the reflection subagent's system prompt/persona,
  passed to the child as --system-custom instead of the built-in --system <type>.

Threaded like #3306's --model: dream.ts -> launchReflectionSubagent
(reflectionPromptOverride/reflectionSystemPromptOverride) -> the task prompt
assembly (buildReflectionSubagentPrompt is bypassed when overridden) and the
subagent deploy boundary (spawnBackgroundSubagentTask -> spawnSubagent ->
executeSubagent -> buildSubagentArgs). Omitting both preserves current behavior.
@carenthomas
carenthomas merged commit 3cf5b4e into main Jul 13, 2026
38 of 40 checks passed
@carenthomas
carenthomas deleted the feat/dream-prompt-system-overrides branch July 13, 2026 18:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant