@haaaiawd/second-nature 0.1.22 → 0.1.24

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "second-nature",
   "name": "Second Nature",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "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 (see README / T1.1.4 ops norm).",
   "activation": {
     "onStartup": true,

package/package.json

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

package/runtime/cli/commands/connector-init.d.ts

@@ -0,0 +1,19 @@
+export interface ConnectorInitInput {
+    platformId: string;
+    family?: "social_community" | "agent_network" | "work_platform" | "custom";
+    displayName?: string;
+    baseUrl?: string;
+    runnerKind?: "declarative_http" | "declarative_a2a" | "declarative_mcp" | "cli_descriptor" | "custom_adapter" | "skill" | "browser";
+    force?: boolean;
+    workspaceRoot?: string;
+}
+export interface ConnectorInitResult {
+    ok: boolean;
+    platformId: string;
+    manifestPath: string;
+    adapterPath: string;
+    typesPath: string;
+    created: boolean;
+    reason?: string;
+}
+export declare function connectorInit(input: ConnectorInitInput): Promise<ConnectorInitResult>;

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

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+function resolveConnectorsDir(workspaceRoot) {
+    if (workspaceRoot) {
+        return path.resolve(workspaceRoot, ".second-nature", "connectors");
+    }
+    return path.resolve(process.cwd(), ".second-nature", "connectors");
+}
+function generateManifestYaml(input) {
+    const platformId = input.platformId;
+    const displayName = input.displayName ?? platformId;
+    const family = input.family ?? "custom";
+    const runnerKind = input.runnerKind ?? "declarative_http";
+    const baseUrlLine = input.baseUrl ? `\nbaseUrl: ${input.baseUrl}` : "";
+    return `schemaVersion: sn.connector.v1
+platformId: ${platformId}
+displayName: ${displayName}
+family: ${family}${baseUrlLine}
+capabilities:
+  - id: ${platformId}.placeholder
+    description: Placeholder capability — replace with real capability declarations
+runner:
+  kind: ${runnerKind}
+  entrypoint: ""
+credentials: []
+sourceRefPolicy:
+  minSourceRefs: 1
+  rejectInlineSensitivePayload: true
+trust:
+  status: custom_adapter_pending_trust
+  reason: generated_by_connector_init
+`;
+}
+function generateAdapterStub(platformId) {
+    const pascalId = platformId
+        .split(/[-_]/)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1).toLowerCase())
+        .join("");
+    return `/**
+ * ${pascalId} Connector Adapter Stub
+ *
+ * Generated by \`second-nature connector init\`.
+ * Replace this stub with real platform-specific execution logic.
+ *
+ * Runner kind: custom_adapter (pending trust until owner allowlists).
+ */
+
+import type { ConnectorResult } from "@second-nature/connector-sdk";
+
+export interface ${pascalId}AdapterConfig {
+  baseUrl: string;
+  apiKey?: string;
+}
+
+export async function execute${pascalId}Action(
+  config: ${pascalId}AdapterConfig,
+  action: string,
+  payload: unknown,
+): Promise<ConnectorResult> {
+  // TODO: implement real platform call
+  return {
+    ok: false,
+    error: {
+      code: "NOT_IMPLEMENTED",
+      message: \`${pascalId} adapter action '\${action}' is not yet implemented\`,
+    },
+  };
+}
+`;
+}
+function generateTypesStub(platformId) {
+    const pascalId = platformId
+        .split(/[-_]/)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1).toLowerCase())
+        .join("");
+    return `/**
+ * ${pascalId} Connector Type Stubs
+ *
+ * Generated by \`second-nature connector init\`.
+ * Expand these types as you add real capabilities.
+ */
+
+export interface ${pascalId}Capability {
+  id: string;
+  description?: string;
+}
+
+export interface ${pascalId}Credential {
+  type: "api_key" | "oauth" | "session";
+  required: boolean;
+}
+
+export interface ${pascalId}PlatformPayload {
+  // TODO: define real platform-specific payload shapes
+  [key: string]: unknown;
+}
+`;
+}
+export async function connectorInit(input) {
+    const { platformId, force = false } = input;
+    if (!platformId || typeof platformId !== "string" || platformId.trim().length === 0) {
+        return {
+            ok: false,
+            platformId: "",
+            manifestPath: "",
+            adapterPath: "",
+            typesPath: "",
+            created: false,
+            reason: "platformId is required and must be a non-empty string",
+        };
+    }
+    const trimmed = platformId.trim();
+    if (trimmed === "." || trimmed === "..") {
+        return {
+            ok: false,
+            platformId: trimmed,
+            manifestPath: "",
+            adapterPath: "",
+            typesPath: "",
+            created: false,
+            reason: "platformId cannot be '.' or '..'",
+        };
+    }
+    const sanitized = trimmed.replace(/[^a-zA-Z0-9_-]/g, "_");
+    if (sanitized !== trimmed) {
+        return {
+            ok: false,
+            platformId,
+            manifestPath: "",
+            adapterPath: "",
+            typesPath: "",
+            created: false,
+            reason: `platformId contains invalid characters. Suggested: ${sanitized}`,
+        };
+    }
+    const connectorsDir = resolveConnectorsDir(input.workspaceRoot);
+    const platformDir = path.join(connectorsDir, sanitized);
+    const manifestPath = path.join(platformDir, "manifest.yaml");
+    const adapterPath = path.join(platformDir, "adapter.ts");
+    const typesPath = path.join(platformDir, "types.ts");
+    // CR7-01: fail-closed when target already exists (no silent skip)
+    if (fs.existsSync(manifestPath) && !force) {
+        return {
+            ok: false,
+            platformId: sanitized,
+            manifestPath,
+            adapterPath,
+            typesPath,
+            created: false,
+            reason: "manifest already exists; use force:true to overwrite",
+        };
+    }
+    fs.mkdirSync(platformDir, { recursive: true });
+    const manifestContent = generateManifestYaml({ ...input, platformId: sanitized });
+    fs.writeFileSync(manifestPath, manifestContent, "utf-8");
+    const adapterContent = generateAdapterStub(sanitized);
+    fs.writeFileSync(adapterPath, adapterContent, "utf-8");
+    const typesContent = generateTypesStub(sanitized);
+    fs.writeFileSync(typesPath, typesContent, "utf-8");
+    return {
+        ok: true,
+        platformId: sanitized,
+        manifestPath,
+        adapterPath,
+        typesPath,
+        created: true,
+    };
+}

