@miaws/miaw 1.18.3 → 1.18.5

package/src/cli/cmd/run/trace.ts

@@ -0,0 +1,94 @@
+// Dev-only JSONL event trace for direct interactive mode.
+//
+// Enable with MIAW_DIRECT_TRACE=1. Writes one JSON line per event to
+// ~/.local/share/miaw/log/direct/<timestamp>-<pid>.jsonl. Also writes
+// a latest.json pointer so you can quickly find the most recent trace.
+//
+// The trace captures the full closed loop: outbound prompts, inbound SDK
+// events, reducer output, footer commits, and turn lifecycle markers.
+// Useful for debugging stream ordering, permission behavior, and
+// footer/transcript mismatches.
+//
+// Lazy-initialized: the first call to trace() decides whether tracing is
+// active based on the env var, and subsequent calls return the cached result.
+import fs from "fs"
+import path from "path"
+import { Global } from "@miaw/core/global"
+
+export type Trace = {
+  write(type: string, data?: unknown): void
+}
+
+let state: Trace | false | undefined
+
+function stamp() {
+  return new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\.\d+Z$/, "Z")
+}
+
+function file() {
+  return path.join(Global.Path.log, "direct", `${stamp()}-${process.pid}.jsonl`)
+}
+
+function latest() {
+  return path.join(Global.Path.log, "direct", "latest.json")
+}
+
+function text(data: unknown) {
+  return JSON.stringify(
+    data,
+    (_key, value) => {
+      if (typeof value === "bigint") {
+        return String(value)
+      }
+
+      return value
+    },
+    0,
+  )
+}
+
+export function trace(): Trace | undefined {
+  if (state !== undefined) {
+    return state || undefined
+  }
+
+  if (!process.env.MIAW_DIRECT_TRACE) {
+    state = false
+    return undefined
+  }
+
+  const target = file()
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(
+    latest(),
+    text({
+      time: new Date().toISOString(),
+      pid: process.pid,
+      cwd: process.cwd(),
+      argv: process.argv.slice(2),
+      path: target,
+    }) + "\n",
+  )
+  state = {
+    write(type: string, data?: unknown) {
+      fs.appendFileSync(
+        target,
+        text({
+          time: new Date().toISOString(),
+          pid: process.pid,
+          type,
+          data,
+        }) + "\n",
+      )
+    },
+  }
+  state.write("trace.start", {
+    argv: process.argv.slice(2),
+    cwd: process.cwd(),
+    path: target,
+  })
+  return state
+}

package/src/cli/cmd/run/turn-summary.ts

@@ -0,0 +1,47 @@
+import * as Locale from "@/util/locale"
+import type { SessionMessages } from "./session.shared"
+import type { RunProvider, StreamCommit } from "./types"
+
+export function turnSummaryCommit(input: {
+  agent: string
+  model: string
+  duration: string
+  messageID?: string
+}): StreamCommit {
+  return {
+    kind: "system",
+    text: `▣ ${input.agent} · ${input.model} · ${input.duration}`,
+    phase: "final",
+    source: "system",
+    summary: {
+      agent: input.agent,
+      model: input.model,
+      duration: input.duration,
+    },
+    messageID: input.messageID,
+  }
+}
+
+export function messageTurnSummaryCommit(
+  message: SessionMessages[number],
+  providers?: RunProvider[],
+): StreamCommit | undefined {
+  const info = message.info
+  if (info.role !== "assistant") {
+    return
+  }
+
+  const completed = info.time.completed
+  if (typeof completed !== "number" || completed <= info.time.created) {
+    return
+  }
+
+  const model = providers?.find((item) => item.id === info.providerID)?.models[info.modelID]?.name
+
+  return turnSummaryCommit({
+    agent: Locale.titlecase(info.agent),
+    model: model ?? info.modelID,
+    duration: Locale.duration(completed - info.time.created),
+    messageID: info.id,
+  })
+}

package/src/cli/cmd/run/types.ts

