@haaaiawd/second-nature 0.1.26 → 0.1.29

package/runtime/cli/commands/connector-behavior.js

@@ -0,0 +1,160 @@
+/**
+ * Workspace connector behavior authoring.
+ *
+ * Adds a declarative capability stub to `.second-nature/connectors/{platformId}/manifest.yaml`.
+ * This records a behavior the agent discovered without granting executable custom code.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import { connectorManifestV6Schema } from "../../connectors/manifest/manifest-schema.js";
+const PLATFORM_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const BEHAVIOR_ID_PATTERN = /^[a-zA-Z0-9_.:-]+$/;
+function resolveManifestPath(workspaceRoot, platformId) {
+    const root = workspaceRoot ? path.resolve(workspaceRoot) : process.cwd();
+    return path.join(root, ".second-nature", "connectors", platformId, "manifest.yaml");
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function sanitizeText(value, max = 500) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed.slice(0, max) : undefined;
+}
+function sanitizeSourceRefs(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        if (typeof entry === "string")
+            return sanitizeText(entry, 300);
+        if (entry && typeof entry === "object" && "id" in entry) {
+            return sanitizeText(entry.id, 300);
+        }
+        return undefined;
+    })
+        .filter((entry) => !!entry);
+}
+export async function connectorBehaviorAdd(input) {
+    const platformId = sanitizeText(input.platformId, 128) ?? "";
+    const behaviorId = sanitizeText(input.behaviorId, 160) ?? "";
+    const description = sanitizeText(input.description);
+    const sourceRefs = sanitizeSourceRefs(input.sourceRefs);
+    const observedCount = Number.isInteger(input.observedCount) && input.observedCount > 0
+        ? input.observedCount
+        : undefined;
+    const manifestPath = resolveManifestPath(input.workspaceRoot, platformId || "_missing");
+    if (!platformId || platformId === "." || platformId === ".." || !PLATFORM_ID_PATTERN.test(platformId)) {
+        return {
+            ok: false,
+            command: "connector_behavior_add",
+            platformId,
+            behaviorId,
+            manifestPath,
+            added: false,
+            reason: "platformId is required and must use only letters, numbers, _, or -",
+        };
+    }
+    if (!behaviorId || !BEHAVIOR_ID_PATTERN.test(behaviorId)) {
+        return {
+            ok: false,
+            command: "connector_behavior_add",
+            platformId,
+            behaviorId,
+            manifestPath,
+            added: false,
+            reason: "behaviorId is required and must use only letters, numbers, _, -, ., or :",
+        };
+    }
+    if (!fs.existsSync(manifestPath)) {
+        return {
+            ok: false,
+            command: "connector_behavior_add",
+            platformId,
+            behaviorId,
+            manifestPath,
+            added: false,
+            reason: "connector manifest not found",
+            nextStep: "run connector_init for this platform first",
+        };
+    }
+    const raw = fs.readFileSync(manifestPath, "utf-8");
+    const manifest = asRecord(yaml.load(raw, { schema: yaml.JSON_SCHEMA }));
+    const parsedBefore = connectorManifestV6Schema.safeParse(manifest);
+    if (!parsedBefore.success) {
+        return {
+            ok: false,
+            command: "connector_behavior_add",
+            platformId,
+            behaviorId,
+            manifestPath,
+            added: false,
+            reason: `manifest schema validation failed: ${parsedBefore.error.issues.map((issue) => issue.path.join(".")).join(",")}`,
+        };
+    }
+    const capabilities = Array.isArray(manifest.capabilities)
+        ? [...manifest.capabilities]
+        : [];
+    const exists = capabilities.some((entry) => asRecord(entry).id === behaviorId);
+    if (exists) {
+        return {
+            ok: true,
+            command: "connector_behavior_add",
+            platformId,
+            behaviorId,
+            manifestPath,
+            added: false,
+            reason: "behavior already exists",
+        };
+    }
+    if (!description && sourceRefs.length === 0) {
+        return {
+            ok: false,
+            command: "connector_behavior_add",
+            platformId,
+            behaviorId,
+            manifestPath,
+            added: false,
+            reason: "behavior description or sourceRefs is required so the new action has a reviewable motive",
+        };
+    }
+    capabilities.push({
+        id: behaviorId,
+        ...(description ? { description } : {}),
+        ...(sanitizeText(input.channel, 64) ? { channel: sanitizeText(input.channel, 64) } : {}),
+        ...(sourceRefs.length > 0 ? { sourceRefs } : {}),
+        ...(observedCount ? { observedCount } : {}),
+    });
+    manifest.capabilities = capabilities;
+    const parsedAfter = connectorManifestV6Schema.safeParse(manifest);
+    if (!parsedAfter.success) {
+        return {
+            ok: false,
+            command: "connector_behavior_add",
+            platformId,
+            behaviorId,
+            manifestPath,
+            added: false,
+            reason: `manifest schema validation failed after behavior add: ${parsedAfter.error.issues.map((issue) => issue.path.join(".")).join(",")}`,
+        };
+    }
+    const nextYaml = yaml.dump(parsedAfter.data, {
+        lineWidth: 100,
+        noRefs: true,
+        sortKeys: false,
+    });
+    fs.writeFileSync(manifestPath, nextYaml, "utf-8");
+    return {
+        ok: true,
+        command: "connector_behavior_add",
+        platformId,
+        behaviorId,
+        manifestPath,
+        added: true,
+        nextStep: "run connector_status or reload the runtime registry before executing this behavior",
+    };
+}

package/runtime/cli/commands/index.js

@@ -244,6 +244,14 @@ export function createCliCommands(deps) {
                 return result;
             },
         },
+        {
+            name: "connector_behavior_add",
+            description: "Add a workspace-defined connector behavior to an existing manifest without executing custom code",
+            execute: async (input) => {
+                const surface = await Promise.resolve(opsRouter.dispatch("connector_behavior_add", input));
+                return surface;
+            },
+        },
         {
             name: "connector_status",
             description: "T1.2.3 — show connector inventory, trust/executable/conflict summary",

package/runtime/cli/index.js

@@ -6,6 +6,7 @@ import { createCliCommands, } from "./commands/index.js";
 import { createOpsRouter } from "./ops/ops-router.js";
 import { createCliReadModels, } from "./read-models/index.js";
 import { resolvePackagedRuntime } from "./runtime/runtime-artifact-boundary.js";
+import { createRestoreSnapshotStore, } from "../storage/services/restore-snapshot-store.js";
 import { createRuntimeDecisionRecorder, } from "../observability/services/runtime-decision-recorder.js";
 import { createConnectorExecutorAdapter, } from "../connectors/services/connector-executor-adapter.js";
 import { DynamicConnectorRegistry, createRegistrySnapshotStore, } from "../connectors/registry/index.js";
@@ -54,6 +55,7 @@ const BUILT_IN_CONNECTOR_MANIFESTS = [
     },
 ];
 export function createCliRuntimeDeps(overrides = {}) {
+    const workspaceRoot = overrides.workspaceRoot ?? process.cwd();
     const stateDb = overrides.stateDb ?? createStateDatabase();
     const observabilityDb = overrides.observabilityDb ?? createObservabilityDatabase();
     const stateApi = overrides.stateApi ?? createStateAPI(stateDb);
@@ -61,7 +63,7 @@ export function createCliRuntimeDeps(overrides = {}) {
         createCliReadModels({
             stateDb,
             observabilityDb,
-            workspaceRoot: process.cwd(),
+            workspaceRoot,
             livedExperienceAuditStore: overrides.livedExperienceAuditStore,
         });
     const actionBridge = overrides.actionBridge ?? createActionBridge(stateApi);
@@ -70,12 +72,14 @@ export function createCliRuntimeDeps(overrides = {}) {
         createConnectorExecutorAdapter({
             stateDb,
             observabilityDb,
+            workspaceRoot,
         });
     const registry = overrides.registry ??
         new DynamicConnectorRegistry({
             builtInManifests: BUILT_IN_CONNECTOR_MANIFESTS,
             snapshotStore: createRegistrySnapshotStore(),
         });
+    const restoreSnapshotStore = overrides.restoreSnapshotStore ?? createRestoreSnapshotStore(stateDb);
     return {
         stateDb,
         observabilityDb,
@@ -85,9 +89,11 @@ export function createCliRuntimeDeps(overrides = {}) {
         runtimeRecorder,
         connectorExecutor,
         registry,
+        restoreSnapshotStore,
     };
 }
 export function createCommandRouter(options = {}) {
+    const workspaceRoot = process.cwd();
     const runtime = createCliRuntimeDeps(options.deps);
     const pluginRoot = path.join(process.cwd(), "plugin");
     const opsRouter = createOpsRouter({
@@ -95,10 +101,11 @@ export function createCommandRouter(options = {}) {
         readModels: runtime.readModels,
         runtimeRecorder: runtime.runtimeRecorder,
         state: runtime.stateDb,
-        workspaceRoot: process.cwd(),
+        workspaceRoot,
         observabilityDb: runtime.observabilityDb,
         connectorExecutor: runtime.connectorExecutor,
         registry: runtime.registry,
+        restoreSnapshotStore: runtime.restoreSnapshotStore,
     });
     const commands = createCliCommands({
         readModels: runtime.readModels,

package/runtime/cli/ops/manual-run-dispatcher.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ManualRunDispatcher — T-ROS.C.3 (DR-038)
+ *
+ * Core logic: Isolated entry points for manual connector execution, wet probe,
+ * and heartbeat probe. All paths enforce:
+ *   - triggerSource: "manual_run" on downstream records
+ *   - affectsHeartbeatCadence: false (does not advance cron cadence)
+ *
+ * Writes are serialized through the same WriteQueue as cron heartbeat,
+ * preventing concurrent DB conflicts without blocking either path.
+ *
+ * Dependencies:
+ *   - ConnectorExecutor (from connector-system)
+ *   - ExperienceWriter (from body-tool-system)
+ *   - WetProbeRunner (from connector-system)
+ *   - heartbeatCheck (from heartbeat-surface)
+ *
+ * Boundary:
+ *   - Does NOT implement connector adapters; delegates to ConnectorExecutor.
+ *   - Does NOT persist raw payloads; redacted samples only.
+ *   - Caller provides all ports; no module-scope state.
+ *
+ * Test coverage: tests/unit/ops/manual-run-dispatcher.test.ts
+ */
+import type { ConnectorExecutor, ConnectorResult } from "../../connectors/base/contract.js";
+import type { ExperienceWriter } from "../../core/second-nature/body/tool-experience/experience-writer.js";
+import type { WetProbeRunner } from "../../connectors/base/wet-probe-runner.js";
+import type { CapabilityContractRegistryV7 } from "../../connectors/base/manifest-v7.js";
+import { type HeartbeatCheckInput, type HeartbeatSurfaceResult } from "./heartbeat-surface.js";
+import type { RuntimeOpsEnvelope } from "./ops-router.js";
+export interface ManualTriggerContext {
+    triggerSource: "manual_run";
+    affectsHeartbeatCadence: false;
+    caller?: string;
+    reason?: string;
+}
+export interface ConnectorRunInput {
+    platformId: string;
+    capabilityId: string;
+    payload?: Record<string, unknown>;
+    caller?: string;
+    reason?: string;
+}
+export interface ConnectorRunResult {
+    connectorResult: ConnectorResult<unknown>;
+    experienceId: string;
+    triggerSource: "manual_run";
+    affectsHeartbeatCadence: false;
+}
+export interface WetProbeRunInput {
+    platformId: string;
+    capabilityId: string;
+}
+export interface WetProbeManualResult {
+    probeResultId: string;
+    platformId: string;
+    capabilityId: string;
+    actualStatus: string;
+    httpStatus: number;
+    triggerSource: "manual_run";
+    affectsHeartbeatCadence: false;
+}
+export interface HeartbeatProbeInput {
+    deps: HeartbeatCheckInput;
+    caller?: string;
+    reason?: string;
+}
+export interface ManualRunDispatcher {
+    runConnector(input: ConnectorRunInput): Promise<RuntimeOpsEnvelope<ConnectorRunResult>>;
+    runWetProbe(input: WetProbeRunInput): Promise<RuntimeOpsEnvelope<WetProbeManualResult>>;
+    runHeartbeatProbe(input: HeartbeatProbeInput): Promise<HeartbeatSurfaceResult & ManualTriggerContext>;
+}
+export interface ManualRunDispatcherDeps {
+    connectorExecutor: ConnectorExecutor;
+    experienceWriter: ExperienceWriter;
+    wetProbeRunner: WetProbeRunner;
+    registryV7: CapabilityContractRegistryV7;
+}
+export declare function createManualRunDispatcher(deps: ManualRunDispatcherDeps): ManualRunDispatcher;

