@maci0/dsh-legion 0.0.0-stage → 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel W. Wysocki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# dsh-legion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Recursive task decomposition for DeepSeek Harness: spydr's workflow on top of
+the harness's native Agent Teams. One root task splits into a tree, leaves run
+as teammates against a shared task board, results consolidate upward, and the
+human gates the root.
+
+## Install
+
+> **Install it as a bundle.** `dsh plugin add …` mounts the row from the
+> package's own patch layer, which is what the settings editor can write to. A
+> row added with `--patch` is an overlay: it disappears at the next start, and
+> the Plugins card cannot save into it (the editor refuses a write an overlay
+> would win).
+
+```sh
+dsh plugin --profile web add github:maci0/dsh-legion#v0.8.2
+```
+
+Pin a release tag: a bare `github:` spec floats on `main`. To upgrade, run the
+same command with the newer tag, then restart `dsh web` (bundle layers compose
+at boot).
+
+The bundled `cordis.patch.yml` inserts the `legion` row automatically.
+
+Requires Agent Teams (`ctx.agentTeams`). When it is not mounted, every verb but
+`config` answers an error naming the bundle to enable and queues nothing, and
+the Legion view says the same. Agent Teams ships as an experimental bundle; enable it in the same
+profile:
+
+```bash
+dsh plugin --profile <name> add @deepseek-ai/dsh-experimental-agent-team-profile
+```
+
+That bundle mounts `agent-team`, `tool-agent-team`, and the Agent Teams Web UI,
+and its own patch disables `tool-subagent`, `tool-subagent-fork`,
+`tool-subagent-list-agents`, and `tool-subagent-control`: the Team tools replace
+direct delegation. Its defaults are `maxMembers: 8` and `maxTasks: 256`. Restart
+the harness after the install.
+
+## Commands
+
+```
+/legion refactor the auth layer   # start a run (attachments allowed)
+/legion start status page redo    # start a task whose title begins with a verb
+/legion status                    # roster + task board
+/legion config                    # effective settings
+/legion stop                      # interrupt every teammate, halt the lead
+/legion approve                   # accept the root deliverable
+/legion approve ship it           # accept, with a note
+/legion reject the API contract   # send it back with a reason
+```
+
+A verb is matched **whole**: `/legion status page redesign` starts a run whose
+title begins with "status". To start a task that *is* one of the verb words,
+prefix it: `/legion start stop`.
+
+## Configure
+
+Two layers, same namespace (`legion`), same precedence as every DSH settings
+section: the patch row is the base, the settings document overrides it.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `minSubtasks` | 2 | Fewer proposals than this ⇒ the task is a leaf |
+| `maxSubtasks` | 4 | Extra proposals are truncated to this |
+| `maxDepth` | 0 | Hard cap on decomposition levels; `0` = no cap |
+| `workersPerTask` | 1 | Independent candidates per leaf |
+| `mergeStrategy` | `best` | `best` \| `reconcile` |
+| `maxReviewRetries` | 2 | Rework attempts before terminal failure |
+| `requireHumanApproval` | `true` | Root waits for `/legion approve` \| `reject` |
+| `maxTasksPerRun` | 0 | Task cap per run; `0` = unlimited |
+
+Edit either way:
+
+- **Config menu**: Plugins → the `legion` row's **Configure** control: every field with its bounds,
+  merge-strategy and approval toggles, overridden-field markers and a one-click
+  Reset, read-only state when the deployment does not persist settings. Its copy ships in
+  English and Chinese through the locale service.
+- **Patch row**: a `- id: legion` row in your profile's `cordis.patch.yml`
+  (or the `config:` block in this package's `cordis.patch.yml`).
+
+Changes validate immediately and apply to the next `/legion` run; `/legion
+config` always prints what the next run will actually use.
+
+## The Legion view
+
+A **Legion** tab sits beside Chat and Trajectory in the session. It draws the
+run's task board as a hierarchy: one round-rect node card per task on a border
+colored by status (completed, in progress, pending), joined by tree rails, each
+carrying the task id, subject, owner, readiness, extra blockers, and write-scope
+overlaps. Branches collapse from their own twisty, a legend names the statuses,
+and the header counts tasks, levels, and members. That is spydr's graph language
+in the harness's own CSS: no canvas, no graph library, no extra dependency. Its copy
+ships in English and Chinese, from the same dictionaries as the card.
+
+The roster ceiling is Agent Teams' `maxMembers`, not this plugin's; raise it in
+the same profile patch (the bundled default is 8, i.e. the lead plus 7
+teammates) so a wide decomposition can keep every ready leaf in flight.
+
+The values come from the session's own `agentTeam` projection, which the
+harness's Agent Teams plugin already publishes, so the tree follows the run
+live (no polling, no RPC, no host-half state) and costs nothing while the tab is
+not selected. Open the lead session of a run; a session with no team shows the
+empty state instead.
+
+## How it works
+
+`/legion <task>` queues a kickoff relay as the agent's next turn. The relay
+carries the decomposition protocol with the current settings inlined:
+
+- split non-atomic tasks into `minSubtasks`-`maxSubtasks` subtasks; fewer than
+  `minSubtasks` means the task is a leaf;
+- never decompose past `maxDepth` (`0` = no cap: split until a task is atomic);
+- `workersPerTask` candidates per leaf, combined by `mergeStrategy`
+  (`best` = judge picks the strongest verbatim, `reconcile` = merge strengths);
+- the authoring agent reviews each child result, up to `maxReviewRetries`
+  rework attempts before a task fails terminally;
+- `requireHumanApproval` holds the root at an `/legion approve | reject` gate;
+- `maxTasksPerRun` caps how many tasks one run may create (`0` = unlimited).
+
+The tree lives on the shared team task board (`team_task_create` with
+`blocked_by` edges), so flow guarantees are structural: tasks flow top-down
+only, results bottom-up only, and siblings never exchange work, the same
+guarantees spydr enforces in its data model. `status`, `stop`, and the
+approval verbs read and steer that live team state; nothing is kept in
+process memory, so a restart cannot strand a run.
+
+## Limits
+
+- Attachments ride the kickoff only; any other verb with attachments is
+  rejected so the composer keeps the originals.
+- `/legion stop` is lead-only, like every roster mutation in the Team domain.
+  Its reply counts the teammates that had a running turn; idle ones are
+  reported separately.
+- `/legion approve` and `/legion reject` go to the Team Lead from any session
+  of the team, and are refused from a session outside one.
+- Settings are read when a verb runs, not when the plugin loads: no restart,
+  no card reload needed.
+
+## Development
+
+`bun test`: pure-logic tests (`parseLegion`, `clampSettings`, `buildKickoff`,
+`formatStatus`, `formatConfig`, `relayText`), the view's tree fold
+(`buildTaskTree`, loaded from the browser half with a stubbed module loader),
+handler tests over a fake host context, and a real Cordis composition. `bun install --frozen-lockfile` first: the handler
+and composition tests load the real module and need the dev dependencies.
+
+dsh loads plugins on Node `^22.19.0 || >=24.0.0`; development and tests run on bun.
+
+For local development, `dsh plugin --profile <name> add <path-to-checkout>`.
+
+## Licence
+
+MIT. See `LICENSE`.

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# The dsh-legion bundle patch: applied automatically when a profile lists
+# this bundle (`dsh plugin add`/`update` appends the package to
+# dsh.profile.bundles). Users override this row from their profile's own
+# cordis.patch.yml (live-watched; dsh.profile.bundles is frozen at boot) with a
+# `- id: legion` row, which replaces the row's whole `config`.
+# `name` stays a bare package specifier: the browser half is served by the
+# client module system, which resolves the Loader entry's package, reads its
+# `dsh.client` manifest, and serves `exports["./client"]`.
+# Do not also insert this same row into the profile patch: insert does not
+# dedupe ids, and a second row would register the plugin twice.
+- insert:
+    - id: legion
+      name: '@maci0/dsh-legion'
+      config:
+        minSubtasks: 2
+        maxSubtasks: 4
+        maxDepth: 0
+        workersPerTask: 1
+        mergeStrategy: best
+        maxReviewRetries: 2
+        requireHumanApproval: true
+        maxTasksPerRun: 0

package/icon.svg

@@ -0,0 +1,7 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect x="6" y="7" width="7" height="7" rx="1.5" fill="#45D9E7"/>
+  <rect x="14.5" y="7" width="7" height="7" rx="1.5" fill="#7CB7FF"/>
+  <rect x="23" y="7" width="7" height="7" rx="1.5" fill="#145AF3"/>
+  <path d="M9.5 14v3.2h17V14" stroke="#145AF3" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+  <rect x="7" y="20.5" width="22" height="8" rx="1.5" fill="#E8F4FF" stroke="#145AF3" stroke-width="1.6"/>
+</svg>

package/index.js

@@ -0,0 +1,245 @@
+/**
+ * dsh-legion: spydr-style recursive task decomposition for DeepSeek Harness.
+ *
+ * One `/legion` command with a verb grammar, backed by the harness's native
+ * Agent Teams instead of a private scheduler:
+ *
+ *   /legion <task>              queue the decomposition protocol (start)
+ *   /legion status              roster + shared task board
+ *   /legion config              effective settings
+ *   /legion stop                interrupt every teammate, tell the lead to halt
+ *   /legion approve [note]      answer the human root-approval gate
+ *   /legion reject <reason>     reject the root deliverable with a reason
+ *
+ * Configuration lives in the `legion` settings namespace (patch row or the
+ * Plugins-page card). It rides into the run inside the kickoff relay,
+ * so a change applies to the next run with no reload and costs no prompt
+ * on turns where no run is active.
+ *
+ * For local development, `dsh plugin --profile <name> add <path-to-checkout>`.
+ */
+import z from '@deepseek-ai/schemastery'
+import { createUserMessage } from '@deepseek-ai/dsh-llm/message'
+import {
+  USAGE,
+  buildKickoff,
+  clampSettings,
+  formatConfig,
+  formatStatus,
+  parseLegion,
+  relayText,
+  DEFAULTS,
+} from './lib/logic.js'
+
+export const name = 'legion'
+
+// `commands` registers the verb grammar; `agentTeams` is an optional service
+// reached through ctx.get, so a team-less composition still mounts the
+// command and degrades per verb.
+export const inject = ['commands']
+
+/**
+ * Row schema; the Plugins-page card edits this shape. `.volatile()` lets a
+ * profile edit land without remounting the plugin.
+ */
+export const Config = z.object({
+  minSubtasks: z.number().step(1).min(1).max(20).default(DEFAULTS.minSubtasks).volatile(),
+  maxSubtasks: z.number().step(1).min(1).max(20).default(DEFAULTS.maxSubtasks).volatile(),
+  maxDepth: z.number().step(1).min(0).max(20).default(DEFAULTS.maxDepth).volatile(),
+  workersPerTask: z.number().step(1).min(1).max(16).default(DEFAULTS.workersPerTask).volatile(),
+  mergeStrategy: z.union(['best', 'reconcile']).default(DEFAULTS.mergeStrategy).volatile(),
+  maxReviewRetries: z.number().step(1).min(0).max(20).default(DEFAULTS.maxReviewRetries).volatile(),
+  requireHumanApproval: z.boolean().default(DEFAULTS.requireHumanApproval).volatile(),
+  maxTasksPerRun: z.number().step(1).min(0).max(10000).default(DEFAULTS.maxTasksPerRun).volatile(),
+})
+
+/**
+ * Queue one relay message as the agent's next turn.
+ * @param {object} agent - the exact receiving agent.
+ * @param {string} text - the relay body.
+ * @param {readonly object[]} [attachments] - durable blocks carried first.
+ */
+function relay(agent, text, attachments = []) {
+  agent.followup(createUserMessage({
+    content: [...attachments, { type: 'text', text }],
+    source: { kind: 'legion', form: 'relay' },
+  }))
+}
+
+/** Error for a verb that needs Agent Teams when the service is not mounted. */
+const NO_TEAMS = 'Agent Teams is not mounted in this composition; /legion needs it. '
+  + 'Enable the experimental bundle: '
+  + 'dsh plugin --profile <name> add @deepseek-ai/dsh-experimental-agent-team-profile'
+
+/**
+ * Resolve the team service's view for one agent, or the reason there is none.
+ * @param {object|undefined} teams - `ctx.agentTeams`, when mounted.
+ * @param {object} agent - the command's receiving agent.
+ * @returns {{ok: true, members: object[], tasks: object[]} |
+ *           {ok: false, reason: string}}
+ */
+function teamView(teams, agent) {
+  if (teams === undefined) return { ok: false, reason: NO_TEAMS }
+  const membership = teams.tryMembership?.(agent)
+  if (membership === undefined) {
+    return { ok: false, reason: 'This session is not part of a team. Start a run with /legion <task>.' }
+  }
+  return { ok: true, members: teams.listMembers(agent), tasks: teams.listTasks(agent) }
+}
+
+/**
+ * Resolve the Team Lead a root-approval verdict goes to.
+ * @param {object|undefined} teams - `ctx.agentTeams`, when mounted.
+ * @param {object} agent - the command's receiving agent.
+ * @returns {{ok: true, agent: object} | {ok: false, reason: string}}
+ */
+function leadOf(teams, agent) {
+  if (teams === undefined) return { ok: false, reason: NO_TEAMS }
+  const membership = teams.tryMembership?.(agent)
+  if (membership === undefined) {
+    return { ok: false, reason: 'This session is not part of a team. Start a run with /legion <task>.' }
+  }
+  return { ok: true, agent: membership.root }
+}
+
+/** Unwrap a volatile config ref (anything with `get()`) to its current value. */
+function plainConfig(value) {
+  if (value !== null && typeof value === 'object' && typeof value.get === 'function') return value.get()
+  return value
+}
+
+/** Snapshot every row field, unwrapping volatile refs. */
+function liveConfig(config) {
+  const plain = {}
+  for (const [key, value] of Object.entries(config)) plain[key] = plainConfig(value)
+  return plain
+}
+
+/**
+ * Mount the plugin.
+ * @param {object} ctx - the host context.
+ * @param {object} [config] - the validated patch-row configuration.
+ */
+export function apply(ctx, config = {}) {
+  // Volatile fields update this object in place. Read it when the command runs.
+  const source = () => clampSettings(liveConfig(config))
+
+  ctx.effect(() => {
+    const dispose = ctx.commands.register({
+      definitionId: 'dsh-legion:legion',
+      name: 'legion',
+      description: '⚔ Recursive task decomposition: /legion <task> starts a run; status | config | stop | approve [note] | reject <reason>',
+      input: { hint: '<task> | start <task> | status | config | stop | approve [note] | reject <reason>', attachments: true },
+      handler: (invocation) => legionHandler(invocation, ctx, source),
+    })
+    return () => dispose()
+  })
+}
+
+/**
+ * Run one `/legion` invocation.
+ * @param {object} invocation - the command invocation.
+ * @param {object} ctx - the host context.
+ * @param {() => object} source - the settings source reader.
+ * @returns {Promise<{kind: 'success'|'error', text?: string}>} the UI result.
+ */
+function legionHandler(invocation, ctx, source) {
+  const parsed = parseLegion(invocation.rawInput)
+  const agent = invocation.agent
+  const teams = ctx.get?.('agentTeams')
+
+  // Attachments are admitted by the definition; only a starting run can carry
+  // them into the kickoff, so any other verb gives the originals back.
+  if (invocation.attachments?.length > 0 && parsed.kind !== 'start') {
+    return Promise.resolve({
+      kind: 'error',
+      text: 'Attachments only accompany a starting run (/legion <task>). Send the verb without them.',
+    })
+  }
+
+  switch (parsed.kind) {
+    case 'usage':
+      return Promise.resolve({ kind: 'error', text: USAGE })
+
+    case 'error':
+      return Promise.resolve({ kind: 'error', text: parsed.text })
+
+    case 'start': {
+      // The run lives on the team board; without it the kickoff would name
+      // tools the model does not have.
+      if (teams === undefined) return Promise.resolve({ kind: 'error', text: NO_TEAMS })
+      relay(agent, buildKickoff(parsed.task, source()), invocation.attachments ?? [])
+      const c = clampSettings(source())
+      return Promise.resolve({
+        kind: 'success',
+        text: `Legion run started: "${parsed.task}". Settings: ${c.maxDepth === 0 ? 'no depth cap' : `up to ${c.maxDepth} level(s) deep`}, `
+          + `${c.minSubtasks}-${c.maxSubtasks} subtasks per split, ${c.workersPerTask} worker(s) per leaf, `
+          + `human root approval ${c.requireHumanApproval ? 'required' : 'off'}. Track it with /legion status.`,
+      })
+    }
+
+    case 'status': {
+      const view = teamView(teams, agent)
+      if (!view.ok) return Promise.resolve({ kind: 'error', text: view.reason })
+      return Promise.resolve({ kind: 'success', text: formatStatus(view) })
+    }
+
+    case 'config':
+      return Promise.resolve({ kind: 'success', text: formatConfig(source()) })
+
+    case 'stop': {
+      const view = teamView(teams, agent)
+      if (!view.ok) return Promise.resolve({ kind: 'error', text: view.reason })
+      const membership = teams.tryMembership(agent)
+      if (membership.role !== 'lead') {
+        return Promise.resolve({ kind: 'error', text: 'Only the Team Lead can stop a legion run.' })
+      }
+      let interrupted = 0
+      let idle = 0
+      for (const member of view.members) {
+        if (member.role === 'teammate') {
+          try {
+            // `previousStatus` is sampled before the cancel: an inactive
+            // teammate had no turn to stop.
+            if (teams.interrupt(agent, member.name).previousStatus === 'running') interrupted += 1
+            else idle += 1
+          } catch {
+            // A teammate that settled between the roster read and the interrupt
+            // needs no report: the run is being stopped either way.
+          }
+        }
+      }
+      relay(agent, relayText('stop'))
+      return Promise.resolve({
+        kind: 'success',
+        text: `Stopped ${interrupted} running teammate(s)${idle > 0 ? `, ${idle} already idle` : ''}; `
+          + 'the lead was told to halt and summarize.',
+      })
+    }
+
+    case 'approve': {
+      const lead = leadOf(teams, agent)
+      if (!lead.ok) return Promise.resolve({ kind: 'error', text: lead.reason })
+      relay(lead.agent, relayText('approve', parsed.note))
+      return Promise.resolve({
+        kind: 'success',
+        text: parsed.note
+          ? `Approval relayed to the lead with your note: "${parsed.note}".`
+          : 'Approval relayed to the lead; the run closes.',
+      })
+    }
+
+    case 'reject': {
+      const lead = leadOf(teams, agent)
+      if (!lead.ok) return Promise.resolve({ kind: 'error', text: lead.reason })
+      relay(lead.agent, relayText('reject', parsed.reason))
+      return Promise.resolve({
+        kind: 'success',
+        text: `Rejection relayed to the lead: "${parsed.reason}". The deliverable goes back for rework.`,
+      })
+    }
+
+    default:
+      return Promise.resolve({ kind: 'error', text: USAGE })
+  }
+}