@@ -0,0 +1,350 @@
+// Shared type vocabulary for the direct interactive mode (`run --interactive`).
+//
+// Direct mode uses a split-footer terminal layout: immutable scrollback for the
+// session transcript, and a mutable footer for prompt input, status, and
+// permission/question UI. Every module in run/* shares these types to stay
+// aligned on that two-lane model.
+//
+// Data flow through the system:
+//
+//   SDK events → session-data reducer → StreamCommit[] + FooterOutput
+//     → stream.ts bridges to footer API
+//       → footer.ts queues commits and patches the footer view
+//         → OpenTUI split-footer renderer writes to terminal
+import type { MiawClient, PermissionRequest, QuestionRequest, ToolPart } from "@miaw/sdk/v2"
+import type { TuiConfig } from "@miaw/tui/config"
+
+export type RunFilePart = {
+  type: "file"
+  url: string
+  filename: string
+  mime: string
+}
+
+type PromptModel = Parameters<MiawClient["session"]["prompt"]>[0]["model"]
+type PromptInput = Parameters<MiawClient["session"]["prompt"]>[0]
+
+export type RunPromptPart = NonNullable<PromptInput["parts"]>[number]
+
+export type RunCommand = NonNullable<Awaited<ReturnType<MiawClient["command"]["list"]>>["data"]>[number]
+
+export type RunProvider = NonNullable<Awaited<ReturnType<MiawClient["provider"]["list"]>>["data"]>["all"][number]
+
+export type RunPrompt = {
+  messageID?: string
+  partID?: string
+  text: string
+  parts: RunPromptPart[]
+  mode?: "shell"
+  command?: {
+    name: string
+    arguments: string
+  }
+}
+
+export type FooterQueuedPrompt = {
+  messageID: string
+  partID: string
+  prompt: RunPrompt
+}
+
+export type RunAgent = NonNullable<Awaited<ReturnType<MiawClient["app"]["agents"]>>["data"]>[number]
+
+type RunResourceMap = NonNullable<Awaited<ReturnType<MiawClient["experimental"]["resource"]["list"]>>["data"]>
+
+export type RunResource = RunResourceMap[string]
+
+export type RunInput = {
+  sdk: MiawClient
+  directory: string
+  sessionID: string
+  sessionTitle?: string
+  resume?: boolean
+  replay?: boolean
+  replayLimit?: number
+  agent: string | undefined
+  model: PromptModel | undefined
+  variant: string | undefined
+  files: RunFilePart[]
+  initialInput?: string
+  thinking: boolean
+  backgroundSubagents: boolean
+  demo?: boolean
+}
+
+// The semantic role of a scrollback entry. Maps 1:1 to theme colors.
+export type EntryKind = "system" | "user" | "assistant" | "reasoning" | "tool" | "error"
+
+// Whether the assistant is actively processing a turn.
+export type FooterPhase = "idle" | "running"
+
+// Full snapshot of footer status bar state. Every update replaces the whole
+// object in the SolidJS signal so the view re-renders atomically.
+export type FooterState = {
+  phase: FooterPhase
+  status: string
+  queue: number
+  model: string
+  duration: string
+  usage: string
+  first: boolean
+  interrupt: number
+  exit: number
+}
+
+// A partial update to FooterState. The footer merges this onto the current state.
+export type FooterPatch = Partial<FooterState>
+
+export type RunDiffStyle = "auto" | "stacked"
+
+export type TurnSummary = {
+  agent: string
+  model: string
+  duration: string
+}
+
+export type ScrollbackOptions = {
+  diffStyle?: RunDiffStyle
+  suppressBackgrounds?: boolean
+}
+
+export type ToolCodeSnapshot = {
+  kind: "code"
+  title: string
+  content: string
+  file?: string
+}
+
+export type ToolDiffSnapshot = {
+  kind: "diff"
+  items: Array<{
+    title: string
+    diff: string
+    file?: string
+    deletions?: number
+  }>
+}
+
+export type ToolTaskSnapshot = {
+  kind: "task"
+  title: string
+  rows: string[]
+  tail: string
+}
+
+export type ToolTodoSnapshot = {
+  kind: "todo"
+  items: Array<{
+    status: string
+    content: string
+  }>
+  tail: string
+}
+
+export type ToolQuestionSnapshot = {
+  kind: "question"
+  items: Array<{
+    question: string
+    answer: string
+  }>
+  tail: string
+}
+
+export type ToolSnapshot =
+  | ToolCodeSnapshot
+  | ToolDiffSnapshot
+  | ToolTaskSnapshot
+  | ToolTodoSnapshot
+  | ToolQuestionSnapshot
+
+export type EntryLayout = "inline" | "block"
+
+export type RunEntryBody =
+  | { type: "none" }
+  | { type: "text"; content: string }
+  | { type: "code"; content: string; filetype?: string }
+  | { type: "markdown"; content: string }
+  | { type: "structured"; snapshot: ToolSnapshot }
+
+// Which interactive surface the footer is showing. Only one view is active at
+// a time. The reducer drives transitions: when a permission arrives the view
+// switches to "permission", and when the permission resolves it falls back to
+// "prompt".
+export type FooterView =
+  | { type: "prompt" }
+  | { type: "permission"; request: PermissionRequest }
+  | { type: "question"; request: QuestionRequest }
+
+export type FooterPromptRoute =
+  | { type: "composer" }
+  | { type: "queued-menu" }
+  | { type: "subagent-menu" }
+  | { type: "subagent"; sessionID: string }
+  | { type: "command" }
+  | { type: "skill" }
+  | { type: "model" }
+  | { type: "variant" }
+
+export type FooterSubagentTab = {
+  sessionID: string
+  partID: string
+  callID: string
+  label: string
+  description: string
+  status: "running" | "completed" | "cancelled" | "error"
+  background?: boolean
+  title?: string
+  toolCalls?: number
+  lastUpdatedAt: number
+}
+
+export type FooterSubagentDetail = {
+  sessionID: string
+  commits: StreamCommit[]
+}
+
+export type FooterSubagentState = {
+  tabs: FooterSubagentTab[]
+  details: Record<string, FooterSubagentDetail>
+  permissions: PermissionRequest[]
+  questions: QuestionRequest[]
+}
+
+// The reducer emits this alongside scrollback commits so the footer can update in the same frame.
+export type FooterOutput = {
+  patch?: FooterPatch
+  view?: FooterView
+  subagent?: FooterSubagentState
+}
+
+// Typed messages sent to RunFooter.event(). The prompt queue and stream
+// transport both emit these to update footer state without reaching into
+// internal signals directly.
+export type FooterEvent =
+  | {
+      type: "catalog"
+      agents: RunAgent[]
+      resources: RunResource[]
+      commands?: RunCommand[]
+    }
+  | {
+      type: "models"
+      providers: RunProvider[]
+    }
+  | {
+      type: "variants"
+      variants: string[]
+      current: string | undefined
+    }
+  | {
+      type: "queue"
+      queue: number
+    }
+  | {
+      type: "queued.prompts"
+      prompts: FooterQueuedPrompt[]
+    }
+  | {
+      type: "first"
+      first: boolean
+    }
+  | {
+      type: "model"
+      model: string
+    }
+  | {
+      type: "turn.send"
+      queue: number
+    }
+  | {
+      type: "turn.wait"
+    }
+  | {
+      type: "turn.idle"
+      queue: number
+    }
+  | {
+      type: "turn.duration"
+      duration: string
+    }
+  | {
+      type: "stream.patch"
+      patch: FooterPatch
+    }
+  | {
+      type: "stream.view"
+      view: FooterView
+    }
+  | {
+      type: "stream.subagent"
+      state: FooterSubagentState
+    }
+
+export type PermissionReply = Parameters<MiawClient["permission"]["reply"]>[0]
+
+export type QuestionReply = Parameters<MiawClient["question"]["reply"]>[0]
+
+export type QuestionReject = Parameters<MiawClient["question"]["reject"]>[0]
+
+export type RunTuiConfig = Pick<TuiConfig.Resolved, "keybinds" | "leader_timeout" | "diff_style">
+
+// Lifecycle phase of a scrollback entry. "start" opens the entry, "progress"
+// appends content (coalesced in the footer queue), "final" closes it.
+export type StreamPhase = "start" | "progress" | "final"
+
+export type StreamSource = "assistant" | "reasoning" | "tool" | "system"
+
+export type StreamToolState = "running" | "completed" | "error"
+
+// A single append-only commit to scrollback. The session-data reducer produces
+// these from SDK events, and RunFooter.append() queues them for the next
+// microtask flush. Once flushed, they become immutable terminal scrollback
+// rows -- they cannot be rewritten.
+export type StreamCommit = {
+  kind: EntryKind
+  text: string
+  phase: StreamPhase
+  source: StreamSource
+  summary?: TurnSummary
+  messageID?: string
+  partID?: string
+  tool?: string
+  part?: ToolPart
+  interrupted?: boolean
+  toolState?: StreamToolState
+  toolError?: string
+  shell?: {
+    callID: string
+    command: string
+  }
+}
+
+export type LocalReplayAnchor = {
+  kind: EntryKind
+  text: string
+  phase: StreamPhase
+  messageID?: string
+  partID?: string
+  toolState?: StreamToolState
+  visible?: string
+}
+
+export type LocalReplayRow = {
+  commit: StreamCommit
+  after?: LocalReplayAnchor
+}
+
+// The public contract between the stream transport / prompt queue and
+// the footer. RunFooter implements this. The transport and queue never
+// touch the renderer directly -- they go through this interface.
+export type FooterApi = {
+  readonly isClosed: boolean
+  onPrompt(fn: (input: RunPrompt) => void): () => void
+  onQueuedRemove(fn: (messageID: string) => boolean | Promise<boolean>): () => void
+  onClose(fn: () => void): () => void
+  event(next: FooterEvent): void
+  append(commit: StreamCommit): void
+  idle(): Promise<void>
+  close(): void
+  destroy(): void
+}

