pi-roundtable 0.33.0 → 0.35.0

package/src/core/agents/helper-create.ts

@@ -1,12 +1,16 @@
 import type { CharacterInput } from "../../characters/index.ts";
-import { helpersOf } from "../config/helpers.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
-import type { Speaker } from "../speakers.ts";
-import { toolTiers } from "../tool-tiers.ts";
+import type { Speaker } from "../identity/speakers.ts";
 import { isHelper } from "./agent-rules.ts";
 import type { Agent } from "./agent-store.ts";
 import { followOrigin } from "./helper-modes.ts";
+import {
+	checkHelperGrant,
+	type HelperFields,
+	helperMaker,
+	withPreset,
+} from "./helper-preset-ops.ts";
 import type { TeamContext } from "./team-options.ts";
 
 /** The team's way of making an agent, which `createHelper` uses to make a temp knight. */
@@ -40,46 +44,26 @@ export async function createHelper(
 	ctx: TeamContext,
 	make: MakeAgent,
 	caller: AgentTurnScope,
-	input: {
-		name?: string;
-		displayName: string;
-		prompt: string;
-		task: string;
-		character?: CharacterInput;
-		skills?: string[];
-		model?: string;
-		thinking?: string;
-	},
+	input: HelperFields & { name?: string; task: string },
 ): Promise<string> {
 	const { store, logger } = ctx.options;
-	const limits = helpersOf(ctx.options.helpers);
-	if (!limits)
-		throw new AgentError("Temp knights are switched off on this host.");
-	const speaker = ctx.turns.speakerOf(caller);
-	if (!speaker)
+	const { speaker, parent, limits } = helperMaker(ctx, caller, "helper_create");
+	// A preset saved earlier is checked again now, merged with the call.
+	const merged = await withPreset(ctx, parent, input);
+	const {
+		task,
+		name: given,
+		model,
+		thinking,
+		preset: _preset,
+		...rest
+	} = merged;
+	const { displayName, prompt } = rest;
+	if (!displayName || !prompt)
 		throw new AgentError(
-			"helper_create can only be used during an agent turn.",
+			"Give display_name and prompt, or a preset (from helper_preset_list) that has them.",
 		);
-	const parent = store.activeAgent(caller.name);
-	if (isHelper(parent))
-		throw new AgentError(
-			`You are a temp knight of "${parent.parent}" and cannot make temp knights; ask it to.`,
-		);
-	const { task, name: given, model, thinking, ...rest } = input;
-	// A temp knight never gets more than its parent unless the speaker could grant it by hand.
-	const tiers = ctx.options.toolTiers ?? toolTiers();
-	if (!tiers.allows(speaker.tier, "agent_update") && (model || thinking))
-		throw new AgentError(
-			"A temp knight runs your model and thinking level; choosing others needs a higher tier.",
-		);
-	if (rest.skills?.length && !tiers.allows(speaker.tier, "agent_skills")) {
-		const own = new Set(ctx.options.skills?.carriedNames(parent.name) ?? []);
-		const extra = rest.skills.filter((skill) => !own.has(skill));
-		if (extra.length > 0)
-			throw new AgentError(
-				`A temp knight can carry only skills you carry; not allowed: ${extra.join(", ")}.`,
-			);
-	}
+	checkHelperGrant(ctx, speaker, parent, merged);
 	const name = given ?? nextName(ctx, parent.name);
 	// Everything that can be refused is checked before anything is made or archived.
 	store.checkNewName(name);
@@ -92,7 +76,7 @@ export async function createHelper(
 			parent,
 			origin: ctx.turns.turnChannel(caller),
 		},
-		{ ...rest, name },
+		{ ...rest, displayName, prompt, name },
 		{ model, thinking },
 	);
 	const helper = made.agent;

package/src/core/agents/helper-modes.ts

@@ -1,8 +1,8 @@
 import type { AgentTurnScope } from "../domain/ports.ts";
 import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+import type { Speaker } from "../identity/speakers.ts";
 import type { ModeOrigins } from "../modes/mode-inheritance.ts";
