Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

28.4 KB
Raw Blame
import { stripChatQuoteMarkerLines } from './chatQuotes.js';
import { allDeepLinkSchemes } from './brandIdentity.js';

/** Stable cross-client marker for a retryable local Codex resume preflight. */
export const CODEX_RESUME_NOT_READY_MARKER = '[CODEX_RESUME_NOT_READY]';

/** Readable fallback for older clients that do not yet localize the marker. */
export const CODEX_RESUME_NOT_READY_WIRE_MESSAGE =
  `${CODEX_RESUME_NOT_READY_MARKER} Codex can't resume this task right now. Try again shortly.`;

/** Keep host diagnostics out of projections while letting each client localize the error. */
export function isCodexResumeNotReadyProjectionError(error: string): boolean {
  return error.includes(CODEX_RESUME_NOT_READY_MARKER);
}

/** Maximum copied target-message text kept in one Composer reference. */
export const AGENT_MESSAGE_REFERENCE_MAX_CHARS = 12_000;

/** Common source range for a structured Composer reference. */
interface AgentInputReferenceBase {
  /** Offsets in the persisted/wire `text`, before quote-marker projection. */
  start: number;
  end: number;
  /** Cindy deep link retained only as stable location metadata. */
  href: string;
}

/** One message-anchor chip and the readable target message it represents. */
export interface AgentInputMessageReference extends AgentInputReferenceBase {
  kind: 'message';
  sessionId: string;
  messageClientId: string;
  /** Readable target body. Main may hydrate this before queue acceptance. */
  text?: string;
  truncated?: boolean;
}

/** One whole-session chip. It identifies a conversation; it does not imply transcript import. */
export interface AgentInputSessionReference extends AgentInputReferenceBase {
  kind: 'session';
  sessionId: string;
  title?: string;
}

/** One project chip with the decoded filesystem location. */
export interface AgentInputProjectReference extends AgentInputReferenceBase {
  kind: 'project';
  name: string;
  workingDir: string;
}

/** One live tab in Cindy's built-in browser for the current task. */
export interface AgentInputBrowserTabReference extends AgentInputReferenceBase {
  kind: 'browser-tab';
  tabId: string;
  title?: string;
  url: string;
}

/** One currently open operating-system application window. */
export interface AgentInputDesktopWindowReference extends AgentInputReferenceBase {
  kind: 'desktop-window';
  windowId: number;
  pid: number;
  appName: string;
  title?: string;
}

/** One opaque business object selected from an explicitly scoped Plugin search. */
export interface AgentInputPluginResourceReference extends AgentInputReferenceBase {
  kind: 'plugin-resource';
  ghostId: string;
  tool: string;
  resourceId: string;
  pluginName: string;
  label: string;
  description?: string;
}

/** One persistent Cindy Bot selected as the intended delegation or handoff target. */
export interface AgentInputBotReference extends AgentInputReferenceBase {
  kind: 'bot';
  botId: string;
  name: string;
  /** Ephemeral state added by Main when the queued input is accepted. */
  hostSnapshot?: AgentInputBotHostSnapshot;
}

/** One of the teammate's own Todo items, quoted by its owner from the teammate's 近况 panel. */
export interface AgentInputTodoReference extends AgentInputReferenceBase {
  kind: 'todo';
  botId: string;
  todoId: string;
  title: string;
}

export interface AgentInputBotHostSnapshot {
  availability: 'ready' | 'degraded' | 'failed' | 'unverified' | 'unavailable';
  activity: 'working' | 'idle' | 'unknown';
  activeDelegations: number;
  /** Bounded host diagnosis; never raw capability or transcript data. */
  reason?: string;
}

/** Structured Composer references preserved beside the human-facing wire text. */
export type AgentInputReference =
  | AgentInputMessageReference
  | AgentInputSessionReference
  | AgentInputProjectReference
  | AgentInputBrowserTabReference
  | AgentInputDesktopWindowReference
  | AgentInputPluginResourceReference
  | AgentInputBotReference
  | AgentInputTodoReference;

/** Immutable inputs required to derive the text sent to semantic consumers. */
export interface AgentFacingTextSource {
  text: string;
  quotesEncoded?: boolean;
  agentReferences?: readonly AgentInputReference[];
}

