mioku-plugin-agent 0.1.0

package/core/media.ts

@@ -0,0 +1,170 @@
+import type { Message, MessageEvent, MultimodalContentItem } from "mioku";
+import type { AgentHost } from "../types";
+import { readImageDataUrl, toFileUrl, type DownloadedMedia } from "./download";
+
+export type MediaKind = "image" | "file" | "video" | "record";
+
+export interface MediaAttachment {
+  kind: MediaKind;
+  messageId: string;
+  name?: string;
+  size?: number;
+  url?: string;
+  file?: string;
+  path?: string;
+  fileId?: string;
+  userId?: string;
+  groupId?: string;
+}
+
+const MEDIA_KINDS: readonly string[] = ["image", "file", "video", "record"];
+
+function pickString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function pickNumber(value: unknown): number | undefined {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function extractMediaFromMessage(
+  message: Message | undefined,
+  messageId: string,
+  context: { userId?: string; groupId?: string } = {},
+): MediaAttachment[] {
+  const items: MediaAttachment[] = [];
+  for (const segment of message ?? []) {
+    if (!MEDIA_KINDS.includes(segment.type)) continue;
+    const data = segment.data ?? {};
+    const attachment = segment.attachment;
+    items.push({
+      kind: segment.type as MediaKind,
+      messageId,
+      userId: context.userId,
+      groupId: context.groupId,
+      name:
+        pickString(data.name) ??
+        pickString(data.file_name) ??
+        pickString(data.file_unique) ??
+        pickString(attachment?.name),
+      size:
+        pickNumber(data.size) ?? pickNumber(data.file_size) ?? attachment?.size,
+      url: pickString(data.url) ?? pickString(attachment?.url),
+      file: pickString(data.file) ?? pickString(attachment?.file),
+      path: pickString(data.path),
+      fileId:
+        pickString(data.file_id) ??
+        pickString(data.fid) ??
+        pickString(data.fileId),
+    });
+  }
+  return items;
+}
+
+export function extractMedia(event: MessageEvent): MediaAttachment[] {
+  return extractMediaFromMessage(
+    event.message,
+    String(event.message_id ?? ""),
+    {
+      userId: event.user_id ? String(event.user_id) : undefined,
+      groupId: event.group_id ? String(event.group_id) : undefined,
+    },
+  );
+}
+
+export function formatMediaNote(
+  downloads: DownloadedMedia[],
+  errors: string[] = [],
+): string {
+  if (downloads.length === 0 && errors.length === 0) return "";
+  const lines = downloads.map(
+    (item, index) =>
+      `- [${index + 1}] message_id=${item.messageId || "unknown"} name=${item.name} [${toFileUrl(item.path)}]`,
+  );
+  lines.push(...errors.map((error) => `- download failed: ${error}`));
+  return [
+    "[Attached files] all saved on disk (images are also attached to this message):",
+    ...lines,
+  ].join("\n");
+}
+
+export async function describeImageFile(
+  host: AgentHost,
+  filePath: string,
+): Promise<string> {
+  const resolved = host.resolveModel();
+  const vision = resolved?.vision ?? resolved?.instance;
+  const visionModel = resolved?.visionModel || resolved?.model || "";
+  if (!vision) return "(vision model unavailable)";
+
+  let dataUrl: string;
+  try {
+    dataUrl = await readImageDataUrl(filePath);
+  } catch (err) {
+    return `(failed to read image: ${err})`;
+  }
+
+  const content: MultimodalContentItem[] = [
+    {
+      type: "text",
+      text: "Describe this image in detail, including any visible text, UI elements and data.",
+    },
+    { type: "image_url", image_url: { url: dataUrl, detail: "auto" } },
+  ];
+  const response = await vision.complete({
+    model: visionModel,
+    messages: [
+      {
+        role: "system",
+        content:
+          "You are an image analysis assistant. Describe the image clearly and objectively in 2-6 sentences. Transcribe any visible text accurately.",
+      },
+      { role: "user", content },
+    ],
+    temperature: 0.3,
+  });
+  return response.content?.trim() || "(no description returned)";
+}
+
+export async function describeImageUrls(
+  host: AgentHost,
+  urls: string[],
+): Promise<string> {
+  const resolved = host.resolveModel();
+  const vision = resolved?.vision ?? resolved?.instance;
+  const visionModel = resolved?.visionModel || resolved?.model || "";
+  if (!vision || urls.length === 0) return "";
+  const content: MultimodalContentItem[] = [
+    {
+      type: "text",
+      text: "Describe the attached image(s) from a chat message in 2-4 sentences. Transcribe any visible text.",
+    },
+    ...urls.map(
+      (url): MultimodalContentItem => ({
+        type: "image_url",
+        image_url: { url, detail: "auto" },
+      }),
+    ),
+  ];
+  try {
+    const response = await vision.complete({
+      model: visionModel,
+      messages: [
+        {
+          role: "system",
+          content:
+            "You are an image analysis assistant. Describe the image clearly and objectively.",
+        },
+        { role: "user", content },
+      ],
+      temperature: 0.3,
+    });
+    return response.content?.trim() || "";
+  } catch (err) {
+    host.logger.warn(`[agent] image describe failed: ${err}`);
+    return "";
+  }
+}

package/core/prompt.ts

@@ -0,0 +1,214 @@
+import type {
+  AgentBaseConfig,
+  AgentSettingsConfig,
+  ChatEmotionConfig,
+} from "../types";
+import type { FsPolicy } from "../tools/perm";
+
+const LEVEL_LINES: Record<string, string> = {
+  "read-only":
+    "Permission level: read-only. File writes are impossible; every bash command requires the user's explicit approval in the chat.",
+  "workspace-write":
+    "Permission level: workspace-write. File tools may only write inside the workspace; every bash command requires the user's explicit approval in the chat.",
+  auto: "Permission level: auto. File tools and bash run without asking first, but every bash command is reviewed by the working model and genuinely destructive ones still require the user's approval in the chat.",
+  full: "Permission level: full access. File tools and bash commands run without approval and are NOT sandboxed — be careful with destructive operations.",
+  yolo: "Permission level: yolo. Everything runs unsandboxed and without approval, and the user is NOT shown any intermediate notices — only your final reply reaches them. Be extra careful with destructive operations.",
+};
+
+function currentTimeLine(): string {
+  const now = new Date();
+  const pad = (value: number) => String(value).padStart(2, "0");
+  const days = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+  ];
+  return `${now.getFullYear()}/${pad(now.getMonth() + 1)}/${pad(now.getDate())} ${pad(now.getHours())}:00 (${days[now.getDay()]}, hour precision)`;
+}
+
+function buildEmotionSection(
+  emotion: ChatEmotionConfig | null,
+  currentEmotion: string,
+): string {
+  if (!emotion) return "";
+  const available = Array.from(
+    new Set([
+      "default",
+      ...Object.keys(emotion.emotions ?? {}).map((name) =>
+        name.trim().toLowerCase(),
+      ),
+    ]),
+  ).filter(Boolean);
+  const defaultEmotion = emotion.defaultEmotion || "default";
+  const current = available.includes(currentEmotion)
+    ? currentEmotion
+    : defaultEmotion;
+  const currentExamples = emotion.emotions?.[current]?.examples ?? [];
+  const fallbackExamples = emotion.emotions?.[defaultEmotion]?.examples ?? [];
+  const examples = (
+    currentExamples.length > 0 ? currentExamples : fallbackExamples
+  ).slice(0, 6);
+  const lines = [
+    "## Emotion State",
+    `Current emotion: ${current || "default"}`,
+    available.length > 0 ? `Available emotions: ${available.join(", ")}` : "",
+    "You may switch your emotion state by writing [emotion:name] on its own line; the marker is removed before the message is sent. Use it sparingly, when the emotion genuinely shifts. Nothing else changes it, so it stays until you switch it.",
+  ];
+  if (examples.length > 0) {
+    lines.push(
+      "For examples of responses to the current emotion, refer to their tone and speech characteristics.",
+      "Imitate their tone and speaking style, including sentence length, pauses inside sentences, and punctuation use:",
+      ...examples.map((example) => `- ${example}`),
+    );
+  }
+  return lines.filter(Boolean).join("\n");
+}
+
+export interface SystemPromptOptions {
+  persona: string;
+  replyStyle: string;
+  base: AgentBaseConfig;
+  settings: AgentSettingsConfig;
+  policy: FsPolicy;
+  currentEmotion: string;
+  emotion: ChatEmotionConfig | null;
+  toolNames: string[];
+  goal?: string;
+  plan?: Array<{ content: string; status: string }>;
+}
+
+export function buildSystemPrompt(options: SystemPromptOptions): string {
+  const {
+    persona,
+    replyStyle,
+    base,
+    settings,
+    policy,
+    currentEmotion,
+    emotion,
+    toolNames,
+    goal,
+    plan,
+  } = options;
+  const sections: string[] = [];
+
+  // Persona comes from the chat plugin's personalization config. When chat is
+  // absent there is no persona section at all, only the agent framing.
+  const personaText = persona.trim();
+  sections.push(
+    [
+      "## Identity",
+      ...(personaText ? [personaText, ""] : []),
+      "You are running as a personal agent: the user talks to you in a private chat and you complete tasks end-to-end with tools, like a coding/OS agent but conversational.",
+    ].join("\n"),
+  );
+
+  const styleText = replyStyle.trim();
+  if (styleText) {
+    sections.push(
+      [
+        "## Speaking Style",
+        "Long-term stable tone, read from the chat plugin's personalization settings. Keep it across every reply:",
+        styleText,
+      ].join("\n"),
+    );
+  }
+
+  sections.push(
+    [
+      "## Output Rules",
+      "- Your final text reply is delivered to the user. Output only the reply itself; never output your thinking process or narrate tool calls.",
+      "- Plain text output must NOT contain Markdown syntax.",
+      "- When the reply genuinely needs rich structure (code, tables, tutorials, long technical explanations), wrap that part in exactly <MARKDOWN> ... </MARKDOWN>. The block is rendered into an image; inside it there is no length limit and Markdown syntax is expected.",
+      "- Reach for a <MARKDOWN> block whenever the answer is table-like or list-like, or whenever you catch yourself laying out three or more parallel items with newlines, dashes or numbering; use it for two or more parallel items when each one carries more than a few words. It is also the right place for any code, path list, or long technical write-up.",
+      "- Put a <MARKDOWN> block on its own paragraph, with nothing else on the same line as the opening or closing tag. You may send plain-text lines before and after it, and more than one <MARKDOWN> block per reply is fine when it reads better.",
+      "- [emotion:name] on its own line switches your emotion state (see Emotion State). No other markers exist; do not invent any.",
+      "- To quote a chat message, put [reply:message_id] alone on the first line of your reply. The marker is removed and the message that follows quotes that message; use it when the user should see which message you are answering.",
+    ].join("\n"),
+  );
+
+  const toolLines: string[] = [
+    "## Tools",
+    "- Use tools proactively to complete tasks and verify facts instead of guessing. Chain multiple tool calls when needed.",
+    `Available tools: ${toolNames.join(", ")}.`,
+    "- File paths may be absolute or relative to the workspace. Relative paths are preferred.",
+  ];
+  if (settings.bash.enabled) {
+    toolLines.push(
+      policy.level === "full"
+        ? "- bash runs unsandboxed with full access; avoid destructive commands unless the user explicitly asked for them."
+        : policy.level === "auto"
+          ? "- bash runs without asking first, but the working model reviews every command and destructive ones still need the user's approval."
+          : "- bash requires in-chat user approval per command; batch related work into a single well-formed command instead of many tiny ones, and continue the task once approval is granted.",
+      "- Always pass `purpose` to bash: one short line saying what the command does and why; it is shown to the user with the command.",
+    );
+  }
+  if (settings.webSearch.enabled) {
+    toolLines.push(
+      `- web_search is limited to about ${settings.webSearch.maxSearchCount} searches per conversation; stop searching and answer from what you have after 2-3 failed attempts.`,
+    );
+  }
+  if (settings.webFetch.enabled && settings.webSearch.enabled) {
+    toolLines.push(
+      "- web_fetch reads a known URL directly; use web_search first when you need to discover sources.",
+    );
+  }
+  toolLines.push(
+    "- send_file/send_image deliver local files to the user; mention what you sent in one short line.",
+  );
+  toolLines.push(
+    "- view_image opens a local image file (screenshot, downloaded photo) so you can see it; use it whenever the answer depends on what an image actually shows.",
+  );
+  if (base.permissionLevel === "yolo") {
+    toolLines.push(
+      "- This mode hides every command/tool notice from the user: only your final reply is delivered, so make it complete, self-contained and free of tool narration.",
+    );
+  }
+  sections.push(toolLines.join("\n"));
+
+  sections.push(
+    [
+      "## Environment",
+      `Current time: ${currentTimeLine()}`,
+      "Chat type: private chat with the user.",
+      `Workspace: ${policy.workspaceRoot}`,
+      LEVEL_LINES[base.permissionLevel] ?? LEVEL_LINES["workspace-write"],
+    ].join("\n"),
+  );
+
+  const emotionSection = buildEmotionSection(emotion, currentEmotion);
+  if (emotionSection) sections.push(emotionSection);
+
+  if (goal?.trim()) {
+    sections.push(
+      [
+        "## Session Goal",
+        goal.trim(),
+        "This goal was set by the user for the current session. Work toward it across turns; it stays until the user clears or replaces it.",
+      ].join("\n"),
+    );
+  }
+  if (plan && plan.length > 0) {
+    const marker: Record<string, string> = {
+      pending: "[ ]",
+      in_progress: "[~]",
+      completed: "[x]",
+    };
+    sections.push(
+      [
+        "## Current Plan",
+        ...plan.map(
+          (item, index) =>
+            `${index + 1}. ${marker[item.status] ?? "[ ]"} ${item.content}`,
+        ),
+        "Keep this plan up to date with the todo_write tool as you make progress: mark items in_progress before starting and completed when done.",
+      ].join("\n"),
+    );
+  }
+
+  return sections.join("\n\n");
+}

