@haaaiawd/second-nature 0.1.3 → 0.1.5

package/runtime/core/second-nature/heartbeat/heartbeat-loop.js

@@ -0,0 +1,73 @@
+import { buildContinuitySnapshot } from "./snapshot-builder.js";
+import { planIntent } from "../orchestrator/intent-planner.js";
+import { evaluateGuards } from "../orchestrator/guard-layer.js";
+/**
+ * Ingest a heartbeat rhythm signal and drive one full decision round.
+ *
+ * Decision flow:
+ * 1. Build continuity snapshot from state-system inputs
+ * 2. Plan candidate intents from snapshot
+ * 3. Evaluate guards for each candidate in priority order
+ * 4. Return one of:
+ *    - intent_selected: a candidate passed all guards
+ *    - denied: candidates existed but all were rejected by guards
+ *    - heartbeat_ok: no candidates or no action warranted (conservative default)
+ *
+ * Per ADR-005: heartbeat is the free-rhythm main entry; this loop
+ * implements the default conservative path where HEARTBEAT_OK is
+ * the first-class result when no action is warranted.
+ */
+export async function ingestRhythmSignal(signal, deps) {
+    // Step 1: Build continuity snapshot
+    const inputs = await deps.loadSnapshotInputs();
+    const snapshot = buildContinuitySnapshot(inputs);
+    // Step 2: Plan candidate intents
+    const candidates = planIntent(snapshot);
+    // Step 3: Evaluate guards for each candidate (priority order)
+    let hasCandidates = false;
+    let anyAllow = false;
+    const denyReasons = [];
+    for (const intent of candidates) {
+        hasCandidates = true;
+        const evaluation = evaluateGuards(intent, snapshot);
+        if (evaluation.verdict === "allow") {
+            anyAllow = true;
+            return {
+                scope: "rhythm",
+                status: "intent_selected",
+                selectedIntentId: intent.id,
+                reasons: evaluation.reasons,
+            };
+        }
+        denyReasons.push(`${intent.id}:${evaluation.verdict}(${evaluation.reasons.join(",")})`);
+    }
+    // Step 4: No viable intent path
+    if (!hasCandidates) {
+        // No candidates at all → heartbeat_ok (nothing to do)
+        return {
+            scope: "rhythm",
+            status: "heartbeat_ok",
+            reasons: ["no_candidates"],
+        };
+    }
+    if (!anyAllow && denyReasons.length > 0) {
+        // Candidates existed but all denied/deferred/escalated → denied
+        return {
+            scope: "rhythm",
+            status: "denied",
+            reasons: denyReasons,
+        };
+    }
+    // Fallback: conservative heartbeat_ok
+    return {
+        scope: "rhythm",
+        status: "heartbeat_ok",
+        reasons: ["no_allow_verdict"],
+    };
+}
+/**
+ * Build a snapshot directly from inputs (for testing or when state-system is unavailable).
+ */
+export function buildSnapshotFromInputs(inputs) {
+    return buildContinuitySnapshot(inputs);
+}

package/runtime/core/second-nature/heartbeat/index.d.ts

@@ -0,0 +1,5 @@
+export { type RuntimeScope, type RuntimeTrigger, type HeartbeatCycleStatus, type HeartbeatSignal, type ScopedRuntimeInput, type HeartbeatCycleResult, type ScopeRouteResult, } from "./signal.js";
+export { buildContinuitySnapshot, type SnapshotInputs, } from "./snapshot-builder.js";
+export { ingestRhythmSignal, type HeartbeatDeps, buildSnapshotFromInputs, } from "./heartbeat-loop.js";
+export { routeScopedInput, type ScopeRouterDeps, } from "./scope-router.js";
+export { requestGuidanceForIntent, dispatchAllowedEffect, executeHeartbeatCycle, type GuidanceBridgeDeps, type EffectDispatchDeps, type HeartbeatExecutorDeps, type GuidanceBridgeResult, type HeartbeatExecutionResult, } from "./heartbeat-executor.js";