/** Bounded readable message text plus an explicit truncation bit. */
export interface BoundedAgentReferenceText {
  text: string;
  truncated: boolean;
}

/** Keep message-reference payloads bounded without using the compact UI label. */
export function boundAgentReferenceText(
  value: string,
  cap = AGENT_MESSAGE_REFERENCE_MAX_CHARS,
): BoundedAgentReferenceText {
  const text = value.trim();
  if (text.length <= cap) return { text, truncated: false };
  return { text: text.slice(0, cap), truncated: true };
}

/** Stable identity of one quoted message across the composer and the session-reference resolver. */
export function agentInputMessageReferenceKey(sessionId: string, messageClientId: string): string {
  return `${sessionId}\u0000${messageClientId}`;
}

/**
 * Messages whose body already reaches the model verbatim inside the user
 * message. The quoted-history payload must not deliver those bodies a second
 * time: a duplicate copy spends the shared quote budget and can arrive
 * trimmed, so the model would see the same message twice — once complete,
 * once mutilated.
 */
export function collectInlineMessageReferenceKeys(
  references: readonly AgentInputReference[] | undefined,
): Set<string> {
  const keys = new Set<string>();
  for (const reference of references ?? []) {
    if (reference.kind !== 'message') continue;
    // No inline body, or a body that was cut at the reference cap: the quote
    // still has to carry the message.
    if (!reference.text?.trim()) continue;
    if (reference.truncated === true) continue;
    keys.add(agentInputMessageReferenceKey(reference.sessionId, reference.messageClientId));
  }
  return keys;
}

function nonEmptyString(value: unknown): value is string {
  return typeof value === 'string' && value.length > 0;
}

function stripDeepLinkPrefix(
  href: string,
  route:
    | 'session/' | 'project/' | 'browser-tab/' | 'desktop-window/' | 'plugin-resource/' | 'bot/'
    | 'bot-todo/',
): string | null {
  for (const scheme of allDeepLinkSchemes()) {
    const prefix = `${scheme}://${route}`;
    if (href.startsWith(prefix)) return href.slice(prefix.length);
  }
  return null;
}

export function buildBotReferenceHref(botId: string): string {
  const scheme = allDeepLinkSchemes()[0];
  return `${scheme}://bot/${encodeURIComponent(botId)}`;
}

export function parseBotReferenceHref(href: string): { botId: string } | null {
  const rest = stripDeepLinkPrefix(href, 'bot/');
  if (rest === null || rest.length > 256 || rest.includes('/') || rest.includes('?') || rest.includes('#')) {
    return null;
  }
  const botId = decodeBoundedComponent(rest, 128);
  if (!botId || botId.includes('/') || /[\u0000-\u001f\u007f\u2028\u2029]/.test(botId)) return null;
  return { botId };
}

export function buildPluginResourceReferenceHref(args: {
  ghostId: string;
  tool: string;
  resourceId: string;
}): string {
  const scheme = allDeepLinkSchemes()[0];
  const strictEncode = (value: string) => encodeURIComponent(value)
    .replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
  return `${scheme}://plugin-resource/${strictEncode(args.ghostId)}/${strictEncode(args.tool)}/${strictEncode(args.resourceId)}`;
}

export function parsePluginResourceReferenceHref(
  href: string,
): { ghostId: string; tool: string; resourceId: string } | null {
  const rest = stripDeepLinkPrefix(href, 'plugin-resource/');
  if (rest === null || rest.length > 1_500 || rest.includes('?') || rest.includes('#')) return null;
  const [rawGhostId, rawTool, rawResourceId, ...extra] = rest.split('/');
  if (extra.length > 0) return null;
  const ghostId = decodeBoundedComponent(rawGhostId, 32);
  const tool = decodeBoundedComponent(rawTool, 64);
  const resourceId = decodeBoundedComponent(rawResourceId, 256);
  if (
    !ghostId
    || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(ghostId)
    || !tool
    || !/^[a-z][a-z0-9_-]{0,63}$/.test(tool)
    || !resourceId
    || /[\u0000-\u001f\u007f\u2028\u2029]/.test(resourceId)
  ) return null;
  return { ghostId, tool, resourceId };
}