package/core/risk.ts

@@ -0,0 +1,61 @@
+import type { AgentHost } from "../types";
+import { extractJsonObject } from "../utils/json";
+
+export interface RiskVerdict {
+  dangerous: boolean;
+  reason: string;
+}
+
+const REVIEWER_PROMPT = `You are a safety reviewer for shell commands an AI agent wants to run on the user's machine.
+
+dangerous=true (the user must approve first) for anything irreversible, destructive or outside the workspace: deleting/moving/overwriting files or directories (rm, rmdir, mv, shred, truncate, mass globs), dropping or truncating databases, wiping data/cache, git push/force push/reset --hard/clean -fd, killing processes, restarting services, changing system or network config, installing/removing system packages, sudo.
+
+dangerous=false for ordinary development work: read-only inspection (ls, cat, head, grep, find, ps, df, git status/diff/log), reading or creating files, writing inside the workspace, running tests/builds/linters, starting local dev servers.
+
+Answer with JSON only: {"dangerous": true|false, "reason": "one short sentence"}`;
+
+export async function assessCommandRisk(
+  host: AgentHost,
+  command: string,
+  purpose: string,
+): Promise<RiskVerdict> {
+  const resolved = host.resolveModel();
+  const reviewer = resolved?.working ?? resolved?.instance;
+  const model = resolved?.workingModel || resolved?.model || "";
+  if (!reviewer) {
+    return { dangerous: true, reason: "no reviewer model available" };
+  }
+
+  try {
+    const response = await reviewer.complete({
+      model,
+      messages: [
+        { role: "system", content: REVIEWER_PROMPT },
+        {
+          role: "user",
+          content: `Command:\n${command}\n\nStated purpose: ${purpose || "(none)"}`,
+        },
+      ],
+      temperature: 0,
+      max_tokens: 200,
+    });
+    const parsed = extractJsonObject<{ dangerous?: unknown; reason?: unknown }>(
+      response.content || "",
+    );
+    if (!parsed || typeof parsed.dangerous !== "boolean") {
+      return {
+        dangerous: true,
+        reason: "reviewer returned an unusable verdict",
+      };
+    }
+    return {
+      dangerous: parsed.dangerous,
+      reason:
+        String(parsed.reason ?? "").trim() ||
+        (parsed.dangerous ? "flagged by the reviewer model" : ""),
+    };
+  } catch (err) {
+    host.logger.warn(`[agent] command risk review failed: ${err}`);
+    return { dangerous: true, reason: `review failed: ${err}` };
+  }
+}

