nfo-cli 0.0.4-improve-prompting → 0.0.5

package/src/musicians/message-log.ts

@@ -1,152 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { appendFile, mkdir, readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { messageLogsDir } from '../config.js';
-
-export type MusicianMessageDelivery = 'immediate' | 'queued-drain';
-
-interface MusicianMessageQueuedEvent {
-  type: 'message_queued';
-  message_id: string;
-  musician_id: string;
-  message: string;
-  created_at: string;
-}
-
-interface MusicianMessageDeliveredEvent {
-  type: 'message_delivered';
-  message_id: string;
-  delivered_at: string;
-  delivery: MusicianMessageDelivery;
-}
-
-type MusicianMessageEvent = MusicianMessageQueuedEvent | MusicianMessageDeliveredEvent;
-
-export interface PendingMusicianMessage {
-  messageId: string;
-  musicianId: string;
-  message: string;
-  createdAt: string;
-}
-
-export interface QueueMusicianMessageResult {
-  messageId: string;
-  createdAt: string;
-}
-
-function messageLogFile(orchestraId: string, musicianId: string): string {
-  return join(messageLogsDir(orchestraId), `${musicianId}.jsonl`);
-}
-
-async function appendEvent(
-  orchestraId: string,
-  musicianId: string,
-  event: MusicianMessageEvent,
-): Promise<void> {
-  const dir = messageLogsDir(orchestraId);
-  await mkdir(dir, { recursive: true });
-  await appendFile(messageLogFile(orchestraId, musicianId), JSON.stringify(event) + '\n', 'utf8');
-}
-
-async function readEvents(orchestraId: string, musicianId: string): Promise<MusicianMessageEvent[]> {
-  const file = messageLogFile(orchestraId, musicianId);
-  if (!existsSync(file)) {
-    return [];
-  }
-  const raw = await readFile(file, 'utf8');
-  return raw
-    .split('\n')
-    .map((line) => { return line.trim(); })
-    .filter((line) => { return line.length > 0; })
-    .map((line) => { return JSON.parse(line) as MusicianMessageEvent; });
-}
-
-export async function queueMusicianMessage(
-  orchestraId: string,
-  musicianId: string,
-  message: string,
-): Promise<QueueMusicianMessageResult> {
-  const createdAt = new Date().toISOString();
-  const messageId = `${Date.now()}-${randomUUID()}`;
-  await appendEvent(orchestraId, musicianId, {
-    type: 'message_queued',
-    message_id: messageId,
-    musician_id: musicianId,
-    message,
-    created_at: createdAt,
-  });
-  return { messageId, createdAt };
-}
-
-export async function markMusicianMessageDelivered(
-  orchestraId: string,
-  musicianId: string,
-  messageId: string,
-  delivery: MusicianMessageDelivery,
-  deliveredAt = new Date().toISOString(),
-): Promise<void> {
-  await appendEvent(orchestraId, musicianId, {
-    type: 'message_delivered',
-    message_id: messageId,
-    delivered_at: deliveredAt,
-    delivery,
-  });
-}
-
-export async function listPendingMusicianMessages(
-  orchestraId: string,
-  musicianId: string,
-): Promise<PendingMusicianMessage[]> {
-  const events = await readEvents(orchestraId, musicianId);
-  const pending = new Map<string, PendingMusicianMessage>();
-
-  for (const event of events) {
-    if (event.type === 'message_queued') {
-      pending.set(event.message_id, {
-        messageId: event.message_id,
-        musicianId: event.musician_id,
-        message: event.message,
-        createdAt: event.created_at,
-      });
-      continue;
-    }
-    pending.delete(event.message_id);
-  }
-
-  return [...pending.values()].sort((left, right) => {
-    return left.createdAt.localeCompare(right.createdAt);
-  });
-}
-
-export async function countPendingMusicianMessages(
-  orchestraId: string,
-  musicianId: string,
-): Promise<number> {
-  const pending = await listPendingMusicianMessages(orchestraId, musicianId);
-  return pending.length;
-}
-
-export function formatQueuedMusicianMessages(messages: PendingMusicianMessage[]): string {
-  if (messages.length === 0) {
-    return '';
-  }
-  if (messages.length === 1) {
-    return messages[0].message;
-  }
-
-  const lines = [
-    'NFO queued follow-up messages while you were busy:',
-    '',
-  ];
-
-  messages.forEach((message, index) => {
-    lines.push(`${index + 1}.`);
-    lines.push(message.message);
-    if (index < messages.length - 1) {
-      lines.push('');
-    }
-  });
-
-  return lines.join('\n');
-}

package/src/musicians/message.ts

@@ -1,99 +0,0 @@
-import { sendKeys, sessionName } from '../tmux.js';
-import { readState } from '../state.js';
-import { findMusicianStrict } from './lookup.js';
-import {
-  setMusicianStatus,
-  touchMusicianActivity,
-} from '../state-updaters.js';
-import {
-  countPendingMusicianMessages,
-  formatQueuedMusicianMessages,
-  listPendingMusicianMessages,
-  markMusicianMessageDelivered,
-  queueMusicianMessage,
-  type MusicianMessageDelivery,
-} from './message-log.js';
-
-export interface MessageMusicianOptions {
-  orchestraId: string;
-  musicianId: string;
-  message: string;
-}
-
-export interface MessageMusicianResult {
-  ok: true;
-  delivery: 'immediate' | 'queued';
-  message_id: string;
-  pending_messages: number;
-}
-
-async function deliverPendingMessages(
-  orchestraId: string,
-  musicianId: string,
-  delivery: MusicianMessageDelivery,
-): Promise<number> {
-  const state = await readState(orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${orchestraId}`);
-  }
-  const musician = findMusicianStrict(state, musicianId);
-  const pending = await listPendingMusicianMessages(orchestraId, musicianId);
-  if (pending.length === 0) {
-    return 0;
-  }
-
-  const target = `${sessionName(orchestraId)}:${musician.tmux_window_id}`;
-  const message = formatQueuedMusicianMessages(pending);
-  await sendKeys(target, message, true);
-
-  const deliveredAt = new Date().toISOString();
-  for (const pendingMessage of pending) {
-    await markMusicianMessageDelivered(
-      orchestraId,
-      musicianId,
-      pendingMessage.messageId,
-      delivery,
-      deliveredAt,
-    );
-  }
-  await touchMusicianActivity(orchestraId, musicianId, deliveredAt);
-  return pending.length;
-}
-
-export async function messageMusician(opts: MessageMusicianOptions): Promise<MessageMusicianResult> {
-  const state = await readState(opts.orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${opts.orchestraId}`);
-  }
-  const musician = findMusicianStrict(state, opts.musicianId);
-  const queued = await queueMusicianMessage(opts.orchestraId, opts.musicianId, opts.message);
-
-  if (musician.status === 'idle') {
-    const delivery: MusicianMessageDelivery = (await countPendingMusicianMessages(
-      opts.orchestraId,
-      opts.musicianId,
-    )) === 1 ? 'immediate' : 'queued-drain';
-    await deliverPendingMessages(opts.orchestraId, opts.musicianId, delivery);
-    await setMusicianStatus(opts.orchestraId, opts.musicianId, 'working');
-    return {
-      ok: true,
-      delivery: 'immediate',
-      message_id: queued.messageId,
-      pending_messages: 0,
-    };
-  }
-
-  return {
-    ok: true,
-    delivery: 'queued',
-    message_id: queued.messageId,
-    pending_messages: await countPendingMusicianMessages(opts.orchestraId, opts.musicianId),
-  };
-}
-
-export async function drainQueuedMusicianMessages(
-  orchestraId: string,
-  musicianId: string,
-): Promise<number> {
-  return deliverPendingMessages(orchestraId, musicianId, 'queued-drain');
-}

