Give your whole website one voice

import { resolve } from 'node:path';
import type { SiteClient } from '@fetchski/attract-cms-sdk';
import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
import { MemorySaver } from '@langchain/langgraph';
import { ChatOpenRouter } from '@langchain/openrouter';
import { CompositeBackend, createDeepAgent, FilesystemBackend, StateBackend } from 'deepagents';
import { todoListMiddleware } from 'langchain';
import { type SavedDraft, siteTools } from './tools.ts';

const REWRITE = `You give a small business website one voice. Over the years different people wrote its pages,
posts and FAQs, so they sound like different businesses. You agree with the owner how the business
sounds, and bring every document into that voice, with the owner approving each one.

The voice guide is /memories/voice-guide.md, your long-term memory: it is kept between runs, and loaded
into your agent memory at the start of each one.

Work in this order:
1. Plan your work with write_todos.
2. Call list_site_content once.
3. If your agent memory holds the voice guide, go to step 4. Otherwise call ask_owner: list the titles,
   and ask which two or three sound most like the business at its best. Read those documents with
   read_document, and write /memories/voice-guide.md: who "we" and "you" are, the tone, sentence length, words and phrases to use, words
   and phrases to avoid, punctuation habits, and three short before/after examples taken from the site.
4. Call ask_owner with the whole guide, and ask the owner to approve it or say what to change. Update
   /memories/voice-guide.md with edit_file and ask again until the owner approves it.
5. For every other document, one at a time, hand it to the rewriter subagent with the task tool: give
   its kind, id and title, and tell it the guide is at /memories/voice-guide.md. Never ask the owner
   about a document's changes yourself: the rewriter's save shows them, and the owner decides there.
6. When a rewriter reports a rule the owner gave, add it to /memories/voice-guide.md with edit_file.
7. Finish with a short summary: how many documents you rewrote, and which ones you left as they were.

Each ask_owner call asks ONE question. Write it in Markdown, with a blank line between paragraphs and
between list items.`;

const CHECK = `You check that a small business website still speaks in one voice: the one in the voice guide,
/memories/voice-guide.md, which the owner approved. It is loaded into your agent memory. Nobody is at the
keyboard for this run: you can't change the site, and you never change the guide.

Work in this order:
1. If your agent memory has no voice guide, answer only "There is no voice guide yet: run the agent at
   your keyboard first, with npm start." and stop.
2. Plan your work with write_todos.
3. Call list_site_content once.
4. Hand the documents to the checker subagent with the task tool, about eight at a time: give it the
   kind, id and title of each.
5. Finish with a report for the owner: a heading per document that drifts from the guide, with what
   drifts and a few of its words quoted. Then how many documents already fit.`;

const REWRITER = `You rewrite one website document in the business's own voice. Read /memories/voice-guide.md with
read_file, then the document with read_document. Rewrite only the wording that doesn't follow the guide.
Keep every fact exactly: names, prices, numbers, dates, addresses, links, and every HTML tag. Keep
headings about as long as they were. Then call save_draft_changes ONCE with every change, and the
document's title. If the owner sends it back with notes, revise your changes to match and call
save_draft_changes again. If the document already follows the guide, change nothing. Answer in one
line: what you changed, or that it already fit, then any rule the owner's notes gave, in their words.`;

const CHECKER = `You check website documents against the business's voice. Read /memories/voice-guide.md with
read_file, then each document you are given with read_document. Answer one line per document:
<kind> "<title>": fits, or <kind> "<title>": drifts, how, with a few of its words quoted.`;

export interface AgentOptions {
  /** Nobody is at the keyboard: the agent only checks and reports, with no tool to ask or to write. */
  reportOnly?: boolean;
  /** The folder on disk that keeps the agent's long-term memory (the voice guide) between runs. */
  memoryFolder?: string;
}

/** The deep agent: our SDK's operations as its tools, a subagent per document, and the owner's approval before any draft is written. */
export function buildAgent(
  site: SiteClient,
  model: BaseChatModel,
  saved: Map<string, SavedDraft>,
  log: (line: string) => void,
  { reportOnly = false, memoryFolder = 'memories' }: AgentOptions = {}
) {
  const tools = siteTools(site, saved, log);
  return createDeepAgent({
    model,
    systemPrompt: reportOnly ? CHECK : REWRITE,
    tools: reportOnly
      ? [tools.listSiteContent, tools.readDocument]
      : [tools.listSiteContent, tools.readDocument, tools.askOwner],
    middleware: [todoListMiddleware()],
    subagents: [
      reportOnly
        ? {
            name: 'checker',
            description:
              'Checks a batch of documents against /memories/voice-guide.md, one line each.',
            systemPrompt: CHECKER,
            tools: [tools.readDocument]
          }
        : {
            name: 'rewriter',
            description:
              'Rewrites one document in the voice of /memories/voice-guide.md and saves it as a draft, once the owner approves.',
            systemPrompt: REWRITER,
            tools: [tools.readDocument, tools.saveDraftChanges]
          }
    ],
    // Long-term memory: /memories/ is a folder on disk, kept between runs; every other file lives
    // for one run. The voice guide is loaded into the agent's instructions at the start of each run.
    backend: new CompositeBackend(new StateBackend(), {
      '/memories/': new FilesystemBackend({ rootDir: resolve(memoryFolder), virtualMode: true })
    }),
    memory: ['/memories/voice-guide.md'],
    // Nothing is written without the owner: approve it, edit it, or reject it.
    interruptOn: { save_draft_changes: { allowedDecisions: ['approve', 'edit', 'reject'] } },
    checkpointer: new MemorySaver()
  });
}

/** The OpenRouter model and settings named in .env. ChatOpenRouter reads OPENROUTER_API_KEY itself. */
export function modelFromEnv() {
  return new ChatOpenRouter({
    model: process.env.OPENROUTER_MODEL || '~google/gemini-flash-latest',
    temperature: Number(process.env.OPENROUTER_TEMPERATURE || 0.3),
    maxTokens: Number(process.env.OPENROUTER_MAX_TOKENS || 16000)
  });
}

import type { SiteClient } from '@fetchski/attract-cms-sdk';
import { interrupt } from '@langchain/langgraph';
import { tool } from 'langchain';
import { z } from 'zod';
import { type Kind, listDocuments, readWording, saveDraftChanges } from './content.ts';

const kind = z.enum(['page', 'post', 'faq']).describe('page, post (a blog post) or faq');

/** A document the agent saved a draft of. */
export interface SavedDraft {
  kind: Kind;
  title: string;
}

/**
 * Our SDK's operations, as the agent's tools. `saved` collects every document a draft was written
 * for, by id; `log` shows the agent's progress.
 */
