@pellux/goodvibes-agent 1.0.31 → 1.0.33

package/src/tools/agent-harness-workspace-actions.ts

@@ -0,0 +1,232 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import { createAgentWorkspaceEditor } from '../input/agent-workspace-activation.ts';
+import { AGENT_WORKSPACE_CATEGORIES } from '../input/agent-workspace-categories.ts';
+import { searchAgentWorkspaceActions } from '../input/agent-workspace-search.ts';
+import { buildAgentWorkspaceRuntimeSnapshot } from '../input/agent-workspace-snapshot.ts';
+import type { AgentWorkspaceAction, AgentWorkspaceCategory, AgentWorkspaceEditorKind, AgentWorkspaceLocalEditor, AgentWorkspaceLocalLibraryItem, AgentWorkspaceRuntimeSnapshot } from '../input/agent-workspace-types.ts';
+import { describeLocalWorkspaceModelExecution } from './agent-harness-local-operations.ts';
+import { describeWorkspaceEditorModelExecution } from './agent-harness-workspace-editor-execution.ts';
+
+export { AGENT_WORKSPACE_CATEGORIES };
+
+export interface AgentHarnessWorkspaceActionArgs {
+  readonly query?: unknown;
+  readonly command?: unknown;
+  readonly actionId?: unknown;
+  readonly recordId?: unknown;
+  readonly fields?: unknown;
+  readonly target?: unknown;
+  readonly category?: unknown;
+  readonly categoryId?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+export interface WorkspaceEditorContext {
+  readonly runtimeStarterTemplates: AgentWorkspaceRuntimeSnapshot['runtimeStarterTemplates'];
+  readonly selectedRoutine: AgentWorkspaceLocalLibraryItem | null;
+}
+
+export interface WorkspaceActionLookup {
+  readonly source: 'actionId' | 'command' | 'target' | 'query';
+  readonly input: string;
+  readonly resolvedBy: 'id' | 'case-insensitive-id' | 'label' | 'case-insensitive-label' | 'command' | 'search';
+}
+
+export type WorkspaceActionResolution =
+  | {
+    readonly status: 'found';
+    readonly category: AgentWorkspaceCategory;
+    readonly action: AgentWorkspaceAction;
+    readonly lookup: WorkspaceActionLookup;
+  }
+  | {
+    readonly status: 'ambiguous';
+    readonly input: string;
+    readonly candidates: readonly { readonly actionId: string; readonly categoryId: string; readonly label: string; readonly command?: string }[];
+  };
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function readFieldMap(value: unknown): Readonly<Record<string, string>> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return {};
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, typeof entry === 'string' ? entry : String(entry)]));
+}
+
+export function allWorkspaceActions(): ReadonlyArray<{
+  readonly category: AgentWorkspaceCategory;
+  readonly action: AgentWorkspaceAction;
+}> {
+  return AGENT_WORKSPACE_CATEGORIES.flatMap((category) => category.actions.map((action) => ({ category, action })));
+}
+
+export function describeWorkspaceCategory(category: AgentWorkspaceCategory): Record<string, unknown> {
+  return {
+    id: category.id,
+    group: category.group,
+    label: category.label,
+    summary: category.summary,
+    detail: category.detail,
+    actions: category.actions.length,
+  };
+}
+
+export function describeWorkspaceEditor(editor: AgentWorkspaceLocalEditor): Record<string, unknown> {
+  return {
+    kind: editor.kind,
+    mode: editor.mode,
+    title: editor.title,
+    message: editor.message,
+    fields: editor.fields.map((field) => ({
+      id: field.id,
+      label: field.label,
+      required: field.required,
+      multiline: field.multiline,
+      hint: field.hint,
+      redact: field.redact === true,
+      default: field.redact ? '<redacted>' : field.value,
+    })),
+  };
+}
+
+function selectedRoutineFromArgs(
+  snapshot: AgentWorkspaceRuntimeSnapshot,
+  args: AgentHarnessWorkspaceActionArgs,
+): AgentWorkspaceLocalLibraryItem | null {
+  const fields = readFieldMap(args.fields);
+  const routineId = readString(args.recordId) || readString(fields.routineId) || readString(fields.id);
+  if (!routineId) return null;
+  return snapshot.localRoutines.find((routine) => routine.id === routineId || routine.name.toLowerCase() === routineId.toLowerCase()) ?? null;
+}
+
+export function buildWorkspaceEditorContext(context: CommandContext, args: AgentHarnessWorkspaceActionArgs): WorkspaceEditorContext {
+  try {
+    const snapshot = buildAgentWorkspaceRuntimeSnapshot(context);
+    return {
+      runtimeStarterTemplates: snapshot.runtimeStarterTemplates,
+      selectedRoutine: selectedRoutineFromArgs(snapshot, args),
+    };
+  } catch {
+    return {
+      runtimeStarterTemplates: [],
+      selectedRoutine: null,
+    };
+  }
+}
+
+export function createWorkspaceEditor(
+  editorKind: AgentWorkspaceEditorKind,
+  editorContext: WorkspaceEditorContext | null,
+): AgentWorkspaceLocalEditor | null {
+  return createAgentWorkspaceEditor(editorKind, {
+    runtimeStarterTemplates: editorContext?.runtimeStarterTemplates ?? [],
+    selectedRoutine: editorKind === 'routine-schedule' ? editorContext?.selectedRoutine ?? null : null,
+  });
+}
+
+export function describeWorkspaceAction(
+  category: AgentWorkspaceCategory,
+  action: AgentWorkspaceAction,
+  options: { readonly includeEditor?: boolean; readonly editorContext?: WorkspaceEditorContext | null; readonly lookup?: WorkspaceActionLookup } = {},
+): Record<string, unknown> {
+  const editor = options.includeEditor && action.editorKind ? createWorkspaceEditor(action.editorKind, options.editorContext ?? null) : null;
+  return {
+    id: action.id,
+    categoryId: category.id,
+    category: category.label,
+    group: category.group,
+    label: action.label,
+    detail: action.detail,
+    kind: action.kind,
+    safety: action.safety,
+    ...(action.command ? { command: action.command } : {}),
+    ...(action.targetCategoryId ? { targetCategoryId: action.targetCategoryId } : {}),
+    ...(action.editorKind ? { editorKind: action.editorKind } : {}),
+    ...(action.localKind ? { localKind: action.localKind } : {}),
+    ...(action.localOperation ? { localOperation: action.localOperation } : {}),
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(editor ? { editor: describeWorkspaceEditor(editor) } : {}),
+    ...(action.kind === 'local-selection' || action.kind === 'local-operation' ? {
+      modelExecution: describeLocalWorkspaceModelExecution(action),
+    } : {}),
+    ...(action.kind === 'editor' && action.editorKind ? {
+      modelExecution: describeWorkspaceEditorModelExecution(action.editorKind),
+    } : {}),
+  };
+}
+
+export function listWorkspaceActions(
+  context: CommandContext,
+  args: AgentHarnessWorkspaceActionArgs,
+): readonly Record<string, unknown>[] {
+  const query = readString(args.query);
+  const categoryId = readString(args.categoryId || args.category);
+  const limit = readLimit(args.limit, 200);
+  const includeEditor = args.includeParameters === true;
+  const editorContext = includeEditor ? buildWorkspaceEditorContext(context, args) : null;
+  const source = query
+    ? searchAgentWorkspaceActions(AGENT_WORKSPACE_CATEGORIES, query).map((result) => ({ category: result.category, action: result.action }))
+    : allWorkspaceActions();
+  return source
+    .filter((entry) => !categoryId || entry.category.id === categoryId)
+    .slice(0, limit)
+    .map((entry) => describeWorkspaceAction(entry.category, entry.action, { includeEditor, editorContext }));
+}
+
+function workspaceActionLookupFromArgs(args: AgentHarnessWorkspaceActionArgs): { readonly source: WorkspaceActionLookup['source']; readonly input: string } | null {
+  const actionId = readString(args.actionId);
+  if (actionId) return { source: 'actionId', input: actionId };
+  const command = readString(args.command);
+  if (command) return { source: 'command', input: command };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function describeWorkspaceActionCandidates(
+  entries: readonly { readonly category: AgentWorkspaceCategory; readonly action: AgentWorkspaceAction }[],
+): readonly { readonly actionId: string; readonly categoryId: string; readonly label: string; readonly command?: string }[] {
+  return entries.slice(0, 8).map((entry) => ({
+    actionId: entry.action.id,
+    categoryId: entry.category.id,
+    label: entry.action.label,
+    ...(entry.action.command ? { command: entry.action.command } : {}),
+  }));
+}
+
+export function resolveWorkspaceActionDetail(args: AgentHarnessWorkspaceActionArgs): WorkspaceActionResolution | null {
+  const lookup = workspaceActionLookupFromArgs(args);
+  const categoryId = readString(args.categoryId || args.category);
+  if (!lookup) return null;
+  const entries = allWorkspaceActions().filter((entry) => !categoryId || entry.category.id === categoryId);
+  const normalized = lookup.input.toLowerCase();
+  const commandInput = lookup.source === 'command' ? lookup.input.trim() : '';
+
+  const exactId = entries.find((entry) => entry.action.id === lookup.input);
+  if (exactId) return { status: 'found', ...exactId, lookup: { ...lookup, resolvedBy: 'id' } };
+  const exactLabel = entries.find((entry) => entry.action.label === lookup.input);
+  if (exactLabel) return { status: 'found', ...exactLabel, lookup: { ...lookup, resolvedBy: 'label' } };
+  const exactCommand = commandInput ? entries.find((entry) => entry.action.command === commandInput) : null;
+  if (exactCommand) return { status: 'found', ...exactCommand, lookup: { ...lookup, resolvedBy: 'command' } };
+
+  const insensitiveId = entries.find((entry) => entry.action.id.toLowerCase() === normalized);
+  if (insensitiveId) return { status: 'found', ...insensitiveId, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } };
+  const insensitiveLabel = entries.find((entry) => entry.action.label.toLowerCase() === normalized);
+  if (insensitiveLabel) return { status: 'found', ...insensitiveLabel, lookup: { ...lookup, resolvedBy: 'case-insensitive-label' } };
+
+  const searched = searchAgentWorkspaceActions(AGENT_WORKSPACE_CATEGORIES, lookup.input)
+    .map((result) => ({ category: result.category, action: result.action }))
+    .filter((entry) => !categoryId || entry.category.id === categoryId);
+  if (searched.length === 1) return { status: 'found', ...searched[0]!, lookup: { ...lookup, resolvedBy: 'search' } };
+  if (searched.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: describeWorkspaceActionCandidates(searched) };
+  return null;
+}

