DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"use client";
import { createContext, useContext, useMemo, type ReactNode } from "react";
import { fromMarkdown } from "mdast-util-from-markdown";
import type { MessageAttachment } from "@/features/chat/ChatStateAdapter";
import { docIconFor } from "@/lib/doc-attachments";
import type { StreamEvent } from "@/features/chat/model/protocol";
/**
* Inline file links. The model refers to a file it generated by writing its
* exact filename in plain prose (e.g. "…saved as DeepTutor_Introduction.pdf");
* a remark plugin (``makeFileLinkRemarkPlugin``) turns each occurrence of a
* known generated filename into a clickable link, and clicking it opens the
* file in the Viewer — the same action as the card under the message (which
* still renders). Codex-style: the filename in the text becomes a live link.
*
* The plugin emits a normal markdown link with the reserved ``attachment:``
* scheme; the renderers' ``a`` component intercepts it (``parseAttachmentHref``)
* and renders a compact ``InlineFileCard``. The href survives the markdown URL
* sanitizer only because ``attachment`` is allow-listed in
* ``SAFE_MARKDOWN_PROTOCOL_REGEX`` (lib/markdown-display.ts), and these links
* are never emitted as navigable anchors, so allowing the scheme is safe.
*/
const ATTACHMENT_HREF_PREFIX = "attachment:";
function decode(raw: string): string {
try {
return decodeURIComponent(raw.trim());
} catch {
return raw.trim();
}
}
/** The target filename of an ``attachment:NAME`` href, or null if this href is
* not a file reference. */
export function parseAttachmentHref(href?: string): string | null {
if (!href || !href.startsWith(ATTACHMENT_HREF_PREFIX)) return null;
const name = decode(href.slice(ATTACHMENT_HREF_PREFIX.length));
return name || null;
}
// ---------------------------------------------------------------------------
// Generated-file collection (shared by the provider and the message's card
// block). Persisted ``generated`` attachments merged with artifacts streamed
// live in ``tool_result`` events, deduped by URL.
// ---------------------------------------------------------------------------
export function extractStreamedArtifacts(
events?: StreamEvent[],
): MessageAttachment[] {
const out: MessageAttachment[] = [];
for (const ev of events ?? []) {
if (ev.type !== "tool_result") continue;
const meta = (ev.metadata ?? {}) as {
tool_metadata?: {
workspace_items?: Array<{
workspace_id?: string;
workspace_item_id?: string;
relative_path?: string;
filename?: string;
url?: string;
mime_type?: string;
size_bytes?: number;
sha256?: string;
title?: string;
caption?: string;
generated?: boolean;
}>;
artifacts?: Array<{
filename?: string;
url?: string;
mime_type?: string;
size_bytes?: number;
}>;
};
};
const workspaceItems = meta.tool_metadata?.workspace_items ?? [];
for (const item of workspaceItems) {
if (!item?.url || !item.workspace_item_id) continue;
out.push({
type: item.mime_type?.startsWith("image/") ? "image" : "document",
filename: item.filename,
url: item.url,
mime_type: item.mime_type,
size_bytes: item.size_bytes,
generated: item.generated ?? true,
origin: "workspace",
workspace_id: item.workspace_id,
workspace_item_id: item.workspace_item_id,
relative_path: item.relative_path,
sha256: item.sha256,
title: item.title,
caption: item.caption,
});
}
if (workspaceItems.length) continue;
for (const a of meta.tool_metadata?.artifacts ?? []) {
if (!a?.url) continue;
out.push({
type: a.mime_type?.startsWith("image/") ? "image" : "document",
filename: a.filename,
url: a.url,
mime_type: a.mime_type,
size_bytes: a.size_bytes,
generated: true,
});
}
}
return out;
}
export function mergeGeneratedFiles(
attachments: MessageAttachment[],
events?: StreamEvent[],
): MessageAttachment[] {
const persisted = attachments.filter(
(a) => a.generated || a.origin === "workspace",
);
const seen = new Set(persisted.map((a) => a.url).filter(Boolean));
const merged = [...persisted];
for (const a of extractStreamedArtifacts(events)) {
if (a.url && seen.has(a.url)) continue;
if (a.url) seen.add(a.url);
merged.push(a);
}
return merged;
}
// ---------------------------------------------------------------------------
// remark plugin: linkify exact filename mentions in prose.
// ---------------------------------------------------------------------------
// mdast node types whose text must NOT be linkified (code, existing links,
// math). Filenames inside these are shown verbatim.
const SKIP_NODE_TYPES = new Set([
"code",
"inlineCode",
"link",
"linkReference",
"definition",
"math",
"inlineMath",
"html",
]);
const NAME_CHAR = /[A-Za-z0-9]/;
function boundaryOk(text: string, start: number, len: number): boolean {
const before = text[start - 1];
const after = text[start + len];
// Don't match inside a larger token/path: reject an alphanumeric, '.', '/'
// or '\' immediately before, or an alphanumeric right after the extension.
if (
before &&
(NAME_CHAR.test(before) ||
before === "." ||
before === "/" ||
before === "\\")
) {
return false;
}
if (after && NAME_CHAR.test(after)) return false;
return true;
}
/**
* Build a remark plugin that wraps every plain-text occurrence of a known
* generated filename in an ``attachment:`` link. Matches the exact filename
* and a separator-normalized variant (``_``/``-`` ⇄ space), longest first.
* Returns null when there are no filenames and relative-link fallback is off.
*/
export function makeFileLinkRemarkPlugin(
files: MessageAttachment[],
unresolvedRelativeLinksAsText = false,
) {
const entries: Array<{ needle: string; name: string }> = [];
const seen = new Set<string>();
for (const file of files) {
const name =
file.origin === "workspace" ? file.relative_path : file.filename;
if (!name) continue;
const variants =
file.origin === "workspace"
? new Set([name, `./${name}`])
: new Set([name, name.replace(/[_-]+/g, " ")]);
for (const needle of variants) {
const key = `${needle}\u0000${name}`;
if (needle && !seen.has(key)) {
seen.add(key);
entries.push({ needle, name });
}
}
}
if (!entries.length && !unresolvedRelativeLinksAsText) return null;
// Prefer the most specific (longest) needle when several could match.
entries.sort((a, b) => b.needle.length - a.needle.length);
// Resolve model-written links against published attachments. Full paths win;
// filenames and presentation titles are accepted only when unique within
// this message. The model may mistype a directory even when the file was
// published correctly, so never navigate to that untrusted relative path.
const exactPaths = new Map<string, string>();
const aliases = new Map<string, string | null>();
const surfaceKeys = (surface: string) =>
new Set([surface.trim(), surface.trim().toLowerCase()]);
const addExactPath = (surface: string, name: string) => {
for (const key of surfaceKeys(surface)) {
if (key) exactPaths.set(key, name);
}
};
const addAlias = (surface: string, name: string) => {
for (const key of surfaceKeys(surface)) {
if (!key) continue;
const previous = aliases.get(key);
if (previous === undefined) aliases.set(key, name);
else if (previous !== name) aliases.set(key, null);
}
};
const baseName = (s: string) => s.split(/[\\/]/).pop() ?? s;
for (const file of files) {
const target =
file.origin === "workspace" ? file.relative_path : file.filename;
if (!target) continue;
addExactPath(target, target);
addExactPath(`./${target}`, target);
addAlias(baseName(target), target);
if (file.origin === "workspace") {
if (file.title) addAlias(file.title, target);
} else {
addAlias(target.replace(/[_-]+/g, " "), target);
}
}
const lookupSurface = (s: string): string | undefined =>
exactPaths.get(s.trim()) ??
exactPaths.get(s.trim().toLowerCase()) ??
aliases.get(s.trim()) ??
aliases.get(s.trim().toLowerCase()) ??
undefined;
const linkLabel = (node: Record<string, unknown>): string => {
const parts: string[] = [];
const walk = (n: Record<string, unknown> | undefined) => {
if (!n) return;
if (n.type === "text" && typeof n.value === "string") parts.push(n.value);
const kids = n.children as Array<Record<string, unknown>> | undefined;
if (Array.isArray(kids)) kids.forEach(walk);
};
(node.children as Array<Record<string, unknown>> | undefined)?.forEach(
walk,
);
return parts.join("");
};
// A model-written link points at one of our files when its url basename or
// its label is a known filename — return the real filename to link to.
const linkTargetFile = (
node: Record<string, unknown>,
): string | undefined => {
const url = typeof node.url === "string" ? node.url : "";
if (url.startsWith(ATTACHMENT_HREF_PREFIX)) return undefined; // already ours
// Only model-written relative paths may be repaired by a filename or
// label. An external URL can share a basename with a generated file.
if (/^[a-z][a-z\d+.-]*:/i.test(url) || url.startsWith("//")) {
return undefined;
}
if (url.startsWith("#") || url.startsWith("?")) return undefined;
if (url.startsWith("/")) {
const file = files.find((item) => item.url === decode(url));
return file?.origin === "workspace" ? file.relative_path : file?.filename;
}
return (
lookupSurface(decode(url)) ??
lookupSurface(decode(baseName(url))) ??
lookupSurface(linkLabel(node))
);
};
const splitText = (value: string): Array<Record<string, unknown>> => {
const nodes: Array<Record<string, unknown>> = [];
let i = 0;
while (i < value.length) {
let hit: { idx: number; needle: string; name: string } | null = null;
for (const e of entries) {
const idx = value.indexOf(e.needle, i);
if (idx === -1 || !boundaryOk(value, idx, e.needle.length)) continue;
if (
!hit ||
idx < hit.idx ||
(idx === hit.idx && e.needle.length > hit.needle.length)
) {
hit = { idx, needle: e.needle, name: e.name };
}
}
if (!hit) {
nodes.push({ type: "text", value: value.slice(i) });
break;
}
if (hit.idx > i) {
nodes.push({ type: "text", value: value.slice(i, hit.idx) });
}
nodes.push({
type: "link",
url: `${ATTACHMENT_HREF_PREFIX}${encodeURIComponent(hit.name)}`,
title: null,
children: [{ type: "text", value: hit.needle }],
});
i = hit.idx + hit.needle.length;
}
return nodes;
};
const visit = (
node: Record<string, unknown>,
definitions: Map<string, Record<string, unknown>>,
): void => {
const children = node.children as
| Array<Record<string, unknown>>
| undefined;
if (!Array.isArray(children)) return;
const out: Array<Record<string, unknown>> = [];
for (let child of children) {
if (
unresolvedRelativeLinksAsText &&
(child.type === "linkReference" || child.type === "imageReference")
) {
const definition = definitions.get(String(child.identifier).toUpperCase());
if (definition) {
child = {
...child,
type: child.type === "linkReference" ? "link" : "image",
url: definition.url,
title: definition.title,
};
}
}
if (child.type === "text" && typeof child.value === "string") {
out.push(...splitText(child.value));
} else if (child.type === "link" || child.type === "image") {
// The model often writes the file as a link itself, e.g.
// `[name.pdf](name.pdf)` or `` — a
// broken relative target that would navigate. Redirect it to the
// published snapshot instead. Don't recurse (keep its label/alt).
const real = linkTargetFile(child);
if (real) {
child.url = `${ATTACHMENT_HREF_PREFIX}${encodeURIComponent(real)}`;
} else if (
unresolvedRelativeLinksAsText &&
!/^(?:[a-z][a-z\d+.-]*:|\/|#|\?)/i.test(String(child.url ?? ""))
) {
// Archive file paths without a published snapshot must not navigate.
out.push(
...(child.type === "image"
? [{ type: "text", value: String(child.alt ?? "") }]
: ((child.children as Record<string, unknown>[] | undefined) ?? [])),
);
continue;
}
out.push(child);
} else {
if (!SKIP_NODE_TYPES.has(child.type as string)) visit(child, definitions);
out.push(child);
}
}
node.children = out;
};
return () => (tree: Record<string, unknown>) => {
const definitions = new Map<string, Record<string, unknown>>();
const collectDefinitions = (node: Record<string, unknown>): void => {
// mdast already normalizes identifiers; match mdast-to-hast's case fold.
const id = String(node.identifier).toUpperCase();
if (node.type === "definition" && !definitions.has(id)) definitions.set(id, node);
for (const child of (node.children as Record<string, unknown>[] | undefined) ?? []) {
collectDefinitions(child);
}
};
if (unresolvedRelativeLinksAsText) collectDefinitions(tree);
visit(tree, definitions);
};
}
/** Files with no visible inline link in the rendered Markdown. Reuse the
* renderer's remark transform so code examples never hide a download card. */
export function unlinkedGeneratedFiles(
content: string,
files: MessageAttachment[],
): MessageAttachment[] {
if (!files.length) return [];
const tree = fromMarkdown(content) as unknown as Record<string, unknown>;
makeFileLinkRemarkPlugin(files)?.()(tree);
const linked = new Set<string>();
const visit = (node: Record<string, unknown>): void => {
if (node.type === "link" || node.type === "image") {
const name = parseAttachmentHref(node.url as string | undefined);
if (name) {
const matching = files.filter(
(file) =>
(file.origin === "workspace" ? file.relative_path : file.filename) ===
name,
);
if (matching.length === 1 && matching[0].url) {
linked.add(matching[0].url);
}
}
return;
}
for (const child of (node.children as Record<string, unknown>[] | undefined) ?? []) {
visit(child);
}
};
visit(tree);
return files.filter((file) => !file.url || !linked.has(file.url));
}
// ---------------------------------------------------------------------------
// Context + provider + the inline link component.
// ---------------------------------------------------------------------------
interface InlineFileCardValue {
files: MessageAttachment[];
resolve: (name: string) => MessageAttachment | undefined;
onOpen?: (attachment: MessageAttachment) => void;
unresolvedRelativeLinksAsText: boolean;
}
const InlineFileCardContext = createContext<InlineFileCardValue | null>(null);
export function useInlineFileCardContext(): InlineFileCardValue | null {
return useContext(InlineFileCardContext);
}
const norm = (name: string): string => name.trim().toLowerCase();
const basename = (name: string): string => name.split(/[\\/]/).pop() ?? name;
/**
* Scoped per assistant message: supplies the renderers' filename-linkify plugin
* and the inline links with the message's generated files + open callback.
* Without a provider (book chat, co-writer, …) the plugin sees no files and
* ``attachment:`` links fall back to plain text, so the generic renderers stay
* generic.
*/
export function InlineFileCardProvider({
attachments,
events,
onOpen,
unresolvedRelativeLinksAsText = false,
children,
}: {
attachments: MessageAttachment[];
events?: StreamEvent[];
onOpen?: (attachment: MessageAttachment) => void;
unresolvedRelativeLinksAsText?: boolean;
children: ReactNode;
}) {
const files = useMemo(
() => mergeGeneratedFiles(attachments, events),
[attachments, events],
);
const value = useMemo<InlineFileCardValue>(() => {
const exact = new Map<string, MessageAttachment>();
const lower = new Map<string, MessageAttachment>();
const base = new Map<string, MessageAttachment>();
for (const file of files) {
const name =
file.origin === "workspace" ? file.relative_path : file.filename;
if (!name) continue;
if (!exact.has(name)) exact.set(name, file);
if (!lower.has(norm(name))) lower.set(norm(name), file);
if (file.origin !== "workspace") {
if (!base.has(norm(basename(name)))) base.set(norm(basename(name)), file);
}
}
const resolve = (name: string): MessageAttachment | undefined => {
const direct = exact.get(name) ?? lower.get(norm(name));
if (direct) return direct;
return base.get(norm(basename(name)));
};
return { files, resolve, onOpen, unresolvedRelativeLinksAsText };
}, [files, onOpen, unresolvedRelativeLinksAsText]);
return (
<InlineFileCardContext.Provider value={value}>
{children}
</InlineFileCardContext.Provider>
);
}
/**
* Renders an ``attachment:NAME`` link as a compact, clickable file chip
* (icon + filename) that opens the file in the Viewer. Falls back to plain text
* when the name can't be resolved (no provider, or the file no longer exists),
* so a stray reference is never a broken link.
*/
export function InlineFileCard({
name,
fallback,
}: {
name: string;
fallback?: ReactNode;
}) {
const ctx = useContext(InlineFileCardContext);
const attachment = ctx?.resolve(name);
if (!attachment) {
return <>{fallback ?? name}</>;
}
const filename = attachment.filename || name;
const spec = docIconFor(filename);
const Icon = spec.Icon;
return (
<button
type="button"
onClick={ctx?.onOpen ? () => ctx.onOpen?.(attachment) : undefined}
className="inline-flex max-w-full items-center gap-1 align-baseline rounded-md px-1 py-0.5 font-medium text-[var(--primary)] underline decoration-[var(--primary)]/40 underline-offset-2 transition-colors hover:bg-[var(--primary)]/5 hover:decoration-[var(--primary)]"
>
<Icon className={`h-[14px] w-[14px] shrink-0 ${spec.tint}`} />
<span className="truncate">{filename}</span>
</button>
);
}
/** Render a Markdown image that points at a published workspace item.
*
* The model only knows the item's relative workspace path. The remark plugin
* rewrites that path to ``attachment:...`` and this component resolves the
* opaque, authenticated snapshot URL. Clicking the image uses the same
* Preview Drawer action as a file card, so Markdown never gets a raw internal
* download URL.
*/
export function InlineWorkspaceImage({
name,
alt,
className,
}: {
name: string;
alt?: string;
className?: string;
}) {
const ctx = useContext(InlineFileCardContext);
const attachment = ctx?.resolve(name);
if (!attachment?.url) return <>{alt || attachment?.filename || name}</>;
const image = (
// Authenticated workspace snapshots use opaque runtime URLs, so Next's
// build-time image optimizer cannot resolve them.
// eslint-disable-next-line @next/next/no-img-element
<img
src={attachment.url}
alt={alt || attachment.title || attachment.filename || name}
loading="lazy"
className={className}
/>
);
if (!ctx?.onOpen) return image;
return (
<button
type="button"
onClick={() => ctx.onOpen?.(attachment)}
className="inline-block max-w-full cursor-zoom-in text-left"
aria-label={`Open ${attachment.filename || name}`}
>
{image}
</button>
);
}