hackmyagent 0.16.7 → 0.17.0

package/dist/arp/intelligence/behavioral-risk.d.ts

@@ -2,9 +2,9 @@
  * Behavioral risk signal channel (AIComply P1, coordinator hot path).
  *
  * The `IntelligenceCoordinator` needs a way to ask the behavioral twin
- * (`NanoMindL1` in `nanomind-l1.ts`) "how anomalous does this event look
- * against the agent's behavioral baseline?" without importing the twin
- * directly into the comply path. Direct coupling would re-introduce the
+ * (`RuntimeTwin` in `runtime-twin.ts`) "how anomalous does this event
+ * look against the agent's behavioral baseline?" without importing the
+ * twin directly into the comply path. Direct coupling would re-introduce the
  * layering break that the L0-comply gate was added to prevent: the twin
  * would sit inline with the crypto verifier, and a bug in the twin would
  * cascade into every classified event.
@@ -16,8 +16,8 @@
  *   - `InProcessBehavioralRiskSource` wraps any object that exposes
  *     `scoreARPEvent(event)`. This is the single-process fast path: no
  *     serialization, no socket, just a direct call guarded by a try/catch.
- *     `NanoMindL1` satisfies the interface via its readonly scoreARPEvent
- *     method, but tests can inject any stub.
+ *     `RuntimeTwin` satisfies the interface via its readonly
+ *     scoreARPEvent method, but tests can inject any stub.
  *
  *   - `UnixSocketBehavioralRiskSource` speaks newline-delimited JSON over
  *     a unix domain socket (or a Windows named pipe via node `net`). This