-import type { AgentDirectory } from "../services.ts";
-import type { Speaker } from "../speakers.ts";
+import type { AgentDirectory } from "../plugin-api/services.ts";
 import { isHelper } from "./agent-rules.ts";
 import type { Agent } from "./agent-store.ts";
 import { agentOfChannel, groupOfChannel, keysOf } from "./team-keys.ts";

package/src/core/agents/helper-preset-ops.ts

@@ -0,0 +1,207 @@
+import type { CharacterInput } from "../../characters/index.ts";
+import { helpersOf, type ResolvedHelpers } from "../config/helpers.ts";
+import { AgentError } from "../domain/errors.ts";
+import { THINKING_LEVELS } from "../domain/models.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import type { Speaker } from "../identity/speakers.ts";
+import { toolTiers } from "../runtime/tool-tiers.ts";
+import {
+	type Agent,
+	checkDisplayName,
+	checkModelRef,
+	checkPrompt,
+	isHelper,
+} from "./agent-rules.ts";
+import type { HelperPreset } from "./helper-presets.ts";
+import type { TeamContext } from "./team-options.ts";
+
+/** What the helper_preset tools ask of the team. */
+export type PresetAction =
+	| { kind: "set"; preset: HelperPreset }
+	| { kind: "list"; name?: string }
+	| { kind: "delete"; name: string };
+
+/** What a temp knight is made with; a preset fills in what the call leaves out. */
+export interface HelperFields {
+	preset?: string;
+	displayName?: string;
+	prompt?: string;
+	character?: CharacterInput;
+	skills?: string[];
+	model?: string;
+	thinking?: string;
+}
+
+const PRESET_NAME = /^[a-z0-9-]{1,32}$/;
+
+/**
+ * The speaker of the caller's turn and the knight it is, refused when temp knights are off, outside
+ * an agent turn, or for a temp knight, which cannot make temp knights.
+ */
+export function helperMaker(
+	ctx: TeamContext,
+	caller: AgentTurnScope,
+	tool: string,
+): { speaker: Speaker; parent: Agent; limits: ResolvedHelpers } {
+	const limits = helpersOf(ctx.options.helpers);
+	if (!limits)
+		throw new AgentError("Temp knights are switched off on this host.");
+	const speaker = ctx.turns.speakerOf(caller);
+	if (!speaker)
+		throw new AgentError(`${tool} can only be used during an agent turn.`);
+	const parent = ctx.options.store.activeAgent(caller.name);
+	if (isHelper(parent))
+		throw new AgentError(
+			`You are a temp knight of "${parent.parent}" and cannot make temp knights; ask it to.`,
+		);
+	return { speaker, parent, limits };
+}
+
+/**
+ * A temp knight never gets more than its parent unless the speaker could grant it by hand: another
+ * model or thinking level needs the agent_update tier, a skill the parent does not carry the
+ * agent_skills tier.
+ */
+export function checkHelperGrant(
+	ctx: TeamContext,
+	speaker: Speaker,
+	parent: Agent,
+	fields: Pick<HelperFields, "model" | "thinking" | "skills">,
+): void {
+	const tiers = ctx.options.toolTiers ?? toolTiers();
+	if (
+		!tiers.allows(speaker.tier, "agent_update") &&
+		(fields.model || fields.thinking)
+	)
+		throw new AgentError(
+			"A temp knight runs your model and thinking level; choosing others needs a higher tier.",
+		);
+	if (fields.skills?.length && !tiers.allows(speaker.tier, "agent_skills")) {
+		const own = new Set(ctx.options.skills?.carriedNames(parent.name) ?? []);
+		const extra = fields.skills.filter((skill) => !own.has(skill));
+		if (extra.length > 0)
+			throw new AgentError(
+				`A temp knight can carry only skills you carry; not allowed: ${extra.join(", ")}.`,
+			);
+	}
+}
+
+/**
+ * The call's fields over the named preset: what the call gives replaces the preset's, and its
+ * skills are added after the preset's. An unknown preset is refused with the caller's names.
+ */
+export async function withPreset<T extends HelperFields>(
+	ctx: TeamContext,
+	parent: Agent,
+	input: T,
+): Promise<T> {
+	const { preset: name, ...given } = input;
+	if (!name) return input;
+	const presets = ctx.options.store.presets;
+	const preset = await presets.get(parent.name, name);
+	if (!preset) {
+		const names = (await presets.list(parent.name)).map((p) => p.name);
+		throw new AgentError(
+			names.length > 0
+				? `You have no preset "${name}". Your presets: ${names.join(", ")}.`
+				: `You have no preset "${name}", nor any other; save one with helper_preset_set.`,
+		);
+	}
+	const skills = [...new Set([...preset.skills, ...(given.skills ?? [])])];
+	const character = { ...preset.character, ...given.character };
+	return {
+		...given,
+		displayName: given.displayName ?? preset.displayName,
+		prompt: given.prompt ?? preset.prompt,
+		...(Object.keys(character).length > 0 ? { character } : {}),
+		...(skills.length > 0 ? { skills } : {}),
+		...((given.model ?? preset.model)
+			? { model: given.model ?? preset.model }
+			: {}),
+		...((given.thinking ?? preset.thinking)
+			? { thinking: given.thinking ?? preset.thinking }
+			: {}),
+	} as T;
+}
+
+/** The helper_preset tools: an agent saves, lists, and deletes its own temp-knight presets. */
+export async function presetAction(
+	ctx: TeamContext,
+	caller: AgentTurnScope,
+	action: PresetAction,
+): Promise<string> {
+	const tool = `helper_preset_${action.kind}`;
+	const { speaker, parent } = helperMaker(ctx, caller, tool);
+	const presets = ctx.options.store.presets;
+	if (action.kind === "set") {
+		const { preset } = action;
+		checkPreset(ctx, preset);
+		checkHelperGrant(ctx, speaker, parent, preset);
+		const done = await presets.set(parent.name, preset);
+		return `${done === "created" ? "Created" : "Replaced"} the preset "${preset.name}"; make its temp knight with helper_create and preset "${preset.name}".`;
+	}
+	if (action.kind === "delete") {
+		if (!(await presets.delete(parent.name, action.name)))
+			throw new AgentError(`You have no preset "${action.name}".`);
+		return `Deleted the preset "${action.name}".`;
+	}
+	if (action.name) {
+		const preset = await presets.get(parent.name, action.name);
+		if (!preset) throw new AgentError(`You have no preset "${action.name}".`);
+		return presetText(preset);
+	}
+	const all = await presets.list(parent.name);
+	if (all.length === 0)
+		return "You have no presets; save one with helper_preset_set.";
+	return all.map(presetLine).join("\n");
+}
+
+/** The checks a temp knight's fields get when it is made, applied when the preset is saved. */
+function checkPreset(ctx: TeamContext, preset: HelperPreset): void {
+	if (!PRESET_NAME.test(preset.name))
+		throw new AgentError(
+			`"${preset.name}" is not a preset name: use 1 to 32 lowercase letters, digits, and dashes.`,
+		);
+	checkDisplayName(preset.displayName);
+	checkPrompt(preset.prompt);
+	if (preset.model) checkModelRef(preset.model);
+	if (
+		preset.thinking &&
+		![...THINKING_LEVELS, "default"].includes(preset.thinking as never)
+	)
+		throw new AgentError(
+			`"${preset.thinking}" is not a thinking level; use one of ${THINKING_LEVELS.join(", ")}, or default.`,
+		);
+	if (preset.skills.length > 0) {
+		const registry = ctx.options.skills;
+		if (!registry)
+			throw new AgentError(
+				"Skills are off on this host, so a preset cannot carry any. Save it without skills.",
+			);
+		registry.checkRegistered(preset.skills);
+	}
+}
+
+const presetLine = (preset: HelperPreset): string => {
+	const prompt = preset.prompt.replace(/\s+/g, " ").trim();
+	const head = prompt.length > 80 ? `${prompt.slice(0, 80)}…` : prompt;
+	const extras = [
+		preset.skills.length > 0 ? `skills: ${preset.skills.join(", ")}` : "",
+		preset.model ? `model: ${preset.model}` : "",
+	].filter(Boolean);
+	return `${preset.name}: "${preset.displayName}"${extras.length > 0 ? ` (${extras.join("; ")})` : ""}: ${head}`;
+};
+
+const presetText = (preset: HelperPreset): string =>
+	[
+		`Preset "${preset.name}"`,
+		`Display name: ${preset.displayName}`,
+		`Skills: ${preset.skills.length > 0 ? preset.skills.join(", ") : "none"}`,
+		...(preset.character?.class ? [`Class: ${preset.character.class}`] : []),
+		...(preset.character?.palette
+			? [`Color: ${preset.character.palette}`]
+			: []),
+		...(preset.model ? [`Model: ${preset.model}`] : []),
+		...(preset.thinking ? [`Thinking: ${preset.thinking}`] : []),
+		`Prompt:\n${preset.prompt}`,
+	].join("\n");

