@duetso/agent 0.1.30 → 0.1.32

package/README.md

@@ -2,6 +2,23 @@
 
 An opinionated, full-stack agent turn runner. Native multimodal memory. Native interrupts. Multi-agent by default. Serverless-friendly: every turn rehydrates from on-disk state, so a session can pause for minutes or months and resume in a fresh sandbox.
 
+## Get started with one login
+
+```bash
+bun add --global @duetso/agent
+duet login
+duet "build a REST API with Express"
+```
+
+`duet login` opens your browser, signs you in, and writes a single `DUET_API_KEY` to `~/.duet/.env`. That one key unlocks:
+
+- **Frontier language models** — Claude Opus / Sonnet / Haiku, GPT-5, Gemini, and friends routed through the Duet AI Gateway. No separate Anthropic, OpenAI, or Google billing to set up.
+- **Image and video generation** — GPT Image 2, Seedance, and the other media models the gateway exposes.
+- **Web scraping and research** — Firecrawl-powered scraping, search, and browser automation come bundled as default skills.
+- **The latest Duet skills** — auto-synced into `~/.duet/skills` on first login and refreshed in the background on every subsequent run.
+
+One login, every frontier model, every default skill, kept fresh. If you would rather wire your own provider keys, see [CLI Env Setup](#cli-env-setup).
+
 ## Why another agent framework?
 
 Existing agent turn runners treat tools and memories as pluggable modules. This makes them flexible but fundamentally disconnected — memory is an afterthought.
@@ -198,14 +215,14 @@ The pre-commit hook runs `format`, `check-types`, and `lint`.
 
 ## CLI Quick Start
 
-The quickest way to get started is `duet login`, which signs in via your browser, writes `DUET_API_KEY` to `~/.duet/.env`, and syncs the default skills:
+The recommended path is `duet login`. One sign-in writes `DUET_API_KEY` to `~/.duet/.env`, syncs the default skills, and gives you access to every frontier language, image, and video model on the Duet AI Gateway plus the bundled web-scraping skills — no other API keys required.
 
 ```bash
 duet login
 duet "build a REST API with Express"
 ```
 
-If you would rather manage provider API keys yourself, use `duet env` (see [CLI Env Setup](#cli-env-setup) below) or set a provider API key in the environment, `<workdir>/.env`, or `~/.duet/.env`. When `--model` is omitted, the CLI infers a default from the configured provider: Anthropic, AI Gateway, and OpenRouter use Opus 4.7; OpenAI uses GPT-5.5.
+If you would rather manage provider API keys yourself, use `duet env` (see [CLI Env Setup](#cli-env-setup) below) or set a provider API key in the environment, `<workdir>/.env`, or `~/.duet/.env`. When `--model` is omitted, the CLI infers a default from the configured provider: Duet, Anthropic, AI Gateway, and OpenRouter use Opus 4.7; OpenAI uses GPT-5.5.
 
 ```bash
 export ANTHROPIC_API_KEY=sk-...
@@ -217,10 +234,10 @@ duet "build a REST API with Express"
 duet
 
 # With options
-duet -m anthropic:claude-opus-4-7 --workdir ./my-project "refactor the auth module"
+duet -m opus-4.7 --workdir ./my-project "refactor the auth module"
 
 # With a custom observational memory model
-duet --memory-model anthropic:claude-sonnet-4-6 "summarize this repo"
+duet --memory-model sonnet-4.6 "summarize this repo"
 
 # With additional system instructions
 duet --system-prompt "Prefer concise answers." "review this repo"
@@ -239,13 +256,20 @@ duet skills
 
 # Through Vercel AI Gateway
 export AI_GATEWAY_API_KEY=...
-duet -m vercel-ai-gateway:anthropic/claude-opus-4.7 "review this repo"
+duet -m opus-4.7 "review this repo"
 ```
 
+Model names can use full `provider:modelId` syntax or shorthand names such as
+`opus-4.7`, `sonnet-4.6`, `haiku-4.5`, and `gpt-5.5`. Shorthands resolve to the
+first configured supported provider; use full `provider:modelId` syntax to pin a
+specific provider.
+
 ### CLI Login
 
 `duet login` is the recommended setup path. It opens a browser to sign in, writes `DUET_API_KEY` for the selected org to `~/.duet/.env`, and syncs the latest default skills into `~/.duet/skills`.
 
+That single `DUET_API_KEY` is your access token to the Duet AI Gateway: frontier language models (Claude, GPT, Gemini), image generation (GPT Image 2), video generation (Seedance), and the Firecrawl-powered web scraping and search skills, all behind one key.
+
 Once you have synced default skills at least once, every subsequent `duet` invocation refreshes them in the background using a conditional GET against the saved hash. Logging in with `--skip-skill-sync` leaves no hash on disk, so this auto-refresh stays a no-op until you explicitly opt in by syncing once.
 
 ```bash
@@ -291,7 +315,7 @@ bun run cli -- "build a REST API with Express"
 import { TurnRunner } from "@duetso/agent";
 
 const turnRunner = new TurnRunner({
-  model: "anthropic:claude-opus-4-7",
+  model: "opus-4.7",
   cwd: process.cwd(),
   mode: "auto",
 });
@@ -306,28 +330,64 @@ const terminal = await turnRunner.turn({
 });
 ```
 
-`TurnRunner.turn()` is the concurrency boundary. Callers may call it repeatedly
-while work is active; the runner folds active `prompt` and `answer` commands
-back into the active pi agent as `steer` or `follow_up`, queues wakes and other
-work it cannot absorb immediately, and emits one terminal event when the whole
-active work chain is done. The parent runner transcript stays linear: state
-machine continuations, script results, poll results, and user follow-ups rejoin
-the parent agent rather than creating separate conversation branches.
+## TurnRunner Lifecycle
+
+`start()` prepares a session, but it does not run agent work. It hydrates durable memory, loads skills and agent files, connects MCP servers, creates or resumes `TurnState`, initializes the parent pi agent, and emits `turn_started`. After that, every `turn()` call accepts one command: `prompt`, `answer`, or `wake`.
+
+```mermaid
+flowchart TD
+  Start["start(command)"] --> Setup["hydrate memory\nload skills + agent files\nconnect MCP servers"]
+  Setup --> State["create or resume TurnState"]
+  State --> Parent["initialize parent pi agent"]
+  Parent --> Started["emit turn_started"]
+
+  Started --> Command["turn(prompt | answer | wake)"]
+  Command --> Active{"active turn\nalready running?"}
+  Active -- yes --> Fold["fold prompt/answer into parent agent\nor queue work behind active chain"]
+  Fold --> ActiveTerminal["return activeTurnPromise"]
+
+  Active -- no --> Chain["run turn chain"]
+  Chain --> Dispatch{"command type"}
+  Dispatch -- prompt/answer --> Mode{"state.mode"}
+  Dispatch -- wake --> Wake["resume scheduled poll/timer state"]
+
+  Mode -- agent --> ParentRun["run parent pi agent"]
+  Mode -- auto or explicit state machine --> Router["parent agent selects next state"]
+  Router --> StateRun["run agent, script, poll, timer,\nor terminal state"]
+  StateRun --> StateResult{"state result"}
+  StateResult -- completed --> Router
+  StateResult -- ask --> Terminal
+  StateResult -- sleep --> Terminal
+  StateResult -- terminal/interrupted --> Terminal
+  Wake --> StateRun
+
+  ParentRun --> Observe["observe transcript suffix\nreflect large observation logs\nflush durable memory"]
+  Router --> Observe
+  Observe --> Queue{"queued commands?"}
+  Queue -- yes --> Dispatch
+  Queue -- no --> Terminal["emit one terminal event\ncomplete | ask | sleep | interrupted"]
+  Terminal --> Snapshot["store latest TurnState in runner"]
+  Snapshot --> Next["caller persists snapshot\nand may call turn() again later"]
+```
+
+`TurnRunner.turn()` is the concurrency boundary. Callers may invoke it repeatedly while work is active; the runner folds active `prompt` and `answer` commands back into the active pi agent as `steer` or `follow_up`, queues wakes and work it cannot absorb immediately, and emits one terminal event when the whole active work chain is done.
+
+The parent runner transcript stays linear across the lifecycle. State-machine continuations, script results, poll results, and user follow-ups all rejoin the parent agent instead of creating separate conversation branches. Terminal events carry the next `TurnState`; callers that need process-level durability persist that snapshot and pass it back to a later `start({ state })`.
 
 ## Memory And Persistence
 
-`TurnRunner` owns memory at runtime. It holds a `MemoryStore` in process, hydrates durable observations from PGlite before the first turn, and subscribes to memory-store events to write future observation changes. Raw conversation messages stay in `TurnState.agent.messages`; memory persistence stores only derived observations/reflections.
+`TurnRunner` owns memory at runtime. It holds a `MemoryStore` in process, hydrates durable observations from PGlite before the first turn, and subscribes to memory-store events to write future observation changes. After each pi-agent run, the runner observes the latest unobserved transcript suffix, reflects oversized observation logs, emits memory events with generated observation payloads, and waits for durable writes before continuing. Raw conversation messages stay in `TurnState.agent.messages`; memory persistence stores only derived observations/reflections.
 
 ```typescript
 import { TurnRunner } from "@duetso/agent";
 
 const turnRunner = new TurnRunner({
-  model: "anthropic:claude-opus-4-7",
+  model: "opus-4.7",
   memoryDbPath: false, // Keep observational memory in process only.
 });
 ```
 
-By default, the CLI stores durable observations in `~/.duet/memory.db`; run it with `--no-memory` to keep observational memory in process only. Programmatic callers can pass `memoryDbPath: false` or provide a custom `memoryDbPath`. The CLI's `SessionManager` is a convenience layer that stores session snapshots under `~/.duet/sessions`, but the runner owns memory hydration, compaction, and observation persistence.
+By default, the CLI stores durable observations in `~/.duet/memory.db`; run it with `--no-memory` to keep observational memory in process only. Programmatic callers can pass `memoryDbPath: false` or provide a custom `memoryDbPath`. The CLI's `SessionManager` is a convenience layer that stores session snapshots under `~/.duet/sessions`, but the runner owns memory hydration, pi-turn observation/reflection, compaction, and observation persistence.
 
 You can also resume directly from saved state. The runner owns state
 internally after `start`, so resumed state is handed in through the start
@@ -347,9 +407,9 @@ Resume continues turn runner session state, not an in-flight model/tool call. An
 
 Observational memory is enabled by default with thresholds tuned for modern 200k-token model windows:
 
-- Raw messages are observed around `150_000` tokens so exact transcript context and prompt caching are used before compaction.
-- Observation logs are reflected around `90_000` tokens, targeting about `65_000` tokens after reflection.
-- Raw-tail retention keeps about `40_000` exact message tokens after observation activation.
+- Raw messages are observed after each pi-agent run; the `100_000` token threshold controls when old raw transcript context is replaced.
+- Observation logs are reflected around `60_000` tokens, targeting about `40_000` tokens after reflection.
+- Raw-tail retention keeps about `30_000` exact message tokens after context replacement activates.
 - Observation context is injected as reminder messages; replacing raw context with observations/reflections is the compaction path.
 
 ## Skills

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@duetso/agent",
-    "version": "0.1.30",
+    "version": "0.1.32",
     "description": "An opinionated full-stack agent turn runner with native memories, interrupts, and multi-agent orchestration",
     "keywords": [
         "agent",

package/dist/src/cli.d.ts

@@ -4,9 +4,11 @@
  *
  * Usage:
  *   duet "build a todo app in React"
- *   duet --model claude-opus-4-7 "refactor auth system"
+ *   duet --model opus-4.7 "refactor auth system"
  *   echo "fix the bug in server.ts" | duet
  */
+import { type ModelResolution } from "./model-resolution/resolver.js";
+import type { TurnRunnerConfig } from "./types/config.js";
 declare const PACKAGE_MANAGERS: readonly ["npm", "bun", "pnpm", "yarn"];
 type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 type PackageManagerDetectionContext = {
@@ -15,11 +17,30 @@ type PackageManagerDetectionContext = {
     cliFilePath?: string;
     scriptPath?: string;
 };
+export interface CliTurnConfigInput {
+    modelName?: string;
+    memoryModelName?: string;
+    disableDurableMemory?: boolean;
+    workDir: string;
+    systemInstructions?: string;
+    systemPromptFiles?: string[];
+}
+export interface CliTurnConfigResolution {
+    config: TurnRunnerConfig;
+    modelResolution: ModelResolution;
+    memoryModelResolution: ModelResolution;
+}
+export declare function buildCliTurnConfig(input: CliTurnConfigInput, dotenvKeys: Set<string>): CliTurnConfigResolution;
 export declare function resolveUserPath(path: string, baseDir?: string): string;
 export declare function defaultDuetEnvFilePath(): string;
 export declare function cliEnvFilePaths(workDir: string, envFilePath?: string): string[];
 export declare function loadCliEnvFiles(workDir: string, envFilePath?: string): Set<string>;
 export declare function parseResumeHistoryLines(value: string, optionName?: string): number;
+export declare function shouldUseTui(input: {
+    interactive: boolean;
+    jsonOutput: boolean;
+    prompt?: string;
+}): boolean;
 export declare function formatNewVersionNotice(packageName: string, currentVersion: string, latestVersion: string): string;
 export declare function compareSemverVersions(left: string, right: string): number;
 interface EnvCommandIO {

package/dist/src/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG;AA6BH,QAAA,MAAM,gBAAgB,yCAA0C,CAAC;AAUjE,KAAK,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,KAAK,8BAA8B,GAAG;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AA4bF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAgB,GAAG,MAAM,CAI7E;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/E;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CASlF;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,UAAU,SAA2B,GACpC,MAAM,CAKR;AAeD,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,MAAM,CAER;AAmBD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAWzE;AA0FD,UAAU,YAAY;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8DxF;AAED,UAAU,cAAc;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmD5F;AAqDD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAErE;AAqBD,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,8BAA8B,GACtC,cAAc,CAiBhB;AAED,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,EAAE,CAMV;AAiCD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IACL,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,GACA,MAAM,CAoCR"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.js

@@ -4,7 +4,7 @@
  *
  * Usage:
  *   duet "build a todo app in React"
- *   duet --model claude-opus-4-7 "refactor auth system"
+ *   duet --model opus-4.7 "refactor auth system"
  *   echo "fix the bug in server.ts" | duet
  */
 import { spawn } from "node:child_process";
@@ -16,11 +16,10 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import dotenv from "dotenv";
 import packageJson from "../package.json" with { type: "json" };
 import { shimDuetApiKeyToAiGateway } from "./model-resolution/duet-gateway.js";
-import { formatCompactJson } from "./lib/compact-json.js";
 import { resolveDuetAppBaseUrl } from "./lib/duet-app-url.js";
 import { loginWithBrowser } from "./lib/login.js";
 import { maybeAutoSyncDefaultSkills, syncDefaultSkills } from "./lib/sync-skills.js";
-import { describeModelResolution, resolveCliMemoryModel, resolveCliModel, } from "./model-resolution/index.js";
+import { describeModelResolution, resolveCliMemoryModel, resolveCliModel, } from "./model-resolution/resolver.js";
 import { SessionManager } from "./session/session-manager.js";
 import { discoverInstalledSkills, resolveSkillScope } from "./turn-runner/skills.js";
 import { runTui } from "./tui/app.js";
@@ -202,30 +201,23 @@ async function main() {
     if (process.env.DUET_API_KEY) {
         await maybeAutoSyncDefaultSkills({ apiKey: process.env.DUET_API_KEY });
     }
-    const modelResolution = resolveCliModel(modelName, dotenvKeys);
+    const { config, modelResolution, memoryModelResolution } = buildCliTurnConfig({
+        modelName,
+        memoryModelName,
+        disableDurableMemory,
+        workDir,
+        systemInstructions,
+        systemPromptFiles,
+    }, dotenvKeys);
     modelName = modelResolution.modelName;
-    const memoryModelResolution = resolveCliMemoryModel(memoryModelName, dotenvKeys);
     memoryModelName = memoryModelResolution.modelName;
-    if (modelName && modelName.indexOf(":") <= 0) {
-        throw new Error("Models must use provider:modelId syntax");
-    }
-    if (memoryModelName && memoryModelName.indexOf(":") <= 0) {
-        throw new Error("Memory model must use provider:modelId syntax");
-    }
-    // Build config
-    const config = {
-        ...(modelName ? { model: modelName } : {}),
-        ...(memoryModelName ? { memoryModel: memoryModelName } : {}),
-        ...(disableDurableMemory ? { memoryDbPath: false } : {}),
-        cwd: workDir,
-        ...(systemInstructions ? { systemInstructions } : {}),
-        ...(systemPromptFiles ? { systemPromptFiles } : {}),
-    };
-    // The TUI owns rendering when active, so we suppress stdout step printing
-    // there to avoid corrupting the alternate-screen UI.
-    const useTui = interactive && !jsonOutput;
+    // The CLI has exactly two rendering modes: the interactive TUI, or JSONL
+    // events. Supplying a prompt selects JSONL so one-shot runs have a stable
+    // machine-readable contract by default.
+    const useTui = shouldUseTui({ interactive, jsonOutput, prompt });
+    const useJson = !useTui;
     const newVersionNotice = await getNewVersionNotice();
-    if (!useTui) {
+    if (useJson) {
         if (newVersionNotice)
             process.stderr.write(`${newVersionNotice}\n`);
         process.stderr.write(`Model: ${modelName}\n`);
@@ -234,81 +226,18 @@ async function main() {
         process.stderr.write(`Memory source: ${describeModelResolution(memoryModelResolution)}\n`);
     }
     const manager = new SessionManager(config);
-    let streamedTextThisTurn = false;
-    let activeTextDelta = false;
-    let activeTextDeltaNeedsNewline = false;
-    let activeReasoningDelta = false;
-    let activeReasoningDeltaNeedsNewline = false;
-    const finishActiveDeltaStreams = () => {
-        if (activeTextDelta) {
-            if (activeTextDeltaNeedsNewline)
-                process.stdout.write("\n");
-            activeTextDelta = false;
-            activeTextDeltaNeedsNewline = false;
-        }
-        if (activeReasoningDelta) {
-            if (activeReasoningDeltaNeedsNewline)
-                process.stderr.write("\n");
-            process.stderr.write("[/reasoning]\n");
-            activeReasoningDelta = false;
-            activeReasoningDeltaNeedsNewline = false;
-        }
-    };
     manager.subscribe(({ event }) => {
-        if (jsonOutput) {
+        if (useJson) {
             process.stdout.write(`${JSON.stringify(event)}\n`);
         }
-        else if (event.type === "step" && !useTui) {
-            if (event.step.type === "text_delta") {
-                streamedTextThisTurn = true;
-                activeTextDelta = true;
-                activeTextDeltaNeedsNewline = !event.step.delta.endsWith("\n");
-                process.stdout.write(event.step.delta);
-            }
-            else if (event.step.type === "reasoning_delta") {
-                if (!activeReasoningDelta)
-                    process.stderr.write("\n[reasoning]\n");
-                activeReasoningDelta = true;
-                activeReasoningDeltaNeedsNewline = !event.step.delta.endsWith("\n");
-                process.stderr.write(event.step.delta);
-            }
-            else if (event.step.type === "text") {
-                streamedTextThisTurn = true;
-                if (activeTextDelta) {
-                    finishActiveDeltaStreams();
-                }
-                else {
-                    handleStep(event.step);
-                }
-            }
-            else if (event.step.type === "reasoning" && activeReasoningDelta) {
-                finishActiveDeltaStreams();
-            }
-            else {
-                handleStep(event.step);
-            }
-        }
-        else if (event.type === "step" &&
-            (event.step.type === "text" || event.step.type === "text_delta")) {
-            // Track streaming even when the TUI is rendering, so post-TUI fallback
-            // result handling stays consistent.
-            streamedTextThisTurn = true;
-        }
-        else if (!jsonOutput && !useTui && isTerminalEvent(event)) {
-            finishActiveDeltaStreams();
-        }
     });
     try {
         const session = resumeSessionId
             ? manager.resume(resumeSessionId)
             : manager.create({
                 ...(config.mode ? { mode: config.mode } : {}),
-                // Defer the prompt for TUI sessions so the user sees the prompt
-                // streamed inside the UI rather than during the pre-TUI phase.
                 ...(useTui || !prompt ? {} : { prompt }),
             });
-        let terminal;
-        let initialTuiPrompt;
         let resumedHistory;
         if (resumeSessionId) {
             // Force-load the persisted state.json so setup hands the resumed
@@ -323,35 +252,15 @@ async function main() {
             resumedHistory = session.getState()?.agent.messages;
         }
         if (prompt && resumeSessionId) {
-            streamedTextThisTurn = false;
-            if (useTui) {
-                initialTuiPrompt = prompt;
-            }
-            else {
-                await session.prompt({ message: prompt });
-                terminal = await session.waitForTerminal();
-                handleTerminal(terminal, {
-                    suppressHumanOutput: jsonOutput,
-                    suppressResult: streamedTextThisTurn,
-                });
-            }
+            await session.prompt({ message: prompt });
+            await session.waitForTerminal();
         }
         else if (prompt && !resumeSessionId) {
-            if (useTui) {
-                initialTuiPrompt = prompt;
-            }
-            else {
-                terminal = await session.waitForTerminal();
-                handleTerminal(terminal, {
-                    suppressHumanOutput: jsonOutput,
-                    suppressResult: streamedTextThisTurn,
-                });
-            }
+            await session.waitForTerminal();
         }
         if (useTui) {
-            terminal = await runTui({
+            await runTui({
                 session,
-                ...(initialTuiPrompt ? { initialPrompt: initialTuiPrompt } : {}),
                 ...(resumedHistory ? { history: resumedHistory } : {}),
                 resumeHistoryLines,
                 modelName,
@@ -383,91 +292,26 @@ async function main() {
         await manager.dispose();
     }
 }
-function handleTerminal(terminal, options = {}) {
-    if (options.suppressHumanOutput)
-        return;
-    if (terminal.type === "complete" && terminal.error) {
-        throw new Error(terminal.error);
-    }
-    if (terminal.type === "complete" && terminal.result && !options.suppressResult) {
-        process.stdout.write(`${terminal.result}\n`);
-    }
-    if (terminal.type === "ask") {
-        for (const question of terminal.questions) {
-            process.stdout.write(`${question.question}\n`);
-        }
-    }
-    if (terminal.type === "interrupted") {
-        process.stderr.write("Interrupted.\n");
-    }
-    if (terminal.type === "sleep") {
-        process.stderr.write(`Sleeping until ${new Date(terminal.wakeAt).toISOString()}.\n`);
-    }
-    if (terminal.usage) {
-        process.stderr.write(`${formatUsage(terminal.usage)}\n`);
-    }
-}
-function isTerminalEvent(event) {
-    return (event.type === "complete" ||
-        event.type === "ask" ||
-        event.type === "interrupted" ||
-        event.type === "sleep");
-}
-function formatUsage(usage) {
-    const parts = [`in=${usage.input}`, `out=${usage.output}`];
-    if (usage.cacheRead > 0)
-        parts.push(`cached=${usage.cacheRead}`);
-    let line = `Tokens: ${parts.join(" ")}`;
-    if (usage.cost.total > 0)
-        line += ` \u00b7 Cost: $${usage.cost.total.toFixed(4)}`;
-    return line;
-}
-function handleStep(step) {
-    if (step.type === "text_delta") {
-        process.stdout.write(step.delta);
-    }
-    if (step.type === "reasoning_delta") {
-        process.stderr.write(step.delta);
-    }
-    if (step.type === "text") {
-        process.stdout.write(`${step.text}\n`);
-    }
-    if (step.type === "reasoning") {
-        process.stderr.write(formatReasoning(step.text));
-    }
-    if (step.type === "tool_call") {
-        process.stderr.write(formatToolCall(step));
-    }
-    if (step.type === "system") {
-        process.stderr.write(`${step.message}\n`);
-    }
-}
-function formatReasoning(text) {
-    const trimmed = text.trim();
-    if (!trimmed)
-        return "";
-    return `\n[reasoning]\n${trimmed}\n[/reasoning]\n`;
-}
-function formatToolCall(step) {
-    const status = step.status ? ` ${step.status}` : "";
-    const input = step.input === undefined ? "" : `\n${formatCompactJson(step.input)}`;
-    let output = "";
-    if (step.output && step.output.length > 0) {
-        const text = step.output
-            .filter((b) => b.type === "text")
-            .map((b) => b.text)
-            .join("\n");
-        if (text) {
-            const label = step.status === "error" ? "output error" : "output";
-            output = `\n[${label}]\n${text}\n[/output]\n`;
-        }
-    }
-    return `\n[tool ${step.toolName}${status}]${input}${output}\n[/tool]\n`;
-}
 function fail(message) {
     console.error(`Fatal: ${message}`);
     process.exit(1);
 }
+export function buildCliTurnConfig(input, dotenvKeys) {
+    const modelResolution = resolveCliModel(input.modelName, dotenvKeys);
+    const memoryModelResolution = resolveCliMemoryModel(input.memoryModelName, dotenvKeys);
+    return {
+        config: {
+            model: modelResolution.modelName,
+            memoryModel: memoryModelResolution.modelName,
+            ...(input.disableDurableMemory ? { memoryDbPath: false } : {}),
+            cwd: input.workDir,
+            ...(input.systemInstructions ? { systemInstructions: input.systemInstructions } : {}),
+            ...(input.systemPromptFiles ? { systemPromptFiles: input.systemPromptFiles } : {}),
+        },
+        modelResolution,
+        memoryModelResolution,
+    };
+}
 export function resolveUserPath(path, baseDir = process.cwd()) {
     if (path === "~")
         return homedir();
@@ -500,6 +344,9 @@ export function parseResumeHistoryLines(value, optionName = "--resume-history-li
     }
     return Number(value);
 }
+export function shouldUseTui(input) {
+    return input.interactive && !input.jsonOutput && !input.prompt;
+}
 async function getNewVersionNotice() {
     try {
         const latestVersion = await fetchLatestPackageVersion(PACKAGE_METADATA.name);
@@ -952,7 +799,7 @@ OPTIONS
                             Load a file into the system prompt; repeatable
   --no-system-prompt-files Disable default AGENTS.md system prompt loading
   --env-file <path>        Shared env file to load after <workdir>/.env (default: ${DEFAULT_DUET_ENV_FILE})
-  --json                    Print streamed events as JSON lines
+  --json                    Force JSONL event output instead of the TUI
   -v, --version            Print the installed duet version and exit
   -h, --help               Show this help
 
@@ -961,7 +808,9 @@ INTERACTIVE
   Type /exit or /quit to end the conversation.
 
 MODELS
-  Use provider:modelId syntax, e.g. anthropic:claude-opus-4-7.
+  Prefer shorthands like opus-4.7, sonnet-4.6, haiku-4.5, and gpt-5.5.
+  They map to the first configured provider that supports that model.
+  Full provider:modelId syntax is also supported, e.g. anthropic:claude-opus-4-7.
   If omitted, duet infers a default from ANTHROPIC_API_KEY,
   DUET_API_KEY, AI_GATEWAY_API_KEY, OPENROUTER_API_KEY, or
   OPENAI_API_KEY after loading <workdir>/.env and the shared duet env file.
@@ -973,10 +822,9 @@ MODELS
 
 EXAMPLES
   duet "build a REST API with Express and TypeScript"
-  duet -m openai:gpt-5.5 "analyze the performance of our test suite"
-  duet --memory-model anthropic:claude-sonnet-4-6 "summarize this repo"
-  duet -m vercel-ai-gateway:anthropic/claude-opus-4.7 "refactor the auth module"
-  duet -m duet-gateway:anthropic/claude-opus-4.7 "review this repo"
+  duet -m gpt-5.5 "analyze the performance of our test suite"
+  duet --memory-model sonnet-4.6 "summarize this repo"
+  duet -m opus-4.7 "refactor the auth module"
   duet --system-prompt "Prefer concise answers." "review this repo"
   duet --system-prompt-file TEAM.md "review this repo"
   duet --env-file ~/.config/duet/env "review this repo"