dsh-iris

Readme

# dsh-iris

Progressive capability selection for DeepSeek Harness. The current model reads short descriptions, selects a capability, and uses DSH's normal loading and execution path.

[简体中文](README.zh-CN.md)

Iris is named after the eye's iris: it adjusts capability exposure within the current Agent's mode and permissions. It preserves native persona and does not require another routing model or any GPT-6 API dependency.

## How selection works

Adaptive modes expose core tools and an Agent-scoped `iris:capabilities` section. A small catalog is described directly; larger catalogs retain `iris_search` for capabilities outside the card budget. Already available native tools, Skills and MCP tools follow their native routes without redundant activation.

```text
short description → current model selects capability ID
  visible native Tool / MCP → normal DSH call
  hidden authorized inherited Tool → iris_activate → normal DSH call
  configured local Provider → iris_activate → import/apply/verify → normal DSH call
  Native Skill → native skill route (reveal its entry only if needed)
  insufficient description → iris_search → select the result's route
```

Metadata reads never import Providers, load Skill bodies, connect MCP servers or execute business tools. Description text grants no permissions. Iris does not install community plugins, create a second Skill/MCP runtime, or proxy calls through a generic JSON execution tool.

## Modes and host boundaries

| Mode | Behavior |
| --- | --- |
| Minimal / Preserve | Native persona, tools and order; no Iris controls, cards or automatic activation. Unknown custom modes default to Preserve. |
| Standard | Core tools and budgeted cards; explicit activation for hidden or unmounted capabilities; search for the long tail. |
| Code / PTC | Native `run_code` and DSH SDK. A running program keeps its bindings; newly activated capabilities wait for the subsequent host step. |
| Cordis / creation | Native persona, creation restrictions and creation entries remain available, including `cordis_mount` / `cordis_unmount`. A failed search does not authorize plugin creation. |

DSH rc.6 restrictions filter inherited tools, but cannot safely hide tools registered in the Agent's own scope. Such MCP tools remain native-visible. A Provider registering several Agent-owned tools exposes its actual Provider loading unit. Iris reports that boundary instead of promising one-tool isolation. Optional inherited tools use precise disclosure or a small explicit native dependency group; unknown extensions do not share an all-extensions switch.

MCP runtime identity uses the full registered name, such as `mcp__github__create_issue`; a short display name is not an execution identity. DSH retains authorization, approval, guards, cancellation and ownership. Configured but disconnected MCP activation is unsupported because the installed host lacks a sufficient public enumeration/connection lifecycle contract.

## Install and configure

```sh
dsh plugin --profile web add dsh-iris
dsh --profile web
```

Use the Iris control beside the mode selector and **Settings → Iris** for configuration and telemetry. These installation commands are documentation; local repository verification does not install or publish a plugin.

Default card budgets are **8 cards**, **200 Unicode characters per description**, and **1800 Unicode characters for the section**. They are initial product parameters, not token estimates. Whole over-budget description fields are omitted with a search fallback; IDs and routes are never cut. Native Skill descriptions are left with their native owner to avoid duplicate cards.

```yaml
iris:
  enabled: true
  policy: auto
  legacyInterface: false
  cards:
    maxCards: 8
    descriptionChars: 200
    totalChars: 1800
```

New sessions register `iris_search` and `iris_activate`. Set `legacyInterface: true` to retain `iris_recommend`; it is not registered by default. Existing sessions retain their captured policy, Provider configuration, budgets and control set to avoid changing replay contracts. Changes apply to new sessions; disabling Iris immediately tears down its active runtimes. Older configurations receive the new defaults.

Configured local capabilities support `description`, `whenToUse` and bilingual `keywords`. Configured `kind: skill` is not a local Skill loader; use DSH's native Skill configuration. Local Providers require explicit activation and policy checks.

For [the local text-tools example](examples/local-text-tools), a card can lead directly to:

```text
iris_activate({ capabilityId: "tool:text_word_count" })
→ import / apply / verify / reveal
text_word_count({ text: "Iris opens only when needed." })
→ native ToolRuntime
```

The intended direct-card path has one activation control call and one Provider apply, with no search/recommend prerequisite. See integration tests for measured fixture behavior; this trace is not a model performance measurement.

## State and evidence

Settings separates catalogued, mounted, visible and staged capabilities. Catalog counts and exposed tool-schema counts are different units; one `run_code` schema can expose many SDK capabilities. Host registration does not prove current-program readiness. rc.6 has no public structured current-step binding inventory, so SDK readiness requires the pinned host execution contract rather than a substring match.

The [architecture](docs/architecture.md) and [optimization audit](docs/optimization-audit.md) record implementation boundaries and verification. Historical [single-pair A/B results](benchmarks/LIGHT-AB-REPORT.md) remain dated sanity checks, including slower Code execution; persona rewrites in older experiments are a confound. [The new offline comparison](benchmarks/OPTIMIZATION-OFFLINE.md) checks transport and verifiers only. It establishes no token, latency or task-success improvement. No paid model evaluation is included in this round.

## Development

Node >=22 and pnpm 11.7.0; the local integration baseline uses DSH 0.1.0-rc.6.

```sh
pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm smoke:release
pnpm smoke:package
pnpm benchmark:optimization
```

`smoke:package` inspects the real tarball and installs it offline into a temporary DSH host fixture. It imports server exports and resolves the browser client; browser rendering still requires DSH Web. Benchmarks and Python caches are excluded from npm packaging. CI runs local checks without credentials, paid requests or publishing. See [benchmark instructions](benchmarks/README.md) for the remaining live-evaluation requirements.

## License

MIT for Iris. See [LICENSE](LICENSE). Retained BFCL research fixtures have separate upstream provenance requirements documented in [their README](benchmarks/bfcl/README.md); they are not included in the npm package.