function decodeBoundedComponent(value: string, maxLength: number): string | null {
  try {
    const decoded = decodeURIComponent(value);
    return decoded && decoded.length <= maxLength ? decoded : null;
  } catch {
    return null;
  }
}

function queryValue(query: string, key: string, maxLength: number): string | null {
  for (const pair of query.split('&')) {
    const equalsIndex = pair.indexOf('=');
    if (equalsIndex <= 0 || pair.slice(0, equalsIndex) !== key) continue;
    return decodeBoundedComponent(pair.slice(equalsIndex + 1), maxLength);
  }
  return null;
}

export function parseBrowserTabReferenceHref(
  href: string,
): { tabId: string; url: string } | null {
  const rest = stripDeepLinkPrefix(href, 'browser-tab/');
  if (rest === null || rest.length > 5_000) return null;
  const hashIndex = rest.indexOf('#');
  const withoutHash = hashIndex >= 0 ? rest.slice(0, hashIndex) : rest;
  const queryIndex = withoutHash.indexOf('?');
  if (queryIndex <= 0) return null;
  const tabId = decodeBoundedComponent(withoutHash.slice(0, queryIndex), 256);
  const url = queryValue(withoutHash.slice(queryIndex + 1), 'url', 4_096);
  if (!tabId || !url) return null;
  try {
    const protocol = new URL(url).protocol;
    return protocol === 'http:' || protocol === 'https:' ? { tabId, url } : null;
  } catch {
    return null;
  }
}

export function parseDesktopWindowReferenceHref(
  href: string,
): { pid: number; windowId: number; appName: string } | null {
  const rest = stripDeepLinkPrefix(href, 'desktop-window/');
  if (rest === null || rest.length > 1_000) return null;
  const hashIndex = rest.indexOf('#');
  const withoutHash = hashIndex >= 0 ? rest.slice(0, hashIndex) : rest;
  const queryIndex = withoutHash.indexOf('?');
  if (queryIndex <= 0) return null;
  const [rawPid, rawWindowId, ...extra] = withoutHash.slice(0, queryIndex).split('/');
  if (extra.length > 0) return null;
  const pid = Number(rawPid);
  const windowId = Number(rawWindowId);
  const appName = queryValue(withoutHash.slice(queryIndex + 1), 'app', 200);
  if (
    !Number.isSafeInteger(pid)
    || pid <= 0
    || !Number.isSafeInteger(windowId)
    || windowId < 0
    || !appName
  ) return null;
  return { pid, windowId, appName };
}

/** Remove a trailing slash run in one linear pass over untrusted deep-link input. */
function stripTrailingSlashes(value: string): string {
  let end = value.length;
  while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
  return end === value.length ? value : value.slice(0, end);
}

function parseSessionHref(
  href: string,
): { sessionId: string; messageClientId: string | null } | null {
  const rest = stripDeepLinkPrefix(href, 'session/');
  if (rest === null) return null;
  const hashIndex = rest.indexOf('#');
  const withoutHash = hashIndex >= 0 ? rest.slice(0, hashIndex) : rest;
  const queryIndex = withoutHash.indexOf('?');
  const rawSessionId = stripTrailingSlashes(
    queryIndex >= 0 ? withoutHash.slice(0, queryIndex) : withoutHash
  );
  if (!rawSessionId) return null;
  let sessionId: string;
  try {
    sessionId = decodeURIComponent(rawSessionId);
  } catch {
    return null;
  }
  if (!sessionId) return null;
  let messageClientId: string | null = null;
  if (queryIndex >= 0) {
    const query = withoutHash.slice(queryIndex + 1);
    for (const pair of query.split('&')) {
      const equalsIndex = pair.indexOf('=');
      if (equalsIndex <= 0 || pair.slice(0, equalsIndex) !== 'message') continue;
      const rawMessageClientId = pair.slice(equalsIndex + 1);
      if (!rawMessageClientId) break;
      try {
        messageClientId = decodeURIComponent(rawMessageClientId) || null;
      } catch {
        messageClientId = null;
      }
      break;
    }
  }
  return { sessionId, messageClientId };
}

export function buildTodoReferenceHref(botId: string, todoId: string): string {
  const scheme = allDeepLinkSchemes()[0];
  return `${scheme}://bot-todo/${encodeURIComponent(botId)}/${encodeURIComponent(todoId)}`;
}