package/src/cli/cmd/run/variant.shared.ts

@@ -0,0 +1,215 @@
+// Model variant resolution and persistence.
+//
+// Variants are provider-specific reasoning effort levels (e.g., "high", "max").
+// Resolution priority: CLI --variant flag > saved preference > session history.
+//
+// The saved variant persists across sessions in ~/.local/state/miaw/model.json
+// so your last-used variant sticks. Cycling (ctrl+t) updates both the active
+// variant and the persisted file.
+import path from "path"
+import { FSUtil } from "@miaw/core/fs-util"
+import { Context, Effect, Layer } from "effect"
+import { makeRuntime } from "@/effect/run-service"
+import { Global } from "@miaw/core/global"
+import { isRecord } from "@/util/record"
+import { createSession, sessionVariant, type RunSession, type SessionMessages } from "./session.shared"
+import type { RunInput, RunProvider } from "./types"
+
+const MODEL_FILE = path.join(Global.Path.state, "model.json")
+
+type ModelState = Record<string, unknown> & {
+  variant?: Record<string, string | undefined>
+}
+type VariantService = {
+  readonly resolveSavedVariant: (model: RunInput["model"]) => Effect.Effect<string | undefined>
+  readonly saveVariant: (model: RunInput["model"], variant: string | undefined) => Effect.Effect<void>
+}
+type VariantRuntime = {
+  resolveSavedVariant(model: RunInput["model"]): Promise<string | undefined>
+  saveVariant(model: RunInput["model"], variant: string | undefined): Promise<void>
+}
+
+class Service extends Context.Service<Service, VariantService>()("@miaw/RunVariant") {}
+
+function modelKey(provider: string, model: string): string {
+  return `${provider}/${model}`
+}
+
+function variantKey(model: NonNullable<RunInput["model"]>): string {
+  return modelKey(model.providerID, model.modelID)
+}
+
+export function modelInfo(providers: RunProvider[] | undefined, model: NonNullable<RunInput["model"]>) {
+  const provider = providers?.find((item) => item.id === model.providerID)
+  return {
+    provider: provider?.name ?? model.providerID,
+    model: provider?.models[model.modelID]?.name ?? model.modelID,
+  }
+}
+
+export function formatModelLabel(
+  model: NonNullable<RunInput["model"]>,
+  variant: string | undefined,
+  providers?: RunProvider[],
+): string {
+  const names = modelInfo(providers, model)
+  const label = variant ? ` · ${variant}` : ""
+  return `${names.model} · ${names.provider}${label}`
+}
+
+export function cycleVariant(current: string | undefined, variants: string[]): string | undefined {
+  if (variants.length === 0) {
+    return undefined
+  }
+
+  if (!current) {
+    return variants[0]
+  }
+
+  const idx = variants.indexOf(current)
+  if (idx === -1 || idx === variants.length - 1) {
+    return undefined
+  }
+
+  return variants[idx + 1]
+}
+
+export function pickVariant(model: RunInput["model"], input: RunSession | SessionMessages): string | undefined {
+  return sessionVariant(Array.isArray(input) ? createSession(input) : input, model)
+}
+
+function fitVariant(value: string | undefined, variants: string[]): string | undefined {
+  if (!value) {
+    return undefined
+  }
+
+  if (variants.length === 0 || variants.includes(value)) {
+    return value
+  }
+
+  return undefined
+}
+
+// Picks the active variant. CLI flag wins, then saved preference, then session
+// history. fitVariant() checks saved and session values against the available
+// variants list -- if the provider doesn't offer a variant, it drops.
+export function resolveVariant(
+  input: string | undefined,
+  session: string | undefined,
+  saved: string | undefined,
+  variants: string[],
+): string | undefined {
+  if (input !== undefined) {
+    return input
+  }
+
+  const fallback = fitVariant(saved, variants)
+  const current = fitVariant(session, variants)
+  if (current !== undefined) {
+    return current
+  }
+
+  return fallback
+}
+
+function state(value: unknown): ModelState {
+  if (!isRecord(value)) {
+    return {}
+  }
+
+  const variant = isRecord(value.variant)
+    ? Object.fromEntries(
+        Object.entries(value.variant).flatMap(([key, item]) => {
+          if (typeof item !== "string") {
+            return []
+          }
+
+          return [[key, item] as const]
+        }),
+      )
+    : undefined
+
+  return {
+    ...value,
+    variant,
+  }
+}
+
+function createLayer(fs = FSUtil.defaultLayer) {
+  return Layer.fresh(
+    Layer.effect(
+      Service,
+      Effect.gen(function* () {
+        const file = yield* FSUtil.Service
+
+        const read = Effect.fn("RunVariant.read")(function* () {
+          return yield* file.readJson(MODEL_FILE).pipe(
+            Effect.map(state),
+            Effect.catchCause(() => Effect.succeed(state(undefined))),
+          )
+        })
+
+        const resolveSavedVariant = Effect.fn("RunVariant.resolveSavedVariant")(function* (model: RunInput["model"]) {
+          if (!model) {
+            return undefined
+          }
+
+          return (yield* read()).variant?.[variantKey(model)]
+        })
+
+        const saveVariant = Effect.fn("RunVariant.saveVariant")(function* (
+          model: RunInput["model"],
+          variant: string | undefined,
+        ) {
+          if (!model) {
+            return
+          }
+
+          const current = yield* read()
+          const next = {
+            ...current.variant,
+          }
+          const key = variantKey(model)
+          if (variant) {
+            next[key] = variant
+          }
+
+          if (!variant) {
+            delete next[key]
+          }
+
+          yield* file
+            .writeJson(MODEL_FILE, {
+              ...current,
+              variant: next,
+            })
+            .pipe(Effect.orElseSucceed(() => undefined))
+        })
+
+        return Service.of({
+          resolveSavedVariant,
+          saveVariant,
+        })
+      }),
+    ).pipe(Layer.provide(fs)),
+  )
+}
+
+/** @internal Exported for testing. */
+export function createVariantRuntime(fs = FSUtil.defaultLayer): VariantRuntime {
+  const runtime = makeRuntime(Service, createLayer(fs))
+  return {
+    resolveSavedVariant: (model) => runtime.runPromise((svc) => svc.resolveSavedVariant(model)).catch(() => undefined),
+    saveVariant: (model, variant) => runtime.runPromise((svc) => svc.saveVariant(model, variant)).catch(() => {}),
+  }
+}
+
+const runtime = createVariantRuntime()
+
+export async function resolveSavedVariant(model: RunInput["model"]): Promise<string | undefined> {
+  return runtime.resolveSavedVariant(model)
+}
+
+export function saveVariant(model: RunInput["model"], variant: string | undefined): void {
+  void runtime.saveVariant(model, variant)
+}