ishuowang/dsh-rolehub-bridge

RoleHub Bridge for DSH

Choose a portable agent role. Verify its bundle. Start it as a native, continuable DSH Session.

The current conversation stays itself. Agent Team Room stays a Room.

简体中文 · Install · Native UI · Commands · Trust model · Security

RoleHub Bridge is the native DeepSeek Harness compatibility layer for RoleHub. It discovers portable roles from Host-configured Hubs, verifies and pins an exact bundle, computes a Host-owned effective policy, and creates a separate role-scoped child Session.

There are no built-in company teams, personas, or Room scenarios here. A role comes from RoleHub only when a person explicitly selects it. Agent Team Room is an optional destination for the resulting Session—not a dependency and not a source of role authority.

One bridge, narrow responsibilities

The bridge owns	The bridge deliberately does not own
Hub discovery, catalog validation, and bounded downloads	Role authoring or community governance
Exact manifest/archive/bundle digest verification	Trusting a publisher merely because it appears in a catalog
Effective capability policy and fixed Host tool bindings	Self-granted tools, secrets, shell, network, or Room authority
A new continuable, role-scoped child Session	Mutating the active conversation into a role
Optional attachment through Room's public Host API	Room membership, delivery, tasks, scenarios, or a kanban board
Additive native DSH controls and a read-only snapshot	Replacing DSH Web, patching its DOM, or injecting global CSS

Architecture

flowchart LR
  U[Human in native DSH UI] -->|explicit selection| C[/rolehub Host command]
  U -->|same-origin GET| V[Allowlisted role snapshot]

  subgraph Bridge[RoleHub Bridge]
    C --> R[Resolver + private cache]
    H[HTTPS Hub catalog] --> R
    R --> D[Digest-locked deployment]
    D --> P[Effective Host policy]
    P --> A[DSHarness compatibility setup]
  end

  A --> S[Continuable child Session]
  S -. optional attach .-> M[Agent Team Room]
  X[Cold resume] -->|provider name contains bundle digest| D
  D -->|revalidate receipt + bindings| X

The executable capability set is intentionally narrower than a role request:

required role requests ∩ bridge support ∩ Host allowlist

Optional capabilities are never granted automatically. A missing required capability fails closed.

Native DSH UI

The package adds RoleHub actions to the official conversation.session.header.actions and sidebar.footer.action slots. Both open the same native Modal, where you can search Hubs, tags, descriptions, and capabilities; inspect the bundle digest and effective capability groups; then create a role Session. With Room v0.6 or newer installed, the bridge registers the same verified picker in Room's distinct header and footer provider seats, with the current Room preselected. The original header-seat key remains registered so existing provider integrations keep working.

The UI's first open performs only a same-origin GET. Refresh explicitly runs /rolehub refresh; starting a role explicitly runs /rolehub start. The browser snapshot exposes Hub ids, public role metadata, digests, capability labels, and bounded Room summaries. It omits catalog/archive URLs, local paths, stored policy receipts, provider bindings, transcripts, and private Room data.

There is no standalone RoleHub dashboard. The conversation, sidebar, composer, and Room member management remain owned by DSH and Room.

Install

Requirements: Node.js ^22.19.0 || >=24 and DeepSeek Harness 0.1.0-rc.6.

dsh plugin --profile web add github:ishuowang/dsh-rolehub-bridge#v0.2.0
dsh web

The pinned GitHub install is the supported path for v0.2. The bundle adds the Host runtime, /rolehub command, read-only native API, and Web client to the same profile. The package is not yet published to npm.

To attach created role Sessions to a Room, install Room in the same profile:

dsh plugin --profile web add github:ishuowang/dsh-agent-team-room#v0.6.0

Without Room, everything except attachment still works: the role starts as an ordinary independent child Session.

First role

Refresh the configured Hubs, inspect one role, and start it:

/rolehub refresh
/rolehub inspect official/software-engineer
/rolehub start official/software-engineer --label "Software engineer" --prompt "Review the current implementation."

Attach the new Session to a Room at creation time only when Room is available:

/rolehub start official/software-engineer --room <room-id> --label "Implementation reviewer"

The initial prompt is delivered only to the child Session. It is not replayed into the parent command history or copied into Room storage.

/rolehub command

/rolehub hubs
/rolehub list
/rolehub refresh
/rolehub inspect <hub>/<role-name>
/rolehub start <hub>/<role-name> [--label "..."] [--room <id>] [--prompt "..."]
/rolehub sessions

Action	Result
hubs	List Host-configured Hub ids and catalog locations on the Host command plane.
list	List roles from the last validated catalog snapshots.
refresh	Fetch and validate configured catalogs, with a bounded-age cache fallback for already installed roles and inspection.
inspect	Show one role's identity, trust label, digests, and capability requests.
start	Verify/install the role, create a continuable child Session, and optionally attach it to Room.
sessions	List the current parent Session's durable role bindings.

Mutations are available only through this Agent-scoped Host command. There is intentionally no model-facing “install role” or “start role” tool.

Configuration

Edit the inserted rolehub-bridge row in the active profile's cordis.patch.yml when defaults are not enough:

- id: rolehub-bridge
  name: dsh-rolehub-bridge
  config:
    storageDir: /srv/dsh/rolehub-bridge
    allowCommunityRoles: false
    allowedCapabilities:
      - filesystem.read
      - filesystem.write
      - network.fetch
      - web.search
      - source-control.read
      - room.message
    fetchTimeoutMs: 15000
    maxCatalogCacheAgeMs: 86400000
    maxCatalogBytes: 2000000
    maxArchiveBytes: 20000000
    agentProvider: ""
    agentModel: ""
    hubs:
      - id: official
        catalogUrl: https://raw.githubusercontent.com/ishuowang/agent-role-hub/main/catalog/index.json
        archiveUrlTemplate: https://github.com/ishuowang/agent-role-hub/releases/download/v{version}/{name}-{version}.role.tgz
        trustedPublishers:
          - io.github.ishuowang
        allowedRedirectHosts:
          - release-assets.githubusercontent.com
          - objects.githubusercontent.com

All Hub endpoints must be credential-free HTTPS. Publisher trust is scoped to one Hub; a publisher name trusted for official is not trusted when another Hub merely claims the same name. Redirects stay on the request host unless their exact hostname appears in that Hub's allowedRedirectHosts. Validated catalog cache fallback expires after maxCatalogCacheAgeMs (24 hours by default), and a cached/offline catalog can never authorize a first-time role installation.

storageDir defaults to $DSH_HOME/rolehub-bridge, or ~/.dsh/rolehub-bridge when DSH_HOME is unset. The bridge claims only a dedicated private store marked as its own, uses 0600 files, bounded downloads, safe archive extraction, and atomic receipt writes. It refuses dangerous or non-private pre-existing roots instead of changing their permissions. Treat the store as single-Host state and do not edit receipts by hand.

agentProvider and agentModel optionally override the route for newly created role Sessions; leaving both empty follows normal DSH routing.

Trust and capability boundary

A catalog label is discovery metadata, not a cryptographic signature. Before activation, the bridge checks the complete catalog identity against the loaded manifest, records the downloaded archive hash, and verifies the manifest, bundle lock, and final RoleHub bundle digest. Reference publishers must be explicitly trusted by that exact Hub configuration; community roles require allowCommunityRoles: true.

A role can request capabilities but cannot grant them. v0.2 grants required requests only when every item is both in allowedCapabilities and implemented by the bridge's fixed DSH binding. Denied capabilities remain denied, optional requests remain ungranted, and unsupported required access aborts creation. The resulting policy receipt is digest-bound to the role bundle and rechecked before every activation.

These controls are DSH tool-policy boundaries inside a shared Host process. They are not an OS sandbox, container, egress firewall, secret broker, or interactive approval system. Install the bridge and its compatibility packages as trusted Host code.

Cold resume

Each created Session records a provider name derived from the exact bundle digest. On a fresh Host process, the bridge reloads verified deployments and prompt-free Session bindings, checks the deployment, manifest, bundle, policy receipt, and fixed bindings again, then applies the DSH role setup before the child is published. A missing or mismatched deployment fails closed instead of silently loading the newest role with the same name.

Persistence contains catalog snapshots, verified role files, deployment/policy receipts, and Session-to-digest bindings. It does not persist Session transcripts, Room messages, secrets, or the user's initial prompt as bridge metadata.

Optional Room integration

Room is role-neutral. It does not discover RoleHub, load prompts or skills, or interpret capability policy. The bridge first verifies and starts a separate Session, then asks Room to attach that Session with non-authorizing RoleHub provenance (id, version, and bundle digest). Detaching or closing a Room never deletes the backing DSH Session.

If final attachment or receipt persistence fails after Session creation, the bridge attempts to remove the Room member, interrupts the child, and records an orphaned binding for diagnosis. It never pretends the whole operation was atomic.

v0.2 limits

• DeepSeek Harness support is a developer-preview integration pinned to 0.1.0-rc.6; revalidate before upgrading DSH.
• Digest verification provides integrity, not publisher identity. Signatures, transparency logs, revocation, and interactive trust prompts are not implemented.
• Optional capability approval is not implemented, so optional requests are not granted.
• Role-declared turn/output/time limits and model preferences are not yet mapped to DSH runtime controls; Host/session limits remain authoritative.
• Enforcement is in-process DSH tool policy with isolated role configuration—not a dedicated process or OS sandbox.
• The native endpoint's same-origin check is not authentication. Put DSH behind authenticated TLS before remote exposure.
• Catalog refresh may fall back to a recent validated cache, but first-time role installation always requires a live Hub and archive download; creating a Session may consume model quota.
• Room attachment is best-effort compensation across two plugins, not a distributed transaction.

Read SECURITY.md before enabling community roles or exposing DSH Web remotely.

Develop

npm ci
npm run check
npm pack --dry-run
git diff --check

Release artifacts in lib/ are committed so GitHub installs do not need to run a dependency prepare script. Development branches use the feature/ prefix; repository-specific invariants live in AGENTS.md.

License

MIT © 2026 ishuowang · Support on 爱发电