package/runtime/cli/commands/connector-status.d.ts

@@ -0,0 +1,12 @@
+import type { DynamicConnectorRegistry } from "../../connectors/registry/index.js";
+import type { ConnectorInventoryLedger } from "../../observability/connector-inventory-ledger.js";
+export interface ConnectorStatusInput {
+    includeHealth?: boolean;
+    workspaceRoot?: string;
+}
+export interface ConnectorTestInput {
+    platformId: string;
+    dryRun?: boolean;
+}
+export declare function connectorStatus(registry: DynamicConnectorRegistry | undefined, ledger: ConnectorInventoryLedger | undefined, input?: ConnectorStatusInput): Promise<Record<string, unknown>>;
+export declare function connectorTest(registry: DynamicConnectorRegistry | undefined, input: ConnectorTestInput): Promise<Record<string, unknown>>;

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

@@ -0,0 +1,156 @@
+export async function connectorStatus(registry, ledger, input) {
+    if (!registry) {
+        return {
+            ok: false,
+            command: "connector_status",
+            error: {
+                code: "REGISTRY_UNAVAILABLE",
+                message: "connector:status requires DynamicConnectorRegistry to be wired into OpsRouterDeps",
+                nextStep: "wire_registry_into_ops_router",
+            },
+        };
+    }
+    // Ensure snapshot is loaded; if workspaceRoot provided, reload
+    if (input?.workspaceRoot) {
+        registry.reloadConnectors(input.workspaceRoot);
+    }
+    const snapshot = registry.getActiveRegistrySnapshot();
+    const entries = [...snapshot.entries.values()];
+    const conflicts = snapshot.conflicts.map((c) => ({
+        platformId: c.platformId,
+        existingSource: c.existingSource,
+        attemptedSource: c.attemptedSource,
+        reason: c.reason,
+    }));
+    const validationErrors = snapshot.validationErrors.map((e) => ({
+        platformId: e.platformId,
+        path: e.path,
+        message: e.message,
+    }));
+    const summary = {
+        total: entries.length,
+        builtIn: entries.filter((e) => e.source === "built_in").length,
+        workspace: entries.filter((e) => e.source === "workspace").length,
+        executable: entries.filter((e) => e.executable).length,
+        pendingTrust: entries.filter((e) => !e.executable).length,
+    };
+    // Optionally record audit
+    if (ledger) {
+        await ledger.recordAudit({
+            snapshotId: snapshot.createdAt,
+            scanned: entries.length + conflicts.length + validationErrors.length,
+            registered: entries.length,
+            skipped: conflicts.length + validationErrors.length,
+            conflicts: conflicts.map((c) => ({ connectorId: c.platformId, reason: c.reason })),
+            validationErrors: validationErrors.map((e) => ({
+                connectorId: e.platformId ?? "unknown",
+                errors: [e.message],
+            })),
+            trustSummary: {
+                executable: summary.executable,
+                pendingTrust: summary.pendingTrust,
+            },
+        });
+    }
+    return {
+        ok: true,
+        command: "connector_status",
+        data: {
+            summary,
+            connectors: entries.map((e) => ({
+                platformId: e.platformId,
+                source: e.source,
+                trustStatus: e.trustStatus,
+                executable: e.executable,
+                capabilities: e.capabilities,
+                validationErrors: e.validationErrors,
+                manifestPath: e.manifestPath,
+            })),
+            conflicts,
+            validationErrors,
+            snapshotCreatedAt: snapshot.createdAt,
+        },
+    };
+}
+export async function connectorTest(registry, input) {
+    if (!registry) {
+        return {
+            ok: false,
+            command: "connector_test",
+            error: {
+                code: "REGISTRY_UNAVAILABLE",
+                message: "connector:test requires DynamicConnectorRegistry to be wired into OpsRouterDeps",
+                nextStep: "wire_registry_into_ops_router",
+            },
+        };
+    }
+    const platformId = input.platformId.trim();
+    if (!platformId) {
+        return {
+            ok: false,
+            command: "connector_test",
+            error: {
+                code: "MISSING_PLATFORM_ID",
+                message: "connector:test requires platformId",
+                requiredUserInput: ["platformId"],
+                nextStep: "reinvoke_with_platform_id",
+            },
+        };
+    }
+    const entry = registry.describeConnector(platformId);
+    if (!entry) {
+        return {
+            ok: false,
+            command: "connector_test",
+            error: {
+                code: "CONNECTOR_NOT_FOUND",
+                message: `No connector found for platformId: ${platformId}`,
+                requiredUserInput: ["platformId"],
+                nextStep: "verify_platform_id_or_run_connector_status",
+            },
+        };
+    }
+    const dryRun = input.dryRun !== false; // default dry-run
+    // CR7-02: pending-trust / non-executable connectors must fail-closed
+    if (!entry.executable) {
+        return {
+            ok: false,
+            command: "connector_test",
+            error: {
+                code: "PENDING_TRUST_DENIED",
+                message: `Connector '${entry.platformId}' is not executable: trustStatus=${entry.trustStatus}. Use connector:status to review trust policy or owner allowlist to enable.`,
+                trustStatus: entry.trustStatus,
+                platformId: entry.platformId,
+                nextStep: "review_trust_policy_or_owner_allowlist",
+            },
+        };
+    }
+    const healthChecks = [];
+    if (entry.validationErrors.length > 0) {
+        healthChecks.push(`validation_errors: ${entry.validationErrors.join("; ")}`);
+    }
+    if (entry.capabilities.length === 0) {
+        healthChecks.push("no_capabilities_declared");
+    }
+    if (healthChecks.length === 0) {
+        healthChecks.push("ok");
+    }
+    return {
+        ok: true,
+        command: "connector_test",
+        data: {
+            platformId: entry.platformId,
+            source: entry.source,
+            trustStatus: entry.trustStatus,
+            executable: entry.executable,
+            capabilities: entry.capabilities,
+            validationErrors: entry.validationErrors,
+            manifestPath: entry.manifestPath,
+            dryRun,
+            healthChecks,
+            note: dryRun
+                ? "dry-run mode: no side effects were attempted"
+                : "live test mode: side effects may have been attempted (use with caution)",
+        },
+    };
+}

package/runtime/cli/commands/index.js

@@ -1,4 +1,5 @@
 import { credentialVerify } from "./credential.js";
+import { connectorInit } from "./connector-init.js";
 import { formatExplanation } from "../explain/format-explanation.js";
 import { explainSurfaceSubject } from "../explain/explain-surface-subject.js";
 import { showOperatorFallback, OperatorFallbackNotFoundError, } from "../ops/show-operator-fallback.js";
@@ -220,5 +221,44 @@ export function createCliCommands(deps) {
                 return surface;
             },
         },
+        {
+            name: "connector_init",
+            description: "T1.3.1 — generate connector manifest stub under .second-nature/connectors/{platformId}/",
+            execute: async (input) => {
+                const result = await connectorInit({
+                    platformId: typeof input?.platformId === "string" ? input.platformId : "",
+                    family: typeof input?.family === "string"
+                        ? input.family
+                        : undefined,
+                    displayName: typeof input?.displayName === "string"
+                        ? input.displayName
+                        : undefined,
+                    runnerKind: typeof input?.runnerKind === "string"
+                        ? input.runnerKind
+                        : undefined,
+                    force: Boolean(input?.force),
+                    workspaceRoot: typeof input?.workspaceRoot === "string"
+                        ? input.workspaceRoot
+                        : undefined,
+                });
+                return result;
+            },
+        },
+        {
+            name: "connector_status",
+            description: "T1.2.3 — show connector inventory, trust/executable/conflict summary",
+            execute: async (input) => {
+                const surface = await Promise.resolve(opsRouter.dispatch("connector_status", input));
+                return surface;
+            },
+        },
+        {
+            name: "connector_test",
+            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));
+                return surface;
+            },
+        },
     ];
 }

package/runtime/cli/index.js

@@ -8,6 +8,51 @@ import { createCliReadModels, } from "./read-models/index.js";
 import { resolvePackagedRuntime } from "./runtime/runtime-artifact-boundary.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";
+/** Built-in connector manifests for DynamicConnectorRegistry. */
+const BUILT_IN_CONNECTOR_MANIFESTS = [
+    {
+        schemaVersion: "sn.connector.v1",
+        platformId: "moltbook",
+        displayName: "Moltbook",
+        family: "social_community",
+        capabilities: [
+            { id: "feed.read" },
+            { id: "post.publish" },
+            { id: "comment.reply" },
+        ],
+        runner: { kind: "declarative_http" },
+        credentials: [{ type: "api_key", required: true }],
+        sourceRefPolicy: { minSourceRefs: 1 },
+    },
+    {
+        schemaVersion: "sn.connector.v1",
+        platformId: "evomap",
+        displayName: "EvoMap",
+        family: "agent_network",
+        capabilities: [
+            { id: "agent.register" },
+            { id: "work.discover" },
+        ],
+        runner: { kind: "declarative_http" },
+        credentials: [{ type: "api_key", required: true }],
+        sourceRefPolicy: { minSourceRefs: 1 },
+    },
+    {
+        schemaVersion: "sn.connector.v1",
+        platformId: "agent-world",
+        displayName: "Agent World",
+        family: "agent_network",
+        capabilities: [
+            { id: "feed.read" },
+            { id: "work.discover" },
+            { id: "task.claim" },
+        ],
+        runner: { kind: "declarative_http" },
+        credentials: [{ type: "api_key", required: true }],
+        sourceRefPolicy: { minSourceRefs: 1 },
+    },
+];
 export function createCliRuntimeDeps(overrides = {}) {
     const stateDb = overrides.stateDb ?? createStateDatabase();
     const observabilityDb = overrides.observabilityDb ?? createObservabilityDatabase();
@@ -26,6 +71,11 @@ export function createCliRuntimeDeps(overrides = {}) {
             stateDb,
             observabilityDb,
         });
+    const registry = overrides.registry ??
+        new DynamicConnectorRegistry({
+            builtInManifests: BUILT_IN_CONNECTOR_MANIFESTS,
+            snapshotStore: createRegistrySnapshotStore(),
+        });
     return {
         stateDb,
         observabilityDb,
@@ -34,6 +84,7 @@ export function createCliRuntimeDeps(overrides = {}) {
         actionBridge,
         runtimeRecorder,
         connectorExecutor,
+        registry,
     };
 }
 export function createCommandRouter(options = {}) {
@@ -47,6 +98,7 @@ export function createCommandRouter(options = {}) {
         workspaceRoot: process.cwd(),
         observabilityDb: runtime.observabilityDb,
         connectorExecutor: runtime.connectorExecutor,
+        registry: runtime.registry,
     });
     const commands = createCliCommands({
         readModels: runtime.readModels,

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

@@ -7,6 +7,7 @@ import type { RuntimeDecisionRecorder } from "../../observability/services/runti
 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";
 export interface OpsRouterDeps {
     /** When true, packaged runtime artifacts resolved and full graph is loadable */
     runtimeAvailable: boolean;
@@ -30,6 +31,10 @@ export interface OpsRouterDeps {
      * connector-system instead of returning connector_dispatch_unwired.
      */
     connectorExecutor?: ConnectorExecutor;
+    /**
+     * T1.2.3: DynamicConnectorRegistry for connector:status and connector:test commands.
+     */
+    registry?: DynamicConnectorRegistry;
 }
 export interface OpsRouter {
     heartbeatCheck(input: HeartbeatCheckInput): Promise<HeartbeatSurfaceResult>;

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

@@ -6,6 +6,8 @@ import { showOperatorFallback, OperatorFallbackNotFoundError, } from "./show-ope
 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 { connectorStatus, connectorTest } from "../commands/connector-status.js";
 function coerceProbeOnlyFlag(input) {
     const v = input?.probeOnly;
     return v === true || v === "true" || v === 1 || v === "1";
@@ -179,6 +181,38 @@ export function createOpsRouter(deps) {
                     };
                 })();
             }
+            if (command === "connector_init") {
+                // T1.3.1 (SN-CODE-06): generate connector manifest stub.
+                return (async () => {
+                    const result = await connectorInit({
+                        platformId: typeof input?.platformId === "string" ? input.platformId : "",
+                        family: typeof input?.family === "string"
+                            ? input.family
+                            : undefined,
+                        displayName: typeof input?.displayName === "string" ? input.displayName : undefined,
+                        runnerKind: typeof input?.runnerKind === "string"
+                            ? input.runnerKind
+                            : undefined,
+                        force: Boolean(input?.force),
+                        workspaceRoot: deps.workspaceRoot,
+                    });
+                    return result;
+                })();
+            }
+            if (command === "connector_status") {
+                return connectorStatus(deps.registry, undefined, {
+                    includeHealth: Boolean(input?.includeHealth),
+                    workspaceRoot: typeof input?.workspaceRoot === "string"
+                        ? input.workspaceRoot
+                        : deps.workspaceRoot,
+                });
+            }
+            if (command === "connector_test") {
+                return connectorTest(deps.registry, {
+                    platformId: typeof input?.platformId === "string" ? input.platformId : "",
+                    dryRun: input?.dryRun === false ? false : true, // default dry-run
+                });
+            }
             return {
                 ok: false,
                 error: {

package/runtime/cli/ops/workspace-heartbeat-runner.js

@@ -1,5 +1,7 @@
 import { runHeartbeatCycle } from "../../core/second-nature/heartbeat/run-heartbeat-cycle.js";
 import { loadLifeEvidenceSnapshot } from "../../storage/snapshots/life-evidence-snapshot.js";
+import { createAgentGoalStore } from "../../storage/goal/agent-goal-store.js";
+import { createNarrativeStateStore } from "../../storage/narrative/narrative-state-store.js";
 export async function loadSnapshotInputsForWorkspaceHeartbeat(readModels, options = {}) {
     const status = await readModels.loadStatus();
     const mode = status.rhythm.mode === "unknown" ? "active" : status.rhythm.mode;
@@ -43,6 +45,20 @@ export async function loadSnapshotInputsForWorkspaceHeartbeat(readModels, option
         // No state wired — record that life evidence wasn't loaded so guards can reason honestly.
         lifeEvidenceEmptyReason = "state_unavailable";
     }
+    // T2.1.4: Load accepted goals from state DB when available.
+    let acceptedGoals;
+    if (options.state) {
+        try {
+            const goalStore = createAgentGoalStore(options.state);
+            acceptedGoals = await goalStore.listAgentGoals({
+                statuses: ["accepted"],
+                limit: 20,
+            });
+        }
+        catch {
+            acceptedGoals = undefined;
+        }
+    }
     return {
         mode,
         currentWindowId: status.rhythm.windowId ?? "workspace-default",
@@ -57,12 +73,17 @@ export async function loadSnapshotInputsForWorkspaceHeartbeat(readModels, option
         platformEventCount,
         workEventCount,
         lifeEvidenceEmptyReason,
+        acceptedGoals,
     };
 }
 export function createWorkspaceHeartbeatRunner(readModels, options = {}) {
     // T1.2.4: inject quietWorkflow dep when workspaceRoot is set so quiet/reflection intents
     // can trigger runSourceBackedQuiet and persist artifacts to disk.
     const quietEnabled = options.workspaceRoot && options.enableQuietWorkflow !== false;
+    // T2.1.5: when state DB is wired, create a NarrativeStateStore for heartbeat updates.
+    const narrativeStateStore = options.state
+        ? createNarrativeStateStore(options.state)
+        : undefined;
     return async (signal) => {
         const cycle = await runHeartbeatCycle({
             signal,
@@ -77,6 +98,7 @@ export function createWorkspaceHeartbeatRunner(readModels, options = {}) {
                     ? { workspaceRoot: options.workspaceRoot }
                     : undefined,
                 connectorExecutor: options.connectorExecutor,
+                narrativeStateStore,
             },
         });
         if (options.runtimeRecorder) {

package/runtime/connectors/agent-network/agent-world/adapter.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectorRequest, ExecutionPlan, RawAttempt } from "../../base/contract.js";
+export interface AgentWorldApiClient {
+    readFeed(payload: Record<string, unknown>, apiKey: string): Promise<unknown>;
+    discoverWork(payload: Record<string, unknown>, apiKey: string): Promise<unknown>;
+    claimTask(payload: Record<string, unknown>, apiKey: string): Promise<unknown>;
+}
+export declare function createAgentWorldRunner(input: {
+    apiClient: AgentWorldApiClient;
+}): {
+    run(plan: ExecutionPlan, request: ConnectorRequest): Promise<RawAttempt>;
+};