@psiclawops/hypercompositor 0.9.0 → 0.9.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@psiclawops/hypercompositor",
-  "version": "0.9.0",
-  "description": "HyperCompositor — context engine plugin for OpenClaw",
+  "version": "0.9.1",
+  "description": "HyperCompositor \u2014 context engine plugin for OpenClaw",
   "type": "module",
   "main": "dist/index.js",
   "license": "Apache-2.0",
@@ -18,7 +18,7 @@
   "openclaw": {
     "plugin": {
       "id": "hypercompositor",
-      "name": "HyperCompositor — Context Engine",
+      "name": "HyperCompositor \u2014 Context Engine",
       "kind": "context-engine"
     },
     "extensions": [
@@ -38,7 +38,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@psiclawops/hypermem": "0.9.0",
+    "@psiclawops/hypermem": "0.9.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/dist/index.d.ts

@@ -1,208 +0,0 @@
-/**
- * hypermem Context Engine Plugin
- *
- * Implements OpenClaw's ContextEngine interface backed by hypermem's
- * four-layer memory architecture:
- *
- *   L1 Cache    — SQLite `:memory:` hot session working memory
- *   L2 Messages — per-agent conversation history (SQLite)
- *   L3 Vectors  — semantic + keyword search (KNN + FTS5)
- *   L4 Library  — facts, knowledge, episodes, preferences
- *
- * Lifecycle mapping:
- *   ingest()     → record each message into messages.db
- *   assemble()   → compositor builds context from all four layers
- *   compact()    → delegate to runtime (ownsCompaction: false)
- *   afterTurn()  → trigger background indexer (fire-and-forget)
- *   bootstrap()  → warm hot-cache session, register agent in fleet
- *   dispose()    → close hypermem connections
- *
- * Session key format expected: "agent:<agentId>:<channel>:<name>"
- */
-import type { NeutralMessage, NeutralToolCall, NeutralToolResult, ComposeRequest, ComposeResult } from '@psiclawops/hypermem';
-import { resolveTrimBudgets } from '@psiclawops/hypermem';
-export type { NeutralMessage, NeutralToolCall, NeutralToolResult, ComposeRequest, ComposeResult };
-type TrimTelemetryPath = 'assemble.normal' | 'assemble.toolLoop' | 'assemble.subagent' | 'reshape' | 'compact.nuclear' | 'compact.history' | 'compact.history2' | 'afterTurn.secondary' | 'warmstart';
-type DegradationTelemetryPath = 'compose' | 'toolLoop';
-interface DegradationTelemetryFields {
-    agentId: string;
-    sessionKey: string;
-    turnId: string;
-    path: DegradationTelemetryPath;
-    toolChainCoEjections?: number;
-    toolChainStubReplacements?: number;
-    artifactDegradations?: number;
-    artifactOversizeThresholdTokens?: number;
-    replayState?: 'entering' | 'stabilizing' | 'exited';
-    replayReason?: string;
-}
-declare function trimTelemetry(fields: {
-    path: TrimTelemetryPath;
-    agentId: string;
-    sessionKey: string;
-    preTokens: number;
-    postTokens: number;
-    removed: number;
-    cacheInvalidated: boolean;
-    reason: string;
-}): void;
-declare function assembleTrace(fields: {
-    agentId: string;
-    sessionKey: string;
-    turnId: string;
-    path: 'cold' | 'replay' | 'subagent';
-    toolLoop: boolean;
-    msgCount: number;
-    prefixChanged?: boolean;
-    prefixHash?: string;
-    rerankerStatus?: string;
-    rerankerCandidates?: number;
-    rerankerProvider?: string | null;
-    slotSpans?: Record<string, {
-        allocated: number;
-        filled: number;
-        overflow: boolean;
-    }>;
-    compactionEligibleCount?: number;
-    compactionEligibleRatio?: number;
-    compactionProcessedCount?: number;
-    composeTopicSource?: 'request-topic-id' | 'session-topic-map' | 'none';
-    composeTopicState?: 'no-active-topic' | 'active-topic-ready' | 'active-topic-missing-stamped-history' | 'history-disabled';
-    composeTopicMessageCount?: number;
-    composeTopicStampedMessageCount?: number;
-    composeTopicTelemetryStatus?: 'emitted' | 'intentionally-omitted';
-}): void;
-declare function degradationTelemetry(fields: DegradationTelemetryFields): void;
-declare function lifecyclePolicyTelemetry(fields: {
-    path: 'compose.eviction' | 'compose.preRecall' | 'afterTurn.gradient';
-    agentId: string;
-    sessionKey: string;
-    band: string;
-    pressurePct?: number;
-    topicShiftConfidence?: number;
-    trimSoftTarget?: number;
-    reasons?: string[];
-}): void;
-declare function nextTurnId(): string;
-declare const GUARD_TELEMETRY_REASONS: readonly ["warmstart-pressure-demoted", "reshape-downshift-demoted", "duplicate-claim-suppressed", "afterturn-secondary-demoted", "window-within-budget-skip", "pressure-accounting-anomaly"];
-type GuardTelemetryReason = typeof GUARD_TELEMETRY_REASONS[number];
-declare function beginTrimOwnerTurn(sessionKey: string, turnId: string): void;
-declare function endTrimOwnerTurn(sessionKey: string, turnId: string): void;
-/**
- * Claim the steady-state trim owner slot for the current turn.
- *
- * Behavior:
- *   - compact.* paths are exception-only and pass through without claiming.
- *   - Non-steady paths (warmstart, reshape, afterTurn.secondary) also pass
- *     through without claiming. Demoted/no-op sites should normally emit
- *     via guardTelemetry() instead so they stay visible without contending
- *     for ownership (sub-tasks 2.2 and 2.3 wire this in).
- *   - Steady-state paths (assemble.normal, assemble.subagent,
- *     assemble.toolLoop) claim the single owner slot for the current turn.
- *     The first such claim succeeds. A second steady-state claim against the
- *     same turn is a duplicate-turn violation: it throws loudly under
- *     NODE_ENV='development' and warns in other environments (returning
- *     false so non-dev runtimes keep working).
- *
- * Callers should invoke this immediately before the real
- * trimHistoryToTokenBudget() call. Guard telemetry does NOT route through
- * this helper — it is explicitly excluded from the steady-state invariant.
- *
- * Returns true when the claim succeeds (or is exempt); false on a swallowed
- * duplicate claim in non-development. In development the duplicate throws
- * before returning.
- */
-declare function claimTrimOwner(sessionKey: string, turnId: string, path: TrimTelemetryPath): boolean;
-/**
- * Non-counting guard / noop telemetry.
- *
- * Emits a `trim-guard` record on the same JSONL channel as trimTelemetry()
- * but with a distinct event name so per-turn reporting (scripts/trim-report.mjs,
- * future ownership dashboards) can keep it out of `trimCount`. Used by
- * demoted/no-op call sites in 2.2 and 2.3 so their path labels stay visible
- * in telemetry without consuming a steady-state owner slot.
- *
- * Zero-cost when telemetry is off. Never throws.
- */
-declare function guardTelemetry(fields: {
-    path: TrimTelemetryPath;
-    agentId: string;
-    sessionKey: string;
-    reason: GuardTelemetryReason;
-}): void;
-export declare const __telemetryForTests: {
-    trimTelemetry: typeof trimTelemetry;
-    assembleTrace: typeof assembleTrace;
-    degradationTelemetry: typeof degradationTelemetry;
-    guardTelemetry: typeof guardTelemetry;
-    lifecyclePolicyTelemetry: typeof lifecyclePolicyTelemetry;
-    nextTurnId: typeof nextTurnId;
-    beginTrimOwnerTurn: typeof beginTrimOwnerTurn;
-    endTrimOwnerTurn: typeof endTrimOwnerTurn;
-    claimTrimOwner: typeof claimTrimOwner;
-    TRIM_SOFT_TARGET: number;
-    TRIM_GROWTH_THRESHOLD: number;
-    TRIM_HEADROOM_FRACTION: number;
-    resolveTrimBudgets: typeof resolveTrimBudgets;
-    reset(): void;
-};
-export declare const CONTEXT_WINDOW_OVERRIDE_KEY_REGEX: RegExp;
-export type ContextWindowOverride = {
-    contextTokens?: number;
-    contextWindow?: number;
-};
-export declare function sanitizeContextWindowOverrides(raw: unknown): {
-    value: Record<string, ContextWindowOverride>;
-    warnings: string[];
-};
-export declare function resolveEffectiveBudget(args: {
-    tokenBudget?: number;
-    model?: string;
-    contextWindowSize: number;
-    contextWindowReserve: number;
-    contextWindowOverrides?: Record<string, ContextWindowOverride>;
-}): {
-    budget: number;
-    source: string;
-};
-export interface ModelIdentity {
-    rawModel: string | null;
-    modelKey: string | null;
-    provider: string | null;
-    modelId: string | null;
-}
-export declare function resolveModelIdentity(model?: string): ModelIdentity;
-export declare function diffModelState(previous: {
-    model?: string;
-    modelKey?: string | null;
-    provider?: string | null;
-    modelId?: string | null;
-    tokenBudget?: number;
-} | null | undefined, current: {
-    model?: string;
-    tokenBudget?: number;
-}): {
-    previousIdentity: ModelIdentity;
-    currentIdentity: ModelIdentity;
-    modelChanged: boolean;
-    providerChanged: boolean;
-    modelIdChanged: boolean;
-    budgetChanged: boolean;
-    budgetDownshift: boolean;
-    budgetUplift: boolean;
-};
-/**
- * Bust the assembly cache for a specific agent+session.
- * Call this after writing to identity files (SOUL.md, IDENTITY.md, TOOLS.md,
- * USER.md) to ensure the next assemble() runs full compositor, not a replay.
- */
-export declare function bustAssemblyCache(agentId: string, sessionKey: string): Promise<void>;
-declare const _default: {
-    id: string;
-    name: string;
-    description: string;
-    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
-    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
-} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
-export default _default;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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