package/src/musicians/query.ts

@@ -1,19 +0,0 @@
-import { capturePane, sessionName } from '../tmux.js';
-import { readState } from '../state.js';
-import { findMusicianStrict } from './lookup.js';
-
-export interface QueryMusicianOptions {
-  orchestraId: string;
-  musicianId: string;
-  lines?: number;
-}
-
-export async function queryMusician(opts: QueryMusicianOptions): Promise<string> {
-  const state = await readState(opts.orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${opts.orchestraId}`);
-  }
-  const musician = findMusicianStrict(state, opts.musicianId);
-  const target = `${sessionName(opts.orchestraId)}:${musician.tmux_window_id}`;
-  return capturePane(target, opts.lines ?? 80);
-}

package/src/musicians/spawn.ts

@@ -1,139 +0,0 @@
-import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { execa } from "execa";
-import { addMusician } from "../state-updaters.js";
-import { readState } from "../state.js";
-import { orchestraDir, worktreesDir } from "../config.js";
-import { addWorktree } from "../worktree.js";
-import { claudeFlagsForLevel } from "../permission.js";
-import { respawnPane, sessionName, setPaneOption } from "../tmux.js";
-import { MUSICIAN_ROLE_PROMPT_V1 } from "../prompts/musician-role.js";
-import { buildMusicianInitialPrompt } from "../prompts/tool-discipline.js";
-import { nextMusicianId } from "./ids.js";
-import { buildClaudeCommand } from "../claude-command.js";
-import { writeMusicianMcpConfig } from "../mcp/config.js";
-
-export interface CreateMusicianOptions {
-  orchestraId: string;
-  name: string;
-  task: string;
-  worktree?: boolean; // default true
-  branchFrom?: string; // default HEAD
-  model: "sonnet" | "haiku";
-  dryRun?: boolean; // skip launching claude; useful for tests
-}
-
-export type CreateMusicianResult = {
-  musician_id: string;
-  worktree_path: string | null;
-  branch: string | null;
-  tmux_window_id: string;
-};
-
-export async function createMusician(
-  opts: CreateMusicianOptions,
-): Promise<CreateMusicianResult> {
-  const state = await readState(opts.orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${opts.orchestraId}`);
-  }
-
-  const musicianId = nextMusicianId(state);
-  const useWorktree = opts.worktree !== false;
-
-  let workingDir: string;
-  let worktreePath: string | null = null;
-  let branch: string | null = null;
-  if (useWorktree) {
-    worktreePath = join(worktreesDir(opts.orchestraId), musicianId);
-    branch = `nfo/${musicianId}`;
-    await addWorktree({
-      repoRoot: state.project_path,
-      path: worktreePath,
-      branch,
-      baseRef: opts.branchFrom,
-    });
-    workingDir = worktreePath;
-  } else {
-    workingDir = state.project_path;
-  }
-
-  const promptFile = join(
-    orchestraDir(opts.orchestraId),
-    `musician-${musicianId}-prompt.md`,
-  );
-  await writeFile(promptFile, MUSICIAN_ROLE_PROMPT_V1, "utf8");
-
-  const session = sessionName(opts.orchestraId);
-  const winLabel = `mus-${musicianId}-${sanitiseName(opts.name)}`;
-  const { stdout: tmuxWindowId } = await execa("tmux", [
-    "new-window",
-    "-t",
-    session,
-    "-n",
-    winLabel,
-    "-c",
-    workingDir,
-    "-d",
-    "-P",
-    "-F",
-    "#{window_id}",
-  ]);
-
-  if (!opts.dryRun) {
-    const mcpConfigPath = await writeMusicianMcpConfig(
-      opts.orchestraId,
-      musicianId,
-    );
-    const flags = claudeFlagsForLevel(state.permission_level);
-    const cmd = buildClaudeCommand({
-      flags,
-      mcpConfigPath,
-      promptFile,
-      prompt: buildMusicianInitialPrompt(opts.task),
-      model: opts.model,
-    });
-    await setPaneOption(
-      `${session}:${tmuxWindowId.trim()}`,
-      "remain-on-exit",
-      "on",
-    );
-    await respawnPane(`${session}:${tmuxWindowId.trim()}`, cmd);
-  } else {
-    await writeMusicianMcpConfig(opts.orchestraId, musicianId);
-  }
-
-  const now = new Date().toISOString();
-  await addMusician(opts.orchestraId, {
-    id: musicianId,
-    name: opts.name,
-    task_summary: opts.task.slice(0, 200),
-    status: "working",
-    pending_permission: null,
-    tmux_window_id: tmuxWindowId.trim(),
-    claude_session_id: null,
-    worktree_path: worktreePath,
-    branch,
-    spawned_at: now,
-    last_activity: now,
-    model: opts.model,
-  });
-
-  return {
-    musician_id: musicianId,
-    worktree_path: worktreePath,
-    branch,
-    tmux_window_id: tmuxWindowId.trim(),
-  };
-}
-
-function sanitiseName(name: string): string {
-  return (
-    name
-      .toLowerCase()
-      .replace(/[^a-z0-9-]+/g, "-")
-      .replace(/-+/g, "-")
-      .replace(/^-|-$/g, "")
-      .slice(0, 32) || "musician"
-  );
-}

