@haaaiawd/second-nature 0.1.43 → 0.1.50

package/dist/scripts/build-plugin-runtime.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * Plugin runtime artifact build script
+ *
+ * This script copies the compiled runtime code from dist/src/ into plugin/runtime/
+ * to create a self-contained plugin package that does not depend on the source repository.
+ *
+ * Usage: node scripts/build-plugin-runtime.js
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, "..", "..");
+const distDir = path.resolve(rootDir, "dist");
+const pluginRuntimeDir = path.resolve(rootDir, "plugin", "runtime");
+/**
+ * Directories and files that must be included in the plugin runtime artifact.
+ * This is the minimum runtime dependency graph as defined in ADR-006.
+ */
+const RUNTIME_ARTIFACTS = [
+    // CLI runtime
+    { src: "src/cli/index.js", dest: "cli/index.js" },
+    { src: "src/cli/index.d.ts", dest: "cli/index.d.ts" },
+    { src: "src/cli/action-bridge.js", dest: "cli/action-bridge.js" },
+    { src: "src/cli/action-bridge.d.ts", dest: "cli/action-bridge.d.ts" },
+    { src: "src/cli/commands/", dest: "cli/commands/" },
+    { src: "src/cli/read-models/", dest: "cli/read-models/" },
+    { src: "src/cli/explain/", dest: "cli/explain/" },
+    // State system runtime
+    { src: "src/storage/", dest: "storage/" },
+    // Observability system runtime
+    { src: "src/observability/", dest: "observability/" },
+    // Core second-nature (for heartbeat service entry)
+    { src: "src/core/second-nature/", dest: "core/second-nature/" },
+    // Guidance system
+    { src: "src/guidance/", dest: "guidance/" },
+    // Connector system
+    { src: "src/connectors/", dest: "connectors/" },
+    // Dream scheduler (required by ops-router.ts → createQuietDreamSchedulePort)
+    { src: "src/dream/", dest: "dream/" },
+    // Shared types
+    { src: "src/shared/", dest: "shared/" },
+    // Type declarations
+    { src: "src/openclaw-plugin-sdk.d.ts", dest: "openclaw-plugin-sdk.d.ts" },
+];
+/**
+ * Copy a file or directory recursively
+ */
+function copyRecursive(srcPath, destPath) {
+    const stat = fs.statSync(srcPath);
+    if (stat.isDirectory()) {
+        if (!fs.existsSync(destPath)) {
+            fs.mkdirSync(destPath, { recursive: true });
+        }
+        const entries = fs.readdirSync(srcPath);
+        for (const entry of entries) {
+            const srcEntry = path.join(srcPath, entry);
+            const destEntry = path.join(destPath, entry);
+            copyRecursive(srcEntry, destEntry);
+        }
+    }
+    else {
+        const destDir = path.dirname(destPath);
+        if (!fs.existsSync(destDir)) {
+            fs.mkdirSync(destDir, { recursive: true });
+        }
+        fs.copyFileSync(srcPath, destPath);
+    }
+}
+/**
+ * Clean the plugin runtime directory
+ */
+function cleanRuntimeDir() {
+    if (fs.existsSync(pluginRuntimeDir)) {
+        fs.rmSync(pluginRuntimeDir, { recursive: true, force: true });
+    }
+    fs.mkdirSync(pluginRuntimeDir, { recursive: true });
+    console.log("✅ Cleaned plugin runtime directory");
+}
+/**
+ * Copy runtime artifacts from dist/ to plugin/runtime/
+ */
+function copyArtifacts() {
+    let copied = 0;
+    let skipped = 0;
+    for (const artifact of RUNTIME_ARTIFACTS) {
+        const srcPath = path.resolve(distDir, artifact.src);
+        const destPath = path.resolve(pluginRuntimeDir, artifact.dest);
+        if (!fs.existsSync(srcPath)) {
+            console.log(`⚠️  Skipped (not found): ${artifact.src}`);
+            skipped++;
+            continue;
+        }
+        copyRecursive(srcPath, destPath);
+        console.log(`✅ Copied: ${artifact.src} -> ${artifact.dest}`);
+        copied++;
+    }
+    return { copied, skipped };
+}
+/**
+ * Verify the runtime artifact structure
+ */
+function verifyArtifacts() {
+    const requiredFiles = [
+        "cli/index.js",
+        "cli/commands/index.js",
+        "storage/index.js",
+        "storage/db/index.js",
+        "observability/index.js",
+        "observability/db/index.js",
+        "core/second-nature/index.js",
+        "guidance/index.js",
+        "connectors/index.js",
+    ];
+    let allPresent = true;
+    for (const file of requiredFiles) {
+        const filePath = path.resolve(pluginRuntimeDir, file);
+        if (!fs.existsSync(filePath)) {
+            console.log(`❌ Missing required file: ${file}`);
+            allPresent = false;
+        }
+    }
+    return allPresent;
+}
+/**
+ * Check for any remaining ../src/ references in the runtime artifact
+ */
+function checkForExternalReferences() {
+    const found = [];
+    function checkFile(filePath) {
+        if (!fs.existsSync(filePath))
+            return;
+        const stat = fs.statSync(filePath);
+        if (stat.isDirectory()) {
+            const entries = fs.readdirSync(filePath);
+            for (const entry of entries) {
+                checkFile(path.join(filePath, entry));
+            }
+        }
+        else if (filePath.endsWith(".js") || filePath.endsWith(".ts")) {
+            const content = fs.readFileSync(filePath, "utf-8");
+            if (content.includes("../src/") || content.includes("..\\src\\")) {
+                found.push(path.relative(pluginRuntimeDir, filePath));
+            }
+        }
+    }
+    checkFile(pluginRuntimeDir);
+    return { found: found.length > 0, files: found };
+}
+/**
+ * Main build function
+ */
+function main() {
+    console.log("🔨 Building plugin runtime artifact...\n");
+    // Step 1: Verify dist/ exists
+    if (!fs.existsSync(distDir)) {
+        console.error("❌ dist/ directory not found. Run 'pnpm build' first.");
+        process.exit(1);
+    }
+    console.log("✅ Found dist/ directory");
+    // Step 2: Clean plugin runtime directory
+    cleanRuntimeDir();
+    // Step 3: Copy artifacts
+    console.log("\n📦 Copying runtime artifacts...");
+    const { copied, skipped } = copyArtifacts();
+    console.log(`\n📊 Copied: ${copied}, Skipped: ${skipped}`);
+    // Step 4: Verify artifacts
+    console.log("\n🔍 Verifying artifact structure...");
+    const verified = verifyArtifacts();
+    if (verified) {
+        console.log("✅ All required files present");
+    }
+    else {
+        console.log("❌ Some required files are missing");
+        process.exit(1);
+    }
+    // Step 5: Check for external references
+    console.log("\n🔍 Checking for external src/ references...");
+    const { found, files } = checkForExternalReferences();
+    if (found) {
+        console.log("⚠️  Found external src/ references in:");
+        files.forEach((f) => console.log(`   - ${f}`));
+        console.log("\n   These will be resolved in T1.2.1 (wrapper rewire)");
+    }
+    else {
+        console.log("✅ No external src/ references found");
+    }
+    // Step 6: Summary
+    console.log("\n📋 Build Summary:");
+    console.log(`   Runtime artifact directory: ${pluginRuntimeDir}`);
+    console.log(`   Files copied: ${copied}`);
+    console.log(`   Files skipped: ${skipped}`);
+    console.log(`   External references: ${found ? "⚠️ (will be fixed in T1.2.1)" : "✅"}`);
+    console.log("\n✅ Plugin runtime artifact build complete");
+}
+main();

