Preface¶

During runtime, the DSH plugin continuously generates events such as session completion, agent questions, process anomalies, errors, and version updates. If each plugin handles banners, system notifications, and logs independently, configuration becomes scattered, and derived plugins find it difficult to reuse the same notification capabilities.

dsh-notifacation-frame is a DSH notification framework maintained by gameswu: it centrally manages notification events, allows derived plugins to register their own notification items, and provides configuration cards for each notification item on the settings page.

What Is This¶

This is a DSH notification framework plugin that abstracts “reminding the user when a specific event occurs” into notification items that can be registered, configured, and delivered.

It is suitable for agents or derived plugins that need to uniformly handle session states, tool results, process anomalies, and update events within the DSH web profile.

The license is:

MIT © 2026 gameswu

Core Features¶

Unified Notification Event Management¶

Built-in notification items and those registered by derived plugins use the same registry, the same configuration model, and the same delivery pipeline.

Settings Page Configuration Cards¶

The Settings → Notifications page provides a card for each notification item, including:

• Enable toggle
• Channel selection
• Sound effect selection
• Derived plugin configuration fields
• Test button
• Recent notification history

Custom Sound Effects¶

Each notification item can choose built-in synthesized sound effects or a custom audio URL. Sounds can be previewed on the card and are played when the notification banner appears.

Derived Plugin Support¶

The key interfaces for derived plugins to integrate with the notification framework are:

inject: ['notificationFrame']

And:

ctx.notificationFrame.register(definition)

Configuration fields declared in definition.fields are parsed, validated, and filled with defaults by the framework before being passed via env.config. The framework automatically re-activates when configuration changes.

In-Page Toasts, System Notifications, and Logs¶

Supports:

• Browser DSH Toast banners
• System notifications (best effort)
• Optional notification logs

System notifications are best effort on Windows / Linux / macOS, with rate limiting to prevent spam.

Built-in Notification Items¶

Built-in notification items include:

• session-complete
• ask-user-question
• process-crash
• agent-error
• agent-loop-config-start-failed
• tool-error
• dsh-update

Among these, tool-error is disabled by default because tool failures are typically self-healed by the model; it can be enabled as needed. agent/request-error is not integrated due to excessive noise.

Installation and Enablement¶

The web profile is used as an example below.

1. Build the plugin module:

cd dsh-notifacation-frame
pnpm install
pnpm run build

The build produces the plugin entry point lib/index.js and the browser bundle lib/client.js.

2. Install to the web profile:

dsh plugin --profile web add "file:$(pwd)"

3. Restart DSH for the plugin to take effect.

After installation, if you need to override framework-level configuration, you can restate the line by id in the profile’s cordis.patch.yml. cordis.patch.yml is an override layer, not a mount point; only restate the line when overriding framework-level configuration (such as logFile). For example, to override only logFile:

- id: notifacation-frame
  config:
    logFile: /path/to/notifications.log

To uninstall the plugin from the web profile:

dsh plugin --profile web remove dsh-notifacation-frame

Typical Usage¶

The minimal path for a derived plugin to integrate with the notification framework consists of three steps:

1. Declare the injection of notificationFrame;
2. Define the notification item definition and declare configuration fields using fields;
3. Subscribe to events in setup(env) and call env.notify({ title, body }) to send notifications.

Example skeleton:

export const inject = ['notificationFrame']

const myItem = {
  id: 'my-event',
  title: 'My event',
  description: 'Notify when a specific event happens.',
  severity: 'info',
  channels: ['web'],
  defaultChannels: ['web'],
  fields: [
    { key: 'minValue', label: 'Minimum value', type: 'number', default: 10 }
  ],
  setup(env) {
    // env.config already contains field values after parsing, validation, and default filling.
    return env.ctx.on('some/event', (payload) => {
      env.notify({
        title: 'Something happened',
        body: `value=${payload.v}`
      })
    })
  }
}

export function apply(ctx) {
  ctx.effect(() => ctx.notificationFrame.register(myItem))
}

After the user modifies the fields configuration on the card, the framework re-runs setup with the new configuration for hot application.

Suitable Scenarios and Notes¶

Suitable for:

• Uniformly handling notifications such as session completion, agent questions, process crashes, agent errors, agent loop configuration startup failures, tool errors, and dsh-update within the DSH web profile.
• Derived plugins that need to register their own notification items and reuse the settings page cards, channel selection, and sound effect capabilities.
• Lightweight notification needs requiring browser banners, system notifications (best effort), and optional logs.

Notes:

• The plugin runs with the current dsh process permissions; check the source code and license before installation.
• System notifications are best effort on Windows / Linux / macOS, with rate limiting to prevent spam.
• Under autoplay policies, AudioContext may be suspended by the browser and automatically resumes after the first user gesture; playback failures are silent and do not affect notifications.
• After installation or configuration overrides, restart DSH for changes to take effect.

Conclusion¶

The value of dsh-notifacation-frame lies in consolidating scattered notification handling into a unified registration, configuration, and delivery mechanism: built-in events work out of the box, derived plugins can extend at low cost, and the settings page allows unified adjustment of toggles, channels, sound effects, and fields.

GitHub link:

https://github.com/gameswu/dsh-notifacation-frame

The community directory is a separate site and can be searched by the plugin name dsh-notifacation-frame.