package/core/send.ts

@@ -0,0 +1,131 @@
+import type { Bot, MessageSegment } from "mioku";
+import type { AgentHost } from "../types";
+import { sendImageSource } from "./attachment";
+import {
+  cleanEmotionMarkers,
+  consumeCompleteStreamUnits,
+  createThinkTagStreamFilter,
+  extractReplyMarker,
+  extractStandaloneMarkdownBlock,
+  splitOutgoingUnits,
+} from "./units";
+
+const MAX_MESSAGE_CHARS = 1200;
+
+function splitLongText(text: string): string[] {
+  if (text.length <= MAX_MESSAGE_CHARS) return [text];
+  const chunks: string[] = [];
+  let rest = text;
+  while (rest.length > MAX_MESSAGE_CHARS) {
+    let cut = rest.lastIndexOf("\n", MAX_MESSAGE_CHARS);
+    if (cut < MAX_MESSAGE_CHARS * 0.5) cut = MAX_MESSAGE_CHARS;
+    chunks.push(rest.slice(0, cut).trim());
+    rest = rest.slice(cut).trim();
+  }
+  if (rest) chunks.push(rest);
+  return chunks.filter(Boolean);
+}
+
+export class TurnSender {
+  private streamBuffer = "";
+  private thinkFilter = createThinkTagStreamFilter();
+  private quoteId: string | null = null;
+  streamedText = "";
+  sentCount = 0;
+
+  constructor(
+    private host: AgentHost,
+    private bot: Bot | undefined,
+    private userId: number,
+    private enableScreenshot: boolean,
+  ) {}
+
+  /** 当前待用的引用段：只有本轮的**第一条**消息带引用，发送成功后才消费掉。 */
+  private quoteSegments(): MessageSegment[] {
+    return this.quoteId ? [this.host.ctx.segment.reply(this.quoteId)] : [];
+  }
+
+  private async deliverText(text: string): Promise<void> {
+    const trimmed = text.trim();
+    if (!trimmed || trimmed === "---") return;
+    if (!this.bot) return;
+    const chunks = splitLongText(trimmed);
+    for (const [index, chunk] of chunks.entries()) {
+      const segments = index === 0 ? this.quoteSegments() : [];
+      segments.push(this.host.ctx.segment.text(chunk));
+      await this.bot.sendMessage(
+        { type: "private", user_id: this.userId },
+        segments,
+      );
+      if (index === 0) this.quoteId = null;
+      this.sentCount += 1;
+    }
+  }
+
+  private async deliverUnit(unit: string): Promise<void> {
+    const cleaned = cleanEmotionMarkers(unit);
+    const { text, replyTo } = extractReplyMarker(cleaned.text);
+    if (replyTo) this.quoteId = replyTo;
+    if (!text) return;
+    this.streamedText = this.streamedText
+      ? `${this.streamedText}\n${text}`
+      : text;
+    const markdown = extractStandaloneMarkdownBlock(text);
+    if (markdown && this.enableScreenshot && this.host.screenshot && this.bot) {
+      try {
+        const imagePath = await this.host.screenshot.screenshotMarkdown(markdown);
+        if (imagePath) {
+          const sent = await sendImageSource(
+            this.host.ctx,
+            this.bot,
+            { type: "private", user_id: this.userId },
+            imagePath,
+            this.quoteSegments(),
+          );
+          if (sent) {
+            this.quoteId = null;
+            this.sentCount += 1;
+            return;
+          }
+        }
+      } catch (err) {
+        this.host.logger.warn(`[agent] markdown screenshot failed: ${err}`);
+      }
+    }
+    await this.deliverText(markdown ?? text);
+  }
+
+  async sendText(text: string): Promise<void> {
+    for (const unit of splitOutgoingUnits(text)) {
+      await this.deliverUnit(unit);
+    }
+  }
+
+  async onDelta(delta: string): Promise<void> {
+    this.streamBuffer += this.thinkFilter.push(delta, false);
+    await this.flush(false);
+  }
+
+  private async flush(force: boolean): Promise<void> {
+    while (true) {
+      const { units, rest } = consumeCompleteStreamUnits(this.streamBuffer, force);
+      if (units.length === 0) {
+        this.streamBuffer = rest;
+        break;
+      }
+      this.streamBuffer = rest;
+      for (const unit of units) {
+        await this.deliverUnit(unit);
+      }
+      if (!force) break;
+    }
+  }
+
+  async finishStream(fullText: string): Promise<void> {
+    this.streamBuffer += this.thinkFilter.push("", true);
+    await this.flush(true);
+    if (this.sentCount === 0 && fullText.trim()) {
+      await this.sendText(fullText);
+    }
+  }
+}

