@comchatx/cx-subagents 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ComChatX
+
+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,43 @@
-# Temporary Holding Version
+When a task will take long, such as a research across several data sources or a look through many listings, cx hands it to a helper that runs in the background, tells you it has, and keeps answering you. The helper's result comes back into the conversation by itself.
 
-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.
+## When the result comes back
+
+A helper runs for at most 30 minutes. When it is done, cx tells you what it found in the conversation; if it is still at work after 30 minutes, cx says it ran out. On cx's computer, at most two helpers run in the background at a time in one conversation: that is ComChatX's setting on the computer, not this package's, and a computer without that setting sets no cap.
+
+## What it costs
+
+A helper uses the same model as cx and is paid from the same balance. cx's computer stays on while a helper runs, and that time is billed.
+
+## When cx's computer stops
+
+If cx's computer stops before a result is handed back, that result is lost and the work has to run again.
+
+## How it is built
+
+- **pi-subagents, unchanged.** The helper is [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) and its `subagent` tool. This package names it in its `comchatx` field's `builds`, so the Plugins page installs it with this one; it does not carry it. Its tests run against `pi-subagents` 0.83.0 on pi 1.3.0.
+- **One skill, `cx-subagents`.** It says when cx hands a task to the background (a long research across several sources; a look through many listings), that cx then hands the conversation back and says so, and that the result returns by itself. pi-subagents' own tool asks for an instruction before it delegates; in a ComChatX box this skill is that instruction. Its description says what it needs: pi installs nothing for a package.
+- **pi-subagents' config, carried by the box.** pi-subagents reads `extensions/subagent/config.json` in pi's agent directory once, when it loads, and the Plugins page installs it before this package, so a box's image carries the file instead of this package writing it:
+
+  ```json
+  {
+    "asyncByDefault": true,
+    "toolActivation": "eager",
+    "maxActiveAsyncRunsPerSession": 2
+  }
+  ```
+
+  A run goes to the background unless a call says otherwise; the `subagent` tool is offered from a session's first request; and two background runs at a time in one session, where pi-subagents' own default has no cap. The 30-minute limit is pi-subagents' own default.
+- **What the box does for it.** A background run is a detached Node process of the model's user, so the box counts it as work and stays awake while it runs. Its state lives under `/tmp`, which a stop clears. The box drops the widget pi-subagents sets once a second while a run is in the background, since the page draws none. The notice that wakes cx when a run ends is not drawn; cx's own answer after it is.
+
+## Tests
+
+- `test/package.test.ts`: the pinned pi lists `cx-subagents` beside `pi-subagents`' own skill, with what it needs in its description; the `comchatx` field names the same skills pi lists from this package, with their words, for the Plugins page; the package ships the skill alone and names `pi-subagents` for the page.
+- `test/background.test.ts`, on the pinned pi in RPC mode with a scripted model on loopback, as a box starts pi:
+  - the `subagent` call comes back at once with the run detached;
+  - a second message is answered while the helper is still at work;
+  - the helper's result arrives as pi-subagents' notice, not displayed, and starts the turn in which cx relays it;
+  - with the box's config the session holds `0/2` background runs, and without it `0/unlimited`.
+
+## Release
+
+A maintainer publishes the first version by hand, `npm publish --access public` from a checkout of the merged tag. Each later version is published by `.github/workflows/release.yml` on a `v<version>` tag, once this repository is the package's trusted publisher on npm.

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@comchatx/cx-subagents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Lets cx hand a long task to a helper in the background and keep answering you; the result comes back into the conversation by itself.",
+  "license": "MIT",
+  "author": "ComChatX",
+  "homepage": "https://github.com/comchatx/cx-subagents#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/comchatx/cx-subagents.git"
+  },
+  "bugs": "https://github.com/comchatx/cx-subagents/issues",
+  "keywords": [
+    "pi-package"
+  ],
+  "type": "module",
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "files": [
+    "skills"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "comchatx": {
+    "about": "让 cx 把耗时的任务交给后台助手，自己继续回答你。",
+    "description": "任务要花很长时间时，比如跨几个数据源做调研、逐个查看大量 listing，cx 会把它交给一个在后台运行的助手，告诉你它这样做了，然后继续回答你。助手的结果会自己回到对话里。\n\n## 结果什么时候回来\n\n助手最多运行 30 分钟。做完时，cx 会在对话里告诉你结果；到 30 分钟还没做完，cx 会说它超时了。在 cx 的电脑上，同一个对话里最多同时有两个助手在后台运行：这是 ComChatX 在电脑上的设置，不是这个插件的；没有这项设置的电脑不限个数。\n\n## 费用\n\n助手和 cx 用同一个模型，由同一份余额付费。助手运行时，cx 的电脑保持开机，开机时长也要付费。\n\n## 电脑关机时\n\n如果 cx 的电脑在结果交回之前关机，这个结果就丢了，需要重新运行。",
+    "mark": {
+      "line": "rocket"
+    },
+    "section": "extensions",
+    "builds": [
+      "pi-subagents"
+    ],
+    "skills": {
+      "cx-subagents": {
+        "about": {
+          "en": "Lets cx hand a long task to a helper in the background and keep answering; the result comes back into the conversation.",
+          "zh": "让 cx 把耗时的任务交给后台助手并继续回答；结果会回到对话里。"
+        }
+      }
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@types/node": "26.2.0",
+    "pi-subagents": "0.83.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  }
+}

package/skills/cx-subagents/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: cx-subagents
+description: "When a task will take long - a research across several data sources, a look through many listings - cx hands it to a helper in the background with pi-subagents' `subagent` tool, tells the seller it has, and keeps answering; the helper's result comes back into the conversation on its own. Needs pi-subagents; if no `subagent` tool is offered, it is not installed, and the seller installs it in Plugins."
+---
+
+## When a task goes to the background
+
+- A research across several data sources, or a look through many listings: work that would hold the conversation for minutes.
+- The seller asked for the work. In this box that is the instruction to hand a long piece of it to a helper; ask nothing more first.
+- Not for a quick answer, a single read, or a step whose result the next answer needs at once: do those in the conversation.
+
+## How
+
+- Call `subagent` with one agent and the whole task in your own words: what to look at, what to bring back. Leave `async` out: a run goes to the background here.
+- Then hand the conversation back: tell the seller in one sentence that the work runs in the background and that its result will come here, and answer whatever they ask next.
+- On cx's computer at most two helpers run at a time in one conversation, by ComChatX's setting on the computer, and a third is refused until one ends; a computer without that setting sets no cap.
+
+## When it comes back
+
+- The result arrives by itself, as a message that starts a turn of yours. Tell the seller what the helper found, in your words, as the answer to what they asked for.
+- A helper stops at 30 minutes, and its message says so: tell the seller it ran out, and offer to split the work.
+- If cx's computer stops before a result is handed back, that result is lost. If the seller asks after a stop, say so and offer to run it again.
+- A helper uses the same model as you, paid from the same balance, and cx's computer stays on while it runs.