Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
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),
});
}