export function siteTools(
  site: SiteClient,
  saved: Map<string, SavedDraft>,
  log: (line: string) => void
) {
  const listSiteContent = tool(
    async () => {
      const documents = await listDocuments(site);
      log(`Found ${documents.length} document${documents.length === 1 ? '' : 's'}.`);
      return JSON.stringify(documents);
    },
    {
      name: 'list_site_content',
      description:
        'Lists every page, blog post and FAQ on the website: kind, id and title. Call it once.',
      schema: z.object({})
    }
  );

  const readDocument = tool(
    async (args) => {
      const document = await readWording(site, args.kind, args.id);
      log(`Read the ${args.kind} "${document.title}".`);
      return JSON.stringify(document.wording);
    },
    {
      name: 'read_document',
      description:
        'Reads one document: every piece of its wording, each with the path that finds it again. Rich text is HTML.',
      schema: z.object({ kind, id: z.string().describe('The id from list_site_content') })
    }
  );

  const saveDraftChangesTool = tool(
    async (args) => {
      const answer = await saveDraftChanges(site, args.kind, args.id, args.changes);
      if (answer.startsWith('Saved')) {
        saved.set(args.id, { kind: args.kind, title: args.title });
      }
      return answer;
    },
    {
      name: 'save_draft_changes',
      description:
        'Saves edits to ONE document as a draft, once the owner approves them. Keep every HTML tag and link ' +
        'exactly; change only words. `before` is the exact text read_document gave for that path.',
      schema: z.object({
        kind,
        id: z.string(),
        title: z.string().describe("The document's title, shown to the owner"),
        changes: z
          .array(z.object({ path: z.string(), before: z.string(), after: z.string() }))
          .min(1)
          .describe('Every edit to this document, each at its path')
      })
    }
  );

  const askOwner = tool(
    // Pauses the run until the owner answers; their answer is the tool's result.
    async (args) => String(interrupt({ question: args.question })),
    {
      name: 'ask_owner',
      description: 'Asks the website owner one question, and waits for their answer.',
      schema: z.object({ question: z.string() })
    }
  );

  return { listSiteContent, readDocument, saveDraftChanges: saveDraftChangesTool, askOwner };
}

import type { SiteClient } from '@fetchski/attract-cms-sdk';

/** The three kinds of document the agent reads and edits. */
export type Kind = 'page' | 'post' | 'faq';

export interface DocumentRow {
  kind: Kind;
  id: string; // the draft's id, `…:en:draft`
  title: string;
}

/** One piece of wording in a document: where it sits, and what it says (rich text is HTML). */
export interface Wording {
  path: string;
  text: string;
}

/** One edit: the wording at `path` goes from `before` to `after`. */
export interface Change {
  path: string;
  before: string;
  after: string;
}

/** The most documents one run reads: a ceiling on time and AI cost. */
export const MAX_DOCUMENTS = Number(process.env.MAX_DOCUMENTS ?? 80);

/** The fields that hold a document's wording, per kind. Nothing else is ever written. */
export const EDITABLE: Record<Kind, readonly string[]> = {
  page: ['title', 'seoDescription', 'sections'],
  post: ['title', 'excerpt', 'seoDescription', 'main'],
  faq: ['title', 'answer']
};

// Keys inside a widget that never hold wording: ids, types, styling, links.
const NOT_WORDING = /^(_|metaType$|type$|id$)|css|color|icon|font|url|href|slug|image|video/i;

/** Every page, blog post and FAQ, as drafts: the latest wording, published or not. */
export async function listDocuments(site: SiteClient): Promise<DocumentRow[]> {
  const draft = { aposMode: 'draft' } as const;
  const [pages, posts, faqs] = await Promise.all([
    site.pages().listPagesPick(['title', 'type'], draft),
    site.blogPosts().listBlogsPick(['title'], draft),
    site.faqItems().listFaqItemsPick(['title'], draft)
  ]);
  const rows: DocumentRow[] = [
    ...pages
      .filter((page) => page.type !== '@apostrophecms/archive-page')
      .map((page) => ({ kind: 'page' as const, id: page.id, title: String(page.title) })),
    ...posts.map((post) => ({ kind: 'post' as const, id: post.id, title: String(post.title) })),
    ...faqs.map((faq) => ({ kind: 'faq' as const, id: faq.id, title: String(faq.title) }))
  ];
  return rows.slice(0, MAX_DOCUMENTS);
}

/** A document's draft, as a plain object. */
async function readDraft(
  site: SiteClient,
  kind: Kind,
  id: string
): Promise<Record<string, unknown>> {
  const draftId = id.replace(/:published$/, ':draft');
  switch (kind) {
    case 'page':
      return { ...(await site.pages().getPage({ id: draftId })) };
    case 'post':
      return { ...(await site.blogPosts().getBlog({ id: draftId })) };
    case 'faq':
      return { ...(await site.faqItems().getFaqItem({ id: draftId })) };
  }
}

/** A document's title, and every piece of wording in its draft with the path that finds it again. */
export async function readWording(
  site: SiteClient,
  kind: Kind,
  id: string
): Promise<{ title: string; wording: Wording[] }> {
  const doc = await readDraft(site, kind, id);
  const found: Wording[] = [];
  const visit = (value: unknown, path: string, topLevel: boolean) => {
    if (typeof value === 'string') {
      // A top-level field is wording even as one word; inside a widget, wording has a space in it.
      if (value.trim() && (topLevel || /\s/.test(value.trim())) && !/^https?:\/\//.test(value)) {
        found.push({ path, text: value });
      }
    } else if (Array.isArray(value)) {
      for (const [index, item] of value.entries()) {
        visit(item, `${path}.${index}`, false);
      }
    } else if (value && typeof value === 'object') {
      for (const [key, item] of Object.entries(value)) {
        if (!NOT_WORDING.test(key)) {
          visit(item, `${path}.${key}`, false);
        }
      }
    }
  };
  for (const field of EDITABLE[kind]) {
    visit(doc[field], field, true);
  }
  return { title: String(doc.title), wording: found };
}

/**
 * Writes the changes to the document's DRAFT. Each change must still match what the agent read
 * (`before`), so an edit someone made meanwhile is never overwritten. Answers in words, for the agent.
 */
