@ddtcorex/dsh-maestro-memory 1.0.1

package/src/host/prompt/snapshot.ts

@@ -0,0 +1,95 @@
+import { Buffer } from 'node:buffer'
+import type { MaestroMemoryStore } from '../memory/store.ts'
+import { entryHeadPrefix, parseEntrySummary } from '../storage/legacy-format.ts'
+
+export interface SnapshotContext {
+  cwd: string | null
+  branch?: string
+  sessionId?: string
+  sessionName?: string
+}
+
+/** Default per-section byte budgets for the snapshot prompt. */
+export const SNAPSHOT_SECTION_CAPS = { memory: 2048, user: 4096, key: 6144 } as const
+
+export type SnapshotSectionKey = keyof typeof SNAPSHOT_SECTION_CAPS
+
+export interface SnapshotRenderOpts {
+  /** Partial override of {@link SNAPSHOT_SECTION_CAPS}; unspecified sections keep defaults. */
+  caps?: Partial<Record<SnapshotSectionKey, number>>
+}
+
+const SECTION_SEP = '\n---\n'
+
+/** Compact an oversize entry to `head + [summary:…]` when it carries a summary tag; otherwise keep whole. */
+function compactToHead(entry: string): string {
+  const summary = parseEntrySummary(entry)
+  if (summary === null) return entry
+  return `${entryHeadPrefix(entry)}[summary:${summary}]`
+}
+
+/**
+ * Keep the newest entries whose combined UTF-8 size (with separators) fits `cap`.
+ * The newest entry is always kept — compacted to its summary head when oversized
+ * and tagged; untagged oversize entries stay whole rather than vanishing.
+ */
+function fitSection(entries: string[], cap: number): string[] {
+  if (entries.length === 0) return []
+  const keptDesc: string[] = []
+  let used = 0
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const isNewest = keptDesc.length === 0
+    let candidate = entries[i]
+    if (isNewest && Buffer.byteLength(candidate, 'utf8') > cap) candidate = compactToHead(candidate)
+    const cost = Buffer.byteLength(candidate, 'utf8') + (keptDesc.length ? SECTION_SEP.length : 0)
+    if (!isNewest && used + cost > cap) break
+    keptDesc.push(candidate)
+    used += cost
+  }
+  return keptDesc.reverse()
+}
+
+/**
+ * Bounded snapshot renderer — contract từ README § System Prompt Snapshot:
+ * Header (sessionId/sessionName) + USER + global MEMORY + current-project KEY
+ * (branch-filtered) + end-of-turn discipline note.
+ * daily và project KHÔNG inject.
+ */
+export function renderSnapshot(
+  store: MaestroMemoryStore,
+  ctx: SnapshotContext,
+  opts: SnapshotRenderOpts = {},
+): string {
+  const caps = { ...SNAPSHOT_SECTION_CAPS, ...opts.caps }
+  const parts: string[] = []
+
+  // Header
+  if (ctx.sessionId || ctx.sessionName) {
+    const header = [
+      ctx.sessionId ? `sessionId: ${ctx.sessionId}` : null,
+      ctx.sessionName ? `sessionName: ${ctx.sessionName}` : null,
+    ].filter(Boolean).join(' | ')
+    if (header) parts.push(`# Session\n${header}`)
+  }
+
+  // Bounded memory sections — delegate branch filtering to store.list, then enforce byte caps
+  const mem = fitSection(store.list('memory'), caps.memory)
+  const user = fitSection(store.list('user'), caps.user)
+  const key = ctx.cwd
+    ? fitSection(store.list('key', ctx.cwd, ctx.branch ? { branch: ctx.branch } : {}), caps.key)
+    : []
+
+  if (mem.length) parts.push(`# Global Memory\n${mem.join('\n---\n')}`)
+  if (user.length) parts.push(`# User Memory\n${user.join('\n---\n')}`)
+  if (key.length) parts.push(`# Project Key Memory\n${key.join('\n---\n')}`)
+
+  // End-of-turn discipline note — verbatim contract (hardened: exactly once, always last)
+  const discipline =
+    `---\nEnd of every turn you must: 1. Write daily+project via memory entries (daily+project in one call) 2. Check dtodo list (bounded, max 8)`
+  // Defensive: strip any pre-existing discipline entry (should never occur — parts is fresh per call)
+  // then append exactly once so the note is guaranteed last even for empty stores or repeated calls.
+  const deduped = parts.filter((p) => p !== discipline)
+  deduped.push(discipline)
+
+  return deduped.join('\n\n')
+}