package/src/notes.ts

@@ -1,39 +0,0 @@
-import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { notesDir } from './config.js';
-
-function ensureSafeFilename(filename: string): void {
-  if (!filename || /[\/\\]/.test(filename) || filename.includes('..')) {
-    throw new Error(`invalid filename: ${filename}`);
-  }
-}
-
-export async function noteWrite(
-  orchestraId: string,
-  filename: string,
-  content: string,
-): Promise<void> {
-  ensureSafeFilename(filename);
-  const dir = notesDir(orchestraId);
-  await mkdir(dir, { recursive: true });
-  await writeFile(join(dir, filename), content, 'utf8');
-}
-
-export async function noteRead(orchestraId: string, filename: string): Promise<string> {
-  ensureSafeFilename(filename);
-  const file = join(notesDir(orchestraId), filename);
-  if (!existsSync(file)) {
-    return '';
-  }
-  return readFile(file, 'utf8');
-}
-
-export async function noteList(orchestraId: string): Promise<string[]> {
-  const dir = notesDir(orchestraId);
-  if (!existsSync(dir)) {
-    return [];
-  }
-  const entries = await readdir(dir, { withFileTypes: true });
-  return entries.filter((e) => { return e.isFile(); }).map((e) => { return e.name; });
-}

package/src/notify.ts

