@haaaiawd/second-nature 0.2.5 → 0.2.7

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "second-nature",
   "name": "Second Nature",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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.5",
+  "version": "0.2.7",
   "description": "OpenClaw native plugin with synchronous registration, a packaged runtime artifact, and operator-facing status/explain flows.",
   "keywords": [
     "openclaw",

package/runtime/cli/commands/index.d.ts

@@ -1,5 +1,7 @@
 import type { ActionBridge } from "../action-bridge.js";
 import type { OpsRouter } from "../ops/ops-router.js";
+import type { StateDatabase } from "../../storage/db/index.js";
+import type { ObservabilityDatabase } from "../../observability/db/index.js";
 import type { CliReadModels } from "../read-models/index.js";
 export interface CliCommandDefinition {
     name: string;
@@ -10,5 +12,7 @@ export interface CliCommandDeps {
     readModels: CliReadModels;
     actionBridge: ActionBridge;
     opsRouter: OpsRouter;
+    stateDb?: StateDatabase;
+    observabilityDb?: ObservabilityDatabase;
 }
 export declare function createCliCommands(deps: CliCommandDeps): CliCommandDefinition[];

package/runtime/cli/commands/index.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import { credentialVerify } from "./credential.js";
 import { connectorInit } from "./connector-init.js";
 import { formatExplanation } from "../explain/format-explanation.js";
@@ -5,6 +7,139 @@ import { explainSurfaceSubject } from "../explain/explain-surface-subject.js";
 import { showOperatorFallback, OperatorFallbackNotFoundError, } from "../ops/show-operator-fallback.js";
 import { runStorageModeSmoke } from "../../storage/bootstrap/storage-mode-smoke.js";
 import { policySet } from "./policy.js";
+const SETUP_MARKER_RELATIVE_PATH = path.join(".second-nature", "setup", "agent-inner-guide-ack.json");
+function safeShortText(value, maxLen) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.slice(0, maxLen);
+}
+function resolveWorkspaceRoot(input) {
+    if (typeof input?.workspaceRoot === "string" && input.workspaceRoot.trim().length > 0) {
+        return path.resolve(input.workspaceRoot);
+    }
+    if (typeof process.env.SECOND_NATURE_WORKSPACE_ROOT === "string" && process.env.SECOND_NATURE_WORKSPACE_ROOT.trim().length > 0) {
+        return path.resolve(process.env.SECOND_NATURE_WORKSPACE_ROOT);
+    }
+    return process.cwd();
+}
+function readSetupText(fileName) {
+    const candidates = fileName === "SKILL.md"
+        ? [path.resolve(process.cwd(), "SKILL.md"), path.resolve(process.cwd(), "..", "SKILL.md")]
+        : [path.resolve(process.cwd(), "plugin", "agent-inner-guide.md"), path.resolve(process.cwd(), "..", "plugin", "agent-inner-guide.md")];
+    for (const candidate of candidates) {
+        try {
+            const content = fs.readFileSync(candidate, "utf-8");
+            return { ok: true, path: candidate, content };
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return { ok: false, path: candidates[0] ?? fileName, error: `Could not read ${fileName}` };
+}
+function summarizeSetupText(content) {
+    const lines = content.split("\n");
+    const nonEmpty = lines.filter((line) => line.trim().length > 0);
+    const first = nonEmpty.slice(0, 3).join("\n");
+    const marker = content.length > first.length ? "\n\n[...]" : "";
+    return `${first}${marker}`;
+}
+function readSetupAckMarker(workspaceRoot) {
+    const markerPath = path.join(workspaceRoot, SETUP_MARKER_RELATIVE_PATH);
+    try {
+        const raw = fs.readFileSync(markerPath, "utf-8");
+        const marker = JSON.parse(raw);
+        if (marker.status === "acknowledged") {
+            return {
+                status: "acknowledged",
+                markerPath,
+                acknowledgedAt: typeof marker.acknowledgedAt === "string" ? marker.acknowledgedAt : undefined,
+                placedIn: typeof marker.placedIn === "string" ? marker.placedIn : undefined,
+            };
+        }
+    }
+    catch {
+        // marker missing or unreadable
+    }
+    return { status: "pending", markerPath };
+}
+async function buildSetupHintPayload(input) {
+    const format = input?.format === "full" ? "full" : "summary";
+    const includeSkill = input?.includeSkill !== false;
+    const includeGuide = input?.includeGuide !== false;
+    const workspaceRoot = resolveWorkspaceRoot(input);
+    const ack = readSetupAckMarker(workspaceRoot);
+    const data = {
+        status: ack.status,
+        workspaceRoot,
+        markerPath: ack.markerPath,
+        acknowledgedAt: ack.acknowledgedAt,
+        placedIn: ack.placedIn,
+        recommendedPlacement: [
+            "agent prompt",
+            "workspace/IDENTITY.md",
+            "workspace/USER.md",
+        ],
+        nextStep: ack.status === "acknowledged"
+            ? "setup_already_acknowledged"
+            : "read_returned_guidance_then_run_setup_ack",
+    };
+    if (includeSkill) {
+        const skill = readSetupText("SKILL.md");
+        data.skill = skill.ok
+            ? {
+                path: skill.path,
+                content: format === "full" ? skill.content : summarizeSetupText(skill.content),
+            }
+            : skill;
+    }
+    if (includeGuide) {
+        const guide = readSetupText("agent-inner-guide.md");
+        data.guide = guide.ok
+            ? {
+                path: guide.path,
+                content: format === "full" ? guide.content : summarizeSetupText(guide.content),
+            }
+            : guide;
+    }
+    return {
+        ok: true,
+        command: "setup_hint",
+        surfaceMode: "workspace_full_runtime",
+        message: "Read the SKILL and guide as a friendly setup note, then place the guidance where the agent naturally checks its working anchors.",
+        data,
+    };
+}
+async function buildSetupAckPayload(input) {
+    const workspaceRoot = resolveWorkspaceRoot(input);
+    const markerPath = path.join(workspaceRoot, SETUP_MARKER_RELATIVE_PATH);
+    const marker = {
+        acknowledgedAt: new Date().toISOString(),
+        acceptedBy: safeShortText(input?.acceptedBy, 80) ?? "agent",
+        placedIn: safeShortText(input?.placedIn, 160) ?? "unspecified",
+        note: safeShortText(input?.note, 240),
+        guideVersion: "0.2.5",
+        source: "second-nature-cli",
+        skillPath: "SKILL.md",
+        guidePath: "plugin/agent-inner-guide.md",
+        status: "acknowledged",
+    };
+    fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+    fs.writeFileSync(markerPath, `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
+    return {
+        ok: true,
+        command: "setup_ack",
+        surfaceMode: "workspace_full_runtime",
+        message: "Setup guide acknowledgement persisted; setup nudge is now silent for this workspace.",
+        data: {
+            markerPath,
+            ...marker,
+        },
+    };
+}
 const notImplemented = async (command) => ({
     ok: false,
     command,
@@ -22,16 +157,45 @@ function explainSubjectError(code, message) {
     };
 }
 export function createCliCommands(deps) {
-    const { readModels, actionBridge, opsRouter } = deps;
+    const { readModels, actionBridge, opsRouter, stateDb, observabilityDb } = deps;
+    const flush = () => {
+        try {
+            stateDb?.flush();
+        }
+        catch {
+            // ignore flush errors to avoid masking command results
+        }
+        try {
+            observabilityDb?.flush();
+        }
+        catch {
+            // ignore flush errors to avoid masking command results
+        }
+    };
     const opsCommand = (name, description) => ({
         name,
         description,
         execute: async (input) => {
             const surface = await Promise.resolve(opsRouter.dispatch(name, input));
+            flush();
             return surface;
         },
     });
     return [
+        {
+            name: "setup_hint",
+            description: "Return the packaged setup SKILL and agent inner guide for first-run onboarding",
+            execute: async (input) => buildSetupHintPayload(input),
+        },
+        {
+            name: "setup_ack",
+            description: "Persist that the packaged setup guide was read and placed into working anchors",
+            execute: async (input) => {
+                const result = await buildSetupAckPayload(input);
+                flush();
+                return result;
+            },
+        },
         {
             name: "status",
             description: "T1.2.6 — Show v6 aggregated Second Nature status (narrative + dream + cycles + runtime)",
@@ -47,7 +211,9 @@ export function createCliCommands(deps) {
             execute: async (input) => {
                 const action = typeof input?.action === "string" ? input.action : "show";
                 if (action === "set") {
-                    return policySet(actionBridge, input);
+                    const result = await policySet(actionBridge, input);
+                    flush();
+                    return result;
                 }
                 // T1.2.6 (SN-CODE-01): `policy show` (default) returns the current rhythm policy
                 // snapshot. Returns workspace defaults when no policy row has been persisted yet.
@@ -159,6 +325,7 @@ export function createCliCommands(deps) {
             description: "Workspace heartbeat_check ops surface (v5 HeartbeatSurfaceResult)",
             execute: async (input) => {
                 const surface = await Promise.resolve(opsRouter.dispatch("heartbeat_check", input));
+                flush();
                 return surface;
             },
         },
@@ -174,6 +341,7 @@ export function createCliCommands(deps) {
                     runRepairFixture,
                     workspaceRoot,
                 });
+                flush();
                 return { ok: true, data };
             },
         },
@@ -218,6 +386,7 @@ export function createCliCommands(deps) {
             description: "T1.2.8 — probe host capabilities and persist report (static unknown adapter in CLI context)",
             execute: async (input) => {
                 const surface = await Promise.resolve(opsRouter.dispatch("capability_probe", input));
+                flush();
                 return surface;
             },
         },
@@ -226,6 +395,7 @@ export function createCliCommands(deps) {
             description: "T3.3.2 — run near-real connector smoke (sentinel Moltbook + EvoMap, no live HTTP)",
             execute: async (input) => {
                 const surface = await Promise.resolve(opsRouter.dispatch("near_real_smoke", input));
+                flush();
                 return surface;
             },
         },
@@ -249,6 +419,7 @@ export function createCliCommands(deps) {
                         ? input.workspaceRoot
                         : undefined,
                 });
+                flush();
                 return result;
             },
         },
@@ -261,10 +432,11 @@ export function createCliCommands(deps) {
             },
         },
         {
-            name: "connector_status",
-            description: "T1.2.3 — show connector inventory, trust/executable/conflict summary",
+            name: "credential",
+            description: "T1.4.1 — inspect or verify credential health without exposing plaintext",
             execute: async (input) => {
-                const surface = await Promise.resolve(opsRouter.dispatch("connector_status", input));
+                const surface = await Promise.resolve(opsRouter.dispatch("credential", input));
+                flush();
                 return surface;
             },
         },
@@ -273,6 +445,16 @@ export function createCliCommands(deps) {
             description: "T1.2.3 — dry-run test a connector by platformId (default dry-run)",
             execute: async (input) => {
                 const surface = await Promise.resolve(opsRouter.dispatch("connector_test", input));
+                flush();
+                return surface;
+            },
+        },
+        {
+            name: "connector_status",
+            description: "T1.2.5 — show connector inventory status, trust, and health conflicts",
+            execute: async (input) => {
+                const surface = await Promise.resolve(opsRouter.dispatch("connector_status", input));
+                flush();
                 return surface;
             },
         },
@@ -292,6 +474,7 @@ export function createCliCommands(deps) {
             description: "T1.2.4 — owner-governed goal operations: set, list, accept, reject",
             execute: async (input) => {
                 const surface = await Promise.resolve(opsRouter.dispatch("goal", input));
+                flush();
                 return surface;
             },
         },

package/runtime/cli/index.js

@@ -290,6 +290,8 @@ export function createCommandRouter(options = {}) {
         readModels: runtime.readModels,
         actionBridge: runtime.actionBridge,
         opsRouter,
+        stateDb: runtime.stateDb,
+        observabilityDb: runtime.observabilityDb,
     });
     return {
         commands,

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

@@ -1144,24 +1144,30 @@ export function createOpsRouter(deps) {
                     };
                     return envelope;
                 }
-                const fromVersion = typeof input?.from === "string" ? input.from : "";
-                const toVersion = typeof input?.to === "string" ? input.to : "";
+                let fromVersion = typeof input?.from === "string" ? input.from : "";
+                let 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;
+                    // Auto-resolve the two most recent narrative timeline versions when not provided.
+                    const recent = await deps.narrativeTimelineDeps.stateMemoryPort.listNarrativeTimeline(new Date(0).toISOString(), new Date().toISOString(), { limit: 2 });
+                    if (recent.length < 2) {
+                        const envelope = {
+                            ok: false,
+                            command: "narrative:diff",
+                            runtimeMode: "workspace_full_runtime",
+                            surfaceMode: "cli",
+                            generatedAt,
+                            error: {
+                                code: "NARRATIVE_DIFF_REQUIRES_TWO_VERSIONS",
+                                message: `narrative:diff requires at least two timeline versions; found ${recent.length}. Pass explicit 'from' and 'to', or run snapshot:capture twice.`,
+                                nextStep: "run_snapshot_capture_twice_or_pass_from_and_to",
+                            },
+                            warnings: [],
+                            sourceRefs: [],
+                        };
+                        return envelope;
+                    }
+                    fromVersion = recent[1].version;
+                    toVersion = recent[0].version;
                 }
                 try {
                     const diff = await queryNarrativeDiff(fromVersion, toVersion, deps.narrativeTimelineDeps);

package/runtime/connectors/base/normalized-evidence-content.d.ts

@@ -0,0 +1,71 @@
+/**
+ * NormalizedEvidenceContent — Cross-platform content-bearing evidence envelope.
+ *
+ * Core logic: Map arbitrary connector read payloads into a stable, source-backed
+ * summary structure that perception, Quiet, and Dream can consume. This is a
+ * schema boundary, not a judgment layer.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/connector-system.md`
+ * - `.anws/v8/04_SYSTEM_DESIGN/perception-judgment-system.md`
+ *
+ * Dependencies:
+ * - none (pure extraction)
+ *
+ * Boundary:
+ * - Does not classify sensitivity.
+ * - Does not redact; callers run redaction separately.
+ * - Does not persist; callers write EvidenceItem.
+ * - Preserves raw values in canonicalText/excerpt so downstream can decide what to keep.
+ *
+ * Test coverage: tests/unit/connectors/normalized-evidence-content.test.ts
+ */
+export declare const NORMALIZED_EVIDENCE_SCHEMA_VERSION = 1;
+export type EvidenceSourceKind = "post" | "comment" | "profile" | "task" | "event" | "game_state" | "notification" | "document" | "unknown";
+export type SummaryProducer = "connector_rules" | "model_assist" | "operator_supplied";
+export interface EvidenceActor {
+    id?: string;
+    displayName?: string;
+    role?: string;
+}
+export interface NormalizedEvidenceContent {
+    schemaVersion: typeof NORMALIZED_EVIDENCE_SCHEMA_VERSION;
+    sourceKind: EvidenceSourceKind;
+    platformId: string;
+    capabilityId: string;
+    externalId?: string;
+    title?: string;
+    summary: string;
+    excerpt?: string;
+    canonicalText?: string;
+    actor?: EvidenceActor;
+    url?: string;
+    occurredAt?: string;
+    observedAt: string;
+    tags?: string[];
+    entities?: string[];
+    metrics?: Record<string, number | string | boolean>;
+    rawContentRef?: string;
+    summaryProducer: SummaryProducer;
+}
+export interface ExtractEvidenceOptions {
+    platformId: string;
+    capabilityId: string;
+    observedAt?: string;
+    summaryProducer?: SummaryProducer;
+    /** Max characters for excerpt. Default 240. */
+    excerptMaxChars?: number;
+    /** Max characters for canonicalText. Default 2000. */
+    canonicalTextMaxChars?: number;
+}
+/**
+ * Extract a list of content-bearing evidence items from a connector success payload.
+ * Returns empty array when data is not an object/array or contains no extractable items.
+ */
+export declare function extractNormalizedEvidenceItems(data: unknown, options: ExtractEvidenceOptions): NormalizedEvidenceContent[];
+/**
+ * Compute a stable content hash for deduplication across connector runs.
+ * Prefer externalId-based identity; this hash is the fallback.
+ */
+export declare function computeEvidenceContentHash(content: NormalizedEvidenceContent): string;
+export declare function computeEvidenceContentHashSync(content: NormalizedEvidenceContent): string;