@haaaiawd/second-nature 0.1.26 → 0.1.29

package/runtime/core/second-nature/body/behavior-promotion/behavior-promotion-loop.d.ts

@@ -0,0 +1,45 @@
+/**
+ * BehaviorPromotionLoop — T-BTS.C.3
+ *
+ * Core logic: Operator-authorized behavior suggestion lifecycle.
+ * - candidate → approved (idempotent: repeated approve returns existing)
+ * - candidate → rejected (with reason)
+ * - candidate → expired (7 days TTL from submission)
+ * - rejected/expired are read-only; new submit creates a fresh candidate
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../../../../storage/db/index.js`
+ *
+ * Boundary:
+ * - Does NOT grant execution authorization; approval is a bookkeeping signal.
+ * - Only accepts operator-authorized suggestions, not connector auto-probe results.
+ *
+ * Test coverage: tests/unit/body/behavior-promotion-loop.test.ts
+ */
+import type { StateDatabase } from "../../../../storage/db/index.js";
+export type PromotionStatus = "candidate" | "approved" | "rejected" | "expired";
+export interface BehaviorPromotion {
+    promotionId: string;
+    behaviorKind: string;
+    description: string;
+    status: PromotionStatus;
+    operatorId?: string;
+    rejectReason?: string;
+    submittedAt: string;
+    decidedAt?: string;
+    expiresAt: string;
+}
+export interface BehaviorPromotionLoop {
+    submitPromotion(input: {
+        promotionId: string;
+        behaviorKind: string;
+        description: string;
+        operatorId?: string;
+    }): Promise<BehaviorPromotion>;
+    approvePromotion(promotionId: string): Promise<BehaviorPromotion>;
+    rejectPromotion(promotionId: string, reason: string): Promise<BehaviorPromotion>;
+    loadPromotion(promotionId: string): Promise<BehaviorPromotion | undefined>;
+    listPromotions(status?: PromotionStatus): Promise<BehaviorPromotion[]>;
+    expireStaleCandidates(): Promise<number>;
+}
+export declare function createBehaviorPromotionLoop(database: StateDatabase): BehaviorPromotionLoop;

package/runtime/core/second-nature/body/behavior-promotion/behavior-promotion-loop.js