export async function saveDraftChanges(
  site: SiteClient,
  kind: Kind,
  id: string,
  changes: readonly Change[]
): Promise<string> {
  const draftId = id.replace(/:published$/, ':draft');
  const doc = await readDraft(site, kind, draftId);
  const fields = new Map<string, unknown>();
  for (const change of changes) {
    const [field = '', ...rest] = change.path.split('.');
    if (!EDITABLE[kind].includes(field)) {
      return `Not saved: "${change.path}" is not wording this tool may change (allowed: ${EDITABLE[kind].join(', ')}).`;
    }
    if (!fields.has(field)) {
      fields.set(field, structuredClone(doc[field]));
    }
    if (rest.length === 0) {
      if (fields.get(field) !== change.before) {
        return `Not saved: "${change.path}" changed since you read it. Read the document again.`;
      }
      fields.set(field, change.after);
      continue;
    }
    let parent = fields.get(field) as Record<string, unknown> | undefined;
    for (const key of rest.slice(0, -1)) {
      parent = parent?.[key] as Record<string, unknown> | undefined;
    }
    const last = rest[rest.length - 1] ?? '';
    if (!parent || parent[last] !== change.before) {
      return `Not saved: "${change.path}" changed since you read it. Read the document again.`;
    }
    parent[last] = change.after;
  }

  const text = (name: string) => fields.get(name) as string | undefined;
  const area = (name: string) => fields.get(name) as Record<string, unknown> | undefined;
  switch (kind) {
    case 'page':
      await site.pages().updatePage({
        id: draftId,
        title: text('title'),
        seoDescription: text('seoDescription'),
        sections: area('sections')
      });
      break;
    case 'post':
      await site.blogPosts().updateBlog({
        id: draftId,
        title: text('title'),
        excerpt: text('excerpt'),
        seoDescription: text('seoDescription'),
        main: area('main')
      });
      break;
    case 'faq':
      await site
        .faqItems()
        .updateFaqItem({ id: draftId, title: text('title'), answer: area('answer') });
      break;
  }
  return `Saved ${changes.length} change(s) to the draft of ${draftId}. Nothing is live until a person publishes it.`;
}

/** A private link to a page's or post's draft, for anyone you send it to: no sign-in. FAQs have no page of their own. */
export async function previewLink(
  site: SiteClient,
  kind: Kind,
  id: string
): Promise<string | null> {
  if (kind === 'faq') {
    return null;
  }
  const doc = await readDraft(site, kind, id);
  const shared =
    kind === 'page'
      ? await site.pages().sharePage({ id, share: true })
      : await site.blogPosts().shareBlog({ id, share: true });
  return `${String(doc.url)}?${new URLSearchParams({ aposShareKey: shared.aposShareKey ?? '', aposShareId: id })}`;
}

import { randomUUID } from 'node:crypto';
import { Command } from '@langchain/langgraph';
import type { buildAgent } from './agent.ts';
import type { Change } from './content.ts';
import type { Usage } from './usage.ts';

/** A draft the agent wants to save: the document, and every change to it. */
export interface Draft {
  kind: string;
  title: string;
  changes: Change[];
}

/** Your call on a draft: save it all, keep some changes, send it back with notes, or skip it. */
export type Choice =
  | { type: 'all' }
  | { type: 'some'; keep: number[] }
  | { type: 'revise'; feedback: string }
  | { type: 'skip'; reason: string };

/** The person at the keyboard. src/terminal.ts is the real one; the tests script one. */
export interface Owner {
  /** The agent is working (a spinner, in the terminal). */
  busy?(): void;
  /** Answers the agent's question. */
  answer(question: string): Promise<string>;
  /** Decides on a draft the agent wants to save. */
  decide(draft: Draft): Promise<Choice>;
}

/** Nobody at the keyboard: a report-only run, whose agent has no tool to ask or to save. */
export const nobody: Owner = {
  answer: async () => {
    throw new Error('A report-only run never asks.');
  },
  decide: async () => {
    throw new Error('A report-only run never saves.');
  }
};

interface ActionRequest {
  name: string;
  args: { kind?: string; id?: string; title?: string; changes?: Change[] };
}

type Decision =
  | { type: 'approve' }
  | { type: 'reject'; message: string }
  | { type: 'edit'; editedAction: { name: string; args: ActionRequest['args'] } };

/** The most steps (model calls and tool calls) one run may take: a ceiling on AI cost. */
const MAX_STEPS = Number(process.env.AGENT_MAX_STEPS ?? 300);

/**
 * Runs the agent to the end. Each time it pauses, the owner answers its question, or decides on the
 * drafts it wants to write. Resolves the agent's closing summary.
 */
export async function runWithOwner(
  agent: ReturnType<typeof buildAgent>,
  task: string,
  owner: Owner,
  usage?: Usage
): Promise<string> {
  // `usage` counts every model call's tokens and cost, the subagents' too.
  const config = {
    configurable: { thread_id: randomUUID() },
    recursionLimit: MAX_STEPS,
    callbacks: usage ? [usage] : []
  };
  let input: Parameters<typeof agent.invoke>[0] = { messages: [{ role: 'user', content: task }] };

  for (;;) {
    owner.busy?.();
    const result = await agent.invoke(input, config);
    // Several rewriters can pause at once: each pause gets its own answer, by its id.
    const pending = result.__interrupt__ ?? [];
    if (pending.length === 0) {
      const last = result.messages.at(-1);
      return typeof last?.content === 'string' ? last.content : JSON.stringify(last?.content ?? '');
    }

    const answers: Record<string, unknown> = {};
    for (const { id, value } of pending) {
      const paused = value as { question?: string; actionRequests?: ActionRequest[] };
      if (paused.question) {
        answers[String(id)] = await owner.answer(paused.question);
        continue;
      }
      const decisions: Decision[] = [];
      for (const action of paused.actionRequests ?? []) {
        decisions.push(await review(action, owner));
      }
      answers[String(id)] = { decisions };
    }
    input = new Command({ resume: answers });
  }
}

/** Your choice, in the form the agent's approval step takes: approve, edit (fewer changes) or reject. */
async function review(action: ActionRequest, owner: Owner): Promise<Decision> {
  const changes = action.args.changes ?? [];
  const choice = await owner.decide({
    kind: action.args.kind ?? 'page',
    title: action.args.title ?? '',
    changes
  });

  switch (choice.type) {
    case 'all':
      return { type: 'approve' };
    case 'some': {
      const kept = changes.filter((_, index) => choice.keep.includes(index));
      if (kept.length === 0) {
        return {
          type: 'reject',
          message: 'The owner kept none of these changes. Do not try them again.'
        };
      }
      return {
        type: 'edit',
        editedAction: { name: action.name, args: { ...action.args, changes: kept } }
      };
    }
    case 'revise':
      return {
        type: 'reject',
        message:
          `Not saved yet: the owner wants changes first. Their words: "${choice.feedback}". ` +
          'Revise your changes to match, then call the same tool again with every change.'
      };
    case 'skip':
      return {
        type: 'reject',
        message: `The owner skipped this draft${choice.reason ? `: ${choice.reason}` : ''}. Do not try it again.`
      };
  }
}

import { stdout } from 'node:process';
import { stripVTControlCharacters, styleText } from 'node:util';
import * as prompt from '@clack/prompts';
import { diffWordsWithSpace } from 'diff';
import { Marked, type Tokens } from 'marked';
import stringWidth from 'string-width';
import yoctoSpinner from 'yocto-spinner';
import type { Change } from './content.ts';
import type { Choice, Draft, Owner } from './review.ts';
import type { Usage } from './usage.ts';

/** You pressed Ctrl+C or Esc at a prompt: the run stops, and the drafts saved so far stay drafts. */
export class Stopped extends Error {}