package/src/host/review/queue.ts

@@ -0,0 +1,325 @@
+/**
+ * review/queue.ts — SuggestionQueue for M2-PR-B confirmation queue
+ * Durable JSONL queue SUGGESTIONS.jsonl, gated memory_suggest and explicit RPC decisions.
+ * Handles append/dedupe/edited approval/reject/archive/malformed JSONL/recovery.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { withLockSync } from '../storage/atomic-store.ts'
+import { resolveMemoryRoot, suggestionsPath } from '../storage/layout.ts'
+
+export interface SuggestionEntry {
+  time: string
+  target: string
+  content: string
+  reason: string
+  cwd?: string | null
+  sessionId?: string | null
+  hits?: number
+  firstSeen?: string
+  lastSeen?: string
+}
+
+function nowIso(): string {
+  return new Date().toISOString()
+}
+
+export function normalizeWhitespace(text: string): string {
+  return String(text ?? '').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * SuggestionQueue — durable JSONL queue with malformed recovery and dedupe.
+ */
+export class SuggestionQueue {
+  constructor(private readonly file: string) {}
+
+  static fromRoot(memoryDir: string | null, file?: string): SuggestionQueue {
+    const root = resolveMemoryRoot(memoryDir)
+    return new SuggestionQueue(file ?? suggestionsPath(root))
+  }
+
+  /** Read all suggestions; missing file -> [], malformed lines skipped. */
+  read(): SuggestionEntry[] {
+    try {
+      const text = readFileSync(this.file, 'utf8')
+      const lines = text.split('\n').filter((l) => l.trim().length > 0)
+      const out: SuggestionEntry[] = []
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line)
+          if (obj && typeof obj.target === 'string' && typeof obj.content === 'string') {
+            out.push(obj as SuggestionEntry)
+          }
+        } catch {
+          // skip malformed line (recovery: not crashing, next write cleans)
+          continue
+        }
+      }
+      return out
+    } catch (e: any) {
+      if (e?.code === 'ENOENT') return []
+      throw e
+    }
+  }
+
+  /** Atomically write full list (same-directory lock, temp+rename). */
+  write(entries: SuggestionEntry[]): void {
+    const dir = dirname(this.file)
+    mkdirSync(dir, { recursive: true })
+    withLockSync(dir, () => {
+      const tmp = join(dir, `.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`)
+      const content = entries.map((e) => JSON.stringify(e)).join('\n') + (entries.length > 0 ? '\n' : '')
+      writeFileSync(tmp, content, 'utf8')
+      renameSync(tmp, this.file)
+    })
+  }
+
+  /** Append one suggestion with dedupe (same target+normalized content bumps hits). */
+  append(entry: SuggestionEntry): { ok: true; queued: number; deduped?: boolean; hits?: number } {
+    const dir = dirname(this.file)
+    mkdirSync(dir, { recursive: true })
+    return withLockSync(dir, () => {
+      const entries = this.readUnsafe()
+      const normalized = normalizeWhitespace(entry.content)
+      const existing = entries.find(
+        (e) => e.target === entry.target && normalizeWhitespace(e.content) === normalized,
+      )
+      if (existing) {
+        existing.hits = (existing.hits ?? 1) + 1
+        existing.lastSeen = nowIso()
+        if (entry.reason) existing.reason = entry.reason
+        this.writeUnsafe(entries)
+        return { ok: true as const, queued: entries.length, deduped: true, hits: existing.hits }
+      }
+      const toPush: SuggestionEntry = {
+        time: entry.time ?? nowIso(),
+        target: entry.target,
+        content: entry.content,
+        reason: entry.reason,
+        cwd: entry.cwd ?? null,
+        sessionId: entry.sessionId ?? null,
+        hits: 1,
+        firstSeen: nowIso(),
+        lastSeen: nowIso(),
+      }
+      entries.push(toPush)
+      this.writeUnsafe(entries)
+      return { ok: true as const, queued: entries.length }
+    })
+  }
+
+  /** Mutate under lock; fn may edit entries in place. Writes back after fn. */
+  mutate<T>(fn: (entries: SuggestionEntry[]) => T): T {
+    const dir = dirname(this.file)
+    mkdirSync(dir, { recursive: true })
+    return withLockSync(dir, () => {
+      const entries = this.readUnsafe()
+      const result = fn(entries)
+      this.writeUnsafe(entries)
+      return result
+    })
+  }
+
+  /** Alias for read */
+  list(): SuggestionEntry[] {
+    return this.read()
+  }
+
+  // internal read without lock (caller holds lock)
+  private readUnsafe(): SuggestionEntry[] {
+    try {
+      const text = readFileSync(this.file, 'utf8')
+      const lines = text.split('\n').filter((l) => l.trim().length > 0)
+      const out: SuggestionEntry[] = []
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line)
+          if (obj && typeof obj.target === 'string' && typeof obj.content === 'string') out.push(obj as SuggestionEntry)
+        } catch {
+          continue
+        }
+      }
+      return out
+    } catch (e: any) {
+      if (e?.code === 'ENOENT') return []
+      throw e
+    }
+  }
+
+  private writeUnsafe(entries: SuggestionEntry[]): void {
+    const dir = dirname(this.file)
+    mkdirSync(dir, { recursive: true })
+    const tmp = join(dir, `.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`)
+    const content = entries.map((e) => JSON.stringify(e)).join('\n') + (entries.length > 0 ? '\n' : '')
+    writeFileSync(tmp, content, 'utf8')
+    renameSync(tmp, this.file)
+  }
+}
+
+/** Enqueue helper with dedupe, used by memory_suggest tool */
+export function enqueueSuggestion(
+  queue: SuggestionQueue,
+  target: string,
+  content: string,
+  reason: string,
+  agent?: { id?: string; session?: { header?: { cwd?: string | null } } },
+): { ok: boolean; message?: string; queued: number; hits?: number } {
+  const normalized = normalizeWhitespace(content)
+  if (!normalized) return { ok: false, message: 'empty content', queued: queue.read().length }
+  if (!reason?.trim()) return { ok: false, message: 'empty reason', queued: queue.read().length }
+  const res = queue.mutate((entries) => {
+    const existing = entries.find(
+      (e) => e.target === target && normalizeWhitespace(e.content) === normalized,
+    )
+    if (existing) {
+      existing.hits = (existing.hits ?? 1) + 1
+      existing.lastSeen = nowIso()
+      if (reason) existing.reason = reason
+      return { deduped: true, hits: existing.hits, queued: entries.length }
+    }
+    entries.push({
+      time: nowIso(),
+      sessionId: agent?.id ?? null,
+      cwd: (agent?.session?.header?.cwd as string) ?? null,
+      target,
+      content,
+      reason,
+      hits: 1,
+      firstSeen: nowIso(),
+      lastSeen: nowIso(),
+    })
+    return { deduped: false, queued: entries.length }
+  })
+  if ((res as any).deduped) {
+    return { ok: true, message: `deduped (hits=${(res as any).hits})`, queued: (res as any).queued, hits: (res as any).hits }
+  }
+  return { ok: true, queued: (res as any).queued }
+}
+
+/** Approve suggestions by 1-based indices, supports edited content and target override */
+export function approveSuggestions(
+  store: any,
+  todoStore: any,
+  queue: SuggestionQueue,
+  indices: number[],
+  agent?: any,
+  edits?: Map<number, string>,
+  targets?: Map<number, string>,
+  options: { isTodoEnabled?: () => boolean } = {},
+): { lines: string[]; remaining: number } {
+  const isTodoEnabled = options.isTodoEnabled ?? (() => true)
+  return queue.mutate((entries) => {
+    const kept: SuggestionEntry[] = []
+    const lines: string[] = []
+    entries.forEach((entry, idx) => {
+      const number = idx + 1
+      if (!indices.includes(number)) {
+        kept.push(entry)
+        return
+      }
+      const isTodo = entry.target.startsWith('todo-')
+      const target = isTodo ? entry.target : (targets?.get(number) ?? entry.target)
+      const edited = edits?.get(number)?.trim()
+      const content = edited ? edited : entry.content
+      if (!content?.trim()) {
+        lines.push(`✗ #${number} [${target}] empty content, kept`)
+        kept.push(entry)
+        return
+      }
+      if (isTodo && !isTodoEnabled()) {
+        lines.push(`✗ #${number} [${target}] TODO_DISABLED: Todo feature is not enabled`)
+        kept.push(entry)
+        return
+      }
+      let outcome: any
+      if (isTodo) {
+        // todoStore may be minimal; try addTodo or add
+        if (todoStore?.addTodo) outcome = todoStore.addTodo(target.slice(5), content, {}, entry.cwd ?? agent?.session?.header?.cwd)
+        else if (todoStore?.add) outcome = todoStore.add(target.slice(5), { content }, entry.cwd ?? agent?.session?.header?.cwd)
+        else outcome = { ok: false, message: 'todo store not available' }
+      } else {
+        const cwdForStore = (entry.cwd as string) ?? agent?.session?.header?.cwd ?? null
+        try {
+          if (store?.add) outcome = store.add(target, content, cwdForStore)
+          else outcome = { ok: false, message: 'store not available' }
+        } catch (e: any) {
+          outcome = { ok: false, message: e?.message ?? String(e) }
+        }
+      }
+      if (outcome?.duplicate === true) {
+        lines.push(`#${number} [${target}] duplicate skipped`)
+      } else if (outcome?.ok) {
+        lines.push(`#${number} [${target}] approved`)
+      } else {
+        lines.push(`✗ #${number} [${target}] ${outcome?.message ?? outcome?.error ?? 'failed'}`)
+        kept.push(entry)
+      }
+    })
+    entries.length = 0
+    entries.push(...kept)
+    return { lines, remaining: kept.length }
+  })
+}
+
+export function rejectSuggestions(queue: SuggestionQueue, indices: number[]): { removed: number; remaining: number } {
+  return queue.mutate((entries) => {
+    const kept: SuggestionEntry[] = []
+    let removed = 0
+    entries.forEach((entry, idx) => {
+      if (indices.includes(idx + 1)) removed += 1
+      else kept.push(entry)
+    })
+    entries.length = 0
+    entries.push(...kept)
+    return { removed, remaining: kept.length }
+  })
+}
+
+export function archiveSuggestions(
+  archive: any,
+  queue: SuggestionQueue,
+  indices: number[],
+): { lines: string[]; remaining: number } {
+  return queue.mutate((entries) => {
+    const kept: SuggestionEntry[] = []
+    const lines: string[] = []
+    entries.forEach((entry, idx) => {
+      const number = idx + 1
+      if (!indices.includes(number)) {
+        kept.push(entry)
+        return
+      }
+      const originTag = entry.target.startsWith('todo-') ? `\n(original track: ${entry.target})` : ''
+      const stamp = new Date().toISOString().slice(0, 10)
+      const stamped = `[${stamp}] ${entry.content}${originTag}${entry.reason ? `\n(archive reason: ${entry.reason})` : ''}`
+      // archive may be MaestroMemoryStore or ArchiveStore
+      let outcome: any
+      try {
+        if (archive?.append) {
+          // ArchiveStore path: needs cwd for key
+          if (entry.target === 'key' || entry.target.startsWith('todo-')) outcome = archive.append(entry.target, stamped, entry.cwd ?? undefined)
+          else outcome = archive.append(entry.target, stamped)
+        } else if (archive?.archive) {
+          outcome = archive.archive(entry.target, entry.content, entry.cwd)
+        } else {
+          outcome = { ok: false, message: 'archive not available' }
+        }
+      } catch (e: any) {
+        outcome = { ok: false, message: e?.message ?? String(e) }
+      }
+      // MaestroMemoryStore archive via atomic store uses raw string; treat any truthy ok
+      const ok = outcome?.ok === true || outcome === undefined
+      if (ok) {
+        lines.push(`#${number} [${entry.target}] archived`)
+      } else {
+        lines.push(`✗ #${number} [${entry.target}] ${outcome?.message ?? outcome?.error ?? 'archive failed'}`)
+        kept.push(entry)
+      }
+    })
+    entries.length = 0
+    entries.push(...kept)
+    return { lines, remaining: kept.length }
+  })
+}