@@ -1,62 +0,0 @@
-import { execa } from 'execa';
-
-export interface NotifyOptions {
-  pendingCount: number;
-  platform?: NodeJS.Platform;
-  bell?: (text: string) => void;
-  spawn?: (bin: string, args: string[]) => Promise<unknown>;
-}
-
-function defaultBell(text: string): void {
-  process.stdout.write(text);
-}
-
-async function defaultSpawn(bin: string, args: string[]): Promise<unknown> {
-  return execa(bin, args);
-}
-
-function pluralise(count: number): string {
-  if (count === 1) {
-    return '1 musician awaiting permission';
-  }
-  return `${count} musicians awaiting permission`;
-}
-
-/**
- * Fire a single notification: ring the terminal bell and (best-effort) spawn
- * the platform's desktop notifier. All errors are swallowed — a missing
- * notify-send / osascript / etc. must not break the orchestra.
- */
-export async function notifyAwaitingPermission(opts: NotifyOptions): Promise<void> {
-  const bell = opts.bell ?? defaultBell;
-  const spawn = opts.spawn ?? defaultSpawn;
-  const platform = opts.platform ?? process.platform;
-  const message = pluralise(opts.pendingCount);
-
-  try {
-    bell('\x07');
-  } catch {
-    // Swallow — a broken stdout sink should never abort.
-  }
-
-  if (platform === 'linux') {
-    try {
-      await spawn('notify-send', ['NFO', message]);
-    } catch {
-      // notify-send may not be installed — best-effort only.
-    }
-    return;
-  }
-
-  if (platform === 'darwin') {
-    const script = `display notification "${message}" with title "NFO"`;
-    try {
-      await spawn('osascript', ['-e', script]);
-    } catch {
-      // osascript should exist on macOS but swallow defensively.
-    }
-    return;
-  }
-
-  // Unknown platform (win32, freebsd, etc.) — bell-only.
-}

package/src/orchestrator/report-back.ts