/**
 * The person at the keyboard, in the terminal: a spinner while the agent works, with what it is
 * doing and what the run has used so far; its words as formatted text.
 */
export function terminalOwner(usage?: Usage): Owner & {
  step: (line: string) => void;
  report: (markdown: string) => void;
  failed: (error: unknown) => void;
} {
  // yocto-spinner's own dots; each frame redraws in one synchronized write, so it never flickers.
  const spin = yoctoSpinner({ stream: stdout });
  // Like yocto-spinner, only a terminal (not TERM=dumb, outside CI) gets live updates; anywhere
  // else each one would print a new line, so output sent to a file gets the start and the steps.
  const live = Boolean(stdout.isTTY) && process.env.TERM !== 'dumb' && !('CI' in process.env);
  let spinning = false;
  let started = 0;
  let clock: NodeJS.Timeout | undefined;
  let steps: string[] = [];
  let doing = 'The agent is working';

  // What the agent is doing, then the tokens, cost and time so far: one line, never wrapped.
  // On a narrow terminal the tokens and cost go first, then the time, before the task is cut.
  const line = () => {
    const seconds = Math.floor((Date.now() - started) / 1000);
    const time = seconds >= 60 ? `${Math.floor(seconds / 60)}m ${seconds % 60}s` : `${seconds}s`;
    const spent = usage && `${tokens(usage)} · $${usage.cost.toFixed(4)}`;
    const width = (stdout.columns || 80) - 3;
    const tail =
      [[spent, time], [time]]
        .map((parts) => parts.filter(Boolean).join(' · '))
        .find((text) => width - stringWidth(text) - 2 >= Math.min(stringWidth(doing), 20)) ?? '';
    const room = tail ? width - stringWidth(tail) - 2 : width;
    return tail ? `${fit(doing, room)}  ${styleText('dim', tail)}` : fit(doing, room);
  };
  const withUsage = (text: string) =>
    usage ? `${text}  ${styleText('dim', `${tokens(usage)} · $${usage.cost.toFixed(4)}`)}` : text;
  const refresh = () => {
    if (spinning && live) {
      spin.text = line();
    }
  };
  if (usage) {
    usage.onCall = refresh;
  }

  // The spinner sits on the run's guide line, like the rest of the terminal.
  const startSpinner = () => {
    started = Date.now();
    spinning = true;
    stdout.write(`${styleText('gray', prompt.S_BAR)}\n`);
    spin.start(line());
    if (live) {
      clock = setInterval(refresh, 1000);
    }
  };
  const stopSpinner = (finish: () => void) => {
    clearInterval(clock);
    spin.stop();
    spinning = false;
    finish();
  };

  // What the agent did since you last heard from it, as one dim line.
  const settle = () => {
    if (spinning) {
      const done = withUsage(styleText('dim', steps.join(' · ') || 'Done'));
      stopSpinner(() => prompt.log.step(done, { spacing: 0 }));
    }
    steps = [];
  };

  return {
    busy() {
      if (!spinning) {
        doing = 'The agent is working';
        startSpinner();
      }
    },
    step(text) {
      doing = text.replace(/\.$/, '');
      steps.push(doing);
      refresh();
    },
    async answer(question) {
      settle();
      say(markdown(question), 'cyan');
      return ask(() =>
        prompt.text({ message: 'Your answer', placeholder: 'Type, then press Enter' })
      );
    },
    async decide(draft) {
      settle();
      say(
        [
          styleText('bold', `Save a draft of the ${draft.kind} "${draft.title}"?`),
          ...draft.changes.map((change, index) => showChange(change, index))
        ].join('\n\n'),
        'cyan'
      );
      return decide(draft);
    },
    /** Shows the run's report. */
    report(text) {
      settle();
      say(markdown(text), 'green');
    },
    /** The run stopped on an error: the spinner says so, and the error follows. */
    failed(error) {
      if (spinning) {
        stopSpinner(() => prompt.log.error('The run stopped', { spacing: 0 }));
      }
      prompt.log.error(error instanceof Error ? error.message : String(error));
    }
  };
}

/** "183,204 tokens": read and written together. */
function tokens(usage: Usage): string {
  return `${new Intl.NumberFormat('en-US').format(usage.inputTokens + usage.outputTokens)} tokens`;
}

/**
 * Text cut to a number of terminal cells, never through a character (an emoji counts as two).
 * yocto-spinner counts a line in UTF-16 code units, which can outnumber its cells (a family emoji
 * is 8), so the cut keeps both within the limit.
 */
function fit(text: string, cells: number): string {
  const size = (part: string) => Math.max(stringWidth(part), part.length);
  if (size(text) <= cells) {
    return text;
  }
  let cut = '';
  for (const { segment } of new Intl.Segmenter().segment(text)) {
    if (size(`${cut}${segment}…`) > cells) {
      break;
    }
    cut += segment;
  }
  return `${cut}…`;
}

/** Prints a block beside the run's guide line, each line wrapped to the terminal's width. */
function say(text: string, color: 'cyan' | 'green') {
  prompt.log.message(wrap(text, (stdout.columns || 80) - 4), { symbol: styleText(color, '◆') });
}

// The terminal's color and style codes (ESC [ … m), as styleText writes them.
const STYLE_CODES = new RegExp(`${String.fromCharCode(27)}\\[[\\d;]*m`, 'g');

/** Wraps each line at spaces, keeping its indent on the lines it wraps onto. Colors don't count. */
export function wrap(text: string, width: number): string {
  const visible = (line: string) => stripVTControlCharacters(line).length;
  return text
    .split('\n')
    .map((line) => {
      // A wrapped line sits under the text, past any list number or bullet.
      const lead =
        /^( *)((\d+\.|•|before|after ) )?/.exec(stripVTControlCharacters(line))?.[0] ?? '';
      const indent = ' '.repeat(lead.length);
      const words = line.trimStart().split(' ');
      const lines: string[] = [];
      let current = line.slice(0, line.length - line.trimStart().length) + (words.shift() ?? '');
      for (const word of words) {
        if (visible(`${current} ${word}`) > width && current.trim()) {
          // The colors in force so far carry onto the next line: the guide line resets them.
          const colors = (lines.join('') + current).match(STYLE_CODES)?.join('') ?? '';
          lines.push(`${current}\x1b[0m`);
          current = indent + colors + word;
        } else {
          current = `${current} ${word}`;
        }
      }
      lines.push(current);
      return lines.join('\n');
    })
    .join('\n');
}

/** Starts and ends the run's frame in the terminal. */
export const intro = (title: string) => prompt.intro(styleText(['bgCyan', 'black'], ` ${title} `));
export const outro = (line: string) => prompt.outro(line);
export const note = (line: string) => prompt.log.info(line);