package/src/host/skills-browser.ts

@@ -0,0 +1,191 @@
+/**
+ * host/skills-browser.ts — M6 read-first skills browser
+ *
+ * Goal: expose existing Maestro skills without taking ownership.
+ * - Confirm boundary with maestro-skills and list metadata/origin only.
+ * - Read-only: no mutation, no write API.
+ * - Model suggestions cannot change skills.
+ * - Browser cannot alter maestro-skills discovery behavior (no provider registration, no writes).
+ *
+ * If later approved to edit, mutation must require explicit user action and
+ * symlink/path containment tests before any write support. This file prepares
+ * the containment helper (isPathContained) and documents the guard, but does
+ * not implement mutation in M6.
+ *
+ * NOTE for future mutation (NOT implemented in M6):
+ * Any future mutation endpoint must require an explicit user action
+ * (UI click with confirmation) and must verify path containment via
+ * isPathContained(targetPath, allowedRoot) including realpath resolution
+ * for symlinks, rejecting any traversal or symlink escape. Tests for
+ * symlink/path containment must pass before mutation is enabled.
+ */
+
+import { existsSync, readdirSync, statSync, lstatSync, readFileSync } from 'node:fs'
+import { join, resolve, relative } from 'node:path'
+
+export interface SkillBrowseEntry {
+  name: string
+  description: string
+  origin: string
+  path: string
+  locator: string
+  metadata: Record<string, string>
+}
+
+export interface ListSkillsOpts {
+  roots?: Array<{ dir: string; origin: string }>
+  skillsDir?: string
+  origin?: string
+}
+
+/**
+ * Whether child is contained inside parent (no traversal escape).
+ * Uses resolved absolute paths and checks relative path does not start with "..".
+ * This helper prepares symlink/path containment tests required before any
+ * future mutation support — explicit user action + containment check.
+ */
+export function isPathContained(child: string, parent: string): boolean {
+  const resolvedChild = resolve(child)
+  const resolvedParent = resolve(parent)
+  if (resolvedChild === resolvedParent) return true
+  const rel = relative(resolvedParent, resolvedChild)
+  // contained if rel does not start with ".." and is not absolute
+  return rel !== '' && !rel.startsWith('..') && !rel.startsWith('/')
+}
+
+function parseFrontmatter(rawContent: string): { metadata: Record<string, string>; body: string } {
+  if (!rawContent.startsWith('---')) return { metadata: {}, body: rawContent }
+  const endIdx = rawContent.indexOf('\n---', 3)
+  if (endIdx === -1) return { metadata: {}, body: rawContent }
+  const yamlLines = rawContent.slice(3, endIdx).split('\n')
+  const body = rawContent.slice(endIdx + 4).trim()
+  const metadata: Record<string, string> = {}
+  let blockKey: string | undefined
+  for (const line of yamlLines) {
+    const trimmed = line.trim()
+    const indent = line.length - trimmed.length
+    if (blockKey !== undefined) {
+      if (trimmed === '') {
+        blockKey = undefined
+        continue
+      }
+      if (indent > 0) {
+        metadata[blockKey] = (metadata[blockKey] + ' ' + trimmed).replace(/\s+/g, ' ').trim()
+        continue
+      }
+      blockKey = undefined
+    }
+    const colonIdx = trimmed.indexOf(':')
+    if (colonIdx <= 0) continue
+    const key = trimmed.slice(0, colonIdx).trim()
+    const val = trimmed.slice(colonIdx + 1).trim()
+    if (val.startsWith('|') || val.startsWith('>')) {
+      metadata[key] = ''
+      blockKey = key
+      continue
+    }
+    metadata[key] = val.startsWith('"') && val.endsWith('"') ? val.slice(1, -1) : val
+  }
+  return { metadata, body }
+}
+
+/**
+ * List skills from a single directory, read-only.
+ * - Scans <skillsDir>/* /SKILL.md
+ * - Parses frontmatter for name/description
+ * - Returns metadata/origin only, does not return body/content
+ * - Does not follow symlink escapes for future mutation; for listing we
+ *   report the logical path, but future mutation will verify containment via
+ *   isPathContained + realpath.
+ */
+export function listSkillsSync(skillsDir: string, origin = 'custom'): SkillBrowseEntry[] {
+  if (!skillsDir) return []
+  let entries: string[] = []
+  try {
+    entries = readdirSync(skillsDir)
+  } catch {
+    return []
+  }
+  const out: SkillBrowseEntry[] = []
+  for (const entry of entries) {
+    const skillFolder = join(skillsDir, entry)
+    let st: any = null
+    try {
+      st = lstatSync(skillFolder)
+    } catch {
+      continue
+    }
+    // allow directory or symlink to directory
+    const isDir = st.isDirectory() || st.isSymbolicLink()
+    if (!isDir) continue
+    // verify it is a directory (follow symlink)
+    try {
+      const follow = statSync(skillFolder)
+      if (!follow.isDirectory()) continue
+    } catch {
+      continue
+    }
+    const skillFilePath = join(skillFolder, 'SKILL.md')
+    try {
+      const fileSt = statSync(skillFilePath)
+      if (!fileSt.isFile()) continue
+    } catch {
+      continue
+    }
+    let rawContent = ''
+    try {
+      rawContent = readFileSync(skillFilePath, 'utf8')
+    } catch {
+      continue
+    }
+    const { metadata } = parseFrontmatter(rawContent)
+    const skillName = metadata.name || entry
+    const description = metadata.description || `Skill for ${skillName}`
+    out.push({
+      name: skillName,
+      description,
+      origin,
+      path: skillFilePath,
+      locator: skillFilePath,
+      metadata,
+    })
+  }
+  return out
+}
+
+/**
+ * Async variant aggregating multiple roots.
+ * Each root is { dir, origin }. If only skillsDir is supplied, use that.
+ */
+export async function listSkills(opts: ListSkillsOpts = {}): Promise<SkillBrowseEntry[]> {
+  if (opts.roots && opts.roots.length > 0) {
+    const all: SkillBrowseEntry[] = []
+    for (const r of opts.roots) {
+      const entries = listSkillsSync(r.dir, r.origin)
+      all.push(...entries)
+    }
+    return all
+  }
+  if (opts.skillsDir) {
+    return listSkillsSync(opts.skillsDir, opts.origin ?? 'custom')
+  }
+  // default: no dir => empty (caller should supply maestro-skills dir explicitly)
+  return []
+}
+
+/**
+ * Resolve default maestro-skills directory for browser (read-only).
+ * Tries well-known checkout location; returns null if not present.
+ * This does NOT alter maestro-skills discovery — it only reads the directory
+ * if it exists, for metadata/origin listing.
+ */
+export function resolveDefaultMaestroSkillsDir(): string | null {
+  const candidates = [
+    '/home/kai/Work/htdocs/maestro-harness/maestro-skills/skills',
+    join(process.cwd(), '../maestro-skills/skills'),
+  ]
+  for (const c of candidates) {
+    if (existsSync(c)) return c
+  }
+  return null
+}