@tokensapi/dsh-progressive-tools 0.1.0

package/lib/state.d.ts

@@ -0,0 +1,16 @@
+import type { ActiveGroupState, ResolvedConfig, SearchResultValue, StateSnapshot, ToolCatalog } from './types.js';
+export interface ProgressiveState {
+    catalog: ToolCatalog;
+    readonly active: Map<string, ActiveGroupState>;
+    currentTurn: number;
+}
+export declare function createProgressiveState(catalog: ToolCatalog, currentTurn?: number): ProgressiveState;
+export declare function snapshotState(state: ProgressiveState): StateSnapshot;
+export declare function restoreSnapshot(state: ProgressiveState, snapshot: StateSnapshot): void;
+export declare function activateGroups(state: ProgressiveState, groupIds: readonly string[], turn: number, config: ResolvedConfig): {
+    activated: string[];
+    evicted: string[];
+};
+export declare function expireGroups(state: ProgressiveState, turn: number, config: ResolvedConfig): string[];
+export declare function touchTool(state: ProgressiveState, toolName: string, turn: number): void;
+export declare function proposeSearch(source: ProgressiveState, action: SearchResultValue['action'], query: string, limit: number, config: ResolvedConfig): SearchResultValue;

package/lib/state.js

@@ -0,0 +1,110 @@
+import { searchCatalog } from './catalog.js';
+export function createProgressiveState(catalog, currentTurn = 0) {
+    return { catalog, active: new Map(), currentTurn };
+}
+export function snapshotState(state) {
+    return {
+        activeGroups: [...state.active.values()].sort((left, right) => left.id.localeCompare(right.id)),
+    };
+}
+export function restoreSnapshot(state, snapshot) {
+    state.active.clear();
+    for (const entry of snapshot.activeGroups) {
+        if (!state.catalog.groups.has(entry.id))
+            continue;
+        state.active.set(entry.id, { ...entry });
+    }
+}
+function activeTokenEstimate(state) {
+    return [...state.active.keys()].reduce((total, id) => total + (state.catalog.groups.get(id)?.estimatedTokens ?? 0), 0);
+}
+function evictToBudget(state, config, protectedGroups) {
+    const evicted = [];
+    const candidates = () => [...state.active.values()]
+        .filter(entry => !protectedGroups.has(entry.id))
+        .sort((left, right) => left.lastUsedTurn - right.lastUsedTurn
+        || left.activatedAtTurn - right.activatedAtTurn
+        || left.id.localeCompare(right.id));
+    while (state.active.size > config.maxActiveGroups || activeTokenEstimate(state) > config.maxActiveToolTokens) {
+        const candidate = candidates()[0];
+        if (candidate === undefined)
+            break;
+        state.active.delete(candidate.id);
+        evicted.push(candidate.id);
+    }
+    return evicted;
+}
+export function activateGroups(state, groupIds, turn, config) {
+    const activated = [];
+    for (const id of groupIds) {
+        if (!state.catalog.groups.has(id))
+            continue;
+        const current = state.active.get(id);
+        state.active.set(id, {
+            id,
+            activatedAtTurn: current?.activatedAtTurn ?? turn,
+            lastUsedTurn: turn,
+        });
+        activated.push(id);
+    }
+    return {
+        activated,
+        evicted: evictToBudget(state, config, new Set(activated)),
+    };
+}
+export function expireGroups(state, turn, config) {
+    if (config.retentionTurns === 0)
+        return [];
+    const expired = [];
+    for (const entry of state.active.values()) {
+        if (turn - entry.lastUsedTurn < config.retentionTurns)
+            continue;
+        state.active.delete(entry.id);
+        expired.push(entry.id);
+    }
+    return expired;
+}
+export function touchTool(state, toolName, turn) {
+    const groupId = state.catalog.toolToGroup.get(toolName);
+    if (groupId === undefined)
+        return;
+    const current = state.active.get(groupId);
+    if (current === undefined)
+        return;
+    state.active.set(groupId, { ...current, lastUsedTurn: turn });
+}
+function resultValue(state, action, query, matches, activatedGroups, evictedGroups) {
+    const activeGroups = [...state.active.keys()].sort();
+    const activeTools = activeGroups.flatMap(id => state.catalog.groups.get(id)?.tools.map(tool => tool.name) ?? []).sort();
+    const estimatedActiveTokens = activeTokenEstimate(state);
+    return {
+        protocol: 'dsh-progressive-tools/v1',
+        action,
+        query,
+        matches,
+        activatedGroups,
+        evictedGroups,
+        activeGroups,
+        activeTools,
+        estimatedActiveTokens,
+        estimatedCatalogTokens: state.catalog.totalEstimatedTokens,
+        estimatedSavedTokens: Math.max(0, state.catalog.totalEstimatedTokens - estimatedActiveTokens),
+        catalogTools: state.catalog.tools.size,
+        state: snapshotState(state),
+    };
+}
+export function proposeSearch(source, action, query, limit, config) {
+    const state = createProgressiveState(source.catalog, source.currentTurn);
+    restoreSnapshot(state, snapshotState(source));
+    if (action === 'status')
+        return resultValue(state, action, '', [], [], []);
+    if (action === 'reset') {
+        const evicted = [...state.active.keys()].sort();
+        state.active.clear();
+        return resultValue(state, action, '', [], [], evicted);
+    }
+    const matches = searchCatalog(state.catalog, query, limit);
+    const selected = matches.slice(0, config.activationGroupLimit).map(match => match.group);
+    const { activated, evicted } = activateGroups(state, selected, state.currentTurn, config);
+    return resultValue(state, action, query, matches, activated, evicted);
+}

package/lib/types.d.ts

