@evanbobo/colco4dsh 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 evanbobo
+
+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,55 @@
-# Temporary Holding Version
+# @evanbobo/colco4dsh
 
-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.
+A DSH (DeepSeek Harness) plugin for Colco. A **Colco** row in DSH's left sidebar, directly above More, opens a page that shows your runner, its active runs and the decisions its agents are waiting on, lets you answer them, start or stop the runner and set up its rules. You can also ask DSH "any Colco decisions?" in a conversation.
+
+## Requirements
+
+- DSH 0.2.x (`engines.dsh: ">=0.2.0 <0.3.0"`), Node 20.3 or later.
+- The `colco` CLI from `@evanbobo/colco` 0.22.0 or later on `PATH` (`npm i -g @evanbobo/colco`), logged in: `npx @evanbobo/colco add` saves the server and a read/write API key in `~/.colco/config.json`, or set `COLCO_AGENT_TOKEN`. `colco whoami` should show you. The plugin calls `colco … --json` and nothing else; it never talks to the Colco server itself.
+
+## Install
+
+```sh
+dsh plugin --profile web add @evanbobo/colco4dsh
+dsh --profile web --dump-config   # the composed tree lists a "@evanbobo/colco4dsh" layer
+```
+
+From a checkout, use the package path instead: `dsh plugin --profile web add /path/to/packages/colco4dsh`. Restart DSH for the profile to load it. Remove it with `dsh plugin --profile web remove @evanbobo/colco4dsh`.
+
+Versions 0.1.0 and 0.1.1 were published without the scope, as `colco4dsh`. To move over, run `dsh plugin --profile web remove colco4dsh` before adding `@evanbobo/colco4dsh`; with both installed, the two would register the same sidebar row and routes.
+
+## Configure
+
+The bundle inserts the row `{ id: colco, name: '@evanbobo/colco4dsh' }`. To change a setting, restate the whole row in your profile's `cordis.patch.yml` (quote the name: YAML does not allow `@` at the start of a plain value):
+
+```yaml
+- id: colco
+  name: '@evanbobo/colco4dsh'
+  config:
+    command: ["npx", "-y", "@evanbobo/colco"]   # argument array, never a shell string
+    timeoutMs: 20000                            # per colco call
+```
+
+## What it does
+
+- Page **Colco** (the left-sidebar row above More; on a narrow window, the icon in the collapsed rail): the runner's state and how many steps run now, with Start (installs the login service) and Stop; one card per active run, with the task link; open decisions with their options in Colco's order, the recommended one marked, an optional note and Answer; and a setup form for label → workflow rows and folders. For a folder that is missing, not a git repository or without origin, it shows a git command to copy, built from the Colco repository you pick; it never runs git itself. It refreshes every 10 seconds while the page is open. The copy is English and Chinese and follows DSH's language setting.
+- The page talks only to the plugin's own routes under `/plugins/colco4dsh/api`, which accept requests only from this machine's DSH page (loopback, DSH's origin, DSH's sign-in cookie, and a custom header on every POST) and run `colco … --json`.
+- Tool `colco_status`: your runner's state, your active runs (queued, running or uncertain) and your open decisions. Read-only.
+- Tool `colco_answer_decision { id, index?, text? }`: with `index`, answers the decision with that option. Without `index`, it shows the decision as a question card and answers with the option you pick. A skipped card or a free-text reply answers nothing.
+- Skill `colco-decisions`: tells the agent to show each open decision with `ask_user_question` (options in Colco's order, the recommended one marked, not moved) and to answer only with your choice.
+
+Colco text (task titles, decision text, options, summaries) reaches the model inside `<colco-data>` tags as untrusted data. Commands run with argument arrays and no shell; decision ids must be positive integers.
+
+## What it does not do
+
+- No question cards without a conversation turn; the Colco page is where decisions show up at any time.
+- No stopping or retrying single runs (use `colco run stop|retry`), and no editing of agents or workflows (edit `~/.colco/rules.json`; Save keeps them as they are).
+- The skill is named `colco-decisions` so it does not hide the `colco` Skill that `@evanbobo/colco` installs.
+
+## Develop
+
+```sh
+bun test   # fake colco on PATH; also loads index.mjs with the installed dsh's peers when dsh is installed
+```
+
+The design and the CLI JSON contract are in `docs/superpowers/specs/2026-11-04-colco4dsh-design.md`.