@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/extensibility/skills.ts

@@ -1,6 +1,11 @@
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import { getProjectDir } from "@prometheus-ai/utils";
+import {
+	isValidManagedSkillName,
+	MANAGED_SKILLS_PROVIDER_ID,
+	sanitizeManagedDescription,
+} from "../autolearn/managed-skills";
 import { skillCapability } from "../capability/skill";
 import type { SourceMeta } from "../capability/types";
 import type { SkillsSettings } from "../config/settings";
@@ -54,6 +59,26 @@ export function resetActiveSkillsForTests(): void {
 	activeSkills = [];
 }
 
+/**
+ * Whether `name` is already claimed by an active authored (non-managed) skill.
+ *
+ * Managed (auto-learn) skills resolve dead-last in discovery, so an authored
+ * skill of the same name always wins (see `loadSkills`) and a managed skill
+ * written under an authored name is silently dropped — it never surfaces.
+ * `manage_skill` create consults this to refuse the write up front instead of
+ * reporting a false "Created" for a skill that can never appear.
+ */
+export function isNameClaimedByAuthoredSkill(name: string): boolean {
+	return getActiveSkills().some(
+		skill =>
+			skillNameKey(skill.name) === skillNameKey(name) && skill._source?.provider !== MANAGED_SKILLS_PROVIDER_ID,
+	);
+}
+
+function skillNameKey(name: string): string {
+	return name.trim().toLowerCase();
+}
+
 export interface LoadSkillsFromDirOptions {
 	/** Directory to scan for skills */
 	dir: string;
@@ -105,31 +130,45 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		enableCodexUser = true,
 		enableClaudeUser = true,
 		enableClaudeProject = true,
+		enablePiUser = true,
+		enablePiProject = true,
+		enableAgentsUser = true,
+		enableAgentsProject = true,
 		customDirectories = [],
 		ignoredSkills = [],
 		includeSkills = [],
 		disabledExtensions = [],
 	} = options;
-	const enablePrometheusUser = options.enablePrometheusUser ?? true;
-	const enablePrometheusProject = options.enablePrometheusProject ?? true;
 
 	// Early return if skills are disabled
 	if (!enabled) {
 		return { skills: [], warnings: [] };
 	}
+	// Fall-through gate for third-party CLI providers (claude-plugins, opencode,
+	// gemini, github, ...) that share user intent with the named third-party
+	// source toggles but don't have a dedicated control of their own. Only the
+	// third-party toggles count here: the Prometheus-native providers (`agents`,
+	// `native`) get explicit branches in `isSourceEnabled` below, so folding
+	// them into the fallback would re-enable unrelated third-party CLIs whenever
+	// the user kept the default `.agent[s]/skills` toggles on while turning off
+	// Codex/Claude/Pi (issue #2401 / PR #2405 review).
+	const anyThirdPartySkillToggleEnabled =
+		enableCodexUser || enableClaudeUser || enableClaudeProject || enablePiUser || enablePiProject;
 
-	const anyBuiltInSkillSourceEnabled =
-		enableCodexUser || enableClaudeUser || enableClaudeProject || enablePrometheusUser || enablePrometheusProject;
-	// Helper to check if a source is enabled
 	function isSourceEnabled(source: SourceMeta): boolean {
 		const { provider, level } = source;
+		// Managed skills (auto-learn) are Prometheus-native and discovered unconditionally
+		// — third-party CLI toggles must never silently hide them (cf. #2401). The
+		// master `enabled` flag above still gates them.
+		if (provider === MANAGED_SKILLS_PROVIDER_ID) return true;
 		if (provider === "codex" && level === "user") return enableCodexUser;
 		if (provider === "claude" && level === "user") return enableClaudeUser;
 		if (provider === "claude" && level === "project") return enableClaudeProject;
-		if (provider === "native" && level === "user") return enablePrometheusUser;
-		if (provider === "native" && level === "project") return enablePrometheusProject;
-		// For other providers (agents, claude-plugins, etc.), treat them as built-in skill sources.
-		return anyBuiltInSkillSourceEnabled;
+		if (provider === "native" && level === "user") return enablePiUser;
+		if (provider === "native" && level === "project") return enablePiProject;
+		if (provider === "agents" && level === "user") return enableAgentsUser;
+		if (provider === "agents" && level === "project") return enableAgentsProject;
+		return anyThirdPartySkillToggleEnabled;
 	}
 
 	// Use capability API to load all skills