export function parseTodoReferenceHref(href: string): { botId: string; todoId: string } | null {
  const rest = stripDeepLinkPrefix(href, 'bot-todo/');
  if (rest === null || rest.length > 512 || rest.includes('?') || rest.includes('#')) return null;
  const [rawBotId, rawTodoId, ...extra] = rest.split('/');
  if (extra.length > 0 || !rawBotId || !rawTodoId) return null;
  const botId = decodeBoundedComponent(rawBotId, 128);
  const todoId = decodeBoundedComponent(rawTodoId, 128);
  const invalid = (value: string | null) =>
    !value || value.includes('/') || /[\u0000-\u001f\u007f\u2028\u2029]/.test(value);
  if (invalid(botId) || invalid(todoId)) return null;
  return { botId: botId!, todoId: todoId! };
}

function parseProjectHref(href: string): { workingDir: string } | null {
  const rest = stripDeepLinkPrefix(href, 'project/');
  if (rest === null) return null;
  const hashIndex = rest.indexOf('#');
  const withoutHash = hashIndex >= 0 ? rest.slice(0, hashIndex) : rest;
  const queryIndex = withoutHash.indexOf('?');
  const rawWorkingDir = stripTrailingSlashes(
    queryIndex >= 0 ? withoutHash.slice(0, queryIndex) : withoutHash
  );
  if (!rawWorkingDir) return null;
  try {
    const workingDir = decodeURIComponent(rawWorkingDir);
    return workingDir ? { workingDir } : null;
  } catch {
    return null;
  }
}

function referenceSpanMatchesHref(span: string, href: string): boolean {
  return span === href || (
    span.startsWith('[')
    && span.endsWith(`](${href})`)
  );
}

function readReference(
  value: unknown,
  sourceText: string,
): AgentInputReference | null {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
  const candidate = value as Record<string, unknown>;
  if (
    !Number.isSafeInteger(candidate.start)
    || !Number.isSafeInteger(candidate.end)
    || !nonEmptyString(candidate.href)
  ) return null;
  const start = candidate.start as number;
  const end = candidate.end as number;
  if (start < 0 || end <= start || end > sourceText.length) return null;
  // The metadata must still point at the exact persisted deep-link span. This
  // rejects stale offsets after arbitrary queue edits instead of replacing
  // unrelated user text with a semantic block.
  if (!referenceSpanMatchesHref(sourceText.slice(start, end), candidate.href)) return null;

  if (candidate.kind === 'message') {
    const target = parseSessionHref(candidate.href);
    if (!target?.messageClientId) return null;
    return {
      kind: 'message',
      start,
      end,
      href: candidate.href,
      sessionId: target.sessionId,
      messageClientId: target.messageClientId,
      ...(typeof candidate.text === 'string' ? { text: candidate.text } : {}),
      ...(candidate.truncated === true ? { truncated: true } : {}),
    };
  }
  if (candidate.kind === 'session') {
    const target = parseSessionHref(candidate.href);
    if (!target || target.messageClientId) return null;
    return {
      kind: 'session',
      start,
      end,
      href: candidate.href,
      sessionId: target.sessionId,
      ...(nonEmptyString(candidate.title) ? { title: candidate.title } : {}),
    };
  }
  if (candidate.kind === 'project' && nonEmptyString(candidate.name)) {
    const target = parseProjectHref(candidate.href);
    if (!target) return null;
    return {
      kind: 'project',
      start,
      end,
      href: candidate.href,
      name: candidate.name,
      workingDir: target.workingDir,
    };
  }
  if (candidate.kind === 'browser-tab') {
    const target = parseBrowserTabReferenceHref(candidate.href);
    if (!target) return null;
    return {
      kind: 'browser-tab',
      start,
      end,
      href: candidate.href,
      tabId: target.tabId,
      url: target.url,
      ...(nonEmptyString(candidate.title) ? { title: candidate.title } : {}),
    };
  }
  if (candidate.kind === 'desktop-window') {
    const target = parseDesktopWindowReferenceHref(candidate.href);
    if (!target) return null;
    return {
      kind: 'desktop-window',
      start,
      end,
      href: candidate.href,
      windowId: target.windowId,
      pid: target.pid,
      appName: target.appName,
      ...(nonEmptyString(candidate.title) ? { title: candidate.title } : {}),
    };
  }
  if (
    candidate.kind === 'plugin-resource'
    && nonEmptyString(candidate.pluginName)
    && candidate.pluginName.length <= 128
    && nonEmptyString(candidate.label)
    && candidate.label.length <= 128
  ) {
    const target = parsePluginResourceReferenceHref(candidate.href);
    if (!target) return null;
    return {
      kind: 'plugin-resource',
      start,
      end,
      href: candidate.href,
      ...target,
      pluginName: oneLine(candidate.pluginName),
      label: oneLine(candidate.label),
      ...(nonEmptyString(candidate.description) && candidate.description.length <= 256
        ? { description: oneLine(candidate.description) }
        : {}),
    };
  }
  if (
    candidate.kind === 'bot'
    && nonEmptyString(candidate.name)
    && candidate.name.length <= 128
  ) {
    const target = parseBotReferenceHref(candidate.href);
    if (!target) return null;
    const hostSnapshot = readBotHostSnapshot(candidate.hostSnapshot);
    return {
      kind: 'bot',
      start,
      end,
      href: candidate.href,
      botId: target.botId,
      name: oneLine(candidate.name),
      ...(hostSnapshot ? { hostSnapshot } : {}),
    };
  }
  if (candidate.kind === 'todo') return readTodoReference(candidate, start, end);
  return null;
}

