@haaaiawd/second-nature 0.2.2 → 0.2.4

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "second-nature",
   "name": "Second Nature",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "OpenClaw native plugin with synchronous surface registration and bundled runtime spine. Set SECOND_NATURE_WORKSPACE_ROOT or tool workspaceRoot to the same path as the agent workspace. Agent inner guide is packaged as agent-inner-guide.md. v7 ops surface: self_health, tool_affordance, heartbeat_digest, snapshot:capture, narrative:diff, timeline, restore, runtime_secret_bootstrap, connector:run, guidance_payload.",
   "activation": {
     "onStartup": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/second-nature",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "OpenClaw native plugin with synchronous registration, a packaged runtime artifact, and operator-facing status/explain flows.",
   "keywords": [
     "openclaw",

package/runtime/cli/ops/heartbeat-surface.d.ts

@@ -19,6 +19,7 @@ import type { GoalLifecyclePolicy } from "../../core/second-nature/heartbeat/goa
 import type { IdleCuriosityPolicy } from "../../core/second-nature/heartbeat/idle-curiosity-policy.js";
 import type { CircuitBreakerManager } from "../../core/second-nature/body/circuit-breaker/circuit-breaker-manager.js";
 import type { AppendOnlyAuditStore } from "../../observability/audit/append-only-audit-store.js";
+import { type RealRuntimeSpineResult } from "../../core/second-nature/control-plane/real-runtime-spine.js";
 export type HeartbeatSurfaceStatus = "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
 export interface HeartbeatSurfaceResult {
     ok: boolean;
@@ -33,6 +34,20 @@ export interface HeartbeatSurfaceResult {
     livedExperienceLoopClaimed: boolean;
     /** True when structured fields mirror a fake adapter for schema parity only */
     schemaParityOnly?: boolean;
+    /** T-CP.R.2: v8 real runtime spine result when state-backed action-closure spine ran */
+    v8Spine?: RealRuntimeSpineResult & {
+        degradedReason?: string;
+    };
+    /** T-GVS.R.1: agent-facing impulse context artifact read pointer */
+    impulseContext?: {
+        available: boolean;
+        sceneType?: string;
+        capabilityClass?: string | null;
+        impulseText?: string | null;
+        atmosphereText?: string | null;
+        freshnessMs?: number;
+        missingReason?: string;
+    };
 }
 export interface HeartbeatCheckInput {
     probeOnly?: boolean;
@@ -83,5 +98,10 @@ export interface HeartbeatCheckInput {
     circuitBreakerManager?: CircuitBreakerManager;
     /** T-OBS.R.1: shared audit sink for connector/Quiet events consumed by heartbeat_digest. */
     auditStore?: AppendOnlyAuditStore;
+    /**
+     * T-CP.R.2: when true and state DB is wired, runs the v8 real runtime action-closure spine
+     * in addition to the v7 heartbeat loop. Produces state-backed closure/no-action records.
+     */
+    v8SpineEnabled?: boolean;
 }
 export declare function heartbeatCheck(input: HeartbeatCheckInput): Promise<HeartbeatSurfaceResult>;

package/runtime/cli/ops/heartbeat-surface.js

@@ -1,4 +1,6 @@
 import { createWorkspaceHeartbeatRunner } from "./workspace-heartbeat-runner.js";
+// T-CP.R.2: v8 real runtime spine bridge
+import { runRealRuntimeHeartbeatCycle, } from "../../core/second-nature/control-plane/real-runtime-spine.js";
 function mapCycleToSurface(cycle, surfaceMode) {
     const status = cycle.status === "runtime_carrier_only"
         ? "runtime_carrier_only"
@@ -86,7 +88,76 @@ export async function heartbeatCheck(input) {
     });
     try {
         const cycle = await run(signal);
-        return mapCycleToSurface(cycle, "workspace_full_runtime");
+        const surfaceResult = mapCycleToSurface(cycle, "workspace_full_runtime");
+        // T-CP.R.2: run v8 real runtime spine when enabled and state is available
+        if (input.v8SpineEnabled && input.state && input.workspaceRoot) {
+            try {
+                const v8Result = await runRealRuntimeHeartbeatCycle({
+                    workspaceRoot: input.workspaceRoot,
+                    state: input.state,
+                    requestedAt: timestamp,
+                    trigger: "host",
+                });
+                if ("status" in v8Result && v8Result.status === "degraded") {
+                    surfaceResult.v8Spine = {
+                        cycleId: "",
+                        cycleSequence: 0,
+                        degradedReason: v8Result.reason,
+                    };
+                    surfaceResult.reasons = [
+                        ...surfaceResult.reasons,
+                        `v8_spine_degraded:${v8Result.reason}`,
+                    ];
+                }
+                else {
+                    const spine = v8Result;
+                    surfaceResult.v8Spine = spine;
+                    surfaceResult.reasons = [
+                        ...surfaceResult.reasons,
+                        `v8_spine_cycle:${spine.cycleId}`,
+                        spine.closureRef
+                            ? "v8_closure_recorded"
+                            : `v8_no_action:${spine.noActionReason ?? "unknown"}`,
+                    ];
+                }
+            }
+            catch (v8Err) {
+                const v8Msg = v8Err instanceof Error ? v8Err.message : String(v8Err);
+                surfaceResult.reasons = [
+                    ...surfaceResult.reasons,
+                    `v8_spine_exception:${v8Msg.slice(0, 120)}`,
+                ];
+            }
+        }
+        // T-GVS.R.1: expose impulse context artifact when state is available
+        if (input.state) {
+            try {
+                const { readImpulseContext } = await import("../../core/second-nature/guidance/impulse-context-reader.js");
+                const ctx = await readImpulseContext(input.state, "social");
+                if (ctx.available) {
+                    surfaceResult.impulseContext = {
+                        available: true,
+                        sceneType: ctx.artifact.sceneType,
+                        capabilityClass: ctx.artifact.capabilityClass,
+                        impulseText: ctx.artifact.impulseText,
+                        atmosphereText: ctx.artifact.atmosphereText,
+                        freshnessMs: ctx.freshnessMs,
+                    };
+                    surfaceResult.reasons.push(`impulse_context:${ctx.artifact.id}`);
+                }
+                else {
+                    surfaceResult.impulseContext = {
+                        available: false,
+                        missingReason: ctx.reason,
+                    };
+                    surfaceResult.reasons.push(`impulse_context_missing:${ctx.reason}`);
+                }
+            }
+            catch {
+                // Non-fatal: impulse context is advisory
+            }
+        }
+        return surfaceResult;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

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

@@ -28,6 +28,7 @@ import { writeRestoreAudit, } from "../../observability/services/restore-audit-s
 import { createHistoryDigestStore } from "../../storage/services/history-digest-store.js";
 // v8 T-ROS.C.1: loop_status read model
 import { readLoopStatus } from "../../observability/loop-status.js";
+import { checkRealRunHealth } from "../../observability/living-loop-health-gate.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";
@@ -445,6 +446,8 @@ export function createOpsRouter(deps) {
                         goalLifecyclePolicy,
                         idleCuriosityPolicy,
                         circuitBreakerManager,
+                        v8SpineEnabled: input
+                            ?.v8SpineEnabled ?? (deps.state !== undefined),
                     });
                     if (result.ok &&
                         result.surfaceMode === "workspace_full_runtime" &&
@@ -1053,6 +1056,33 @@ export function createOpsRouter(deps) {
                         ...deps.heartbeatDigestDeps,
                     };
                     const digest = await generateHeartbeatDigest(date, digestDeps);
+                    // T-OBS.R.3: Embed real-run health into digest when state DB is available
+                    if (deps.state) {
+                        const realRunResult = await checkRealRunHealth(deps.state, date);
+                        if (realRunResult.ok) {
+                            digest.realRunHealth = {
+                                gatePassed: realRunResult.gate.gatePassed,
+                                contractSmokeOnly: realRunResult.gate.contractSmokeOnly,
+                                seededStateDetected: realRunResult.gate.seededStateDetected,
+                                hasRealClosure: realRunResult.gate.hasRealClosure,
+                                hasQuietArtifact: realRunResult.gate.hasQuietArtifact,
+                                hasDreamArtifact: realRunResult.gate.hasDreamArtifact,
+                                missingStage: realRunResult.gate.missingStage,
+                                missingReason: realRunResult.gate.missingReason,
+                            };
+                        }
+                        else {
+                            digest.realRunHealth = {
+                                gatePassed: false,
+                                contractSmokeOnly: false,
+                                seededStateDetected: false,
+                                hasRealClosure: false,
+                                hasQuietArtifact: false,
+                                hasDreamArtifact: false,
+                                missingReason: "Real-run health check degraded: " + realRunResult.degraded.reason,
+                            };
+                        }
+                    }
                     const envelope = {
                         ok: true,
                         command: "heartbeat_digest",
@@ -1472,14 +1502,12 @@ export function createOpsRouter(deps) {
                     return envelope;
                 }
             }
-            // ─── T-V7C.C.4R: guidance_payload ──────────────────────────────────────
+            // ─── T-V7C.C.4R + T-GVS.R.1: guidance_payload ─────────────────────────
             // Returns the assembled impulse + atmosphere for a given scene context.
-            // Useful for Claw to inspect what guidance content would be injected before
-            // a real heartbeat cycle, and to verify platform-specific impulse overrides.
+            // When state DB is wired, reads persisted artifact first; falls back to
+            // real-time assembly and persists for subsequent reads.
             if (command === "guidance_payload") {
                 const generatedAt = new Date().toISOString();
-                const { assembleImpulseSync } = await import("../../guidance/impulse-assembler.js");
-                const { getBaselineAtmosphereTemplate } = await import("../../guidance/template-registry.js");
                 const sceneType = input?.sceneType ?? "social";
                 const capabilityIntent = typeof input?.capabilityIntent === "string"
                     ? input.capabilityIntent
@@ -1505,22 +1533,53 @@ export function createOpsRouter(deps) {
                     };
                     return envelope;
                 }
-                const impulseResult = assembleImpulseSync({
-                    sceneType: sceneType,
-                    capabilityIntent,
-                    platformId,
-                });
-                const { buildExpressionBoundary } = await import("../../guidance/output-guard.js");
-                const { getShortAtmosphereTemplate } = await import("../../guidance/template-registry.js");
-                const atmosphere = getShortAtmosphereTemplate("active", "low");
-                const expressionBoundary = buildExpressionBoundary(sceneType);
-                const envelope = {
-                    ok: true,
-                    command: "guidance_payload",
-                    runtimeMode: deps.runtimeAvailable ? "workspace_full_runtime" : "host_safe_carrier",
-                    surfaceMode: "cli",
-                    generatedAt,
-                    data: {
+                // T-GVS.R.1: Try reading persisted artifact first
+                let artifactData;
+                let warnings = [];
+                let sourceRefs = [
+                    "guidance/capability-class.ts",
+                    "guidance/impulse-assembler.ts",
+                    "guidance/template-registry.ts",
+                    "guidance/output-guard.ts",
+                ];
+                if (deps.state) {
+                    try {
+                        const { readImpulseContext } = await import("../../core/second-nature/guidance/impulse-context-reader.js");
+                        const existing = await readImpulseContext(deps.state, sceneType, capabilityIntent, platformId);
+                        if (existing.available) {
+                            artifactData = {
+                                sceneType: existing.artifact.sceneType,
+                                capabilityIntent: existing.artifact.capabilityIntent,
+                                platformId: existing.artifact.platformId,
+                                capabilityClass: existing.artifact.capabilityClass,
+                                impulseSource: existing.artifact.impulseSource,
+                                impulseText: existing.artifact.impulseText,
+                                atmosphereText: existing.artifact.atmosphereText,
+                                expressionBoundaryConstraints: existing.artifact.expressionBoundaryConstraints,
+                                expressionBoundaryStyle: existing.artifact.expressionBoundaryStyle,
+                                freshnessMs: existing.freshnessMs,
+                                persisted: true,
+                            };
+                            sourceRefs.push("core/second-nature/guidance/impulse-context-reader.ts");
+                        }
+                    }
+                    catch {
+                        // Reader failure → fall through to assembly
+                    }
+                }
+                // Real-time assembly if no persisted artifact
+                if (!artifactData) {
+                    const { assembleImpulseSync } = await import("../../guidance/impulse-assembler.js");
+                    const { buildExpressionBoundary } = await import("../../guidance/output-guard.js");
+                    const { getShortAtmosphereTemplate } = await import("../../guidance/template-registry.js");
+                    const impulseResult = assembleImpulseSync({
+                        sceneType: sceneType,
+                        capabilityIntent,
+                        platformId,
+                    });
+                    const atmosphere = getShortAtmosphereTemplate("active", "low");
+                    const expressionBoundary = buildExpressionBoundary(sceneType);
+                    artifactData = {
                         sceneType,
                         capabilityIntent: capabilityIntent ?? null,
                         platformId: platformId ?? null,
@@ -1532,16 +1591,41 @@ export function createOpsRouter(deps) {
                         atmosphereReviewStatus: atmosphere.reviewStatus,
                         expressionBoundaryConstraints: expressionBoundary.constraints,
                         expressionBoundaryStyle: expressionBoundary.style,
-                    },
-                    warnings: impulseResult.source === "none"
-                        ? ["no_impulse_available_for_this_scene_and_capability"]
-                        : [],
-                    sourceRefs: [
-                        "guidance/capability-class.ts",
-                        "guidance/impulse-assembler.ts",
-                        "guidance/template-registry.ts",
-                        "guidance/output-guard.ts",
-                    ],
+                        persisted: false,
+                    };
+                    if (impulseResult.source === "none") {
+                        warnings.push("no_impulse_available_for_this_scene_and_capability");
+                    }
+                    // T-GVS.R.1: Persist assembled artifact for future reads
+                    if (deps.state) {
+                        try {
+                            const { writeImpulseContext } = await import("../../core/second-nature/guidance/impulse-context-writer.js");
+                            await writeImpulseContext(deps.state, {
+                                sceneType,
+                                capabilityIntent,
+                                platformId,
+                                impulseResult,
+                                atmosphereText: atmosphere.text,
+                                expressionBoundaryConstraints: expressionBoundary.constraints,
+                                expressionBoundaryStyle: expressionBoundary.style,
+                            }, { now: generatedAt });
+                            sourceRefs.push("core/second-nature/guidance/impulse-context-writer.ts");
+                        }
+                        catch {
+                            // Persistence failure is non-fatal; surface still returns assembled payload
+                            warnings.push("impulse_context_persistence_failed");
+                        }
+                    }
+                }
+                const envelope = {
+                    ok: true,
+                    command: "guidance_payload",
+                    runtimeMode: deps.runtimeAvailable ? "workspace_full_runtime" : "host_safe_carrier",
+                    surfaceMode: "cli",
+                    generatedAt,
+                    data: artifactData,
+                    warnings,
+                    sourceRefs,
                 };
                 return envelope;
             }

package/runtime/connectors/base/contract.d.ts

@@ -12,6 +12,14 @@ export interface ConnectorRequestIdentity {
     /** Canonical name across all platforms. */
     canonicalName?: string;
 }
+export interface PolicyProof {
+    decisionId: string;
+    decision: "allow" | "defer" | "downgrade" | "deny";
+    ownerConfirmMode?: boolean;
+    ownerConfirmed?: boolean;
+    dryRun?: boolean;
+    reason?: string;
+}
 export interface ConnectorRequest {
     platformId: string;
     intent: CapabilityIntent;
@@ -23,6 +31,8 @@ export interface ConnectorRequest {
     intentId?: string;
     /** T-V7C.C.4: identity for connector request (readable, no credential). */
     identity?: ConnectorRequestIdentity;
+    /** T-CS.R.1: policy proof for write-side actions */
+    policyProof?: PolicyProof;
 }
 export interface ExecutionPlan {
     platformId: string;

package/runtime/connectors/base/policy-bound-write-dispatch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PolicyBoundWriteDispatch — Write-side connector dispatch with policy proof gate.
+ *
+ * Core logic: Verify policy proof before external write; reject without platform
+ * call when proof is missing, deny, or lacks owner confirmation for high-risk
+ * actions. Support dry-run mode for safe testing.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/connector-system.md §2`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.3`
+ * - `docs/validation/openclaw-plugin-classification.md §5`
+ *
+ * Dependencies:
+ * - `src/connectors/base/contract.js` (ConnectorRequest, ConnectorResult, PolicyProof)
+ * - `src/connectors/base/policy-layer.js` (createConnectorPolicyLayer)
+ *
+ * Boundary:
+ * - Does NOT bypass ActionPolicyDecision.
+ * - Does NOT execute write without valid policy proof.
+ * - Does NOT leak credentials in returned results.
+ */
+import type { ConnectorRequest, ConnectorResult } from "./contract.js";
+export interface WriteDispatchResult {
+    status: "allowed" | "denied" | "deferred" | "dry_run" | "downgraded";
+    reason: string;
+    connectorResult?: ConnectorResult<unknown>;
+    simulatedPayload?: Record<string, unknown>;
+}
+export declare function dispatchPolicyBoundWrite(request: ConnectorRequest, executeConnector: (req: ConnectorRequest) => Promise<ConnectorResult<unknown>>): Promise<WriteDispatchResult>;

package/runtime/connectors/base/policy-bound-write-dispatch.js

@@ -0,0 +1,127 @@
+/**
+ * PolicyBoundWriteDispatch — Write-side connector dispatch with policy proof gate.
+ *
+ * Core logic: Verify policy proof before external write; reject without platform
+ * call when proof is missing, deny, or lacks owner confirmation for high-risk
+ * actions. Support dry-run mode for safe testing.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/connector-system.md §2`
+ * - `.anws/v8/04_SYSTEM_DESIGN/action-closure-policy-system.detail.md §3.3`
+ * - `docs/validation/openclaw-plugin-classification.md §5`
+ *
+ * Dependencies:
+ * - `src/connectors/base/contract.js` (ConnectorRequest, ConnectorResult, PolicyProof)
+ * - `src/connectors/base/policy-layer.js` (createConnectorPolicyLayer)
+ *
+ * Boundary:
+ * - Does NOT bypass ActionPolicyDecision.
+ * - Does NOT execute write without valid policy proof.
+ * - Does NOT leak credentials in returned results.
+ */
+// ───────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────
+function isWriteCapability(intent) {
+    const writeIntents = ["post.publish", "comment.reply", "message.send"];
+    return writeIntents.includes(intent);
+}
+function validatePolicyProof(proof, intent) {
+    if (!proof) {
+        return {
+            valid: false,
+            reason: "policy_denied_missing_permission",
+        };
+    }
+    if (proof.decision === "deny") {
+        return {
+            valid: false,
+            reason: proof.reason || "policy_denied_high_risk",
+        };
+    }
+    if (proof.decision === "defer") {
+        return {
+            valid: false,
+            reason: "policy_deferred_owner_confirmation",
+        };
+    }
+    if (proof.decision === "downgrade") {
+        return {
+            valid: false,
+            reason: proof.reason || "policy_downgraded_to_draft",
+        };
+    }
+    // Allow decision
+    if (proof.decision !== "allow") {
+        return {
+            valid: false,
+            reason: "policy_denied_missing_permission",
+        };
+    }
+    // For write capabilities, require owner-confirm, dry-run, or explicit owner-confirmed flag
+    if (isWriteCapability(intent) &&
+        !proof.ownerConfirmMode &&
+        !proof.dryRun &&
+        !proof.ownerConfirmed) {
+        return {
+            valid: false,
+            reason: "policy_denied_owner_confirm_required",
+        };
+    }
+    return { valid: true, reason: "policy_allowed" };
+}
+// ───────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────
+export async function dispatchPolicyBoundWrite(request, executeConnector) {
+    const { intent, policyProof, payload } = request;
+    // Only gate write capabilities
+    if (!isWriteCapability(intent)) {
+        // Read capabilities pass through to normal execution
+        const result = await executeConnector(request);
+        return {
+            status: "allowed",
+            reason: "read_capability_no_policy_gate",
+            connectorResult: result,
+        };
+    }
+    // Validate policy proof
+    const validation = validatePolicyProof(policyProof, intent);
+    if (!validation.valid) {
+        return {
+            status: validation.reason === "policy_deferred_owner_confirmation"
+                ? "deferred"
+                : "denied",
+            reason: validation.reason,
+        };
+    }
+    // Dry-run mode: simulate execution without platform call
+    if (policyProof?.dryRun) {
+        return {
+            status: "dry_run",
+            reason: "dry_run_simulated_success",
+            simulatedPayload: {
+                ...payload,
+                _simulated: true,
+                _idempotencyKey: request.idempotencyKey,
+                _decisionId: policyProof.decisionId,
+            },
+        };
+    }
+    // Owner-confirm mode without explicit approval: defer to owner approval
+    if (policyProof?.ownerConfirmMode && !policyProof?.ownerConfirmed) {
+        return {
+            status: "deferred",
+            reason: "owner_confirm_pending",
+        };
+    }
+    // Full allow → execute connector
+    const result = await executeConnector(request);
+    return {
+        status: result.status === "success" ? "allowed" : "denied",
+        reason: result.status === "success"
+            ? "execution_completed"
+            : (result.failureClass || "execution_failed"),
+        connectorResult: result,
+    };
+}