@stackstackstack/dsh-compaction-basic 0.1.5

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@stackstackstack/dsh-compaction-basic`.
+* @module @stackstackstack/dsh-compaction-basic/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-compaction-basic";
+/** Cordis companion plugin name. */
+const name = "compaction-basic-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Load-time validation and routed-model policy resolution for compaction-basic.
+ *
+ * @module @stackstackstack/dsh-compaction-basic/config
+ */
+import type { LlmCallConfig } from '@stackstackstack/dsh-llm';
+import type { BasicCompactionConfig, ResolvedCompactSpec, ResolvedConfig, ResolvedTargetPolicy } from './types.ts';
+/** Target-specific pressure configuration failure eligible for warning suppression. */
+export declare class TargetPressureConfigError extends Error {
+    readonly targetKey: string;
+    /**
+     * @param targetKey - exact provider/model route used as the warning key.
+     * @param message - actionable configuration failure detail.
+     */
+    constructor(targetKey: string, message: string);
+}
+/**
+ * Resolve and validate service defaults plus exact-target partial overrides.
+ * @param config - untrusted plugin configuration after Loader normalization.
+ * @returns detached immutable defaults and validated exact-target overrides.
+ */
+export declare function resolveConfig(config?: BasicCompactionConfig): ResolvedConfig;
+/**
+ * Merge the exact provider/model override over the validated default policy.
+ * @param config - validated service defaults and override table.
+ * @param target - exact durable provider/model route to match.
+ * @returns detached immutable policy before model-capacity scaling.
+ */
+export declare function resolveTargetPolicy(config: ResolvedConfig, target: Pick<LlmCallConfig, 'provider' | 'model'>): ResolvedTargetPolicy;
+/**
+ * Scale one routed policy into concrete token budgets for its model capacity.
+ * @param policy - merged policy for the exact routed target.
+ * @param contextWindow - positive adapter-owned capacity for that target.
+ * @returns detached immutable pressure and retention budgets.
+ */
+export declare function resolveCompactSpec(policy: ResolvedTargetPolicy, contextWindow: number): ResolvedCompactSpec;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Basic replay-aware compaction backend.
+ *
+ * @module @stackstackstack/dsh-compaction-basic
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { CompactionEngine } from '@stackstackstack/dsh-compaction';
+import type { CompactionResult, CompactionTrigger } from '@stackstackstack/dsh-compaction';
+import type { Agent } from '@stackstackstack/dsh-agent';
+import type { CommandId } from '@stackstackstack/dsh-commands/brand';
+import type { SummarizationInput, SummaryResult } from './summarizer.ts';
+import type { BasicCompactionConfig, ResolvedConfig } from './types.ts';
+export type { BasicCompactionConfig, CompactionPolicyConfig, ModelCompactPolicyConfig, ResolvedCompactSpec, ResolvedConfig, ResolvedRetention, ResolvedTargetPolicy, } from './types.ts';
+/**
+ * Dependency-light compaction backend using `ctx.tokenMeter` for pressure,
+ * retention, cited source events, and summary-convergence pricing.
+ *
+ * `summarize()` is the sole subclass customization hook; the replay and durable
+ * mutation strategy stays fixed so every pricing decision uses the singleton
+ * token meter.
+ */
+export declare class BasicCompactionEngine extends CompactionEngine {
+    static inject: string[];
+    static Config: z<BasicCompactionConfig>;
+    /** Resolved and validated compaction configuration. */
+    readonly config: ResolvedConfig;
+    private readonly warnedPressureConfigTargets;
+    private readonly overflowRetries;
+    private readonly overflowAgents;
+    constructor(ctx: Context, config?: BasicCompactionConfig);
+    /**
+     * Register automatic between-step pressure and model-request overflow
+     * recovery. `compactIfNeeded` stays dynamically dispatched so subclass
+     * overrides are honored at event time.
+     */
+    private _registerAutomaticCompaction;
+    /**
+     * Summarize the replayed conversation region through a direct one-shot
+     * `ctx.llm.stream()` call whose prefix reuses the conversation's own system
+     * prompt, tools, and messages so the provider's KV cache is not invalidated.
+     * Override this sole hook for a template or remote summarizer.
+     * @param input - replayed conversation prefix (system, tools, and leading messages) to condense.
+     * @param agent - supplies routed-model history, fallback model, and session id.
+     * @param signal - optional cancellation forwarded to the adapter.
+     * @returns safe text summary blocks and the exact auxiliary call envelope and output.
+     */
+    protected summarize(input: SummarizationInput, agent: Agent, signal?: AbortSignal): Promise<SummaryResult>;
+    /**
+     * Compact for replayed step-boundary pressure or one provider-confirmed context
+     * overflow. Both triggers price the latest durable routed request envelope;
+     * overflow bypasses the normal threshold and retained-tail policy so it can
+     * force one useful balanced reduction.
+     * @param agent - agent whose latest durable routed request is measured.
+     * @param trigger - normal step-boundary pressure or context-overflow recovery.
+     * @param signal - live turn cancellation signal forwarded to summarization.
+     * @returns the latest summary compaction result, or `null` when no summary ran.
+     */
+    compactIfNeeded(agent: Agent, trigger: CompactionTrigger, signal: AbortSignal): Promise<CompactionResult | null>;
+    /**
+     * Compact one inclusive positional range from the agent-owned surface using
+     * the effective token meter for all retention and shrink pricing.
+     * @param start - inclusive first surface-node seq.
+     * @param end - inclusive last surface-node seq.
+     * @param agent - owner of the target session, used by the summarizer.
+     * @param signal - optional summarization cancellation signal.
+     * @returns the successful durable compaction result.
+     */
+    compactRegion(start: number, end: number, agent: Agent, signal?: AbortSignal): Promise<CompactionResult>;
+    /**
+     * Force one useful idle-session compaction below the pressure threshold, and
+     * resolve only after its standalone marker pair is durably checkpointed.
+     * @param agent - idle agent whose next-turn admission this call reserves.
+     * @param signal - cancellation scoped to this compaction request.
+     * @param sourceCommandId - initiating command identity for presentation correlation.
+     * @returns the committed result, or `null` when no safe useful range exists.
+     */
+    compactNow(agent: Agent, signal: AbortSignal, sourceCommandId?: CommandId): Promise<CompactionResult | null>;
+    /** Bind the effective token meter and dynamically dispatched summarizer hook. */
+    private regionDependencies;
+}
+export default BasicCompactionEngine;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@stackstackstack/dsh-compaction-basic`.
+ * @module @stackstackstack/dsh-compaction-basic/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "compaction-basic-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/region.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Surface retention selection and the shared log-recorded compaction
+ * transaction for automatic open-turn and manual idle-session compaction.
+ *
+ * @module @stackstackstack/dsh-compaction-basic/region
+ */
+import type { CompactionResult } from '@stackstackstack/dsh-compaction';
+import type { CommandId } from '@stackstackstack/dsh-commands/brand';
+import type { TokenMeasurement, TokenMeter } from '@stackstackstack/dsh-token-meter';
+import type { Session } from '@stackstackstack/dsh-session';
+import type { Agent } from '@stackstackstack/dsh-agent';
+import type { SummarizationInput, SummaryResult } from './summarizer.ts';
+interface RegionDependencies {
+    readonly meter: TokenMeter;
+    summarize(input: SummarizationInput, agent: Agent, signal?: AbortSignal): Promise<SummaryResult>;
+}
+interface CompactionTransactionOptions {
+    /** `current-turn` derives a numbered owner; `null` writes a standalone bracket. */
+    readonly owner: 'current-turn' | null;
+    /** Surface relationship that must survive asynchronous summarization. */
+    readonly stability: 'whole-surface' | 'selected-span';
+    /** Optional durability checkpoint after a successfully closed bracket. */
+    readonly flush?: () => Promise<void>;
+    /** Manual command that initiated this transaction, when present. */
+    readonly sourceCommandId?: CommandId;
+}
+/**
+ * Resolve the next head-anchored range while retaining a priced recent tail
+ * and never splitting an assistant tool-call/result pair.
+ * @param session - session supplying authoritative current surface positions.
+ * @param measurement - unified pressure and surface measurement from the conversation meter.
+ * @param retainTokens - minimum recent tail budget retained verbatim.
+ * @returns the inclusive positional seq range to compact, or `null`.
+ */
+export declare function selectCompactableRange(session: Session, measurement: TokenMeasurement, retainTokens: number): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Run the single compaction transaction over one selected positional span.
+ * Selection and validation are read-only. Idle/log validation and
+ * `compaction/start` are synchronously adjacent, so the durable opening marker is
+ * the compaction lock before summarization yields. Every later failure makes
+ * exactly one `compaction/end` attempt; a failed close deliberately leaves the
+ * unmatched start detectable.
+ * @param dependencies - conversation meter and dynamically dispatched summarizer hook.
+ * @param session - session whose surface is mutated.
+ * @param start - inclusive first surface-node seq.
+ * @param end - inclusive last surface-node seq.
+ * @param agent - agent used by the summarizer.
+ * @param options - bracket owner, stability rule, and optional durability checkpoint.
+ * @param signal - optional summarization cancellation signal.
+ * @returns the successful durable compaction result.
+ */
+export declare function compactSurfaceRegion(dependencies: RegionDependencies, session: Session, start: number, end: number, agent: Agent, options: CompactionTransactionOptions, signal?: AbortSignal): Promise<CompactionResult>;
+/**
+ * Recheck the durable compaction lock after an asynchronous policy decision.
+ * @param session - session whose latest marker state is inspected.
+ * @param stage - operation label included in the busy diagnostic.
+ */
+export declare function assertNoActiveCompaction(session: Session, stage: string): void;
+export {};
+//# sourceMappingURL=region.d.ts.map