function readTodoReference(
  candidate: Record<string, unknown>,
  start: number,
  end: number,
): AgentInputTodoReference | null {
  if (!nonEmptyString(candidate.title) || candidate.title.length > 300) return null;
  const target = parseTodoReferenceHref(candidate.href as string);
  if (!target) return null;
  return {
    kind: 'todo',
    start,
    end,
    href: candidate.href as string,
    botId: target.botId,
    todoId: target.todoId,
    title: oneLine(candidate.title),
  };
}

function readBotHostSnapshot(value: unknown): AgentInputBotHostSnapshot | null {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
  const candidate = value as Record<string, unknown>;
  const availability = typeof candidate.availability === 'string'
    ? candidate.availability
    : '';
  const activity = typeof candidate.activity === 'string' ? candidate.activity : '';
  const activeDelegations = candidate.activeDelegations;
  if (
    !['ready', 'degraded', 'failed', 'unverified', 'unavailable'].includes(availability)
    || !['working', 'idle', 'unknown'].includes(activity)
    || !Number.isSafeInteger(activeDelegations)
    || (activeDelegations as number) < 0
    || (activeDelegations as number) > 10_000
  ) return null;
  const reason = typeof candidate.reason === 'string'
    ? oneLine(candidate.reason).slice(0, 240)
    : '';
  return {
    availability: availability as AgentInputBotHostSnapshot['availability'],
    activity: activity as AgentInputBotHostSnapshot['activity'],
    activeDelegations: activeDelegations as number,
    ...(reason ? { reason } : {}),
  };
}

/** Validate untrusted persisted/remote reference metadata against its wire text. */
export function readAgentInputReferences(
  value: unknown,
  sourceText: string,
): AgentInputReference[] {
  if (!Array.isArray(value)) return [];
  const references = value
    .map((candidate) => readReference(candidate, sourceText))
    .filter((candidate): candidate is AgentInputReference => candidate !== null)
    .sort((left, right) => left.start - right.start || left.end - right.end);
  const nonOverlapping: AgentInputReference[] = [];
  let previousEnd = 0;
  for (const reference of references) {
    if (reference.start < previousEnd) continue;
    nonOverlapping.push(reference);
    previousEnd = reference.end;
  }
  return nonOverlapping;
}

function oneLine(value: string): string {
  return value.replace(/\s+/g, ' ').trim();
}

function quotedMetadata(value: string): string {
  return JSON.stringify(value)
    .replace(/\[/g, '\\u005b')
    .replace(/\]/g, '\\u005d')
    .replace(/\u2028/g, '\\u2028')
    .replace(/\u2029/g, '\\u2029');
}