package/core/session.ts

@@ -0,0 +1,58 @@
+import type { AgentDatabase, AgentSessionRow } from "../db";
+
+export class SessionManager {
+  constructor(private db: AgentDatabase) {}
+
+  generation(userId: number): number {
+    return this.db.getUserGeneration(userId);
+  }
+
+  sessionId(userId: number): string {
+    return `agent:${userId}:g${this.generation(userId)}`;
+  }
+
+  get(userId: number): AgentSessionRow {
+    return this.db.getOrCreateSession(this.sessionId(userId), userId);
+  }
+
+  newSession(userId: number): AgentSessionRow {
+    this.db.bumpUserGenerationTo(userId, this.db.maxGeneration(userId) + 1);
+    return this.get(userId);
+  }
+
+  resume(userId: number, generation: number): AgentSessionRow | undefined {
+    const target = this.db.getSessionByGeneration(userId, generation);
+    if (!target) return undefined;
+    this.db.bumpUserGenerationTo(userId, generation);
+    return this.db.getOrCreateSession(target.sessionId, userId);
+  }
+
+  resumableSessions(userId: number, excludeSessionId: string): AgentSessionRow[] {
+    return this.db
+      .listSessions(userId, { archived: false })
+      .filter((session) => session.sessionId !== excludeSessionId);
+  }
+
+  archive(userId: number, generation: number): AgentSessionRow | undefined {
+    const target = this.db.getSessionByGeneration(userId, generation);
+    if (!target) return undefined;
+    this.db.setSessionMeta(target.sessionId, { archived: true });
+    return this.db.getSessionByGeneration(userId, generation);
+  }
+
+  reset(userId: number): void {
+    this.db.resetSession(this.sessionId(userId));
+  }
+
+  history(session: AgentSessionRow) {
+    return this.db.getMessagesAfter(session.sessionId, session.summaryUpTo);
+  }
+
+  append(userId: number, role: "user" | "assistant", content: string): number {
+    return this.db.appendMessage(this.sessionId(userId), role, content);
+  }
+
+  setEmotion(userId: number, emotion: string): void {
+    this.db.setSessionMeta(this.sessionId(userId), { emotion });
+  }
+}