@@ -0,0 +1,120 @@
+export interface ToolSchemaView {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+}
+export interface ToolGroupConfig {
+    readonly id: string;
+    readonly description?: string;
+    readonly aliases?: readonly string[];
+    readonly include: readonly string[];
+    readonly exclude?: readonly string[];
+}
+export interface SkillBindingConfig {
+    readonly skill: string;
+    readonly groups: readonly string[];
+}
+export type ProgressiveMode = 'stable-proxy' | 'dynamic';
+export interface ResolvedConfig {
+    readonly mode: ProgressiveMode;
+    readonly toolName: string;
+    readonly dispatchToolName: string;
+    readonly alwaysVisible: readonly string[];
+    readonly groups: readonly ToolGroupConfig[];
+    readonly skillBindings: readonly SkillBindingConfig[];
+    readonly maxResults: number;
+    readonly activationGroupLimit: number;
+    readonly maxActiveGroups: number;
+    readonly maxActiveToolTokens: number;
+    readonly retentionTurns: number;
+    readonly charactersPerToken: number;
+    readonly requireDiscovery: boolean;
+    readonly statusGrantsDiscovery: boolean;
+    readonly deferToolGuidance: boolean;
+}
+export interface CatalogTool extends ToolSchemaView {
+    readonly estimatedTokens: number;
+    readonly searchText: string;
+}
+export interface ToolGroup {
+    readonly id: string;
+    readonly description: string;
+    readonly aliases: readonly string[];
+    readonly tools: readonly CatalogTool[];
+    readonly estimatedTokens: number;
+    readonly searchText: string;
+}
+export interface ToolCatalog {
+    readonly tools: ReadonlyMap<string, CatalogTool>;
+    readonly groups: ReadonlyMap<string, ToolGroup>;
+    readonly toolToGroup: ReadonlyMap<string, string>;
+    readonly totalEstimatedTokens: number;
+}
+export interface SearchMatch {
+    readonly group: string;
+    readonly description: string;
+    readonly score: number;
+    readonly estimatedTokens: number;
+    readonly tools: readonly string[];
+}
+/** One exact deferred definition returned by stable-proxy discovery. */
+export interface DeferredToolMatch extends ToolSchemaView {
+    readonly group: string;
+    readonly score: number;
+    readonly estimatedTokens: number;
+    /** Every member name of the owning family, so siblings surface in one search. */
+    readonly groupTools: readonly string[];
+}
+/** One browsable deferred family listed by the stable-proxy status action. */
+export interface DeferredGroupSummary {
+    readonly id: string;
+    readonly description: string;
+    readonly tools: readonly string[];
+}
+export interface ProxySearchResultValue {
+    readonly protocol: 'dsh-progressive-tools/v2';
+    readonly mode: 'stable-proxy';
+    readonly action: 'search' | 'status';
+    readonly query: string;
+    readonly matches: readonly DeferredToolMatch[];
+    /** Complete deferred family catalog, included by the status action. */
+    readonly groups?: readonly DeferredGroupSummary[];
+    readonly stableTools: readonly string[];
+    /** Names newly discovered by this call; earlier discoveries are not repeated. */
+    readonly discoveredTools: readonly string[];
+    /** Cumulative number of discovered deferred tools. */
+    readonly discoveredCount: number;
+    /**
+     * Cumulative discovered names. Carried in presentation metadata for resume
+     * and stripped from the rendered text to keep conversation growth bounded.
+     */
+    readonly allDiscoveredTools: readonly string[];
+    readonly catalogTools: number;
+    readonly estimatedVisibleTokens: number;
+    readonly estimatedCatalogTokens: number;
+    readonly estimatedSavedTokens: number;
+    readonly instruction: string;
+}
+export interface ActiveGroupState {
+    readonly id: string;
+    readonly activatedAtTurn: number;
+    readonly lastUsedTurn: number;
+}
+export interface StateSnapshot {
+    readonly activeGroups: readonly ActiveGroupState[];
+}
+export interface SearchResultValue {
+    readonly protocol: 'dsh-progressive-tools/v1';
+    readonly action: 'search' | 'status' | 'reset';
+    readonly query: string;
+    readonly matches: readonly SearchMatch[];
+    readonly activatedGroups: readonly string[];
+    readonly evictedGroups: readonly string[];
+    readonly activeGroups: readonly string[];
+    readonly activeTools: readonly string[];
+    readonly estimatedActiveTokens: number;
+    readonly estimatedCatalogTokens: number;
+    readonly estimatedSavedTokens: number;
+    readonly catalogTools: number;
+    readonly state: StateSnapshot;
+}

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@tokensapi/dsh-progressive-tools",
+  "version": "0.1.0",
+  "description": "TokensCowork cache-stable progressive tool discovery and dispatch for DeepSeek Harness",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml",
+    "docs/**/*.md",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "oxlint src tests",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "audit:session": "node scripts/audit-session.mjs",
+    "check": "node --check scripts/audit-session.mjs && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run build && pnpm run publint",
+    "publint": "publint",
+    "prepare": "pnpm run build",
+    "prepack": "pnpm run check"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.19.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TokensAPI/tokens_DshProgressiveTools_code.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TokensAPI/tokens_DshProgressiveTools_code/issues"
+  },
+  "homepage": "https://github.com/TokensAPI/tokens_DshProgressiveTools_code#readme",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "cordis",
+    "tokenscowork",
+    "tools",
+    "progressive-disclosure",
+    "token-optimization"
+  ],
+  "author": "TokensAPI contributors",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.8"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-agent-loop": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-scope": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.8",
+    "@types/node": "^22.19.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "oxlint": "^1.76.0",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}