async function decide(draft: Draft): Promise<Choice> {
  const many = draft.changes.length > 1;
  const choice = await ask(() =>
    prompt.select({
      message: 'Your call',
      options: [
        { value: 'all', label: many ? `Save all ${draft.changes.length} changes` : 'Save it' },
        ...(many ? [{ value: 'some', label: 'Pick which changes to keep' }] : []),
        { value: 'revise', label: 'Tell the agent what to change', hint: 'it tries again' },
        { value: 'skip', label: 'Skip this one', hint: 'nothing is saved' }
      ]
    })
  );
  if (choice === 'some') {
    const keep = await ask(() =>
      prompt.multiselect({
        message: 'Keep these (Space to toggle, Enter to save)',
        options: draft.changes.map((change, index) => ({
          value: index,
          label: `${index + 1}. ${plain(change.after)}`
        })),
        initialValues: draft.changes.map((_, index) => index),
        required: false
      })
    );
    return { type: 'some', keep };
  }
  if (choice === 'revise') {
    return {
      type: 'revise',
      feedback: await ask(() =>
        prompt.text({
          message: 'What should change?',
          validate: (value) => (value?.trim() ? undefined : 'Say what should change.')
        })
      )
    };
  }
  if (choice === 'skip') {
    return {
      type: 'skip',
      reason: await ask(() =>
        prompt.text({ message: 'Why? (optional, the agent reads it)', defaultValue: '' })
      )
    };
  }
  return { type: 'all' };
}

/** Waits for one prompt; Ctrl+C or Esc stops the run. */
async function ask<T>(show: () => Promise<T | symbol>): Promise<Exclude<T, symbol>> {
  const value = await show();
  if (prompt.isCancel(value)) {
    throw new Stopped('You stopped the run.');
  }
  return value as Exclude<T, symbol>;
}

/**
 * One change, numbered: the text before and after, whole, with the words that change marked (red
 * and struck through before, green after). Still readable with the colors gone, pasted elsewhere.
 */
export function showChange(change: Change, index: number): string {
  const parts = diffWordsWithSpace(change.before, change.after);
  const kept = parts.filter((part) => !part.added && !part.removed);
  const label = `${styleText(['bold', 'cyan'], `${index + 1}.`)} ${styleText('dim', change.path)}`;
  // Mostly rewritten: the old text in red and the new in green, with no marks to read through.
  if (
    kept
      .map((part) => part.value)
      .join('')
      .trim().length <
    change.after.length / 2
  ) {
    return [
      label,
      `   ${styleText('dim', 'before')} ${styleText('red', change.before)}`,
      `   ${styleText('dim', 'after ')} ${styleText('green', change.after)}`
    ].join('\n');
  }
  const side = (drop: 'added' | 'removed', mark: Parameters<typeof styleText>[0]) =>
    parts
      .filter((part) => !part[drop])
      .map((part) =>
        part.added || part.removed ? styleText(mark, part.value) : dimTags(part.value)
      )
      .join('');
  return [
    label,
    `   ${styleText('dim', 'before')} ${side('added', ['red', 'strikethrough'])}`,
    `   ${styleText('dim', 'after ')} ${side('removed', ['green', 'bold'])}`
  ].join('\n');
}

/** Rich text's HTML tags, dimmed, so the words stand out. */
const dimTags = (text: string) => text.replace(/<[^>]+>/g, (tag) => styleText('dim', tag));

/** Text with its HTML tags taken out, on one line, for a short label. */
function plain(text: string, max = 70): string {
  const flat = text
    .replace(/<[^>]+>/g, ' ')
    .replace(/\s+/g, ' ')
    .trim();
  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
}

// The agent writes Markdown. This renders it for the terminal, with a blank line after every
// paragraph and every list item, so a long answer reads as separate blocks, not a wall of text.
const terminal = new Marked({
  renderer: {
    heading({ tokens }) {
      return `${styleText(['bold', 'cyan'], this.parser.parseInline(tokens))}\n\n`;
    },
    paragraph({ tokens }) {
      return `${this.parser.parseInline(tokens)}\n\n`;
    },
    list(list: Tokens.List) {
      const start = typeof list.start === 'number' ? list.start : 1;
      return list.items
        .map((item, index) => {
          const bullet = list.ordered ? `${start + index}.` : '•';
          const body = this.parser.parse(item.tokens).trim();
          // Lines under the first are indented to sit under its text.
          const pad = ' '.repeat(bullet.length + 1);
          return `${styleText('cyan', bullet)} ${body.replace(/\n/g, `\n${pad}`)}\n\n`;
        })
        .join('');
    },
    text(token) {
      return 'tokens' in token && token.tokens ? this.parser.parseInline(token.tokens) : token.text;
    },
    strong({ tokens }) {
      return styleText('bold', this.parser.parseInline(tokens));
    },
    em({ tokens }) {
      return styleText('italic', this.parser.parseInline(tokens));
    },
    codespan({ text }) {
      return styleText('cyan', text);
    },
    code({ text }) {
      return `${styleText('cyan', text)}\n\n`;
    },
    blockquote({ tokens }) {
      return `${styleText('dim', `│ ${this.parser.parse(tokens).trim().replace(/\n/g, '\n│ ')}`)}\n\n`;
    },
    link({ href, tokens }) {
      const text = this.parser.parseInline(tokens);
      return text === href
        ? styleText('underline', href)
        : `${text} ${styleText('dim', `(${href})`)}`;
    },
    hr() {
      return `${styleText('dim', '─'.repeat(Math.min(stdout.columns || 60, 60)))}\n\n`;
    },
    br() {
      return '\n';
    },
    html({ text }) {
      return text;
    }
  }
});

/** The agent's Markdown, formatted for the terminal. */
export function markdown(text: string): string {
  return String(terminal.parse(text, { async: false })).trim();
}

import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
import { AIMessage } from '@langchain/core/messages';
import type { ChatGeneration, LLMResult } from '@langchain/core/outputs';

/**
 * Counts every model call in a run, the subagents' too: tokens read and written, and what
 * OpenRouter charged. Pass it in the run's `callbacks`; LangChain calls handleLLMEnd after each call.
 */
export class Usage extends BaseCallbackHandler {
  name = 'usage';
  calls = 0;
  inputTokens = 0;
  outputTokens = 0;
  /** In US dollars, from OpenRouter's own answer (`usage.cost`), never estimated from a price list. */
  cost = 0;
  /** Calls whose answer carried no cost (a streamed answer, or a provider that leaves it out). */
  uncosted = 0;
  /** Called after each model call, e.g. to refresh a running total on screen. */
  onCall?: () => void;

  override handleLLMEnd(output: LLMResult) {
    this.calls += 1;
    const message = (output.generations[0]?.[0] as ChatGeneration | undefined)?.message;
    const usage = AIMessage.isInstance(message) ? message.usage_metadata : undefined;
    this.inputTokens += usage?.input_tokens ?? 0;
    this.outputTokens += usage?.output_tokens ?? 0;
    const cost = output.llmOutput?.tokenUsage?.cost;
    if (typeof cost === 'number') {
      this.cost += cost;
    } else {
      this.uncosted += 1;
    }
    this.onCall?.();
  }

