@haaaiawd/second-nature 0.1.7 → 0.1.8

package/index.js

@@ -1,27 +1,322 @@
-// @ts-ignore packaged runtime declarations are generated under plugin/runtime
-import { createCliRuntimeDeps, createCommandRouter } from "./runtime/cli/index.js";
-import { DecisionLedger } from "./runtime/observability/services/decision-ledger.js";
-import { ExecutionTelemetry } from "./runtime/observability/services/execution-telemetry.js";
+/**
+ * Host-safe Second Nature plugin surface.
+ *
+ * Core logic:
+ * - keep register(api) synchronous so OpenClaw captures services/command/tool before return
+ * - avoid importing CLI/runtime DB modules at module-evaluation time because the packaged
+ *   runtime graph currently contains async sql.js bootstrap that breaks vm sandbox loading
+ * - expose a minimal in-memory activation spine so status/lifecycle stay truthful even when
+ *   the full workspace runtime is not loaded inside the host
+ *
+ * Dependencies:
+ * - only imports runtime lifecycle/service modules that are synchronous at load time
+ *
+ * Boundaries:
+ * - read-only operator flows stay available through command/tool surface
+ * - structured mutating flows such as policy set / credential verify remain unavailable here
+ * - full evidence-backed workspace runtime can be reintroduced later behind a host-safe boundary
+ *
+ * Test coverage:
+ * - tests/integration/cli/plugin-runtime-registration.test.ts
+ * - tests/integration/cli/plugin-packaging-walkthrough.test.ts
+ */
 import { startRuntimeService, } from "./runtime/core/second-nature/runtime/service-entry.js";
 import { getLifecycleState, recordRegistration, } from "./runtime/core/second-nature/runtime/lifecycle-service.js";
-const INTERNAL_RUNTIME_PLATFORM_ID = "second-nature-runtime";
 const INTERNAL_RUNTIME_TRACE_PREFIX = "sn-runtime-";
-const INTERNAL_RUNTIME_CHANNEL = "plugin_host";
+const HOST_SAFE_LIMITATION_MESSAGE = "Host-safe plugin package keeps synchronous register/load semantics, but mutating workspace runtime flows remain unavailable here.";
 let activationSpine = null;
-function createFallbackCommands() {
-    const commandNames = ["status", "policy", "credential", "quiet", "report", "session", "audit", "explain"];
-    return commandNames.map((name) => ({
-        name,
-        description: `Fallback command shell for ${name}`,
-        execute: async (_input) => ({
+function trimRuntimeEvidence(spine) {
+    if (spine.runtimeEvidence.length > 12) {
+        spine.runtimeEvidence.splice(0, spine.runtimeEvidence.length - 12);
+    }
+}
+function latestRuntimeEvidence(spine) {
+    return spine.runtimeEvidence[spine.runtimeEvidence.length - 1];
+}
+function createUnavailableActionError(code, message, requiredUserInput, nextStep) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message,
+            requiredUserInput,
+            nextStep,
+        },
+        message: HOST_SAFE_LIMITATION_MESSAGE,
+    };
+}
+function parseExplainSubject(subjectRaw) {
+    const trimmed = subjectRaw.trim();
+    if (!trimmed) {
+        throw new Error("explain_subject_invalid");
+    }
+    const separatorIndex = trimmed.indexOf(":");
+    if (separatorIndex === -1) {
+        throw new Error("explain_subject_requires_id");
+    }
+    const kind = trimmed.slice(0, separatorIndex).trim();
+    const id = trimmed.slice(separatorIndex + 1).trim();
+    if (!id) {
+        throw new Error("explain_subject_requires_id");
+    }
+    switch (kind) {
+        case "decision":
+            return { subjectType: "decision", subjectId: id };
+        case "platform":
+        case "platform-selection":
+            return { subjectType: "platform-selection", subjectId: id };
+        case "outreach":
+            return { subjectType: "outreach", subjectId: id };
+        case "soul":
+        case "soul-change":
+            return { subjectType: "soul-change", subjectId: id };
+        default:
+            throw new Error("explain_subject_unsupported");
+    }
+}
+function buildStatusPayload(spine) {
+    const runtimeEvidence = latestRuntimeEvidence(spine);
+    const updatedAt = runtimeEvidence?.createdAt ?? new Date(spine.lifecycleState.lastChangedAt).toISOString();
+    return {
+        ok: true,
+        data: {
+            runtime: {
+                host: "openclaw-plugin",
+                serviceStatus: spine.runtimeHandle.ready ? "running" : "idle",
+                updatedAt,
+            },
+            rhythm: {
+                mode: "active",
+                windowId: undefined,
+            },
+            quiet: {
+                mode: "unknown",
+                lastEvent: runtimeEvidence?.traceId,
+                interrupted: undefined,
+            },
+            connectors: [],
+            credentials: [],
+            risk: {
+                level: "low",
+                flags: [],
+            },
+        },
+    };
+}
+function buildQuietPayload(scope) {
+    return {
+        ok: true,
+        data: {
+            scope,
+            mode: "unknown",
+            sourceCount: 0,
+            reportCount: 0,
+            recentJournalCount: 0,
+        },
+    };
+}
+function buildReportPayload(day) {
+    return {
+        ok: true,
+        data: {
+            day: day && day.trim() ? day : new Date().toISOString().slice(0, 10),
+            summary: "",
+            highlights: [],
+            sourceRefs: [],
+        },
+    };
+}
+function buildSessionPayload(sessionId) {
+    if (!sessionId) {
+        return {
             ok: false,
-            command: name,
-            message: "Plugin loaded in packaging fallback mode; reinstall full workspace build for command runtime.",
-        }),
-    }));
+            error: {
+                code: "MISSING_SESSION_ID",
+                message: "session show requires sessionId",
+                requiredUserInput: ["session_id"],
+                nextStep: "reinvoke_session_with_session_id",
+            },
+        };
+    }
+    return {
+        ok: true,
+        data: {
+            requestedSessionId: sessionId,
+            traceId: sessionId,
+            decisionCount: 0,
+            attemptCount: 0,
+            governanceCount: 0,
+            keyFactors: [],
+            evidenceRefs: [],
+        },
+    };
 }