package/src/tools/agent-knowledge-ingest-tool.ts

@@ -262,11 +262,9 @@ export function createAgentKnowledgeIngestTool(
     definition: {
       name: 'agent_knowledge_ingest',
       description: [
-        'Ingest explicit sources into isolated GoodVibes Agent Knowledge from the main conversation.',
-        'Use only when the user explicitly asks Agent to add, remember, import, or ingest a URL, local file, URL-list file, bookmarks file, browser history, or connector input into its Agent Knowledge.',
-        'This writes only to /api/goodvibes-agent/knowledge/* ingest routes on the connected GoodVibes host.',
-        'It must never call default knowledge, non-Agent knowledge spaces, separate Agent jobs, local schedulers, or delegated review.',
-        'Set confirm:true only for an explicit user request. Otherwise return the preview/confirmation error.',
+        'Ingest one confirmed source into isolated Agent Knowledge.',
+        'Use only for explicit ingest/import requests.',
+        'Supports URL, file, bookmark, history, and connector sources.',
       ].join(' '),
       parameters: {
         type: 'object',
@@ -282,7 +280,7 @@ export function createAgentKnowledgeIngestTool(
           },
           path: {
             type: 'string',
-            description: 'Local file/import path for file, urls_file, bookmarks_file, or connector source kinds.',
+            description: 'Local file or import path.',
           },
           title: {
             type: 'string',
@@ -299,7 +297,7 @@ export function createAgentKnowledgeIngestTool(
           },
           connectorId: {
             type: 'string',
-            description: 'Connector id for connector ingest, or optional connector id override for file ingest.',
+            description: 'Connector id.',
           },
           input: {
             description: 'Connector input as JSON-compatible data or a JSON/text string.',
@@ -340,7 +338,7 @@ export function createAgentKnowledgeIngestTool(
           },
           explicitUserRequest: {
             type: 'string',
-            description: 'Short quote or summary of the user request that authorized this Agent Knowledge ingest.',
+            description: 'User request authorizing this ingest.',
           },
         },
         required: ['confirm', 'explicitUserRequest'],

package/src/tools/agent-knowledge-tool.ts

@@ -4,29 +4,62 @@ import type { ShellPathService } from '@/runtime/index.ts';
 import {
   createAgentSdk,
   classifyKnowledgeError,
+  getAgentKnowledgeJson,
   resolveConnectedHostConnection,
+  validateAgentKnowledgeData,
   type AgentKnowledgeFailure,
   type AgentKnowledgeConnectionRuntime,
 } from '../cli/agent-knowledge-runtime.ts';
 import { AGENT_KNOWLEDGE_METHODS, type ConnectedHostCallMethod } from '../cli/agent-knowledge-methods.ts';
 import {
   formatAsk,
+  formatConnector,
+  formatConnectorDoctor,
+  formatConnectors,
+  formatEntityList,
   formatFailure,
+  formatItem,
+  formatMap,
   formatSearch,
   formatStatus,
 } from '../cli/agent-knowledge-format.ts';
 
-export type AgentKnowledgeToolAction = 'status' | 'ask' | 'search';
+export type AgentKnowledgeToolAction =
+  | 'status'
+  | 'ask'
+  | 'search'
+  | 'sources'
+  | 'nodes'
+  | 'issues'
+  | 'item'
+  | 'map'
+  | 'connectors'
+  | 'connector'
+  | 'connector_doctor';
 export type AgentKnowledgeAskMode = 'concise' | 'standard' | 'detailed';
 
 export interface AgentKnowledgeToolArgs {
   readonly action?: unknown;
   readonly query?: unknown;
+  readonly id?: unknown;
+  readonly connectorId?: unknown;
   readonly limit?: unknown;
   readonly mode?: unknown;
 }
 
-const ACTIONS: readonly AgentKnowledgeToolAction[] = ['status', 'ask', 'search'];
+const ACTIONS: readonly AgentKnowledgeToolAction[] = [
+  'status',
+  'ask',
+  'search',
+  'sources',
+  'nodes',
+  'issues',
+  'item',
+  'map',
+  'connectors',
+  'connector',
+  'connector_doctor',
+];
 const ASK_MODES: readonly AgentKnowledgeAskMode[] = ['concise', 'standard', 'detailed'];
 
 function isAction(value: unknown): value is AgentKnowledgeToolAction {
@@ -37,11 +70,11 @@ function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
 
-function readLimit(value: unknown, fallback: number): number {
-  if (typeof value === 'number' && Number.isInteger(value) && value > 0) return Math.min(value, 25);
+function readLimit(value: unknown, fallback: number, max = 25): number {
+  if (typeof value === 'number' && Number.isInteger(value) && value > 0) return Math.min(value, max);
   if (typeof value === 'string' && value.trim()) {
     const parsed = Number(value);
-    if (Number.isInteger(parsed) && parsed > 0) return Math.min(parsed, 25);
+    if (Number.isInteger(parsed) && parsed > 0) return Math.min(parsed, max);
   }
   return fallback;
 }
@@ -72,6 +105,17 @@ async function classifyToolKnowledgeError(
   return toolFailure(formatKnowledgeFailure(await classifyKnowledgeError(error, connection, method.route)));
 }
 
+function validatedToolOutput<TData>(
+  data: TData,
+  connection: ReturnType<typeof resolveConnectedHostConnection>,
+  method: ConnectedHostCallMethod,
+  format: (validatedData: TData) => string,
+): { readonly success: true; readonly output: string } | { readonly success: false; readonly error: string } {
+  const validated = validateAgentKnowledgeData(data, connection, method);
+  if (!validated.ok) return toolFailure(formatKnowledgeFailure(validated));
+  return toolOutput(format(validated.data));
+}
+
 export function createAgentKnowledgeTool(
   shellPaths: ShellPathService,
   configManager: AgentKnowledgeConnectionRuntime['configManager'],
@@ -80,10 +124,9 @@ export function createAgentKnowledgeTool(
     definition: {
       name: 'agent_knowledge',
       description: [
-        'Read isolated GoodVibes Agent Knowledge from the main conversation.',
-        'Use for Agent-owned knowledge status, ask, and search only.',
-        'This tool calls /api/goodvibes-agent/knowledge/* on the connected GoodVibes host and must never fall back to default knowledge or non-Agent knowledge spaces.',
-        'It is read-only and does not ingest, reindex, mutate, or create background work.',
+        'Read isolated Agent Knowledge.',
+        'Use for status, ask/search, source/node/issue lists, item lookup, map summary, and connector inspection.',
+        'Read-only.',
       ].join(' '),
       parameters: {
         type: 'object',
@@ -95,11 +138,19 @@ export function createAgentKnowledgeTool(
           },
           query: {
             type: 'string',
-            description: 'Question/query for ask or search.',
+            description: 'Question/query for ask, search, or map filtering.',
+          },
+          id: {
+            type: 'string',
+            description: 'Agent Knowledge source, node, or issue id for action item.',
+          },
+          connectorId: {
+            type: 'string',
+            description: 'Connector id for action connector or connector_doctor. id may also be used.',
           },
           limit: {
             type: 'number',
-            description: 'Maximum source/search results, capped at 25.',
+            description: 'Maximum result count.',
           },
           mode: {
             type: 'string',
@@ -125,13 +176,16 @@ export function createAgentKnowledgeTool(
           route: '/api/goodvibes-agent/knowledge/*',
         }));
       }
+      let method: ConnectedHostCallMethod = AGENT_KNOWLEDGE_METHODS.status;
       try {
         const sdk = createAgentSdk(connection);
         if (args.action === 'status') {
+          method = AGENT_KNOWLEDGE_METHODS.status;
           const data = await sdk.knowledge.status();
-          return toolOutput(formatStatus(data));
+          return validatedToolOutput(data, connection, method, formatStatus);
         }
         if (args.action === 'ask') {
+          method = AGENT_KNOWLEDGE_METHODS.ask;
           const query = readString(args.query);
           if (!query) return toolFailure('query is required for Agent Knowledge ask.');
           const data = await sdk.knowledge.ask({
@@ -142,19 +196,64 @@ export function createAgentKnowledgeTool(
             includeConfidence: true,
             includeLinkedObjects: true,
           });
-          return toolOutput(formatAsk(data, query));
+          return validatedToolOutput(data, connection, method, (validatedData) => formatAsk(validatedData, query));
+        }
+        if (args.action === 'search') {
+          method = AGENT_KNOWLEDGE_METHODS.search;
+          const query = readString(args.query);
+          if (!query) return toolFailure('query is required for Agent Knowledge search.');
+          const data = await sdk.knowledge.search({ query, limit: readLimit(args.limit, 10) });
+          return validatedToolOutput(data, connection, method, (validatedData) => formatSearch(validatedData, query));
+        }
+        if (args.action === 'sources' || args.action === 'nodes' || args.action === 'issues') {
+          const kind = args.action;
+          const limit = readLimit(args.limit, 25, 500);
+          method = kind === 'sources'
+            ? AGENT_KNOWLEDGE_METHODS.sourcesList
+            : kind === 'nodes'
+              ? AGENT_KNOWLEDGE_METHODS.nodesList
+              : AGENT_KNOWLEDGE_METHODS.issuesList;
+          const data = await getAgentKnowledgeJson(connection, method.route, { limit });
+          return validatedToolOutput(data, connection, method, (validatedData) => formatEntityList(validatedData, kind, limit));
+        }
+        if (args.action === 'item') {
+          method = AGENT_KNOWLEDGE_METHODS.itemGet;
+          const id = readString(args.id);
+          if (!id) return toolFailure('id is required for Agent Knowledge item lookup.');
+          const route = `/api/goodvibes-agent/knowledge/items/${encodeURIComponent(id)}`;
+          const data = await getAgentKnowledgeJson(connection, route);
+          return validatedToolOutput(data, connection, { ...method, route }, (validatedData) => formatItem(validatedData, id));
+        }
+        if (args.action === 'map') {
+          method = AGENT_KNOWLEDGE_METHODS.map;
+          const data = await getAgentKnowledgeJson(connection, method.route, {
+            limit: readLimit(args.limit, 50, 500),
+            query: readString(args.query),
+          });
+          return validatedToolOutput(data, connection, method, formatMap);
+        }
+        if (args.action === 'connectors') {
+          method = AGENT_KNOWLEDGE_METHODS.connectorsList;
+          const data = await getAgentKnowledgeJson(connection, method.route);
+          return validatedToolOutput(data, connection, method, formatConnectors);
+        }
+        if (args.action === 'connector' || args.action === 'connector_doctor') {
+          method = args.action === 'connector'
+            ? AGENT_KNOWLEDGE_METHODS.connectorGet
+            : AGENT_KNOWLEDGE_METHODS.connectorDoctor;
+          const connectorId = readString(args.connectorId) || readString(args.id);
+          if (!connectorId) return toolFailure('connectorId or id is required for Agent Knowledge connector lookup.');
+          const suffix = args.action === 'connector_doctor' ? '/doctor' : '';
+          const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(connectorId)}${suffix}`;
+          const data = await getAgentKnowledgeJson(connection, route);
+          return validatedToolOutput(data, connection, { ...method, route }, (validatedData) => (
+            args.action === 'connector'
+              ? formatConnector(validatedData, connectorId)
+              : formatConnectorDoctor(validatedData, connectorId)
+          ));
         }
-        const query = readString(args.query);
-        if (!query) return toolFailure('query is required for Agent Knowledge search.');
-        const method = AGENT_KNOWLEDGE_METHODS.search;
-        const data = await sdk.knowledge.search({ query, limit: readLimit(args.limit, 10) });
-        return toolOutput(formatSearch(data, query));
+        return toolFailure(`Unknown Agent Knowledge action. Valid values ${ACTIONS.join(', ')}.`);
       } catch (error) {
-        const method = args.action === 'status'
-          ? AGENT_KNOWLEDGE_METHODS.status
-          : args.action === 'ask'
-            ? AGENT_KNOWLEDGE_METHODS.ask
-            : AGENT_KNOWLEDGE_METHODS.search;
         return classifyToolKnowledgeError(error, connection, method);
       }
     },

package/src/tools/agent-local-registry-tool.ts

@@ -736,9 +736,8 @@ export function createAgentLocalRegistryTool(shellPaths: ShellPathService, memor
     definition: {
       name: 'agent_local_registry',
       description: [
-        'Inspect and maintain GoodVibes Agent-local notes, memory, personas, skills, and routines from the main conversation.',
-        'Use this for safe self-improvement: capture scratchpad notes, remember durable non-secret facts, create or refine reusable behavior, bundle related skills, enable skills/routines, choose personas, review/stale records, and start routines in the same serial conversation.',
-        'Destructive record deletion requires confirm:true plus explicitUserRequest. This tool cannot create schedules, mutate connected hosts, send messages, run background jobs, or delegate build work.',
+        'Inspect or update Agent-local records: memory, notes, personas, skills, bundles, and routines.',
+        'Deletion requires confirm:true plus explicitUserRequest.',
       ].join(' '),
       parameters: {
         type: 'object',
@@ -761,13 +760,13 @@ export function createAgentLocalRegistryTool(shellPaths: ShellPathService, memor
           steps: { type: 'string', description: 'Routine steps.' },
           skills: { type: 'array', items: { type: 'string' }, description: 'Skill ids for skill_bundle create/update.' },
           skillIds: { type: 'array', items: { type: 'string' }, description: 'Skill ids for skill_bundle create/update.' },
-          requiresEnv: { type: 'array', items: { type: 'string' }, description: 'Environment variable names required by a skill or routine. Values are never stored.' },
+          requiresEnv: { type: 'array', items: { type: 'string' }, description: 'Required environment variable names.' },
           requiresCommands: { type: 'array', items: { type: 'string' }, description: 'Command names required by a skill or routine.' },
           triggers: { type: 'array', items: { type: 'string' } },
           tags: { type: 'array', items: { type: 'string' } },
           reason: { type: 'string' },
           enabled: { type: 'boolean' },
-          activate: { type: 'boolean', description: 'Activate a created/updated persona, or clear it when updating the active persona with false.' },
+          activate: { type: 'boolean', description: 'Activate or clear the persona.' },
           provenance: { type: 'string' },
           confirm: { type: 'boolean', description: 'Required true for delete after an explicit user request.' },
           explicitUserRequest: { type: 'string', description: 'Exact user request or faithful short summary authorizing delete.' },

package/src/tools/agent-media-generate-tool.ts

@@ -53,11 +53,9 @@ export function createAgentMediaGenerateTool(
     definition: {
       name: 'agent_media_generate',
       description: [
-        'Generate image or video artifacts through configured GoodVibes Agent media providers from the main conversation.',
-        'Use only when the user explicitly asks Agent to generate media.',
-        'Generated bytes are stored as GoodVibes artifacts and the response returns artifact ids; do not print inline base64.',
-        'This tool does not use default knowledge, non-Agent knowledge segments, connected-host lifecycle routes, separate Agent jobs, delegated review, channel sends, or arbitrary route invocation.',
-        'Set confirm:true only for an explicit user request. Otherwise return the preview/confirmation error.',
+        'Generate one confirmed image or video artifact.',
+        'Use only for explicit media generation requests.',
+        'Returns artifact ids, not inline base64.',
       ].join(' '),
       parameters: {
         type: 'object',
@@ -68,7 +66,7 @@ export function createAgentMediaGenerateTool(
           },
           providerId: {
             type: 'string',
-            description: 'Optional configured media provider id. If omitted, the first generation-capable provider is used.',
+            description: 'Optional media provider id.',
           },
           modelId: {
             type: 'string',

package/src/tools/agent-notify-tool.ts

@@ -79,17 +79,16 @@ export function createAgentNotifyTool(
     definition: {
       name: 'agent_notify',
       description: [
-        'Send one plain-text notification to configured GoodVibes Agent webhook notification targets from the main conversation.',
-        'Use only when the user explicitly asks Agent to notify, message, alert, or send a configured notification.',
-        'This uses Agent-local notification webhook targets; it does not create channel routes, authorize accounts, manage connected-host hosting, create separate Agent jobs, run delegated review, or write to default knowledge or non-Agent knowledge segments.',
-        'Set confirm:true only for an explicit user request. Otherwise return the preview/confirmation error.',
+        'Send one confirmed plain-text notification.',
+        'Use only for explicit notify/message/alert requests.',
+        'Uses existing targets only.',
       ].join(' '),
       parameters: {
         type: 'object',
         properties: {
           message: {
             type: 'string',
-            description: 'Plain-text notification body to send to configured Agent notification webhook targets.',
+            description: 'Plain-text notification body.',
           },
           confirm: {
             type: 'boolean',
@@ -97,7 +96,7 @@ export function createAgentNotifyTool(
           },
           explicitUserRequest: {
             type: 'string',
-            description: 'Short quote or summary of the user request that authorized this external notification.',
+            description: 'User request authorizing this notification.',
           },
         },
         required: ['message', 'confirm', 'explicitUserRequest'],

package/src/tools/agent-operator-action-tool.ts

@@ -36,11 +36,9 @@ export function createAgentOperatorActionTool(
     definition: {
       name: 'agent_operator_action',
       description: [
-        'Perform one explicit, confirmed connected-host operator action from the main conversation.',
-        'Allowed actions are approvals.approve, approvals.deny, approvals.cancel, automation.jobs.run, automation.jobs.pause, automation.jobs.resume, automation.runs.cancel, automation.runs.retry, and schedules.run.',
-        'Use only when the user explicitly asks for that exact approval, automation job, automation run, or schedule action.',
-        'This tool never creates, edits, deletes, or discovers automation definitions; never manages connected-host hosting; never uses default knowledge, non-Agent knowledge segments, separate Agent jobs, delegated review, or arbitrary route invocation.',
-        'Set confirm:true only for an explicit user request. Otherwise return the preview/confirmation error.',
+        'Run one confirmed allowlisted operator action.',
+        'Use only for explicit approval, automation, or schedule requests.',
+        'No automation definition edits or host lifecycle.',
       ].join(' '),
       parameters: {
         type: 'object',
@@ -52,7 +50,7 @@ export function createAgentOperatorActionTool(
           },
           targetId: {
             type: 'string',
-            description: 'Generic target id. Prefer the specific approvalId, jobId, runId, or scheduleId field when known.',
+            description: 'Generic target id.',
           },
           approvalId: {
             type: 'string',
@@ -60,7 +58,7 @@ export function createAgentOperatorActionTool(
           },
           jobId: {
             type: 'string',
-            description: 'Automation job id for automation.jobs.run, automation.jobs.pause, or automation.jobs.resume.',
+            description: 'Automation job id.',
           },
           runId: {
             type: 'string',
@@ -80,7 +78,7 @@ export function createAgentOperatorActionTool(
           },
           confirm: {
             type: 'boolean',
-            description: 'Required true only when the user explicitly asked for this exact operator action.',
+            description: 'Required true for confirmed operator action.',
           },
           explicitUserRequest: {
             type: 'string',

package/src/tools/agent-operator-briefing-tool.ts

@@ -176,10 +176,9 @@ export function createAgentOperatorBriefingTool(
     definition: {
       name: 'agent_operator_briefing',
       description: [
-        'Read connected GoodVibes operator state for a concise main-conversation briefing.',
-        'Use when the user asks what needs attention, what is pending, what is scheduled, or what the operator status is.',
-        'This is read-only and calls only public work-plan, approvals, automation, schedules, and scheduler routes.',
-        'It never uses default knowledge, non-Agent knowledge segments, channel send routes, mutation routes, connected-host lifecycle, separate Agent jobs, or delegated review.',
+        'Read connected Agent operator state for a concise briefing.',
+        'Use for pending attention, approvals, automation, schedules, or status.',
+        'Read-only.',
       ].join(' '),
       parameters: {
         type: 'object',