function formatReference(reference: AgentInputReference): string {
  if (reference.kind === 'message') {
    const bounded = boundAgentReferenceText(reference.text ?? '');
    const truncated = reference.truncated === true || bounded.truncated;
    return [
      '[Referenced message]',
      `Session ID: ${quotedMetadata(reference.sessionId)}`,
      `Message ID: ${quotedMetadata(reference.messageClientId)}`,
      'Content:',
      bounded.text || '(message content unavailable)',
      ...(truncated ? ['[Content truncated]'] : []),
      '[/Referenced message]',
    ].join('\n');
  }
  if (reference.kind === 'session') {
    return [
      '[Referenced conversation]',
      `Title: ${quotedMetadata(oneLine(reference.title ?? '') || `Conversation ${reference.sessionId}`)}`,
      `Session ID: ${quotedMetadata(reference.sessionId)}`,
      '[/Referenced conversation]',
    ].join('\n');
  }
  if (reference.kind === 'browser-tab') {
    return [
      '[Referenced browser tab]',
      `Title: ${quotedMetadata(oneLine(reference.title ?? '') || reference.url)}`,
      `URL: ${quotedMetadata(reference.url)}`,
      `Tab ID: ${quotedMetadata(reference.tabId)}`,
      '[/Referenced browser tab]',
    ].join('\n');
  }
  if (reference.kind === 'desktop-window') {
    return [
      '[Referenced desktop window]',
      `Title: ${quotedMetadata(oneLine(reference.title ?? '') || reference.appName)}`,
      `Application: ${quotedMetadata(oneLine(reference.appName))}`,
      `PID: ${reference.pid}`,
      `Window ID: ${reference.windowId}`,
      '[/Referenced desktop window]',
    ].join('\n');
  }
  if (reference.kind === 'plugin-resource') {
    return [
      '[Referenced plugin resource]',
      `Plugin: ${quotedMetadata(oneLine(reference.pluginName))} (${reference.ghostId})`,
      `Resource ID: ${quotedMetadata(reference.resourceId)}`,
      `Label: ${quotedMetadata(oneLine(reference.label))}`,
      ...(reference.description
        ? [`Summary: ${quotedMetadata(oneLine(reference.description))}`]
        : []),
      `Search tool: ${reference.tool}`,
      'Resolution: call the search tool with query equal to the Resource ID.',
      '[/Referenced plugin resource]',
    ].join('\n');
  }
  if (reference.kind === 'bot') {
    const snapshot = reference.hostSnapshot;
    return [
      '[Referenced Cindy Bot]',
      `Name: ${quotedMetadata(oneLine(reference.name))}`,
      `Bot ID: ${quotedMetadata(reference.botId)}`,
      'Intent: the user explicitly selected this Bot as a collaboration target.',
      'Resolution: the host already resolved this exact stable Bot ID. Do not list Bots, search chat history, or inspect another task runtime merely to identify or locate it.',
      ...(snapshot
        ? [
            `Host status: availability=${snapshot.availability}; activity=${snapshot.activity}; active_tracked_tasks=${snapshot.activeDelegations}.`,
            ...(snapshot.reason ? [`Host note: ${quotedMetadata(snapshot.reason)}`] : []),
          ]
        : [
            "Host status: not refreshed. Do not invent availability or activity.",
          ]),
      "Action: infer intent from the surrounding request. Answer status questions from Host status without sending a new message. To contact this teammate, call send_to_agent once with this Bot ID. For independently tracked work or deliverables, use start_session_task instead; it does not target a Bot.",
      "Boundary: Do not blindly forward the surrounding user text. A teammate message only confirms delivery and must never stand in for a tracked task.",
      '[/Referenced Cindy Bot]',
    ].join('\n');
  }
  if (reference.kind === 'todo') {
    return [
      '[Referenced todo]',
      `Title: ${quotedMetadata(oneLine(reference.title))}`,
      `Todo ID: ${quotedMetadata(reference.todoId)}`,
      'Owner: the user picked this item from your own Todo list; the surrounding text says what to do with it.',
      'Resolution: read it with list_teammate_todos and record any change with update_teammate_todo using this exact Todo ID. Do not create a new item for it.',
      '[/Referenced todo]',
    ].join('\n');
  }
  return [
    '[Referenced project]',
    `Name: ${quotedMetadata(oneLine(reference.name))}`,
    `Working directory: ${quotedMetadata(reference.workingDir)}`,
    '[/Referenced project]',
  ].join('\n');
}