  /** One line: "42 model calls · 183,204 tokens in · 9,876 out · $0.0412". */
  line(): string {
    const count = new Intl.NumberFormat('en-US');
    const parts = [
      `${count.format(this.calls)} model call${this.calls === 1 ? '' : 's'}`,
      `${count.format(this.inputTokens)} tokens in`,
      `${count.format(this.outputTokens)} out`,
      `$${this.cost.toFixed(4)}`
    ];
    const line = parts.join(' · ');
    return this.uncosted > 0
      ? `${line} (${this.uncosted} call${this.uncosted === 1 ? '' : 's'} without a cost)`
      : line;
  }

  /** The run's usage, as a Markdown section for the report and its email. */
  markdown(): string {
    return `## Usage\n\n${this.line()}. The cost is what OpenRouter charged for this run.`;
  }
}

import type { SiteClient } from '@fetchski/attract-cms-sdk';
import { type Kind, previewLink } from './content.ts';
import type { SavedDraft } from './tools.ts';
import type { Usage } from './usage.ts';

/** A draft the run saved, and the private link that previews it (FAQs have no page of their own). */
export interface WaitingDraft {
  kind: Kind;
  title: string;
  link: string | null;
}

/** Every draft the run saved, each with its preview link. */
export async function draftsWaiting(
  site: SiteClient,
  saved: Map<string, SavedDraft>
): Promise<WaitingDraft[]> {
  const drafts: WaitingDraft[] = [];
  for (const [id, draft] of saved) {
    drafts.push({ ...draft, link: await previewLink(site, draft.kind, id) });
  }
  return drafts;
}

/**
 * The run's report, in Markdown: a heading, the agent's summary, the drafts waiting for you, then
 * what the run used (tokens and cost).
 */
export function reportMarkdown(
  summary: string,
  drafts: readonly WaitingDraft[],
  usage?: Usage,
  date = new Date()
) {
  // The site's host for the heading; a missing or mistyped URL still gets a report that says why.
  const site = URL.parse(process.env.FETCHSKI_ATTRACT_URL ?? '')?.host || 'your site';
  const lines = [`# One voice on ${site}, ${date.toLocaleDateString('en-CA')}`, '', summary.trim()];
  if (drafts.length > 0) {
    lines.push('', '## Drafts waiting for you', '');
    lines.push('Publish each one in the CMS when it reads right.', '');
    for (const draft of drafts) {
      const link = draft.link ? `, preview: ${draft.link}` : '';
      lines.push(`- ${draft.kind} "${draft.title}"${link}`);
    }
  }
  if (usage) {
    lines.push('', usage.markdown());
  }
  return `${lines.join('\n')}\n`;
}

import { createSiteClient } from '@fetchski/attract-cms-sdk';
import { buildAgent, modelFromEnv } from './agent.ts';
import { draftsWaiting, reportMarkdown } from './report.ts';
import { runWithOwner } from './review.ts';
import { intro, outro, Stopped, terminalOwner } from './terminal.ts';
import type { SavedDraft } from './tools.ts';
import { Usage } from './usage.ts';

// FETCHSKI_ATTRACT_URL, FETCHSKI_ATTRACT_API_KEY and FETCHSKI_ATTRACT_SIGNING_SECRET, from .env
const site = createSiteClient();

const saved = new Map<string, SavedDraft>();
const usage = new Usage();
const owner = terminalOwner(usage);
const agent = buildAgent(site, modelFromEnv(), saved, owner.step);

intro('One voice');
let summary: string;
try {
  summary = await runWithOwner(
    agent,
    'Give this whole website one voice, with me approving the voice guide and every document.',
    owner,
    usage
  );
} catch (error) {
  if (!(error instanceof Stopped)) {
    owner.failed(error);
    throw error;
  }
  // Ctrl+C at a prompt: the drafts saved so far stay drafts, and the report lists them.
  summary = 'You stopped the run before it finished.';
}

const report = reportMarkdown(summary, await draftsWaiting(site, saved), usage);
owner.report(report);
outro(`Done: ${saved.size} draft${saved.size === 1 ? '' : 's'} saved · ${usage.line()}`);

import { deepStrictEqual, ok, strictEqual } from 'node:assert';
import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { factories, fakeSite } from '@fetchski/attract-cms-sdk/testing';
import { AIMessage, type BaseMessage } from '@langchain/core/messages';
import type { LLMResult } from '@langchain/core/outputs';
import { fakeModel } from 'langchain';
import { buildAgent } from '../src/agent.ts';
import { type Choice, type Draft, nobody, type Owner, runWithOwner } from '../src/review.ts';
import type { SavedDraft } from '../src/tools.ts';
import { Usage } from '../src/usage.ts';

const PAGE_ID = 'page-about:en:draft';
const FAQ_ID = 'faq-returns:en:draft';
// A fresh memory folder, per test.
const memoryFolder = () => mkdtempSync(join(tmpdir(), 'memories-'));
const GUIDE = '# Our voice\n- Plain, warm, direct. "We" and "you".';

const STIFF = '<p>Customers are advised that returns are processed within 14 days.</p>';
const WARM = '<p>Changed your mind? Send it back within 14 days and we will sort it out.</p>';

function richText(html: string) {
  return {
    metaType: 'area',
    items: [{ _id: 'w1', metaType: 'widget', type: '@apostrophecms/rich-text', content: html }]
  };
}

// A site whose About page sounds like the owner, and whose FAQ sounds like a legal notice.
function siteWithTwoVoices() {
  return fakeSite({
    'pages.listPages': factories.ListPagesResponse({
      results: [{ id: PAGE_ID, title: 'About us', type: 'default-page' }]
    }),
    'blogPosts.listBlogs': factories.BlogList({ results: [], pages: 1, currentPage: 1 }),
    'faqItems.listFaqItems': factories.FaqItemList({
      results: [{ id: FAQ_ID, title: 'Can I return something?' }],
      pages: 1,
      currentPage: 1
    }),
    'pages.getPage': factories.Page({
      id: PAGE_ID,
      title: 'About us',
      sections: richText('<p>We fix things properly, and we tell you straight.</p>')
    }),
    'faqItems.getFaqItem': factories.FaqItem({
      id: FAQ_ID,
      title: 'Can I return something?',
      answer: richText(STIFF)
    })
  });
}