package/runtime/core/second-nature/heartbeat/index.js

@@ -0,0 +1,4 @@
+export { buildContinuitySnapshot, } from "./snapshot-builder.js";
+export { ingestRhythmSignal, buildSnapshotFromInputs, } from "./heartbeat-loop.js";
+export { routeScopedInput, } from "./scope-router.js";
+export { requestGuidanceForIntent, dispatchAllowedEffect, executeHeartbeatCycle, } from "./heartbeat-executor.js";

package/runtime/core/second-nature/heartbeat/scope-router.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scope Signal Router
+ *
+ * Routes incoming signals to the correct runtime scope based on
+ * bridge protocol, entry type, or explicit signal metadata.
+ *
+ * Per ADR-005: runtime scope classification must NOT assume host natural
+ * classification. It depends on explicit signal metadata.
+ *
+ * Three scopes:
+ * - rhythm: heartbeat bridge signals, enters free-rhythm decision chain
+ * - user_task: user explicit tasks, bypasses rhythm gate entirely
+ * - user_reply: direct user replies, only gets very light continuity
+ */
+import type { ScopedRuntimeInput, ScopeRouteResult } from "./signal.js";
+export interface ScopeRouterDeps {
+    /** Optional: additional context for scope resolution */
+    getContext: () => Record<string, unknown>;
+}
+/**
+ * Route a scoped input to the correct runtime chain.
+ *
+ * Classification priority:
+ * 1. Explicit scopeHint from the signal
+ * 2. Trigger type mapping
+ * 3. Default fallback to rhythm for unknown triggers
+ */
+export declare function routeScopedInput(input: ScopedRuntimeInput, _deps?: ScopeRouterDeps): ScopeRouteResult;

package/runtime/core/second-nature/heartbeat/scope-router.js

@@ -0,0 +1,46 @@
+/**
+ * Route a scoped input to the correct runtime chain.
+ *
+ * Classification priority:
+ * 1. Explicit scopeHint from the signal
+ * 2. Trigger type mapping
+ * 3. Default fallback to rhythm for unknown triggers
+ */
+export function routeScopedInput(input, _deps) {
+    // Priority 1: Use explicit scopeHint if provided
+    if (input.scopeHint) {
+        return {
+            scope: input.scopeHint,
+            trigger: input.trigger,
+            handled: true,
+        };
+    }
+    // Priority 2: Map trigger type to scope
+    const scope = triggerToScope(input.trigger);
+    return {
+        scope,
+        trigger: input.trigger,
+        handled: true,
+    };
+}
+/**
+ * Map a trigger type to its default runtime scope.
+ *
+ * This is the fallback when no explicit scopeHint is provided.
+ */
+function triggerToScope(trigger) {
+    switch (trigger) {
+        case "heartbeat_bridge":
+            return "rhythm";
+        case "user_task":
+            return "user_task";
+        case "user_reply":
+            return "user_reply";
+        case "interrupt":
+            return "rhythm";
+        case "resume":
+            return "rhythm";
+        default:
+            return "rhythm";
+    }
+}

package/runtime/core/second-nature/heartbeat/signal.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Heartbeat Signal Contract
+ *
+ * Defines the signal types that enter the control-plane from various sources.
+ * Per ADR-005: runtime scope classification depends on bridge protocol,
+ * entry type, or explicit signal metadata, NOT on host natural classification.
+ */
+export type RuntimeScope = "rhythm" | "user_task" | "user_reply";
+export type RuntimeTrigger = "heartbeat_bridge" | "user_task" | "user_reply" | "interrupt" | "resume";
+export type HeartbeatCycleStatus = "heartbeat_ok" | "intent_selected" | "deferred" | "denied";
+export interface HeartbeatSignal {
+    trigger: RuntimeTrigger;
+    scopeHint?: RuntimeScope;
+    payload: {
+        timestamp: string;
+        sessionContext?: string;
+        heartbeatChecklist?: string;
+    };
+}
+export interface ScopedRuntimeInput {
+    trigger: RuntimeTrigger;
+    scopeHint?: RuntimeScope;
+    payload: Record<string, unknown>;
+}
+export interface HeartbeatCycleResult {
+    scope: "rhythm";
+    status: HeartbeatCycleStatus;
+    selectedIntentId?: string;
+    reasons: string[];
+}
+export interface ScopeRouteResult {
+    scope: RuntimeScope;
+    trigger: RuntimeTrigger;
+    handled: boolean;
+}

package/runtime/core/second-nature/heartbeat/signal.js

@@ -0,0 +1,8 @@
+/**
+ * Heartbeat Signal Contract
+ *
+ * Defines the signal types that enter the control-plane from various sources.
+ * Per ADR-005: runtime scope classification depends on bridge protocol,
+ * entry type, or explicit signal metadata, NOT on host natural classification.
+ */
+export {};

package/runtime/core/second-nature/heartbeat/snapshot-builder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Snapshot Builder
+ *
+ * Builds a ContinuitySnapshot from state-system, workspace, and runtime context.
+ * This is the input preparation step for each heartbeat round.
+ *
+ * Per design doc §4.2: SnapshotBuilder prepares inputs for the Rhythm Engine.
+ */
+import type { ContinuitySnapshot, TopLevelMode } from "../types.js";
+export interface SnapshotInputs {
+    mode: TopLevelMode;
+    currentWindowId: string;
+    pendingObligations: string[];
+    recentOutreachHashes: string[];
+    deniedIntents: Array<{
+        intentHash: string;
+        reason: string;
+        at: string;
+    }>;
+    budgets?: {
+        socialUsed: number;
+        socialLimit: number;
+    };
+    awaitingUserInput?: boolean;
+    riskSuppressed?: boolean;
+}
+/**
+ * Build a ContinuitySnapshot from loaded inputs.
+ *
+ * In production, inputs come from state-system (mode, budgets, obligations),
+ * workspace (outreach hashes, denied intents), and runtime context (window ID).
+ */
+export declare function buildContinuitySnapshot(inputs: SnapshotInputs): ContinuitySnapshot;

package/runtime/core/second-nature/heartbeat/snapshot-builder.js

@@ -0,0 +1,18 @@
+/**
+ * Build a ContinuitySnapshot from loaded inputs.
+ *
+ * In production, inputs come from state-system (mode, budgets, obligations),
+ * workspace (outreach hashes, denied intents), and runtime context (window ID).
+ */
+export function buildContinuitySnapshot(inputs) {
+    return {
+        mode: inputs.mode,
+        currentWindowId: inputs.currentWindowId,
+        pendingObligations: inputs.pendingObligations,
+        recentOutreachHashes: inputs.recentOutreachHashes,
+        deniedIntents: inputs.deniedIntents,
+        budgets: inputs.budgets,
+        awaitingUserInput: inputs.awaitingUserInput,
+        riskSuppressed: inputs.riskSuppressed,
+    };
+}

package/runtime/core/second-nature/runtime/service-entry.js

@@ -26,7 +26,7 @@ export function startRuntimeService(ctx) {
     // - observability-system (event store setup)
     // - control-plane-system (heartbeat bridge preparation)
     const workspaceRoot = ctx?.workspaceRoot ?? process.cwd();
-    const version = "0.1.3";
+    const version = "0.1.0";
     activeHandle = {
         ready: true,
         version,

package/runtime/guidance/guidance-assembler.js

@@ -13,7 +13,7 @@ async function buildAtmosphere(sceneContext) {
     };
 }
 async function selectImpulses(sceneContext) {
-    if (sceneContext.sceneType === "explain") {
+    if (sceneContext.sceneType === "explain" || sceneContext.sceneType === "user_reply") {
         return [];
     }
     return [getImpulseTemplate(sceneContext.sceneType)];

package/runtime/guidance/persona-selection.js

@@ -24,6 +24,11 @@ const SCENE_POLICIES = {
         preferredTags: ["explain", "principle", "context", "truthfulness"],
         budget: { maxSnippets: 2, maxTotalCharacters: 420 },
     },
+    user_reply: {
+        sourcePriority: ["SOUL", "IDENTITY", "USER", "MEMORY"],
+        preferredTags: ["continuity", "tone", "conversation", "authenticity"],
+        budget: { maxSnippets: 2, maxTotalCharacters: 280 },
+    },
 };
 function tagScore(candidate, preferredTags) {
     const normalized = new Set(candidate.tags.map((tag) => tag.toLowerCase()));

package/runtime/guidance/template-registry.d.ts

@@ -1,3 +1,3 @@
 import type { AtmosphereBlock, GuidanceSceneType, ImpulseBlock } from "./types.js";
 export declare function getBaselineAtmosphereTemplate(): Pick<AtmosphereBlock, "kind" | "text" | "reviewStatus">;
-export declare function getImpulseTemplate(sceneType: Exclude<GuidanceSceneType, "explain">): ImpulseBlock;
+export declare function getImpulseTemplate(sceneType: Exclude<GuidanceSceneType, "explain" | "user_reply">): ImpulseBlock;

package/runtime/guidance/types.d.ts

@@ -1,4 +1,4 @@
-export type GuidanceSceneType = "social" | "reply" | "outreach" | "quiet" | "explain";
+export type GuidanceSceneType = "social" | "reply" | "outreach" | "quiet" | "explain" | "user_reply";
 export type GuidanceMode = "active" | "quiet" | "maintenance_only" | "paused_for_interrupt";
 export type GuidanceRiskLevel = "low" | "medium" | "high";
 export type AtmosphereOpenness = "open" | "narrow" | "quiet";

package/runtime/observability/index.d.ts

@@ -2,7 +2,7 @@ export { createObservabilityDatabase, type ObservabilityDatabase } from "./db/in
 export * as obsSchema from "./db/schema/index.js";
 export { REDACTION_CONFIG, DEFAULT_REDACTION_POLICY, getFieldRedactionRule, type RedactionPolicy, type RedactionRule, type SensitivityLevel, } from "./redaction/policy.js";
 export { redactEvent, createEmptyManifest, mergeManifests, type RedactionManifest, type RedactionResult, } from "./redaction/manifest.js";
-export { DecisionLedger, type QuietLifecycleEvent, type OutreachDecision } from "./services/decision-ledger.js";
+export { DecisionLedger, type QuietLifecycleEvent, type OutreachDecision, type HeartbeatDecisionEvent } from "./services/decision-ledger.js";
 export { GovernanceAudit, type CredentialLifecycleAudit } from "./services/governance-audit.js";
 export { ExecutionTelemetry, type ExecutionAttemptInput } from "./services/execution-telemetry.js";
 export { EvidenceQueryEngine, } from "./query/evidence-query-engine.js";

package/runtime/observability/services/decision-ledger.d.ts

@@ -20,10 +20,23 @@ export interface OutreachDecision {
     messagePreview?: string;
     createdAt: string;
 }
+export interface HeartbeatDecisionEvent {
+    id: string;
+    tickId: string;
+    traceId: string;
+    runtimeScope: "rhythm" | "user_task" | "user_reply";
+    triggerSource: "heartbeat_bridge" | "user_task" | "user_reply" | "interrupt" | "resume";
+    decisionStatus: "heartbeat_ok" | "intent_selected" | "denied" | "deferred";
+    reasons: string[];
+    intentId?: string;
+    mode: "active" | "quiet" | "maintenance_only" | "paused_for_interrupt";
+    createdAt: string;
+}
 export declare class DecisionLedger {
     private db;
     constructor(db: ObservabilityDatabase);
     recordDecision(record: DecisionRecord): Promise<void>;
+    recordHeartbeatDecision(event: HeartbeatDecisionEvent): Promise<void>;
     recordQuietLifecycle(event: QuietLifecycleEvent): Promise<void>;
     recordOutreachDecision(event: OutreachDecision): Promise<void>;
     queryByTickId(tickId: string): Promise<DecisionRecord[]>;

package/runtime/observability/services/decision-ledger.js

@@ -26,6 +26,31 @@ export class DecisionLedger {
         });
         await persistRedactionManifest(this.db, redacted.id, "decision.recorded", manifest);
     }
+    async recordHeartbeatDecision(event) {
+        const { redacted, manifest } = redactEvent(event);
+        // Map decisionStatus to existing verdict field without changing business semantics
+        const verdict = mapHeartbeatStatusToVerdict(redacted.decisionStatus);
+        await this.db.db.insert(decisionLedger).values({
+            id: redacted.id,
+            tickId: redacted.tickId,
+            traceId: redacted.traceId,
+            intentId: redacted.intentId ?? null,
+            platformId: null,
+            verdict,
+            mode: redacted.mode,
+            reasons: JSON.stringify(redacted.reasons),
+            reasonCodes: JSON.stringify(["heartbeat_decision"]),
+            decisionBasis: "rule_only",
+            evidenceRefs: JSON.stringify([
+                `scope:${redacted.runtimeScope}`,
+                `trigger:${redacted.triggerSource}`,
+                `status:${redacted.decisionStatus}`,
+            ].filter(Boolean)),
+            modelEvalRef: null,
+            createdAt: redacted.createdAt,
+        });
+        await persistRedactionManifest(this.db, redacted.id, "heartbeat.decision", manifest);
+    }
     async recordQuietLifecycle(event) {
         const { redacted, manifest } = redactEvent(event);
         await this.db.db.insert(decisionLedger).values({
@@ -113,3 +138,20 @@ export class DecisionLedger {
         };
     }
 }
+/**
+ * Map heartbeat decision status to existing verdict field.
+ * This preserves the existing DecisionRecord semantics while allowing
+ * heartbeat-specific status to be recoverable from evidenceRefs.
+ */
+function mapHeartbeatStatusToVerdict(status) {
+    switch (status) {
+        case "intent_selected":
+            return "allow";
+        case "denied":
+            return "deny";
+        case "deferred":
+            return "defer";
+        case "heartbeat_ok":
+            return "defer";
+    }
+}

package/index.ts

@@ -1,200 +0,0 @@
-import { createRequire } from "node:module";
-
-interface RegisterApi {
-  registerService(service: { id: string; start: () => unknown }): void;
-  registerCli(registrar: (ctx: { program: unknown }) => void, options?: { commands?: string[] }): void;
-  registerCommand(command: {
-    name: string;
-    description: string;
-    acceptsArgs?: boolean;
-    handler: (ctx: { args?: string }) => Promise<{ text: string }> | { text: string };
-  }): void;
-  registerTool(tool: unknown, options?: unknown): void;
-}
-
-function createFallbackCommands(): Array<{
-  name: string;
-  description: string;
-  execute: (input?: Record<string, unknown>) => Promise<Record<string, unknown>>;
-}> {
-  const commandNames = ["status", "policy", "credential", "quiet", "report", "session", "audit", "explain"];
-
-  return commandNames.map((name) => ({
-    name,
-    description: `Fallback command shell for ${name}`,
-    execute: async (_input?: Record<string, unknown>) => ({
-      ok: false,
-      command: name,
-      message: "Plugin loaded in packaging fallback mode; reinstall full workspace build for command runtime.",
-    }),
-  }));
-}
-
-function resolveCommandRouterSafe(): {
-  commands: Array<{ name: string; description: string; execute: (input?: Record<string, unknown>) => Promise<Record<string, unknown>> }>;
-  resolve(name: string): { name: string; description: string; execute: (input?: Record<string, unknown>) => Promise<Record<string, unknown>> } | undefined;
-} {
-  const require = createRequire(import.meta.url);
-
-  try {
-    const mod = require("./runtime/cli/index.js") as { createCommandRouter: () => { commands: any[]; resolve: (name: string) => any } };
-    if (mod?.createCommandRouter) {
-      return mod.createCommandRouter();
-    }
-  } catch {
-    // fall through to fallback router
-  }
-
-  const commands = createFallbackCommands();
-  return {
-    commands,
-    resolve(name: string) {
-      return commands.find((command) => command.name === name);
-    },
-  };
-}
-
-function createRuntimeService(): { id: string; start: () => unknown } {
-  const require = createRequire(import.meta.url);
-
-  try {
-    const runtimeMod = require("./runtime/core/second-nature/runtime/service-entry.js") as {
-      startRuntimeService: (ctx?: Record<string, unknown>) => { ready: boolean; version: string; close: () => void };
-    };
-
-    if (runtimeMod?.startRuntimeService) {
-      const handle = runtimeMod.startRuntimeService();
-      return {
-        id: "second-nature-runtime",
-        start() {
-          return { ready: handle.ready, version: handle.version };
-        },
-      };
-    }
-  } catch {
-    // fall through to minimal service shell
-  }
-
-  return {
-    id: "second-nature-runtime",
-    start() {
-      return { ready: true, version: "0.1.3-minimal" };
-    },
-  };
-}
-
-function createLifecycleService(): { id: string; start: () => unknown } {
-  const require = createRequire(import.meta.url);
-
-  try {
-    const lifecycleMod = require("./runtime/core/second-nature/runtime/lifecycle-service.js") as {
-      recordRegistration: () => { registerCount: number; phase: string; lastChangedAt: number };
-    };
-
-    if (lifecycleMod?.recordRegistration) {
-      return {
-        id: "second-nature-lifecycle",
-        start() {
-          const state = lifecycleMod.recordRegistration();
-          return { phase: state.phase, registerCount: state.registerCount };
-        },
-      };
-    }
-  } catch {
-    // fall through to minimal lifecycle shell
-  }
-
-  let registerCount = 0;
-  return {
-    id: "second-nature-lifecycle",
-    start() {
-      registerCount += 1;
-      return { phase: registerCount === 1 ? "loading" : "reloading", registerCount };
-    },
-  };
-}
-
-export default {
-  id: "second-nature",
-  name: "Second Nature",
-  description: "Registers command/tool/service surface with load-reload lifecycle semantics.",
-  register(api: RegisterApi) {
-    const router = resolveCommandRouterSafe();
-    const runtimeService = createRuntimeService();
-    const lifecycleService = createLifecycleService();
-
-    api.registerService(runtimeService);
-    api.registerService(lifecycleService);
-
-    api.registerCli(
-      ({ program }) => {
-        void program;
-      },
-      { commands: ["second-nature"] },
-    );
-
-    api.registerCommand({
-      name: "second-nature",
-      description: "Route Agent-facing operational commands for Second Nature.",
-      acceptsArgs: true,
-      handler: async (ctx: { args?: string }) => {
-        const command = ctx.args?.trim();
-        if (!command) {
-          return {
-            text: JSON.stringify({ ok: false, message: "Missing command argument." }),
-          };
-        }
-
-        const resolved = router.resolve(command);
-        if (!resolved) {
-          return {
-            text: JSON.stringify({ ok: false, command, message: "Unknown Second Nature command." }),
-          };
-        }
-
-        const result = await resolved.execute();
-        return {
-          text: JSON.stringify(result),
-        };
-      },
-    });
-
-    api.registerTool({
-      name: "second_nature_ops",
-      description: "Access the Second Nature command surface through a single tool shell.",
-      parameters: {
-        type: "object",
-        additionalProperties: false,
-        properties: {
-          command: { type: "string" },
-          args: { type: "object", additionalProperties: true }
-        },
-        required: ["command"]
-      },
-      async execute(_id: string, params: { command: string; args?: Record<string, unknown> }) {
-        const resolved = router.resolve(params.command);
-        if (!resolved) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify({ ok: false, message: "Unknown Second Nature command." }),
-              },
-            ],
-          };
-        }
-
-        const result = await resolved.execute(params.args);
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result),
-            },
-          ],
-        };
-      },
-    });
-  },
-};