@haaaiawd/second-nature 0.1.27 → 0.1.30

package/runtime/cli/ops/ops-router.js

@@ -1,14 +1,32 @@
 /**
  * Shared ops command dispatch for CLI + tool surfaces (T1.1.3, T1.2.2).
+ *
+ * v7 additions (T-ROS.C.1): self_health, tool_affordance, connector_test --wet,
+ * heartbeat_digest, narrative:diff, timeline, restore, runtime_secret_bootstrap.
+ * All commands return RuntimeOpsEnvelope.
  */
+import fs from "node:fs";
 import { heartbeatCheck, } from "./heartbeat-surface.js";
 import { showOperatorFallback, OperatorFallbackNotFoundError, } from "./show-operator-fallback.js";
 import { probeHostCapability } from "../host-capability/probe-host-capability.js";
 import { recordHostCapability } from "../host-capability/record-host-capability.js";
 import { runNearRealConnectorSmoke } from "../../connectors/near-real/near-real-connector-smoke.js";
 import { connectorInit } from "../commands/connector-init.js";
+import { connectorBehaviorAdd } from "../commands/connector-behavior.js";
 import { connectorStatus, connectorTest } from "../commands/connector-status.js";
 import { goalCommand } from "../commands/goal.js";
+// v7 observability services (T-ROS.C.1)
+import { getSelfHealthSnapshot, ensureMinimumProbes, } from "../../observability/services/self-health-snapshot.js";
+import { generateHeartbeatDigest, } from "../../observability/services/heartbeat-digest-assembler.js";
+import { queryNarrativeTimeline, queryNarrativeDiff, } from "../../observability/services/narrative-timeline-query-service.js";
+import { viewSecretAnchor, } from "../../observability/services/runtime-secret-anchor-view.js";
+import { writeRestoreAudit, } from "../../observability/services/restore-audit-service.js";
+// T-ROS.C.3: ManualRunDispatcher and its deps
+import { createManualRunDispatcher, } from "./manual-run-dispatcher.js";
+import { createExperienceWriter } from "../../core/second-nature/body/tool-experience/experience-writer.js";
+import { createToolExperienceStore } from "../../storage/services/tool-experience-store.js";
+import { createWetProbeRunner } from "../../connectors/base/wet-probe-runner.js";
+import { CapabilityContractRegistryV7 } from "../../connectors/base/manifest-v7.js";
 function coerceProbeOnlyFlag(input) {
     const v = input?.probeOnly;
     return v === true || v === "true" || v === 1 || v === "1";
@@ -200,6 +218,23 @@ export function createOpsRouter(deps) {
                     return result;
                 })();
             }