function projectLiteralText(text: string, quotesEncoded: boolean): string {
  return quotesEncoded ? stripChatQuoteMarkerLines(text) : text;
}

/**
 * Derive immutable agent-facing text from Composer wire data.
 *
 * The persisted text remains untouched. Quote markers are removed only when
 * their persisted flag is true, while structured reference spans are replaced
 * in source order with readable semantic blocks.
 */
export function projectAgentFacingText(source: AgentFacingTextSource): string {
  const references = readAgentInputReferences(source.agentReferences, source.text);
  const stripMarkers = source.quotesEncoded === true;
  if (references.length === 0) return projectLiteralText(source.text, stripMarkers);

  const parts: string[] = [];
  let cursor = 0;
  for (const reference of references) {
    parts.push(projectLiteralText(source.text.slice(cursor, reference.start), stripMarkers));
    parts.push(formatReference(reference));
    cursor = reference.end;
  }
  parts.push(projectLiteralText(source.text.slice(cursor), stripMarkers));
  return parts.join('');
}

/**
 * 只取用户自己写下的正文:引用 span 被整段剔除(而不是像
 * {@link projectAgentFacingText} 那样替换成 `[Referenced ...]` 语义块),引用块
 * marker 行按 quotesEncoded 剥离。
 *
 * 用途是判定「这条消息里有没有真正可用于起名的文字」。会话/项目引用展开后的
 * 语义块是给模型看的机器格式,既不该出现在标题里,也不该被当成"用户打了字"
 * 的证据 —— 拿它去起名会得到 `[Referenced conversation] Title: ...` 这种标题,
 * 或让标题模型对着一坨元数据硬编。
 *
 * 注意:选中文字引用(blockquote)的正文**会**保留 —— 那是真实文字内容,可以
 * 起出有意义的标题。
 */
export function projectLiteralUserText(source: AgentFacingTextSource): string {
  const references = readAgentInputReferences(source.agentReferences, source.text);
  const stripMarkers = source.quotesEncoded === true;
  if (references.length === 0) return projectLiteralText(source.text, stripMarkers).trim();

  const parts: string[] = [];
  let cursor = 0;
  for (const reference of references) {
    parts.push(projectLiteralText(source.text.slice(cursor, reference.start), stripMarkers));
    cursor = reference.end;
  }
  parts.push(projectLiteralText(source.text.slice(cursor), stripMarkers));
  return parts.join('').trim();
}

/** 被引用对象的可读名字(会话标题 / 项目名 / 被引用消息正文)。取不到 → null。 */
export function describeAgentInputReference(reference: AgentInputReference): string | null {
  if (reference.kind === 'session') return oneLine(reference.title ?? '') || null;
  if (reference.kind === 'project') return oneLine(reference.name) || null;
  if (reference.kind === 'browser-tab') return oneLine(reference.title ?? reference.url) || null;
  if (reference.kind === 'desktop-window') {
    return oneLine(reference.title ?? reference.appName) || null;
  }
  if (reference.kind === 'plugin-resource') return oneLine(reference.label) || null;
  if (reference.kind === 'bot') return oneLine(reference.name) || null;
  if (reference.kind === 'todo') return oneLine(reference.title) || null;
  return oneLine(reference.text ?? '') || null;
}

/**
 * Project the persisted `{text, quotesEncoded, agentReferences}` envelope.
 * Returns null for non-user/unknown shapes so callers can keep their existing
 * assistant/tool extraction logic.
 */
export function projectPersistedAgentFacingUserText(content: unknown): string | null {
  let value = content;
  if (typeof value === 'string') {
    if (!value || (value[0] !== '{' && value[0] !== '[')) return null;
    try {
      value = JSON.parse(value);
    } catch {
      return null;
    }
  }
  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
  const record = value as Record<string, unknown>;
  if (typeof record.text !== 'string') return null;
  return projectAgentFacingText({
    text: record.text,
    quotesEncoded: record.quotesEncoded === true,
    agentReferences: readAgentInputReferences(record.agentReferences, record.text),
  });
}