-function createFallbackRouter() {
-    const commands = createFallbackCommands();
+function buildCredentialPayload(platformId) {
+    return {
+        ok: true,
+        data: {
+            platformId: platformId && platformId.trim() ? platformId : "unknown",
+            status: "missing",
+            nextStep: "provide_credential_context",
+        },
+    };
+}
+function buildExplainPayload(spine, subjectRaw) {
+    if (!subjectRaw?.trim()) {
+        return {
+            ok: false,
+            error: {
+                code: "MISSING_EXPLAIN_SUBJECT",
+                message: "explain requires subject",
+                requiredUserInput: ["subject"],
+                nextStep: "reinvoke_explain_with_subject",
+            },
+        };
+    }
+    let subject;
+    try {
+        subject = parseExplainSubject(subjectRaw);
+    }
+    catch (error) {
+        const code = error.message;
+        if (code === "explain_subject_requires_id") {
+            return createUnavailableActionError("EXPLAIN_SUBJECT_REQUIRES_ID", "subject must include identifier", ["subject"], "reinvoke_explain_with_supported_subject");
+        }
+        if (code === "explain_subject_unsupported") {
+            return createUnavailableActionError("EXPLAIN_SUBJECT_UNSUPPORTED", "supported subjects are decision:<id>, platform:<id>, outreach:<id>, soul:<id>", ["subject"], "reinvoke_explain_with_supported_subject");
+        }
+        return createUnavailableActionError("EXPLAIN_SUBJECT_INVALID", "invalid explain subject", ["subject"], "reinvoke_explain_with_supported_subject");
+    }
+    const runtimeEvidence = latestRuntimeEvidence(spine);
+    return {
+        ok: true,
+        data: {
+            subjectType: subject.subjectType,
+            conclusion: "Plugin surface is loaded in host-safe mode with a minimal activation spine.",
+            keyFactors: [
+                "synchronous_register",
+                `subject:${subject.subjectId}`,
+                runtimeEvidence?.capability ?? "runtime.activate",
+            ],
+            evidenceRefs: [
+                runtimeEvidence?.traceId ?? `${INTERNAL_RUNTIME_TRACE_PREFIX}none`,
+                `subject:${subjectRaw.trim()}`,
+                "host_safe_mode",
+            ],
+            nextStep: "use full workspace runtime for evidence-backed explain details",
+        },
+    };
+}
+function buildHeartbeatCheckPayload(spine, input) {
+    const runtimeEvidence = latestRuntimeEvidence(spine);
+    const updatedAt = runtimeEvidence?.createdAt ?? new Date(spine.lifecycleState.lastChangedAt).toISOString();
+    const timestamp = typeof input?.timestamp === "string" && input.timestamp.trim().length > 0 ? input.timestamp : updatedAt;
+    return {
+        ok: true,
+        status: "heartbeat_ok",
+        heartbeat: "HEARTBEAT_OK",
+        scope: "rhythm",
+        trigger: "heartbeat_bridge",
+        reasons: ["host_safe_bridge_ready"],
+        nextAction: "continue",
+        message: "Host-safe heartbeat bridge acknowledged the round. No additional action is required from this surface.",
+        data: {
+            runtime: {
+                host: "openclaw-plugin",
+                serviceStatus: spine.runtimeHandle.ready ? "running" : "idle",
+                updatedAt,
+            },
+            surface: {
+                tool: "second_nature_ops",
+                command: "second-nature heartbeat_check",
+            },
+            bridge: {
+                timestamp,
+                sessionContextProvided: typeof input?.sessionContext === "string" && input.sessionContext.trim().length > 0,
+                heartbeatChecklistProvided: typeof input?.heartbeatChecklist === "string" && input.heartbeatChecklist.trim().length > 0,
+                serviceEntryMode: "runtime_carrier_only",
+            },
+        },
+    };
+}
+function createHostSafeRouter(spine) {
+    const notImplemented = async (command) => ({
+        ok: false,
+        command,
+        message: HOST_SAFE_LIMITATION_MESSAGE,
+    });
+    const commands = [
+        {
+            name: "status",
+            description: "Show aggregated Second Nature status",
+            execute: async () => buildStatusPayload(spine),
+        },
+        {
+            name: "policy",
+            description: "Write or inspect policy state",
+            execute: async (input) => {
+                const action = typeof input?.action === "string" ? input.action : "show";
+                if (action === "set") {
+                    return createUnavailableActionError("HOST_SAFE_POLICY_SET_UNAVAILABLE", "policy set is unavailable in the host-safe plugin package", ["social_daily_limit", "quiet_enabled"], "run_workspace_runtime_or_reinstall_full_build");
+                }
+                return notImplemented("policy");
+            },
+        },
+        {
+            name: "credential",
+            description: "Inspect or recover credential state",
+            execute: async (input) => {
+                const action = typeof input?.action === "string" ? input.action : "show";
+                if (action === "verify") {
+                    return createUnavailableActionError("HOST_SAFE_CREDENTIAL_VERIFY_UNAVAILABLE", "credential verify is unavailable in the host-safe plugin package", ["verification_answer"], "run_workspace_runtime_or_reinstall_full_build");
+                }
+                const platformId = typeof input?.platformId === "string" ? input.platformId : undefined;
+                return buildCredentialPayload(platformId);
+            },
+        },
+        {
+            name: "quiet",
+            description: "Inspect Quiet lifecycle state",
+            execute: async (input) => {
+                const scope = typeof input?.scope === "string" ? input.scope : undefined;
+                return buildQuietPayload(scope);
+            },
+        },
+        {
+            name: "report",
+            description: "Show daily report artifacts",
+            execute: async (input) => {
+                const day = typeof input?.day === "string" ? input.day : undefined;
+                return buildReportPayload(day);
+            },
+        },
+        {
+            name: "session",
+            description: "Inspect continuity session details",
+            execute: async (input) => {
+                const sessionId = typeof input?.sessionId === "string" ? input.sessionId : undefined;
+                return buildSessionPayload(sessionId);
+            },
+        },
+        {
+            name: "audit",
+            description: "Inspect audit and evidence views",
+            execute: async () => notImplemented("audit"),
+        },
+        {
+            name: "explain",
+            description: "Answer why-question explain requests",
+            execute: async (input) => {
+                const subject = typeof input?.subject === "string" ? input.subject : undefined;
+                return buildExplainPayload(spine, subject);
+            },
+        },
+        {
+            name: "heartbeat_check",
+            description: "Acknowledge the shipping heartbeat bridge round",
+            execute: async (input) => buildHeartbeatCheckPayload(spine, input),
+        },
+    ];
     return {
         commands,
         resolve(name) {
@@ -29,33 +324,43 @@ function createFallbackRouter() {
         },
     };
 }
+function createActivationSpine() {
+    const spine = {
+        router: undefined,
+        runtimeHandle: startRuntimeService({ workspaceRoot: process.cwd() }),
+        lifecycleState: getLifecycleState(),
+        serviceStartRecorded: false,
+        runtimeEvidence: [],
+    };
+    spine.router = createHostSafeRouter(spine);
+    return spine;
+}
 function ensureActivationSpine() {
     if (activationSpine) {
         return activationSpine;
     }
-    try {
-        const runtimeDeps = createCliRuntimeDeps();
-        const router = createCommandRouter({ deps: runtimeDeps });
-        activationSpine = {
-            runtimeDeps,
-            router,
-            decisionLedger: new DecisionLedger(runtimeDeps.observabilityDb),
-            executionTelemetry: new ExecutionTelemetry(runtimeDeps.observabilityDb),
-            runtimeHandle: startRuntimeService({ workspaceRoot: process.cwd() }),
-            lifecycleState: getLifecycleState(),
-            serviceStartRecorded: false,
-        };
-        return activationSpine;
+    activationSpine = createActivationSpine();
+    return activationSpine;
+}
+function recordRuntimeEvidence(spine, origin) {
+    if (origin === "service_start" && spine.serviceStartRecorded) {
+        return;
     }
-    catch {
-        activationSpine = {
-            router: createFallbackRouter(),
-            runtimeHandle: { ready: true, version: "0.1.7-minimal", close() { } },
-            lifecycleState: getLifecycleState(),
-            serviceStartRecorded: false,
-        };
-        return activationSpine;
+    if (origin === "service_start") {
+        spine.serviceStartRecorded = true;
     }
+    spine.runtimeEvidence.push({
+        traceId: `${INTERNAL_RUNTIME_TRACE_PREFIX}${origin}-${spine.lifecycleState.registerCount}-${Date.now()}`,
+        capability: origin === "register"
+            ? spine.lifecycleState.registerCount === 1
+                ? "runtime.activate"
+                : "runtime.reload"
+            : "runtime.heartbeat",
+        origin,
+        createdAt: new Date().toISOString(),
+        status: "succeeded",
+    });
+    trimRuntimeEvidence(spine);
 }
 function refreshRegistrationState() {
     const spine = ensureActivationSpine();
@@ -65,62 +370,6 @@ function refreshRegistrationState() {
     recordRuntimeEvidence(spine, "register");
     return spine;
 }
-function recordRuntimeEvidence(spine, origin) {
-    const decisionLedger = spine.decisionLedger;
-    const executionTelemetry = spine.executionTelemetry;
-    if (!decisionLedger || !executionTelemetry) {
-        return;
-    }
-    if (origin === "service_start" && spine.serviceStartRecorded) {
-        return;
-    }
-    if (origin === "service_start") {
-        spine.serviceStartRecorded = true;
-    }
-    const now = new Date().toISOString();
-    const traceId = `${INTERNAL_RUNTIME_TRACE_PREFIX}${origin}-${spine.lifecycleState.registerCount}-${Date.now()}`;
-    const decisionId = `decision-${traceId}`;
-    const tickId = `tick-${traceId}`;
-    const intentId = `intent-${traceId}`;
-    const capability = origin === "register"
-        ? spine.lifecycleState.registerCount === 1
-            ? "runtime.activate"
-            : "runtime.reload"
-        : "runtime.heartbeat";
-    void (async () => {
-        await decisionLedger.recordHeartbeatDecision({
-            id: decisionId,
-            tickId,
-            traceId,
-            intentId,
-            runtimeScope: "rhythm",
-            triggerSource: "heartbeat_bridge",
-            decisionStatus: "heartbeat_ok",
-            reasons: [
-                `origin:${origin}`,
-                `phase:${spine.lifecycleState.phase}`,
-                `registrations:${spine.lifecycleState.registerCount}`,
-            ],
-            mode: "active",
-            createdAt: now,
-        });
-        await executionTelemetry.startAttempt({
-            traceId,
-            decisionId,
-            intentId,
-            platformId: INTERNAL_RUNTIME_PLATFORM_ID,
-            capability,
-            channel: INTERNAL_RUNTIME_CHANNEL,
-            status: "started",
-            startedAt: now,
-        });
-        await executionTelemetry.completeAttempt(traceId, "succeeded", "committed");
-    })().catch(() => {
-        if (origin === "service_start") {
-            spine.serviceStartRecorded = false;
-        }
-    });
-}
 function parseCommandInput(rawArgs) {
     const tokens = rawArgs?.trim().split(/\s+/).filter(Boolean) ?? [];
     if (tokens.length === 0) {
@@ -176,6 +425,17 @@ function parseCommandInput(rawArgs) {
                 command,
                 input: rest[0] ? { platformId: rest[0] } : undefined,
             };
+        case "heartbeat_check":
+            return {
+                ok: true,
+                command,
+                input: rest.length > 0
+                    ? {
+                        timestamp: rest[0],
+                        sessionContext: rest.length > 1 ? rest.slice(1).join(" ") : undefined,
+                    }
+                    : undefined,
+            };
         case "explain":
             return {
                 ok: true,
@@ -221,7 +481,6 @@ export default {
     name: "Second Nature",
     description: "Registers command/tool/service surface with load-reload lifecycle semantics.",
     register(api) {
-        const spine = refreshRegistrationState();
         const runtimeService = createRuntimeService();
         const lifecycleService = createLifecycleService();
         api.registerService(runtimeService);
@@ -231,6 +490,7 @@ export default {
             description: "Route Agent-facing operational commands for Second Nature.",
             acceptsArgs: true,
             handler: async (ctx) => {
+                const spine = ensureActivationSpine();
                 const parsed = parseCommandInput(ctx.args);
                 if (!parsed.ok) {
                     return {
@@ -262,6 +522,7 @@ export default {
                 required: ["command"],
             },
             async execute(_id, params) {
+                const spine = ensureActivationSpine();
                 const resolved = spine.router.resolve(params.command);
                 if (!resolved) {
                     return {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "second-nature",
   "name": "Second Nature",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "entry": "./index.js",
   "description": "OpenClaw native plugin package with synchronous surface registration and a bundled runtime spine.",
   "capabilities": {

package/package.json

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

package/runtime/connectors/base/policy-layer.js

@@ -108,40 +108,23 @@ export function createConnectorPolicyLayer(ctx) {
             }
             let lastFailure;
             for (let attempt = 1; attempt <= retryPolicy.maxRetries; attempt += 1) {
-                const traceId = makeTraceId(request, plan);
-                const attemptId = `attempt-${traceId}-${attempt}`;
+                const traceId = `${makeTraceId(request, plan)}:${attempt}`;
                 if (ctx.telemetry) {
-                    await ctx.telemetry.recordExecutionAttempt({
-                        id: attemptId,
+                    await ctx.telemetry.startAttempt({
                         traceId,
                         decisionId: identity.decisionId,
                         intentId: identity.intentId,
                         platformId: request.platformId,
                         capability: request.intent,
                         channel: plan.channel,
-                        status: "started",
                         retryPolicy: JSON.stringify(retryPolicy),
                         idempotencyKey: request.idempotencyKey,
-                        startedAt: new Date().toISOString(),
                     });
                 }
                 const raw = await ctx.executionRunner.run(plan, request);
                 if (raw.success) {
                     if (ctx.telemetry) {
-                        await ctx.telemetry.recordExecutionAttempt({
-                            id: `${attemptId}-done`,
-                            traceId,
-                            decisionId: identity.decisionId,
-                            intentId: identity.intentId,
-                            platformId: request.platformId,
-                            capability: request.intent,
-                            channel: plan.channel,
-                            status: "succeeded",
-                            retryPolicy: JSON.stringify(retryPolicy),
-                            idempotencyKey: request.idempotencyKey,
-                            startedAt: new Date().toISOString(),
-                            finishedAt: new Date().toISOString(),
-                        });
+                        await ctx.telemetry.completeAttempt(traceId, "succeeded");
                     }
                     return {
                         status: "success",
@@ -161,21 +144,7 @@ export function createConnectorPolicyLayer(ctx) {
                     channel: raw.channel,
                 };
                 if (ctx.telemetry) {
-                    await ctx.telemetry.recordExecutionAttempt({
-                        id: `${attemptId}-failed`,
-                        traceId,
-                        decisionId: identity.decisionId,
-                        intentId: identity.intentId,
-                        platformId: request.platformId,
-                        capability: request.intent,
-                        channel: plan.channel,
-                        status: "failed",
-                        failureClass: classified.class,
-                        retryPolicy: JSON.stringify(retryPolicy),
-                        idempotencyKey: request.idempotencyKey,
-                        startedAt: new Date().toISOString(),
-                        finishedAt: new Date().toISOString(),
-                    });
+                    await ctx.telemetry.completeAttempt(traceId, "failed", undefined, classified.class);
                 }
                 if (ctx.cooldownPort) {
                     await ctx.cooldownPort.markFailure(request.platformId, intent, classified.class, classified.retryAfterMs);

package/runtime/observability/services/execution-telemetry.d.ts

@@ -7,7 +7,6 @@ export interface ExecutionAttemptInput {
     platformId: string;
     capability: string;
     channel: string;
-    status: ExecutionAttempt["status"];
     commitState?: IntentCommitState;
     failureClass?: string;
     retryPolicy?: string;