package/dist/scripts/packaging-feasibility-poc.js

@@ -0,0 +1,127 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Resolve project root regardless of whether script runs from source or dist/.
+ * When compiled, __dirname is dist/scripts/, so we need to go up two levels.
+ * When running from source via --experimental-strip-types, __dirname is scripts/.
+ */
+function resolveRootDir() {
+    if (__dirname.includes(path.sep + 'dist' + path.sep + 'scripts')) {
+        return path.resolve(__dirname, '..', '..');
+    }
+    if (__dirname.endsWith('scripts')) {
+        return path.resolve(__dirname, '..');
+    }
+    return path.resolve(__dirname, '..');
+}
+const rootDir = resolveRootDir();
+const require = createRequire(import.meta.url);
+console.log('=== Packaging Feasibility POC Report ===');
+console.log('Project root:', rootDir, '\n');
+// 1. Test jiti loading of compiled JS
+console.log('--- Test 1: jiti loading of compiled JS ---');
+try {
+    const { createJiti } = require('jiti');
+    const jiti = createJiti(import.meta.url);
+    const cliPath = path.resolve(rootDir, 'dist/src/cli/index.js');
+    console.log('Attempting to load:', cliPath);
+    console.log('File exists:', fs.existsSync(cliPath));
+    const mod = jiti(cliPath);
+    console.log('Module loaded successfully:', !!mod);
+    console.log('Has createCommandRouter:', !!mod.createCommandRouter);
+    console.log('Has createCliRuntimeDeps:', !!mod.createCliRuntimeDeps);
+    console.log('✅ jiti loading: PASS\n');
+}
+catch (e) {
+    const err = e;
+    console.log('❌ jiti loading: FAIL');
+    console.log('Error:', err.message, '\n');
+}
+// 2. Test better-sqlite3 native module
+console.log('--- Test 2: better-sqlite3 native module ---');
+try {
+    const Database = require('better-sqlite3');
+    const db = new Database(':memory:');
+    db.exec('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)');
+    db.exec("INSERT INTO test (name) VALUES ('test')");
+    const row = db.prepare('SELECT * FROM test').get();
+    console.log('SQLite test row:', row);
+    db.close();
+    console.log('✅ better-sqlite3: PASS\n');
+}
+catch (e) {
+    const err = e;
+    console.log('❌ better-sqlite3: FAIL');
+    console.log('Error:', err.message, '\n');
+}
+// 3. Test npm install --ignore-scripts impact
+console.log('--- Test 3: npm install --ignore-scripts impact ---');
+console.log('better-sqlite3 requires native compilation during npm install');
+console.log('With --ignore-scripts, better-sqlite3 prebuilds may not be available');
+const sqlitePkg = require('better-sqlite3/package.json');
+console.log('Current better-sqlite3 version:', sqlitePkg.version);
+const prebuildsPath = path.resolve(rootDir, 'node_modules/better-sqlite3/prebuilds');
+console.log('Check if prebuilds are bundled:', fs.existsSync(prebuildsPath));
+console.log('⚠️ better-sqlite3 with --ignore-scripts: RISK (needs prebuild or compilation)\n');
+// 4. Test artifact closure boundary
+console.log('--- Test 4: Artifact closure boundary ---');
+const pluginPkgPath = path.resolve(rootDir, 'plugin/package.json');
+const pluginPkg = JSON.parse(fs.readFileSync(pluginPkgPath, 'utf-8'));
+console.log('Current plugin files field:', JSON.stringify(pluginPkg.files));
+console.log('Current plugin main:', pluginPkg.main);
+console.log('Plugin has dependencies field:', !!pluginPkg.dependencies);
+const runtimeDir = path.resolve(rootDir, 'plugin/runtime');
+const hasRuntimeDir = fs.existsSync(runtimeDir);
+console.log('plugin/runtime/ exists:', hasRuntimeDir);
+if (hasRuntimeDir) {
+    const entries = fs.readdirSync(runtimeDir);
+    console.log('Runtime artifact contents:', entries.join(', '));
+    console.log('✅ Artifact boundary: PASS — runtime code included in package\n');
+}
+else {
+    console.log('❌ Artifact boundary: FAIL — no runtime code in package\n');
+}
+// 5. Test compiled code import chain
+console.log('--- Test 5: Compiled code import chain ---');
+try {
+    const cliPath = path.resolve(rootDir, 'dist/src/cli/index.js');
+    const cliModule = await import(pathToFileURL(cliPath).href);
+    console.log('Direct import successful:', !!cliModule);
+    console.log('Exports:', Object.keys(cliModule));
+    console.log('✅ Compiled import chain: PASS\n');
+}
+catch (e) {
+    const err = e;
+    console.log('❌ Compiled import chain: FAIL');
+    console.log('Error:', err.message, '\n');
+}
+// 6. Test plugin wrapper path resolution
+console.log('--- Test 6: Plugin wrapper path resolution ---');
+const pluginIndexPath = path.resolve(rootDir, 'plugin/index.ts');
+const pluginIndex = fs.readFileSync(pluginIndexPath, 'utf-8');
+const hasExternalRef = pluginIndex.includes('../src/');
+const hasRuntimeRef = pluginIndex.includes('./runtime/');
+console.log('Wrapper references ../src/:', hasExternalRef);
+console.log('Wrapper references ./runtime/:', hasRuntimeRef);
+if (!hasExternalRef && hasRuntimeRef) {
+    console.log('✅ Plugin wrapper: PASS — uses package-local paths\n');
+}
+else {
+    console.log('❌ Plugin wrapper: FAIL — still references external src/\n');
+}
+// Summary
+console.log('=== Summary ===');
+console.log('1. jiti loading: tested');
+console.log('2. better-sqlite3: tested');
+console.log('3. npm install --ignore-scripts: RISK identified');
+console.log('4. Artifact closure:', hasRuntimeDir ? '✅ PASS' : '❌ FAIL');
+console.log('5. Compiled import chain: tested');
+console.log('6. Plugin wrapper paths:', !hasExternalRef && hasRuntimeRef ? '✅ PASS' : '❌ FAIL');
+console.log('\nConclusion: 可继续沿用 (Can continue using current stack)');
+function pathToFileURL(filePath) {
+    return new URL('file://' + filePath.replace(/\\/g, '/'));
+}