package/src/core/agents/helper-preset-tools.ts

@@ -0,0 +1,109 @@
+import { Type } from "typebox";
+import { THINKING_LEVELS } from "../domain/models.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import {
+	optionalString,
+	requiredString,
+	stringList,
+	type TextToolDef,
+} from "../runtime/text-tools.ts";
+import { CLASS, COLOR, DISPLAY, lookOf, PROMPT } from "./agent-tool-schema.ts";
+import type { AgentOps } from "./agent-tools.ts";
+
+export const MODEL = Type.String({
+	description:
+		"The model to run on, as <provider>/<model>; left out, yours. An unusable one is refused with the usable list.",
+});
+export const THINKING = Type.Union(
+	[...THINKING_LEVELS, "default"].map((level) => Type.Literal(level)),
+	{ description: "Its thinking level; left out, yours." },
+);
+const PRESET_NAME = Type.String({
+	pattern: "^[a-z0-9-]{1,32}$",
+	description: "The preset's name: lowercase letters, digits, and dashes.",
+});
+
+/** The tools that keep a knight's temp-knight presets, which only it sees and uses. */
+export function helperPresetToolDefs(
+	ops: Pick<AgentOps, "helperPreset">,
+	scope: AgentTurnScope,
+	skillsOn: boolean,
+): TextToolDef<
+	"helper_preset_set" | "helper_preset_list" | "helper_preset_delete"
+>[] {
+	return [
+		{
+			name: "helper_preset_set",
+			label: "Save temp knight preset",
+			description:
+				"Save a temp knight you make often (its role prompt, skills, and look) as a preset, then make it with helper_create and preset instead of writing them again. Saving under a name you have replaces that preset whole. Only you see and use your presets; you may keep 20.",
+			parameters: Type.Object({
+				name: PRESET_NAME,
+				display_name: DISPLAY,
+				prompt: PROMPT,
+				class: Type.Optional(CLASS),
+				color: Type.Optional(COLOR),
+				model: Type.Optional(MODEL),
+				thinking: Type.Optional(THINKING),
+				...(skillsOn
+					? {
+							skills: Type.Optional(
+								Type.Array(Type.String(), {
+									description:
+										"Skills its temp knight carries, from skill_list.",
+								}),
+							),
+						}
+					: {}),
+			}),
+			run: (i) => {
+				const look = lookOf(i);
+				const model = optionalString(i, "model");
+				const thinking = optionalString(i, "thinking");
+				return ops.helperPreset(scope, {
+					kind: "set",
+					preset: {
+						name: requiredString(i, "name"),
+						displayName: requiredString(i, "display_name"),
+						prompt: requiredString(i, "prompt"),
+						skills: [...new Set(stringList(i, "skills") ?? [])],
+						...(Object.keys(look).length > 0 ? { character: look } : {}),
+						...(model ? { model } : {}),
+						...(thinking ? { thinking } : {}),
+					},
+				});
+			},
+		},
+		{
+			name: "helper_preset_list",
+			label: "List temp knight presets",
+			description:
+				"List your temp knight presets, one line each; with a name, show that preset in full.",
+			parameters: Type.Object({
+				name: Type.Optional(
+					Type.String({ description: "A preset to show in full." }),
+				),
+			}),
+			run: (i) => {
+				const name = optionalString(i, "name");
+				return ops.helperPreset(scope, {
+					kind: "list",
+					...(name ? { name } : {}),
+				});
+			},
+		},
+		{
+			name: "helper_preset_delete",
+			label: "Delete temp knight preset",
+			description: "Delete one of your temp knight presets.",
+			parameters: Type.Object({
+				name: Type.String({ description: "The preset's name." }),
+			}),
+			run: (i) =>
+				ops.helperPreset(scope, {
+					kind: "delete",
+					name: requiredString(i, "name"),
+				}),
+		},
+	];
+}