package/lib/types/summarizer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Default one-shot summarization and durable checkpoint framing.
+ *
+ * @module @stackstackstack/dsh-compaction-basic/summarizer
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ContentBlock, Message, TokenUsage, ToolSchema } from '@stackstackstack/dsh-llm';
+import type { Agent } from '@stackstackstack/dsh-agent';
+interface SummaryConfig {
+    readonly summarizationProvider: string;
+    readonly summarizationModel: string;
+    readonly maxTokens: number;
+}
+/**
+ * The replayed conversation surface the summarizer condenses. Reproducing the
+ * last routed request's system prompt, tools, and leading messages verbatim
+ * lets the auxiliary call reuse the provider's warm prefix cache; the trailing
+ * compaction instruction is then the only novel input.
+ */
+export interface SummarizationInput {
+    /** The conversation's own system prompt, reused for prefix-cache alignment; absent for a system-less request. */
+    readonly system?: string;
+    /** The conversation's tool schemas, reused for prefix-cache alignment; absent when the request carried none. */
+    readonly tools?: readonly ToolSchema[];
+    /** The shadowed region, in surface order, that precedes the compaction instruction. */
+    readonly messages: readonly Message[];
+}
+/** Safe summary content plus the exact auxiliary call envelope recorded with it. */
+export type SummaryResult = {
+    summary: ContentBlock[];
+    provider: string;
+    model: string;
+    maxTokens?: number;
+    /** Provider-reported usage for this summarization request. */
+    usage?: TokenUsage;
+} & ({
+    /** Complete provider output before the text-only summary projection. */
+    rawOutput: ContentBlock[];
+    /** Identifies exactly one call through this context's `ctx.llm.stream()`. */
+    llmStreamCall: true;
+} | {
+    /** Optional complete output from an unmarked template, remote, or other summarizer. */
+    rawOutput?: ContentBlock[];
+    /** An unmarked result does not identify a call through this context's LLM seam. */
+    llmStreamCall?: never;
+});
+/**
+ * Run the default cache-reusing `ctx.llm.stream()` summarization call: replay
+ * the conversation prefix, then append the compaction instruction as the final
+ * user message so the provider's warm prefix cache is reused.
+ * @param ctx - context providing the LLM service.
+ * @param config - resolved backend configuration.
+ * @param input - replayed conversation prefix (system, tools, and leading messages) to condense.
+ * @param agent - supplies routed-model history, fallback model, and session id.
+ * @param signal - optional cancellation forwarded to the adapter.
+ * @returns safe text-only summary blocks and the exact call envelope and output.
+ */
+export declare function summarizeWithLlm(ctx: Context, config: SummaryConfig, input: SummarizationInput, agent: Agent, signal?: AbortSignal): Promise<SummaryResult>;
+/**
+ * Wrap raw summary blocks in the durable checkpoint framing.
+ * @param summary - safe text-only model output.
+ * @returns content for the synthesized replacement user message.
+ */
+export declare function frameSummary(summary: readonly ContentBlock[]): ContentBlock[];
+export {};
+//# sourceMappingURL=summarizer.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Configuration vocabulary for the replay-aware basic compaction backend.
+ *
+ * @module @stackstackstack/dsh-compaction-basic/types
+ */
+import type { LlmCallConfig } from '@stackstackstack/dsh-llm';
+/** Policy fields shared by the default policy and exact model overrides. */
+export interface CompactionPolicyConfig {
+    /** Compact at this fraction of the model's context window. Defaults to `0.8`. */
+    thresholdRatio?: number;
+    /** Recent context retained as a fraction of the model's window. Defaults to `0.16`. */
+    retainRatio?: number;
+    /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */
+    retainTokens?: number;
+    /** Summary provider; set together with `summarizationModel`, or inherit the conversation target. */
+    summarizationProvider?: string;
+    /** Summary model; set together with `summarizationProvider`, or inherit the conversation target. */
+    summarizationModel?: string;
+    /** Provider generation cap for summarization. Defaults to `8192`. */
+    maxTokens?: number;
+    /** Extra attempts after the first compaction when pressure remains above threshold. Defaults to `1`. */
+    compactionRetries?: number;
+    /** Maximum retries after canonical context overflow; `0` disables recovery. Defaults to `1`. */
+    maxOverflowRetries?: number;
+}
+/** Exact provider/model override merged over the default compaction policy. */
+export interface ModelCompactPolicyConfig extends CompactionPolicyConfig {
+    /** Registered provider route to match. */
+    provider: string;
+    /** Exact routed model id to match within `provider`. */
+    model: string;
+}
+/** Basic compaction configuration with an optional exact-target policy table. */
+export interface BasicCompactionConfig extends CompactionPolicyConfig {
+    /** Exact provider/model overrides; duplicate targets fail plugin load. */
+    modelPolicies?: ModelCompactPolicyConfig[];
+    /** Enable automatic step-boundary pressure and overflow-recovery listeners. Defaults to `true`. */
+    auto?: boolean;
+}
+/** Exactly one validated retention form. */
+export type ResolvedRetention = {
+    readonly retainRatio: number;
+    readonly retainTokens?: never;
+} | {
+    readonly retainRatio?: never;
+    readonly retainTokens: number;
+};
+/** Validated policy fields shared before and after exact-target matching. */
+interface ResolvedPolicyFields {
+    readonly thresholdRatio: number;
+    readonly summarizationProvider: string;
+    readonly summarizationModel: string;
+    readonly maxTokens: number;
+    readonly compactionRetries: number;
+    readonly maxOverflowRetries: number;
+}
+/** Validated immutable config whose target-specific defaults remain unresolved. */
+export type ResolvedConfig = ResolvedPolicyFields & ResolvedRetention & {
+    readonly modelPolicies: readonly Readonly<ModelCompactPolicyConfig>[];
+    readonly auto: boolean;
+};
+/** Fully merged policy for one routed conversation target, before capacity scaling. */
+export type ResolvedTargetPolicy = ResolvedPolicyFields & ResolvedRetention & {
+    readonly target: Pick<LlmCallConfig, 'provider' | 'model'>;
+};
+/** One routed model's concrete pressure and retention budget. */
+export type ResolvedCompactSpec = Omit<ResolvedTargetPolicy, 'retainRatio' | 'retainTokens'> & {
+    readonly contextWindow: number;
+    readonly thresholdTokens: number;
+    readonly retainTokens: number;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@stackstackstack/dsh-compaction-basic",
+  "description": "Token-meter-driven compaction policy and LLM summarization backend for the DeepSeek Harness",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/compaction/compaction-basic"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-compaction": "^0.1.5",
+    "@stackstackstack/dsh-commands": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-token-meter": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@stackstackstack/dsh-compaction-tool-result-pruner": "^0.1.5"
+  },
+  "peerDependenciesMeta": {
+    "@stackstackstack/dsh-compaction-tool-result-pruner": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+    "@stackstackstack/dsh-agent-loop-testkit": "^0.1.5",
+    "@stackstackstack/dsh-agent-loop": "^0.1.5",
+    "@stackstackstack/dsh-compaction": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@stackstackstack/dsh-llm-retry": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-commands": "^0.1.5",
+    "@stackstackstack/dsh-compaction-tool-result-pruner": "^0.1.5",
+    "@stackstackstack/dsh-tools": "^0.1.5",
+    "@stackstackstack/dsh-token-meter": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}