package/core/title.ts

@@ -0,0 +1,52 @@
+import type { AgentHost } from "../types";
+
+const TITLE_MAX_CHARS = 40;
+const TITLE_MAX_MESSAGES = 20;
+
+function fallbackTitle(
+  messages: Array<{ role: string; content: string }>,
+): string {
+  const firstUser = messages.find((message) => message.role === "user");
+  const text = (firstUser?.content ?? "").replace(/\s+/g, " ").trim();
+  return text.slice(0, TITLE_MAX_CHARS) || "Untitled session";
+}
+
+export async function generateSessionTitle(
+  host: AgentHost,
+  sessionId: string,
+): Promise<string> {
+  const messages = host.db.getMessagesAfter(sessionId, 0);
+  if (messages.length === 0) return "Empty session";
+  const fallback = fallbackTitle(messages);
+
+  const resolved = host.resolveModel();
+  const worker = resolved?.working ?? resolved?.instance;
+  if (!worker) return fallback;
+
+  const transcript = messages
+    .slice(-TITLE_MAX_MESSAGES)
+    .map((message) => `${message.role === "user" ? "USER" : "AGENT"}: ${message.content}`)
+    .join("\n")
+    .slice(0, 6000);
+
+  try {
+    const response = await worker.complete({
+      model: resolved?.workingModel || resolved?.model || "",
+      messages: [
+        {
+          role: "system",
+          content:
+            "You name conversation sessions. Given a conversation transcript, write a short title that captures the main task or topic. Rules: at most 12 words, same language as the conversation, no quotes, no punctuation at the end, output ONLY the title.",
+        },
+        { role: "user", content: transcript },
+      ],
+      temperature: 0.3,
+    });
+    const title = (response.content ?? "").trim().replace(/^["'#\s]+|["'\s]+$/g, "");
+    if (!title) return fallback;
+    return title.slice(0, TITLE_MAX_CHARS);
+  } catch (err) {
+    host.logger.warn(`[agent] session title generation failed: ${err}`);
+    return fallback;
+  }
+}