@@ -0,0 +1,132 @@
+/**
+ * BehaviorPromotionLoop — T-BTS.C.3
+ *
+ * Core logic: Operator-authorized behavior suggestion lifecycle.
+ * - candidate → approved (idempotent: repeated approve returns existing)
+ * - candidate → rejected (with reason)
+ * - candidate → expired (7 days TTL from submission)
+ * - rejected/expired are read-only; new submit creates a fresh candidate
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../../../../storage/db/index.js`
+ *
+ * Boundary:
+ * - Does NOT grant execution authorization; approval is a bookkeeping signal.
+ * - Only accepts operator-authorized suggestions, not connector auto-probe results.
+ *
+ * Test coverage: tests/unit/body/behavior-promotion-loop.test.ts
+ */
+const DEFAULT_TTL_DAYS = 7;
+function rowToPromotion(row, cols) {
+    const get = (name) => row[cols.indexOf(name)];
+    return {
+        promotionId: get("promotion_id"),
+        behaviorKind: get("behavior_kind"),
+        description: get("description"),
+        status: get("status"),
+        operatorId: get("operator_id") ?? undefined,
+        rejectReason: get("reject_reason") ?? undefined,
+        submittedAt: get("submitted_at"),
+        decidedAt: get("decided_at") ?? undefined,
+        expiresAt: get("expires_at"),
+    };
+}
+export function createBehaviorPromotionLoop(database) {
+    const { sqlite } = database;
+    function loadRecord(promotionId) {
+        const result = sqlite.exec(`SELECT * FROM behavior_promotion WHERE promotion_id = ?`, [promotionId]);
+        if (result.length === 0 || result[0].values.length === 0) {
+            return undefined;
+        }
+        return rowToPromotion(result[0].values[0], result[0].columns);
+    }
+    function saveStatus(promotionId, status, decidedAt, rejectReason) {
+        sqlite.run(`UPDATE behavior_promotion
+       SET status = ?, decided_at = ?, reject_reason = ?
+       WHERE promotion_id = ?`, [status, decidedAt, rejectReason ?? null, promotionId]);
+    }
+    return {
+        async submitPromotion(input) {
+            const now = new Date().toISOString();
+            const expiresAt = new Date(Date.now() + DEFAULT_TTL_DAYS * 24 * 60 * 60 * 1000).toISOString();
+            sqlite.run(`INSERT INTO behavior_promotion
+         (promotion_id, behavior_kind, description, status,
+          operator_id, submitted_at, expires_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+                input.promotionId,
+                input.behaviorKind,
+                input.description,
+                "candidate",
+                input.operatorId ?? null,
+                now,
+                expiresAt,
+            ]);
+            return {
+                promotionId: input.promotionId,
+                behaviorKind: input.behaviorKind,
+                description: input.description,
+                status: "candidate",
+                operatorId: input.operatorId,
+                submittedAt: now,
+                expiresAt,
+            };
+        },
+        async approvePromotion(promotionId) {
+            const rec = loadRecord(promotionId);
+            if (!rec) {
+                throw new Error(`promotion_not_found:${promotionId}`);
+            }
+            if (rec.status === "approved") {
+                return rec; // idempotent
+            }
+            if (rec.status === "rejected" || rec.status === "expired") {
+                throw new Error(`promotion_immutable:${promotionId}:${rec.status}`);
+            }
+            const now = new Date().toISOString();
+            saveStatus(promotionId, "approved", now);
+            return { ...rec, status: "approved", decidedAt: now };
+        },
+        async rejectPromotion(promotionId, reason) {
+            const rec = loadRecord(promotionId);
+            if (!rec) {
+                throw new Error(`promotion_not_found:${promotionId}`);
+            }
+            if (rec.status === "rejected") {
+                return rec; // idempotent
+            }
+            if (rec.status === "approved" || rec.status === "expired") {
+                throw new Error(`promotion_immutable:${promotionId}:${rec.status}`);
+            }
+            const now = new Date().toISOString();
+            saveStatus(promotionId, "rejected", now, reason);
+            return { ...rec, status: "rejected", decidedAt: now, rejectReason: reason };
+        },
+        async loadPromotion(promotionId) {
+            return loadRecord(promotionId);
+        },
+        async listPromotions(status) {
+            let sql = `SELECT * FROM behavior_promotion`;
+            const params = [];
+            if (status) {
+                sql += ` WHERE status = ?`;
+                params.push(status);
+            }
+            sql += ` ORDER BY submitted_at DESC`;
+            const result = sqlite.exec(sql, params);
+            if (result.length === 0 || result[0].values.length === 0) {
+                return [];
+            }
+            return result[0].values.map((row) => rowToPromotion(row, result[0].columns));
+        },
+        async expireStaleCandidates() {
+            const now = new Date().toISOString();
+            sqlite.run(`UPDATE behavior_promotion
+         SET status = 'expired', decided_at = ?
+         WHERE status = 'candidate' AND expires_at < ?`, [now, now]);
+            // sql.js does not provide changes count easily; approximate via re-query
+            const result = sqlite.exec(`SELECT COUNT(*) as cnt FROM behavior_promotion
+         WHERE status = 'expired' AND decided_at = ?`, [now]);
+            return result[0]?.values[0]?.[0] ?? 0;
+        },
+    };
+}

package/runtime/core/second-nature/body/circuit-breaker/circuit-breaker-manager.d.ts

@@ -0,0 +1,60 @@
+/**
+ * CircuitBreakerManager — T-BTS.C.5
+ *
+ * Core logic: State machine (Closed → Open → HalfOpen → Closed/Open).
+ * - Closed: counts consecutive failures; threshold hit → Open.
+ * - Open: rejects execution; cooldown elapsed → HalfOpen.
+ * - HalfOpen: initiates runWetProbe via ProbeSignalAdapter.
+ *   - strict side-effect → probe_policy_denied, stays HalfOpen.
+ *   - probe success → Closed + invalidate affordance cache (DR-003).
+ *   - probe failure → Open.
+ *
+ * Persistence:
+ * - State stored in SQLite `circuit_breaker_state` table (v7-003).
+ * - Loads previous state on first access.
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../../../../storage/db/index.js`
+ * - `WetProbeRunner` from `../../../../connectors/base/wet-probe-runner.js`
+ * - `CapabilityContractRegistryV7` from `../../../../connectors/base/manifest-v7.js`
+ * - `ProbeSignalAdapter` from `../probe-signal-adapter.js`
+ *
+ * Boundary:
+ * - Manager decides WHEN to probe (DR-002); connector-system executes it.
+ * - Does NOT execute HTTP directly — delegates to ProbeSignalAdapter.
+ *
+ * Test coverage: tests/unit/body/circuit-breaker-manager.test.ts
+ */
+import type { StateDatabase } from "../../../../storage/db/index.js";
+import type { CapabilityContractRegistryV7 } from "../../../../connectors/base/manifest-v7.js";
+import type { ProbeSignalAdapter } from "../probe-signal-adapter.js";
+export type BreakerState = "closed" | "open" | "half_open";
+export interface BreakerRecord {
+    platformId: string;
+    capabilityId: string;
+    state: BreakerState;
+    failureCount: number;
+    consecutiveFailures: number;
+    lastFailureAt?: string;
+    openedAt?: string;
+    lastProbeAt?: string;
+}
+export interface CircuitBreakerManager {
+    evaluateFailure(platformId: string, capabilityId: string): Promise<BreakerState>;
+    evaluateSuccess(platformId: string, capabilityId: string): Promise<BreakerState>;
+    canExecute(platformId: string, capabilityId: string): Promise<boolean>;
+    getState(platformId: string, capabilityId: string): Promise<BreakerState>;
+    attemptReset(platformId: string, capabilityId: string): Promise<BreakerState>;
+}
+export interface CircuitBreakerManagerOptions {
+    database: StateDatabase;
+    probeAdapter: ProbeSignalAdapter;
+    registry: CapabilityContractRegistryV7;
+    /** Consecutive failures before opening. Default 3. */
+    failureThreshold?: number;
+    /** Cooldown in ms before HalfOpen. Default 30_000. */
+    cooldownMs?: number;
+    /** Callback when breaker transitions to Closed (for affordance cache invalidation). */
+    onClosed?: (platformId: string, capabilityId: string) => void;
+}
+export declare function createCircuitBreakerManager(options: CircuitBreakerManagerOptions): CircuitBreakerManager;

package/runtime/core/second-nature/body/circuit-breaker/circuit-breaker-manager.js

@@ -0,0 +1,174 @@
+/**
+ * CircuitBreakerManager — T-BTS.C.5
+ *
+ * Core logic: State machine (Closed → Open → HalfOpen → Closed/Open).
+ * - Closed: counts consecutive failures; threshold hit → Open.
+ * - Open: rejects execution; cooldown elapsed → HalfOpen.
+ * - HalfOpen: initiates runWetProbe via ProbeSignalAdapter.
+ *   - strict side-effect → probe_policy_denied, stays HalfOpen.
+ *   - probe success → Closed + invalidate affordance cache (DR-003).
+ *   - probe failure → Open.
+ *
+ * Persistence:
+ * - State stored in SQLite `circuit_breaker_state` table (v7-003).
+ * - Loads previous state on first access.
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../../../../storage/db/index.js`
+ * - `WetProbeRunner` from `../../../../connectors/base/wet-probe-runner.js`
+ * - `CapabilityContractRegistryV7` from `../../../../connectors/base/manifest-v7.js`
+ * - `ProbeSignalAdapter` from `../probe-signal-adapter.js`
+ *
+ * Boundary:
+ * - Manager decides WHEN to probe (DR-002); connector-system executes it.
+ * - Does NOT execute HTTP directly — delegates to ProbeSignalAdapter.
+ *
+ * Test coverage: tests/unit/body/circuit-breaker-manager.test.ts
+ */
+export function createCircuitBreakerManager(options) {
+    const { database: { sqlite }, probeAdapter, failureThreshold = 3, cooldownMs = 30_000, onClosed, } = options;
+    function loadRecord(platformId, capabilityId) {
+        const result = sqlite.exec(`SELECT * FROM circuit_breaker_state
+       WHERE platform_id = ? AND capability_id = ?`, [platformId, capabilityId]);
+        if (result.length === 0 || result[0].values.length === 0) {
+            return {
+                platformId,
+                capabilityId,
+                state: "closed",
+                failureCount: 0,
+                consecutiveFailures: 0,
+            };
+        }
+        const cols = result[0].columns;
+        const get = (name) => result[0].values[0][cols.indexOf(name)];
+        return {
+            platformId,
+            capabilityId,
+            state: get("state"),
+            failureCount: get("failure_count") ?? 0,
+            consecutiveFailures: get("consecutive_failures") ?? 0,
+            lastFailureAt: get("last_failure_at") ?? undefined,
+            openedAt: get("opened_at") ?? undefined,
+            lastProbeAt: get("last_probe_at") ?? undefined,
+        };
+    }
+    function saveRecord(rec) {
+        const now = new Date().toISOString();
+        sqlite.run(`INSERT INTO circuit_breaker_state
+       (platform_id, capability_id, state, failure_count, consecutive_failures,
+        last_failure_at, opened_at, last_probe_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(platform_id, capability_id) DO UPDATE SET
+         state = excluded.state,
+         failure_count = excluded.failure_count,
+         consecutive_failures = excluded.consecutive_failures,
+         last_failure_at = excluded.last_failure_at,
+         opened_at = excluded.opened_at,
+         last_probe_at = excluded.last_probe_at,
+         updated_at = excluded.updated_at`, [
+            rec.platformId,
+            rec.capabilityId,
+            rec.state,
+            rec.failureCount,
+            rec.consecutiveFailures,
+            rec.lastFailureAt ?? null,
+            rec.openedAt ?? null,
+            rec.lastProbeAt ?? null,
+            now,
+        ]);
+    }
+    return {
+        async evaluateFailure(platformId, capabilityId) {
+            const rec = loadRecord(platformId, capabilityId);
+            rec.consecutiveFailures += 1;
+            rec.failureCount += 1;
+            rec.lastFailureAt = new Date().toISOString();
+            if (rec.state === "closed" && rec.consecutiveFailures >= failureThreshold) {
+                rec.state = "open";
+                rec.openedAt = rec.lastFailureAt;
+            }
+            else if (rec.state === "half_open") {
+                // HalfOpen + failure → back to Open
+                rec.state = "open";
+                rec.openedAt = rec.lastFailureAt;
+            }
+            // open + failure stays open
+            saveRecord(rec);
+            return rec.state;
+        },
+        async evaluateSuccess(platformId, capabilityId) {
+            const rec = loadRecord(platformId, capabilityId);
+            if (rec.state === "half_open") {
+                rec.state = "closed";
+                rec.consecutiveFailures = 0;
+                rec.openedAt = undefined;
+                if (onClosed) {
+                    onClosed(platformId, capabilityId);
+                }
+            }
+            else if (rec.state === "closed") {
+                rec.consecutiveFailures = 0;
+            }
+            // open + success stays open (should not happen via normal path)
+            saveRecord(rec);
+            return rec.state;
+        },
+        async canExecute(platformId, capabilityId) {
+            const rec = loadRecord(platformId, capabilityId);
+            if (rec.state === "closed")
+                return true;
+            if (rec.state === "half_open")
+                return true; // allow limited probe traffic
+            if (rec.state === "open") {
+                if (rec.openedAt) {
+                    const elapsed = Date.now() - new Date(rec.openedAt).getTime();
+                    if (elapsed >= cooldownMs) {
+                        return true; // let caller attempt, will transition to HalfOpen
+                    }
+                }
+                return false;
+            }
+            return true;
+        },
+        async getState(platformId, capabilityId) {
+            return loadRecord(platformId, capabilityId).state;
+        },
+        async attemptReset(platformId, capabilityId) {
+            const rec = loadRecord(platformId, capabilityId);
+            if (rec.state !== "half_open" && rec.state !== "open") {
+                return rec.state;
+            }
+            // If cooldown has elapsed from Open, transition to HalfOpen and probe
+            if (rec.state === "open" && rec.openedAt) {
+                const elapsed = Date.now() - new Date(rec.openedAt).getTime();
+                if (elapsed < cooldownMs) {
+                    return rec.state; // still cooling
+                }
+                rec.state = "half_open";
+                saveRecord(rec);
+            }
+            // HalfOpen: run wet probe
+            const probeResult = await probeAdapter.runAndRecordProbe(platformId, capabilityId, options.registry);
+            rec.lastProbeAt = new Date().toISOString();
+            if (probeResult.httpStatus === 0 && probeResult.actualStatus === "unavailable") {
+                // probe_policy_denied or network failure → stay HalfOpen
+                saveRecord(rec);
+                return rec.state;
+            }
+            if (probeResult.actualStatus === "available") {
+                rec.state = "closed";
+                rec.consecutiveFailures = 0;
+                rec.openedAt = undefined;
+                if (onClosed) {
+                    onClosed(platformId, capabilityId);
+                }
+            }
+            else {
+                rec.state = "open";
+                rec.openedAt = new Date().toISOString();
+            }
+            saveRecord(rec);
+            return rec.state;
+        },
+    };
+}

package/runtime/core/second-nature/body/probe-signal-adapter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ProbeSignalAdapter — T-BTS.C.4
+ *
+ * Core logic: Bridge between WetProbeRunner and state-memory.
+ * 1. Runs a wet probe for a capability.
+ * 2. Persists the CapabilityProbeResult to state-memory.
+ * 3. If the probe indicates degradation/unavailability, records a
+ *    corresponding ToolExperience row with triggerSource="probe".
+ *
+ * Dependencies:
+ * - `WetProbeRunner` from `../../../connectors/base/wet-probe-runner.js`
+ * - `CapabilityContractRegistryV7` from `../../../connectors/base/manifest-v7.js`
+ * - `CapabilityProbeResultStore` from `../../../storage/services/tool-experience-store.js`
+ * - `ToolExperienceStore` from `../../../storage/services/tool-experience-store.js`
+ * - `ExperienceWriter` from `./tool-experience/experience-writer.js`
+ *
+ * Boundary:
+ * - Does NOT modify breaker state — caller (CircuitBreakerManager) decides.
+ * - probePolicyDenied is treated as a valid result, not an error.
+ *
+ * Test coverage: tests/unit/body/probe-signal-adapter.test.ts
+ */
+import type { WetProbeRunner } from "../../../connectors/base/wet-probe-runner.js";
+import type { CapabilityContractRegistryV7 } from "../../../connectors/base/manifest-v7.js";
+import type { CapabilityProbeResultStore, ToolExperienceStore } from "../../../storage/services/tool-experience-store.js";
+export interface ProbeSignalAdapter {
+    runAndRecordProbe(platformId: string, capabilityId: string, registry: CapabilityContractRegistryV7): Promise<{
+        actualStatus: string;
+        httpStatus: number;
+        recorded: boolean;
+        experienceRecorded: boolean;
+    }>;
+}
+export declare function createProbeSignalAdapter(deps: {
+    wetProbeRunner: WetProbeRunner;
+    probeResultStore: CapabilityProbeResultStore;
+    toolExperienceStore: ToolExperienceStore;
+}): ProbeSignalAdapter;

package/runtime/core/second-nature/body/probe-signal-adapter.js

@@ -0,0 +1,60 @@
+/**
+ * ProbeSignalAdapter — T-BTS.C.4
+ *
+ * Core logic: Bridge between WetProbeRunner and state-memory.
+ * 1. Runs a wet probe for a capability.
+ * 2. Persists the CapabilityProbeResult to state-memory.
+ * 3. If the probe indicates degradation/unavailability, records a
+ *    corresponding ToolExperience row with triggerSource="probe".
+ *
+ * Dependencies:
+ * - `WetProbeRunner` from `../../../connectors/base/wet-probe-runner.js`
+ * - `CapabilityContractRegistryV7` from `../../../connectors/base/manifest-v7.js`
+ * - `CapabilityProbeResultStore` from `../../../storage/services/tool-experience-store.js`
+ * - `ToolExperienceStore` from `../../../storage/services/tool-experience-store.js`
+ * - `ExperienceWriter` from `./tool-experience/experience-writer.js`
+ *
+ * Boundary:
+ * - Does NOT modify breaker state — caller (CircuitBreakerManager) decides.
+ * - probePolicyDenied is treated as a valid result, not an error.
+ *
+ * Test coverage: tests/unit/body/probe-signal-adapter.test.ts
+ */
+import { createExperienceWriter } from "./tool-experience/experience-writer.js";
+export function createProbeSignalAdapter(deps) {
+    const { wetProbeRunner, probeResultStore, toolExperienceStore } = deps;
+    const experienceWriter = createExperienceWriter(toolExperienceStore);
+    return {
+        async runAndRecordProbe(platformId, capabilityId, registry) {
+            const result = await wetProbeRunner.runWetProbe(platformId, capabilityId, registry);
+            // Persist probe result
+            await probeResultStore.appendProbeResult(result.probeResult);
+            // Record experience for non-success probes
+            let experienceRecorded = false;
+            if (result.probeResult.actualStatus !== "available") {
+                const mockResult = {
+                    status: "terminal_failure",
+                    failureClass: "transport_failure",
+                    metadata: {
+                        platformId,
+                        channel: "api_rest",
+                        latencyMs: 0,
+                    },
+                };
+                await experienceWriter.recordExperience({
+                    connectorId: platformId,
+                    capabilityId,
+                    result: mockResult,
+                    triggerSource: "probe",
+                });
+                experienceRecorded = true;
+            }
+            return {
+                actualStatus: result.probeResult.actualStatus,
+                httpStatus: result.httpStatus,
+                recorded: true,
+                experienceRecorded,
+            };
+        },
+    };
+}

package/runtime/core/second-nature/body/tool-affordance/affordance-assembler.d.ts

@@ -0,0 +1,51 @@
+/**
+ * AffordanceAssembler — T-BTS.C.1
+ *
+ * Core logic: Assemble a platform→capability affordance map from the v7
+ * capability registry and recent probe results.
+ *
+ * Mapping rules (probe actualStatus → affordance status):
+ * - available  → safe
+ * - degraded   → exploratory
+ * - unavailable → unavailable
+ * - no probe + credential required → needs_auth
+ * - no probe + no credential required → unavailable
+ *
+ * Caching:
+ * - TTL cache (default 30s) keyed by serialized scope.
+ * - Invalidate on explicit call or when underlying data changes.
+ *
+ * Performance target: P95 < 1s for 50 manifests.
+ *
+ * Dependencies:
+ * - `CapabilityContractRegistryV7` from `../../../../connectors/base/manifest-v7.js`
+ * - `AffordanceItem`, `AffordanceMap`, `AffordanceContextScope`
+ *   from `../../../../shared/types/v7-entities.js`
+ * - `applyAffordanceContextScope` from `./affordance-context-scope.js`
+ *
+ * Boundary:
+ * - Does NOT perform HTTP probes — reads cached probe results only.
+ * - Credential-bearing entries are excluded (ADR-003).
+ * - Returns a plain object; caller decides persistence.
+ *
+ * Test coverage: tests/unit/body/affordance-assembler.test.ts
+ */
+import type { CapabilityContractRegistryV7 } from "../../../../connectors/base/manifest-v7.js";
+import type { AffordanceMap, AffordanceContextScope, ProbeActualStatus } from "../../../../shared/types/v7-entities.js";
+export interface ProbeResultReader {
+    getLatestProbeResult(platformId: string, capabilityId: string): {
+        actualStatus: ProbeActualStatus;
+        createdAt: string;
+    } | undefined;
+}
+export interface AffordanceAssembler {
+    assembleAffordanceMap(scope?: AffordanceContextScope): Promise<AffordanceMap>;
+    invalidateCache(): void;
+}
+export interface AffordanceAssemblerOptions {
+    registry: CapabilityContractRegistryV7;
+    probeReader: ProbeResultReader;
+    credentialRequired?: (platformId: string, capabilityId: string) => boolean;
+    ttlMs?: number;
+}
+export declare function createAffordanceAssembler(options: AffordanceAssemblerOptions): AffordanceAssembler;