@@ -1,33 +0,0 @@
-import { sendKeys, sessionName } from '../tmux.js';
-
-export interface MusicianDoneReport {
-  musicianId: string;
-  musicianName: string;
-  summary: string;
-  nextSteps?: string | null;
-}
-
-export function formatMusicianDonePrompt(report: MusicianDoneReport): string {
-  const nextSteps = report.nextSteps?.trim()
-    ? `\nSuggested next steps from the Musician:\n${report.nextSteps.trim()}\n`
-    : '';
-
-  return `Musician ${report.musicianId} (${report.musicianName}) reported done and is now idle.
-
-Summary:
-${report.summary}
-${nextSteps}
-Resolve this now with an NFO tool call only:
-- If the work is good enough, call dismiss_musician({ musician_id: ${JSON.stringify(report.musicianId)} }).
-- If it needs another pass, call message_musician({ musician_id: ${JSON.stringify(report.musicianId)}, message: "..." }).
-
-Do not leave this Musician idle without either dismissing it or sending the next iteration.
-A plain-text acknowledgement is invalid here.`;
-}
-
-export async function notifyOrchestratorOfDoneReport(
-  orchestraId: string,
-  report: MusicianDoneReport,
-): Promise<void> {
-  await sendKeys(`${sessionName(orchestraId)}:0`, formatMusicianDonePrompt(report), true);
-}

package/src/permission.ts

@@ -1,30 +0,0 @@
-export const PERMISSION_LEVELS = ['dangerouslySkipPermissions', 'auto', 'acceptEdits', 'supervised', 'strict'] as const;
-export type PermissionLevel = (typeof PERMISSION_LEVELS)[number];
-
-export function isPermissionLevel(s: string): s is PermissionLevel {
-  return (PERMISSION_LEVELS as readonly string[]).includes(s);
-}
-
-export function claudeFlagsForLevel(level: PermissionLevel): string[] {
-  switch (level) {
-    case 'dangerouslySkipPermissions':
-      return ['--dangerously-skip-permissions'];
-    case 'auto':
-      return ['--permission-mode', 'auto'];
-    case 'acceptEdits':
-      return ['--permission-mode', 'acceptEdits'];
-    case 'supervised':
-      return ['--permission-mode', 'default'];
-    case 'strict':
-      return ['--permission-mode', 'plan'];
-  }
-}
-
-export const DANGEROUSLY_SKIP_PERMISSIONS_CONFIRM_PHRASE = 'I understand';
-
-export const DANGEROUSLY_SKIP_PERMISSIONS_WARNING = `⚠ "Dangerously skip permissions" mode disables all permission checks.
-Musicians can execute arbitrary shell commands, modify files anywhere on
-this system, and access the network without asking. Worktrees limit but
-do not contain risky operations. Use this only in trusted sandboxes or
-when you accept these risks.
-Type "${DANGEROUSLY_SKIP_PERMISSIONS_CONFIRM_PHRASE}" to continue.`;

package/src/project-key.ts

@@ -1,12 +0,0 @@
-import { createHash } from 'node:crypto';
-import { basename } from 'node:path';
-
-export function projectKeyFromPath(absolutePath: string): string {
-  const hash = createHash('sha1').update(absolutePath).digest('hex').slice(0, 10);
-  const name = basename(absolutePath)
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '');
-  return `${hash}-${name || 'project'}`;
-}

package/src/prompts/musician-role.ts

@@ -1,22 +0,0 @@
-import { MUSICIAN_TOOL_DISCIPLINE } from './tool-discipline.js';
-
-export const MUSICIAN_ROLE_PROMPT_V1 = `You are a Musician in an NFO orchestra.
-
-You were spawned by the Orchestrator with a specific task. The user typing into
-your pane is debugging / observing — usually the user does NOT direct you;
-the Orchestrator does. Treat new user messages as either Orchestrator
-hand-offs or out-of-band human guidance, and use judgment.
-
-Your workspace is a dedicated git worktree, so file edits are isolated from
-other Musicians. When you finish the task you were spawned with, call the
-\`report_done\` MCP tool with a concise summary and optional next steps. After
-that, stay alive while the Orchestrator reviews your report. NFO may batch
-queued follow-up messages and deliver them right after \`report_done\`; if the
-Orchestrator is satisfied, it may dismiss you instead.
-
-${MUSICIAN_TOOL_DISCIPLINE}
-
-You also have the full NFO MCP tool surface (\`spawn_musician\`,
-\`message_musician\`, etc.). Avoid spawning sub-Musicians unless the
-Orchestrator explicitly asks you to. Keep coordination centralised.
-`;