@pellux/goodvibes-agent 1.1.7 → 1.3.0

package/src/tools/agent-harness-device-live-read-models.ts

@@ -0,0 +1,366 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+
+export interface DeviceLiveRecordCertification {
+  readonly schemaStatus: 'certified' | 'legacy';
+  readonly schemaVersion?: string;
+  readonly publicationGuarantee?: string;
+  readonly publisher?: string;
+  readonly provenance?: readonly string[];
+  readonly receiptId?: string;
+  readonly cursor?: string;
+  readonly missingSignals: readonly string[];
+  readonly policy: string;
+}
+
+export interface DeviceLiveCapabilityRecord {
+  readonly id: string;
+  readonly capabilityId: string;
+  readonly label: string | null;
+  readonly domain: string;
+  readonly status: string;
+  readonly summary: string | null;
+  readonly capabilities: readonly string[];
+  readonly permissionScope: string | null;
+  readonly route: string | null;
+  readonly modelRoute: string;
+  readonly controlRoutes: Readonly<Record<string, string>>;
+  readonly sourcePath: string;
+  readonly source: 'daemon-read-model' | 'sdk-read-model';
+  readonly certification: DeviceLiveRecordCertification;
+}
+
+export interface DeviceLiveReadModelSnapshot {
+  readonly capabilities: readonly DeviceLiveCapabilityRecord[];
+  readonly sourceCounts: Readonly<Record<string, number>>;
+}
+
+interface SourceCandidate {
+  readonly path: string;
+  readonly source: unknown;
+  readonly kind: 'daemon-read-model' | 'sdk-read-model';
+}
+
+interface CollectedRecord {
+  readonly path: string;
+  readonly kind: 'daemon-read-model' | 'sdk-read-model';
+  readonly record: Record<string, unknown>;
+}
+
+const WRAPPER_KEYS = [
+  'records',
+  'items',
+  'capabilities',
+  'deviceCapabilities',
+  'mobileCapabilities',
+  'voiceWorkflows',
+  'workflows',
+  'sensors',
+  'sensorRoutes',
+] as const;
+
+const SNAPSHOT_METHODS = ['getSnapshot', 'snapshot', 'toJSON'] as const;
+const LIST_METHODS = ['listCapabilities', 'listDeviceCapabilities', 'listSensors', 'listVoiceWorkflows', 'list'] as const;
+
+function readObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readMetadata(record: Record<string, unknown>): Record<string, unknown> {
+  return readObject(record.metadata);
+}
+
+function nestedString(record: Record<string, unknown>, key: string): string {
+  return readString(record[key])
+    || readString(readMetadata(record)[key])
+    || readString(readObject(record.capability)[key])
+    || readString(readObject(record.device)[key])
+    || readString(readObject(record.permission)[key])
+    || readString(readObject(record.evidence)[key])
+    || readString(readObject(record.route)[key]);
+}
+
+function certificationRecords(record: Record<string, unknown>): readonly Record<string, unknown>[] {
+  return [
+    record,
+    readMetadata(record),
+    readObject(record.schema),
+    readObject(record.contract),
+    readObject(record.publication),
+    readObject(record.receipt),
+    readObject(record.certification),
+  ];
+}
+
+function firstAcross(records: readonly Record<string, unknown>[], keys: readonly string[]): string {
+  for (const record of records) {
+    for (const key of keys) {
+      const value = readString(record[key]);
+      if (value) return value;
+    }
+  }
+  return '';
+}
+
+function stringArray(value: unknown): readonly string[] {
+  if (Array.isArray(value)) return [...new Set(value.map((entry) => readString(entry)).filter(Boolean))].slice(0, 16);
+  const text = readString(value);
+  return text ? text.split(',').map((entry) => entry.trim()).filter(Boolean).slice(0, 16) : [];
+}
+
+function redactText(value: string): string {
+  return value
+    .replace(/\b(bearer)\s+[a-z0-9._~+/=-]+/gi, '$1 <redacted>')
+    .replace(/\b(token|secret|password|api[_-]?key|authorization)\s*[:=]\s*[^,\s;/]+/gi, '$1=<redacted>');
+}
+
+function safePreview(value: string, limit: number): string {
+  return previewHarnessText(redactText(value), limit);
+}
+
+function safeNullablePreview(value: string, limit: number): string | null {
+  return value ? safePreview(value, limit) : null;
+}
+
+function schemaStatus(records: readonly Record<string, unknown>[]): DeviceLiveRecordCertification['schemaStatus'] {
+  const explicit = firstAcross(records, ['schemaStatus', 'receiptSchemaStatus', 'certificationStatus']).toLowerCase().replace(/[_\s]+/g, '-');
+  if (['certified', 'valid', 'verified', 'schema-certified'].includes(explicit)) return 'certified';
+  return firstAcross(records, ['schemaVersion', 'receiptSchemaVersion', 'contractVersion'])
+    && firstAcross(records, ['publicationGuarantee', 'hostPublicationGuarantee', 'devicePublicationGuarantee'])
+    && firstAcross(records, ['publisher', 'publisherId', 'daemonId', 'hostId'])
+    ? 'certified'
+    : 'legacy';
+}
+
+function routeMap(record: Record<string, unknown>): Readonly<Record<string, string>> {
+  const routes = { ...readObject(record.routes), ...readObject(record.controls) };
+  const output: Record<string, string> = {};
+  for (const key of ['inspect', 'open', 'run', 'capture', 'repairPermission', 'grantPermission', 'revokePermission', 'test']) {
+    const value = readString(routes[key]) || nestedString(record, `${key}Route`);
+    if (value) output[key] = safePreview(value, 180);
+  }
+  return output;
+}
+
+function certification(input: {
+  readonly record: Record<string, unknown>;
+  readonly sourcePath: string;
+  readonly id: string;
+  readonly capabilityId: string;
+  readonly status: string;
+  readonly permissionScope: string;
+  readonly modelRoute: string;
+  readonly hasRoutes: boolean;
+}): DeviceLiveRecordCertification {
+  const records = certificationRecords(input.record);
+  const currentSchemaStatus = schemaStatus(records);
+  const schemaVersion = firstAcross(records, ['schemaVersion', 'receiptSchemaVersion', 'contractVersion']);
+  const publicationGuarantee = firstAcross(records, ['publicationGuarantee', 'hostPublicationGuarantee', 'devicePublicationGuarantee']);
+  const publisher = firstAcross(records, ['publisher', 'publisherId', 'daemonId', 'hostId']);
+  const receiptId = firstAcross(records, ['receiptId', 'capabilityReceiptId', 'permissionReceiptId', 'routeReceiptId']);
+  const cursor = firstAcross(records, ['cursor', 'freshnessCursor', 'sequence', 'checkpoint']);
+  const provenance = [...new Set([
+    ...stringArray(input.record.provenance),
+    input.sourcePath ? `source ${input.sourcePath}` : '',
+    firstAcross(records, ['methodId']) ? `method ${firstAcross(records, ['methodId'])}` : '',
+    firstAcross(records, ['sourceTool']) ? `sourceTool ${firstAcross(records, ['sourceTool'])}` : '',
+  ].map((entry) => safePreview(entry, 180)).filter(Boolean))].slice(0, 8);
+  const missingSignals = [
+    ...(currentSchemaStatus === 'certified' ? [] : ['Certified device capability schema is not published.']),
+    ...(input.id ? [] : ['Durable device capability record id is not published.']),
+    ...(input.capabilityId ? [] : ['Device capability id is not published.']),
+    ...(input.status ? [] : ['Device capability status is not published.']),
+    ...(publicationGuarantee ? [] : ['Device capability publication guarantee is not published.']),
+    ...(publisher ? [] : ['Device capability publisher is not published.']),
+    ...(provenance.length > 0 ? [] : ['Device capability provenance is not published.']),
+    ...(cursor ? [] : ['Device capability freshness cursor is not published.']),
+    ...(input.permissionScope ? [] : ['Permission scope is not published.']),
+    ...(input.modelRoute && input.hasRoutes ? [] : ['Exact inspect/control route is not published.']),
+  ];
+  return {
+    schemaStatus: currentSchemaStatus,
+    ...(schemaVersion ? { schemaVersion: safePreview(schemaVersion, 80) } : {}),
+    ...(publicationGuarantee ? { publicationGuarantee: safePreview(publicationGuarantee, 220) } : {}),
+    ...(publisher ? { publisher: safePreview(publisher, 80) } : {}),
+    ...(provenance.length > 0 ? { provenance } : {}),
+    ...(receiptId ? { receiptId: safePreview(receiptId, 96) } : {}),
+    ...(cursor ? { cursor: safePreview(cursor, 96) } : {}),
+    missingSignals,
+    policy: 'Device capability read models certify release readiness only when the SDK or daemon publishes schema, durable capability ids, permission scope, publication guarantee, publisher/provenance, freshness cursor, exact inspect/control routes, and redacted receipt evidence.',
+  };
+}
+
+function callMethod(source: Record<string, unknown>, method: string): unknown {
+  const fn = source[method];
+  if (typeof fn !== 'function') return undefined;
+  try {
+    return (fn as () => unknown).call(source);
+  } catch {
+    return undefined;
+  }
+}
+
+function collectFromSource(
+  source: unknown,
+  path: string,
+  kind: 'daemon-read-model' | 'sdk-read-model',
+  visited = new WeakSet<object>(),
+): readonly CollectedRecord[] {
+  if (!source) return [];
+  if (Array.isArray(source)) return source.flatMap((entry, index) => collectFromSource(entry, `${path}[${index}]`, kind, visited));
+  if (source instanceof Map) return Array.from(source.entries()).flatMap(([key, value]) => collectFromSource(value, `${path}.${String(key)}`, kind, visited));
+  if (typeof source !== 'object') return [];
+  if (visited.has(source)) return [];
+  visited.add(source);
+  const record = source as Record<string, unknown>;
+  const fromSnapshots = SNAPSHOT_METHODS.flatMap((method) => {
+    const snapshot = callMethod(record, method);
+    return snapshot === undefined ? [] : collectFromSource(snapshot, `${path}.${method}()`, kind, visited);
+  });
+  const fromMethods = LIST_METHODS.flatMap((method) => {
+    const snapshot = callMethod(record, method);
+    return snapshot === undefined ? [] : collectFromSource(snapshot, `${path}.${method}()`, kind, visited);
+  });
+  const fromWrappers = WRAPPER_KEYS.flatMap((key) => {
+    if (!(key in record)) return [];
+    return collectFromSource(record[key], `${path}.${key}`, kind, visited);
+  });
+  if (fromSnapshots.length > 0 || fromMethods.length > 0 || fromWrappers.length > 0) {
+    return [...fromSnapshots, ...fromMethods, ...fromWrappers];
+  }
+  return [{ path, kind, record }];
+}
+
+function modelRoute(record: Record<string, unknown>, capabilityId: string): string {
+  const routes = readObject(record.routes);
+  return nestedString(record, 'modelRoute')
+    || nestedString(record, 'inspectRoute')
+    || nestedString(record, 'route')
+    || readString(routes.inspect)
+    || readString(routes.open)
+    || readString(routes.run)
+    || `device action:"capability" capabilityId:"${capabilityId}" includeParameters:true`;
+}
+
+function capabilityId(record: Record<string, unknown>, index: number): string {
+  return nestedString(record, 'capabilityId')
+    || nestedString(record, 'id')
+    || nestedString(record, 'kind')
+    || `device-capability-${index}`;
+}
+
+function normalizeCapability(entry: CollectedRecord, index: number): DeviceLiveCapabilityRecord | null {
+  const capId = capabilityId(entry.record, index);
+  if (!capId) return null;
+  const id = nestedString(entry.record, 'id') || nestedString(entry.record, 'receiptId') || `device-live:${capId}:${index}`;
+  const routes = routeMap(entry.record);
+  const route = nestedString(entry.record, 'route') || nestedString(entry.record, 'openRoute') || routes.open || routes.run || routes.inspect || null;
+  const routeForModel = modelRoute(entry.record, capId);
+  const permissionScope = nestedString(entry.record, 'permissionScope') || nestedString(entry.record, 'scope') || nestedString(entry.record, 'permission');
+  const status = nestedString(entry.record, 'status') || nestedString(entry.record, 'state') || 'unknown';
+  return {
+    id,
+    capabilityId: capId,
+    label: safeNullablePreview(nestedString(entry.record, 'label') || nestedString(entry.record, 'title'), 120),
+    domain: nestedString(entry.record, 'domain') || nestedString(entry.record, 'surface') || 'device',
+    status,
+    summary: safeNullablePreview(nestedString(entry.record, 'summary') || nestedString(entry.record, 'detail'), 220),
+    capabilities: [...new Set([
+      ...stringArray(entry.record.capabilities),
+      ...stringArray(entry.record.features),
+      ...stringArray(readObject(entry.record.capability).capabilities),
+      capId,
+    ].map((value) => safePreview(value, 80)).filter(Boolean))].slice(0, 16),
+    permissionScope: safeNullablePreview(permissionScope, 120),
+    route: route ? safePreview(route, 180) : null,
+    modelRoute: routeForModel,
+    controlRoutes: routes,
+    sourcePath: entry.path,
+    source: entry.kind,
+    certification: certification({
+      record: entry.record,
+      sourcePath: entry.path,
+      id,
+      capabilityId: capId,
+      status,
+      permissionScope,
+      modelRoute: routeForModel,
+      hasRoutes: Boolean(route || Object.keys(routes).length > 0),
+    }),
+  };
+}
+
+function sourceCounts(entries: readonly CollectedRecord[]): Readonly<Record<string, number>> {
+  const counts: Record<string, number> = {};
+  for (const entry of entries) counts[entry.path] = (counts[entry.path] ?? 0) + 1;
+  return counts;
+}
+
+function sources(context: CommandContext): readonly SourceCandidate[] {
+  const platform = readObject(context.platform);
+  const readModels = readObject(platform.readModels);
+  const device = readObject(readModels.device);
+  const companion = readObject(readModels.companion);
+  const voice = readObject(readModels.voice);
+  const opsDevice = readObject(readObject(context.ops).device);
+  const clients = readObject(context.clients);
+  const operator = readObject(clients.operator);
+  const operatorSdk = readObject(clients.operatorSdk);
+  return [
+    { path: 'context.platform.readModels.device.capabilities', source: device.capabilities, kind: 'daemon-read-model' },
+    { path: 'context.platform.readModels.device.sensors', source: device.sensors, kind: 'daemon-read-model' },
+    { path: 'context.platform.readModels.companion.capabilities', source: companion.capabilities, kind: 'daemon-read-model' },
+    { path: 'context.platform.readModels.voice.workflows', source: voice.workflows, kind: 'daemon-read-model' },
+    { path: 'context.platform.readModels.deviceCapabilities', source: readModels.deviceCapabilities, kind: 'daemon-read-model' },
+    { path: 'context.platform.readModels.companionCapabilities', source: readModels.companionCapabilities, kind: 'daemon-read-model' },
+    { path: 'context.ops.device.capabilities', source: opsDevice.capabilities, kind: 'sdk-read-model' },
+    { path: 'context.clients.operator.device.capabilities', source: readObject(operator.device).capabilities, kind: 'sdk-read-model' },
+    { path: 'context.clients.operatorSdk.device.capabilities', source: readObject(operatorSdk.device).capabilities, kind: 'sdk-read-model' },
+  ];
+}
+
+export function isCertifiedDeviceLiveRecord(record: DeviceLiveCapabilityRecord): boolean {
+  return record.certification.schemaStatus === 'certified' && record.certification.missingSignals.length === 0;
+}
+
+export function certifiedDeviceLiveRecords(
+  snapshot: DeviceLiveReadModelSnapshot,
+  capabilityId: string,
+  terms: readonly string[] = [],
+): readonly DeviceLiveCapabilityRecord[] {
+  const expected = [capabilityId, ...terms].map((term) => term.toLowerCase());
+  return snapshot.capabilities.filter((record) => {
+    if (!isCertifiedDeviceLiveRecord(record)) return false;
+    const text = [
+      record.id,
+      record.capabilityId,
+      record.label ?? '',
+      record.domain,
+      record.status,
+      record.summary ?? '',
+      record.permissionScope ?? '',
+      ...record.capabilities,
+    ].join('\n').toLowerCase();
+    return expected.some((term) => text.includes(term));
+  });
+}
+
+export function deviceLiveReadModelSnapshot(context: CommandContext): DeviceLiveReadModelSnapshot {
+  const entries = sources(context).flatMap((candidate) => collectFromSource(candidate.source, candidate.path, candidate.kind));
+  const seen = new Set<string>();
+  const capabilities: DeviceLiveCapabilityRecord[] = [];
+  for (const record of entries.map(normalizeCapability).filter((entry): entry is DeviceLiveCapabilityRecord => entry !== null)) {
+    const key = `${record.capabilityId}:${record.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    capabilities.push(record);
+  }
+  return {
+    capabilities,
+    sourceCounts: sourceCounts(entries),
+  };
+}

package/src/tools/agent-harness-document-ops-reviewer-readiness.ts

@@ -0,0 +1,234 @@
+import type { ArtifactDescriptor } from '@pellux/goodvibes-sdk/platform/artifacts';
+import type { CommandContext } from '../input/command-registry.ts';
+import { AgentDocumentRegistry, type AgentDocumentRecord } from '../agent/document-registry.ts';
+import type { ReviewerReadinessCheck, ReviewerReadinessChecklist, ReviewerReadinessStatus } from './agent-harness-document-ops-types.ts';
+
+function readMetadataString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readMetadataStringList(value: unknown): readonly string[] {
+  if (typeof value === 'string') {
+    return value.split(/[,\n]/).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 artifactPurpose(artifact: ArtifactDescriptor): string {
+  return readMetadataString(artifact.metadata.purpose);
+}
+
+function isModelCompareArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = artifactPurpose(artifact);
+  if (purpose === 'agent-model-compare') return true;
+  if (purpose) return false;
+  return readMetadataString(artifact.filename).startsWith('blind-model-comparison-cmp_');
+}
+
+function isModelCompareJudgmentArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = artifactPurpose(artifact);
+  if (purpose === 'agent-model-compare-judgment') return true;
+  if (purpose) return false;
+  return readMetadataString(artifact.filename).startsWith('blind-model-comparison-judgment-');
+}
+
+function isModelCompareRouteDecisionArtifact(artifact: ArtifactDescriptor): boolean {
+  return artifactPurpose(artifact) === 'agent-model-compare-route-decision';
+}
+
+function isModelCompareHandoffArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = artifactPurpose(artifact);
+  if (purpose === 'agent-model-compare-handoff') return true;
+  if (purpose) return false;
+  return readMetadataString(artifact.filename).startsWith('blind-model-comparison-handoff-');
+}
+
+function readDocuments(context: CommandContext): readonly AgentDocumentRecord[] {
+  const shellPaths = context.workspace?.shellPaths;
+  if (!shellPaths) return [];
+  try {
+    return AgentDocumentRegistry.fromShellPaths(shellPaths).list();
+  } catch {
+    return [];
+  }
+}
+
+function readArtifacts(context: CommandContext): readonly ArtifactDescriptor[] {
+  try {
+    return context.platform.artifactStore?.list?.(100) ?? [];
+  } catch {
+    return [];
+  }
+}
+
+function reviewerReadinessStatus(checks: readonly ReviewerReadinessCheck[]): ReviewerReadinessStatus {
+  if (checks.some((check) => check.status === 'needs-setup')) return 'needs-setup';
+  if (checks.some((check) => check.status === 'attention')) return 'attention';
+  return 'ready';
+}
+
+export function buildReviewerReadinessChecklist(
+  context: CommandContext,
+  options: {
+    readonly documentsReady: boolean;
+    readonly modelCompareReady: boolean;
+    readonly artifactBrowserReady: boolean;
+  },
+): ReviewerReadinessChecklist {
+  const documents = readDocuments(context);
+  const reviewDocuments = documents.filter((document) => document.status !== 'archived');
+  const openComments = reviewDocuments.reduce((total, document) => total + document.comments.filter((comment) => comment.status === 'open').length, 0);
+  const proposedSuggestions = reviewDocuments.reduce((total, document) => total + document.suggestions.filter((suggestion) => suggestion.status === 'proposed').length, 0);
+  const documentsMissingSourceArtifacts = reviewDocuments.filter((document) => document.attachments.length === 0 && !document.lastArtifactId).length;
+  const artifacts = readArtifacts(context);
+  const comparisons = artifacts.filter(isModelCompareArtifact);
+  const judgments = artifacts.filter(isModelCompareJudgmentArtifact);
+  const routeDecisions = artifacts.filter(isModelCompareRouteDecisionArtifact);
+  const handoffs = artifacts.filter(isModelCompareHandoffArtifact);
+  const revealedJudgments = judgments.filter((artifact) => (
+    artifact.metadata.revealIncludedInJudgment === true
+    && readMetadataString(artifact.metadata.winnerModel).length > 0
+  ));
+  const hiddenJudgments = judgments.filter((artifact) => (
+    artifact.metadata.revealIncludedInJudgment !== true
+    || readMetadataString(artifact.metadata.winnerModel).length === 0
+  ));
+  const routeDecisionComparisonIds = new Set(routeDecisions.map((artifact) => readMetadataString(artifact.metadata.comparisonId)).filter(Boolean));
+  const routeDecisionJudgmentArtifactIds = new Set(routeDecisions.map((artifact) => readMetadataString(artifact.metadata.judgmentArtifactId)).filter(Boolean));
+  const revealedJudgmentsWaitingOnRouteDecision = revealedJudgments.filter((artifact) => {
+    const comparisonId = readMetadataString(artifact.metadata.comparisonId);
+    return !routeDecisionJudgmentArtifactIds.has(artifact.id) && (!comparisonId || !routeDecisionComparisonIds.has(comparisonId));
+  });
+  const revealedComparisonIds = new Set(revealedJudgments.map((artifact) => readMetadataString(artifact.metadata.comparisonId)).filter(Boolean));
+  const unrevealedComparisons = comparisons.filter((artifact) => {
+    const comparisonId = readMetadataString(artifact.metadata.comparisonId);
+    return artifact.metadata.revealIncludedInTranscript !== true && (!comparisonId || !revealedComparisonIds.has(comparisonId));
+  });
+  const handoffsMissingRelatedArtifacts = handoffs.filter((artifact) => readMetadataStringList(artifact.metadata.relatedArtifactIds).length === 0).length;
+  const comparisonSourceMissing = comparisons.filter((artifact) => (
+    !readMetadataString(artifact.metadata.sourceArtifactId)
+    && !readMetadataString(artifact.metadata.documentId)
+  )).length;
+  const missingSourceArtifacts = documentsMissingSourceArtifacts + comparisonSourceMissing;
+  const firstOpenCommentDocument = reviewDocuments.find((document) => document.comments.some((comment) => comment.status === 'open'));
+  const firstProposedSuggestionDocument = reviewDocuments.find((document) => document.suggestions.some((suggestion) => suggestion.status === 'proposed'));
+  const firstUnrevealedComparison = unrevealedComparisons[0];
+  const firstHiddenJudgment = hiddenJudgments[0];
+  const firstRevealedJudgment = revealedJudgmentsWaitingOnRouteDecision[0];
+  const firstHandoffMissingRelated = handoffs.find((artifact) => readMetadataStringList(artifact.metadata.relatedArtifactIds).length === 0);
+
+  const checks: ReviewerReadinessCheck[] = [
+    {
+      id: 'review-tooling',
+      label: 'Review tooling',
+      status: options.documentsReady && options.modelCompareReady && options.artifactBrowserReady ? 'pass' : 'needs-setup',
+      count: Number(options.documentsReady) + Number(options.modelCompareReady) + Number(options.artifactBrowserReady),
+      detail: options.documentsReady && options.modelCompareReady && options.artifactBrowserReady
+        ? 'Document, artifact, and blind comparison routes are available.'
+        : 'Document, artifact, and blind comparison routes must be available before a reviewer-ready export can be trusted.',
+      inspectRoute: 'agent_harness mode:"document_ops"',
+      repairRoute: 'agent_harness mode:"workspace_actions" categoryId:"documents"',
+    },
+    {
+      id: 'document-review-state',
+      label: 'Document comments and suggestions',
+      status: openComments + proposedSuggestions > 0 ? 'attention' : 'pass',
+      count: openComments + proposedSuggestions,
+      detail: openComments + proposedSuggestions > 0
+        ? `${openComments} open comment(s) and ${proposedSuggestions} proposed suggestion(s) need a visible resolve, accept, or reject decision.`
+        : 'No open document comments or proposed AI suggestions are waiting on reviewer action.',
+      inspectRoute: firstOpenCommentDocument || firstProposedSuggestionDocument
+        ? `agent_documents show documentId:"${firstOpenCommentDocument?.id ?? firstProposedSuggestionDocument?.id}" includeVersions:true`
+        : 'agent_documents list',
+      repairRoute: firstOpenCommentDocument
+        ? `agent_documents resolveComment documentId:"${firstOpenCommentDocument.id}" commentId:"..." confirm:true explicitUserRequest:"..."`
+        : firstProposedSuggestionDocument
+          ? `agent_documents acceptSuggestion documentId:"${firstProposedSuggestionDocument.id}" suggestionId:"..." confirm:true explicitUserRequest:"..." or agent_documents rejectSuggestion documentId:"${firstProposedSuggestionDocument.id}" suggestionId:"..." confirm:true explicitUserRequest:"..."`
+          : undefined,
+    },
+    {
+      id: 'source-artifacts',
+      label: 'Source artifacts',
+      status: missingSourceArtifacts > 0 ? 'attention' : 'pass',
+      count: missingSourceArtifacts,
+      detail: missingSourceArtifacts > 0
+        ? `${documentsMissingSourceArtifacts} document draft(s) and ${comparisonSourceMissing} comparison artifact(s) have no attached source artifact or document source marker.`
+        : 'Document drafts and saved comparisons have source artifacts or explicit document/source markers where the current stores can verify them.',
+      inspectRoute: 'agent_harness mode:"document_ops_lane" laneId:"artifact_browser"',
+      repairRoute: missingSourceArtifacts > 0
+        ? 'agent_documents attachArtifact documentId:"..." artifactId:"..." confirm:true explicitUserRequest:"..." or agent_model_compare handoff artifactId:"..." relatedArtifactIds:"..." confirm:true explicitUserRequest:"..."'
+        : undefined,
+    },
+    {
+      id: 'comparison-reveal',
+      label: 'Blind comparison reveal',
+      status: unrevealedComparisons.length + hiddenJudgments.length > 0 ? 'attention' : 'pass',
+      count: unrevealedComparisons.length + hiddenJudgments.length,
+      detail: unrevealedComparisons.length + hiddenJudgments.length > 0
+        ? `${unrevealedComparisons.length} saved comparison(s) and ${hiddenJudgments.length} judgment(s) still hide winner identity before reviewer handoff.`
+        : 'Saved comparison judgments with route-change implications are revealed, or no hidden comparison artifacts are pending.',
+      inspectRoute: firstUnrevealedComparison
+        ? `agent_model_compare review artifactId:"${firstUnrevealedComparison.id}"`
+        : firstHiddenJudgment
+          ? `agent_model_compare review artifactId:"${firstHiddenJudgment.id}"`
+          : 'agent_model_compare review',
+      repairRoute: firstUnrevealedComparison
+        ? `agent_model_compare reveal artifactId:"${firstUnrevealedComparison.id}"`
+        : firstHiddenJudgment
+          ? `agent_model_compare judge artifactId:"${readMetadataString(firstHiddenJudgment.metadata.sourceArtifactId) || firstHiddenJudgment.id}" winnerBlindId:"${readMetadataString(firstHiddenJudgment.metadata.winnerBlindId) || '...'}" reveal:true confirm:true explicitUserRequest:"..."`
+          : undefined,
+    },
+    {
+      id: 'route-change-decision',
+      label: 'Route-change decision',
+      status: revealedJudgmentsWaitingOnRouteDecision.length > 0 ? 'attention' : 'pass',
+      count: revealedJudgmentsWaitingOnRouteDecision.length,
+      detail: revealedJudgmentsWaitingOnRouteDecision.length > 0
+        ? `${revealedJudgmentsWaitingOnRouteDecision.length} revealed judgment(s) can drive a confirmed model route update, or the user can explicitly leave routing unchanged before archiving.`
+        : 'No revealed model comparison judgment is waiting on an apply-or-leave-unchanged decision.',
+      inspectRoute: firstRevealedJudgment
+        ? `agent_model_compare review artifactId:"${firstRevealedJudgment.id}" reveal:true`
+        : 'models action:"status"',
+      repairRoute: firstRevealedJudgment
+        ? `agent_model_compare apply artifactId:"${firstRevealedJudgment.id}" confirm:true explicitUserRequest:"..." or agent_model_compare routeDecision artifactId:"${firstRevealedJudgment.id}" decision:"left-unchanged" confirm:true explicitUserRequest:"..."`
+        : undefined,
+    },
+    {
+      id: 'handoff-archive-evidence',
+      label: 'Reviewer handoff evidence',
+      status: handoffsMissingRelatedArtifacts > 0 ? 'attention' : 'pass',
+      count: handoffsMissingRelatedArtifacts,
+      detail: handoffsMissingRelatedArtifacts > 0
+        ? `${handoffsMissingRelatedArtifacts} reviewer handoff artifact(s) have no related evidence artifact ids before archive.`
+        : 'Reviewer handoff artifacts include related evidence ids, or no reviewer handoff archive is pending.',
+      inspectRoute: firstHandoffMissingRelated
+        ? `agent_model_compare review artifactId:"${firstHandoffMissingRelated.id}"`
+        : 'agent_model_compare review',
+      repairRoute: firstHandoffMissingRelated
+        ? `agent_model_compare handoff artifactId:"${readMetadataString(firstHandoffMissingRelated.metadata.sourceArtifactId) || firstHandoffMissingRelated.id}" relatedArtifactIds:"..." confirm:true explicitUserRequest:"..."`
+        : undefined,
+    },
+  ];
+  const status = reviewerReadinessStatus(checks);
+  const firstAction = checks.find((check) => check.status === 'attention' || check.status === 'needs-setup');
+  return {
+    status,
+    next: firstAction
+      ? `${firstAction.label}: ${firstAction.detail}`
+      : 'Export or archive reviewer packets through the returned confirmed document, artifact, or comparison routes.',
+    summary: {
+      documents: documents.length,
+      openComments,
+      proposedSuggestions,
+      documentsMissingSourceArtifacts,
+      savedComparisons: comparisons.length,
+      unrevealedComparisons: unrevealedComparisons.length,
+      hiddenJudgments: hiddenJudgments.length,
+      revealedJudgments: revealedJudgmentsWaitingOnRouteDecision.length,
+      handoffsMissingRelatedArtifacts,
+    },
+    checks,
+    policy: 'Reviewer readiness is read-only. It flags unresolved review work and returns exact existing routes; document exports, comparison handoffs, archives, and model route updates still require explicit confirmation.',
+  };
+}

package/src/tools/agent-harness-document-ops-types.ts

@@ -0,0 +1,72 @@
+import type { AgentWorkspaceReviewPacketWizard } from '../input/agent-workspace-types.ts';
+
+export type DocumentOpsLaneId =
+  | 'documents'
+  | 'uploads'
+  | 'exports'
+  | 'reviewer_readiness'
+  | 'review_packet_timeline'
+  | 'review_packet_wizard'
+  | 'source_library'
+  | 'media_artifacts'
+  | 'artifact_browser'
+  | 'model_compare';
+
+export type DocumentOpsStatus = 'ready' | 'attention' | 'partial' | 'needs-setup' | 'gap';
+export type ReviewerReadinessStatus = 'ready' | 'attention' | 'needs-setup';
+export type ReviewerReadinessCheckStatus = 'pass' | 'attention' | 'needs-setup';
+
+export interface AgentHarnessDocumentOpsArgs {
+  readonly laneId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+}
+
+export interface DocumentOpsLane {
+  readonly id: DocumentOpsLaneId;
+  readonly label: string;
+  readonly status: DocumentOpsStatus;
+  readonly outcome: string;
+  readonly current: string;
+  readonly next: string;
+  readonly userRoute: string;
+  readonly modelRoute: string;
+  readonly signals: readonly string[];
+  readonly actionIds: readonly string[];
+  readonly reviewerReadiness?: ReviewerReadinessChecklist;
+  readonly reviewPacketWizard?: AgentWorkspaceReviewPacketWizard;
+}
+
+export interface ReviewerReadinessChecklist {
+  readonly status: ReviewerReadinessStatus;
+  readonly next: string;
+  readonly summary: {
+    readonly documents: number;
+    readonly openComments: number;
+    readonly proposedSuggestions: number;
+    readonly documentsMissingSourceArtifacts: number;
+    readonly savedComparisons: number;
+    readonly unrevealedComparisons: number;
+    readonly hiddenJudgments: number;
+    readonly revealedJudgments: number;
+    readonly handoffsMissingRelatedArtifacts: number;
+  };
+  readonly checks: readonly ReviewerReadinessCheck[];
+  readonly policy: string;
+}
+
+export interface ReviewerReadinessCheck {
+  readonly id: string;
+  readonly label: string;
+  readonly status: ReviewerReadinessCheckStatus;
+  readonly count: number;
+  readonly detail: string;
+  readonly inspectRoute: string;
+  readonly repairRoute?: string;
+}
+
+export type DocumentOpsLaneResolution =
+  | { readonly status: 'found'; readonly lane: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };