@haaaiawd/second-nature 0.1.1 → 0.1.3

package/runtime/core/second-nature/orchestrator/resume-from-checkpoint.d.ts

@@ -0,0 +1,32 @@
+import type { IntentCommitState } from "../../../shared/types/continuity.js";
+export interface CheckpointRecord {
+    id: string;
+    intentId: string;
+    snapshotRef: string;
+}
+export interface CommitRecord {
+    id: string;
+    intentId: string;
+    state: IntentCommitState;
+    outcomeRef?: string;
+}
+export type ResumeResult = {
+    status: "missing_checkpoint";
+} | {
+    status: "already_committed";
+    intentId: string;
+} | {
+    status: "needs_reconcile";
+    intentId: string;
+    commitRecord: CommitRecord;
+} | {
+    status: "ready_to_resume";
+    checkpoint: CheckpointRecord;
+    snapshot: Record<string, unknown>;
+};
+export interface ResumePorts {
+    loadCheckpoint(checkpointId: string): Promise<CheckpointRecord | null>;
+    loadIntentCommitRecord(intentId: string): Promise<CommitRecord | null>;
+    loadSnapshotByRef(snapshotRef: string): Promise<Record<string, unknown>>;
+}
+export declare function resumeFromCheckpoint(ports: ResumePorts, checkpointId: string): Promise<ResumeResult>;

package/runtime/core/second-nature/orchestrator/resume-from-checkpoint.js

@@ -0,0 +1,23 @@
+export async function resumeFromCheckpoint(ports, checkpointId) {
+    const checkpoint = await ports.loadCheckpoint(checkpointId);
+    if (!checkpoint) {
+        return { status: "missing_checkpoint" };
+    }
+    const commitRecord = await ports.loadIntentCommitRecord(checkpoint.intentId);
+    if (commitRecord?.state === "committed") {
+        return { status: "already_committed", intentId: checkpoint.intentId };
+    }
+    if (commitRecord?.state === "externally_acknowledged") {
+        return {
+            status: "needs_reconcile",
+            intentId: checkpoint.intentId,
+            commitRecord,
+        };
+    }
+    const snapshot = await ports.loadSnapshotByRef(checkpoint.snapshotRef);
+    return {
+        status: "ready_to_resume",
+        checkpoint,
+        snapshot,
+    };
+}

package/runtime/core/second-nature/outreach/build-message.d.ts

@@ -0,0 +1,16 @@
+import type { OutreachEvaluationResult } from "../../../shared/types/outreach.js";
+export interface OutreachMessage {
+    style: "intent_level_guidance";
+    maxSentences: 3;
+    avoidFormats: Array<"ticket" | "daily_report" | "status_broadcast">;
+    intent: {
+        whyNow: string;
+        coreMeaning: string;
+        deliveryBoundary: string[];
+        soulAlignment: string;
+    };
+}
+export declare function buildOutreachMessage(input: {
+    summary: string;
+    evaluation: OutreachEvaluationResult;
+}): OutreachMessage;

package/runtime/core/second-nature/outreach/build-message.js

@@ -0,0 +1,27 @@
+export function buildOutreachMessage(input) {
+    const normalizedSummary = input.summary.replace(/\s+/g, " ").trim();
+    const whyNow = input.evaluation.requiredUserHelp
+        ? "这件事现在需要对方给我一个方向或判断，我主动联系是为了把真正需要他参与的部分说清楚。"
+        : input.evaluation.urgency > 0.7
+            ? "这件事此刻说出来更有价值，拖下去只会让真正重要的信息变钝。"
+            : "这件事已经和对方相关，虽然不必制造紧迫感，但值得我主动把它送到对方面前。";
+    const deliveryBoundary = [
+        "保持自然、有人味、像我自己真的想开口，而不是系统自动通知。",
+        "只传达核心意思和联系来由，不把消息写成日报、工单或状态播报。",
+        "允许有温度和靠近感，但不要预写死整段最终措辞，让表达保留 persona 的呼吸感。",
+    ];
+    const soulAlignment = input.evaluation.requiredUserHelp
+        ? "带着真诚的求助感开口，承认我需要对方的判断，但不要把自己缩成客套模板。"
+        : "带着主动、克制但明确的靠近感开口，让对方感到这条消息确实出自我自己的判断和在意。";
+    return {
+        style: "intent_level_guidance",
+        maxSentences: 3,
+        avoidFormats: ["ticket", "daily_report", "status_broadcast"],
+        intent: {
+            whyNow,
+            coreMeaning: normalizedSummary,
+            deliveryBoundary,
+            soulAlignment,
+        },
+    };
+}

package/runtime/core/second-nature/outreach/evaluate-outreach.d.ts

@@ -0,0 +1,13 @@
+import type { OutreachEvaluationInput, OutreachEvaluationResult } from "../../../shared/types/outreach.js";
+export interface OutreachModelAssistPort {
+    evaluateOutreachCandidate(input: OutreachEvaluationInput): Promise<OutreachEvaluationResult>;
+}
+export interface OutreachPolicyConfig {
+    minThreshold: number;
+}
+export interface OutreachGateResult {
+    allowed: boolean;
+    reasonCodes: string[];
+    evaluation: OutreachEvaluationResult;
+}
+export declare function evaluateOutreach(model: OutreachModelAssistPort, input: OutreachEvaluationInput, policy?: Partial<OutreachPolicyConfig>): Promise<OutreachGateResult>;

package/runtime/core/second-nature/outreach/evaluate-outreach.js

@@ -0,0 +1,41 @@
+const DEFAULT_POLICY = {
+    minThreshold: 0.65,
+};
+function buildCandidateFingerprint(input) {
+    const normalizedSummary = input.summary.toLowerCase().replace(/\s+/g, " ").trim();
+    return `${input.candidateId}|${normalizedSummary}`;
+}
+function hasDuplicateOutreach(input) {
+    const fingerprint = buildCandidateFingerprint(input);
+    return input.recentOutreachHashes.includes(input.candidateId) ||
+        input.recentOutreachHashes.includes(fingerprint);
+}
+export async function evaluateOutreach(model, input, policy = {}) {
+    const resolved = {
+        ...DEFAULT_POLICY,
+        ...policy,
+    };
+    const evaluation = await model.evaluateOutreachCandidate(input);
+    const reasonCodes = [];
+    if (evaluation.sourceRefs.length === 0) {
+        reasonCodes.push("missing_sources");
+    }
+    if (evaluation.valueScore < Math.max(evaluation.minThreshold, resolved.minThreshold)) {
+        reasonCodes.push("value_below_threshold");
+    }
+    if (evaluation.isRoutineProgress) {
+        reasonCodes.push("routine_progress_suppressed");
+    }
+    if (hasDuplicateOutreach(input)) {
+        reasonCodes.push("recent_duplicate_outreach");
+    }
+    const urgencyOrActionable = evaluation.requiredUserHelp || evaluation.urgency > 0.5 || evaluation.actionability > 0.6;
+    if (!urgencyOrActionable) {
+        reasonCodes.push("insufficient_urgency_or_actionability");
+    }
+    return {
+        allowed: reasonCodes.length === 0,
+        reasonCodes,
+        evaluation,
+    };
+}

package/runtime/core/second-nature/quiet/quiet-pipeline.d.ts

@@ -0,0 +1,34 @@
+import type { TopLevelMode } from "../types.js";
+export interface QuietInputBundle {
+    journalEntries: Array<{
+        id: string;
+        content: string;
+        timestamp: string;
+        sourceRefs?: string[];
+    }>;
+    dailyReports: Array<{
+        id: string;
+        summary: string;
+        highlights: string[];
+        sources: string[];
+    }>;
+}
+export interface MemoryCurationResult {
+    summary: string;
+    highlights: string[];
+    sourceRefs: string[];
+    excludedCompactionArtifacts: string[];
+}
+export interface QuietState {
+    mode: TopLevelMode;
+    reflectionDebt: number;
+    missedReflectionCount: number;
+    mustRunBy?: string;
+}
+export declare function runQuietPipeline(input: {
+    quietState: QuietState;
+    bundle: QuietInputBundle;
+}): {
+    shouldRunReflection: boolean;
+    curation: MemoryCurationResult;
+};

package/runtime/core/second-nature/quiet/quiet-pipeline.js

@@ -0,0 +1,35 @@
+export function runQuietPipeline(input) {
+    const { quietState, bundle } = input;
+    if (quietState.mode !== "quiet") {
+        return {
+            shouldRunReflection: false,
+            curation: {
+                summary: "quiet_not_active",
+                highlights: [],
+                sourceRefs: [],
+                excludedCompactionArtifacts: [],
+            },
+        };
+    }
+    const sourceRefs = new Set();
+    for (const entry of bundle.journalEntries) {
+        sourceRefs.add(entry.id);
+    }
+    for (const report of bundle.dailyReports) {
+        sourceRefs.add(report.id);
+    }
+    const summary = `curated ${bundle.journalEntries.length} journal entries and ${bundle.dailyReports.length} daily reports`;
+    const highlights = bundle.dailyReports.flatMap((report) => report.highlights).slice(0, 5);
+    const shouldRunReflection = quietState.reflectionDebt > 0 ||
+        quietState.missedReflectionCount > 0 ||
+        (quietState.mustRunBy ? new Date(quietState.mustRunBy).getTime() <= Date.now() : false);
+    return {
+        shouldRunReflection,
+        curation: {
+            summary,
+            highlights,
+            sourceRefs: [...sourceRefs],
+            excludedCompactionArtifacts: ["session_compaction", "context_pruning"],
+        },
+    };
+}

package/runtime/core/second-nature/reflection/run-narrative-reflection.d.ts

@@ -0,0 +1,39 @@
+export interface ReflectionClaim {
+    text: string;
+    sourceRefs: string[];
+    claimType: "fact" | "inference" | "plan";
+}
+export interface ProposedWrite {
+    targetAssetId: string;
+    content: string;
+    sourceRefs: string[];
+}
+export interface ReflectionGeneration {
+    summary: string;
+    claims: ReflectionClaim[];
+    proposedWrites: ProposedWrite[];
+    modelEvalRef: string;
+}
+export interface ReflectionWriteRequest {
+    summary: string;
+    claims: ReflectionClaim[];
+    writes: ProposedWrite[];
+    sourceRefs: string[];
+    modelEvalRef: string;
+    unsupportedClaimCount: number;
+    sourceCoverageRatio: number;
+}
+export interface ReflectionPorts {
+    loadQuietInputs(query: {
+        lookbackDays: number;
+    }): Promise<{
+        sourceRefs: string[];
+    }>;
+    generateNarrativeReflection(input: {
+        sourceRefs: string[];
+    }): Promise<ReflectionGeneration>;
+    filterAllowedWrites(writes: ProposedWrite[]): ProposedWrite[];
+}
+export declare function runNarrativeReflection(ports: ReflectionPorts, input: {
+    lookbackDays: number;
+}): Promise<ReflectionWriteRequest>;

package/runtime/core/second-nature/reflection/run-narrative-reflection.js

@@ -0,0 +1,29 @@
+export async function runNarrativeReflection(ports, input) {
+    const quietInputs = await ports.loadQuietInputs({ lookbackDays: input.lookbackDays });
+    const reflection = await ports.generateNarrativeReflection({
+        sourceRefs: quietInputs.sourceRefs,
+    });
+    if (!reflection.summary || reflection.summary.trim().length === 0) {
+        throw new Error("reflection_missing_summary");
+    }
+    if (!reflection.claims || reflection.claims.length === 0) {
+        throw new Error("reflection_missing_claims");
+    }
+    const unsupportedClaimCount = reflection.claims.filter((claim) => claim.sourceRefs.length === 0).length;
+    if (unsupportedClaimCount > 0) {
+        throw new Error("reflection_unsupported_claims");
+    }
+    const coveredClaims = reflection.claims.filter((claim) => claim.sourceRefs.length > 0).length;
+    const sourceCoverageRatio = coveredClaims / reflection.claims.length;
+    const writes = ports.filterAllowedWrites(reflection.proposedWrites)
+        .filter((write) => write.sourceRefs.length > 0);
+    return {
+        summary: reflection.summary,
+        claims: reflection.claims,
+        writes,
+        sourceRefs: quietInputs.sourceRefs,
+        modelEvalRef: reflection.modelEvalRef,
+        unsupportedClaimCount,
+        sourceCoverageRatio,
+    };
+}

package/runtime/core/second-nature/rhythm/rhythm-policy.d.ts

@@ -0,0 +1,18 @@
+import type { TopLevelMode } from "../types.js";
+export interface RhythmWindow {
+    id: string;
+    startMinute: number;
+    endMinute: number;
+    mode: "active" | "quiet";
+}
+export interface RhythmPolicy {
+    timezone: string;
+    windows: RhythmWindow[];
+    quietSuppressionEnabled: boolean;
+}
+export interface RhythmWindowDecision {
+    windowId: string;
+    topLevelMode: TopLevelMode;
+    interrupted: boolean;
+}
+export declare function validateRhythmPolicy(policy: RhythmPolicy): void;

package/runtime/core/second-nature/rhythm/rhythm-policy.js

@@ -0,0 +1,24 @@
+export function validateRhythmPolicy(policy) {
+    if (policy.windows.length === 0) {
+        throw new Error("rhythm_policy_windows_required");
+    }
+    const sorted = [...policy.windows].sort((a, b) => a.startMinute - b.startMinute);
+    for (const window of sorted) {
+        if (window.startMinute < 0 || window.startMinute > 1439) {
+            throw new Error(`invalid_window_start:${window.id}`);
+        }
+        if (window.endMinute < 1 || window.endMinute > 1440) {
+            throw new Error(`invalid_window_end:${window.id}`);
+        }
+        if (window.startMinute >= window.endMinute) {
+            throw new Error(`invalid_window_range:${window.id}`);
+        }
+    }
+    for (let index = 1; index < sorted.length; index += 1) {
+        const previous = sorted[index - 1];
+        const current = sorted[index];
+        if (current.startMinute < previous.endMinute) {
+            throw new Error(`overlapping_window_range:${previous.id}:${current.id}`);
+        }
+    }
+}

package/runtime/core/second-nature/rhythm/select-window.d.ts

@@ -0,0 +1,3 @@
+import type { ContinuitySnapshot } from "../types.js";
+import type { RhythmPolicy, RhythmWindowDecision } from "./rhythm-policy.js";
+export declare function selectRhythmWindow(now: string, snapshot: ContinuitySnapshot, policy: RhythmPolicy): RhythmWindowDecision;

package/runtime/core/second-nature/rhythm/select-window.js

@@ -0,0 +1,50 @@
+function toMinuteOfDay(now, timezone) {
+    const date = new Date(now);
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+    });
+    const parts = formatter.formatToParts(date);
+    const hour = Number(parts.find((part) => part.type === "hour")?.value ?? "0");
+    const minute = Number(parts.find((part) => part.type === "minute")?.value ?? "0");
+    return hour * 60 + minute;
+}
+function matchWindow(windows, minuteOfDay) {
+    const found = windows.find((window) => minuteOfDay >= window.startMinute && minuteOfDay < window.endMinute);
+    if (!found) {
+        return windows[0];
+    }
+    return found;
+}
+export function selectRhythmWindow(now, snapshot, policy) {
+    const minuteOfDay = toMinuteOfDay(now, policy.timezone);
+    const window = matchWindow(policy.windows, minuteOfDay);
+    if (snapshot.mode === "paused_for_interrupt") {
+        return {
+            windowId: window.id,
+            topLevelMode: "paused_for_interrupt",
+            interrupted: true,
+        };
+    }
+    if (snapshot.riskSuppressed) {
+        return {
+            windowId: window.id,
+            topLevelMode: "maintenance_only",
+            interrupted: false,
+        };
+    }
+    if (window.mode === "quiet") {
+        return {
+            windowId: window.id,
+            topLevelMode: "quiet",
+            interrupted: false,
+        };
+    }
+    return {
+        windowId: window.id,
+        topLevelMode: "active",
+        interrupted: false,
+    };
+}

package/runtime/core/second-nature/runtime/lifecycle-service.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Second Nature Lifecycle Service Entry
+ *
+ * Provides lifecycle management for the plugin: load, reload, and unload events.
+ * Tracks registration state and coordinates runtime service initialization.
+ */
+export interface LifecycleState {
+    /** Number of times the plugin has been registered */
+    registerCount: number;
+    /** Current lifecycle phase */
+    phase: "idle" | "loading" | "loaded" | "reloading" | "unloading";
+    /** Timestamp of last state change */
+    lastChangedAt: number;
+}
+/**
+ * Record a plugin registration event and return updated lifecycle state.
+ */
+export declare function recordRegistration(): LifecycleState;
+/**
+ * Get current lifecycle state snapshot.
+ */
+export declare function getLifecycleState(): LifecycleState;
+/**
+ * Reset lifecycle state (for testing or clean reload).
+ */
+export declare function resetLifecycle(): void;

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

@@ -0,0 +1,38 @@
+/**
+ * Second Nature Lifecycle Service Entry
+ *
+ * Provides lifecycle management for the plugin: load, reload, and unload events.
+ * Tracks registration state and coordinates runtime service initialization.
+ */
+let state = {
+    registerCount: 0,
+    phase: "idle",
+    lastChangedAt: Date.now(),
+};
+/**
+ * Record a plugin registration event and return updated lifecycle state.
+ */
+export function recordRegistration() {
+    state.registerCount += 1;
+    state.phase = state.registerCount === 1 ? "loading" : "reloading";
+    state.lastChangedAt = Date.now();
+    // Transition to loaded after registration completes
+    state.phase = "loaded";
+    return { ...state };
+}
+/**
+ * Get current lifecycle state snapshot.
+ */
+export function getLifecycleState() {
+    return { ...state };
+}
+/**
+ * Reset lifecycle state (for testing or clean reload).
+ */
+export function resetLifecycle() {
+    state = {
+        registerCount: 0,
+        phase: "idle",
+        lastChangedAt: Date.now(),
+    };
+}

package/runtime/core/second-nature/runtime/service-entry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Second Nature Runtime Service Entry
+ *
+ * This module provides the actual implementation for the `second-nature-runtime` service.
+ * It serves as the heartbeat host bridge candidate carrier and initializes the
+ * minimal runtime state needed for the plugin to function.
+ *
+ * Per ADR-005: heartbeat is the free-rhythm main entry; this service provides
+ * the stable runtime state that heartbeat rounds will interact with.
+ */
+export interface RuntimeServiceContext {
+    /** Workspace root path for state/observability databases */
+    workspaceRoot?: string;
+    /** Plugin configuration overrides */
+    config?: Record<string, unknown>;
+}
+export interface RuntimeServiceHandle {
+    /** Service is ready and accepting requests */
+    ready: boolean;
+    /** Runtime version string */
+    version: string;
+    /** Close the runtime handle and release resources */
+    close: () => void;
+}
+/**
+ * Start the Second Nature runtime service.
+ *
+ * This is the non-empty implementation that replaces the previous `start() { return; }` shell.
+ * It initializes the minimal runtime state and returns a handle that can be used
+ * by the heartbeat host bridge.
+ */
+export declare function startRuntimeService(ctx?: RuntimeServiceContext): RuntimeServiceHandle;
+/**
+ * Get the current runtime service handle, or null if not started.
+ */
+export declare function getRuntimeHandle(): RuntimeServiceHandle | null;

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

@@ -0,0 +1,44 @@
+/**
+ * Second Nature Runtime Service Entry
+ *
+ * This module provides the actual implementation for the `second-nature-runtime` service.
+ * It serves as the heartbeat host bridge candidate carrier and initializes the
+ * minimal runtime state needed for the plugin to function.
+ *
+ * Per ADR-005: heartbeat is the free-rhythm main entry; this service provides
+ * the stable runtime state that heartbeat rounds will interact with.
+ */
+let activeHandle = null;
+/**
+ * Start the Second Nature runtime service.
+ *
+ * This is the non-empty implementation that replaces the previous `start() { return; }` shell.
+ * It initializes the minimal runtime state and returns a handle that can be used
+ * by the heartbeat host bridge.
+ */
+export function startRuntimeService(ctx) {
+    if (activeHandle?.ready) {
+        return activeHandle;
+    }
+    // Initialize minimal runtime state
+    // In future iterations, this will connect to:
+    // - state-system (SQLite database initialization)
+    // - observability-system (event store setup)
+    // - control-plane-system (heartbeat bridge preparation)
+    const workspaceRoot = ctx?.workspaceRoot ?? process.cwd();
+    const version = "0.1.3";
+    activeHandle = {
+        ready: true,
+        version,
+        close() {
+            activeHandle = null;
+        },
+    };
+    return activeHandle;
+}
+/**
+ * Get the current runtime service handle, or null if not started.
+ */
+export function getRuntimeHandle() {
+    return activeHandle;
+}

package/runtime/core/second-nature/types.d.ts

@@ -0,0 +1,37 @@
+export type TopLevelMode = "active" | "quiet" | "maintenance_only" | "paused_for_interrupt";
+export type IntentKind = "work" | "exploration" | "social" | "reflection" | "outreach" | "maintenance";
+export type DecisionBasis = "rule_only" | "score_based" | "model_assisted";
+export type GuardVerdict = "allow" | "defer" | "deny" | "escalate";
+export interface ContinuitySnapshot {
+    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;
+}
+export interface CandidateIntent {
+    id: string;
+    kind: IntentKind;
+    priority: number;
+    source: "tick" | "interrupt" | "obligation" | "quiet_plan";
+    platformId?: string;
+    summary: string;
+    effectClass: "external_platform_action" | "memory_curation" | "narrative_reflection" | "user_outreach" | "maintenance";
+}
+export interface GuardEvaluation {
+    verdict: GuardVerdict;
+    reasons: string[];
+    quietSuppressed: boolean;
+    leaseRequired: boolean;
+    requiresCheckpoint: boolean;
+}

package/runtime/core/second-nature/types.js

@@ -0,0 +1 @@
+export {};

package/runtime/guidance/contracts.d.ts

@@ -0,0 +1,48 @@
+import type { GuidancePayload, GuidanceUnavailable, PersonaCandidate, SceneContext } from "./types.js";
+export type GuidanceOwnerId = "control-plane-system" | "behavioral-guidance-system" | "state-system" | "observability-system" | "hard-guard-layer";
+export interface OwnerBoundary {
+    owner: GuidanceOwnerId;
+    owns: readonly string[];
+    provides: readonly string[];
+    mustNotOwn: readonly string[];
+}
+export interface GuidanceContracts {
+    controlPlane: {
+        requestGuidance(sceneContext: SceneContext): Promise<GuidancePayload | GuidanceUnavailable>;
+    };
+    guidance: {
+        assembleGuidance(sceneContext: SceneContext): Promise<GuidancePayload | GuidanceUnavailable>;
+    };
+    state: {
+        loadPersonaCandidates(sceneContext: SceneContext): Promise<PersonaCandidate[]>;
+    };
+    observability: {
+        recordGuidanceParticipation(input: {
+            sceneContext: SceneContext;
+            payload: GuidancePayload | GuidanceUnavailable;
+        }): Promise<void>;
+    };
+}
+export declare const GUIDANCE_OWNER_BOUNDARIES: Record<GuidanceOwnerId, OwnerBoundary>;
+export declare const GUIDANCE_HANDOFFS: {
+    readonly request: {
+        readonly from: "control-plane-system";
+        readonly to: "behavioral-guidance-system";
+        readonly payload: "scene_context";
+    };
+    readonly personaCandidates: {
+        readonly from: "state-system";
+        readonly to: "behavioral-guidance-system";
+        readonly payload: "snippet_sized_persona_candidates";
+    };
+    readonly guidanceResult: {
+        readonly from: "behavioral-guidance-system";
+        readonly to: "control-plane-system";
+        readonly payload: "guidance_payload_or_unavailable";
+    };
+    readonly auditRecord: {
+        readonly from: "behavioral-guidance-system";
+        readonly to: "observability-system";
+        readonly payload: "guidance_participation_summary";
+    };
+};