package/src/core/agents/helper-presets.ts

@@ -0,0 +1,128 @@
+import type { SQL } from "bun";
+import type { CharacterInput } from "../../characters/index.ts";
+import { AgentError } from "../domain/errors.ts";
+
+/** The most presets one agent may keep. */
+export const MAX_HELPER_PRESETS = 20;
+
+/** A temp knight an agent makes often: what `helper_create` takes, saved under a name. */
+export interface HelperPreset {
+	name: string;
+	displayName: string;
+	prompt: string;
+	skills: string[];
+	character?: CharacterInput;
+	model?: string;
+	thinking?: string;
+}
+
+interface Row {
+	name: string;
+	display_name: string;
+	prompt: string;
+	skills: string[] | null;
+	character: CharacterInput | null;
+	model: string | null;
+	thinking: string | null;
+}
+
+const toPreset = (row: Row): HelperPreset => ({
+	name: row.name,
+	displayName: row.display_name,
+	prompt: row.prompt,
+	skills: row.skills ?? [],
+	...(row.character ? { character: row.character } : {}),
+	...(row.model ? { model: row.model } : {}),
+	...(row.thinking ? { thinking: row.thinking } : {}),
+});
+
+/**
+ * The temp-knight presets, each owned by the agent that saved it; only that agent reads or uses
+ * them. They outlive an archive, so an agent restored finds its presets.
+ */
+export class HelperPresets {
+	readonly #sql: SQL;
+	readonly #guild: string;
+
+	constructor(sql: SQL, guildId: string) {
+		this.#sql = sql;
+		this.#guild = guildId;
+	}
+
+	/** The table, created by the agents' migrations. */
+	static readonly migration = {
+		name: "helper-presets",
+		up: async (sql: SQL) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS helper_presets (
+					guild_id text NOT NULL,
+					agent text NOT NULL,
+					name text NOT NULL,
+					display_name text NOT NULL,
+					prompt text NOT NULL,
+					skills jsonb NOT NULL DEFAULT '[]',
+					character jsonb,
+					model text,
+					thinking text,
+					updated_at timestamptz NOT NULL DEFAULT now(),
+					PRIMARY KEY (guild_id, agent, name)
+				)`;
+		},
+	};
+
+	/** The agent's presets, by name. */
+	async list(agent: string): Promise<HelperPreset[]> {
+		const rows: Row[] = await this.#sql`
+			SELECT * FROM helper_presets
+			WHERE guild_id = ${this.#guild} AND agent = ${agent} ORDER BY name`;
+		return rows.map(toPreset);
+	}
+
+	async get(agent: string, name: string): Promise<HelperPreset | undefined> {
+		const rows: Row[] = await this.#sql`
+			SELECT * FROM helper_presets
+			WHERE guild_id = ${this.#guild} AND agent = ${agent} AND name = ${name}`;
+		return rows[0] ? toPreset(rows[0]) : undefined;
+	}
+
+	/** Saves the preset whole, refusing a new one past the cap; says whether it was new. */
+	async set(
+		agent: string,
+		preset: HelperPreset,
+	): Promise<"created" | "replaced"> {
+		const guild = this.#guild;
+		return this.#sql.begin(async (tx) => {
+			// One save per agent at a time, so two cannot both pass the cap.
+			await tx`SELECT pg_advisory_xact_lock(hashtext(${`helper-presets:${guild}:${agent}`}))`;
+			const [counted]: { others: number; same: number }[] = await tx`
+				SELECT count(*) FILTER (WHERE name <> ${preset.name})::int AS others,
+					count(*) FILTER (WHERE name = ${preset.name})::int AS same
+				FROM helper_presets WHERE guild_id = ${guild} AND agent = ${agent}`;
+			const replaced = (counted?.same ?? 0) > 0;
+			if (!replaced && (counted?.others ?? 0) >= MAX_HELPER_PRESETS)
+				throw new AgentError(
+					`You have ${MAX_HELPER_PRESETS} presets, the most you may keep; delete one with helper_preset_delete or replace one by saving under its name.`,
+				);
+			await tx`
+				INSERT INTO helper_presets
+					(guild_id, agent, name, display_name, prompt, skills, character, model, thinking)
+				VALUES (${guild}, ${agent}, ${preset.name}, ${preset.displayName}, ${preset.prompt},
+					${preset.skills}::jsonb, ${preset.character ?? null}::jsonb,
+					${preset.model ?? null}, ${preset.thinking ?? null})
+				ON CONFLICT (guild_id, agent, name) DO UPDATE SET
+					display_name = EXCLUDED.display_name, prompt = EXCLUDED.prompt,
+					skills = EXCLUDED.skills, character = EXCLUDED.character,
+					model = EXCLUDED.model, thinking = EXCLUDED.thinking, updated_at = now()`;
+			return replaced ? "replaced" : "created";
+		});
+	}
+
+	/** Deletes one of the agent's presets; says whether there was one. */
+	async delete(agent: string, name: string): Promise<boolean> {
+		const rows = await this.#sql`
+			DELETE FROM helper_presets
+			WHERE guild_id = ${this.#guild} AND agent = ${agent} AND name = ${name}
+			RETURNING name`;
+		return rows.length > 0;
+	}
+}

package/src/core/agents/helper-test-kit.ts

@@ -1,6 +1,6 @@
 import { NO_ATTACHMENTS } from "../domain/attachment.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
-import type { Speaker } from "../speakers.ts";
+import type { Speaker } from "../identity/speakers.ts";
 import { OWNER_SPEAKER } from "../testing/owner.ts";
 import { agentChannel, fx, settle } from "./agent-team-fixture.ts";
 

package/src/core/agents/helper-tools.ts

@@ -1,29 +1,54 @@
 import { Type } from "typebox";
 import type { AgentTurnScope } from "../domain/ports.ts";
-import { THINKING_LEVELS } from "../models.ts";
 import {
 	optionalString,
 	requiredString,
 	stringList,
 	type TextToolDef,
 } from "../runtime/text-tools.ts";
-import { CLASS, COLOR, DISPLAY, lookOf, PROMPT } from "./agent-tool-schema.ts";
-import type { AgentOps } from "./agent-tools.ts";
+import { MAX_PROMPT_CHARS } from "./agent-rules.ts";
+import { CLASS, COLOR, lookOf } from "./agent-tool-schema.ts";
+import type { AgentOps, HELPER_TOOLS } from "./agent-tools.ts";
+import {
+	helperPresetToolDefs,
+	MODEL,
+	THINKING,
+} from "./helper-preset-tools.ts";
 
 /** The tools that make and end a knight's temp knights. */
 export function helperToolDefs(
 	ops: AgentOps,
 	scope: AgentTurnScope,
 	skillsOn: boolean,
-): TextToolDef<"helper_create" | "helper_end">[] {
+): TextToolDef<(typeof HELPER_TOOLS)[number]>[] {
 	return [
 		{
 			name: "helper_create",
 			label: "Create temp knight",
-			description: `Make a temp knight (a helper knight) for one self-contained task that can run on its own, such as one of several things to look up or compare. It is a real agent with its own picture and place, listed under you; it starts at once and its answer comes back to you here as a new turn, like message_agent's. Make one per task, then end your turn; when the answers are in, merge them and clear the ones that are done with helper_end. It runs your model unless you give one, cannot make knights, temp knights or groups, and has no schedules. You may have a few at once, and when you are at the limit your oldest finished one is archived to make room.`,
+			description: `Make a temp knight (a helper knight) for one self-contained task that can run on its own, such as one of several things to look up or compare. It is a real agent with its own picture and place, listed under you; it starts at once and its answer comes back to you here as a new turn, like message_agent's. Make one per task, then end your turn; when the answers are in, merge them and clear the ones that are done with helper_end. It runs your model unless you give one, cannot make knights, temp knights or groups, and has no schedules. You may have a few at once, and when you are at the limit your oldest finished one is archived to make room. A temp knight you make often can be saved as a preset (helper_preset_set) and made by its name: what you give in the call replaces the preset's, and skills you give are added to the preset's.`,
 			parameters: Type.Object({
-				display_name: DISPLAY,
-				prompt: PROMPT,
+				preset: Type.Optional(
+					Type.String({
+						description:
+							"A preset of yours, from helper_preset_list, that gives what you leave out here.",
+					}),
+				),
+				display_name: Type.Optional(
+					Type.String({
+						minLength: 1,
+						maxLength: 32,
+						description:
+							"The name shown on its messages; any language. Required unless a preset gives it; given, it replaces the preset's.",
+					}),
+				),
+				prompt: Type.Optional(
+					Type.String({
+						minLength: 1,
+						maxLength: MAX_PROMPT_CHARS,
+						description:
+							"Its role prompt, in English: its job, sources, boundaries, and how it reports. Required unless a preset gives it; given, it replaces the preset's.",
+					}),
+				),
 				task: Type.String({
 					minLength: 1,
 					maxLength: 4000,
@@ -39,24 +64,14 @@ export function helperToolDefs(
 				),
 				class: Type.Optional(CLASS),
 				color: Type.Optional(COLOR),
-				model: Type.Optional(
-					Type.String({
-						description:
-							"The model to run on, as <provider>/<model>; left out, yours. An unusable one is refused with the usable list.",
-					}),
-				),
-				thinking: Type.Optional(
-					Type.Union(
-						[...THINKING_LEVELS, "default"].map((level) => Type.Literal(level)),
-						{ description: "Its thinking level; left out, yours." },
-					),
-				),
+				model: Type.Optional(MODEL),
+				thinking: Type.Optional(THINKING),
 				...(skillsOn
 					? {
 							skills: Type.Optional(
 								Type.Array(Type.String(), {
 									description:
-										"Skills it carries, from skill_list; pick those the task needs.",
+										"Skills it carries, from skill_list; pick those the task needs. With a preset, added to the preset's.",
 								}),
 							),
 						}
@@ -68,9 +83,13 @@ export function helperToolDefs(
 				const thinking = optionalString(i, "thinking");
 				const skills = stringList(i, "skills");
 				const look = lookOf(i);
+				const preset = optionalString(i, "preset");
+				const displayName = optionalString(i, "display_name");
+				const prompt = optionalString(i, "prompt");
 				return ops.helperCreate(scope, {
-					displayName: requiredString(i, "display_name"),
-					prompt: requiredString(i, "prompt"),
+					...(preset ? { preset } : {}),
+					...(displayName ? { displayName } : {}),
+					...(prompt ? { prompt } : {}),
 					task: requiredString(i, "task"),
 					...(name ? { name } : {}),
 					...(Object.keys(look).length > 0 ? { character: look } : {}),
@@ -100,5 +119,6 @@ export function helperToolDefs(
 					i.names === "finished" ? "finished" : (stringList(i, "names") ?? []),
 				),
 		},
+		...helperPresetToolDefs(ops, scope, skillsOn),
 	];
 }

package/src/core/agents/helper-work.ts

@@ -1,6 +1,6 @@
 import type { QueuePort } from "../contract/channels.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
-import type { Logger } from "../log.ts";
+import type { Logger } from "../kernel/log.ts";
 import type { AgentTurnRunner } from "./agent-ports.ts";
 import { isHelper } from "./agent-rules.ts";
 import type { PgAgentStore } from "./agent-store.ts";