package/runtime/cli/ops/manual-run-dispatcher.js

@@ -0,0 +1,110 @@
+/**
+ * ManualRunDispatcher — T-ROS.C.3 (DR-038)
+ *
+ * Core logic: Isolated entry points for manual connector execution, wet probe,
+ * and heartbeat probe. All paths enforce:
+ *   - triggerSource: "manual_run" on downstream records
+ *   - affectsHeartbeatCadence: false (does not advance cron cadence)
+ *
+ * Writes are serialized through the same WriteQueue as cron heartbeat,
+ * preventing concurrent DB conflicts without blocking either path.
+ *
+ * Dependencies:
+ *   - ConnectorExecutor (from connector-system)
+ *   - ExperienceWriter (from body-tool-system)
+ *   - WetProbeRunner (from connector-system)
+ *   - heartbeatCheck (from heartbeat-surface)
+ *
+ * Boundary:
+ *   - Does NOT implement connector adapters; delegates to ConnectorExecutor.
+ *   - Does NOT persist raw payloads; redacted samples only.
+ *   - Caller provides all ports; no module-scope state.
+ *
+ * Test coverage: tests/unit/ops/manual-run-dispatcher.test.ts
+ */
+import * as crypto from "node:crypto";
+import { heartbeatCheck, } from "./heartbeat-surface.js";
+function buildManualContext(input) {
+    return {
+        triggerSource: "manual_run",
+        affectsHeartbeatCadence: false,
+        caller: input.caller,
+        reason: input.reason ?? "manual_run_dispatcher",
+    };
+}
+export function createManualRunDispatcher(deps) {
+    return {
+        async runConnector(input) {
+            const ctx = buildManualContext(input);
+            const decisionId = `manual:${crypto.randomUUID()}`;
+            const intentId = `manual-run:${input.platformId}:${input.capabilityId}`;
+            const idempotencyKey = `idem:manual:${crypto.randomUUID()}`;
+            const connectorResult = await deps.connectorExecutor.executeEffect({
+                platformId: input.platformId,
+                intent: input.capabilityId,
+                payload: input.payload ?? {},
+                decisionId,
+                intentId,
+                idempotencyKey,
+            });
+            const experienceId = crypto.randomUUID();
+            await deps.experienceWriter.recordExperience({
+                connectorId: input.platformId,
+                capabilityId: input.capabilityId,
+                result: connectorResult,
+                triggerSource: ctx.triggerSource,
+            });
+            const runResult = {
+                connectorResult,
+                experienceId,
+                triggerSource: ctx.triggerSource,
+                affectsHeartbeatCadence: ctx.affectsHeartbeatCadence,
+            };
+            return {
+                ok: connectorResult.status === "success",
+                command: "connector:run",
+                data: runResult,
+                runtimeMode: "workspace_full_runtime",
+                surfaceMode: "cli",
+                generatedAt: new Date().toISOString(),
+                warnings: [],
+                sourceRefs: ["manual-run-dispatcher:runConnector"],
+            };
+        },
+        async runWetProbe(input) {
+            const ctx = buildManualContext({});
+            // WetProbeRunner requires a CapabilityContractRegistryV7.
+            // In the full runtime this is available via deps.registry; here we
+            // delegate to the caller-provided wetProbeRunner which already has
+            // the registry wired. If the runner is not available, degrade.
+            const wetResult = await deps.wetProbeRunner.runWetProbe(input.platformId, input.capabilityId, deps.registryV7);
+            const result = {
+                probeResultId: wetResult.probeResult.probeResultId,
+                platformId: wetResult.probeResult.connectorId,
+                capabilityId: wetResult.probeResult.capabilityId,
+                actualStatus: wetResult.probeResult.actualStatus,
+                httpStatus: wetResult.httpStatus,
+                triggerSource: ctx.triggerSource,
+                affectsHeartbeatCadence: ctx.affectsHeartbeatCadence,
+            };
+            return {
+                ok: wetResult.probeResult.actualStatus === "available",
+                command: "connector_test",
+                data: result,
+                runtimeMode: "workspace_full_runtime",
+                surfaceMode: "cli",
+                generatedAt: new Date().toISOString(),
+                warnings: [],
+                sourceRefs: ["manual-run-dispatcher:runWetProbe"],
+            };
+        },
+        async runHeartbeatProbe(input) {
+            const ctx = buildManualContext(input);
+            const heartbeatResult = await heartbeatCheck(input.deps);
+            return {
+                ...heartbeatResult,
+                ...ctx,
+            };
+        },
+    };
+}

