@mushinjs/plugin-agent 0.0.0-stage → 0.2.0-next.20261112165327

package/dist/index.js

@@ -0,0 +1,942 @@
+import { SYSTEM_PROMPT, contextNote, skillBlock } from "./prompt.js";
+import { SCENE_KEYS, defaultPolicy, formatSkillMarkdown, parseSkillMarkdown, policyInput, profileInput, today } from "./settings.js";
+import { BUILTIN_SKILLS, skillFields, skillInput } from "./skills.js";
+import { MushinError, Service, field, fromToolName, randomId, segmentsToText, toToolName, z } from "@mushinjs/core";
+// src/index.ts
+/** Commands the dashboard runs itself, without asking the model. */
+const BUILTIN_COMMANDS = [
+	{
+		name: "new",
+		description: "Start a new conversation",
+		"zh-CN": "开始新对话"
+	},
+	{
+		name: "history",
+		description: "Open the full conversation history",
+		"zh-CN": "打开完整历史"
+	},
+	{
+		name: "model",
+		description: "Switch the Agent's model",
+		"zh-CN": "切换模型"
+	},
+	{
+		name: "status",
+		description: "Show how much context this conversation uses",
+		"zh-CN": "查看上下文用量"
+	},
+	{
+		name: "clear",
+		description: "Clear the input and close the conversation",
+		"zh-CN": "清空当前对话视图"
+	},
+	{
+		name: "help",
+		description: "Show what you can type",
+		"zh-CN": "查看可用的指令和技能"
+	}
+];
+const SETTINGS_KEY = "agent/settings/main";
+const USAGE_KEY = "agent/settings/usage";
+const MAX_RESULT_CHARS = 16e3;
+const Config = z.object({
+	provider: z.string().optional().meta(field("Provider", "Provider or model profile for the Agent; empty uses the default provider", { "zh-CN": {
+		title: "提供商",
+		description: "智能体使用的提供商或配置方案；留空使用默认提供商"
+	} }, { choices: "providers.choices" })),
+	model: z.string().optional().meta(field("Model", "Model for the Agent; empty uses the provider's default", { "zh-CN": {
+		title: "模型",
+		description: "智能体使用的模型；留空使用提供商默认模型"
+	} })),
+	maxSteps: z.number().int().min(1).max(50).default(20).meta(field("Max steps", "Most tool-calling rounds in one reply", { "zh-CN": {
+		title: "最大步数",
+		description: "一次回复中最多调用工具的轮数"
+	} })),
+	confirmTimeout: z.number().int().min(10).default(600).meta(field("Approval timeout", "Seconds to wait for approval of a dangerous action", { "zh-CN": {
+		title: "确认超时",
+		description: "等待用户批准危险操作的秒数"
+	} })),
+	dailyTokens: z.number().int().min(0).default(0).meta(field("Daily token budget", "Input and output tokens the Agent may use per day; 0 means no limit", { "zh-CN": {
+		title: "每日 Token 预算",
+		description: "智能体每天最多使用的输入和输出 Token；0 表示不限制"
+	} }))
+});
+/** The turn used every tool round it may; the dashboard offers to continue. */
+var StepLimit = class extends Error {
+	constructor(steps) {
+		super(`Stopped after ${steps} tool rounds; send another message to continue`);
+	}
+};
+/** After this many failures of one tool in a turn, its errors ask the model to change course. */
+const FAILURE_HINT_AFTER = 3;
+/** Runs conversations in which the LLM operates Mushin.js through the action registry. */
+var Agent = class extends Service {
+	config;
+	static inject = [
+		"actions",
+		"llm",
+		"storage"
+	];
+	static Config = Config;
+	home;
+	running = /* @__PURE__ */ new Map();
+	pluginSkills = /* @__PURE__ */ new Map();
+	settingsCache;
+	constructor(ctx, config) {
+		super(ctx, "agent");
+		this.config = config;
+		this.home = ctx;
+	}
+	*[Service.init]() {
+		yield* this.defineActions();
+		yield () => {
+			for (const id of this.running.keys()) this.cancel(id);
+		};
+	}
+	/** Tools offered to the model: every action except the Agent's own and those turned off. */
+	async tools() {
+		const settings = await this.settings();
+		return this.home.actions.list().filter((action) => action.agent && !action.name.startsWith("agent.") && this.policyOf(settings, action) !== "off").map((action) => ({
+			name: toToolName(action.name),
+			description: describeTool(action),
+			parameters: action.inputSchema
+		}));
+	}
+	async settings() {
+		if (!this.settingsCache) {
+			const saved = await this.home.storage.get(SETTINGS_KEY);
+			this.settingsCache = {
+				profiles: {},
+				toolPolicy: {},
+				disabledSkills: [],
+				...saved
+			};
+		}
+		return this.settingsCache;
+	}
+	async updateSettings(change) {
+		const settings = await this.settings();
+		change(settings);
+		await this.home.storage.set(SETTINGS_KEY, settings);
+		this.home.emit("agent/changed");
+		return settings;
+	}
+	policyOf(settings, action) {
+		return settings.toolPolicy[action.name] ?? defaultPolicy(action.risk);
+	}
+	/** Every action with its policy, for the tool policy table. */
+	async policies() {
+		const settings = await this.settings();
+		return this.home.actions.list().filter((action) => action.agent && !action.name.startsWith("agent.")).map((action) => ({
+			name: action.name,
+			description: action.description,
+			plugin: action.plugin,
+			risk: action.risk,
+			client: action.client,
+			policy: this.policyOf(settings, action),
+			custom: action.name in settings.toolPolicy
+		}));
+	}
+	/** Sets the policy of some actions; `null` goes back to the default for the action's risk. */
+	async setPolicy(changes) {
+		await this.updateSettings((settings) => {
+			for (const [name, policy] of Object.entries(changes)) if (policy === null) delete settings.toolPolicy[name];
+			else settings.toolPolicy[name] = policy;
+		});
+		return this.policies();
+	}
+	async profiles() {
+		return (await this.settings()).profiles;
+	}
+	async setProfile(scene, profile) {
+		return (await this.updateSettings((settings) => {
+			if (profile === null) delete settings.profiles[scene];
+			else settings.profiles[scene] = profile;
+		})).profiles[scene] ?? {};
+	}
+	/** Tokens used today and the daily budget. */
+	async usage() {
+		const saved = await this.home.storage.get(USAGE_KEY);
+		return {
+			...saved?.day === today() ? saved : {
+				day: today(),
+				input: 0,
+				output: 0
+			},
+			budget: this.config.dailyTokens
+		};
+	}
+	async addUsage(usage) {
+		const current = await this.usage();
+		await this.home.storage.set(USAGE_KEY, {
+			day: current.day,
+			input: current.input + usage.inputTokens,
+			output: current.output + usage.outputTokens
+		});
+	}
+	emit(event) {
+		this.home.emit("agent/event", event);
+	}
+	async allSessions() {
+		const keys = await this.home.storage.list("agent");
+		return (await Promise.all(keys.map((key) => this.home.storage.get(key)))).filter((session) => !!session && Array.isArray(session.messages)).sort((a, b) => b.updatedAt - a.updatedAt);
+	}
+	summary({ id, title, createdAt, updatedAt, scene, tags }) {
+		return {
+			id,
+			title,
+			createdAt,
+			updatedAt,
+			scene,
+			tags: tags ?? [],
+			running: this.running.has(id)
+		};
+	}
+	async sessions() {
+		return (await this.allSessions()).map((session) => this.summary(session));
+	}
+	/**
+	* Conversations matching every tag (`scene:flowEditor`, `skill:<id>`, `status:running`, …) and
+	* containing the query in the title or in what the user or the Agent wrote.
+	*/
+	async search(options = {}) {
+		const query = options.query?.trim().toLowerCase();
+		const results = [];
+		for (const session of await this.allSessions()) {
+			const summary = this.summary(session);
+			const tags = [...summary.tags, `status:${summary.running ? "running" : "idle"}`];
+			if (options.tags?.some((tag) => !tags.includes(tag))) continue;
+			let snippet;
+			if (query) {
+				if (!session.title.toLowerCase().includes(query)) {
+					const hit = session.messages.filter((message) => message.role === "user" || message.role === "assistant").map((message) => message.role === "user" ? message.display ?? message.content : message.content).find((text) => typeof text === "string" && text.toLowerCase().includes(query));
+					if (!hit) continue;
+					const at = hit.toLowerCase().indexOf(query);
+					snippet = `${at > 30 ? "…" : ""}${hit.slice(Math.max(0, at - 30), at + query.length + 50).replace(/\s+/g, " ")}`;
+				}
+			}
+			results.push({
+				...summary,
+				...snippet ? { snippet } : {}
+			});
+			if (results.length >= (options.limit ?? 50)) break;
+		}
+		return results;
+	}
+	/** Adds a skill from a plugin; removed when the plugin unloads. */
+	defineSkill(definition) {
+		const ctx = this.ctx;
+		const skill = {
+			...definition,
+			source: "plugin",
+			plugin: ctx.fiber.name,
+			enabled: true
+		};
+		return ctx.effect(() => {
+			this.pluginSkills.set(skill.id, skill);
+			return () => {
+				if (this.pluginSkills.get(skill.id) === skill) this.pluginSkills.delete(skill.id);
+			};
+		}, `agent.defineSkill(${definition.id})`);
+	}
+	/** Built-in, plugin and user skills; user skills win on the same id. */
+	async skills() {
+		const disabled = new Set((await this.settings()).disabledSkills);
+		const byId = /* @__PURE__ */ new Map();
+		for (const skill of BUILTIN_SKILLS) byId.set(skill.id, {
+			...skill,
+			source: "builtin",
+			enabled: true
+		});
+		for (const skill of this.pluginSkills.values()) byId.set(skill.id, { ...skill });
+		const keys = await this.home.storage.list("agent/skills");
+		for (const skill of await Promise.all(keys.map((key) => this.home.storage.get(key)))) if (skill?.id) byId.set(skill.id, {
+			...skill,
+			source: "user",
+			enabled: skill.enabled !== false
+		});
+		return [...byId.values()].map((skill) => skill.source !== "user" && disabled.has(skill.id) ? {
+			...skill,
+			enabled: false
+		} : skill);
+	}
+	async skill(id) {
+		const skill = (await this.skills()).find((item) => item.id === id);
+		if (!skill) throw new MushinError("not_found", `No skill "${id}"`);
+		return skill;
+	}
+	/** Saves a user skill. With the id of a built-in or plugin skill it replaces that one until deleted. */
+	async saveSkill(input) {
+		const skill = {
+			...input,
+			source: "user",
+			enabled: input.enabled !== false
+		};
+		await this.home.storage.set(`agent/skills/${skill.id}`, skill);
+		this.home.emit("agent/changed");
+		return this.skill(skill.id);
+	}
+	async createSkill(input) {
+		const taken = new Set((await this.skills()).map((skill) => skill.id));
+		let id = input.id ?? (input.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || randomId(6).toLowerCase());
+		if (taken.has(id) && !input.id) id = `${id}-${randomId(4).toLowerCase()}`;
+		else if (taken.has(id)) throw new MushinError("conflict", `A skill with id "${id}" already exists`);
+		return this.saveSkill({
+			...input,
+			id
+		});
+	}
+	async updateSkill(id, patch) {
+		const { source, plugin, enabled, ...rest } = await this.skill(id);
+		return this.saveSkill({
+			...rest,
+			...patch,
+			id,
+			enabled
+		});
+	}
+	/** Deletes a user skill; a built-in or plugin skill it replaced comes back. */
+	async deleteSkill(id) {
+		if ((await this.skill(id)).source !== "user") throw new MushinError("forbidden", "Built-in and plugin skills cannot be deleted; turn them off instead");
+		await this.home.storage.delete(`agent/skills/${id}`);
+		this.home.emit("agent/changed");
+		return {
+			deleted: id,
+			restored: (await this.skills()).some((skill) => skill.id === id)
+		};
+	}
+	async setSkillEnabled(id, enabled) {
+		const current = await this.skill(id);
+		if (current.source === "user") {
+			await this.home.storage.set(`agent/skills/${id}`, {
+				...current,
+				enabled
+			});
+			this.home.emit("agent/changed");
+			return this.skill(id);
+		}
+		await this.updateSettings((settings) => {
+			settings.disabledSkills = enabled ? settings.disabledSkills.filter((item) => item !== id) : [.../* @__PURE__ */ new Set([...settings.disabledSkills, id])];
+		});
+		return this.skill(id);
+	}
+	/** Agent commands and the commands of every bot, for the `/` picker. */
+	commands() {
+		const bots = this.home.get("bots");
+		const names = new Map((bots?.list() ?? []).map((bot) => [bot.id, bot.name]));
+		const listed = bots?.commandList().commands ?? [];
+		return {
+			builtin: BUILTIN_COMMANDS,
+			bots: listed.filter((entry) => !entry.hidden).map((entry) => ({
+				name: entry.name,
+				description: entry.description,
+				usage: entry.usage,
+				permission: entry.permission ?? entry.role,
+				bot: entry.botId,
+				botName: names.get(entry.botId),
+				source: entry.source
+			}))
+		};
+	}
+	async session(id) {
+		const session = await this.home.storage.get(`agent/${id}`);
+		if (!session) throw new MushinError("not_found", `No Agent session "${id}"`);
+		return session;
+	}
+	async createSession() {
+		const now = Date.now();
+		const session = {
+			id: randomId(),
+			title: "",
+			createdAt: now,
+			updatedAt: now,
+			tools: await this.tools(),
+			messages: []
+		};
+		await this.save(session);
+		return session;
+	}
+	async deleteSession(id) {
+		this.cancel(id);
+		await this.home.storage.delete(`agent/${id}`);
+		return { deleted: id };
+	}
+	save(session) {
+		session.updatedAt = Date.now();
+		return this.home.storage.set(`agent/${session.id}`, session);
+	}
+	turnContext(page, scene) {
+		const providers = this.home.llm.list();
+		const bots = this.home.get("bots")?.list() ?? [];
+		return {
+			page,
+			scene,
+			providers: providers.length,
+			ready: this.home.llm.isReady(),
+			bots: bots.length,
+			online: bots.filter((bot) => bot.status === "online").length
+		};
+	}
+	/** A bot's chat around one message, for quoting into an Agent message. */
+	async quoteChat(input) {
+		const bots = this.home.get("bots");
+		if (!bots) throw new MushinError("unavailable", "Quoting a chat needs the bots plugin");
+		const record = bots.get(input.bot);
+		const list = await bots.messages(input.bot, {
+			channel: input.channel,
+			limit: 300
+		});
+		const index = list.findIndex((item) => item.id === input.id);
+		if (index < 0) throw new MushinError("not_found", "That message is no longer in the chat's recent messages");
+		const picked = list.slice(Math.max(0, index - (input.before ?? 6)), index + 1 + (input.after ?? 2));
+		return {
+			bot: input.bot,
+			botName: record.name,
+			channel: {
+				type: list[index].channel.type,
+				id: list[index].channel.id,
+				...list[index].channel.name ? { name: list[index].channel.name } : {}
+			},
+			focus: input.id,
+			lines: picked.map((item) => ({
+				id: item.id,
+				direction: item.direction,
+				user: item.user.name ?? item.user.id,
+				userId: item.user.id,
+				text: segmentsToText(item.segments).trim().slice(0, 500),
+				at: item.timestamp
+			}))
+		};
+	}
+	/** Starts a turn and returns once it finishes. Progress streams as `agent/event` events. */
+	async send(sessionId, text, options = {}) {
+		if (!this.home.llm.list().length) throw new MushinError("unavailable", "Add an LLM provider before using the Agent");
+		const usage = await this.usage();
+		if (usage.budget && usage.input + usage.output >= usage.budget) throw new MushinError("unavailable", `The Agent used its daily budget of ${usage.budget} tokens; raise it in the Agent settings or wait until tomorrow`);
+		const session = sessionId ? await this.session(sessionId) : await this.createSession();
+		if (this.running.has(session.id)) throw new MushinError("conflict", "The Agent is still working on this conversation");
+		const running = {
+			abort: new AbortController(),
+			confirms: /* @__PURE__ */ new Map(),
+			usage: {
+				inputTokens: 0,
+				outputTokens: 0
+			},
+			failures: /* @__PURE__ */ new Map()
+		};
+		this.running.set(session.id, running);
+		const skills = options.skills?.length ? await Promise.all(options.skills.map((id) => this.skill(id))) : [];
+		if (!session.title) session.title = (text || skills.map((skill) => skill.name).join(", ")).replace(/\s+/g, " ").slice(0, 48);
+		if (!session.messages.length && options.scene) session.scene = {
+			key: options.scene.key,
+			...options.scene.label ? { label: options.scene.label } : {},
+			...options.page ? { page: options.page } : {}
+		};
+		session.tags = [.../* @__PURE__ */ new Set([...session.tags ?? [], ...turnTags(text, options, skills)])];
+		const quote = options.quote ? await this.quoteChat(options.quote) : void 0;
+		session.messages.push({
+			role: "user",
+			content: [
+				contextNote(this.turnContext(options.page, options.scene)),
+				...skills.map(skillBlock),
+				quote ? quoteBlock(quote) : "",
+				text
+			].filter(Boolean).join("\n\n"),
+			display: text,
+			...skills.length ? { skills: skills.map((skill) => skill.name) } : {},
+			...quote ? { quote } : {},
+			at: Date.now()
+		});
+		await this.save(session);
+		this.emit({
+			session: session.id,
+			type: "start"
+		});
+		try {
+			const final = await this.loop(session, running, options);
+			this.emit({
+				session: session.id,
+				type: "done",
+				text: final?.text ?? "",
+				usage: running.usage
+			});
+		} catch (error) {
+			const message = running.abort.signal.aborted ? "Stopped" : error instanceof Error ? error.message : String(error);
+			this.emit({
+				session: session.id,
+				type: "error",
+				error: message,
+				...error instanceof StepLimit && !running.abort.signal.aborted ? { code: "max_steps" } : {}
+			});
+		} finally {
+			this.running.delete(session.id);
+			await this.save(session);
+		}
+		return { session: session.id };
+	}
+	async loop(session, running, options) {
+		for (let step = 0; step < this.config.maxSteps; step++) {
+			const history = [{
+				role: "system",
+				content: SYSTEM_PROMPT
+			}, ...session.messages.map(stripMeta)];
+			let result;
+			for await (const event of this.home.llm.stream({
+				provider: this.config.provider,
+				model: this.config.model,
+				messages: history,
+				tools: session.tools,
+				signal: running.abort.signal
+			})) if (event.type === "delta") this.emit({
+				session: session.id,
+				type: "delta",
+				text: event.text
+			});
+			else if (event.type === "result") result = event.result;
+			if (!result) throw new Error("The provider returned no result");
+			if (result.usage) {
+				running.usage.inputTokens += result.usage.inputTokens;
+				running.usage.outputTokens += result.usage.outputTokens;
+				await this.addUsage(result.usage);
+			}
+			session.messages.push({
+				role: "assistant",
+				content: result.text,
+				...result.toolCalls.length ? { toolCalls: result.toolCalls } : {},
+				...result.raw ? { raw: result.raw } : {},
+				at: Date.now()
+			});
+			if (!result.toolCalls.length) return result;
+			if (result.finishReason === "length" || result.finishReason === "refusal") {
+				const reason = result.finishReason === "length" ? "The reply hit the output limit, so this tool call may be incomplete and was not run." : "The model declined this turn, so this tool call was not run.";
+				for (const call of result.toolCalls) session.messages.push({
+					role: "tool",
+					toolCallId: call.id,
+					content: reason,
+					isError: true,
+					at: Date.now()
+				});
+				throw new Error(reason);
+			}
+			for (const call of result.toolCalls) await this.runTool(session, running, call, options);
+			if (step === this.config.maxSteps - 2) {
+				const last = session.messages.at(-1);
+				last.content += `\n\n[This was the last tool round for this message (the limit is ${this.config.maxSteps}). Do not call tools now: tell the user what is done, what is left, and that they can send another message to continue.]`;
+			}
+			await this.save(session);
+		}
+		throw new StepLimit(this.config.maxSteps);
+	}
+	async runTool(session, running, call, options) {
+		const name = fromToolName(call.name);
+		const info = this.home.actions.get(name);
+		const reply = (content, isError = false) => {
+			session.messages.push({
+				role: "tool",
+				toolCallId: call.id,
+				content,
+				...isError ? { isError } : {},
+				at: Date.now()
+			});
+		};
+		let input;
+		try {
+			input = JSON.parse(call.arguments || "{}");
+		} catch {
+			this.emit({
+				session: session.id,
+				type: "tool-result",
+				id: call.id,
+				ok: false,
+				error: "Arguments are not valid JSON"
+			});
+			return reply("The arguments were not valid JSON. Send a JSON object that matches the tool schema.", true);
+		}
+		if (!info || !info.agent) {
+			this.emit({
+				session: session.id,
+				type: "tool-result",
+				id: call.id,
+				ok: false,
+				error: `Unknown tool ${call.name}`
+			});
+			return reply(`The tool ${call.name} is not available right now.`, true);
+		}
+		const policy = this.policyOf(await this.settings(), info);
+		if (policy === "off") {
+			this.emit({
+				session: session.id,
+				type: "tool-result",
+				id: call.id,
+				ok: false,
+				error: "Turned off in the Agent settings"
+			});
+			return reply(`The user turned ${call.name} off for the Agent. Do not use it; tell them if it is needed.`, true);
+		}
+		this.emit({
+			session: session.id,
+			type: "tool-call",
+			id: call.id,
+			action: name,
+			input,
+			risk: info.risk
+		});
+		if (policy === "confirm") {
+			this.emit({
+				session: session.id,
+				type: "confirm",
+				id: call.id,
+				action: name,
+				input
+			});
+			if (!await this.waitForApproval(running, call.id)) {
+				this.emit({
+					session: session.id,
+					type: "tool-result",
+					id: call.id,
+					ok: false,
+					error: "Declined by the user"
+				});
+				return reply("The user declined this action. Do not retry it.", true);
+			}
+		}
+		try {
+			const result = await this.home.actions.call(name, input, {
+				kind: "agent",
+				session: session.id,
+				client: options.client
+			});
+			this.emit({
+				session: session.id,
+				type: "tool-result",
+				id: call.id,
+				ok: true,
+				result
+			});
+			reply(truncate(JSON.stringify(result ?? { ok: true })));
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			this.emit({
+				session: session.id,
+				type: "tool-result",
+				id: call.id,
+				ok: false,
+				error: message
+			});
+			const failures = (running.failures.get(name) ?? 0) + 1;
+			running.failures.set(name, failures);
+			reply(`Error: ${message}${failures >= FAILURE_HINT_AFTER ? `\n${call.name} has failed ${failures} times in this reply. Stop retrying it with guessed inputs: take valid values from the error above or from the tool that lists them, or tell the user what is missing.` : ""}`, true);
+		}
+	}
+	waitForApproval(running, callId) {
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => finish(false), this.config.confirmTimeout * 1e3);
+			const finish = (approved) => {
+				clearTimeout(timer);
+				running.confirms.delete(callId);
+				resolve(approved);
+			};
+			running.confirms.set(callId, finish);
+			running.abort.signal.addEventListener("abort", () => finish(false), { once: true });
+		});
+	}
+	confirm(sessionId, callId, approved) {
+		const resolve = this.running.get(sessionId)?.confirms.get(callId);
+		if (!resolve) throw new MushinError("not_found", "No action is waiting for approval");
+		resolve(approved);
+		return { ok: true };
+	}
+	cancel(sessionId) {
+		const running = this.running.get(sessionId);
+		if (!running) return { ok: false };
+		running.abort.abort();
+		return { ok: true };
+	}
+	status() {
+		return {
+			ready: this.home.llm.isReady(),
+			providers: this.home.llm.list().length,
+			running: [...this.running.keys()]
+		};
+	}
+	*defineActions() {
+		const actions = this.home.actions;
+		yield actions.define({
+			name: "agent.status",
+			description: "Whether the Agent can run (a provider exists and passed its test).",
+			risk: "read",
+			input: z.object({}),
+			handler: () => this.status()
+		});
+		yield actions.define({
+			name: "agent.sessions",
+			description: "List Agent conversations, newest first.",
+			risk: "read",
+			input: z.object({}),
+			handler: () => this.sessions()
+		});
+		yield actions.define({
+			name: "agent.session",
+			description: "Get one Agent conversation with its messages.",
+			risk: "read",
+			input: z.object({ id: z.string() }),
+			handler: async ({ id }) => {
+				const { tools, ...session } = await this.session(id);
+				const now = new Set((await this.tools()).map((tool) => tool.name));
+				const toolsStale = tools.length !== now.size || tools.some((tool) => !now.has(tool.name));
+				return {
+					...session,
+					messages: session.messages.map(({ raw, ...message }) => message),
+					running: this.running.has(id),
+					toolsStale
+				};
+			}
+		});
+		yield actions.define({
+			name: "agent.send",
+			description: "Send a message to the Agent. Omit session to start a new conversation. Progress streams over the WebSocket.",
+			risk: "write",
+			input: z.object({
+				session: z.string().optional(),
+				text: z.string(),
+				page: z.string().optional(),
+				scene: z.object({
+					key: z.string(),
+					label: z.string().max(200).optional(),
+					hint: z.string().max(1e3).optional(),
+					state: z.record(z.string(), z.union([
+						z.string().max(200),
+						z.number(),
+						z.boolean()
+					])).optional(),
+					resource: z.string().max(200).optional()
+				}).optional().describe("The dashboard page as the dashboard describes it"),
+				skills: z.array(z.string()).max(5).optional().describe("Skill ids to apply to this message"),
+				quote: z.object({
+					bot: z.string(),
+					channel: z.string().describe("The chat's id"),
+					id: z.string().describe("The quoted message's record id, from bots.messages"),
+					before: z.number().int().min(0).max(30).optional(),
+					after: z.number().int().min(0).max(10).optional()
+				}).optional().describe("A message of a bot's chat to quote, with a few messages around it")
+			}).refine((input) => input.text.trim() || input.skills?.length, "Send some text or pick a skill"),
+			handler: ({ session, text, ...options }, caller) => this.send(session, text, {
+				client: caller.client,
+				...options
+			})
+		});
+		yield actions.define({
+			name: "agent.search",
+			description: "Search Agent conversations by text and tags (scene:<page kind>, skill:<id>, command:<name>, resource:<kind>:<id>, status:running).",
+			risk: "read",
+			input: z.object({
+				query: z.string().optional(),
+				tags: z.array(z.string()).optional(),
+				limit: z.number().int().min(1).max(200).optional()
+			}),
+			handler: (input) => this.search(input)
+		});
+		yield actions.define({
+			name: "agent.commands",
+			description: "Commands for the Agent's \"/\" picker: its own (new, history, …) and every bot's commands.",
+			risk: "read",
+			input: z.object({}),
+			handler: () => this.commands()
+		});
+		yield actions.define({
+			name: "agent.skills.list",
+			description: "List the Agent's skills: built in, from plugins, and written by the user.",
+			risk: "read",
+			input: z.object({}),
+			handler: () => this.skills()
+		});
+		yield actions.define({
+			name: "agent.skills.get",
+			description: "Get one Agent skill with its instructions.",
+			risk: "read",
+			input: z.object({ id: z.string() }),
+			handler: ({ id }) => this.skill(id)
+		});
+		const skillId = z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/).describe("Lowercase letters, digits and dashes");
+		yield actions.define({
+			name: "agent.skills.create",
+			description: "Create a user skill. Omit id to make one from the name.",
+			risk: "write",
+			input: skillInput.extend({ id: skillId.optional() }),
+			handler: (input) => this.createSkill(input)
+		});
+		yield actions.define({
+			name: "agent.skills.update",
+			description: "Change a skill. Changing a built-in or plugin skill saves your own copy that replaces it until deleted.",
+			risk: "write",
+			input: z.object({
+				id: z.string(),
+				name: skillFields.name.optional(),
+				description: z.string().trim().max(300).optional(),
+				instructions: skillFields.instructions.optional(),
+				whenToUse: skillFields.whenToUse,
+				tools: skillFields.tools,
+				scenes: skillFields.scenes
+			}),
+			handler: ({ id, ...patch }) => this.updateSkill(id, patch)
+		});
+		yield actions.define({
+			name: "agent.skills.delete",
+			description: "Delete a user skill. A built-in or plugin skill it replaced comes back.",
+			risk: "write",
+			input: z.object({ id: z.string() }),
+			handler: ({ id }) => this.deleteSkill(id)
+		});
+		yield actions.define({
+			name: "agent.skills.setEnabled",
+			description: "Turn a skill on or off; off skills are not offered with $.",
+			risk: "write",
+			input: z.object({
+				id: z.string(),
+				enabled: z.boolean()
+			}),
+			handler: ({ id, enabled }) => this.setSkillEnabled(id, enabled)
+		});
+		yield actions.define({
+			name: "agent.skills.import",
+			description: "Import a skill from a SKILL.md file (YAML frontmatter with name and description, then Markdown instructions), as used by Claude and Codex skills.",
+			risk: "write",
+			input: z.object({
+				markdown: z.string().min(1).max(4e4),
+				replace: z.boolean().optional().describe("Overwrite a skill with the same id")
+			}),
+			handler: async ({ markdown, replace }) => {
+				let parsed;
+				try {
+					parsed = parseSkillMarkdown(markdown);
+				} catch (error) {
+					throw new MushinError("invalid_input", error instanceof Error ? error.message : String(error));
+				}
+				const input = skillInput.extend({ id: skillId.optional() }).parse(parsed);
+				if (replace && input.id) return this.saveSkill({
+					...input,
+					id: input.id
+				});
+				return this.createSkill(input);
+			}
+		});
+		yield actions.define({
+			name: "agent.skills.export",
+			description: "A skill as a SKILL.md file.",
+			risk: "read",
+			input: z.object({ id: z.string() }),
+			handler: async ({ id }) => ({
+				fileName: "SKILL.md",
+				markdown: formatSkillMarkdown(await this.skill(id))
+			})
+		});
+		yield actions.define({
+			name: "agent.profiles.list",
+			description: "What the Agent says and offers on each dashboard page, as the user changed it: hint, welcome line, own suggestions, hidden built-in suggestions, recommended skills.",
+			risk: "read",
+			input: z.object({}),
+			handler: async () => ({
+				scenes: SCENE_KEYS,
+				profiles: await this.profiles()
+			})
+		});
+		yield actions.define({
+			name: "agent.profiles.update",
+			description: "Change what the Agent says and offers on one dashboard page. Send the whole profile; null goes back to the defaults.",
+			risk: "write",
+			input: z.object({
+				scene: z.enum(SCENE_KEYS),
+				profile: profileInput.nullable()
+			}),
+			handler: ({ scene, profile }) => this.setProfile(scene, profile)
+		});
+		yield actions.define({
+			name: "agent.policy.list",
+			description: "Every tool the Agent can use, with its plugin, risk and policy: auto (runs), confirm (asks the user first) or off (not offered).",
+			risk: "read",
+			input: z.object({}),
+			handler: () => this.policies()
+		});
+		yield actions.define({
+			name: "agent.policy.set",
+			description: "Set the policy of tools by action name: auto, confirm, or off; null goes back to the default (dangerous actions ask, others run). Off tools leave new conversations only.",
+			risk: "dangerous",
+			input: z.object({ policies: z.record(z.string(), policyInput.nullable()) }),
+			handler: ({ policies }) => this.setPolicy(policies)
+		});
+		yield actions.define({
+			name: "agent.usage",
+			description: "Tokens the Agent used today and its daily budget (0 means no limit).",
+			risk: "read",
+			input: z.object({}),
+			handler: () => this.usage()
+		});
+		yield actions.define({
+			name: "agent.confirm",
+			description: "Approve or decline an action the Agent is waiting on.",
+			risk: "write",
+			input: z.object({
+				session: z.string(),
+				id: z.string(),
+				approved: z.boolean()
+			}),
+			handler: ({ session, id, approved }) => this.confirm(session, id, approved)
+		});
+		yield actions.define({
+			name: "agent.cancel",
+			description: "Stop the Agent's current reply in a conversation.",
+			risk: "write",
+			input: z.object({ session: z.string() }),
+			handler: ({ session }) => this.cancel(session)
+		});
+		yield actions.define({
+			name: "agent.deleteSession",
+			description: "Delete an Agent conversation.",
+			risk: "write",
+			input: z.object({ id: z.string() }),
+			handler: ({ id }) => this.deleteSession(id)
+		});
+	}
+};
+function describeTool(action) {
+	const notes = [];
+	if (action.risk === "dangerous") notes.push("Dangerous: the user must approve it.");
+	if (action.client) notes.push("Runs in the user's dashboard; fails if none is connected.");
+	return [action.description, ...notes].join(" ");
+}
+/** Search tags for one message: its scene, skills, a leading command, and the page's resource. */
+/** A quoted chat as the model reads it; the picked message is marked, with its record id for samples. */
+function quoteBlock(quote) {
+	const where = quote.channel.type === "group" ? `group ${quote.channel.name ? `${quote.channel.name} ` : ""}(${quote.channel.id})` : `private chat with ${quote.channel.id}`;
+	const lines = quote.lines.map((line) => {
+		const time = new Date(line.at).toISOString().slice(11, 16);
+		const who = line.direction === "out" ? `${quote.botName} (bot)` : `${line.user} (${line.userId})`;
+		return `${line.id === quote.focus ? "→ " : "  "}[${time}] ${who}: ${line.text}`;
+	});
+	return [
+		`<quote bot="${quote.bot}" chat="${quote.channel.id}" message="${quote.focus}">`,
+		`Messages from ${quote.botName} in the ${where}; the user picked the one marked →. To build or check a flow for it, pass sample { bot: "${quote.bot}", id: "${quote.focus}", channel: "${quote.channel.id}" } to flows.test or flows.preview.`,
+		...lines,
+		"</quote>"
+	].join("\n");
+}
+function turnTags(text, options, skills) {
+	const tags = [];
+	if (options.scene) tags.push(`scene:${options.scene.key}`);
+	if (options.scene?.resource) tags.push(`resource:${options.scene.resource}`);
+	for (const skill of skills) tags.push(`skill:${skill.id}`);
+	const command = /^\s*\/([\p{L}\p{N}_-]+)/u.exec(text);
+	if (command) tags.push(`command:${command[1]}`);
+	return tags;
+}
+function stripMeta(message) {
+	const { display, skills, quote, at, ...rest } = message;
+	return rest;
+}
+function truncate(text) {
+	if (text.length <= MAX_RESULT_CHARS) return text;
+	return `${text.slice(0, MAX_RESULT_CHARS)}… [truncated ${text.length - MAX_RESULT_CHARS} characters; ask for less, e.g. with a filter or limit]`;
+}
+export { Agent, Agent as default, BUILTIN_COMMANDS, BUILTIN_SKILLS, Config, SCENE_KEYS, SYSTEM_PROMPT, contextNote, defaultPolicy, formatSkillMarkdown, parseSkillMarkdown, policyInput, profileInput, skillBlock, skillFields, skillInput, today };
+
+//# sourceMappingURL=index.js.map