@@ -162,6 +201,15 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		if (!matchesIncludePatterns(capSkill.name)) return false;
 		return true;
 	});
+	const enabledAuthoredSkillNames = new Set<string>();
+	for (const capSkill of result.all) {
+		if (capSkill._source.provider === MANAGED_SKILLS_PROVIDER_ID) continue;
+		if (disabledSkillNames.has(capSkill.name)) continue;
+		if (!isSourceEnabled(capSkill._source)) continue;
+		if (matchesIgnorePatterns(capSkill.name)) continue;
+		if (!matchesIncludePatterns(capSkill.name)) continue;
+		enabledAuthoredSkillNames.add(skillNameKey(capSkill.name));
+	}
 
 	// Batch resolve all real paths in parallel
 	const realPaths = await Promise.all(
@@ -177,6 +225,9 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	// Process skills with resolved paths
 	for (let i = 0; i < filteredSkills.length; i++) {
 		const capSkill = filteredSkills[i];
+		// Managed (auto-learn) skills are resolved dead-last (below) so any
+		// authored skill of the same name — from ANY provider or custom dir — wins.
+		if (capSkill._source.provider === MANAGED_SKILLS_PROVIDER_ID) continue;
 		const resolvedPath = realPaths[i];
 
 		// Skip silently if we've already loaded this exact file (via symlink)
@@ -256,6 +307,7 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	for (let i = 0; i < allCustomSkills.length; i++) {
 		const { skill } = allCustomSkills[i];
 		const resolvedPath = customRealPaths[i];
+		enabledAuthoredSkillNames.add(skillNameKey(skill.name));
 		if (realPathSet.has(resolvedPath)) continue;
 
 		const existing = skillMap.get(skill.name);
@@ -270,6 +322,58 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		}
 	}
 
+	// Managed (auto-learn) skills resolve dead-last with first-wins. Source from
+	// result.all (pre-dedup): capability-level dedup runs BEFORE isSourceEnabled,
+	// so a managed skill can be shadowed by a higher-priority authored skill that
+	// is itself disabled here — managed must stay visible regardless of toggles.
+	// Validate the on-disk name (a hand-placed managed file could carry an unsafe
+	// frontmatter name) and re-sanitize the description on read. Descriptions and
+	// names both render unescaped into the system prompt.
+	const managedCandidates = result.all.filter(
+		capSkill =>
+			capSkill._source.provider === MANAGED_SKILLS_PROVIDER_ID &&
+			isValidManagedSkillName(capSkill.name) &&
+			!disabledSkillNames.has(capSkill.name) &&
+			!matchesIgnorePatterns(capSkill.name) &&
+			matchesIncludePatterns(capSkill.name),
+	);
+	// Names claimed by any ENABLED authored skill (from the pre-dedup superset).
+	// Managed defers to these even when capability dedup hid an enabled authored
+	// skill behind a disabled higher-priority one, so managed never masks it.
+	const managedRealPaths = await Promise.all(
+		managedCandidates.map(async capSkill => {
+			try {
+				return await fs.realpath(capSkill.path);
+			} catch {
+				return capSkill.path;
+			}
+		}),
+	);
+	for (let i = 0; i < managedCandidates.length; i++) {
+		const capSkill = managedCandidates[i];
+		const resolvedPath = managedRealPaths[i];
+		if (realPathSet.has(resolvedPath)) continue;
+		if (enabledAuthoredSkillNames.has(skillNameKey(capSkill.name))) continue; // an enabled authored skill owns this name
+		// Already claimed — e.g. by a custom-directory skill. LOAD-BEARING: custom
+		// dirs also populate `enabledAuthoredSkillNames` above; this map check is
+		// the final veto that lets an authored skill win over a same-named managed one.
+		// The custom-dir loop (which populates
+		// skillMap, ~30 lines up) MUST run before this block — do not reorder.
+		if (skillMap.has(capSkill.name)) continue;
+		const rawDescription =
+			typeof capSkill.frontmatter?.description === "string" ? capSkill.frontmatter.description : "";
+		skillMap.set(capSkill.name, {
+			name: capSkill.name,
+			description: sanitizeManagedDescription(rawDescription),
+			filePath: capSkill.path,
+			baseDir: capSkill.path.replace(/[\\/]SKILL\.md$/, ""),
+			source: `${capSkill._source.provider}:${capSkill.level}`,
+			hide: capSkill.frontmatter?.hide === true || capSkill.frontmatter?.disableModelInvocation === true,
+			_source: capSkill._source,
+		});
+		realPathSet.add(resolvedPath);
+	}
+
 	const skills = Array.from(skillMap.values());
 	// Deterministic ordering for prompt stability (case-insensitive, then exact name, then path).
 	skills.sort((a, b) => compareSkillOrder(a.name, a.filePath, b.name, b.filePath));

package/src/extensibility/slash-commands.ts

@@ -1,14 +1,8 @@
-import type { AutocompleteItem } from "@prometheus-ai/tui";
 import { parseFrontmatter, prompt } from "@prometheus-ai/utils";
 import { slashCommandCapability } from "../capability/slash-command";
 import { appendInlineArgsFallback, templateUsesInlineArgPlaceholders } from "../config/prompt-templates";
 import type { SlashCommand } from "../discovery";
 import { loadCapability } from "../discovery";
-import {
-	BUILTIN_SLASH_COMMAND_DEFS,
-	type BuiltinSlashCommand,
-	type SubcommandDef,
-} from "../slash-commands/builtin-registry";
 import { EMBEDDED_COMMAND_TEMPLATES } from "../task/commands";
 import { parseCommandArgs, substituteArgs } from "../utils/command-args";
 
@@ -24,97 +18,7 @@ export interface SlashCommandInfo {
 	path?: string;
 }
 
-export type { BuiltinSlashCommand, SubcommandDef } from "../slash-commands/builtin-registry";
-
-/**
- * Build getArgumentCompletions from declarative subcommand definitions.
- * Returns subcommand names filtered by prefix in the dropdown.
- */
-function buildArgumentCompletions(subcommands: SubcommandDef[]): (prefix: string) => AutocompleteItem[] | null {
-	return (argumentPrefix: string) => {
-		if (argumentPrefix.includes(" ")) return null; // past the subcommand
-		const lower = argumentPrefix.toLowerCase();
-		const matches = subcommands
-			.filter(s => s.name.startsWith(lower))
-			.map(s => ({
-				value: `${s.name} `,
-				label: s.name,
-				description: s.description,
-				hint: s.usage,
-			}));
-		return matches.length > 0 ? matches : null;
-	};
-}
-
-/**
- * Build getInlineHint from declarative subcommand definitions.
- * Shows remaining completion + usage as dim ghost text after cursor.
- */
-function buildSubcommandInlineHint(subcommands: SubcommandDef[]): (argumentText: string) => string | null {
-	return (argumentText: string) => {
-		const trimmed = argumentText.trimStart();
-		const spaceIndex = trimmed.indexOf(" ");
-
-		if (spaceIndex === -1) {
-			// Still typing subcommand name — show remaining chars + usage
-			const prefix = trimmed.toLowerCase();
-			if (prefix.length === 0) return null;
-			const match = subcommands.find(s => s.name.startsWith(prefix));
-			if (!match) return null;
-			const remaining = match.name.slice(prefix.length);
-			return remaining + (match.usage ? ` ${match.usage}` : "");
-		}
-
-		// Subcommand typed — show remaining usage params
-		const subName = trimmed.slice(0, spaceIndex).toLowerCase();
-		const afterSub = trimmed.slice(spaceIndex + 1);
-		const sub = subcommands.find(s => s.name === subName);
-		if (!sub?.usage) return null;
-
-		if (afterSub.length > 0) {
-			const usageParts = sub.usage.split(" ");
-			const inputParts = afterSub.trim().split(/\s+/);
-			const remaining = usageParts.slice(inputParts.length);
-			return remaining.length > 0 ? remaining.join(" ") : null;
-		}
-
-		return sub.usage;
-	};
-}
-
-/**
- * Build getInlineHint for commands with a simple static hint string.
- * Shows the hint only when no arguments have been typed yet.
- */
-function buildStaticInlineHint(hint: string): (argumentText: string) => string | null {
-	return (argumentText: string) => (argumentText.trim().length === 0 ? hint : null);
-}
-
-/**
- * Materialized builtin slash commands with completion functions derived from
- * declarative subcommand/hint definitions.
- */
-export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<
-	BuiltinSlashCommand & {
-		getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null;
-		getInlineHint?: (argumentText: string) => string | null;
-	}
-> = BUILTIN_SLASH_COMMAND_DEFS.map(cmd => {
-	if (cmd.subcommands) {
-		return {
-			...cmd,
-			getArgumentCompletions: buildArgumentCompletions(cmd.subcommands),
-			getInlineHint: buildSubcommandInlineHint(cmd.subcommands),
-		};
-	}
-	if (cmd.inlineHint) {
-		return {
-			...cmd,
-			getInlineHint: buildStaticInlineHint(cmd.inlineHint),
-		};
-	}
-	return cmd;
-});
+export type { BuiltinSlashCommand, SubcommandDef } from "../slash-commands/types";
 
 /**
  * Represents a custom slash command loaded from a file

package/src/gateway/adapters/telegram/access.ts

@@ -2,17 +2,26 @@ import type { GatewayEvent } from "../../types";
 
 export interface TelegramGatewayAccessPolicy {
 	allowedUserIds: string[];
+	allowedChatIds?: string[];
 }
 
 export type TelegramGatewayAuthorizer = (event: GatewayEvent) => boolean | Promise<boolean>;
 
-export function createTelegramUserAllowlistPolicy(userIds: Iterable<string>): TelegramGatewayAccessPolicy | undefined {
+export function createTelegramUserAllowlistPolicy(
+	userIds: Iterable<string>,
+	chatIds: Iterable<string> = [],
+): TelegramGatewayAccessPolicy | undefined {
 	const allowedUserIds = normalizeTelegramUserIds(userIds);
-	return allowedUserIds.length === 0 ? undefined : { allowedUserIds };
+	const allowedChatIds = normalizeTelegramChatIds(chatIds);
+	if (allowedUserIds.length === 0 && allowedChatIds.length === 0) return undefined;
+	return {
+		allowedUserIds,
+		...(allowedChatIds.length > 0 ? { allowedChatIds } : {}),
+	};
 }
 
 export function isTelegramGatewayAccessRestricted(policy: TelegramGatewayAccessPolicy | undefined): boolean {
-	return (policy?.allowedUserIds.length ?? 0) > 0;
+	return (policy?.allowedUserIds.length ?? 0) > 0 || (policy?.allowedChatIds?.length ?? 0) > 0;
 }
 
 export function isTelegramGatewayEventAuthorized(
@@ -21,7 +30,9 @@ export function isTelegramGatewayEventAuthorized(
 ): boolean {
 	if (!policy || !isTelegramGatewayAccessRestricted(policy)) return true;
 	const userId = event.source.userId?.trim();
-	return userId !== undefined && policy.allowedUserIds.includes(userId);
+	if (userId !== undefined && policy.allowedUserIds.includes(userId)) return true;
+	const chatId = event.source.chatId.trim();
+	return chatId.length > 0 && (policy.allowedChatIds?.includes(chatId) ?? false);
 }
 
 export function normalizeTelegramUserIds(userIds: Iterable<string>): string[] {
@@ -36,6 +47,18 @@ export function normalizeTelegramUserIds(userIds: Iterable<string>): string[] {
 	return normalized;
 }
 
+export function normalizeTelegramChatIds(chatIds: Iterable<string>): string[] {
+	const normalized: string[] = [];
+	const seen = new Set<string>();
+	for (const chatId of chatIds) {
+		const value = normalizeTelegramSignedIntegerId(chatId, "Telegram chat id");
+		if (seen.has(value)) continue;
+		seen.add(value);
+		normalized.push(value);
+	}
+	return normalized;
+}
+
 export function normalizeTelegramPositiveIntegerId(value: string, label: string): string {
 	const trimmed = value.trim();
 	if (!/^[0-9]+$/u.test(trimmed)) {
@@ -48,6 +71,18 @@ export function normalizeTelegramPositiveIntegerId(value: string, label: string)
 	return String(numeric);
 }
 
+export function normalizeTelegramSignedIntegerId(value: string, label: string): string {
+	const trimmed = value.trim();
+	if (!/^-?[0-9]+$/u.test(trimmed)) {
+		throw new Error(`${label} must be an integer`);
+	}
+	const numeric = Number(trimmed);
+	if (!Number.isSafeInteger(numeric) || numeric === 0) {
+		throw new Error(`${label} must be a non-zero safe integer`);
+	}
+	return String(numeric);
+}
+
 export function toTelegramPositiveIntegerId(value: string, label: string): number {
 	return Number(normalizeTelegramPositiveIntegerId(value, label));
 }

package/src/gateway/adapters/telegram/normalize.ts

@@ -3,6 +3,7 @@ import type {
 	GatewayChatType,
 	GatewayEvent,
 	GatewayEventFeatures,
+	GatewayEventKind,
 	GatewayLocation,
 	GatewayMediaAttachment,
 	GatewayMediaVariant,
@@ -19,7 +20,8 @@ export function normalizeTelegramUpdate(
 	update: TelegramUpdate,
 	options: TelegramNormalizeOptions = {},
 ): GatewayEvent | undefined {
-	const message = update.message;
+	const messageUpdate = getTelegramMessageUpdate(update);
+	const message = messageUpdate?.message;
 	if (!message) return undefined;
 	const messageUser = message.from ?? message.direct_messages_topic?.user;
 	if (messageUser?.is_bot && !options.allowBotMessages) return undefined;
@@ -47,6 +49,7 @@ export function normalizeTelegramUpdate(
 		text,
 		receivedAt,
 	};
+	if (messageUpdate.kind !== "message") event.kind = messageUpdate.kind;
 	if (media.length > 0) event.media = media;
 	if (features !== undefined) event.features = features;
 
@@ -72,6 +75,18 @@ export function normalizeTelegramUpdate(
 	return event;
 }
 
+function getTelegramMessageUpdate(
+	update: TelegramUpdate,
+): { kind: Exclude<GatewayEventKind, "callback_query">; message: TelegramMessage } | undefined {
+	if (update.message !== undefined) return { kind: "message", message: update.message };
+	if (update.edited_message !== undefined) return { kind: "edited_message", message: update.edited_message };
+	if (update.channel_post !== undefined) return { kind: "channel_post", message: update.channel_post };
+	if (update.edited_channel_post !== undefined) {
+		return { kind: "edited_channel_post", message: update.edited_channel_post };
+	}
+	return undefined;
+}
+
 export function normalizeTelegramCallbackQuery(
 	update: TelegramUpdate,
 	options: TelegramNormalizeOptions = {},

package/src/gateway/adapters/telegram/setup-api.ts

@@ -6,7 +6,13 @@ import {
 } from "./send-message";
 import type { TelegramUpdate, TelegramUser } from "./types";
 
-export const TELEGRAM_GATEWAY_ALLOWED_UPDATES = ["message", "callback_query"] as const;
+export const TELEGRAM_GATEWAY_ALLOWED_UPDATES = [
+	"message",
+	"edited_message",
+	"channel_post",
+	"edited_channel_post",
+	"callback_query",
+] as const;
 
 export interface TelegramSetupApiOptions {
 	apiBaseUrl?: string;

package/src/gateway/adapters/telegram/webhook.ts

@@ -33,7 +33,12 @@ export const TELEGRAM_UPDATE_TYPES = [
 ] as const;
 
 export type TelegramUpdateType = (typeof TELEGRAM_UPDATE_TYPES)[number];
-export type TelegramRoutableUpdateType = "message" | "callback_query";
+export type TelegramRoutableUpdateType =
+	| "message"
+	| "edited_message"
+	| "channel_post"
+	| "edited_channel_post"
+	| "callback_query";
 
 export type TelegramWebhookIgnoreReason =
 	| "unsupported_update_type"
@@ -170,7 +175,7 @@ export async function processTelegramUpdate(
 			}
 			event = normalizeTelegramCallbackQuery(update, options);
 		} else {
-			if (!hasTelegramMessageEnvelope(update)) {
+			if (!hasTelegramMessageEnvelope(update, updateType)) {
 				return rejectWebhook(400, "invalid_json_update");
 			}
 			event = normalizeTelegramUpdate(update, options);
@@ -223,7 +228,13 @@ export function getTelegramUpdateType(update: TelegramUpdate): TelegramUpdateTyp
 export function isRoutableUpdateType(
 	updateType: TelegramUpdateType | undefined,
 ): updateType is TelegramRoutableUpdateType {
-	return updateType === "message" || updateType === "callback_query";
+	return (
+		updateType === "message" ||
+		updateType === "edited_message" ||
+		updateType === "channel_post" ||
+		updateType === "edited_channel_post" ||
+		updateType === "callback_query"
+	);
 }
 
 export function isValidTelegramWebhookSecretToken(secretToken: string): boolean {
@@ -256,8 +267,8 @@ function getTelegramCallbackQueryId(update: TelegramUpdate): string | undefined
 	return normalized ? normalized : undefined;
 }
 
-function hasTelegramMessageEnvelope(update: TelegramUpdate): boolean {
-	const message = (update as unknown as Record<string, unknown>).message;
+function hasTelegramMessageEnvelope(update: TelegramUpdate, updateType: TelegramRoutableUpdateType): boolean {
+	const message = getTelegramMessageEnvelope(update, updateType);
 	if (!isRecord(message)) return false;
 
 	const chat = message.chat;
@@ -273,6 +284,16 @@ function hasTelegramMessageEnvelope(update: TelegramUpdate): boolean {
 	);
 }
 
+function getTelegramMessageEnvelope(update: TelegramUpdate, updateType: TelegramRoutableUpdateType): unknown {
+	if (updateType === "message") return (update as unknown as Record<string, unknown>).message;
+	if (updateType === "edited_message") return (update as unknown as Record<string, unknown>).edited_message;
+	if (updateType === "channel_post") return (update as unknown as Record<string, unknown>).channel_post;
+	if (updateType === "edited_channel_post") {
+		return (update as unknown as Record<string, unknown>).edited_channel_post;
+	}
+	return undefined;
+}
+
 function isValidTelegramChatId(value: unknown): boolean {
 	if (typeof value === "number") return Number.isSafeInteger(value);
 	if (typeof value === "string") return value.trim().length > 0;

package/src/gateway/context.ts

@@ -72,10 +72,18 @@ export function renderGatewayEventPrompt(event: GatewayEvent): string {
 	if (event.text.trim().length === 0) {
 		throw new Error("Gateway event text cannot be empty");
 	}
-	const label = event.kind === "callback_query" ? "Gateway user action" : "Gateway user message";
+	const label = getGatewayPromptLabel(event.kind);
 	return `${renderGatewayEventContext(event)}\n\n${label}:\n${event.text}`;
 }
 
+function getGatewayPromptLabel(kind: GatewayEvent["kind"]): string {
+	if (kind === "callback_query") return "Gateway user action";
+	if (kind === "edited_message") return "Gateway edited user message";
+	if (kind === "channel_post") return "Gateway channel post";
+	if (kind === "edited_channel_post") return "Gateway edited channel post";
+	return "Gateway user message";
+}
+
 function addInteraction(
 	payload: GatewayEventContextPayload,
 	interaction: GatewayEvent["interaction"] | undefined,

package/src/gateway/types.ts

@@ -4,7 +4,7 @@ export type GatewayChatType = "direct" | "group" | "supergroup" | "channel";
 
 export type GatewayParticipantScope = "shared" | "per-user";
 
-export type GatewayEventKind = "message" | "callback_query";
+export type GatewayEventKind = "message" | "edited_message" | "channel_post" | "edited_channel_post" | "callback_query";
 
 export interface GatewayCallbackInteraction {
 	type: "callback_query";

package/src/goals/guided-setup.ts

@@ -0,0 +1,133 @@
+import { instrumentedCompleteSimple, resolveTelemetry } from "@prometheus-ai/agent-core";
+import type { Tool } from "@prometheus-ai/ai";
+import { prompt } from "@prometheus-ai/utils";
+import { extractTextContent, extractToolCall, parseJsonPayload } from "../commit/utils";
+import guidedGoalInterviewPrompt from "../prompts/goals/guided-goal-interview.md" with { type: "text" };
+import guidedGoalSystemPrompt from "../prompts/goals/guided-goal-system.md" with { type: "text" };
+import type { AgentSession } from "../session/agent-session";
+import { toReasoningEffort } from "../thinking";
+
+const RESPOND_TOOL_NAME = "respond";
+
+const RESPOND_TOOL: Tool = {
+	name: RESPOND_TOOL_NAME,
+	description: "Return the next guided-goal interview step.",
+	parameters: {
+		type: "object",
+		properties: {
+			kind: { type: "string", enum: ["question", "ready"] },
+			question: { type: "string" },
+			objective: { type: "string" },
+		},
+		required: ["kind"],
+		additionalProperties: false,
+	},
+	strict: false,
+};
+
+export interface GuidedGoalMessage {
+	role: "user" | "assistant";
+	content: string;
+}
+
+export type GuidedGoalTurnResult =
+	| { kind: "question"; question: string; objective?: string }
+	| { kind: "ready"; objective: string };
+
+export interface GuidedGoalTurnOptions {
+	messages: readonly GuidedGoalMessage[];
+	signal?: AbortSignal;
+}
+
+function parseGuidedGoalPayload(value: unknown): GuidedGoalTurnResult {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("guided goal returned an invalid response");
+	}
+	const payload = value as Record<string, unknown>;
+	if (payload.kind === "question" && typeof payload.question === "string" && payload.question.trim()) {
+		const question = payload.question.trim();
+		if (typeof payload.objective === "string" && payload.objective.trim()) {
+			return { kind: "question", question, objective: payload.objective.trim() };
+		}
+		return { kind: "question", question };
+	}
+	if (payload.kind === "ready" && typeof payload.objective === "string" && payload.objective.trim()) {
+		return { kind: "ready", objective: payload.objective.trim() };
+	}
+	throw new Error("guided goal returned an invalid response");
+}
+
+function parseToolArguments(value: unknown): unknown {
+	return typeof value === "string" ? parseJsonPayload(value) : value;
+}
+
+export async function runGuidedGoalTurn(
+	session: AgentSession,
+	options: GuidedGoalTurnOptions,
+): Promise<GuidedGoalTurnResult> {
+	const plan = session.resolveRoleModelWithThinking("plan");
+	const resolved = plan.model ? plan : session.resolveRoleModelWithThinking("slow");
+	if (!resolved.model) {
+		throw new Error("No plan or slow model is available for /guided-goal.");
+	}
+
+	const apiKey = await session.modelRegistry.getApiKey(resolved.model, session.sessionId);
+	if (!apiKey) {
+		throw new Error(`No API key for ${resolved.model.provider}/${resolved.model.id}`);
+	}
+
+	const userPrompt = prompt.render(guidedGoalInterviewPrompt, {
+		messages: options.messages.map(message => ({ label: message.role.toUpperCase(), content: message.content })),
+	});
+	// Secret obfuscation: route the user-authored transcript through the session obfuscator the
+	// same way normal turns do, so an API key / secret typed into the rough goal or an answer is
+	// never sent verbatim to the plan/slow provider. Deobfuscated again below before display/use.
+	const obfuscator = session.obfuscator;
+	const promptText = obfuscator?.hasSecrets() ? obfuscator.obfuscate(userPrompt) : userPrompt;
+	const response = await instrumentedCompleteSimple(
+		resolved.model,
+		{
+			systemPrompt: [prompt.render(guidedGoalSystemPrompt)],
+			messages: [{ role: "user", content: [{ type: "text", text: promptText }], timestamp: Date.now() }],
+			tools: [RESPOND_TOOL],
+		},
+		{
+			apiKey: session.modelRegistry.resolver(resolved.model, session.sessionId),
+			signal: options.signal,
+			reasoning: toReasoningEffort(resolved.thinkingLevel),
+			toolChoice: { type: "tool", name: RESPOND_TOOL_NAME },
+		},
+		{ telemetry: resolveTelemetry(session.agent.telemetry, session.sessionId), oneshotKind: "guided_goal_setup" },
+	);
+
+	if (response.stopReason === "error") {
+		throw new Error(response.errorMessage ?? "guided goal request failed");
+	}
+	if (response.stopReason === "aborted") {
+		throw new Error("guided goal request aborted");
+	}
+
+	const call = extractToolCall(response, RESPOND_TOOL_NAME);
+	let result: GuidedGoalTurnResult;
+	if (call) {
+		result = parseGuidedGoalPayload(parseToolArguments(call.arguments));
+	} else {
+		const text = extractTextContent(response);
+		if (!text) {
+			throw new Error("guided goal returned an invalid response");
+		}
+		result = parseGuidedGoalPayload(parseJsonPayload(text));
+	}
+
+	// Reverse the obfuscation: restore any secret placeholders the model echoed back before the
+	// question/objective is shown or the goal is started.
+	if (!obfuscator?.hasSecrets()) return result;
+	if (result.kind === "question") {
+		return {
+			kind: "question",
+			question: obfuscator.deobfuscate(result.question),
+			objective: result.objective !== undefined ? obfuscator.deobfuscate(result.objective) : undefined,
+		};
+	}
+	return { kind: "ready", objective: obfuscator.deobfuscate(result.objective) };
+}

package/src/goals/state.ts

@@ -1,4 +1,4 @@
-import type { UsageStatistics } from "../session/session-manager";
+import type { UsageStatistics } from "../session/session-entries";
 
 export type GoalStatus = "active" | "paused" | "budget-limited" | "complete" | "dropped";