package/runtime/cli/ops/ops-router.d.ts

@@ -1,6 +1,3 @@
-/**
- * Shared ops command dispatch for CLI + tool surfaces (T1.1.3, T1.2.2).
- */
 import { type HeartbeatCheckInput, type HeartbeatSurfaceResult } from "./heartbeat-surface.js";
 import type { CliReadModels } from "../read-models/index.js";
 import type { RuntimeDecisionRecorder } from "../../observability/services/runtime-decision-recorder.js";
@@ -8,6 +5,27 @@ import type { StateDatabase } from "../../storage/db/index.js";
 import type { ObservabilityDatabase } from "../../observability/db/index.js";
 import type { ConnectorExecutor } from "../../core/second-nature/orchestrator/effect-dispatcher.js";
 import type { DynamicConnectorRegistry } from "../../connectors/registry/index.js";
+import { type HeartbeatDigestAssemblerDeps } from "../../observability/services/heartbeat-digest-assembler.js";
+import { type NarrativeTimelineDeps } from "../../observability/services/narrative-timeline-query-service.js";
+import { type SecretAnchorDeps } from "../../observability/services/runtime-secret-anchor-view.js";
+import { AppendOnlyAuditStore } from "../../observability/audit/append-only-audit-store.js";
+import type { RestoreSnapshotStore } from "../../storage/services/restore-snapshot-store.js";
+/** Unified response envelope for all v7 runtime-ops commands. */
+export interface RuntimeOpsEnvelope<T = unknown> {
+    ok: boolean;
+    command: string;
+    runtimeMode: "host_safe_carrier" | "workspace_full_runtime" | "unavailable";
+    surfaceMode: "cli" | "openclaw_tool" | "plugin_command" | "cron_probe";
+    generatedAt: string;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        nextStep?: string;
+    };
+    warnings: string[];
+    sourceRefs: string[];
+}
 export interface OpsRouterDeps {
     /** When true, packaged runtime artifacts resolved and full graph is loadable */
     runtimeAvailable: boolean;
@@ -35,9 +53,32 @@ export interface OpsRouterDeps {
      * T1.2.3: DynamicConnectorRegistry for connector:status and connector:test commands.
      */
     registry?: DynamicConnectorRegistry;
+    /**
+     * In-memory audit store for heartbeat_digest, restore, and audit commands.
+     * When absent, commands degrade gracefully.
+     */
+    auditStore?: AppendOnlyAuditStore;
+    /**
+     * Deps for heartbeat_digest — includes optional stateMemoryPort and deliveryAdapter.
+     * When absent, only auditStore is used (no state-memory enrichment).
+     */
+    heartbeatDigestDeps?: Omit<HeartbeatDigestAssemblerDeps, "auditStore">;
+    /**
+     * Deps for narrative timeline (narrative:diff, timeline commands).
+     */
+    narrativeTimelineDeps?: NarrativeTimelineDeps;
+    /**
+     * Deps for runtime_secret_bootstrap (key anchor health check).
+     */
+    secretAnchorDeps?: SecretAnchorDeps;
+    /**
+     * T-ROS.C.1: RestoreSnapshotStore for bounded state restoration.
+     * When absent, restore command degrades to audit-only.
+     */
+    restoreSnapshotStore?: RestoreSnapshotStore;
 }
 export interface OpsRouter {
     heartbeatCheck(input: HeartbeatCheckInput): Promise<HeartbeatSurfaceResult>;
-    dispatch(command: string, input?: Record<string, unknown>): Promise<HeartbeatSurfaceResult | Record<string, unknown>>;
+    dispatch(command: string, input?: Record<string, unknown>): Promise<HeartbeatSurfaceResult | Record<string, unknown> | RuntimeOpsEnvelope>;
 }
 export declare function createOpsRouter(deps: OpsRouterDeps): OpsRouter;