+            if (command === "connector_behavior_add") {
+                return connectorBehaviorAdd({
+                    platformId: typeof input?.platformId === "string" ? input.platformId : "",
+                    behaviorId: typeof input?.behaviorId === "string"
+                        ? input.behaviorId
+                        : typeof input?.capabilityId === "string"
+                            ? input.capabilityId
+                            : "",
+                    description: typeof input?.description === "string" ? input.description : undefined,
+                    channel: typeof input?.channel === "string" ? input.channel : undefined,
+                    sourceRefs: input?.sourceRefs,
+                    observedCount: typeof input?.observedCount === "number" ? input.observedCount : undefined,
+                    workspaceRoot: typeof input?.workspaceRoot === "string"
+                        ? input.workspaceRoot
+                        : deps.workspaceRoot,
+                });
+            }
             if (command === "connector_status") {
                 return connectorStatus(deps.registry, undefined, {
                     includeHealth: Boolean(input?.includeHealth),
@@ -209,9 +244,79 @@ export function createOpsRouter(deps) {
                 });
             }
             if (command === "connector_test") {
-                return connectorTest(deps.registry, {
+                // v7 T-ROS.C.1: --wet flag (wet=true) sets dryRun=false + marks triggerSource:"manual_run"
+                const isWet = input?.wet === true || input?.wet === "true";
+                const result = await connectorTest(deps.registry, {
                     platformId: typeof input?.platformId === "string" ? input.platformId : "",
-                    dryRun: input?.dryRun === false ? false : true, // default dry-run
+                    dryRun: isWet ? false : (input?.dryRun === false ? false : true),
+                });
+                if (isWet && result.ok) {
+                    // Annotate result with manual trigger context (DR-038 / T-ROS.C.3)
+                    result.triggerSource = "manual_run";
+                    result.affectsHeartbeatCadence = false;
+                }
+                return result;
+            }
+            if (command === "connector:run") {
+                // T-ROS.C.3: manual connector execution — isolated from heartbeat cadence
+                const platformId = typeof input?.platformId === "string" ? input.platformId : "";
+                const capabilityId = typeof input?.capabilityId === "string" ? input.capabilityId : "";
+                if (!platformId || !capabilityId) {
+                    return {
+                        ok: false,
+                        command: "connector:run",
+                        error: {
+                            code: "MISSING_PLATFORM_OR_CAPABILITY_ID",
+                            message: "connector:run requires platformId and capabilityId",
+                            requiredUserInput: ["platformId", "capabilityId"],
+                            nextStep: "reinvoke_with_platform_and_capability_id",
+                        },
+                    };
+                }
+                if (!deps.connectorExecutor || !deps.state) {
+                    return {
+                        ok: false,
+                        command: "connector:run",
+                        error: {
+                            code: "MANUAL_RUN_DEPS_UNAVAILABLE",
+                            message: "connector:run requires connectorExecutor and state database",
+                            nextStep: "wire_connector_executor_and_state_into_ops_router",
+                        },
+                    };
+                }
+                const toolExperienceStore = createToolExperienceStore(deps.state);
+                const experienceWriter = createExperienceWriter(toolExperienceStore);
+                const wetProbeRunner = createWetProbeRunner();
+                const registryV7 = new CapabilityContractRegistryV7();
+                // Populate V7 registry from dynamic registry if available (best-effort)
+                if (deps.registry) {
+                    for (const entry of deps.registry.listConnectors()) {
+                        if (entry.manifestPath) {
+                            try {
+                                const manifestText = fs.readFileSync(entry.manifestPath, "utf-8");
+                                const manifest = JSON.parse(manifestText);
+                                registryV7.register(manifest);
+                            }
+                            catch {
+                                // Skip manifests that can't be read or don't validate as V7
+                            }
+                        }
+                    }
+                }
+                const dispatcher = createManualRunDispatcher({
+                    connectorExecutor: deps.connectorExecutor,
+                    experienceWriter,
+                    wetProbeRunner,
+                    registryV7,
+                });
+                return dispatcher.runConnector({
+                    platformId,
+                    capabilityId,
+                    payload: typeof input?.payload === "object" && input?.payload !== null
+                        ? input.payload
+                        : undefined,
+                    caller: typeof input?.caller === "string" ? input.caller : undefined,
+                    reason: typeof input?.reason === "string" ? input.reason : undefined,
                 });
             }
             if (command === "goal") {
@@ -275,6 +380,442 @@ export function createOpsRouter(deps) {
                 const data = await deps.readModels.loadCycleRecent(limit);
                 return { ok: true, data };
             }
+            // ─── v7 commands (T-ROS.C.1) ─────────────────────────────────────────
+            /** [G2] self_health — transparent pass-through from SelfHealthSnapshot (DR-042). */
+            if (command === "self_health") {
+                const generatedAt = new Date().toISOString();
+                try {
+                    ensureMinimumProbes();
+                    const snap = await getSelfHealthSnapshot();
+                    const degraded_dimensions = Object.entries(snap.dimensions)
+                        .filter(([, d]) => d.status === "degraded")
+                        .map(([k]) => k);
+                    const envelope = {
+                        ok: true,
+                        command: "self_health",
+                        runtimeMode: "workspace_full_runtime",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        data: {
+                            overall: snap.overall,
+                            generatedAt: snap.generatedAt,
+                            degraded_dimensions,
+                            dimensions: snap.dimensions,
+                        },
+                        warnings: [],
+                        sourceRefs: ["observability/services/self-health-snapshot.ts"],
+                    };
+                    return envelope;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    const envelope = {
+                        ok: false,
+                        command: "self_health",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: { code: "SELF_HEALTH_PROBE_FAILED", message: msg },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+            }
+            /**
+             * [G3] tool_affordance — body-tool AffordanceMap pass-through.
+             * Port not yet wired in this wave; returns degraded view with clear next-step.
+             */
+            if (command === "tool_affordance") {
+                const generatedAt = new Date().toISOString();
+                const envelope = {
+                    ok: false,
+                    command: "tool_affordance",
+                    runtimeMode: "unavailable",
+                    surfaceMode: "cli",
+                    generatedAt,
+                    error: {
+                        code: "TOOL_AFFORDANCE_PORT_UNWIRED",
+                        message: "tool_affordance requires body-tool AffordanceMap port (T-BTS.C.1) to be wired into OpsRouterDeps",
+                        nextStep: "wire_body_tool_port_into_ops_router_deps",
+                    },
+                    warnings: [],
+                    sourceRefs: [],
+                };
+                return envelope;
+            }
+            /**
+             * [G6] heartbeat_digest — wraps generateHeartbeatDigest.
+             * Requires auditStore in deps; degrades if unavailable.
+             */
+            if (command === "heartbeat_digest") {
+                const generatedAt = new Date().toISOString();
+                if (!deps.auditStore) {
+                    const envelope = {
+                        ok: false,
+                        command: "heartbeat_digest",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: {
+                            code: "AUDIT_STORE_UNAVAILABLE",
+                            message: "heartbeat_digest requires auditStore in OpsRouterDeps",
+                            nextStep: "wire_audit_store_into_ops_router",
+                        },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                const date = typeof input?.date === "string" && input.date
+                    ? input.date
+                    : new Date().toISOString().slice(0, 10);
+                try {
+                    const digestDeps = {
+                        auditStore: deps.auditStore,
+                        ...deps.heartbeatDigestDeps,
+                    };
+                    const digest = await generateHeartbeatDigest(date, digestDeps);
+                    const envelope = {
+                        ok: true,
+                        command: "heartbeat_digest",
+                        runtimeMode: "workspace_full_runtime",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        data: digest,
+                        warnings: [],
+                        sourceRefs: ["observability/services/heartbeat-digest-assembler.ts"],
+                    };
+                    return envelope;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    const envelope = {
+                        ok: false,
+                        command: "heartbeat_digest",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: { code: "DIGEST_GENERATION_FAILED", message: msg },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+            }
+            /**
+             * [G6] narrative:diff — queryNarrativeDiff between two versions.
+             * Requires narrativeTimelineDeps in OpsRouterDeps.
+             */
+            if (command === "narrative:diff") {
+                const generatedAt = new Date().toISOString();
+                if (!deps.narrativeTimelineDeps) {
+                    const envelope = {
+                        ok: false,
+                        command: "narrative:diff",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: {
+                            code: "NARRATIVE_TIMELINE_PORT_UNAVAILABLE",
+                            message: "narrative:diff requires narrativeTimelineDeps in OpsRouterDeps",
+                            nextStep: "wire_narrative_timeline_deps_into_ops_router",
+                        },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                const fromVersion = typeof input?.from === "string" ? input.from : "";
+                const toVersion = typeof input?.to === "string" ? input.to : "";
+                if (!fromVersion || !toVersion) {
+                    const envelope = {
+                        ok: false,
+                        command: "narrative:diff",
+                        runtimeMode: "workspace_full_runtime",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: {
+                            code: "MISSING_VERSIONS",
+                            message: "narrative:diff requires 'from' and 'to' version arguments",
+                            nextStep: "reinvoke_with_from_and_to",
+                        },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                try {
+                    const diff = await queryNarrativeDiff(fromVersion, toVersion, deps.narrativeTimelineDeps);
+                    const envelope = {
+                        ok: true,
+                        command: "narrative:diff",
+                        runtimeMode: "workspace_full_runtime",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        data: diff,
+                        warnings: [],
+                        sourceRefs: ["observability/services/narrative-timeline-query-service.ts"],
+                    };
+                    return envelope;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    const envelope = {
+                        ok: false,
+                        command: "narrative:diff",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: { code: "NARRATIVE_DIFF_FAILED", message: msg },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+            }
+            /**
+             * [G6] timeline — queryNarrativeTimeline with cursor pagination.
+             * Requires narrativeTimelineDeps in OpsRouterDeps.
+             */
+            if (command === "timeline") {
+                const generatedAt = new Date().toISOString();
+                if (!deps.narrativeTimelineDeps) {
+                    const envelope = {
+                        ok: false,
+                        command: "timeline",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: {
+                            code: "NARRATIVE_TIMELINE_PORT_UNAVAILABLE",
+                            message: "timeline requires narrativeTimelineDeps in OpsRouterDeps",
+                            nextStep: "wire_narrative_timeline_deps_into_ops_router",
+                        },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                const now = new Date();
+                const to = typeof input?.to === "string" ? input.to : now.toISOString();
+                const from = typeof input?.from === "string"
+                    ? input.from
+                    : new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString();
+                const limit = typeof input?.limit === "number" ? input.limit : 20;
+                const cursor = typeof input?.cursor === "string" ? input.cursor : undefined;
+                try {
+                    const page = await queryNarrativeTimeline(from, to, { limit, cursor }, deps.narrativeTimelineDeps);
+                    const envelope = {
+                        ok: true,
+                        command: "timeline",
+                        runtimeMode: "workspace_full_runtime",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        data: page,
+                        warnings: [],
+                        sourceRefs: ["observability/services/narrative-timeline-query-service.ts"],
+                    };
+                    return envelope;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    const code = err.name === "NarrativeQueryRangeError"
+                        ? "NARRATIVE_RANGE_EXCEEDED"
+                        : "TIMELINE_QUERY_FAILED";
+                    const envelope = {
+                        ok: false,
+                        command: "timeline",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: { code, message: msg },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+            }
+            /**
+             * [G6] restore — bounded state restoration via RestoreSnapshotStore + audit (T-ROS.C.1, T-OBS.C.6).
+             * When restoreSnapshotStore is wired, attempts to apply the snapshot payload back to state.
+             * Always writes RestoreAudit. Never restores credential fields.
+             */
+            if (command === "restore") {
+                const generatedAt = new Date().toISOString();
+                if (!deps.auditStore) {
+                    const envelope = {
+                        ok: false,
+                        command: "restore",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: {
+                            code: "AUDIT_STORE_UNAVAILABLE",
+                            message: "restore requires auditStore in OpsRouterDeps",
+                            nextStep: "wire_audit_store_into_ops_router",
+                        },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                const missingFields = [];
+                if (typeof input?.restoreTarget !== "string")
+                    missingFields.push("restoreTarget");
+                if (typeof input?.fromVersion !== "string")
+                    missingFields.push("fromVersion");
+                if (typeof input?.toVersion !== "string")
+                    missingFields.push("toVersion");
+                if (missingFields.length > 0) {
+                    const envelope = {
+                        ok: false,
+                        command: "restore",
+                        runtimeMode: "workspace_full_runtime",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: {
+                            code: "MISSING_RESTORE_FIELDS",
+                            message: `restore requires: ${missingFields.join(", ")}`,
+                            nextStep: "reinvoke_with_required_fields",
+                        },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                // [NEW] Invoke bounded restore via RestoreSnapshotStore when wired
+                let restoreResult = {
+                    ok: false,
+                    completedEntities: [],
+                    failedEntities: [],
+                    warnings: ["restore_snapshot_store_unavailable"],
+                };
+                if (deps.restoreSnapshotStore) {
+                    restoreResult = await deps.restoreSnapshotStore.applyBoundedRestore({
+                        restoreTarget: input.restoreTarget,
+                        fromVersion: input.fromVersion,
+                        toVersion: input.toVersion,
+                    });
+                }
+                const event = {
+                    id: `restore-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                    restoreTarget: input.restoreTarget,
+                    fromVersion: input.fromVersion,
+                    toVersion: input.toVersion,
+                    triggeredBy: input?.triggeredBy ?? "operator",
+                    reason: typeof input?.reason === "string" ? input.reason : "manual_restore",
+                    completedEntities: restoreResult.completedEntities,
+                    failedEntities: restoreResult.failedEntities,
+                    // credentials are always excluded from restore audit
+                    excludedFields: Array.isArray(input?.excludedFields)
+                        ? input.excludedFields.filter((f) => typeof f === "string")
+                        : ["credential", "encryptionKey"],
+                    restoredFieldCount: restoreResult.completedEntities.length,
+                    createdAt: generatedAt,
+                    traceId: typeof input?.traceId === "string" ? input.traceId : `trace-restore-${Date.now()}`,
+                };
+                const auditResult = await writeRestoreAudit(event, deps.auditStore);
+                const envelope = {
+                    ok: restoreResult.ok && auditResult.ok,
+                    command: "restore",
+                    runtimeMode: "workspace_full_runtime",
+                    surfaceMode: "cli",
+                    generatedAt,
+                    data: {
+                        auditWritten: auditResult.warnings.length === 0,
+                        fromVersion: event.fromVersion,
+                        toVersion: event.toVersion,
+                        restoreTarget: event.restoreTarget,
+                        isPartialRestore: event.failedEntities.length > 0,
+                        failedEntities: event.failedEntities,
+                        completedEntities: event.completedEntities,
+                        restoreSnapshotStoreAvailable: !!deps.restoreSnapshotStore,
+                    },
+                    warnings: [...restoreResult.warnings, ...auditResult.warnings],
+                    sourceRefs: [
+                        "observability/services/restore-audit-service.ts",
+                        "storage/services/restore-snapshot-store.ts",
+                    ],
+                };
+                return envelope;
+            }
+            /**
+             * [G7] runtime_secret_bootstrap — RuntimeSecretAnchorView pass-through.
+             * Requires secretAnchorDeps in OpsRouterDeps; never returns key plaintext.
+             */
+            if (command === "runtime_secret_bootstrap") {
+                const generatedAt = new Date().toISOString();
+                if (!deps.secretAnchorDeps) {
+                    const envelope = {
+                        ok: false,
+                        command: "runtime_secret_bootstrap",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: {
+                            code: "SECRET_ANCHOR_DEPS_UNAVAILABLE",
+                            message: "runtime_secret_bootstrap requires secretAnchorDeps in OpsRouterDeps",
+                            nextStep: "wire_secret_anchor_deps_into_ops_router",
+                        },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+                try {
+                    const view = await viewSecretAnchor(deps.secretAnchorDeps);
+                    // Map to RuntimeSecretBootstrapView (design model §6.1)
+                    const data = {
+                        status: view.status === "verified" || view.status === "ok"
+                            ? "ok"
+                            : view.status === "missing"
+                                ? "runtime_secret_anchor_missing"
+                                : view.status === "wrong_key"
+                                    ? "credential_recovery_required"
+                                    : view.status === "decryption_failed"
+                                        ? "runtime_secret_unavailable"
+                                        : "unknown",
+                        keyHealth: view.status === "verified" || view.status === "ok"
+                            ? "ok"
+                            : view.status === "missing"
+                                ? "missing_key"
+                                : view.status === "wrong_key"
+                                    ? "wrong_key"
+                                    : "unknown",
+                        anchorLocation: view.keyPath,
+                        recoveryPrincipleRef: view.recoveryDocRef,
+                        plaintextKeyExposed: false,
+                        reasonCode: view.reasonCode,
+                        recoverySteps: view.recoverySteps,
+                    };
+                    const envelope = {
+                        ok: true,
+                        command: "runtime_secret_bootstrap",
+                        runtimeMode: "workspace_full_runtime",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        data,
+                        warnings: [],
+                        sourceRefs: ["observability/services/runtime-secret-anchor-view.ts"],
+                    };
+                    return envelope;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    const envelope = {
+                        ok: false,
+                        command: "runtime_secret_bootstrap",
+                        runtimeMode: "unavailable",
+                        surfaceMode: "cli",
+                        generatedAt,
+                        error: { code: "SECRET_ANCHOR_PROBE_FAILED", message: msg },
+                        warnings: [],
+                        sourceRefs: [],
+                    };
+                    return envelope;
+                }
+            }
             return {
                 ok: false,
                 error: {