@pellux/goodvibes-agent 1.1.7 → 1.3.0

package/src/tools/agent-harness-memory-provider-certification.ts

@@ -0,0 +1,219 @@
+import { previewHarnessText } from './agent-harness-text.ts';
+import { readRecord, readString } from './agent-harness-model-routing-utils.ts';
+
+export interface MemoryExternalProviderCertification {
+  readonly schemaStatus: 'certified' | 'legacy';
+  readonly schemaVersion?: string;
+  readonly publicationGuarantee?: string;
+  readonly publisher?: string;
+  readonly provenance?: readonly string[];
+  readonly receiptId?: string;
+  readonly receiptStatus?: string;
+  readonly receiptRoute?: string;
+  readonly receiptIds?: readonly string[];
+  readonly receiptStreamStatus?: string;
+  readonly missingSignals: readonly string[];
+  readonly policy: string;
+}
+
+const MEMORY_CERT_SECRET_PATTERNS: readonly [RegExp, string][] = [
+  [/secret:\/\/[^\s,'"}]+/gi, 'secret://<redacted>'],
+  [/("?\b(?:api[-_]?key|apikey|token|secret|password|passwd|credential|authorization)\b"?\s*:\s*)("[^"]*"|'[^']*'|[^\s,}]+)/gi, '$1"<redacted>"'],
+  [/\b([A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTHORIZATION|BEARER)[A-Z0-9_]*)=("[^"]*"|'[^']*'|[^\s]+)/gi, '$1=<redacted>'],
+  [/(\b(?:token|secret|password|passwd|api[-_]?key|apikey|authorization|credential)\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,}]+)/gi, '$1<redacted>'],
+  [/(Authorization:\s*Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, '$1<redacted>'],
+];
+
+function redactedPreview(value: unknown, limit = 180): string {
+  const raw = readString(value);
+  const redacted = MEMORY_CERT_SECRET_PATTERNS.reduce((text, [pattern, replacement]) => text.replace(pattern, replacement), raw);
+  return previewHarnessText(redacted, limit);
+}
+
+function firstString(record: Readonly<Record<string, unknown>>, keys: readonly string[]): string {
+  for (const key of keys) {
+    const value = readString(record[key]);
+    if (value) return value;
+  }
+  return '';
+}
+
+function readStringArray(value: unknown): readonly string[] {
+  if (Array.isArray(value)) {
+    return [...new Set(value.map((entry) => readString(entry)).filter(Boolean))].slice(0, 12);
+  }
+  const text = readString(value);
+  return text ? text.split(',').map((entry) => entry.trim()).filter(Boolean).slice(0, 12) : [];
+}
+
+function recordsForCertification(record: Readonly<Record<string, unknown>>): readonly Readonly<Record<string, unknown>>[] {
+  return [
+    record,
+    readRecord(record.schema),
+    readRecord(record.contract),
+    readRecord(record.providerContract),
+    readRecord(record.memoryProviderContract),
+    readRecord(record.receipt),
+    readRecord(record.receiptContract),
+    readRecord(record.publication),
+    readRecord(record.certification),
+  ];
+}
+
+function firstAcross(records: readonly Readonly<Record<string, unknown>>[], keys: readonly string[]): string {
+  for (const record of records) {
+    const value = firstString(record, keys);
+    if (value) return value;
+  }
+  return '';
+}
+
+function normalizeSchemaStatus(records: readonly Readonly<Record<string, unknown>>[]): MemoryExternalProviderCertification['schemaStatus'] {
+  const explicit = firstAcross(records, ['schemaStatus', 'receiptSchemaStatus', 'certificationStatus'])
+    .toLowerCase()
+    .replace(/[_\s]+/g, '-');
+  if (['certified', 'valid', 'verified', 'schema-certified'].includes(explicit)) return 'certified';
+  const schemaVersion = firstAcross(records, ['schemaVersion', 'receiptSchemaVersion', 'contractVersion']);
+  const publicationGuarantee = firstAcross(records, ['publicationGuarantee', 'hostPublicationGuarantee', 'providerPublicationGuarantee', 'memoryPublicationGuarantee']);
+  const proof = firstAcross(records, ['methodId', 'sourceTool', 'actionId', 'publisher', 'publisherId', 'daemonId', 'hostId']);
+  return schemaVersion && publicationGuarantee && proof ? 'certified' : 'legacy';
+}
+
+function receiptIds(record: Readonly<Record<string, unknown>>, records: readonly Readonly<Record<string, unknown>>[], extraIds: readonly string[]): readonly string[] {
+  const explicit = [
+    ...extraIds,
+    ...readStringArray(record.receiptIds),
+    ...readStringArray(record.effectReceiptIds),
+    ...readStringArray(record.providerReceiptIds),
+    ...readStringArray(record.syncReceiptIds),
+    firstAcross(records, ['receiptId', 'effectReceiptId', 'readReceiptId', 'writeReceiptId', 'syncReceiptId', 'forgetReceiptId', 'operationReceiptId']),
+  ].filter(Boolean);
+  return [...new Set(explicit.map((entry) => redactedPreview(entry, 96)))].slice(0, 12);
+}
+
+function provenance(record: Readonly<Record<string, unknown>>, records: readonly Readonly<Record<string, unknown>>[], sourcePath: string): readonly string[] {
+  const values = [
+    ...readStringArray(record.provenance),
+    sourcePath ? `source ${sourcePath}` : '',
+    firstAcross(records, ['methodId']) ? `method ${firstAcross(records, ['methodId'])}` : '',
+    firstAcross(records, ['actionId']) ? `action ${firstAcross(records, ['actionId'])}` : '',
+    firstAcross(records, ['sourceTool']) ? `sourceTool ${firstAcross(records, ['sourceTool'])}` : '',
+  ];
+  return [...new Set(values.map((entry) => redactedPreview(entry, 180)).filter(Boolean))].slice(0, 8);
+}
+
+function certifiedBase(input: {
+  readonly record: Readonly<Record<string, unknown>>;
+  readonly sourcePath: string;
+  readonly receiptIds?: readonly string[];
+}): Omit<MemoryExternalProviderCertification, 'missingSignals' | 'policy'> & { readonly rawPublicationGuarantee: string; readonly rawPublisher: string; readonly rawReceiptRoute: string; readonly rawReceiptStreamStatus: string; readonly rawReceiptStatus: string; readonly rawSchemaVersion: string; readonly receiptIdsValue: readonly string[]; readonly schemaStatusValue: MemoryExternalProviderCertification['schemaStatus'] } {
+  const records = recordsForCertification(input.record);
+  const schemaStatus = normalizeSchemaStatus(records);
+  const schemaVersion = firstAcross(records, ['schemaVersion', 'receiptSchemaVersion', 'contractVersion']);
+  const publicationGuarantee = firstAcross(records, ['publicationGuarantee', 'hostPublicationGuarantee', 'providerPublicationGuarantee', 'memoryPublicationGuarantee']);
+  const publisher = firstAcross(records, ['publisher', 'publisherId', 'daemonId', 'hostId']);
+  const ids = receiptIds(input.record, records, input.receiptIds ?? []);
+  const receiptStatus = firstAcross(records, ['receiptStatus', 'receiptOutcome', 'operationStatus', 'status']);
+  const receiptRoute = firstAcross(records, ['receiptRoute', 'inspectReceiptRoute', 'artifactRoute']);
+  const receiptStreamStatus = firstAcross(records, ['receiptStreamStatus', 'receiptPublicationStatus', 'receiptsStatus', 'streamStatus']);
+  const proof = provenance(input.record, records, input.sourcePath);
+  return {
+    schemaStatus,
+    ...(schemaVersion ? { schemaVersion: redactedPreview(schemaVersion, 80) } : {}),
+    ...(publicationGuarantee ? { publicationGuarantee: redactedPreview(publicationGuarantee, 220) } : {}),
+    ...(publisher ? { publisher: redactedPreview(publisher, 80) } : {}),
+    ...(proof.length > 0 ? { provenance: proof } : {}),
+    ...(ids[0] ? { receiptId: ids[0] } : {}),
+    ...(receiptStatus ? { receiptStatus: redactedPreview(receiptStatus, 80) } : {}),
+    ...(receiptRoute ? { receiptRoute: redactedPreview(receiptRoute, 180) } : {}),
+    ...(ids.length > 0 ? { receiptIds: ids } : {}),
+    ...(receiptStreamStatus ? { receiptStreamStatus: redactedPreview(receiptStreamStatus, 80) } : {}),
+    rawPublicationGuarantee: publicationGuarantee,
+    rawPublisher: publisher,
+    rawReceiptRoute: receiptRoute,
+    rawReceiptStreamStatus: receiptStreamStatus,
+    rawReceiptStatus: receiptStatus,
+    rawSchemaVersion: schemaVersion,
+    receiptIdsValue: ids,
+    schemaStatusValue: schemaStatus,
+  };
+}
+
+export function memoryExternalProviderLiveCertification(input: {
+  readonly record: Readonly<Record<string, unknown>>;
+  readonly sourcePath: string;
+  readonly providerId: string;
+  readonly readContractPublished: boolean;
+  readonly writeContractPublished: boolean;
+  readonly syncContractPublished: boolean;
+  readonly forgetContractPublished: boolean;
+  readonly receiptIds: readonly string[];
+  readonly receiptRoute: string | null;
+}): MemoryExternalProviderCertification {
+  const base = certifiedBase({ record: input.record, sourcePath: input.sourcePath, receiptIds: input.receiptIds });
+  const {
+    rawPublicationGuarantee,
+    rawPublisher,
+    rawReceiptRoute,
+    rawReceiptStreamStatus,
+    rawReceiptStatus,
+    rawSchemaVersion,
+    receiptIdsValue,
+    schemaStatusValue,
+    ...certification
+  } = base;
+  const receiptPublished = base.receiptIdsValue.length > 0 || Boolean(input.receiptRoute) || Boolean(base.rawReceiptRoute) || Boolean(base.rawReceiptStreamStatus);
+  const missingSignals = [
+    ...(schemaStatusValue === 'certified' ? [] : ['Certified external memory provider schema is not published.']),
+    ...(input.providerId ? [] : ['Durable external memory provider id is not published.']),
+    ...(rawPublicationGuarantee ? [] : ['Provider-side external memory publication guarantee is not published.']),
+    ...(rawPublisher ? [] : ['Provider-side external memory publisher is not published.']),
+    ...(certification.provenance?.length ? [] : ['Provider-side external memory provenance is not published.']),
+    ...(input.readContractPublished ? [] : ['Bounded read/search contract is not published.']),
+    ...(input.writeContractPublished ? [] : ['Confirmed write/upsert contract is not published.']),
+    ...(input.syncContractPublished ? [] : ['Confirmed sync/import/export contract is not published.']),
+    ...(input.forgetContractPublished ? [] : ['Forget/delete contract or explicit not-supported contract is not published.']),
+    ...(receiptPublished ? [] : ['External memory provider receipt stream or receipt ids are not published.']),
+  ];
+  return {
+    ...certification,
+    ...(input.receiptRoute && !certification.receiptRoute ? { receiptRoute: redactedPreview(input.receiptRoute, 180) } : {}),
+    missingSignals,
+    policy: 'External memory provider records certify release readiness only when the host or SDK publishes schema, durable provider id, publication guarantee, publisher/provenance, bounded read, confirmed write/sync, forget or explicit not-supported, and receipt stream evidence without raw secrets or memory bodies.',
+  };
+}
+
+export function memoryExternalProviderReceiptCertification(input: {
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly sourcePath: string;
+  readonly providerId: string;
+  readonly artifactId: string;
+}): MemoryExternalProviderCertification {
+  const base = certifiedBase({ record: input.metadata, sourcePath: input.sourcePath });
+  const {
+    rawPublicationGuarantee,
+    rawPublisher,
+    rawReceiptRoute,
+    rawReceiptStreamStatus,
+    rawReceiptStatus,
+    rawSchemaVersion,
+    receiptIdsValue,
+    schemaStatusValue,
+    ...certification
+  } = base;
+  const missingSignals = [
+    ...(schemaStatusValue === 'certified' ? [] : ['Certified external memory receipt schema is not published.']),
+    ...(input.providerId ? [] : ['Durable external memory provider id is not published.']),
+    ...(input.artifactId || receiptIdsValue.length > 0 ? [] : ['Durable external memory receipt id is not published.']),
+    ...(rawPublicationGuarantee ? [] : ['Provider-side external memory receipt publication guarantee is not published.']),
+    ...(rawPublisher ? [] : ['Provider-side external memory receipt publisher is not published.']),
+    ...(certification.provenance?.length ? [] : ['Provider-side external memory receipt provenance is not published.']),
+    ...(receiptIdsValue.length > 0 ? [] : ['Confirmed external memory operation receipt id is not published.']),
+  ];
+  return {
+    ...certification,
+    ...(certification.receiptId ? {} : { receiptId: redactedPreview(input.artifactId, 96), receiptIds: [redactedPreview(input.artifactId, 96)] }),
+    missingSignals,
+    policy: 'External memory receipt artifacts certify release evidence only when they include schema, durable provider and receipt ids, publication guarantee, publisher/provenance, status, redaction posture, and inspectable follow-up route metadata.',
+  };
+}

package/src/tools/agent-harness-memory-refinement.ts

@@ -0,0 +1,340 @@
+import type {
+  KnowledgeRefinementTaskRecord,
+  KnowledgeSemanticSelfImproveResult,
+} from '@pellux/goodvibes-sdk/platform/knowledge';
+import type { CommandContext } from '../input/command-registry.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+
+interface AgentHarnessMemoryRefinementArgs {
+  readonly query?: unknown;
+  readonly target?: unknown;
+  readonly knowledgeSpaceId?: unknown;
+  readonly sourceIds?: unknown;
+  readonly gapIds?: unknown;
+  readonly limit?: unknown;
+  readonly maxRunMs?: unknown;
+  readonly timeoutMs?: unknown;
+  readonly force?: unknown;
+  readonly includeParameters?: unknown;
+}
+
+interface KnowledgeRefinementService {
+  listRefinementTasks?: (
+    limit?: number,
+    input?: {
+      readonly spaceId?: string;
+      readonly state?: string;
+      readonly subjectKind?: string;
+      readonly subjectId?: string;
+      readonly gapId?: string;
+    },
+  ) => readonly KnowledgeRefinementTaskRecord[];
+  getRefinementTask?: (id: string) => KnowledgeRefinementTaskRecord | null;
+  runRefinement?: (input?: {
+    readonly knowledgeSpaceId?: string;
+    readonly sourceIds?: readonly string[];
+    readonly gapIds?: readonly string[];
+    readonly limit?: number;
+    readonly maxRunMs?: number;
+    readonly force?: boolean;
+  }) => Promise<KnowledgeSemanticSelfImproveResult>;
+  listJobs?: () => readonly {
+    readonly id: string;
+    readonly kind: string;
+    readonly title: string;
+    readonly description: string;
+    readonly defaultMode: string;
+  }[];
+  listJobRuns?: (limit?: number, jobId?: string) => readonly {
+    readonly id: string;
+    readonly jobId: string;
+    readonly status: string;
+    readonly mode: string;
+    readonly requestedAt: number;
+    readonly completedAt?: number;
+    readonly error?: string;
+  }[];
+}
+
+const ACTIVE_STATES = new Set(['detected', 'queued', 'searching', 'evaluating', 'extracting', 'applying', 'verified']);
+const ATTENTION_STATES = new Set(['blocked', 'needs_review', 'failed']);
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readStringArray(value: unknown): readonly string[] {
+  if (Array.isArray(value)) return value.filter((entry): entry is string => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
+  const text = readString(value);
+  if (!text) return [];
+  return text.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function readLimit(value: unknown, fallback: number, max = 100): 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(max, Math.trunc(parsed)));
+}
+
+function readRunBudgetMs(value: unknown): number | undefined {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return undefined;
+  return Math.max(5_000, Math.min(60_000, Math.trunc(parsed)));
+}
+
+function knowledgeService(context: CommandContext): KnowledgeRefinementService | null {
+  const service = context.extensions?.agentKnowledgeService;
+  return service && typeof service === 'object' ? service as KnowledgeRefinementService : null;
+}
+
+function iso(value: number | undefined): string | null {
+  return typeof value === 'number' && Number.isFinite(value) ? new Date(value).toISOString() : null;
+}
+
+function routeValue(value: string): string {
+  return JSON.stringify(value);
+}
+
+function taskSearchText(task: KnowledgeRefinementTaskRecord): string {
+  return [
+    task.id,
+    task.spaceId,
+    task.state,
+    task.priority,
+    task.trigger,
+    task.subjectTitle ?? '',
+    task.subjectId ?? '',
+    task.subjectType ?? '',
+    task.gapId ?? '',
+    task.issueId ?? '',
+    task.blockedReason ?? '',
+    readString(task.metadata.gapTitle),
+    readString(task.metadata.gapKind),
+  ].join('\n').toLowerCase();
+}
+
+function compactTask(task: KnowledgeRefinementTaskRecord, includeParameters: boolean): Record<string, unknown> {
+  const latestTrace = task.trace.at(-1);
+  const accepted = task.acceptedSourceIds ?? [];
+  const ingested = task.ingestedSourceIds ?? [];
+  return {
+    taskId: task.id,
+    spaceId: task.spaceId,
+    state: task.state,
+    priority: task.priority,
+    trigger: task.trigger,
+    ...(task.subjectTitle ? { subject: previewHarnessText(task.subjectTitle, includeParameters ? 140 : 80) } : {}),
+    ...(task.subjectId ? { subjectId: task.subjectId } : {}),
+    ...(task.gapId ? { gapId: task.gapId } : {}),
+    attemptCount: task.attemptCount,
+    ...(task.blockedReason ? { blockedReason: previewHarnessText(task.blockedReason, includeParameters ? 180 : 96) } : {}),
+    acceptedSourceCount: accepted.length,
+    ingestedSourceCount: ingested.length,
+    promotedFactCount: task.promotedFactCount ?? 0,
+    updatedAt: iso(task.updatedAt),
+    inspectRoute: `memory action:"refinement" query:${routeValue(task.id)} includeParameters:true`,
+    rerunRoute: task.gapId
+      ? `memory action:"run_refinement" gapIds:[${routeValue(task.gapId)}] confirm:true explicitUserRequest:"..."`
+      : `memory action:"run_refinement" knowledgeSpaceId:${routeValue(task.spaceId)} limit:1 confirm:true explicitUserRequest:"..."`,
+    ...(latestTrace ? {
+      latestTrace: {
+        at: iso(latestTrace.at),
+        state: latestTrace.state,
+        message: previewHarnessText(latestTrace.message, includeParameters ? 180 : 96),
+      },
+    } : {}),
+    ...(includeParameters ? {
+      budget: task.budget,
+      acceptedSourceIds: accepted,
+      ingestedSourceIds: ingested,
+      rejectedSourceUrls: task.rejectedSourceUrls ?? [],
+      sourceAssessments: (task.sourceAssessments ?? []).slice(0, 5).map((entry) => ({
+        url: previewHarnessText(entry.url, 120),
+        accepted: entry.accepted,
+        confidence: entry.confidence,
+        reasons: entry.reasons.slice(0, 3),
+      })),
+    } : {}),
+  };
+}
+
+function taskCounts(tasks: readonly KnowledgeRefinementTaskRecord[]): Record<string, number> {
+  const counts: Record<string, number> = {
+    total: tasks.length,
+    active: tasks.filter((task) => ACTIVE_STATES.has(task.state)).length,
+    attention: tasks.filter((task) => ATTENTION_STATES.has(task.state)).length,
+    closed: tasks.filter((task) => task.state === 'closed').length,
+    suppressed: tasks.filter((task) => task.state === 'suppressed').length,
+    cancelled: tasks.filter((task) => task.state === 'cancelled').length,
+  };
+  for (const task of tasks) counts[task.state] = (counts[task.state] ?? 0) + 1;
+  return counts;
+}
+
+function semanticJob(service: KnowledgeRefinementService): ReturnType<NonNullable<KnowledgeRefinementService['listJobs']>>[number] | null {
+  return service.listJobs?.().find((job) => job.kind === 'semantic-self-improvement' || job.id === 'knowledge-semantic-self-improvement') ?? null;
+}
+
+export function memoryRefinementCatalogStatus(context: CommandContext): Record<string, unknown> {
+  const service = knowledgeService(context);
+  const tasks = service?.listRefinementTasks?.(1_000) ?? [];
+  const counts = taskCounts(tasks);
+  return {
+    modes: ['memory_refinement', 'run_memory_refinement'],
+    status: !service?.listRefinementTasks && !service?.runRefinement
+      ? 'unavailable'
+      : counts.attention > 0
+        ? 'attention'
+        : counts.active > 0
+          ? 'active'
+          : counts.total > 0
+            ? 'ready'
+            : 'empty',
+    serviceAvailable: Boolean(service),
+    taskCounts: counts,
+    semanticJobPublished: Boolean(service ? semanticJob(service) : null),
+    readOnlyRoute: 'memory action:"refinement"',
+    confirmedRunRoute: 'memory action:"run_refinement" confirm:true explicitUserRequest:"..."',
+  };
+}
+
+export function memoryRefinementSummary(context: CommandContext, args: AgentHarnessMemoryRefinementArgs): Record<string, unknown> {
+  const includeParameters = args.includeParameters === true;
+  const service = knowledgeService(context);
+  if (!service?.listRefinementTasks && !service?.runRefinement) {
+    return {
+      status: 'unavailable',
+      summary: 'Agent Knowledge semantic refinement is not available in this runtime.',
+      requiredService: 'extensions.agentKnowledgeService.listRefinementTasks and runRefinement',
+      routes: {
+        knowledgeStatus: 'agent_knowledge action:"status"',
+        memoryCurator: 'memory action:"curator" includeParameters:true',
+      },
+      policy: 'No refinement mutation is attempted from posture inspection.',
+    };
+  }
+
+  const query = (readString(args.query) || readString(args.target)).toLowerCase();
+  const limit = readLimit(args.limit, 25, 100);
+  const spaceId = readString(args.knowledgeSpaceId);
+  const allTasks = service.listRefinementTasks?.(1_000, spaceId ? { spaceId } : undefined) ?? [];
+  const filtered = allTasks.filter((task) => !query || taskSearchText(task).includes(query));
+  const counts = taskCounts(allTasks);
+  const job = semanticJob(service);
+  const latestRun = job ? service.listJobRuns?.(1, job.id)?.[0] : null;
+
+  return {
+    status: counts.attention > 0 ? 'attention' : counts.active > 0 ? 'active' : counts.total > 0 ? 'ready' : 'empty',
+    userOutcome: 'Semantic self-improvement is a supervised Agent Knowledge refinement lane: gaps and repair tasks stay inspectable before any source search, ingest, or prompt expansion.',
+    taskCounts: counts,
+    tasks: filtered.slice(0, limit).map((task) => compactTask(task, includeParameters)),
+    returned: Math.min(filtered.length, limit),
+    total: filtered.length,
+    semanticSelfImprovementJob: job ? {
+      id: job.id,
+      title: job.title,
+      defaultMode: job.defaultMode,
+      description: previewHarnessText(job.description, includeParameters ? 180 : 96),
+      runRoute: 'memory action:"run_refinement" confirm:true explicitUserRequest:"..."',
+      ...(latestRun ? {
+        latestRun: {
+          id: latestRun.id,
+          status: latestRun.status,
+          mode: latestRun.mode,
+          requestedAt: iso(latestRun.requestedAt),
+          completedAt: iso(latestRun.completedAt),
+          ...(latestRun.error ? { error: previewHarnessText(latestRun.error, 120) } : {}),
+        },
+      } : {}),
+    } : {
+      status: 'not-published',
+      description: 'KnowledgeService.runRefinement is available, but the scheduled semantic-self-improvement job is not listed.',
+    },
+    routes: {
+      inspect: 'memory action:"refinement" includeParameters:true',
+      inspectTask: 'memory action:"refinement" query:"<taskId>" includeParameters:true',
+      runManual: 'memory action:"run_refinement" limit:12 confirm:true explicitUserRequest:"..."',
+      runScopedSpace: 'memory action:"run_refinement" knowledgeSpaceId:"<spaceId>" limit:12 confirm:true explicitUserRequest:"..."',
+      runScopedGaps: 'memory action:"run_refinement" gapIds:["<gapId>"] confirm:true explicitUserRequest:"..."',
+      knowledgeStatus: 'agent_knowledge action:"status"',
+      memoryCurator: 'memory action:"curator" includeParameters:true',
+    },
+    nextActions: [
+      counts.attention > 0 ? 'Inspect blocked or failed refinement tasks before running a broader semantic self-improvement pass.' : '',
+      counts.active > 0 ? 'Let active refinement tasks finish or inspect their trace before starting another broad run.' : '',
+      counts.total === 0 ? 'Run a small confirmed manual refinement after useful Agent Knowledge sources exist.' : '',
+      'Keep reviewed Agent-local memory as the active prompt path until refined Knowledge evidence is inspected and promoted through existing confirmed routes.',
+    ].filter(Boolean),
+    policy: 'Read-only refinement inspection never searches, ingests, writes prompt memory, or mutates Knowledge. Manual refinement runs require confirm:true and explicitUserRequest.',
+  };
+}
+
+export async function runMemoryRefinement(context: CommandContext, args: AgentHarnessMemoryRefinementArgs): Promise<Record<string, unknown>> {
+  const service = knowledgeService(context);
+  if (!service?.runRefinement) {
+    return {
+      status: 'unavailable',
+      error: 'Agent Knowledge semantic refinement runner is not available in this runtime.',
+      inspectRoute: 'memory action:"refinement" includeParameters:true',
+    };
+  }
+  const sourceIds = readStringArray(args.sourceIds);
+  const gapIds = readStringArray(args.gapIds);
+  const knowledgeSpaceId = readString(args.knowledgeSpaceId);
+  const limit = readLimit(args.limit, 12, 24);
+  const maxRunMs = readRunBudgetMs(args.maxRunMs) ?? readRunBudgetMs(args.timeoutMs);
+  const run = await service.runRefinement({
+    ...(knowledgeSpaceId ? { knowledgeSpaceId } : {}),
+    ...(sourceIds.length > 0 ? { sourceIds } : {}),
+    ...(gapIds.length > 0 ? { gapIds } : {}),
+    limit,
+    ...(maxRunMs ? { maxRunMs } : {}),
+    ...(args.force === true ? { force: true } : {}),
+  });
+  return {
+    status: run.errors.length > 0 || run.blockedGaps > 0 ? 'completed-with-attention' : 'completed',
+    result: {
+      scannedGaps: run.scannedGaps,
+      candidateGaps: run.candidateGaps ?? 0,
+      processedGaps: run.processedGaps ?? 0,
+      createdGaps: run.createdGaps,
+      repairableGaps: run.repairableGaps,
+      suppressedGaps: run.suppressedGaps,
+      skippedGaps: run.skippedGaps,
+      searched: run.searched,
+      ingestedSources: run.ingestedSources,
+      linkedRepairs: run.linkedRepairs,
+      blockedGaps: run.blockedGaps,
+      closedGaps: run.closedGaps,
+      queuedTasks: run.queuedTasks,
+      requestedLimit: run.requestedLimit ?? limit,
+      effectiveLimit: run.effectiveLimit ?? 0,
+      truncated: Boolean(run.truncated),
+      budgetExhausted: Boolean(run.budgetExhausted),
+      taskIds: run.taskIds,
+      acceptedSourceIds: run.acceptedSourceIds ?? [],
+      ingestedSourceIds: run.ingestedSourceIds,
+      promotedFactCount: run.promotedFactCount ?? 0,
+      ...(run.nextRepairAttemptAt ? { nextRepairAttemptAt: iso(run.nextRepairAttemptAt) } : {}),
+      errors: run.errors.map((entry) => ({
+        gapId: entry.gapId,
+        error: previewHarnessText(entry.error, 160),
+      })),
+    },
+    scope: {
+      ...(knowledgeSpaceId ? { knowledgeSpaceId } : {}),
+      ...(sourceIds.length > 0 ? { sourceIds } : {}),
+      ...(gapIds.length > 0 ? { gapIds } : {}),
+      limit,
+      ...(maxRunMs ? { maxRunMs } : {}),
+      force: args.force === true,
+    },
+    nextRoutes: {
+      refinement: 'memory action:"refinement" includeParameters:true',
+      curator: 'memory action:"curator" includeParameters:true',
+      tasks: run.taskIds.map((taskId) => `memory action:"refinement" query:${routeValue(taskId)} includeParameters:true`).slice(0, 8),
+      knowledgeStatus: 'agent_knowledge action:"status"',
+    },
+    policy: 'Confirmed semantic refinement updates only Agent Knowledge semantic gaps/refinement tasks and source-backed repair evidence through KnowledgeService.runRefinement. It does not write Agent-local prompt memory, external memory providers, channel messages, or reports.',
+  };
+}