dsh-agent-preset-recommender

English | 中文

A persistent, host-side DeepSeek Harness bundle that privately summarizes local Codex, Claude Code, and WorkBuddy/CodeBuddy activity and recommends a built-in DSH agent preset. It is advisory only: there is no LLM call, installation, preset mutation, or network request.

Preview

These previews use synthetic aggregate fixture data. They illustrate the bounded tool results only; no user sessions, paths, prompts, commands, or secrets appear.

Capability map

Install

dsh plugin --profile web add github:LeemanCheung/dsh-agent-preset-recommender

Restart the selected DSH profile after installation. The package declares dsh.bundle.patch and mounts one host plugin.

What it recommends

Observed aggregate behavior is mapped to:

• capability presets: minimal or standard.

code is a Code Mode presentation variant of standard, so this scanner never infers it from local activity volume or silently recommends it as a capability tier.

• optional capabilities: Codex delegation, Claude Code delegation, workflows, web, MCP, and LSP.

Every recommendation includes confidence and numerical evidence. Thresholds are deterministic and local; results never automatically change DSH.

Exact recommendation and evidence rules

• standard is recommended when at least one recognized session, workflow, or categorized tool call exists. Metadata files alone—and an empty observation set—yield minimal.
• Codex/Claude Code delegation needs a recognized session from that source. Workflows need a workflow count or workflow-category tool call; web, MCP, and LSP need their corresponding category count.
• Confidence is 0 with no observations; otherwise it is min(0.95, 0.35 + 0.2 × log10(observations + 1)), rounded to two decimal places, where observations are sessions + workflows + categorized tool calls.
• Tool names first use exact delegation aliases, then the fixed heuristic order delegation → workflow → MCP → LSP → web → shell → search → files; the first match wins and unmatched names are other. These are trend signals, not an audit of every product tool.

Architecture

cordis.patch.yml → src/index.js (Cordis lifecycle + raw model tools)
                    ├─ scanner.js (bounded traversal and aggregation)
                    ├─ extractors.js (selected JSON/JSONL metadata fields)
                    ├─ recommender.js (deterministic rules)
                    ├─ store.js (atomic private report file)
                    └─ render.js (bounded readable tool output)

Runtime code is plain ESM JavaScript for Node.js 20+. It uses Node built-ins plus @deepseek-ai/schemastery for plugin configuration validation. Tool definitions are registered directly through ctx.tools.register and do not import unpublished DSH tool runtime helpers.

Privacy

The scanner persists aggregate metadata only:

• source and installation-keyed project identifier;
• categorized tool counts;
• session, workflow, and project-metadata counts;
• first/last observation dates (day-level);
• recommendation, confidence, and evidence counts;
• an explicit machine-readable privacy declaration.

It never persists prompts, responses, commands, tool arguments, raw events, absolute paths, usernames, secrets, or file contents. Project identifiers are derived with a random installation-local HMAC key, so report IDs cannot be dictionary-matched without the private key. WorkBuddy/CodeBuddy memory metadata is counted from file presence and modification time only; workflow/plan files are likewise never opened. The scanner makes no network requests and runs no discovered command.

Cache, dependency, build, output, coverage, virtual-environment, and .git directories are skipped. Symbolic links are not followed.

The default report is:

$DSH_HOME/state/agent-preset-recommender/report.json

If DSH_HOME is unset, ~/.dsh is used. The directory also holds a private random identity.key used only to derive project IDs. Report writes use a same-directory temporary file and atomic rename; restrictive permissions are requested where the platform supports them.

Supported locations and formats

Formats vary between product releases. CodeBuddy paths/workflow scripts are documented; WorkBuddy session-file detection is an observed heuristic. Unknown fields are ignored, malformed records are skipped, and malformed files are counted as errors without stopping the scan.

Configuration

Configure the inserted agent-preset-recommender row in a DSH patch:

- id: agent-preset-recommender
  config:
    scanOnStart: true
    intervalMinutes: 360      # 0 disables scheduled scans
    maxFilesPerSource: 500
    maxBytesPerFile: 1048576
    recentDays: 90
    stateDirectory: ''        # empty = $DSH_HOME/state/agent-preset-recommender
    codexRoots:
      - ~/.codex/sessions
      - ~/.codex/archived_sessions
    claudeRoots:
      - ~/.claude/projects
    claudeTranscriptRoots: [] # opt in explicitly
    claudeWorkflowRoots:
      - ~/.claude/workflows   # inventory only; script content is never read
    workbuddyRoots:
      - ~/.codebuddy
      - ~/.workbuddy
      - ~/.workbuddy-ai
      - ~/WorkBuddy
      - ~/CodeBuddy

Defaults honor CODEX_HOME, CLAUDE_CONFIG_DIR, CODEBUDDY_CONFIG_DIR, and WORKBUDDY_CONFIG_DIR when DSH starts. Supplying an explicit root list in the plugin configuration takes precedence over those defaults.

Bounds are validated: intervalMinutes is 0–35,791, maxFilesPerSource 1–100,000, maxBytesPerFile 1 KiB–64 MiB, and recentDays 1–3,650. Missing/inaccessible roots are skipped. Startup, scheduled, and tool-triggered scans share one serialized queue and are aborted on plugin disposal.

Set both scanOnStart: false and intervalMinutes: 0 to disable automatic scans; the model tool can still scan on demand. Before deleting the state directory to reset the report, stop the plugin: this also removes identity.key, intentionally rotating every keyed project ID.

Model tools

scan_agent_projects

Runs and persists a fresh scan. Optionally refresh only selected sources:

{ "sources": ["codex", "claude"] }

Unselected source aggregates from the previous report remain intact.

get_agent_preset_recommendations

Reads the persisted report without scanning:

{}

Or retrieve one keyed project:

{ "project_id": "codex-0123456789abcdef" }

Both tools return bounded readable text strings. Omitting sources or passing an empty list scans every source; a selected-source scan preserves the prior aggregate for unselected sources.

Each persisted source report exposes filesConsidered, truncatedFiles, skippedOld, skippedOversize, skippedLimit, and parseOrAccessErrors alongside counts. Summary output lists at most 50 projects and is capped at 12,000 characters; query a project_id for its bounded detail.

Limitations

• Metadata schemas are intentionally conservative; unrecognized tool events may be undercounted.
• Keyed IDs are stable only while the private state directory remains available; deleting identity.key intentionally creates a new identifier set.
• A recommendation reflects observed local frequency, not task quality or organizational policy.
• The plugin does not verify that optional products or capabilities are installed or authenticated.
• JSONL files above the byte cap are prefix-sampled within the byte/record bounds; their remaining data, oversized JSON files, old files, and older files beyond a source limit are intentionally omitted. Compressed Codex .jsonl.zst rollouts are not read in 0.1.6. Claude workflow scripts and dynamic workflow sidecars are deliberately not parsed.

Development

npm install
npm test

Tests use synthetic temporary fixtures and Node's built-in node:test; no local product data is read. See SECURITY.md for private vulnerability reporting guidance.

License

MIT