@@ -51,10 +51,10 @@
  */
 import type { ARPEvent } from '../types';
 /**
- * Shape returned by the twin's on-demand scorer. Mirrors NanoMindL1's
+ * Shape returned by the twin's on-demand scorer. Mirrors RuntimeTwin's
  * internal AnomalyResult so this module does not need to import the twin
  * directly, and so test stubs can produce it without depending on the
- * full NanoMindL1 class surface.
+ * full RuntimeTwin class surface.
  */
 export interface BehavioralRiskScore {
     /** Normalized anomaly score in [0, 1]. Higher is riskier. */
@@ -66,7 +66,7 @@ export interface BehavioralRiskScore {
 }
 /**
  * Minimum interface an in-process twin handle must satisfy to be plugged
- * into `InProcessBehavioralRiskSource`. NanoMindL1.scoreARPEvent matches
+ * into `InProcessBehavioralRiskSource`. RuntimeTwin.scoreARPEvent matches
  * this shape by construction.
  */
 export interface BehavioralRiskScoreable {
@@ -158,7 +158,7 @@ export declare function defaultBehavioralRiskSocketPath(agentId: string): string
  * misbehaving twin that throws.
  *
  * Decoupling rationale: the coordinator holds this as a
- * `BehavioralRiskSource`, not as a `NanoMindL1`. The comply path has no
+ * `BehavioralRiskSource`, not as a `RuntimeTwin`. The comply path has no
  * knowledge of twin internals and a bug in the twin surfaces as an
  * `unavailable` result, not a cascade failure.
  */

package/dist/arp/intelligence/behavioral-risk.js

@@ -3,9 +3,9 @@
  * Behavioral risk signal channel (AIComply P1, coordinator hot path).
  *
  * The `IntelligenceCoordinator` needs a way to ask the behavioral twin
- * (`NanoMindL1` in `nanomind-l1.ts`) "how anomalous does this event look
- * against the agent's behavioral baseline?" without importing the twin
- * directly into the comply path. Direct coupling would re-introduce the
+ * (`RuntimeTwin` in `runtime-twin.ts`) "how anomalous does this event
+ * look against the agent's behavioral baseline?" without importing the
+ * twin directly into the comply path. Direct coupling would re-introduce the
  * layering break that the L0-comply gate was added to prevent: the twin
  * would sit inline with the crypto verifier, and a bug in the twin would
  * cascade into every classified event.
@@ -17,8 +17,8 @@
  *   - `InProcessBehavioralRiskSource` wraps any object that exposes
  *     `scoreARPEvent(event)`. This is the single-process fast path: no
  *     serialization, no socket, just a direct call guarded by a try/catch.
- *     `NanoMindL1` satisfies the interface via its readonly scoreARPEvent
- *     method, but tests can inject any stub.
+ *     `RuntimeTwin` satisfies the interface via its readonly
+ *     scoreARPEvent method, but tests can inject any stub.
  *
  *   - `UnixSocketBehavioralRiskSource` speaks newline-delimited JSON over
  *     a unix domain socket (or a Windows named pipe via node `net`). This
@@ -135,7 +135,7 @@ function defaultBehavioralRiskSocketPath(agentId) {
  * misbehaving twin that throws.
  *
  * Decoupling rationale: the coordinator holds this as a
- * `BehavioralRiskSource`, not as a `NanoMindL1`. The comply path has no
+ * `BehavioralRiskSource`, not as a `RuntimeTwin`. The comply path has no
  * knowledge of twin internals and a bug in the twin surfaces as an
  * `unavailable` result, not a cascade failure.
  */

package/dist/arp/intelligence/coordinator.js

@@ -476,8 +476,8 @@ function raiseSeverity(current, floor) {
 /**
  * Bands the behavioral risk score is sorted into, matched to severity
  * floors raised on the event when the band fires. The score ranges come
- * from NanoMindL1's response table; they are deliberately mirrored here
- * rather than imported, so the coordinator's policy can drift
+ * from RuntimeTwin's response table; they are deliberately mirrored
+ * here rather than imported, so the coordinator's policy can drift
  * independently of the twin's internal action labels if needed.
  *
  *   >= 0.8 : critical   -> event.category >= threat, severity >= critical

package/dist/arp/intelligence/runtime-twin.d.ts

@@ -0,0 +1,157 @@
+/**
+ * RuntimeTwin - Behavioral Anomaly Detection Layer (L1).
+ *
+ * Integrates the RuntimeTwin behavioral scorer into ARP's event pipeline.
+ * Processes every L0 event through the twin for anomaly scoring.
+ *
+ * Three-tier ARP model:
+ *   L0: Rule-based (EventEngine)           microseconds, always runs
+ *   L1: RuntimeTwin behavioral twin        milliseconds, this module
+ *   L2: Claude or local LLM intelligence   seconds, IntelligenceCoordinator
+ *
+ * L1 runs in parallel with L0. It never blocks the L0 decision.
+ *
+ * === SOURCE-OF-TRUTH NOTE ===
+ *
+ * The canonical implementation of this class lives at:
+ *     opena2a-org/nanomind/packages/nanomind-runtime-core/src/index.ts
+ *
+ * This file is a temporary integration-layer mirror maintained in lockstep
+ * with the canonical source until PR 1b publishes @nanomind/runtime-core
+ * to npm. Until that cut-over, any change to the LSTM scoring logic,
+ * gradient accumulation, or differential privacy path MUST be made in
+ * both files. See todo/NANOMIND_V3_AUDIT.md Section 8 PR 1 and Section 9
+ * item 1 for the rationale.
+ *
+ * This mirror retains the hackmyagent-local imports of ARPEvent and
+ * ARPConfig so ARP integration stays type-safe. The canonical package
+ * defines a structural ARPEventInput equivalent to keep itself free of
+ * cross-repo dependencies.
+ */
+import type { ARPEvent } from '../types';
+import type { EventEngine } from '../engine/event-engine';
+type EventType = 'TOOL_CALL' | 'CAPABILITY_CHECK' | 'MCP_CALL' | 'MEMORY_READ' | 'MEMORY_WRITE' | 'EXTERNAL_CALL';
+type ARPAction = 'allow' | 'alert' | 'throttle' | 'suspend' | 'kill';
+interface BehavioralEvent {
+    agentId: string;
+    sessionId: string;
+    sequenceNum: number;
+    eventType: EventType;
+    capability: string;
+    toolName: string | null;
+    argHash: string;
+    timestampDelta: number;
+    wallClock: number;
+    responseSize: number;
+    responseCode: number;
+    l0Decision: 'allow' | 'block' | 'alert';
+}
+interface BaselineStats {
+    eventTypeCounts: Record<string, number>;
+    avgTimingDelta: number;
+    stdTimingDelta: number;
+    capabilitySet: Set<string>;
+    avgResponseSize: number;
+    totalEvents: number;
+    errorRate: number;
+}
+interface AnomalyResult {
+    score: number;
+    action: ARPAction;
+    reason: string;
+}
+export declare class RuntimeTwin {
+    private agentId;
+    private sessionId;
+    private baseline;
+    private eventBuffer;
+    private sequenceNum;
+    private lastEventTime;
+    private eventLogPath;
+    private enabled;
+    private gradientAccumulator;
+    private gradientEventCount;
+    private gradientLossSum;
+    private fleetEnabled;
+    private agentCategory;
+    constructor(agentId: string, config?: {
+        enabled?: boolean;
+        fleetEnabled?: boolean;
+        agentCategory?: string;
+    });
+    /**
+     * Attach to an ARP EventEngine — processes every event for anomaly detection.
+     * Non-blocking: L1 runs in parallel, L0 decision is returned immediately.
+     */
+    attach(engine: EventEngine): void;
+    /**
+     * Score an ARP event for behavioral risk WITHOUT mutating any twin state.
+     *
+     * Used by the behavioral risk IPC server (behavioral-risk-server.ts) to
+     * answer on-demand scoring requests from a coordinator running in another
+     * process, or by InProcessBehavioralRiskSource for single-process wiring.
+     * Unlike `processEvent`, this does not advance the sequence number, append
+     * to the event log, add to the event buffer, or accumulate the gradient.
+     * It is a pure read against the current baseline.
+     *
+     * Returns null when the twin is disabled or the baseline is not yet
+     * trained (totalEvents < 100). The caller must surface this to the IPC
+     * client as a NOT_READY signal; silently returning a zero score would
+     * misrepresent the twin's confidence.
+     */
+    scoreARPEvent(event: ARPEvent): AnomalyResult | null;
+    /**
+     * Readonly variant of convertEvent that does not mutate lastEventTime or
+     * sequenceNum. Used by scoreARPEvent for on-demand IPC scoring.
+     */
+    private convertEventReadonly;
+    /**
+     * Test-only seam: force-install a baseline so unit tests can exercise
+     * scoreARPEvent without first calling processEvent a hundred times. Marked
+     * with a leading underscore so it is easy to grep for in production code.
+     */
+    _setBaselineForTest(baseline: BaselineStats): void;
+    /**
+     * Process a behavioral event and return anomaly score.
+     */
+    processEvent(event: BehavioralEvent): AnomalyResult;
+    /**
+     * Convert an ARP event to a NanoMind behavioral event.
+     */
+    private convertEvent;
+    /**
+     * Compute anomaly score (same algorithm as @nanomind/runtime-core).
+     */
+    private computeAnomalyScore;
+    private updateBaseline;
+    private getResponse;
+    private loadBaseline;
+    private appendToLog;
+    private logEscalation;
+    /**
+     * Accumulate behavioral features into gradient vector.
+     * Each event contributes to a running gradient that captures the
+     * distribution of event types, timing anomalies, error rates,
+     * and capability novelty seen by this agent.
+     */
+    private accumulateGradient;
+    /**
+     * Submit accumulated gradient to Registry fleet endpoint.
+     * Normalizes by event count before submission (the fleet module
+     * handles clipping and differential privacy noise).
+     */
+    private flushGradient;
+    /**
+     * Apply differential privacy: clip to L2 norm 1.0, add Gaussian noise.
+     * Matches the privacy guarantees inlined in @nanomind/runtime-core
+     * (epsilon=1.0, delta=1e-5). The statistical twin's @nanomind/runtime
+     * package was retired in the Q5 split (audit Section 9 item 1).
+     */
+    private addPrivacyNoise;
+    /**
+     * Force flush any remaining gradient (call on shutdown).
+     */
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=runtime-twin.d.ts.map

package/dist/arp/intelligence/runtime-twin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-twin.d.ts","sourceRoot":"","sources":["../../../src/arp/intelligence/runtime-twin.ts"],"names":[],"mappings":"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"}