dsh-mnemon 0.3.2 → 0.3.4

package/lib/types/src/client/api.d.ts

@@ -36,6 +36,7 @@ export declare class MnemonClient {
         content?: string;
         old_text?: string;
         importance?: RuntimeMemoryImportance;
+        branches?: string[];
     }): Promise<RuntimeMemoryMutationResult>;
     documents(): Promise<DocumentSnapshot>;
     document(id: string): Promise<DocumentView>;

package/lib/types/src/client/locales.d.ts

@@ -333,6 +333,10 @@ export declare const zh: {
     'runtime.importance.critical': string;
     'runtime.importance.normal': string;
     'runtime.importance.low': string;
+    'runtime.branches': string;
+    'runtime.branchesPlaceholder': string;
+    'runtime.branchesHint': string;
+    'runtime.branchBadge': string;
     'runtime.empty': string;
     'runtime.editContent': string;
     'runtime.editAction': string;
@@ -706,6 +710,13 @@ export declare const zh: {
     'config.customHintShort': string;
     'config.customSelected': string;
     'config.globalScopeHint': string;
+    'config.runtimeUserScopeTitle': string;
+    'config.runtimeUserScopeDescription': string;
+    'config.runtimeUserScopeAria': string;
+    'config.runtimeUserScopeStorage': string;
+    'config.runtimeUserScopeStorageHint': string;
+    'config.runtimeUserScopeGlobal': string;
+    'config.runtimeUserScopeGlobalHint': string;
     'config.topologyTitle': string;
     'config.topologyDescription': string;
     'config.topologyLoading': string;
@@ -826,6 +837,7 @@ export declare const zh: {
     'config.customDirectoryHint': string;
     'config.customPlaceholder': string;
     'config.invalidScope': string;
+    'config.invalidRuntimeUserScope': string;
     'config.customRequired': string;
     'config.customAbsolute': string;
     'config.saveFailed': string;
@@ -1228,6 +1240,10 @@ export declare const en: {
     'runtime.importance.critical': string;
     'runtime.importance.normal': string;
     'runtime.importance.low': string;
+    'runtime.branches': string;
+    'runtime.branchesPlaceholder': string;
+    'runtime.branchesHint': string;
+    'runtime.branchBadge': string;
     'runtime.empty': string;
     'runtime.editContent': string;
     'runtime.editAction': string;
@@ -1601,6 +1617,13 @@ export declare const en: {
     'config.customHintShort': string;
     'config.customSelected': string;
     'config.globalScopeHint': string;
+    'config.runtimeUserScopeTitle': string;
+    'config.runtimeUserScopeDescription': string;
+    'config.runtimeUserScopeAria': string;
+    'config.runtimeUserScopeStorage': string;
+    'config.runtimeUserScopeStorageHint': string;
+    'config.runtimeUserScopeGlobal': string;
+    'config.runtimeUserScopeGlobalHint': string;
     'config.topologyTitle': string;
     'config.topologyDescription': string;
     'config.topologyLoading': string;
@@ -1721,6 +1744,7 @@ export declare const en: {
     'config.customDirectoryHint': string;
     'config.customPlaceholder': string;
     'config.invalidScope': string;
+    'config.invalidRuntimeUserScope': string;
     'config.customRequired': string;
     'config.customAbsolute': string;
     'config.saveFailed': string;

package/lib/types/src/client/subagent-token-usage.d.ts

@@ -0,0 +1,24 @@
+import type { SessionListState } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
+import type { MnemonClientContext } from './dsh-compat.ts';
+export declare const MNEMON_SUBAGENT_TOKEN_USAGE_KEY = "mnemonSubagentTokenUsage";
+export interface MnemonTokenUsageProjection {
+    uncachedInputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/**
+ * Present the child-local projection under the generic key expected by the
+ * released official catalog component. All other consumers continue seeing
+ * DSH's complete-log `tokenUsage` value.
+ */
+export declare function scopeSubagentTokenUsage(state: SessionListState): SessionListState;
+/** Wrap the framework hook while preserving its selector/equality contract. */
+export declare function createScopedUseSessions(useSessions: SnapshotSelectorHook<SessionListState>): SnapshotSelectorHook<SessionListState>;
+/**
+ * Shadow the released official single-slot entry at a lower priority. The
+ * component and action factory are captured from the public slot ledger, so
+ * Mnemon keeps the official UI, styles, locale, and navigation behavior.
+ */
+export declare function mountSubagentTokenUsageOverride(ctx: MnemonClientContext): () => void;

package/lib/types/src/config-values.d.ts

@@ -7,4 +7,9 @@ export declare const DEFAULT_RECALL_HIGH_SCORE_THRESHOLD = 0.6;
 export declare const DEFAULT_RECALL_CANDIDATE_MULTIPLIER = 3;
 export declare const DEFAULT_RECALL_MAX_MEDIUM_RESULTS = 4;
 export declare const DEFAULT_RECALL_MAX_UNKNOWN_RESULTS = 2;
+export declare const DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES: number;
+export declare const DEFAULT_RUNTIME_USER_LIMIT_BYTES: number;
+export declare const DEFAULT_RUNTIME_MAINTENANCE_MAX_TOKENS = 8192;
+export declare const MAX_RUNTIME_MEMORY_LIMIT_BYTES: number;
+export declare const MAX_RUNTIME_MAINTENANCE_MAX_TOKENS = 1000000;
 export { DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL } from './shared/contracts.ts';

package/lib/types/src/config.d.ts

@@ -1,6 +1,6 @@
 import z from 'schemastery';
 import type { Config as SharedConfig, CustomPackConfig as SharedCustomPackConfig, InteractionConfig as SharedInteractionConfig, ResolvedConfig as SharedResolvedConfig, ResolvedInteractionConfig as SharedResolvedInteractionConfig } from './shared/contracts.ts';
-export { DEFAULT_IDLE_REVIEW_MS, DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL, DEFAULT_RECALL_CANDIDATE_MULTIPLIER, DEFAULT_RECALL_HIGH_SCORE_THRESHOLD, DEFAULT_RECALL_LIMIT, DEFAULT_RECALL_LOW_SCORE_THRESHOLD, DEFAULT_RECALL_MAX_MEDIUM_RESULTS, DEFAULT_RECALL_MAX_UNKNOWN_RESULTS, DEFAULT_RECALL_QUALITY_POLICY, DEFAULT_TIMEOUT_MS, } from './config-values.ts';
+export { DEFAULT_IDLE_REVIEW_MS, DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL, DEFAULT_RECALL_CANDIDATE_MULTIPLIER, DEFAULT_RECALL_HIGH_SCORE_THRESHOLD, DEFAULT_RECALL_LIMIT, DEFAULT_RECALL_LOW_SCORE_THRESHOLD, DEFAULT_RECALL_MAX_MEDIUM_RESULTS, DEFAULT_RECALL_MAX_UNKNOWN_RESULTS, DEFAULT_RECALL_QUALITY_POLICY, DEFAULT_RUNTIME_MAINTENANCE_MAX_TOKENS, DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES, DEFAULT_RUNTIME_USER_LIMIT_BYTES, DEFAULT_TIMEOUT_MS, MAX_RUNTIME_MAINTENANCE_MAX_TOKENS, MAX_RUNTIME_MEMORY_LIMIT_BYTES, } from './config-values.ts';
 export type Config = SharedConfig;
 export type CustomPackConfig = SharedCustomPackConfig;
 export type InteractionConfig = SharedInteractionConfig;

package/lib/types/src/contracts.d.ts

@@ -151,6 +151,14 @@ export interface HostAgent {
             agentPreset?: string;
         };
         events: readonly HostSessionEvent[];
+        /**
+         * Model-visible event sequences, in order. Optional because not every host
+         * publishes a surface projection; when absent, callers fall back to
+         * session-scoped state.
+         */
+        surface?: {
+            readonly nodes: readonly number[];
+        };
     };
     ctx: HostAgentContext;
     followup(message: HostUserMessage): void;

package/lib/types/src/git-branch.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve the current git branch of a workspace root. Returns undefined when
+ * the directory is not a git working tree, HEAD is detached, or the probe
+ * fails or times out, so callers fall back to the unfiltered view.
+ */
+export declare function resolveGitBranch(cwd?: string): string | undefined;

package/lib/types/src/memory-view.d.ts

@@ -1,4 +1,4 @@
-import { MemoryTurnViewManager } from '../packages/kernel/src/index.ts';
+import { MemoryTurnViewManager, type MemorySource } from '../packages/kernel/src/index.ts';
 import type { DocumentManager } from './documents.ts';
 import type { MemoryKernel } from './memory-system/kernel.ts';
 import type { RuntimeMemoryController } from './runtime-memory.ts';
@@ -10,6 +10,12 @@ export interface DefaultMemorySources {
 }
 /** Compatibility name for the v0.3 pre-release API. */
 export type DefaultMemoryViewSources = DefaultMemorySources;
-export declare function createDefaultMemoryTurnViewManager(kernel: MemoryKernel, sources: DefaultMemorySources): MemoryTurnViewManager;
+export type BranchResolver = (cwd?: string) => string | undefined;
+export interface DefaultMemoryTurnViewManagerOptions {
+    /** Override the git branch probe used for runtime branch scoping. Defaults to resolveGitBranch. */
+    resolveBranch?: BranchResolver;
+}
+export declare function createRuntimeMemorySource(runtimeMemory: RuntimeMemoryController, resolveBranch?: BranchResolver): MemorySource;
+export declare function createDefaultMemoryTurnViewManager(kernel: MemoryKernel, sources: DefaultMemorySources, options?: DefaultMemoryTurnViewManagerOptions): MemoryTurnViewManager;
 /** Compatibility name for the v0.3 pre-release API. */
 export declare const createDefaultMemoryViewManager: typeof createDefaultMemoryTurnViewManager;

package/lib/types/src/pack.d.ts

@@ -14,7 +14,8 @@ export declare class MnemonPackManager {
     private readonly afterImport;
     private readonly now;
     private readonly root;
-    constructor(runner: MnemonRunner, config: Pick<ResolvedConfig, 'storageScope'>, afterImport?: (components: MnemonPackComponent[]) => void, now?: () => Date);
+    private readonly runtimeLimits;
+    constructor(runner: MnemonRunner, config: Pick<ResolvedConfig, 'storageScope' | 'runtimeMemory'>, afterImport?: (components: MnemonPackComponent[]) => void, now?: () => Date);
     target(): {
         root: string;
         scope: ResolvedConfig['storageScope'];

package/lib/types/src/runtime-memory.d.ts

@@ -5,10 +5,11 @@ import type { RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEnt
 export type { RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEntry, RuntimeMemoryImportance, RuntimeMemoryMutation, RuntimeMemoryMutationResult, RuntimeMemorySnapshot, RuntimeMemoryTarget, RuntimeMemoryTargetView, RuntimeMemoryUsage, } from './shared/contracts.ts';
 export declare const RUNTIME_MEMORY_VERSION = 1;
 export declare const RUNTIME_ENTRY_DELIMITER = "\n\u00A7\n";
-export declare const RUNTIME_MEMORY_LIMITS: {
+export interface RuntimeMemoryLimits {
     readonly memory: number;
     readonly user: number;
-};
+}
+export declare const RUNTIME_MEMORY_LIMITS: RuntimeMemoryLimits;
 export declare const RUNTIME_MEMORY_PROTOCOL: string;
 export interface RuntimeMemoryContextProjection {
     revision: string;
@@ -37,6 +38,10 @@ export declare class RuntimeMemoryCapacityError extends Error {
 export declare class RuntimeMemoryConflictError extends Error {
     constructor();
 }
+export declare const RUNTIME_BRANCH_NAME_MAX = 128;
+export declare const RUNTIME_BRANCHES_PER_ENTRY_MAX = 16;
+/** Validate a model-supplied branch scope. Returns the normalized list; an empty list means "no scope". */
+export declare function normalizeRuntimeBranches(value: unknown, field?: string): string[];
 /**
  * Single authority for hot memory. JSON is the durable source of truth;
  * Markdown files are deterministic projections consumed by prompt assembly.
@@ -46,15 +51,26 @@ export declare class RuntimeMemoryController {
     private readonly recordCommit?;
     readonly directory: string;
     readonly sourcePath: string;
+    readonly userSourcePath: string;
     readonly memoryPath: string;
     readonly userPath: string;
     readonly lockPath: string;
+    readonly limits: RuntimeMemoryLimits;
     private queue;
-    constructor(runner: Pick<MnemonRunner, 'effectiveDataDir'>, now?: () => Date, recordCommit?: AuthorityCommitRecorder | undefined);
+    private readonly localUserPath;
+    private readonly userController;
+    constructor(runner: Pick<MnemonRunner, 'effectiveDataDir'>, now?: () => Date, recordCommit?: AuthorityCommitRecorder | undefined, limits?: RuntimeMemoryLimits, userRunner?: Pick<MnemonRunner, 'effectiveDataDir'>);
     snapshot(): RuntimeMemorySnapshot;
-    contextText(): string;
-    /** Read the exact Runtime revision and its prompt projection under one lock. */
-    contextProjection(): RuntimeMemoryContextProjection;
+    contextText(branch?: string): string;
+    /**
+     * Read the exact Runtime revision and its prompt projection from each
+     * configured authority root.
+     * When a git branch is supplied, target=memory entries scoped to other
+     * branches are hidden from the projection; the on-disk Markdown files and
+     * the source JSON always remain complete.
+     */
+    contextProjection(branch?: string): RuntimeMemoryContextProjection;
+    private localContextProjection;
     mutate(request: RuntimeMemoryMutation): Promise<RuntimeMemoryMutationResult>;
     /** Resolve exactly which committed entries survive a blocked mutation and are safe to compact. */
     planMaintenance(request: RuntimeMemoryMutation): Promise<RuntimeMemoryMaintenancePlan>;

package/lib/types/src/shared/contracts.d.ts

@@ -104,6 +104,19 @@ export interface RecallQualityConfig {
     /** Maximum unknown-scale or unscored rows admitted by the strict policy. */
     maxUnknownResults?: number;
 }
+export interface RuntimeMemoryConfig {
+    /** Maximum UTF-8 bytes projected into MEMORY.md. */
+    memoryLimitBytes?: number;
+    /** Maximum UTF-8 bytes projected into USER.md. */
+    userLimitBytes?: number;
+    /** Completion-token budget for Runtime migration and compaction workers. */
+    maintenanceMaxTokens?: number;
+}
+export interface ResolvedRuntimeMemoryConfig {
+    memoryLimitBytes: number;
+    userLimitBytes: number;
+    maintenanceMaxTokens: number;
+}
 export interface ResolvedRecallQualityConfig {
     policy: string;
     lowScoreThreshold: number;
@@ -114,6 +127,8 @@ export interface ResolvedRecallQualityConfig {
 }
 export interface Config {
     storageScope?: StorageScopeKind;
+    /** Whether USER.md follows the selected storage root or stays in the global root. */
+    runtimeUserScope?: 'storage' | 'global';
     cliPath?: string;
     dataDir?: string;
     customPackId?: string;
@@ -121,6 +136,7 @@ export interface Config {
     store?: string;
     timeoutMs?: number;
     defaultRecallLimit?: number;
+    runtimeMemory?: RuntimeMemoryConfig;
     /** Optional DSH-owned overrides injected into every Mnemon CLI process. */
     embedding?: MnemonEmbeddingConfig;
     memoryTopology?: MemoryTopologyConfig;
@@ -202,11 +218,13 @@ export interface InteractionConfig {
 }
 export interface ResolvedConfig {
     storageScope: StorageScopeKind;
+    runtimeUserScope: 'storage' | 'global';
     cliPath?: string;
     dataDir?: string;
     store?: string;
     timeoutMs: number;
     defaultRecallLimit: number;
+    runtimeMemory: ResolvedRuntimeMemoryConfig;
     embedding: ResolvedMnemonEmbeddingConfig;
     memoryTopology: ResolvedMemoryTopologyConfig;
     recallQuality: ResolvedRecallQualityConfig;
@@ -683,6 +701,8 @@ export interface RuntimeMemoryEntry {
     updated_at: string;
     target: RuntimeMemoryTarget;
     importance: RuntimeMemoryImportance;
+    /** Optional git branch names that limit where this entry is projected. Absent means every branch. */
+    branches?: string[];
 }
 export interface RuntimeMemoryUsage {
     used: number;
@@ -704,6 +724,8 @@ export interface RuntimeMemorySnapshot {
 export interface RuntimeMemoryCompactedEntry {
     content: string;
     importance: RuntimeMemoryImportance;
+    /** Branch scope carried through compaction; absent means the entry is visible on every branch. */
+    branches?: string[];
 }
 export interface RuntimeMemoryMutation {
     action: RuntimeMemoryAction;
@@ -711,6 +733,8 @@ export interface RuntimeMemoryMutation {
     content?: string;
     oldText?: string;
     importance?: RuntimeMemoryImportance;
+    /** Git branch names limiting where a target=memory entry is projected. Absent keeps the current scope on replace; an empty list clears it. */
+    branches?: string[];
 }
 export type RuntimeMemoryMutationResult = {
     success: true;

package/lib/types/src/subagent-token-usage.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Mnemon-owned projection for provider usage after a subagent descriptor.
+ *
+ * Fork-backed subagents inherit the parent's durable event prefix. DSH's
+ * generic `tokenUsage` projection intentionally totals that complete log, so
+ * it cannot also represent the cost of the child shown in the subagent
+ * catalog. This independent projection keeps the generic metric untouched
+ * and resets at every durable descriptor.
+ */
+import { z } from 'zod';
+import type { HostContextShape, HostSessionEvent } from './contracts.ts';
+export interface MnemonTokenUsageProjection {
+    uncachedInputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+export interface MnemonSubagentTokenUsageState {
+    descriptorSeen: boolean;
+    totals: MnemonTokenUsageProjection;
+    last: {
+        turn: number;
+        step: number;
+        buckets: MnemonTokenUsageProjection;
+    } | null;
+}
+/** Wire key consumed only by Mnemon's subagent-catalog compatibility shim. */
+export declare const MNEMON_SUBAGENT_TOKEN_USAGE_KEY = "mnemonSubagentTokenUsage";
+/**
+ * Fold provider usage after the latest subagent descriptor. A fork may carry
+ * an ancestor descriptor as part of its seed, so every descriptor resets the
+ * fold and the child's own descriptor becomes the final authoritative origin.
+ */
+export declare const mnemonSubagentTokenUsageProjectionDefinition: {
+    readonly key: "mnemonSubagentTokenUsage";
+    readonly stateVersion: 1;
+    readonly stateSchema: z.ZodType<MnemonSubagentTokenUsageState, unknown, z.core.$ZodTypeInternals<MnemonSubagentTokenUsageState, unknown>>;
+    readonly init: () => MnemonSubagentTokenUsageState;
+    readonly apply: (state: MnemonSubagentTokenUsageState, event: HostSessionEvent) => MnemonSubagentTokenUsageState;
+    readonly wire: {
+        readonly viewSchema: z.ZodNullable<z.ZodType<MnemonTokenUsageProjection, unknown, z.core.$ZodTypeInternals<MnemonTokenUsageProjection, unknown>>>;
+        readonly view: (state: MnemonSubagentTokenUsageState) => MnemonTokenUsageProjection | null;
+    };
+};
+/** Register lazily when the optional DSH projection service is present. */
+export declare function registerMnemonSubagentTokenUsageProjection(ctx: HostContextShape): void;

package/lib/types/src/subagent.d.ts

@@ -66,6 +66,7 @@ export declare class MnemonSubagentCoordinator {
     private readonly documents?;
     private readonly resultRuntime?;
     private readonly taskAgentModelResolver?;
+    private readonly runtimeMaintenanceMaxTokensResolver?;
     private readonly counters;
     private runtimeQueue;
     private documentQueue;
@@ -73,7 +74,7 @@ export declare class MnemonSubagentCoordinator {
     constructor(subagents: HostSubagentsService, runtimeMemoryOrSource?: (RuntimeMemoryController | AgentRuntimeSource) | undefined, documents?: DocumentManager | undefined, resultRuntime?: HostResultToolRuntime | undefined, taskAgentModelResolver?: (() => {
         provider: string;
         model: string;
-    } | undefined) | undefined);
+    } | undefined) | undefined, runtimeMaintenanceMaxTokensResolver?: (() => number) | undefined);
     snapshot(): SubagentCounters;
     documentsSnapshot(parent: HostAgent): import("./documents.ts").DocumentSnapshot;
     documentGet(parent: HostAgent, id: string): DocumentView;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mnemon",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Composable three-tier memory control plane for DeepSeek Harness: persistent runtime context, searchable project documents, pluggable long-term memory, guarded strategies, WebUI, and headless tools.",
   "keywords": [
     "deepseek-harness",
@@ -138,7 +138,8 @@
   "dependencies": {
     "fflate": "^0.8.3",
     "markdown-to-jsx": "^7.7.17",
-    "schemastery": "^3.18.0"
+    "schemastery": "^3.18.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6 || ^0.1.1-rc.1",