// The moves a real model would make, scripted: the main agent's, then the rewriter subagent's, then the main agent's summary.
function scriptedModel() {
  return (
    fakeModel()
      .respondWithTools([{ name: 'list_site_content', args: {} }])
      .respondWithTools([
        {
          name: 'ask_owner',
          args: { question: 'Which pages sound most like you? About us, Can I return something?' }
        }
      ])
      .respondWithTools([{ name: 'read_document', args: { kind: 'page', id: PAGE_ID } }])
      .respondWithTools([
        {
          name: 'write_file',
          args: {
            file_path: '/memories/voice-guide.md',
            content: GUIDE
          }
        }
      ])
      .respondWithTools([
        {
          name: 'ask_owner',
          args: { question: 'Here is the voice guide: … Approve it, or tell me what to change.' }
        }
      ])
      .respondWithTools([
        {
          name: 'task',
          args: {
            subagent_type: 'rewriter',
            description: `Rewrite the faq ${FAQ_ID} "Can I return something?". The guide is at /memories/voice-guide.md.`
          }
        }
      ])
      // The rewriter subagent:
      .respondWithTools([{ name: 'read_file', args: { file_path: '/memories/voice-guide.md' } }])
      .respondWithTools([{ name: 'read_document', args: { kind: 'faq', id: FAQ_ID } }])
      .respondWithTools([
        {
          name: 'save_draft_changes',
          args: {
            kind: 'faq',
            id: FAQ_ID,
            title: 'Can I return something?',
            changes: [{ path: 'answer.items.0.content', before: STIFF, after: WARM }]
          }
        }
      ])
      .respond(new AIMessage('Rewrote the answer in the guide’s voice.'))
      // The main agent again:
      .respond(new AIMessage('Rewrote 1 document; About us already fit the voice.'))
  );
}

// The person at the keyboard, scripted: their answers to questions, then their call on each draft.
function scriptedOwner(answers: string[], choices: Choice[]): Owner & { drafts: Draft[] } {
  const drafts: Draft[] = [];
  return {
    drafts,
    answer: async () => answers.shift() ?? '',
    decide: async (draft) => {
      drafts.push(draft);
      return choices.shift() ?? { type: 'skip', reason: '' };
    }
  };
}

test('agrees the voice with the owner, then saves each approved rewrite as a draft', async () => {
  const site = siteWithTwoVoices();
  const saved = new Map<string, SavedDraft>();
  const owner = scriptedOwner(['About us', 'Approved'], [{ type: 'all' }]);
  const folder = memoryFolder();

  const summary = await runWithOwner(
    buildAgent(site, scriptedModel(), saved, () => {}, { memoryFolder: folder }),
    'Give this whole website one voice.',
    owner
  );

  strictEqual(summary, 'Rewrote 1 document; About us already fit the voice.');
  site.assertCalled('faqItems.updateFaqItem', (args) => {
    deepStrictEqual(args.answer, richText(WARM));
    return args.id === FAQ_ID;
  });
  site.assertNotCalled('pages.updatePage');
  deepStrictEqual([...saved], [[FAQ_ID, { kind: 'faq', title: 'Can I return something?' }]]);
  deepStrictEqual(
    owner.drafts.map((draft) => [draft.kind, draft.title, draft.changes.length]),
    [['faq', 'Can I return something?', 1]]
  );
  strictEqual(readFileSync(join(folder, 'voice-guide.md'), 'utf8'), GUIDE);
});

test('a rewrite the owner skips is never written', async () => {
  const site = siteWithTwoVoices();
  const owner = scriptedOwner(
    ['About us', 'Approved'],
    [{ type: 'skip', reason: 'Our returns answer has to stay formal' }]
  );

  await runWithOwner(
    buildAgent(site, scriptedModel(), new Map(), () => {}, { memoryFolder: memoryFolder() }),
    'Give this whole website one voice.',
    owner
  );

  site.assertNotCalled('faqItems.updateFaqItem');
});

// The rewriter's moves for a run whose guide is already approved: one save, then whatever follows.
function rewriterModel(...after: Array<AIMessage | ((messages: BaseMessage[]) => AIMessage)>) {
  let model = fakeModel()
    .respondWithTools([{ name: 'list_site_content', args: {} }])
    .respondWithTools([
      {
        name: 'task',
        args: { subagent_type: 'rewriter', description: `Rewrite the faq ${FAQ_ID}.` }
      }
    ])
    .respondWithTools([{ name: 'read_document', args: { kind: 'faq', id: FAQ_ID } }])
    .respondWithTools([
      {
        name: 'save_draft_changes',
        args: {
          kind: 'faq',
          id: FAQ_ID,
          title: 'Can I return something?',
          changes: [
            { path: 'title', before: 'Can I return something?', after: 'Changed your mind?' },
            { path: 'answer.items.0.content', before: STIFF, after: WARM }
          ]
        }
      }
    ]);
  for (const step of after) {
    model = model.respond(step);
  }
  return model;
}

function withGuide() {
  const folder = memoryFolder();
  writeFileSync(join(folder, 'voice-guide.md'), GUIDE);
  return folder;
}

test('only the changes the owner keeps are written', async () => {
  const site = siteWithTwoVoices();
  const model = rewriterModel(
    new AIMessage('Rewrote the answer.'),
    new AIMessage('Rewrote 1 document.')
  );

  await runWithOwner(
    buildAgent(site, model, new Map(), () => {}, { memoryFolder: withGuide() }),
    'Give this whole website one voice.',
    scriptedOwner([], [{ type: 'some', keep: [1] }])
  );

  site.assertCalled('faqItems.updateFaqItem', (args) => {
    deepStrictEqual(args.answer, richText(WARM));
    strictEqual(args.title, undefined);
    return true;
  });
});

test('the owner sends a draft back with notes, and the agent revises it before it is saved', async () => {
  const site = siteWithTwoVoices();
  const SHORTER = '<p>Changed your mind? Send it back within 14 days.</p>';
  let notes = '';
  const model = rewriterModel(
    // The rewriter reads the owner's notes, then saves its revision.
    (messages) => {
      notes = String(messages.at(-1)?.content ?? '');
      return new AIMessage({
        content: '',
        tool_calls: [
          {
            id: 'revised',
            name: 'save_draft_changes',
            args: {
              kind: 'faq',
              id: FAQ_ID,
              title: 'Can I return something?',
              changes: [{ path: 'answer.items.0.content', before: STIFF, after: SHORTER }]
            }
          }
        ]
      });
    },
    new AIMessage('Rewrote the answer, shorter, as the owner asked. Rule: keep answers short.'),
    new AIMessage('Rewrote 1 document.')
  );
  const owner = scriptedOwner(
    [],
    [{ type: 'revise', feedback: 'Shorter, and keep the title' }, { type: 'all' }]
  );

  await runWithOwner(
    buildAgent(site, model, new Map(), () => {}, { memoryFolder: withGuide() }),
    'Give this whole website one voice.',
    owner
  );

  ok(notes.includes('Shorter, and keep the title'));
  strictEqual(owner.drafts.length, 2);
  site.assertCalled('faqItems.updateFaqItem', (args) => {
    deepStrictEqual(args.answer, richText(SHORTER));
    return true;
  });
});