package/dist/scripts/plugin-smoke-check.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import path from "node:path";
+function resolveRoot() {
+    return process.cwd();
+}
+function ensureFile(filePath) {
+    return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+}
+function localPathResult(root) {
+    const pluginDir = path.join(root, "plugin");
+    const pluginPkgPath = path.join(pluginDir, "package.json");
+    const manifestPath = path.join(pluginDir, "openclaw.plugin.json");
+    const entryPath = path.join(pluginDir, "index.js");
+    const pluginPkg = ensureFile(pluginPkgPath)
+        ? JSON.parse(fs.readFileSync(pluginPkgPath, "utf-8"))
+        : undefined;
+    const manifest = ensureFile(manifestPath)
+        ? JSON.parse(fs.readFileSync(manifestPath, "utf-8"))
+        : undefined;
+    const activation = manifest?.activation;
+    const checks = {
+        pluginDirExists: fs.existsSync(pluginDir),
+        pluginPackageExists: ensureFile(pluginPkgPath),
+        manifestExists: ensureFile(manifestPath),
+        entryExists: ensureFile(entryPath),
+        packageMainIsIndexJs: pluginPkg?.main === "./index.js",
+        // OpenClaw 2026.5.x discovers the runtime entry via openclaw.runtimeExtensions
+        // in package.json; the legacy manifest.entry field is no longer required.
+        packageRuntimeExtensionsHasIndexJs: Array.isArray(pluginPkg?.openclaw?.runtimeExtensions) &&
+            pluginPkg.openclaw.runtimeExtensions.includes("./index.js"),
+        // contracts: { tools, commands, services } enumerates the agent-facing
+        // surface this plugin contributes. The host does not use it for shape
+        // classification — it just exposes the tools/commands/services to agents
+        // once the plugin is loaded.
+        manifestHasContracts: manifest?.contracts !== undefined &&
+            manifest?.contracts !== null &&
+            typeof manifest.contracts === "object",
+        // CRITICAL — without activation.onStartup the gateway daemon's
+        // loadGatewayStartupPluginPlan will silently skip this plugin (it has no
+        // channel/provider/context-engine slot to ride). onCapabilities mirrors
+        // the discovery allow-list ("provider" | "channel" | "tool" | "hook") and
+        // is our second startup ticket.
+        manifestActivationOnStartupTrue: activation?.onStartup === true,
+        manifestActivationDeclaresToolCapability: Array.isArray(activation?.onCapabilities) &&
+            activation.onCapabilities.includes("tool"),
+    };
+    return {
+        mode: "local-path",
+        ok: Object.values(checks).every(Boolean),
+        installSpec: `file:${pluginDir}`,
+        gatewayRestartRequired: true,
+        manifestPath,
+        entryPath,
+        checks,
+        notes: [
+            `openclaw plugins install file:${pluginDir}`,
+            "openclaw plugins enable second-nature",
+            "openclaw gateway restart",
+            "openclaw plugins status second-nature",
+        ],
+    };
+}
+function clawhubResult() {
+    return {
+        mode: "clawhub",
+        ok: true,
+        installSpec: "clawhub:@second-nature/openclaw-plugin",
+        fallbackOrder: ["clawhub", "npm"],
+        gatewayRestartRequired: true,
+        checks: {
+            installSpecReady: true,
+            fallbackOrderDefined: true,
+        },
+        notes: [
+            "openclaw plugins install clawhub:@second-nature/openclaw-plugin",
+            "if clawhub unresolved: retry with npm:@second-nature/openclaw-plugin",
+            "openclaw gateway restart",
+        ],
+    };
+}
+function npmResult() {
+    return {
+        mode: "npm",
+        ok: true,
+        installSpec: "npm:@second-nature/openclaw-plugin",
+        fallbackOrder: ["npm", "file"],
+        gatewayRestartRequired: true,
+        checks: {
+            installSpecReady: true,
+            fallbackOrderDefined: true,
+        },
+        notes: [
+            "openclaw plugins install npm:@second-nature/openclaw-plugin",
+            "if npm unavailable: fallback to file:./plugin",
+            "openclaw gateway restart",
+        ],
+    };
+}
+function parseMode(rawMode) {
+    if (rawMode === "clawhub")
+        return "clawhub";
+    if (rawMode === "npm")
+        return "npm";
+    return "local-path";
+}
+function run() {
+    const mode = parseMode(process.argv[2]);
+    const root = resolveRoot();
+    let result;
+    if (mode === "clawhub") {
+        result = clawhubResult();
+    }
+    else if (mode === "npm") {
+        result = npmResult();
+    }
+    else {
+        result = localPathResult(root);
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (!result.ok) {
+        process.exitCode = 1;
+    }
+}
+run();

package/dist/src/cli/action-bridge.d.ts

@@ -0,0 +1,11 @@
+import type { StateAPI } from "../storage/state-api.js";
+export interface PolicyWriteInput {
+    platformId: string;
+    socialDailyLimit: number;
+    quietEnabled: boolean;
+}
+export interface ActionBridge {
+    savePolicy(input: PolicyWriteInput): Promise<void>;
+    verifyCredential(platformId: string, answer: string): Promise<void>;
+}
+export declare function createActionBridge(stateApi: StateAPI): ActionBridge;

package/dist/src/cli/index.d.ts

@@ -0,0 +1,65 @@
+import { type ObservabilityDatabase } from "../observability/db/index.js";
+import { type StateDatabase, type StateAPI } from "../storage/index.js";
+import { type ActionBridge } from "./action-bridge.js";
+import { type CliCommandDefinition } from "./commands/index.js";
+import { type CliReadModels } from "./read-models/index.js";
+import type { AppendOnlyAuditStore } from "../observability/audit/append-only-audit-store.js";
+import { type RestoreSnapshotStore } from "../storage/services/restore-snapshot-store.js";
+import { type RuntimeDecisionRecorder } from "../observability/services/runtime-decision-recorder.js";
+import { type ConnectorExecutor } from "../connectors/services/connector-executor-adapter.js";
+import { CapabilityContractRegistry } from "../connectors/base/manifest.js";
+import { type AffordanceAssembler } from "../core/second-nature/body/tool-affordance/affordance-assembler.js";
+import type { NarrativeTimelineDeps } from "../observability/services/narrative-timeline-query-service.js";
+import type { SecretAnchorDeps } from "../observability/services/runtime-secret-anchor-view.js";
+import { type DynamicConnectorRegistry as DynamicConnectorRegistryType } from "../connectors/registry/index.js";
+export interface CommandRouter {
+    commands: CliCommandDefinition[];
+    resolve(name: string): CliCommandDefinition | undefined;
+}
+export interface CommandRouterDeps {
+    commands: CliCommandDefinition[];
+}
+export interface CliRuntimeDeps {
+    stateDb: StateDatabase;
+    observabilityDb: ObservabilityDatabase;
+    stateApi: StateAPI;
+    readModels: CliReadModels;
+    actionBridge: ActionBridge;
+    /** T1.2.3 — write back full-runtime heartbeat cycles into observability so `loadStatus` exits unknown. */
+    runtimeRecorder: RuntimeDecisionRecorder;
+    /** Connector-system executor used by full-runtime heartbeat connector_action intents. */
+    connectorExecutor: ConnectorExecutor;
+    /** Capability registry used by heartbeat planner to avoid platform/capability mismatches. */
+    capabilityRegistry: CapabilityContractRegistry;
+    /** T1.2.3 — DynamicConnectorRegistry for connector:status / connector:test commands. */
+    registry: DynamicConnectorRegistryType;
+    /** T-ROS.C.1 — body-tool affordance map port. */
+    affordanceAssembler: AffordanceAssembler;
+    /** T-ROS.C.1 — narrative timeline query deps. */
+    narrativeTimelineDeps: NarrativeTimelineDeps;
+    /** T-ROS.C.1 — runtime secret anchor health deps. */
+    secretAnchorDeps: SecretAnchorDeps;
+    /** T-ROS.C.1 — bounded restore port used by runtime restore command. */
+    restoreSnapshotStore: RestoreSnapshotStore;
+}
+export interface CreateCommandRouterOptions {
+    deps?: Partial<CliRuntimeDeps>;
+}
+export interface CreateCliRuntimeDepsOptions extends Partial<CliRuntimeDeps> {
+    /** T1.2.7 — pass an explicit audit store so `loadAuditSummary()` reflects test-injected events. */
+    livedExperienceAuditStore?: AppendOnlyAuditStore;
+    workspaceRoot?: string;
+}
+export declare function createCliRuntimeDeps(overrides?: CreateCliRuntimeDepsOptions): CliRuntimeDeps;
+export declare function createCommandRouter(options?: CreateCommandRouterOptions): CommandRouter;
+export declare function closeCliRuntimeDeps(deps: Pick<CliRuntimeDeps, "stateDb" | "observabilityDb">): void;
+export { createOpsRouter, type OpsRouter, type OpsRouterDeps, } from "./ops/ops-router.js";
+export { heartbeatCheck, type HeartbeatSurfaceResult, type HeartbeatSurfaceStatus, type HeartbeatCheckInput, } from "./ops/heartbeat-surface.js";
+export * from "./host-capability/types.js";
+export { classifyDeliveryCapability, type ClassifyDeliveryCapabilityInput, } from "./host-capability/classify-delivery.js";
+export { probeHostCapability } from "./host-capability/probe-host-capability.js";
+export { recordHostCapability } from "./host-capability/record-host-capability.js";
+export { runHostSmoke } from "./host-smoke/run-host-smoke.js";
+export type { HostSmokePlan, HostSmokeReport, HostSmokeCase, HostSmokeCaseResult, } from "./host-smoke/types.js";
+export { explainSurfaceSubject } from "./explain/explain-surface-subject.js";
+export { showOperatorFallback, OperatorFallbackNotFoundError, } from "./ops/show-operator-fallback.js";

package/dist/src/cli/ops/heartbeat-surface.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Stable HeartbeatSurfaceResult for second_nature_ops / CLI (T1.1.3, cli-system / ADR-005).
+ *
+ * S1 scope: carrier / probe / runtime-unavailable / fake control-plane passthrough only.
+ * Workspace full runtime: delegates to `runHeartbeatCycle` when read models are wired (US-001 / CH-09-02).
+ */
+import type { SurfaceMode } from "../runtime/runtime-artifact-boundary.js";
+import type { HeartbeatSignal } from "../../core/second-nature/heartbeat/signal.js";
+import type { CliReadModels } from "../read-models/index.js";
+import type { RuntimeDecisionRecorder } from "../../observability/services/runtime-decision-recorder.js";
+import type { StateDatabase } from "../../storage/db/index.js";
+import type { ConnectorExecutor } from "../../core/second-nature/orchestrator/effect-dispatcher.js";
+import type { CapabilityContractRegistry } from "../../connectors/base/manifest.js";
+import type { AffordanceMap } from "../../shared/types/v7-entities.js";
+import type { ExperienceWriter } from "../../core/second-nature/body/tool-experience/experience-writer.js";
+import type { QuietDreamSchedulePort } from "../../core/second-nature/quiet/run-source-backed-quiet.js";
+import type { HeartbeatDigestAssemblerDeps } from "../../observability/services/heartbeat-digest-assembler.js";
+import type { GoalLifecyclePolicy } from "../../core/second-nature/heartbeat/goal-lifecycle-policy.js";
+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";
+export type HeartbeatSurfaceStatus = "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
+export interface HeartbeatSurfaceResult {
+    ok: boolean;
+    status: HeartbeatSurfaceStatus;
+    surfaceMode: SurfaceMode;
+    decisionId?: string;
+    deliveryAttemptId?: string;
+    capabilityReportRef?: string;
+    fallbackRef?: string;
+    reasons: string[];
+    /** When false, callers must not treat the round as lived-experience loop completion */
+    livedExperienceLoopClaimed: boolean;
+    /** True when structured fields mirror a fake adapter for schema parity only */
+    schemaParityOnly?: boolean;
+}
+export interface HeartbeatCheckInput {
+    probeOnly?: boolean;
+    runtimeAvailable: boolean;
+    fakeControlPlanePassthrough?: Record<string, unknown>;
+    /** When set, full-runtime heartbeat_check runs the control-plane decision loop (US-001). */
+    readModels?: CliReadModels;
+    /** When set, full-runtime cycles are persisted so `loadStatus` exits unknown (T1.2.3). */
+    runtimeRecorder?: RuntimeDecisionRecorder;
+    /**
+     * T2.2.2: when set together with `workspaceRoot`, life evidence from the state DB is loaded
+     * and merged into SnapshotInputs so planner/guard paths see real source-ref truth.
+     */
+    state?: StateDatabase;
+    workspaceRoot?: string;
+    timestamp?: string;
+    sessionContext?: string;
+    scopeHint?: HeartbeatSignal["scopeHint"];
+    /**
+     * When present, guard-allowed connector_action intents are dispatched through the
+     * connector-system instead of returning connector_dispatch_unwired.
+     */
+    connectorExecutor?: ConnectorExecutor;
+    /** Capability registry used by planner to avoid platform/capability protocol mismatches. */
+    connectorRegistry?: CapabilityContractRegistry;
+    /** v7 T-V7C.C.2: affordance map for breaker-aware guard evaluation. */
+    affordanceMap?: AffordanceMap;
+    /** v7 T-V7C.C.2: experience writer for heartbeat connector attempts. */
+    experienceWriter?: ExperienceWriter;
+    /**
+     * v7 T-V7C.C.6: when present, a successful Quiet write auto-triggers Dream scheduling.
+     * Fixes the production-data gap where dream_output_index does not grow after Quiet.
+     */
+    dreamSchedulePort?: QuietDreamSchedulePort;
+    /**
+     * v7 T-V7C.C.6: when present, generates a HeartbeatDigest after each cycle.
+     * Fixes the production-data gap where heartbeat_digest does not grow.
+     */
+    digestOpts?: {
+        assemblerDeps: HeartbeatDigestAssemblerDeps;
+        digestWindowHour?: number;
+    };
+    /** v7 T-CP.C.3: goal lifecycle policy for evaluating goal transitions. */
+    goalLifecyclePolicy?: GoalLifecyclePolicy;
+    /** v7 T-CP.C.3: idle curiosity policy for read-only sensing when no active goals. */
+    idleCuriosityPolicy?: IdleCuriosityPolicy;
+    /** v7 T-BTS.C.5: circuit breaker manager for connector execution health. */
+    circuitBreakerManager?: CircuitBreakerManager;
+}
+export declare function heartbeatCheck(input: HeartbeatCheckInput): Promise<HeartbeatSurfaceResult>;