@pellux/goodvibes-agent 0.1.47 → 0.1.49

package/src/panels/knowledge-panel.ts

@@ -2,9 +2,9 @@ import type { Line } from '../types/grid.ts';
 import { ScrollableListPanel } from './scrollable-list-panel.ts';
 import { type ConfirmState, handleConfirmInput, renderConfirmLines } from './confirm-state.ts';
 import type { MemoryClass, MemoryRecord, MemoryRegistry, MemoryReviewState } from '@pellux/goodvibes-sdk/platform/state';
+import type { KnowledgeStatus } from '@pellux/goodvibes-sdk/platform/knowledge';
 import {
   buildBodyText,
-  buildEmptyState,
   buildGuidanceLine,
   buildKeyValueLine,
   buildPanelLine,
@@ -12,6 +12,10 @@ import {
   DEFAULT_PANEL_PALETTE,
 } from './polish.ts';
 
+export interface AgentKnowledgePanelService {
+  readonly getStatus: () => Promise<KnowledgeStatus & { readonly note?: string }>;
+}
+
 function summarize(records: MemoryRecord[], cls: MemoryClass): MemoryRecord[] {
   return records.filter((record) => record.cls === cls).slice(0, 3);
 }
@@ -42,19 +46,25 @@ function formatConfidence(confidence: number): string {
 
 export class KnowledgePanel extends ScrollableListPanel<MemoryRecord> {
   private readonly registry: MemoryRegistry;
+  private readonly agentKnowledgeService: AgentKnowledgePanelService | null;
   private unsubscribe?: () => void;
   private records: MemoryRecord[] = [];
+  private agentKnowledgeStatus: (KnowledgeStatus & { readonly note?: string }) | null = null;
+  private agentKnowledgeError: string | null = null;
+  private agentKnowledgeLoading = false;
   // I1: confirm for destructive review-state mutations
   private confirm: ConfirmState<{ id: string; action: 'stale' | 'contradicted' }> | null = null;
 
-  public constructor(registry: MemoryRegistry) {
+  public constructor(registry: MemoryRegistry, agentKnowledgeService: AgentKnowledgePanelService | null = null) {
     super('knowledge', 'Knowledge', 'K', 'agent');
     this.registry = registry;
+    this.agentKnowledgeService = agentKnowledgeService;
   }
 
   public override onActivate(): void {
     super.onActivate();
     this.refresh();
+    this.refreshAgentKnowledgeStatus();
     this.unsubscribe = this.registry.subscribe(() => {
       this.refresh();
       this.markDirty();
@@ -89,12 +99,13 @@ export class KnowledgePanel extends ScrollableListPanel<MemoryRecord> {
   }
 
   protected override getPalette() { return C; }
-  protected override getEmptyStateMessage() { return 'No durable project knowledge'; }
+  protected override getEmptyStateMessage() { return 'No Agent Knowledge sources or local memory review records'; }
   protected override getEmptyStateActions() {
     return [
-      { command: '/recall add fact <summary>', summary: 'capture a durable fact directly' },
-      { command: '/recall capture incident latest', summary: 'promote the latest incident into project memory' },
-      { command: '/recall capture policy', summary: 'store the current policy posture as durable evidence' },
+      { command: '/knowledge status', summary: 'inspect the isolated Agent Knowledge store' },
+      { command: '/knowledge ingest-url <url> --yes', summary: 'ingest source-backed material into Agent Knowledge only' },
+      { command: '/knowledge queue', summary: 'review Agent Knowledge issues' },
+      { command: '/recall add fact <summary>', summary: 'capture a local non-secret memory record when appropriate' },
     ];
   }
 
@@ -198,6 +209,64 @@ export class KnowledgePanel extends ScrollableListPanel<MemoryRecord> {
     this.clampSelection();
   }
 
+  private refreshAgentKnowledgeStatus(): void {
+    if (!this.agentKnowledgeService || this.agentKnowledgeLoading) return;
+    this.agentKnowledgeLoading = true;
+    this.agentKnowledgeError = null;
+    this.agentKnowledgeService.getStatus()
+      .then((status) => {
+        this.agentKnowledgeStatus = status;
+        this.agentKnowledgeError = null;
+      })
+      .catch((error: unknown) => {
+        this.agentKnowledgeError = error instanceof Error ? error.message : String(error);
+      })
+      .finally(() => {
+        this.agentKnowledgeLoading = false;
+        this.markDirty();
+      });
+  }
+
+  private buildAgentKnowledgeHeader(width: number): Line[] {
+    const lines: Line[] = [
+      buildPanelLine(width, [[' Agent Knowledge Segment', C.label]]),
+      buildPanelLine(width, [
+        ['  route ', C.label],
+        ['/api/goodvibes-agent/knowledge/*', C.info],
+        ['  isolated: no default Knowledge/Wiki or HomeGraph fallback', C.dim],
+      ]),
+    ];
+    if (this.agentKnowledgeLoading && !this.agentKnowledgeStatus) {
+      lines.push(buildPanelLine(width, [['  loading isolated Agent Knowledge status...', C.dim]]));
+    } else if (this.agentKnowledgeStatus) {
+      const status = this.agentKnowledgeStatus;
+      lines.push(buildKeyValueLine(width, [
+        { label: 'Ready', value: status.ready ? 'yes' : 'no', valueColor: status.ready ? C.good : C.warn },
+        { label: 'Sources', value: String(status.sourceCount), valueColor: status.sourceCount > 0 ? C.info : C.dim },
+        { label: 'Nodes', value: String(status.nodeCount), valueColor: status.nodeCount > 0 ? C.info : C.dim },
+        { label: 'Issues', value: String(status.issueCount), valueColor: status.issueCount > 0 ? C.warn : C.good },
+      ], C));
+      const note = status.note ? `  note: ${status.note}` : '';
+      lines.push(buildPanelLine(width, [['  storage: ', C.label], [status.storagePath, C.dim], [note, C.dim]]));
+    } else {
+      lines.push(buildPanelLine(width, [['  status: not loaded; /knowledge status uses the same isolated route.', C.dim]]));
+    }
+    if (this.agentKnowledgeError) {
+      lines.push(...buildBodyText(width, `Agent Knowledge status warning: ${this.agentKnowledgeError}`, C, C.warn));
+    }
+    lines.push(buildPanelLine(width, [
+      ['  actions ', C.label],
+      ['/knowledge status', C.value],
+      [' | ', C.dim],
+      ['/knowledge ingest-url <url> --yes', C.value],
+      [' | ', C.dim],
+      ['/knowledge search <query>', C.value],
+      [' | ', C.dim],
+      ['/knowledge queue', C.value],
+    ]));
+    return lines;
+  }
+
   public render(width: number, height: number): Line[] {
     this.clampSelection();
 
@@ -214,12 +283,14 @@ export class KnowledgePanel extends ScrollableListPanel<MemoryRecord> {
 
     if (this.records.length === 0) this.refresh();
 
-    const intro = 'Typed project knowledge, reviewed evidence, and operator-governed memory across session, project, and team scopes.';
+    const intro = 'Isolated Agent Knowledge plus local non-secret memory review. This surface never falls back to default Knowledge/Wiki or HomeGraph.';
     const records = this.registry.search({ limit: 200 });
+    const agentKnowledgeHeader = this.buildAgentKnowledgeHeader(width);
 
     if (records.length === 0) {
       return this.renderList(width, height, {
         title: 'Knowledge Control Room',
+        header: agentKnowledgeHeader,
         footer: [buildPanelLine(width, [[' Review keys: Up/Down move  r/Enter review  s stale  c contradicted  f fresh', C.dim]])],
       });
     }
@@ -334,11 +405,11 @@ export class KnowledgePanel extends ScrollableListPanel<MemoryRecord> {
 
     return this.renderList(width, height, {
       title: 'Knowledge Control Room',
-      header: [...classLines, ...reviewLines],
+      header: [...agentKnowledgeHeader, ...classLines, ...reviewLines],
       footer: [
+        buildPanelLine(width, [['  Up/Down move  r/Enter reviewed  s stale  c contradicted  f fresh', C.dim]]),
         ...(selectedLines.length > 0 ? selectedLines : []),
         ...recentSummaryLines,
-        buildPanelLine(width, [['  Up/Down move  r/Enter reviewed  s stale  c contradicted  f fresh', C.dim]]),
       ],
     });
   }

package/src/panels/provider-health-domains.ts

@@ -104,7 +104,7 @@ export function buildProviderHealthDomainSummaries(
           .slice(0, 3)
           .map((entry) => `${entry.runnerId}: transport=${entry.transportState} heartbeat=${entry.heartbeat.status}${entry.lastError ? ` error=${entry.lastError}` : ''}`),
     nextSteps: remote.supervisor.degradedConnections > 0
-      ? ['/remote supervisor', '/remote recover <runnerId>', '/remote capabilities']
+      ? ['/remote supervisor', '/remote recover <runnerId>', '/remote support']
       : ['/remote supervisor'],
   });
 

package/src/panels/remote-panel.ts

@@ -204,8 +204,8 @@ export class RemotePanel extends BasePanel {
       ]));
     }
     postureLines.push(
-      buildGuidanceLine(width, '/remote recover', 'resume remote state with runner, capability, and disconnect recovery hints', C),
-      buildGuidanceLine(width, '/remote capabilities', 'inspect transport support before routing remote work or reattaching a session', C),
+      buildGuidanceLine(width, '/remote recover', 'resume remote state with runner support and disconnect recovery hints', C),
+      buildGuidanceLine(width, '/remote support', 'inspect transport support before routing remote work or reattaching a session', C),
     );
 
     const footerLines = [

package/src/renderer/agent-workspace.ts

@@ -67,11 +67,39 @@ function buildLeftRows(workspace: AgentWorkspace, height: number): WorkspaceRow[
 }
 
 function actionCommand(action: AgentWorkspaceAction): string {
+  if (action.kind === 'workspace') return action.targetCategoryId ? `open ${action.targetCategoryId}` : '(workspace)';
   return action.command ?? '(guidance)';
 }
 
 type ContextLine = { readonly text: string; readonly fg?: string; readonly bold?: boolean; readonly dim?: boolean };
 
+function setupStatusColor(status: AgentWorkspaceRuntimeSnapshot['setupChecklist'][number]['status']): string {
+  if (status === 'ready') return PALETTE.good;
+  if (status === 'recommended') return PALETTE.warn;
+  if (status === 'blocked') return PALETTE.bad;
+  return PALETTE.muted;
+}
+
+function setupChecklistLines(snapshot: AgentWorkspaceRuntimeSnapshot): ContextLine[] {
+  const readyCount = snapshot.setupChecklist.filter((item) => item.status === 'ready').length;
+  const recommendedCount = snapshot.setupChecklist.filter((item) => item.status === 'recommended').length;
+  const blockedCount = snapshot.setupChecklist.filter((item) => item.status === 'blocked').length;
+  const lines: ContextLine[] = [
+    { text: 'Setup Checklist', fg: PALETTE.title, bold: true },
+    { text: `${readyCount}/${snapshot.setupChecklist.length} ready; ${recommendedCount} recommended; ${blockedCount} blocked`, fg: blockedCount > 0 ? PALETTE.warn : PALETTE.info },
+  ];
+  for (const item of snapshot.setupChecklist) {
+    const command = item.command ? ` -> ${item.command}` : '';
+    lines.push({
+      text: `${item.status.toUpperCase()} ${item.label}${command}`,
+      fg: setupStatusColor(item.status),
+      bold: item.status === 'blocked',
+    });
+    lines.push({ text: `  ${item.detail}`, fg: PALETTE.muted });
+  }
+  return lines;
+}
+
 function snapshotLines(category: AgentWorkspaceCategory, snapshot: AgentWorkspaceRuntimeSnapshot | null): ContextLine[] {
   if (!snapshot) return [{ text: 'Runtime context is not loaded yet.', fg: PALETTE.warn }];
   const base: ContextLine[] = [{ text: 'Live Agent Context', fg: PALETTE.title, bold: true }];
@@ -87,14 +115,8 @@ function snapshotLines(category: AgentWorkspaceCategory, snapshot: AgentWorkspac
       { text: `Daemon ownership: ${snapshot.daemonOwnership}; Agent never starts or restarts it`, fg: PALETTE.good },
       { text: `Workspace: ${snapshot.workingDirectory}`, fg: PALETTE.muted },
       { text: `Home: ${snapshot.homeDirectory}`, fg: PALETTE.muted },
-    );
-  } else if (category.id === 'capabilities') {
-    base.push(
-      { text: `External daemon: ${snapshot.daemonBaseUrl}`, fg: PALETTE.info },
-      { text: 'Live audit source: /api/control-plane/methods plus /api/goodvibes-agent/knowledge/status.', fg: PALETTE.info },
-      { text: 'Isolation: no default Knowledge/Wiki, HomeGraph, or Home Assistant route is used for Agent Knowledge coverage.', fg: PALETTE.good },
-      { text: 'Readiness meaning: daemon route coverage is platform capability; missing Agent UX remains a product gap to close here.', fg: PALETTE.muted },
-      { text: 'Use filtered audits for knowledge, channels, automation, voice/media/nodes, providers, MCP/tools, approvals, or sessions.', fg: PALETTE.muted },
+      { text: '' },
+      ...setupChecklistLines(snapshot),
     );
   } else if (category.id === 'channels') {
     const enabledCount = snapshot.channels.filter((channel) => channel.enabled).length;
@@ -275,10 +297,17 @@ function footerText(workspace: AgentWorkspace): string {
 }
 
 export function renderAgentWorkspace(workspace: AgentWorkspace, width: number, height: number): Line[] {
-  const layoutOptions = { width, height, leftWidth: width < 90 ? undefined : 30, contextRatio: 0.62, minContextRows: 10 };
-  const metrics = getFullscreenWorkspaceMetrics(layoutOptions);
   const category = workspace.selectedCategory;
   const action = workspace.selectedAction;
+  const setupCategory = category.id === 'setup';
+  const layoutOptions = {
+    width,
+    height,
+    leftWidth: width < 90 ? undefined : 30,
+    contextRatio: setupCategory ? 0.86 : 0.62,
+    minContextRows: setupCategory ? 18 : 10,
+  };
+  const metrics = getFullscreenWorkspaceMetrics(layoutOptions);
 
   return renderFullscreenWorkspace({
     width,

package/src/runtime/bootstrap-core.ts

@@ -30,6 +30,7 @@ import { registerBootstrapRuntimeEvents } from '@/runtime/index.ts';
 import { createRuntimeServices, type RuntimeServices } from './services.ts';
 import { createUiRuntimeServices, type UiRuntimeServices } from './ui-services.ts';
 import { installAgentToolPolicyGuard } from '../tools/wrfc-agent-guard.ts';
+import { registerAgentLocalRegistryTool } from '../tools/agent-local-registry-tool.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
 
 export interface BootstrapCoreState {
@@ -227,6 +228,7 @@ export async function initializeBootstrapCore(
     overflowHandler: services.overflowHandler,
     changeTracker: services.sessionChangeTracker,
   });
+  registerAgentLocalRegistryTool(toolRegistry, services.shellPaths);
   installAgentToolPolicyGuard(toolRegistry, {
     getLastUserMessage: () => conversation.getLastUserMessage(),
   });

package/src/runtime/bootstrap-shell.ts

@@ -135,6 +135,7 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     sandboxSessionRegistry: services.sandboxSessionRegistry,
     systemMessagesPanel,
     memoryRegistry: services.memoryRegistry,
+    agentKnowledgeService: services.agentKnowledgeService,
     uiServices,
     pluginManager: services.pluginManager,
     hookDispatcher: services.hookDispatcher,

package/src/runtime/bootstrap.ts

@@ -48,6 +48,7 @@ const GOODVIBES_AGENT_OPERATOR_POLICY = [
   '## GoodVibes Agent Operator Policy',
   '- Default to serial, proactive assistant work in the main conversation. Answer, inspect, summarize, remember useful non-secret facts, configure local Agent state, use read-only daemon/operator routes, and take safe non-destructive actions without spawning local agents or WRFC.',
   '- GoodVibes Agent connects to an externally managed GoodVibes daemon. Do not start, stop, restart, install, expose, or mutate daemon/listener/control-plane surface posture from Agent runtime.',
+  '- Use the `agent_local_registry` tool when a reusable persona, skill, or routine would improve future work. Keep those records local, non-secret, source/provenance tagged, and reviewable. Starting a routine means applying its steps in this same serial conversation, not creating a background job.',
   '- WRFC is never the default Agent reasoning path. Do not create local WRFC chains for planning, research, operations, knowledge, memory, configuration, approvals, automation observability, or ordinary assistant work.',
   '- GoodVibes Agent is not the coding TUI. Do not use the `agent` tool to spawn local Engineer, Reviewer, Tester, Verifier, or batch-spawn roots from Agent.',
   '- When the user explicitly asks to build, implement, fix, patch, or review code, preserve the full original user ask and delegate one build request to GoodVibes TUI through the public shared-session/build-delegation contract. Include clear executionIntent and request WRFC only for explicit build/fix/review work or when the user explicitly asks for WRFC/agent review.',

package/src/tools/agent-context-policy.ts

@@ -3,13 +3,13 @@ import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
 const CONTEXT_TOOL_DENIAL = [
   'GoodVibes Agent does not expose copied GoodVibes runtime context through model tools in the main conversation.',
   'The copied context tool can describe TUI/default runtime assumptions that are not the Agent product boundary.',
-  'Use explicit Agent CLI/slash commands such as status, compat, capabilities, and isolated Agent Knowledge instead.',
+  'Use explicit Agent CLI/slash commands such as status, compat, setup, and isolated Agent Knowledge instead.',
 ].join(' ');
 
 export function wrapBlockedContextToolForAgentPolicy(tool: Tool): void {
   tool.definition.description = [
     'Blocked in GoodVibes Agent main conversation: copied runtime context.',
-    'Use explicit Agent CLI/slash status, compat, capabilities, and Agent Knowledge commands for product-scoped context.',
+    'Use explicit Agent CLI/slash status, compat, setup, and Agent Knowledge commands for product-scoped context.',
     'Default Knowledge/Wiki, HomeGraph, and copied TUI runtime assumptions are not Agent fallbacks.',
   ].join(' ');
   tool.definition.sideEffects = [];

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

@@ -0,0 +1,341 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { AgentPersonaRegistry, type AgentPersonaRecord } from '../agent/persona-registry.ts';
+import { AgentRoutineRegistry, type AgentRoutineRecord } from '../agent/routine-registry.ts';
+import { AgentSkillRegistry, type AgentSkillRecord } from '../agent/skill-registry.ts';
+
+export type AgentLocalRegistryDomain = 'persona' | 'skill' | 'routine';
+export type AgentLocalRegistryAction =
+  | 'list'
+  | 'search'
+  | 'get'
+  | 'create'
+  | 'update'
+  | 'enable'
+  | 'disable'
+  | 'review'
+  | 'stale'
+  | 'use'
+  | 'clear_active'
+  | 'start';
+
+export interface AgentLocalRegistryToolArgs {
+  readonly domain?: unknown;
+  readonly action?: unknown;
+  readonly id?: unknown;
+  readonly query?: unknown;
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly body?: unknown;
+  readonly procedure?: unknown;
+  readonly steps?: unknown;
+  readonly triggers?: unknown;
+  readonly tags?: unknown;
+  readonly reason?: unknown;
+  readonly enabled?: unknown;
+  readonly provenance?: unknown;
+}
+
+const DOMAINS: readonly AgentLocalRegistryDomain[] = ['persona', 'skill', 'routine'];
+const ACTIONS: readonly AgentLocalRegistryAction[] = [
+  'list',
+  'search',
+  'get',
+  'create',
+  'update',
+  'enable',
+  'disable',
+  'review',
+  'stale',
+  'use',
+  'clear_active',
+  'start',
+];
+
+function isDomain(value: unknown): value is AgentLocalRegistryDomain {
+  return typeof value === 'string' && DOMAINS.includes(value as AgentLocalRegistryDomain);
+}
+
+function isAction(value: unknown): value is AgentLocalRegistryAction {
+  return typeof value === 'string' && ACTIONS.includes(value as AgentLocalRegistryAction);
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readStringList(value: unknown): readonly string[] {
+  if (typeof value === 'string') {
+    return value.split(',').map((entry) => entry.trim()).filter(Boolean);
+  }
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function registryError(message: string): { readonly success: false; readonly error: string } {
+  return { success: false, error: message };
+}
+
+function registryOutput(output: string): { readonly success: true; readonly output: string } {
+  return { success: true, output };
+}
+
+function requireId(args: AgentLocalRegistryToolArgs): string {
+  const id = readString(args.id);
+  if (!id) throw new Error('id is required.');
+  return id;
+}
+
+function requireName(args: AgentLocalRegistryToolArgs): string {
+  const name = readString(args.name);
+  if (!name) throw new Error('name is required.');
+  return name;
+}
+
+function requireDescription(args: AgentLocalRegistryToolArgs): string {
+  const description = readString(args.description);
+  if (!description) throw new Error('description is required.');
+  return description;
+}
+
+function formatPersona(persona: AgentPersonaRecord, activeId: string | null): string {
+  const active = persona.id === activeId ? 'active' : 'inactive';
+  return `${persona.id}  ${active}  ${persona.reviewState}  ${persona.name} - ${persona.description}`;
+}
+
+function formatSkill(skill: AgentSkillRecord): string {
+  const enabled = skill.enabled ? 'enabled' : 'disabled';
+  return `${skill.id}  ${enabled}  ${skill.reviewState}  ${skill.name} - ${skill.description}`;
+}
+
+function formatRoutine(routine: AgentRoutineRecord): string {
+  const enabled = routine.enabled ? 'enabled' : 'disabled';
+  return `${routine.id}  ${enabled}  ${routine.reviewState}  starts=${routine.startCount}  ${routine.name} - ${routine.description}`;
+}
+
+function listPersonas(registry: AgentPersonaRegistry, records: readonly AgentPersonaRecord[], title: string): string {
+  const snapshot = registry.snapshot();
+  return records.length === 0
+    ? `${title}\nNo Agent-local personas.`
+    : [title, ...records.map((persona) => formatPersona(persona, snapshot.activePersonaId))].join('\n');
+}
+
+function listSkills(records: readonly AgentSkillRecord[], title: string): string {
+  return records.length === 0
+    ? `${title}\nNo Agent-local skills.`
+    : [title, ...records.map(formatSkill)].join('\n');
+}
+
+function listRoutines(records: readonly AgentRoutineRecord[], title: string): string {
+  return records.length === 0
+    ? `${title}\nNo Agent-local routines.`
+    : [title, ...records.map(formatRoutine)].join('\n');
+}
+
+function handlePersona(shellPaths: ShellPathService, action: AgentLocalRegistryAction, args: AgentLocalRegistryToolArgs): string {
+  const registry = AgentPersonaRegistry.fromShellPaths(shellPaths);
+  if (action === 'list') return listPersonas(registry, registry.list(), 'Agent-local personas');
+  if (action === 'search') return listPersonas(registry, registry.search(readString(args.query)), 'Agent-local personas search');
+  if (action === 'get') {
+    const persona = registry.get(requireId(args));
+    if (!persona) return `Unknown Agent-local persona: ${readString(args.id)}`;
+    return [
+      formatPersona(persona, registry.snapshot().activePersonaId),
+      `triggers: ${persona.triggers.join(', ') || '(manual)'}`,
+      `tags: ${persona.tags.join(', ') || '(none)'}`,
+      '',
+      persona.body,
+    ].join('\n');
+  }
+  if (action === 'create') {
+    const persona = registry.create({
+      name: requireName(args),
+      description: requireDescription(args),
+      body: readString(args.body),
+      tags: readStringList(args.tags),
+      triggers: readStringList(args.triggers),
+      source: 'agent',
+      provenance: readString(args.provenance) || 'agent-local-registry-tool',
+    });
+    return `Created Agent-local persona ${persona.id}: ${persona.name}`;
+  }
+  if (action === 'update') {
+    const persona = registry.update(requireId(args), {
+      name: readString(args.name) || undefined,
+      description: readString(args.description) || undefined,
+      body: readString(args.body) || undefined,
+      tags: args.tags === undefined ? undefined : readStringList(args.tags),
+      triggers: args.triggers === undefined ? undefined : readStringList(args.triggers),
+      provenance: readString(args.provenance) || 'agent-local-registry-tool',
+    });
+    return `Updated Agent-local persona ${persona.id}: ${persona.name}`;
+  }
+  if (action === 'use') {
+    const persona = registry.setActive(requireId(args));
+    return `Active Agent-local persona set to ${persona.id}: ${persona.name}`;
+  }
+  if (action === 'clear_active') {
+    registry.clearActive();
+    return 'Cleared active Agent-local persona.';
+  }
+  if (action === 'review') return `Reviewed Agent-local persona ${registry.markReviewed(requireId(args)).id}.`;
+  if (action === 'stale') return `Marked Agent-local persona ${registry.markStale(requireId(args), readString(args.reason)).id} stale.`;
+  throw new Error(`Action ${action} is not valid for personas.`);
+}
+
+function handleSkill(shellPaths: ShellPathService, action: AgentLocalRegistryAction, args: AgentLocalRegistryToolArgs): string {
+  const registry = AgentSkillRegistry.fromShellPaths(shellPaths);
+  if (action === 'list') return listSkills(registry.list(), 'Agent-local skills');
+  if (action === 'search') return listSkills(registry.search(readString(args.query)), 'Agent-local skills search');
+  if (action === 'get') {
+    const skill = registry.get(requireId(args));
+    if (!skill) return `Unknown Agent-local skill: ${readString(args.id)}`;
+    return [
+      formatSkill(skill),
+      `triggers: ${skill.triggers.join(', ') || '(manual)'}`,
+      `tags: ${skill.tags.join(', ') || '(none)'}`,
+      '',
+      skill.procedure,
+    ].join('\n');
+  }
+  if (action === 'create') {
+    const skill = registry.create({
+      name: requireName(args),
+      description: requireDescription(args),
+      procedure: readString(args.procedure),
+      triggers: readStringList(args.triggers),
+      tags: readStringList(args.tags),
+      enabled: args.enabled === true,
+      source: 'agent',
+      provenance: readString(args.provenance) || 'agent-local-registry-tool',
+    });
+    return `Created Agent-local skill ${skill.id}: ${skill.name}`;
+  }
+  if (action === 'update') {
+    const skill = registry.update(requireId(args), {
+      name: readString(args.name) || undefined,
+      description: readString(args.description) || undefined,
+      procedure: readString(args.procedure) || undefined,
+      triggers: args.triggers === undefined ? undefined : readStringList(args.triggers),
+      tags: args.tags === undefined ? undefined : readStringList(args.tags),
+      provenance: readString(args.provenance) || 'agent-local-registry-tool',
+    });
+    return `Updated Agent-local skill ${skill.id}: ${skill.name}`;
+  }
+  if (action === 'enable' || action === 'disable') {
+    const skill = registry.setEnabled(requireId(args), action === 'enable');
+    return `${action === 'enable' ? 'Enabled' : 'Disabled'} Agent-local skill ${skill.id}: ${skill.name}`;
+  }
+  if (action === 'review') return `Reviewed Agent-local skill ${registry.markReviewed(requireId(args)).id}.`;
+  if (action === 'stale') return `Marked Agent-local skill ${registry.markStale(requireId(args), readString(args.reason)).id} stale.`;
+  throw new Error(`Action ${action} is not valid for skills.`);
+}
+
+function handleRoutine(shellPaths: ShellPathService, action: AgentLocalRegistryAction, args: AgentLocalRegistryToolArgs): string {
+  const registry = AgentRoutineRegistry.fromShellPaths(shellPaths);
+  if (action === 'list') return listRoutines(registry.list(), 'Agent-local routines');
+  if (action === 'search') return listRoutines(registry.search(readString(args.query)), 'Agent-local routines search');
+  if (action === 'get') {
+    const routine = registry.get(requireId(args));
+    if (!routine) return `Unknown Agent-local routine: ${readString(args.id)}`;
+    return [
+      formatRoutine(routine),
+      `triggers: ${routine.triggers.join(', ') || '(manual)'}`,
+      `tags: ${routine.tags.join(', ') || '(none)'}`,
+      '',
+      routine.steps,
+    ].join('\n');
+  }
+  if (action === 'create') {
+    const routine = registry.create({
+      name: requireName(args),
+      description: requireDescription(args),
+      steps: readString(args.steps),
+      triggers: readStringList(args.triggers),
+      tags: readStringList(args.tags),
+      enabled: args.enabled === true,
+      source: 'agent',
+      provenance: readString(args.provenance) || 'agent-local-registry-tool',
+    });
+    return `Created Agent-local routine ${routine.id}: ${routine.name}`;
+  }
+  if (action === 'update') {
+    const routine = registry.update(requireId(args), {
+      name: readString(args.name) || undefined,
+      description: readString(args.description) || undefined,
+      steps: readString(args.steps) || undefined,
+      triggers: args.triggers === undefined ? undefined : readStringList(args.triggers),
+      tags: args.tags === undefined ? undefined : readStringList(args.tags),
+      provenance: readString(args.provenance) || 'agent-local-registry-tool',
+    });
+    return `Updated Agent-local routine ${routine.id}: ${routine.name}`;
+  }
+  if (action === 'enable' || action === 'disable') {
+    const routine = registry.setEnabled(requireId(args), action === 'enable');
+    return `${action === 'enable' ? 'Enabled' : 'Disabled'} Agent-local routine ${routine.id}: ${routine.name}`;
+  }
+  if (action === 'start') {
+    const routine = registry.markStarted(requireId(args));
+    return [
+      `Started Agent-local routine ${routine.id}: ${routine.name}`,
+      'Policy: same main conversation; no hidden background job, daemon mutation, or external side effect was started.',
+      '',
+      routine.steps,
+    ].join('\n');
+  }
+  if (action === 'review') return `Reviewed Agent-local routine ${registry.markReviewed(requireId(args)).id}.`;
+  if (action === 'stale') return `Marked Agent-local routine ${registry.markStale(requireId(args), readString(args.reason)).id} stale.`;
+  throw new Error(`Action ${action} is not valid for routines.`);
+}
+
+export function createAgentLocalRegistryTool(shellPaths: ShellPathService): Tool {
+  return {
+    definition: {
+      name: 'agent_local_registry',
+      description: [
+        'Inspect and maintain GoodVibes Agent-local personas, skills, and routines from the main conversation.',
+        'Use this for safe self-improvement: create or refine reusable behavior, enable skills/routines, choose personas, review/stale records, and start routines in the same serial conversation.',
+        'This tool cannot delete records, create schedules, mutate the daemon, send messages, run background jobs, or delegate build work.',
+      ].join(' '),
+      parameters: {
+        type: 'object',
+        properties: {
+          domain: { type: 'string', enum: [...DOMAINS] },
+          action: { type: 'string', enum: [...ACTIONS] },
+          id: { type: 'string' },
+          query: { type: 'string' },
+          name: { type: 'string' },
+          description: { type: 'string' },
+          body: { type: 'string', description: 'Persona body/instructions.' },
+          procedure: { type: 'string', description: 'Skill procedure.' },
+          steps: { type: 'string', description: 'Routine steps.' },
+          triggers: { type: 'array', items: { type: 'string' } },
+          tags: { type: 'array', items: { type: 'string' } },
+          reason: { type: 'string' },
+          enabled: { type: 'boolean' },
+          provenance: { type: 'string' },
+        },
+        required: ['domain', 'action'],
+        additionalProperties: false,
+      },
+      sideEffects: ['state'],
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = rawArgs as AgentLocalRegistryToolArgs;
+      if (!isDomain(args.domain)) return registryError(`Unknown domain. Valid: ${DOMAINS.join(', ')}.`);
+      if (!isAction(args.action)) return registryError(`Unknown action. Valid: ${ACTIONS.join(', ')}.`);
+      try {
+        if (args.domain === 'persona') return registryOutput(handlePersona(shellPaths, args.action, args));
+        if (args.domain === 'skill') return registryOutput(handleSkill(shellPaths, args.action, args));
+        return registryOutput(handleRoutine(shellPaths, args.action, args));
+      } catch (error) {
+        return registryError(error instanceof Error ? error.message : String(error));
+      }
+    },
+  };
+}
+
+export function registerAgentLocalRegistryTool(registry: ToolRegistry, shellPaths: ShellPathService): void {
+  registry.register(createAgentLocalRegistryTool(shellPaths));
+}