test('two rewriters that pause at once each get their own decision', async () => {
  const OTHER_ID = 'faq-shipping:en:draft';
  const site = siteWithTwoVoices();
  // One rewriter step, for whichever rewriter asks: read its FAQ, save it, then answer.
  const rewriter = (messages: BaseMessage[]) => {
    const id = String(messages.find((message) => message.type === 'human')?.content).includes(
      OTHER_ID
    )
      ? OTHER_ID
      : FAQ_ID;
    const done = messages.filter((message) => message.type === 'tool').length;
    if (done === 0) {
      return new AIMessage({
        content: '',
        tool_calls: [{ id: `read-${id}`, name: 'read_document', args: { kind: 'faq', id } }]
      });
    }
    if (done === 1) {
      return new AIMessage({
        content: '',
        tool_calls: [
          {
            id: `save-${id}`,
            name: 'save_draft_changes',
            args: {
              kind: 'faq',
              id,
              title: id,
              changes: [{ path: 'answer.items.0.content', before: STIFF, after: WARM }]
            }
          }
        ]
      });
    }
    return new AIMessage(`Done with ${id}.`);
  };
  const model = fakeModel()
    .respondWithTools([{ name: 'list_site_content', args: {} }])
    .respondWithTools(
      [FAQ_ID, OTHER_ID].map((id) => ({
        name: 'task',
        args: { subagent_type: 'rewriter', description: `Rewrite the faq ${id}.` }
      }))
    )
    .respond(rewriter)
    .respond(rewriter)
    .respond(rewriter)
    .respond(rewriter)
    .respond(rewriter)
    .respond(rewriter)
    .respond(new AIMessage('Rewrote 1 document.'));
  // The owner saves the first draft they see and skips the second.
  const owner = scriptedOwner([], [{ type: 'all' }, { type: 'skip', reason: '' }]);

  await runWithOwner(
    buildAgent(site, model, new Map(), () => {}, { memoryFolder: withGuide() }),
    'Give this whole website one voice.',
    owner
  );

  strictEqual(owner.drafts.length, 2);
  const [first, second] = owner.drafts.map((draft) => draft.title);
  site.assertCalled('faqItems.updateFaqItem', (args) => args.id === first);
  ok(second && second !== first);
  site.assertCalledTimes('faqItems.updateFaqItem', 1);
});

test('a report-only run with no voice guide stops, and never asks or writes', async () => {
  const site = siteWithTwoVoices();
  const model = fakeModel().respond(
    new AIMessage(
      'There is no voice guide yet: run the agent at your keyboard first, with npm start.'
    )
  );

  const summary = await runWithOwner(
    buildAgent(site, model, new Map(), () => {}, {
      reportOnly: true,
      memoryFolder: memoryFolder()
    }),
    'Check every document against our voice guide.',
    nobody
  );

  strictEqual(summary.startsWith('There is no voice guide yet'), true);
  ok(model.calls[0]?.messages[0]?.text.includes('(No memory loaded)'));
  site.assertNotCalled('faqItems.updateFaqItem');
});

test('a report-only run checks the documents against the guide in its memory', async () => {
  const site = siteWithTwoVoices();
  const folder = memoryFolder();
  writeFileSync(join(folder, 'voice-guide.md'), GUIDE);
  const model = fakeModel()
    .respondWithTools([{ name: 'list_site_content', args: {} }])
    .respondWithTools([
      {
        name: 'task',
        args: {
          subagent_type: 'checker',
          description: `Check page ${PAGE_ID} "About us" and faq ${FAQ_ID} "Can I return something?".`
        }
      }
    ])
    // The checker subagent:
    .respondWithTools([{ name: 'read_file', args: { file_path: '/memories/voice-guide.md' } }])
    .respondWithTools([
      { name: 'read_document', args: { kind: 'page', id: PAGE_ID } },
      { name: 'read_document', args: { kind: 'faq', id: FAQ_ID } }
    ])
    .respond(
      new AIMessage(
        'page "About us": fits\nfaq "Can I return something?": drifts, stiff: "Customers are advised"'
      )
    )
    // The main agent again:
    .respond(new AIMessage('## Can I return something?\nStiff: "Customers are advised". 1 fits.'));

  const summary = await runWithOwner(
    buildAgent(site, model, new Map(), () => {}, { reportOnly: true, memoryFolder: folder }),
    'Check every document against our voice guide.',
    nobody
  );

  strictEqual(summary, '## Can I return something?\nStiff: "Customers are advised". 1 fits.');
  // The guide was in the agent's instructions from the start: its long-term memory.
  ok(model.calls[0]?.messages[0]?.text.includes(GUIDE));
  site.assertCalled('faqItems.getFaqItem', (args) => args.id === FAQ_ID);
  site.assertNotCalled('faqItems.updateFaqItem');
});

test('usage adds up tokens and the cost OpenRouter reports for each call', () => {
  const usage = new Usage();
  const call = (input: number, output: number, cost?: number) =>
    usage.handleLLMEnd({
      generations: [
        [
          {
            text: '',
            message: new AIMessage({
              content: '',
              usage_metadata: {
                input_tokens: input,
                output_tokens: output,
                total_tokens: input + output
              }
            })
          }
        ]
      ],
      // OpenRouter's own `usage` object, as ChatOpenRouter passes it on.
      llmOutput: { tokenUsage: cost === undefined ? {} : { cost } }
    } as unknown as LLMResult);
  call(1000, 200, 0.0012);
  call(3000, 50, 0.0021);
  call(10, 5);

  strictEqual(
    usage.line(),
    '3 model calls · 4,010 tokens in · 255 out · $0.0033 (1 call without a cost)'
  );
  ok(usage.markdown().startsWith('## Usage\n\n3 model calls'));
});

test("a run's usage counts the subagents' model calls too", async () => {
  const site = siteWithTwoVoices();
  const usage = new Usage();
  const used = (message: AIMessage) => {
    message.usage_metadata = { input_tokens: 100, output_tokens: 10, total_tokens: 110 };
    return message;
  };
  const model = fakeModel()
    .respond(
      used(
        new AIMessage({
          content: '',
          tool_calls: [
            {
              id: 't',
              name: 'task',
              args: { subagent_type: 'rewriter', description: `Rewrite the faq ${FAQ_ID}.` }
            }
          ]
        })
      )
    )
    // The rewriter subagent:
    .respond(used(new AIMessage('It already fits.')))
    // The main agent again:
    .respond(used(new AIMessage('Rewrote 0 documents.')));

  await runWithOwner(
    buildAgent(site, model, new Map(), () => {}, { memoryFolder: withGuide() }),
    'Give this whole website one voice.',
    scriptedOwner([], []),
    usage
  );

  strictEqual(usage.calls, 3);
  strictEqual(usage.inputTokens, 300);
  strictEqual(usage.outputTokens, 30);
});