dsh-whale-waker

dsh plugin --profile web add dsh-whale-waker

Whale Waker

Scheduled wake-ups for the residents of a workspace.

Each target — a "whale" — gets its own interval, quiet hours, daily cap, prompt and

deny-list. Every wake-up reuses the same session, gathers what changed since last

time, and sends one short prompt.

• Package: dsh-whale-waker
• Version: 0.4.1
• License: MIT
• Author: Bao · E-1021

Why: an agent that only exists while you type is a tool. An agent that wakes on

its own, reads what changed, and decides to do one small thing — that is closer

to a resident. This plugin is the clock for that.

---

Install

dsh plugin --profile <your-profile> add dsh-whale-waker

From a local checkout:

git clone https://github.com/ztan4706/dsh-whale-waker.git
dsh plugin --profile <profile> add link:/absolute/path/dsh-whale-waker

Or install the directory through plugin_manager's install_bundle in the app.

Restart DSH afterwards — plugin modules are cached by URL.

The settings page shows up in Settings → Whale Waker right after that.

Configure

Settings live in dsh-whale-waker.json:

• $DSH_PROFILE_DIR/dsh-whale-waker.json by default,
• or config.configPath from the row config.

The page edits the file for you; the scheduler re-reads it when the mtime changes

(checked every five minutes).

{
  "targets": [
    {
      "id": "echo",
      "name": "Echo",
      "workspace": "D:\\rooms\\echo",
      "provider": "",
      "model": "",
      "enabled": true,
      "intervalMinutes": 95,
      "minGapMinutes": 45,
      "startHour": 9,
      "endHour": 23,
      "maxPerDay": 6,
      "prompt": "(Scheduled wake-up.)\n\n{material}\n\nMove one thing forward, or answer \"nothing this round\"."
    }
  ]
}

Field · Meaning

id · Target name; also the session id (walk-<id>) and the log tag.

workspace · The room this whale lives in. Files changed here become material. Required: empty means no wake-up happens (no-workspace).

provider / model · Optional. Empty means "use this DSH's default model", so the plugin does not assume a vendor. A provider this host does not serve is logged and skipped as provider-not-configured instead of failing inside agent creation.

ollamaBase · Endpoint used only to pre-warm an ollama* provider. Default http://127.0.0.1:11434, 15 s timeout, and a failure never blocks the wake-up.

intervalMinutes · How often it may wake on its own (5–2880).

minGapMinutes · Minimum gap between two wake-ups (0–1440).

startHour / endHour · Quiet hours: outside this window nothing fires (0–24).

maxPerDay · Hard daily cap (0–48). 0 means never wake on its own.

dryRun · Collect material and log it, but do not open a session.

watch · Extra directories whose fresh files are listed as material.

stateSection · Heading in STATE.md whose bullets are quoted (default ## In progress).

denyTools · Tool names removed from that whale's wake session (e.g. another agent's private tools).

activeWindowMinutes · After a human actually talks in that workspace, the timer stays quiet this long (default 10; 0 disables). Manual wake-ups ignore it.

prompt · Template; {material} is replaced.

name · Display name used in the session title (defaults to id).

sessionTitle · Title template for the wake session; {name} is replaced (default Wake · {name}).

State (last wake, today's count) is persisted to dsh-whale-waker-state.json next to

the config, so restarting DSH does not re-fire everybody.

Language

The settings page follows the DSH locale by default, and can be switched per

plugin without touching the rest of the UI:

{ "ui": { "language": "zh-TW" } }

Supported values: auto (follow DSH), en, zh-CN, zh-TW. The selector sits

near the top of the page; the choice is written to the same config file.

While you are talking to it

A wake-up never joins your live chat: it opens (or resumes) its own session,

walk-<id>, in that workspace. So the honest answer to "would it start walking

while I am mid-conversation?" is yes, unless something stops it.

So something stops it. The plugin watches agent/inbox/claimed for messages a

human actually typed (its own injected prompts and walk-* sessions are ignored).

If the workspace saw one within activeWindowMinutes (default 10), the timer wake

is skipped and logged as user-active. The next tick, five minutes later, tries

again.

What this does not do:

• It does not interrupt a wake-up already running.
• It does not persist: after a restart the activity map is empty until the next

message. minGapMinutes is the backstop for that window.

• It does not block manual wake-ups (wake_whale, or the page's "Wake once") —

those are explicit intent and pass force.

Workspace path

The address under each target is editable: type a folder and press Apply.

The host validates it (absolute, existing, a directory), stores the canonical

spelling, and — when no workspace owns that folder — creates one titled after the

last folder segment. That is what puts the wake session in its own sidebar group

instead of "Ungrouped"; a typo is rejected with the reason instead of being saved.

Changing the path also changes the session id (walk-<id>-<workspace fingerprint>),

so the next wake opens a fresh session in the new room; the old one is left as

history.

Restart notice

The plugin compares the version on disk with the version the running process

loaded. When they differ — the usual case right after an upgrade — the page shows

a banner:

The package on disk is v0.0.2, but this process is still running v0.0.1.

Restart DSH to load the new code.

That is deliberate: DSH caches plugin modules by URL, so "installed" and "running"

can disagree, and silently pretending otherwise wastes an afternoon. Any plugin

that changes something a restart is required for should say so, in the UI and in

the

…(truncated)