@pellux/goodvibes-agent 0.1.117 → 1.0.0

package/src/agent/note-registry.ts

@@ -0,0 +1,329 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import { assertNoSecretLikeText } from './persona-registry.ts';
+
+export type AgentNoteSource = 'user' | 'agent' | 'imported' | 'system';
+export type AgentNoteReviewState = 'fresh' | 'reviewed' | 'stale';
+
+export interface AgentNoteRecord {
+  readonly id: string;
+  readonly title: string;
+  readonly body: string;
+  readonly tags: readonly string[];
+  readonly sourceUrl?: string;
+  readonly source: AgentNoteSource;
+  readonly provenance: string;
+  readonly reviewState: AgentNoteReviewState;
+  readonly staleReason?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly reviewedAt?: string;
+}
+
+export interface AgentNoteCreateInput {
+  readonly title: string;
+  readonly body: string;
+  readonly tags?: readonly string[];
+  readonly sourceUrl?: string;
+  readonly source?: AgentNoteSource;
+  readonly provenance?: string;
+}
+
+export interface AgentNoteUpdateInput {
+  readonly title?: string;
+  readonly body?: string;
+  readonly tags?: readonly string[];
+  readonly sourceUrl?: string;
+  readonly provenance?: string;
+}
+
+export interface AgentNoteSnapshot {
+  readonly path: string;
+  readonly notes: readonly AgentNoteRecord[];
+  readonly reviewQueue: readonly AgentNoteRecord[];
+}
+
+interface NoteStoreFile {
+  readonly version: 1;
+  readonly notes: readonly AgentNoteRecord[];
+}
+
+const STORE_VERSION = 1;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readString(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function readStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function normalizeTitle(title: string): string {
+  return title.trim().replace(/\s+/g, ' ');
+}
+
+function normalizeList(values: readonly string[] | undefined): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values ?? []) {
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    const key = trimmed.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(trimmed);
+  }
+  return result;
+}
+
+function slugify(value: string): string {
+  const slug = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return slug || 'note';
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function assertNoNoteSecretLikeText(fields: readonly string[]): void {
+  try {
+    assertNoSecretLikeText(fields);
+  } catch {
+    throw new Error('Notes cannot store secret-looking values. Store a secret reference or remove the sensitive text.');
+  }
+}
+
+function parseNote(value: unknown): AgentNoteRecord | null {
+  if (!isRecord(value)) return null;
+  const id = readString(value.id).trim();
+  const title = normalizeTitle(readString(value.title));
+  const body = readString(value.body).trim();
+  if (!id || !title || !body) return null;
+  const reviewState = value.reviewState === 'reviewed' || value.reviewState === 'stale' ? value.reviewState : 'fresh';
+  const source = value.source === 'agent' || value.source === 'imported' || value.source === 'system' ? value.source : 'user';
+  const sourceUrl = readString(value.sourceUrl).trim();
+  const staleReason = readString(value.staleReason).trim();
+  const reviewedAt = readString(value.reviewedAt).trim();
+  return {
+    id,
+    title,
+    body,
+    tags: readStringArray(value.tags),
+    sourceUrl: sourceUrl || undefined,
+    source,
+    provenance: readString(value.provenance, source).trim() || source,
+    reviewState,
+    staleReason: staleReason || undefined,
+    createdAt: readString(value.createdAt, nowIso()),
+    updatedAt: readString(value.updatedAt, nowIso()),
+    reviewedAt: reviewedAt || undefined,
+  };
+}
+
+function parseStore(raw: string): NoteStoreFile {
+  const parsed: unknown = JSON.parse(raw);
+  if (!isRecord(parsed)) return { version: STORE_VERSION, notes: [] };
+  return {
+    version: STORE_VERSION,
+    notes: Array.isArray(parsed.notes)
+      ? parsed.notes.map(parseNote).filter((entry): entry is AgentNoteRecord => entry !== null)
+      : [],
+  };
+}
+
+function formatStore(store: NoteStoreFile): string {
+  return `${JSON.stringify(store, null, 2)}\n`;
+}
+
+type AgentLocalStorePaths = Pick<ShellPathService, 'resolveUserPath'>;
+
+export function noteStorePath(shellPaths: AgentLocalStorePaths): string {
+  return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'notes', 'notes.json');
+}
+
+export class AgentNoteRegistry {
+  public constructor(private readonly storePath: string) {}
+
+  public static fromShellPaths(shellPaths: AgentLocalStorePaths): AgentNoteRegistry {
+    return new AgentNoteRegistry(noteStorePath(shellPaths));
+  }
+
+  public snapshot(): AgentNoteSnapshot {
+    const store = this.readStore();
+    const notes = [...store.notes].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    return {
+      path: this.storePath,
+      notes,
+      reviewQueue: notes.filter((note) => note.reviewState !== 'reviewed'),
+    };
+  }
+
+  public list(): readonly AgentNoteRecord[] {
+    return this.snapshot().notes;
+  }
+
+  public search(query: string): readonly AgentNoteRecord[] {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized) return this.list();
+    return this.list().filter((note) => [
+      note.id,
+      note.title,
+      note.body,
+      note.sourceUrl ?? '',
+      ...note.tags,
+    ].some((field) => field.toLowerCase().includes(normalized)));
+  }
+
+  public get(idOrTitle: string): AgentNoteRecord | null {
+    const lookup = idOrTitle.trim().toLowerCase();
+    if (!lookup) return null;
+    return this.list().find((note) => note.id.toLowerCase() === lookup || note.title.toLowerCase() === lookup) ?? null;
+  }
+
+  public create(input: AgentNoteCreateInput): AgentNoteRecord {
+    const store = this.readStore();
+    const title = normalizeTitle(input.title);
+    const body = input.body.trim();
+    this.validateRequired(title, body);
+    const sourceUrl = input.sourceUrl?.trim() || undefined;
+    assertNoNoteSecretLikeText([title, body, sourceUrl ?? '', ...(input.tags ?? [])]);
+    const duplicate = store.notes.find((note) => note.title.toLowerCase() === title.toLowerCase());
+    if (duplicate) throw new Error(`Note already exists ${duplicate.id}`);
+    const timestamp = nowIso();
+    const note: AgentNoteRecord = {
+      id: this.nextId(title, store.notes),
+      title,
+      body,
+      tags: normalizeList(input.tags),
+      sourceUrl,
+      source: input.source ?? 'user',
+      provenance: input.provenance?.trim() || input.source || 'user',
+      reviewState: 'fresh',
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    };
+    this.writeStore({ ...store, notes: [...store.notes, note] });
+    return note;
+  }
+
+  public update(idOrTitle: string, input: AgentNoteUpdateInput): AgentNoteRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrTitle);
+    if (!existing) throw new Error(`Unknown note ${idOrTitle}`);
+    const title = input.title === undefined ? existing.title : normalizeTitle(input.title);
+    const body = input.body === undefined ? existing.body : input.body.trim();
+    this.validateRequired(title, body);
+    const sourceUrl = input.sourceUrl === undefined ? existing.sourceUrl : input.sourceUrl.trim() || undefined;
+    assertNoNoteSecretLikeText([title, body, sourceUrl ?? '', ...(input.tags ?? [])]);
+    const duplicate = store.notes.find((note) => note.id !== existing.id && note.title.toLowerCase() === title.toLowerCase());
+    if (duplicate) throw new Error(`Note already exists ${duplicate.id}`);
+    const updated: AgentNoteRecord = {
+      ...existing,
+      title,
+      body,
+      tags: input.tags === undefined ? existing.tags : normalizeList(input.tags),
+      sourceUrl,
+      provenance: input.provenance === undefined ? existing.provenance : input.provenance.trim() || existing.provenance,
+      reviewState: 'fresh',
+      staleReason: undefined,
+      reviewedAt: undefined,
+      updatedAt: nowIso(),
+    };
+    this.writeStore({
+      ...store,
+      notes: store.notes.map((note) => note.id === existing.id ? updated : note),
+    });
+    return updated;
+  }
+
+  public markReviewed(idOrTitle: string): AgentNoteRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrTitle);
+    if (!existing) throw new Error(`Unknown note ${idOrTitle}`);
+    const updated: AgentNoteRecord = {
+      ...existing,
+      reviewState: 'reviewed',
+      staleReason: undefined,
+      reviewedAt: nowIso(),
+      updatedAt: nowIso(),
+    };
+    this.writeStore({
+      ...store,
+      notes: store.notes.map((note) => note.id === existing.id ? updated : note),
+    });
+    return updated;
+  }
+
+  public markStale(idOrTitle: string, reason: string): AgentNoteRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrTitle);
+    if (!existing) throw new Error(`Unknown note ${idOrTitle}`);
+    const updated: AgentNoteRecord = {
+      ...existing,
+      reviewState: 'stale',
+      staleReason: reason.trim() || 'Marked stale by user.',
+      updatedAt: nowIso(),
+    };
+    this.writeStore({
+      ...store,
+      notes: store.notes.map((note) => note.id === existing.id ? updated : note),
+    });
+    return updated;
+  }
+
+  public deleteNote(idOrTitle: string): AgentNoteRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrTitle);
+    if (!existing) throw new Error(`Unknown note ${idOrTitle}`);
+    this.writeStore({
+      ...store,
+      notes: store.notes.filter((note) => note.id !== existing.id),
+    });
+    return existing;
+  }
+
+  private validateRequired(title: string, body: string): void {
+    if (!title) throw new Error('Note title is required.');
+    if (!body) throw new Error('Note body is required.');
+  }
+
+  private nextId(title: string, notes: readonly AgentNoteRecord[]): string {
+    const base = slugify(title);
+    const ids = new Set(notes.map((note) => note.id));
+    if (!ids.has(base)) return base;
+    for (let index = 2; index < 1000; index += 1) {
+      const candidate = `${base}-${index}`;
+      if (!ids.has(candidate)) return candidate;
+    }
+    throw new Error(`Could not allocate note id for ${title}.`);
+  }
+
+  private findInStore(store: NoteStoreFile, idOrTitle: string): AgentNoteRecord | null {
+    const lookup = idOrTitle.trim().toLowerCase();
+    if (!lookup) return null;
+    return store.notes.find((note) => note.id.toLowerCase() === lookup || note.title.toLowerCase() === lookup) ?? null;
+  }
+
+  private readStore(): NoteStoreFile {
+    if (!existsSync(this.storePath)) return { version: STORE_VERSION, notes: [] };
+    try {
+      return parseStore(readFileSync(this.storePath, 'utf-8'));
+    } catch (error) {
+      throw new Error(`Could not read Agent note store ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  private writeStore(store: NoteStoreFile): void {
+    mkdirSync(dirname(this.storePath), { recursive: true });
+    const tmpPath = `${this.storePath}.tmp`;
+    writeFileSync(tmpPath, formatStore(store), 'utf-8');
+    renameSync(tmpPath, this.storePath);
+  }
+}

package/src/agent/operator-actions.ts

@@ -0,0 +1,343 @@
+import type { OperatorMethodInput } from '@pellux/goodvibes-sdk/contracts';
+
+export type JsonRecord = Record<string, unknown>;
+
+export type ApprovalActionId = 'approvals.approve' | 'approvals.deny' | 'approvals.cancel';
+export type AutomationActionId =
+  | 'automation.jobs.run'
+  | 'automation.jobs.pause'
+  | 'automation.jobs.resume'
+  | 'automation.runs.cancel'
+  | 'automation.runs.retry'
+  | 'schedules.run';
+export type OperatorActionId = ApprovalActionId | AutomationActionId;
+
+type ApprovalActionInput =
+  | OperatorMethodInput<'approvals.approve'>
+  | OperatorMethodInput<'approvals.deny'>
+  | OperatorMethodInput<'approvals.cancel'>;
+
+export interface OperatorActionArgs {
+  readonly action?: unknown;
+  readonly targetId?: unknown;
+  readonly approvalId?: unknown;
+  readonly jobId?: unknown;
+  readonly runId?: unknown;
+  readonly scheduleId?: unknown;
+  readonly note?: unknown;
+  readonly remember?: unknown;
+}
+
+export interface OperatorActionDescriptor {
+  readonly action: OperatorActionId;
+  readonly label: string;
+  readonly pathTemplate: string;
+  readonly targetField: 'approvalId' | 'jobId' | 'runId' | 'scheduleId';
+}
+
+export interface OperatorActionRequest {
+  readonly ok: true;
+  readonly descriptor: OperatorActionDescriptor;
+  readonly targetId: string;
+  readonly body: JsonRecord | null;
+}
+
+export interface OperatorActionSuccess {
+  readonly ok: true;
+  readonly methodId: OperatorActionId;
+  readonly path: string;
+  readonly body: unknown;
+}
+
+export interface OperatorActionFailure {
+  readonly ok: false;
+  readonly kind:
+    | 'auth_required'
+    | 'connected_host_unavailable'
+    | 'connected_host_route_unavailable'
+    | 'connected_host_error';
+  readonly error: string;
+  readonly methodId: OperatorActionId;
+  readonly path: string;
+}
+
+export type OperatorActionResult = OperatorActionSuccess | OperatorActionFailure;
+export type OperatorActionParseResult = OperatorActionRequest | { readonly ok: false; readonly error: string };
+
+export interface OperatorActionConnection {
+  readonly baseUrl: string;
+  readonly token: string | null;
+  readonly tokenPath?: string;
+}
+
+export const OPERATOR_ACTIONS: Record<OperatorActionId, OperatorActionDescriptor> = {
+  'approvals.approve': {
+    action: 'approvals.approve',
+    label: 'approve approval',
+    pathTemplate: '/api/approvals/{approvalId}/approve',
+    targetField: 'approvalId',
+  },
+  'approvals.deny': {
+    action: 'approvals.deny',
+    label: 'deny approval',
+    pathTemplate: '/api/approvals/{approvalId}/deny',
+    targetField: 'approvalId',
+  },
+  'approvals.cancel': {
+    action: 'approvals.cancel',
+    label: 'cancel approval',
+    pathTemplate: '/api/approvals/{approvalId}/cancel',
+    targetField: 'approvalId',
+  },
+  'automation.jobs.run': {
+    action: 'automation.jobs.run',
+    label: 'run automation job',
+    pathTemplate: '/api/automation/jobs/{jobId}/run',
+    targetField: 'jobId',
+  },
+  'automation.jobs.pause': {
+    action: 'automation.jobs.pause',
+    label: 'pause automation job',
+    pathTemplate: '/api/automation/jobs/{jobId}/pause',
+    targetField: 'jobId',
+  },
+  'automation.jobs.resume': {
+    action: 'automation.jobs.resume',
+    label: 'resume automation job',
+    pathTemplate: '/api/automation/jobs/{jobId}/resume',
+    targetField: 'jobId',
+  },
+  'automation.runs.cancel': {
+    action: 'automation.runs.cancel',
+    label: 'cancel automation run',
+    pathTemplate: '/api/automation/runs/{runId}/cancel',
+    targetField: 'runId',
+  },
+  'automation.runs.retry': {
+    action: 'automation.runs.retry',
+    label: 'retry automation run',
+    pathTemplate: '/api/automation/runs/{runId}/retry',
+    targetField: 'runId',
+  },
+  'schedules.run': {
+    action: 'schedules.run',
+    label: 'run schedule',
+    pathTemplate: '/api/automation/schedules/{scheduleId}/run',
+    targetField: 'scheduleId',
+  },
+};
+
+export const OPERATOR_ACTION_IDS = Object.keys(OPERATOR_ACTIONS) as readonly OperatorActionId[];
+
+export function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function readOperatorActionString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function readOperatorActionBoolean(value: unknown): boolean {
+  return value === true || value === 'true' || value === 'yes';
+}
+
+export function isOperatorActionId(value: unknown): value is OperatorActionId {
+  return typeof value === 'string' && value in OPERATOR_ACTIONS;
+}
+
+export function targetValue(args: OperatorActionArgs, descriptor: OperatorActionDescriptor): string {
+  const specific = args[descriptor.targetField];
+  return readOperatorActionString(specific) || readOperatorActionString(args.targetId);
+}
+
+export function renderOperatorActionPath(descriptor: OperatorActionDescriptor, targetId: string): string {
+  return descriptor.pathTemplate.replace(`{${descriptor.targetField}}`, encodeURIComponent(targetId));
+}
+
+function approvalBody(args: OperatorActionArgs): ApprovalActionInput {
+  const note = readOperatorActionString(args.note);
+  const body: ApprovalActionInput = {
+    approvalId: targetValue(args, OPERATOR_ACTIONS['approvals.approve']),
+  };
+  if (note) body.note = note;
+  if (args.remember !== undefined) body.remember = readOperatorActionBoolean(args.remember);
+  return body;
+}
+
+function requestBody(args: OperatorActionArgs, action: OperatorActionId): JsonRecord | null {
+  if (action !== 'approvals.approve' && action !== 'approvals.deny' && action !== 'approvals.cancel') return null;
+  const body = approvalBody(args);
+  const out: JsonRecord = {};
+  if (body.note) out.note = body.note;
+  if (body.remember !== undefined) out.remember = body.remember;
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+export function buildOperatorActionRequest(rawArgs: unknown): OperatorActionParseResult {
+  if (!isRecord(rawArgs)) return { ok: false, error: 'Operator action arguments must be an object.' };
+  const args = rawArgs as OperatorActionArgs;
+  if (!isOperatorActionId(args.action)) {
+    return {
+      ok: false,
+      error: `action must be one of: ${OPERATOR_ACTION_IDS.join(', ')}`,
+    };
+  }
+  const descriptor = OPERATOR_ACTIONS[args.action];
+  const targetId = targetValue(args, descriptor);
+  if (!targetId) {
+    return {
+      ok: false,
+      error: `${descriptor.targetField} or targetId is required for ${descriptor.action}.`,
+    };
+  }
+  return {
+    ok: true,
+    descriptor,
+    targetId,
+    body: requestBody(args, descriptor.action),
+  };
+}
+
+async function readResponseBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function summarizeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function classifyHttpFailure(
+  methodId: OperatorActionId,
+  path: string,
+  status: number,
+  body: unknown,
+): OperatorActionFailure {
+  const detail = isRecord(body) && typeof body.error === 'string' ? body.error : '';
+  return {
+    ok: false,
+    methodId,
+    path,
+    kind: status === 401 || status === 403
+      ? 'auth_required'
+      : status === 404
+        ? 'connected_host_route_unavailable'
+        : 'connected_host_error',
+    error: `HTTP ${status}${detail ? `: ${detail}` : ''}`,
+  };
+}
+
+export async function postOperatorAction(
+  connection: OperatorActionConnection,
+  request: OperatorActionRequest,
+): Promise<OperatorActionResult> {
+  const path = renderOperatorActionPath(request.descriptor, request.targetId);
+  const token = connection.token;
+  if (!token) {
+    return {
+      ok: false,
+      methodId: request.descriptor.action,
+      path,
+      kind: 'auth_required',
+      error: connection.tokenPath ? `no connected-host operator token found at ${connection.tokenPath}` : 'no connected-host operator token found',
+    };
+  }
+  const headers: HeadersInit = {
+    authorization: `Bearer ${token}`,
+  };
+  const init: RequestInit = {
+    method: 'POST',
+    headers,
+  };
+  if (request.body) {
+    headers['content-type'] = 'application/json';
+    init.body = JSON.stringify(request.body);
+  }
+  try {
+    const response = await fetch(`${connection.baseUrl}${path}`, init);
+    const body = await readResponseBody(response);
+    if (!response.ok) return classifyHttpFailure(request.descriptor.action, path, response.status, body);
+    return {
+      ok: true,
+      methodId: request.descriptor.action,
+      path,
+      body,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      methodId: request.descriptor.action,
+      path,
+      kind: 'connected_host_unavailable',
+      error: summarizeError(error),
+    };
+  }
+}
+
+export function statusFromOperatorActionBody(body: unknown): string {
+  if (!isRecord(body)) return 'ok';
+  const approval = body.approval;
+  if (isRecord(approval) && typeof approval.status === 'string') return approval.status;
+  const run = body.run;
+  if (isRecord(run) && typeof run.status === 'string') return run.status;
+  if (typeof body.status === 'string') return body.status;
+  if (typeof body.enabled === 'boolean') return body.enabled ? 'enabled' : 'disabled';
+  return 'ok';
+}
+
+function formatOperatorActionFailureKind(kind: OperatorActionFailure['kind']): string {
+  if (kind === 'auth_required') return 'authorization required';
+  if (kind === 'connected_host_unavailable') return 'connected host unavailable';
+  if (kind === 'connected_host_route_unavailable') return 'connected host route unavailable';
+  return 'connected host error';
+}
+
+export function formatOperatorActionSuccess(baseUrl: string, result: OperatorActionSuccess): string {
+  return [
+    'Agent operator action completed',
+    `  method: ${result.methodId}`,
+    `  route: POST ${result.path}`,
+    `  connected host: ${baseUrl}`,
+    `  status: ${statusFromOperatorActionBody(result.body)}`,
+  ].join('\n');
+}
+
+export function formatOperatorActionFailure(result: OperatorActionFailure): string {
+  return [
+    `Agent operator action failed: ${result.kind} (${formatOperatorActionFailureKind(result.kind)})`,
+    `  method: ${result.methodId}`,
+    `  route: POST ${result.path}`,
+    `  error: ${result.error}`,
+  ].join('\n');
+}
+
+export function formatOperatorActionPreview(request: OperatorActionRequest, explicitUserRequest: string): string {
+  return [
+    'Agent operator action preview',
+    `  method ${request.descriptor.action}`,
+    `  action ${request.descriptor.label}`,
+    `  target ${request.targetId}`,
+    `  route POST ${renderOperatorActionPath(request.descriptor, request.targetId)}`,
+    explicitUserRequest ? `  requested by ${explicitUserRequest}` : '  requested by (missing)',
+    '',
+    'Confirmation required: type yes in the workspace form or pass --yes only when the user explicitly asked GoodVibes Agent to perform this exact operator action.',
+  ].join('\n');
+}
+
+export function formatOperatorActionToolPreview(request: OperatorActionRequest, explicitUserRequest: string): string {
+  return [
+    'Agent operator action preview',
+    `  method ${request.descriptor.action}`,
+    `  action ${request.descriptor.label}`,
+    `  target ${request.targetId}`,
+    `  route POST ${renderOperatorActionPath(request.descriptor, request.targetId)}`,
+    explicitUserRequest ? `  requested by ${explicitUserRequest}` : '  requested by (missing)',
+    '',
+    'Model tool confirmation required. Call this tool with confirm:true only when the user explicitly asked GoodVibes Agent to perform this exact operator action.',
+  ].join('\n');
+}