@pellux/goodvibes-agent 1.1.7 → 1.2.0

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

@@ -0,0 +1,159 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { CommandContext, CommandRegistry } from '../input/command-registry.ts';
+import { createAgentHarnessTool } from './agent-harness-tool.ts';
+
+type AgentHostAction =
+  | 'status'
+  | 'capabilities'
+  | 'capability'
+  | 'services'
+  | 'service'
+  | 'methods'
+  | 'method';
+
+interface AgentHostToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly capabilityId?: unknown;
+  readonly endpointId?: unknown;
+  readonly methodId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentHostToolDeps {
+  readonly commandRegistry: CommandRegistry;
+  readonly commandContext: CommandContext;
+  readonly toolRegistry: ToolRegistry;
+  readonly harnessTool?: Tool;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeHostAction(value: unknown): AgentHostAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'health' || action === 'readiness' || action === 'daemon_status' || action === 'connected_host_status') return 'status';
+  if (action === 'capabilities' || action === 'capability_map' || action === 'map' || action === 'inventory' || action === 'connected_host' || action === 'daemon' || action === 'host' || action === 'boundaries') return 'capabilities';
+  if (action === 'capability' || action === 'show_capability' || action === 'inspect_capability' || action === 'connected_host_capability') return 'capability';
+  if (action === 'services' || action === 'service_posture' || action === 'service_status' || action === 'endpoints' || action === 'endpoint_list') return 'services';
+  if (action === 'service' || action === 'endpoint' || action === 'service_endpoint') return 'service';
+  if (action === 'methods' || action === 'operator_methods' || action === 'operator_contract' || action === 'operations' || action === 'actions') return 'methods';
+  if (action === 'method' || action === 'operator_method' || action === 'operation') return 'method';
+  return null;
+}
+
+function readAction(args: AgentHostToolArgs): AgentHostAction {
+  const explicit = normalizeHostAction(args.action) ?? normalizeHostAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.methodId)) return 'method';
+  if (readString(args.endpointId)) return 'service';
+  if (readString(args.capabilityId) || readString(args.target) || readString(args.query)) return 'capability';
+  return 'status';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+export function createAgentHostTool(deps: AgentHostToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'host',
+      description: 'Inspect GoodVibes host status, services, and methods.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'capabilities', 'capability', 'services', 'service', 'methods', 'method'],
+            description: 'Read host status, capabilities, services, and method posture.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          capabilityId: { type: 'string', description: 'Connected-host capability id.' },
+          endpointId: { type: 'string', description: 'Service endpoint id.' },
+          methodId: { type: 'string', description: 'Daemon operator method id.' },
+          target: { type: 'string', description: 'Lookup target for a capability, endpoint, or method.' },
+          query: { type: 'string', description: 'Search text for capabilities or methods.' },
+          includeParameters: { type: 'boolean', description: 'Include detailed method schemas, route families, probes, or diagnostics.' },
+          limit: { type: 'number', description: 'Maximum methods to return for action:methods.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentHostToolArgs;
+      const action = readAction(args);
+
+      if (action === 'status') {
+        return harnessTool.execute(compactArgs({
+          mode: 'connected_host_status',
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'capabilities') {
+        return harnessTool.execute(compactArgs({
+          mode: 'connected_host',
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'capability') {
+        return harnessTool.execute(compactArgs({
+          mode: 'connected_host_capability',
+          capabilityId: args.capabilityId,
+          target: args.target,
+          query: args.query,
+        }));
+      }
+      if (action === 'services') {
+        return harnessTool.execute(compactArgs({
+          mode: 'service_posture',
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'service') {
+        return harnessTool.execute(compactArgs({
+          mode: 'service_endpoint',
+          endpointId: args.endpointId,
+          target: args.target,
+          query: args.query,
+        }));
+      }
+      if (action === 'methods') {
+        return harnessTool.execute(compactArgs({
+          mode: 'operator_methods',
+          query: args.query ?? args.target,
+          includeParameters: args.includeParameters,
+          limit: args.limit,
+        }));
+      }
+      return harnessTool.execute(compactArgs({
+        mode: 'operator_method',
+        methodId: args.methodId,
+        target: args.target,
+        query: args.query,
+      }));
+    },
+  };
+}
+
+export function registerAgentHostTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('host')) registry.register(createAgentHostTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

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

@@ -14,6 +14,7 @@ import { formatBatchIngest, formatFailure, formatIngest } from '../cli/agent-kno
 export type AgentKnowledgeIngestSourceKind =
   | 'url'
   | 'file'
+  | 'artifact'
   | 'urls_file'
   | 'bookmarks_file'
   | 'browser_history'
@@ -23,6 +24,7 @@ export interface AgentKnowledgeIngestToolArgs {
   readonly sourceKind?: unknown;
   readonly url?: unknown;
   readonly path?: unknown;
+  readonly artifactId?: unknown;
   readonly title?: unknown;
   readonly tags?: unknown;
   readonly folderPath?: unknown;
@@ -44,6 +46,7 @@ type JsonRecord = Record<string, unknown>;
 interface AgentKnowledgeIngestRequest {
   readonly method: typeof AGENT_KNOWLEDGE_METHODS[keyof typeof AGENT_KNOWLEDGE_METHODS];
   readonly target: string;
+  readonly targetLabel: string;
   readonly label: string;
   readonly payload: JsonRecord;
   readonly batch: boolean;
@@ -52,6 +55,7 @@ interface AgentKnowledgeIngestRequest {
 const SOURCE_KINDS: readonly AgentKnowledgeIngestSourceKind[] = [
   'url',
   'file',
+  'artifact',
   'urls_file',
   'bookmarks_file',
   'browser_history',
@@ -161,6 +165,7 @@ function requestForArgs(args: AgentKnowledgeIngestToolArgs): AgentKnowledgeInges
     return {
       method: AGENT_KNOWLEDGE_METHODS.ingestUrl,
       target: url,
+      targetLabel: 'url',
       label: 'URL ingest',
       batch: false,
       payload: {
@@ -180,6 +185,7 @@ function requestForArgs(args: AgentKnowledgeIngestToolArgs): AgentKnowledgeInges
     return {
       method: AGENT_KNOWLEDGE_METHODS.ingestArtifact,
       target: path,
+      targetLabel: 'file',
       label: 'file ingest',
       batch: false,
       payload: {
@@ -194,6 +200,26 @@ function requestForArgs(args: AgentKnowledgeIngestToolArgs): AgentKnowledgeInges
     };
   }
 
+  if (sourceKind === 'artifact') {
+    const artifactId = readString(args.artifactId);
+    if (!artifactId) throw new Error('artifactId is required.');
+    return {
+      method: AGENT_KNOWLEDGE_METHODS.ingestArtifact,
+      target: artifactId,
+      targetLabel: 'artifact',
+      label: 'artifact ingest',
+      batch: false,
+      payload: {
+        artifactId,
+        title,
+        tags: [...tags],
+        folderPath: readOptionalString(args.folderPath),
+        connectorId: readOptionalString(args.connectorId) ?? 'goodvibes-agent-artifact-browser',
+        metadata: originMetadata,
+      },
+    };
+  }
+
   if (sourceKind === 'urls_file' || sourceKind === 'bookmarks_file') {
     const path = readString(args.path);
     if (!path) throw new Error('path is required.');
@@ -201,6 +227,7 @@ function requestForArgs(args: AgentKnowledgeIngestToolArgs): AgentKnowledgeInges
     return {
       method,
       target: path,
+      targetLabel: 'file',
       label: sourceKind === 'urls_file' ? 'URL-list import' : 'bookmarks import',
       batch: true,
       payload: {
@@ -215,6 +242,7 @@ function requestForArgs(args: AgentKnowledgeIngestToolArgs): AgentKnowledgeInges
     return {
       method: AGENT_KNOWLEDGE_METHODS.ingestBrowserHistory,
       target: 'local browser history',
+      targetLabel: 'source',
       label: 'browser-history import',
       batch: true,
       payload: {
@@ -240,6 +268,7 @@ function requestForArgs(args: AgentKnowledgeIngestToolArgs): AgentKnowledgeInges
   return {
     method: AGENT_KNOWLEDGE_METHODS.ingestConnector,
     target: connectorId,
+    targetLabel: 'connector',
     label: 'connector ingest',
     batch: true,
     payload: {
@@ -278,6 +307,10 @@ export function createAgentKnowledgeIngestTool(
             type: 'string',
             description: 'Local file or import path.',
           },
+          artifactId: {
+            type: 'string',
+            description: 'Saved artifact id when sourceKind is artifact.',
+          },
           title: {
             type: 'string',
             description: 'Optional source title for url or file ingest.',
@@ -381,7 +414,7 @@ export function createAgentKnowledgeIngestTool(
             request.target,
             request.label,
             request.method.route,
-            request.label === 'file ingest' ? 'file' : 'url',
+            request.targetLabel,
           ));
       } catch (error) {
         return failure(formatKnowledgeFailure(await classifyKnowledgeError(error, connection, request.method.route)));

package/src/tools/agent-learning-consolidation-core.ts

@@ -0,0 +1,327 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { MemoryBundle, MemoryRecord, MemoryRegistry } from '@pellux/goodvibes-sdk/platform/state';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import type { CommandContext } from '../input/command-registry.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';
+import {
+  resolveLearningConsolidationCandidate,
+  type LearningCandidate,
+  type LearningConsolidationFields,
+} from './agent-harness-learning-curator.ts';
+
+export type AgentLearningConsolidationMode = 'preview' | 'merge' | 'stale' | 'delete' | 'rollback' | 'recreate' | 'receipts';
+export type AgentLearningConsolidationDomain = 'memory' | 'persona' | 'skill' | 'routine';
+export type AgentLearningConsolidationWriteMode = 'merge' | 'stale' | 'delete' | 'rollback' | 'recreate';
+
+export interface AgentLearningConsolidationToolArgs {
+  readonly mode?: unknown;
+  readonly candidateId?: unknown;
+  readonly query?: unknown;
+  readonly receiptId?: unknown;
+  readonly limit?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+export interface LearningConsolidationReceipt {
+  readonly id: string;
+  readonly createdAt: string;
+  readonly domain: AgentLearningConsolidationDomain;
+  readonly candidateId: string;
+  readonly phase: AgentLearningConsolidationWriteMode;
+  readonly explicitUserRequest: string;
+  readonly survivorId: string;
+  readonly duplicateIds: readonly string[];
+  readonly beforeSurvivor?: Record<string, unknown>;
+  readonly beforeDuplicates: readonly Record<string, unknown>[];
+}
+
+export interface LearningConsolidationReceiptFile {
+  readonly version: 1;
+  readonly receipts: readonly LearningConsolidationReceipt[];
+}
+
+export const MODES: readonly AgentLearningConsolidationMode[] = ['preview', 'merge', 'stale', 'delete', 'rollback', 'recreate', 'receipts'];
+export const WRITE_MODES = new Set<AgentLearningConsolidationMode>(['merge', 'stale', 'delete', 'rollback', 'recreate']);
+export const RECEIPT_LIMIT = 100;
+export const MEMORY_CLASSES = new Set(['decision', 'constraint', 'incident', 'pattern', 'fact', 'risk', 'runbook', 'architecture', 'ownership']);
+export const MEMORY_SCOPES = new Set(['session', 'project', 'team']);
+export const MEMORY_REVIEW_STATES = new Set(['fresh', 'reviewed', 'stale', 'contradicted']);
+
+export function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function readMode(value: unknown): AgentLearningConsolidationMode {
+  return typeof value === 'string' && MODES.includes(value as AgentLearningConsolidationMode)
+    ? value as AgentLearningConsolidationMode
+    : 'preview';
+}
+
+export 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(RECEIPT_LIMIT, Math.trunc(parsed)));
+}
+
+function slugifyForDomain(value: string, fallback: AgentLearningConsolidationDomain): string {
+  const slug = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return slug || fallback;
+}
+
+export function nextGeneratedId(name: string, occupiedIds: Set<string>, fallback: AgentLearningConsolidationDomain): string {
+  const base = slugifyForDomain(name, fallback);
+  if (!occupiedIds.has(base)) return base;
+  for (let index = 2; index < 1000; index += 1) {
+    const candidate = `${base}-${index}`;
+    if (!occupiedIds.has(candidate)) return candidate;
+  }
+  throw new Error(`Could not allocate ${fallback} id for ${name}.`);
+}
+
+export function output(value: unknown): { readonly success: true; readonly output: string } {
+  return { success: true, output: JSON.stringify(value, null, 2) };
+}
+
+export function failure(error: string): { readonly success: false; readonly error: string } {
+  return { success: false, error };
+}
+
+export function requireConfirmedWrite(args: AgentLearningConsolidationToolArgs, mode: AgentLearningConsolidationWriteMode): string {
+  const explicitUserRequest = readString(args.explicitUserRequest);
+  if (!explicitUserRequest) throw new Error(`${mode} requires explicitUserRequest with the user's exact request or a short faithful summary.`);
+  if (args.confirm !== true) throw new Error(`${mode} requires confirm:true after an explicit user request.`);
+  return explicitUserRequest;
+}
+
+function isDomain(value: string): value is AgentLearningConsolidationDomain {
+  return value === 'memory' || value === 'persona' || value === 'skill' || value === 'routine';
+}
+
+export function receiptPath(shellPaths: ShellPathService): string {
+  return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'learning', 'consolidation-receipts.json');
+}
+
+function parseReceipt(value: unknown): LearningConsolidationReceipt | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const id = readString(record.id);
+  const createdAt = readString(record.createdAt);
+  const domain = readString(record.domain);
+  const candidateId = readString(record.candidateId);
+  const phase = readString(record.phase);
+  const explicitUserRequest = readString(record.explicitUserRequest);
+  const survivorId = readString(record.survivorId);
+  const duplicateIds = Array.isArray(record.duplicateIds)
+    ? record.duplicateIds.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+  const beforeDuplicates = Array.isArray(record.beforeDuplicates)
+    ? record.beforeDuplicates.filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null && !Array.isArray(entry))
+    : [];
+  if (
+    !id
+    || !createdAt
+    || !isDomain(domain)
+    || !candidateId
+    || !['merge', 'stale', 'delete', 'rollback', 'recreate'].includes(phase)
+    || !explicitUserRequest
+    || !survivorId
+  ) return null;
+  const beforeSurvivor = typeof record.beforeSurvivor === 'object' && record.beforeSurvivor !== null && !Array.isArray(record.beforeSurvivor)
+    ? record.beforeSurvivor as Record<string, unknown>
+    : undefined;
+  return {
+    id,
+    createdAt,
+    domain,
+    candidateId,
+    phase: phase as AgentLearningConsolidationWriteMode,
+    explicitUserRequest,
+    survivorId,
+    duplicateIds,
+    ...(beforeSurvivor ? { beforeSurvivor } : {}),
+    beforeDuplicates,
+  };
+}
+
+export function readReceiptFile(shellPaths: ShellPathService): LearningConsolidationReceiptFile {
+  const path = receiptPath(shellPaths);
+  if (!existsSync(path)) return { version: 1, receipts: [] };
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return { version: 1, receipts: [] };
+    const receipts = Array.isArray((parsed as Record<string, unknown>).receipts)
+      ? ((parsed as Record<string, unknown>).receipts as unknown[]).map(parseReceipt).filter((entry): entry is LearningConsolidationReceipt => entry !== null)
+      : [];
+    return { version: 1, receipts };
+  } catch {
+    return { version: 1, receipts: [] };
+  }
+}
+
+export function writeReceipt(shellPaths: ShellPathService, receipt: LearningConsolidationReceipt): void {
+  const path = receiptPath(shellPaths);
+  const current = readReceiptFile(shellPaths).receipts;
+  const next: LearningConsolidationReceiptFile = {
+    version: 1,
+    receipts: [receipt, ...current.filter((entry) => entry.id !== receipt.id)].slice(0, RECEIPT_LIMIT),
+  };
+  mkdirSync(dirname(path), { recursive: true });
+  const tmpPath = `${path}.tmp`;
+  writeFileSync(tmpPath, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+  renameSync(tmpPath, path);
+}
+
+export function receiptId(candidate: LearningCandidate, phase: AgentLearningConsolidationWriteMode): string {
+  const slug = candidate.id.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'candidate';
+  return `lcon-${phase}-${Date.now().toString(36)}-${slug}`;
+}
+
+export function receiptIdFromReceipt(receipt: LearningConsolidationReceipt, phase: AgentLearningConsolidationWriteMode): string {
+  const slug = receipt.candidateId.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'receipt';
+  return `lcon-${phase}-${Date.now().toString(36)}-${slug}`;
+}
+
+function minimalContext(shellPaths: ShellPathService, memoryRegistry: MemoryRegistry): CommandContext {
+  return {
+    workspace: { shellPaths },
+    clients: { agentKnowledgeApi: { memory: memoryRegistry } },
+  } as unknown as CommandContext;
+}
+
+export function resolveCandidate(
+  shellPaths: ShellPathService,
+  memoryRegistry: MemoryRegistry,
+  args: AgentLearningConsolidationToolArgs,
+): LearningCandidate {
+  const input = readString(args.candidateId) || readString(args.query);
+  const resolved = resolveLearningConsolidationCandidate(minimalContext(shellPaths, memoryRegistry), input);
+  if (resolved.status === 'found') return resolved.candidate;
+  if (resolved.status === 'ambiguous') {
+    throw new Error(`Ambiguous learning consolidation candidate ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+  }
+  throw new Error(resolved.usage);
+}
+
+export function domainForCandidate(candidate: LearningCandidate): AgentLearningConsolidationDomain {
+  const domain = String(candidate.domain);
+  if (!isDomain(domain)) throw new Error(`Candidate ${candidate.id} is not an applyable consolidation domain.`);
+  return domain;
+}
+
+export function cloneRecord(record: unknown): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(record)) as Record<string, unknown>;
+}
+
+export function getRecord(
+  shellPaths: ShellPathService,
+  memoryRegistry: MemoryRegistry,
+  domain: AgentLearningConsolidationDomain,
+  id: string,
+): MemoryRecord | AgentPersonaRecord | AgentSkillRecord | AgentRoutineRecord {
+  if (domain === 'memory') {
+    const record = memoryRegistry.get(id);
+    if (!record) throw new Error(`Unknown Agent-local memory ${id}`);
+    return record;
+  }
+  if (domain === 'persona') {
+    const record = AgentPersonaRegistry.fromShellPaths(shellPaths).get(id);
+    if (!record) throw new Error(`Unknown Agent-local persona ${id}`);
+    return record;
+  }
+  if (domain === 'skill') {
+    const record = AgentSkillRegistry.fromShellPaths(shellPaths).get(id);
+    if (!record) throw new Error(`Unknown Agent-local skill ${id}`);
+    return record;
+  }
+  const record = AgentRoutineRegistry.fromShellPaths(shellPaths).get(id);
+  if (!record) throw new Error(`Unknown Agent-local routine ${id}`);
+  return record;
+}
+
+export function updateSurvivor(
+  shellPaths: ShellPathService,
+  memoryRegistry: MemoryRegistry,
+  domain: AgentLearningConsolidationDomain,
+  survivorId: string,
+  fields: LearningConsolidationFields,
+): Record<string, unknown> {
+  if (domain === 'memory') {
+    const record = memoryRegistry.update(survivorId, {
+      ...(fields.detail === undefined ? {} : { detail: fields.detail }),
+      ...(fields.tags === undefined ? {} : { tags: [...fields.tags] }),
+    });
+    if (!record) throw new Error(`Unknown Agent-local memory ${survivorId}`);
+    return cloneRecord(record);
+  }
+  if (domain === 'persona') {
+    const record = AgentPersonaRegistry.fromShellPaths(shellPaths).update(survivorId, {
+      ...(fields.description === undefined ? {} : { description: fields.description }),
+      ...(fields.tags === undefined ? {} : { tags: [...fields.tags] }),
+      ...(fields.triggers === undefined ? {} : { triggers: [...fields.triggers] }),
+      provenance: 'learning-curator-consolidation',
+    });
+    return cloneRecord(record);
+  }
+  if (domain === 'skill') {
+    const record = AgentSkillRegistry.fromShellPaths(shellPaths).update(survivorId, {
+      ...(fields.description === undefined ? {} : { description: fields.description }),
+      ...(fields.tags === undefined ? {} : { tags: [...fields.tags] }),
+      ...(fields.triggers === undefined ? {} : { triggers: [...fields.triggers] }),
+      provenance: 'learning-curator-consolidation',
+    });
+    return cloneRecord(record);
+  }
+  const record = AgentRoutineRegistry.fromShellPaths(shellPaths).update(survivorId, {
+    ...(fields.description === undefined ? {} : { description: fields.description }),
+    ...(fields.tags === undefined ? {} : { tags: [...fields.tags] }),
+    ...(fields.triggers === undefined ? {} : { triggers: [...fields.triggers] }),
+    provenance: 'learning-curator-consolidation',
+  });
+  return cloneRecord(record);
+}
+
+export function markDuplicateStale(
+  shellPaths: ShellPathService,
+  memoryRegistry: MemoryRegistry,
+  domain: AgentLearningConsolidationDomain,
+  duplicateId: string,
+  survivorId: string,
+): Record<string, unknown> {
+  const reason = `Duplicate of ${survivorId}; staged by learning curator consolidation.`;
+  if (domain === 'memory') {
+    const record = memoryRegistry.review(duplicateId, { state: 'stale', staleReason: reason, reviewedBy: 'agent' });
+    if (!record) throw new Error(`Unknown Agent-local memory ${duplicateId}`);
+    return cloneRecord(record);
+  }
+  if (domain === 'persona') return cloneRecord(AgentPersonaRegistry.fromShellPaths(shellPaths).markStale(duplicateId, reason));
+  if (domain === 'skill') return cloneRecord(AgentSkillRegistry.fromShellPaths(shellPaths).markStale(duplicateId, reason));
+  return cloneRecord(AgentRoutineRegistry.fromShellPaths(shellPaths).markStale(duplicateId, reason));
+}
+
+export function deleteDuplicate(
+  shellPaths: ShellPathService,
+  memoryRegistry: MemoryRegistry,
+  domain: AgentLearningConsolidationDomain,
+  duplicateId: string,
+): void {
+  if (domain === 'memory') {
+    if (!memoryRegistry.delete(duplicateId)) throw new Error(`Unknown Agent-local memory ${duplicateId}`);
+    return;
+  }
+  if (domain === 'persona') {
+    AgentPersonaRegistry.fromShellPaths(shellPaths).deletePersona(duplicateId);
+    return;
+  }
+  if (domain === 'skill') {
+    AgentSkillRegistry.fromShellPaths(shellPaths).deleteSkill(duplicateId);
+    return;
+  }
+  AgentRoutineRegistry.fromShellPaths(shellPaths).deleteRoutine(duplicateId);
+}