@realqiyan/agent-task 0.1.0-rc.4 → 0.1.0-rc.5

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "agent-task",
+  "interface": {
+    "displayName": "Agent Task"
+  },
+  "plugins": [
+    {
+      "name": "agent-task",
+      "source": {
+        "source": "local",
+        "path": "./hosts/agent-task"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_USE"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "agent-task",
+  "metadata": {
+    "description": "Agent Task installation, usage guidance and native MCP connection"
+  },
+  "owner": {
+    "name": "realqiyan"
+  },
+  "plugins": [
+    {
+      "name": "agent-task",
+      "source": "./hosts/agent-task",
+      "description": "Using Agent Task: installation, setup and existing MCP tools"
+    }
+  ]
+}

package/README.md

@@ -9,6 +9,7 @@
 | 目的 | 入口 |
 | --- | --- |
 | 安装、配置、运行 | [部署说明](docs/deployment.md) |
+| Pi、Claude Code、Codex 接入包与 using-agent-task 使用引导 | [宿主接入](docs/host-integrations.md) |
 | 本机控制台、配置保存与 Web/CLI 重启 | [控制台说明](docs/web-console.md) |
 | 命令行配置、凭据和任务管理 | [CLI 说明](docs/cli.md) |
 | 理解产品目标和架构选择 | [总体方案](docs/design-proposal.md) |
@@ -34,7 +35,7 @@ agent-task status
 agent-task restart
 ```
 
-setup 确认本机配置；MCP 连接自动启动或复用独立后台，宿主退出后后台继续运行。首次使用须安装至少一种原生执行 CLI 并准备其认证。完整接入配置、执行端准备与服务管理见[部署说明](docs/deployment.md)。
+setup 确认本机配置；MCP 连接自动启动或复用独立后台，宿主退出后后台继续运行。首次使用须安装至少一种原生执行 CLI 并准备其认证。Pi、Claude Code 和 Codex 可先安装[接入包](docs/host-integrations.md)，再通过 `using-agent-task` 引导安装服务、完成 setup 和使用现有 MCP 工具。执行端准备与服务管理见[部署说明](docs/deployment.md)。
 
 任务由 `task_create` 提交固定 DAG，每个节点选择已就绪执行端。显式工作目录优先，否则 stdio 入口补入自己的启动目录；直接 HTTP 调用必须提供目录。具体契约见 [task-contract.ts](src/protocol/task-contract.ts)，管理工具见 [mcp.ts](src/protocol/mcp.ts)。Prompt、人工回复和工作空间选择都不授予工具权限。
 

package/bin/agent-task.mjs

@@ -55,6 +55,9 @@ try {
     }
   }
 } catch (error) {
-  console.error(process.argv.includes("--json") ? JSON.stringify({ error: error.message }) : error.message);
+  const message = process.argv[2] === "mcp"
+    ? error.message + "\nFor installation, setup or connection troubleshooting, use using-agent-task: Pi /skill:using-agent-task; Claude Code /agent-task:using-agent-task; Codex $using-agent-task. Do not reinstall or replay work without checking the cause."
+    : error.message;
+  console.error(process.argv.includes("--json") ? JSON.stringify({ error: message }) : message);
   process.exitCode = 1;
 }

package/docs/deployment.md

@@ -27,6 +27,8 @@ agent-task setup --home /absolute/private/agent-task \
 
 ## MCP 接入与工作目录
 
+Pi、Claude Code 和 Codex 可使用[可安装接入包](host-integrations.md)先安装使用引导，再经确认安装服务、完成 setup 和宿主配置。以下是其他宿主或手工配置的通用入口。
+
 在宿主的 MCP 配置中添加命令，例如采用 `mcpServers` 格式的宿主：
 
 ```json
@@ -86,6 +88,8 @@ Web 访问 `status` 返回地址同源的 `/admin/`，连接与令牌保护见[
 
 修改数据目录后，下次启动只准备目标配置和私有环境，并切换定位文件；不复制任务、会话、结果或日志，不删除旧目录。目标已有不同启动文件时拒绝覆盖，须停服核对并显式准备目标。新目录没有旧任务，目录切换不是恢复或重放许可。
 
+`agent-task setup --check --json`（自定义安装附加相同 `--home`）只读检查初始化状态，不启动后台、不写锁或修复文件。它不验证模型登录、执行端授权或实时 MCP 健康；摘要契约见 [setup](../scripts/setup.mjs)。
+
 重复 setup 保留已有配置。初始化中断后须显式执行 `setup --resume`，它只接续已保存且一致的初始化文件；缺少凭据或所有权不明时停止核查，不猜测修复。更新前停止后台并备份安装目录和数据目录。调研阶段不保证旧配置或数据兼容，普通启动不迁移历史。
 
 源码开发者执行 `npm ci --ignore-scripts && npm run build` 后，可用 `node bin/agent-task.mjs setup`、`node bin/agent-task.mjs mcp` 或 `npm start -- --home ...`。内部 `dist/application/main.js` 不是独立的重启入口。

package/docs/host-integrations.md

@@ -0,0 +1,117 @@
+# Pi、Claude Code 与 Codex 接入包
+
+**先安装接入包，再由 `using-agent-task` 引导安装、初始化和使用服务。** 插件名仍为 `agent-task`。skill 只指导使用现有 CLI/MCP，不增加任务 API、执行器或业务规则。
+
+入口：[共享包](../hosts/agent-task/)、[使用引导](../hosts/agent-task/skills/using-agent-task/SKILL.md)、[Claude marketplace](../.claude-plugin/marketplace.json)、[Codex marketplace](../.agents/plugins/marketplace.json)。
+
+Agent Task 支持 Linux/macOS、Node.js 22.19+ 与 npm。Pi 需要 1.4.0+ 的原生 MCP；Claude Code 需要插件支持；Codex CLI 需要 `plugin marketplace add` 和 `plugin add`。不承诺 Codex IDE、云端或其他同名插件系统可用。核验版本与限制见[验证说明](validation.md#宿主接入包)。
+
+## 不预装服务的本地入口
+
+当前源码可直接安装接入包，**不需要先执行服务的 `npm ci`、build、link 或 setup**。在包含本次接入资产的仓库根目录设置：
+
+```bash
+AGENT_TASK_SOURCE="$(pwd -P)"
+```
+
+然后只执行对应宿主的安装命令。保留被引用的本地目录；接入包与服务安装目录是两个概念。
+
+### Pi
+
+```bash
+pi install "$AGENT_TASK_SOURCE/hosts/agent-task"
+```
+
+启动 Pi（已有会话先 `/reload`），调用 `/skill:using-agent-task`。Pi package 安装 skill 和只读启动检查扩展，首次引导会在 setup 完成并取得确认后，执行原生 `pi mcp add` 注册连接。已有同名连接时先核对，不盲目替换。需要项目作用域时，分别为 package 安装和 MCP 注册选择 `--local` 并审查项目信任设置。
+
+### Claude Code
+
+```bash
+claude plugin marketplace add "$AGENT_TASK_SOURCE"
+claude plugin install agent-task@agent-task --scope user
+```
+
+在新会话调用 `/agent-task:using-agent-task`。插件已声明 `agent-task mcp`，不要重复执行 `claude mcp add`。服务未安装或 setup 未完成时，MCP 连接失败是预期行为，不妨碍使用引导。初始化后重开会话或在 `/mcp` 重连。
+
+### Codex CLI
+
+```bash
+codex plugin marketplace add "$AGENT_TASK_SOURCE"
+codex plugin add agent-task@agent-task
+```
+
+在新会话调用 `$using-agent-task`，或在 `/skills` 中选择它。支持原生 onboarding 的界面也指向同一 skill。插件已声明 `agent-task mcp`，不要重复执行 `codex mcp add`。初始化后开新会话，在 `/mcp` 检查连接；`codex mcp list` 的静态配置输出本身不证明连接成功。
+
+安装接入资产不需要服务凭据；让宿主模型执行 skill 仍需宿主自身的模型认证。
+
+## 分发入口与发布边界
+
+独立轻量 npm 包名为 `@realqiyan/agent-task-hosts`，不依赖服务或 SDK，也没有 npm 安装 hook。**维护者发布该包后**，Pi 可直接使用：
+
+```bash
+pi install npm:@realqiyan/agent-task-hosts
+```
+
+Claude Code/Codex 的 marketplace 文件进入远端后，可将上文 marketplace add 参数替换为 `realqiyan/agent-task`，无需预装服务或克隆源码。
+
+这些入口的源码配置不等于已完成发布；当前改动可使用上述本地入口。独立包的打包、发布要求见[发布说明](release.md#独立接入包)。包含接入资产的服务 npm 发行版仍可提供同一目录，已安装服务的用户可将 `AGENT_TASK_SOURCE` 设为 `$(npm root -g)/@realqiyan/agent-task`；这不是首次接入的前提。
+
+## 启动提醒与检查边界
+
+接入包的检查独立于 MCP 连接：Pi 在会话启动时显示通知并加入简短模型上下文；Claude Code/Codex 的同步 `SessionStart` hook 返回用户可见的 `systemMessage` 和模型上下文。异常提示给出对应的 `using-agent-task` 入口，状态正常时保持安静；不会自动调用模型或执行安装。
+
+检查复用服务的 `agent-task setup --check --json`，不解析私有配置。该服务命令只在自己的进程内校验初始化和凭据文件，返回不含路径、密钥或原始异常的摘要；不创建目录/SQLite 锁、不修复文件、不启动服务、联网或发现执行端。检查有时间与输出限制，失败不会阻塞整个宿主会话。未安装、初始化未完成、配置异常、协调模型未配置和检查本身失败分别提示；无法启动命令也可能是 PATH 或 Node 问题，不等于应当重装。
+
+这是安装状态检查，**不是实时 MCP 健康检查**。后台停止不等于未初始化；端口冲突、执行端准备和连接错误仍需查看宿主 MCP 状态。服务 MCP 启动失败的 stderr 也附带 skill 入口，但 stderr 不保证直接展示给用户。对不支持此只读命令的服务版本只报告检查失败，不回退到可能写锁的旧检查路径。
+
+检查默认使用宿主 PATH 的 `agent-task` 和默认 home。自定义 MCP 命令/home 时，在启动宿主的环境中同步设置以下非敏感变量：
+
+```bash
+export AGENT_TASK_PREFLIGHT_COMMAND=/absolute/bin/agent-task
+export AGENT_TASK_PREFLIGHT_HOME=/absolute/private/agent-task
+```
+
+这些变量**只选择检查目标，不修改 MCP 连接**，也不推断或改写宿主配置。已关闭插件 MCP、改用远程连接或不需要此提示时，可在宿主原生设置中禁用该 hook/扩展，保留 skill。
+
+Codex 插件 hook 必须先在 `/hooks` 中审查并信任；安装插件不自动授权 hook。Claude Code/Pi 也须允许插件 hook/扩展运行。禁用、未信任或 Node 无法启动时，不能保证出现自定义提示，仍可显式调用上述 skill。不要通过绕过信任或扩大权限来消除提示。程序入口见 [preflight](../hosts/agent-task/scripts/preflight.mjs)、[Pi 扩展](../hosts/agent-task/pi-extension.js)、[hook 入口](../hosts/agent-task/scripts/session-start.mjs)。
+
+## 引导如何安装服务
+
+调用 skill 后先检查已有命令、Node/npm、安装目录和连接配置。服务确实缺失时，宿主说明安装影响，取得用户确认，然后通过自身 shell 工具执行：
+
+```bash
+npm install -g @realqiyan/agent-task
+```
+
+这不是安装插件时静默执行，也不是每次连接运行 `npx`。已有安装不自动升级，PATH 问题不重复安装；权限不足时停止并给出用户终端操作，不使用 sudo 或扩大宿主权限。
+
+随后引导用户在自己的终端执行 `agent-task setup`，让凭据通过隐藏输入收集。用户明确选择非交互初始化时，可由宿主执行已确认的参数和私有凭据文件方式，但不将秘密放入会话或命令参数。setup 和执行端准备的服务规则由[部署说明](deployment.md)维护。
+
+## 使用与验收
+
+引导按需读取包内参考文件，复制到插件缓存或独立安装后不依赖仓库文档：
+
+- [安装与连接](../hosts/agent-task/skills/using-agent-task/references/installation.md)：setup、原生 MCP 注册、自定义 home/绝对命令路径和连接验证。
+- [日常使用](../hosts/agent-task/skills/using-agent-task/references/tasks.md)：通过现有 MCP 提交固定 DAG、查看运行与交付、回答事实问题、区分未来触发控制和当前运行取消。
+- [排障](../hosts/agent-task/skills/using-agent-task/references/troubleshooting.md)：区分安装、连接、配置、适配器准备和执行结果不明，不盲目重试。
+
+安装验收只需宿主显示已连接，并成功调用 `executor_list({})`、`task_list({})`。Pi 默认通过原生 codemode/tool search 发现工具；使用实际宿主命名空间。不为验收创建任务或执行付费模型/领域工作。连接成功、执行端 ready、原生授权和真实交付是不同证据。
+
+创建任务建议明确给出目标项目的绝对 `workspace`，不把插件缓存目录当成工作目录。MCP token 不写入插件配置，事实回复不授予权限。自定义 home 时，setup、MCP 和后续 CLI 命令必须使用同一目录；Claude/Codex 先禁用插件自带 MCP 项再添加手工连接，不能同时保留两条有效连接。
+
+## 更新与移除
+
+接入包与服务使用同一项目版本，但分别安装。接入包更新不升级服务、不执行 setup、不迁移数据；更新服务前按[部署说明](deployment.md#数据目录与管理)停服并备份。使用宿主原生 package/marketplace 更新入口刷新接入资产，再重开会话。
+
+- Pi 本地安装：`pi remove "$AGENT_TASK_SOURCE/hosts/agent-task"`；npm 安装：`pi remove npm:@realqiyan/agent-task-hosts`。另用 `pi mcp remove agent-task` 移除引导注册的 MCP 连接。
+- Claude Code：`claude plugin uninstall agent-task@agent-task`。
+- Codex：`codex plugin remove agent-task@agent-task`。
+- 另行添加的手工 MCP 连接需单独移除。
+
+宿主退出或卸载插件不停止已提交任务。`agent-task status` 查看共享后台，`agent-task stop` 显式停止；先核对活动工作，自定义安装附加相同 `--home`。卸载接入包不删除服务、历史、工作空间或原生执行端配置。
+
+## 原生机制依据
+
+- Pi：[packages](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/packages.md)、[MCP](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/mcp.md)。
+- Claude Code：[marketplace](https://code.claude.com/docs/en/plugin-marketplaces)、[插件清单](https://code.claude.com/docs/en/plugins-reference)。
+- Codex：[插件包与 marketplace](https://developers.openai.com/plugins/build/plugins)。使用已核验 CLI 支持的 `.codex-plugin/plugin.json`，不依赖 Claude 清单回退。

package/docs/release.md

@@ -24,6 +24,19 @@ npm run test:install -- "./realqiyan-agent-task-$VERSION.tgz"
 
 npm 接收发布后可能仍在处理包。[发布后验收](../scripts/verify-install.mjs)有限等待公开 `latest` 指向目标版本，再执行默认全局安装；等待只读取 registry。超时先核对版本状态，不重复上传。
 
+## 独立接入包
+
+[轻量包](../hosts/agent-task/package.json)为 `@realqiyan/agent-task-hosts`，使用同一项目版本，不依赖服务或 SDK，不运行安装脚本。它允许先安装 `using-agent-task`，再经用户确认安装服务；不是服务的替代安装。Claude Code/Codex 还可直接使用仓库 marketplace，不依赖此 npm 包。
+
+```bash
+npm run pack:hosts
+# 产物：hosts/realqiyan-agent-task-hosts-<项目版本>.tgz
+```
+
+[独立包门禁](../scripts/pack-hosts.mjs)检查版本、无执行/依赖字段和实际包清单；不需要构建服务。[接入测试](../tests/host-integrations.test.mjs)使用临时目录和空 npm 缓存离线安装真实 tarball。发布前还须通过本文的项目检查，并用对应宿主验收引导发现与连接，不能将 skill 文本当成模型已执行的证据。
+
+当前 GitHub 发布工作流只上传服务包，**不会自动发布独立接入包**。接入包需单独授权发布，先核对同名目标版本未占用及 npm 账号/权限，再发布已检查的 `hosts/realqiyan-agent-task-hosts-<版本>.tgz`，明确使用 `--ignore-scripts --access public --tag latest --registry=https://registry.npmjs.org`。不要为新包擅自复用服务包的 Trusted Publisher 授权或绕过登录/2FA。发布后核查该包的 registry 版本和 latest，并在隔离宿主配置中验证 `pi install npm:@realqiyan/agent-task-hosts`；此前文档中的 npm 入口仅代表预定分发方式。
+
 ## GitHub Actions 门禁与受控发布
 
 - [Validate](../.github/workflows/ci.yml)：PR/master 或手动触发时在 Ubuntu 执行 TypeScript 与依赖边界检查、基础测试及构建；检查包清单。安装任务**不 checkout 项目源码**，只接收 tarball 和验收脚本，在当前 Linux runner 验证启动、重启及认证检查。常规 CI 使用 Linux runner，不能据此推断 macOS 验证结果。
@@ -32,7 +45,7 @@ npm 接收发布后可能仍在处理包。[发布后验收](../scripts/verify-i
 
 ### 通过 tag 发布
 
-1. 核对 npm 中目标版本尚未发布。用 `npm version <新版本> --no-git-tag-version --ignore-scripts` 同步包版本和锁文件；完成上述候选验收后，提交并推送到 master。
+1. 核对 npm 中目标版本尚未发布。用 `npm version <新版本> --no-git-tag-version --ignore-scripts` 同步包版本和锁文件，并将 `hosts/agent-task/package.json`、`hosts/agent-task/.claude-plugin/plugin.json`、`hosts/agent-task/.codex-plugin/plugin.json` 的版本设为同一值；打包门禁拒绝不一致。完成上述候选验收后，提交并推送到 master。
 2. 给已验收的提交打版本 tag，并单独推送该 tag：
 
 ```bash

package/docs/technical-design.md

@@ -24,6 +24,8 @@
 | 装配、启动、关闭与重启 | [main](../src/application/main.ts)、[MCP 后台启动](../src/application/mcp-entry.ts)、[业务运行实例](../src/application/task-runtime.ts)、[launcher](../src/application/launcher.ts)、[启动准备](../src/application/startup.ts) | [stdio.test.mjs](../tests/stdio.test.mjs)、[restart.test.mjs](../tests/restart.test.mjs)、[service.test.mjs](../tests/service.test.mjs) |
 | 安装与发布 | [命令入口](../bin/agent-task.mjs)、[setup](../scripts/setup.mjs)、[安装库](../scripts/install-lib.mjs)、[包门禁](../scripts/pack-release.mjs)、[发布准入](../scripts/check-release.mjs)、[工作流](../.github/workflows/) | [install.test.mjs](../tests/install.test.mjs)、[setup.test.mjs](../tests/setup.test.mjs)、[release.test.mjs](../tests/release.test.mjs)、[发布说明](release.md) |
 
+宿主安装资产位于 [hosts/agent-task](../hosts/agent-task/)，包含原生插件清单、MCP 连接声明、`using-agent-task` 使用引导和只读启动检查，不进入服务运行时依赖图。检查通过 CLI 摘要复用 setup 校验；[检查测试](../tests/host-preflight.test.mjs)验证无写入、故障分类和凭据不回显。[独立包门禁](../scripts/pack-hosts.mjs)不构建或安装服务；[接入测试](../tests/host-integrations.test.mjs)验证无服务依赖的离线安装、清单契约和真实 stdio 工具调用；宿主原生流程见[接入说明](host-integrations.md)。
+
 ## 依赖与一致性边界
 
 依赖方向由[架构原则](architecture-guidelines.md#职责与依赖)定义，[依赖检查器](../scripts/check-boundaries.mjs)随 `npm run check` 执行。模块分类、允许引用及 Run 写入口检查以该脚本为准；新增文件须明确归属。

package/docs/validation.md

@@ -14,6 +14,16 @@ git diff --check
 
 [MCP 服务测试](../tests/service.test.mjs)通过真实 HTTP 和 SDK 校验器检查输入/输出契约、成功与失败响应及列表查询。契约不使用数组形式的 `type`，可空字段仍必填并接受 `null`；实现见 [mcp-contract.ts](../src/protocol/mcp-contract.ts)。这不替代曾报告契约警告的客户端复验，其名称和版本尚未提供。
 
+## 宿主接入包
+
+`0.1.0-rc.4` 基线上的接入资产，Linux x64、Node 24.15.0，在无个人凭据的隔离 HOME/宿主配置中验证：未安装服务时，Pi 1.4.0、Claude Code 2.1.302、Codex CLI 0.164.0 均可安装本地接入包并发现 `using-agent-task`。随后用本地构建服务完成 setup，Pi 工具发现、Claude MCP 健康连接、Codex app-server 连接及 `executor_list`、`task_list` 调用通过。证据：`/tmp/agent-task-native-hosts-TvywpQ/report.json`、同目录 `codex-runtime.json`。这是本地资产验证，不表示已发布到 npm 或远端 marketplace。
+
+同一环境中，Pi RPC 发出缺少命令的通知并保留模型上下文，未触发模型运行（`pi-preflight.jsonl`）；Claude headless 原生 SessionStart 执行并返回用户提示和上下文（`claude-hook.jsonl`，MCP 被显式关闭以验证独立性）。Codex 发现同步 hook 且无清单错误，但标记为未信任；未绕过审查执行。
+
+[接入测试](../tests/host-integrations.test.mjs)从真实 tarball、空 npm 缓存离线安装独立接入包，并通过真实 setup、stdio 与官方 MCP SDK 调用上述只读工具。[启动检查测试](../tests/host-preflight.test.mjs)检查配置缺失/损坏、失败进程、输出限制与取消、无目录/锁写入及私密值不回显；hook 故障输出不阻塞会话，正常状态不输出通知。[独立包门禁](../scripts/pack-hosts.mjs)与[服务包门禁](../scripts/pack-release.mjs)检查实际包包含 hook、扩展、清单和 skill。原生宿主不是基础测试依赖。
+
+未执行独立接入包的 npm registry 安装、三种宿主的模型驱动安装/setup/日常使用会话、Pi/Claude 模型侧工具调用、真实 TUI 告警展示、Codex 用户信任后的 hook 调用、macOS 接入或自定义 home 的宿主 UI 禁用流程。探针不运行模型或 ACP 领域工作；可发现的真实失败程序只提供连接前置条件，不证明执行端能完成任务。操作入口见[宿主接入](host-integrations.md)。
+
 ## 控制台验证
 
 [Web/CLI](../tests/web.test.mjs)、[配置](../tests/settings.test.mjs)和[重启](../tests/restart.test.mjs)测试覆盖真实本机服务的管理互通、旧编辑拒绝、凭据隔离、浏览器请求边界、配置生效与目录切换，以及重启后不确定派发仍被阻断。配置文件测试不构成断电、磁盘满或目录同步失败窗口的完整证据。

package/hosts/agent-task/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "agent-task",
+  "version": "0.1.0-rc.5",
+  "description": "Install, set up and use Agent Task through its existing MCP tools",
+  "author": {
+    "name": "realqiyan"
+  },
+  "license": "MIT",
+  "mcpServers": "./mcp.json",
+  "hooks": "./hooks/claude.json"
+}

package/hosts/agent-task/.codex-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "agent-task",
+  "version": "0.1.0-rc.5",
+  "description": "Install, set up and use Agent Task through its existing MCP tools",
+  "author": {
+    "name": "realqiyan"
+  },
+  "license": "MIT",
+  "skills": "./skills/",
+  "mcpServers": "./mcp.json",
+  "hooks": "./hooks/codex.json",
+  "extensions": {
+    "com.openai": {
+      "onboardingSkill": "./skills/using-agent-task/SKILL.md"
+    }
+  }
+}

package/hosts/agent-task/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 realqiyan
+
+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/hosts/agent-task/README.md

@@ -0,0 +1,54 @@
+# Agent Task host integration
+
+A dependency-free Pi package and Claude Code/Codex plugin. The plugin remains named `agent-task`; its skill is `using-agent-task`. It guides service installation, setup, MCP connection and daily task use. All task operations use the existing Agent Task MCP tools.
+
+## Install before the service
+
+From an Agent Task source checkout, no service build or npm install is needed:
+
+```bash
+pi install /absolute/path/to/agent-task/hosts/agent-task
+# Or, for Claude Code:
+claude plugin marketplace add /absolute/path/to/agent-task
+claude plugin install agent-task@agent-task --scope user
+# Or, for Codex CLI:
+codex plugin marketplace add /absolute/path/to/agent-task
+codex plugin add agent-task@agent-task
+```
+
+Keep a local source directory in place while it is registered. After the marketplace files are published to Git, Claude Code/Codex can use `realqiyan/agent-task` instead of the local repository path.
+
+The standalone npm package is `@realqiyan/agent-task-hosts`. **Only after a maintainer publishes it**, Pi can install it with:
+
+```bash
+pi install npm:@realqiyan/agent-task-hosts
+```
+
+There is no npm install hook or service dependency. This package does not silently run `npm install -g @realqiyan/agent-task`. In a new session, invoke:
+
+- Pi: `/skill:using-agent-task`
+- Claude Code: `/agent-task:using-agent-task`
+- Codex: `$using-agent-task` or select it in `/skills`
+
+The skill checks the installation and, with your confirmation, runs the service's npm install command using the host's shell tool. It then guides `agent-task setup`; credentials stay in your terminal/private files, not chat. Agent Task requires Linux/macOS, Node.js 22.19+ and npm. The host itself needs its own model access to follow the skill.
+
+Pi registers MCP after setup. Claude Code/Codex declare MCP in the plugin; a missing-command/setup error is expected before initialization. Reconnect or start a new session after setup. Do not add a duplicate manual connection.
+
+## Startup reminders
+
+The Pi extension and Claude Code/Codex SessionStart hooks check installation state independently of MCP. When the check finds a problem, they show the skill entry point and supply brief model context. Healthy checks are silent; no model turn, installation, repair or service start is triggered.
+
+The check runs `agent-task setup --check --json` with a time/output limit. It does not interpret private files or forward child-process diagnostics. Unsupported check commands are reported as inconclusive, not treated as proof that installation is missing. This is not a live MCP health check.
+
+For a custom MCP command/home, set `AGENT_TASK_PREFLIGHT_COMMAND` and `AGENT_TASK_PREFLIGHT_HOME` in the environment that launches your host. They select only the check target; configure MCP separately with the same executable/home. Disable this hook/extension in the host if you do not want checks, or use a different connection.
+
+Review and trust Codex's plugin hook in `/hooks` before expecting it to run. Disabled/untrusted hooks or a missing Node runtime cannot show the custom notice. Do not bypass hook trust. The skill remains available independently.
+
+## Guides
+
+- [Install, setup and connect](skills/using-agent-task/references/installation.md)
+- [Submit tasks, inspect delivery and answer questions](skills/using-agent-task/references/tasks.md)
+- [Troubleshoot](skills/using-agent-task/references/troubleshooting.md)
+- [Full host installation and removal guide](https://github.com/realqiyan/agent-task/blob/master/docs/host-integrations.md)
+
+Removing the plugin does not stop the shared service or delete task history. Pi's manually registered MCP entry must be removed separately. No plugin installation or skill grants executor tool permissions.

package/hosts/agent-task/hooks/claude.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs\" claude",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/hosts/agent-task/hooks/codex.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/session-start.mjs\" codex",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/hosts/agent-task/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "agent-task": {
+      "type": "stdio",
+      "command": "agent-task",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}

package/hosts/agent-task/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@realqiyan/agent-task-hosts",
+  "version": "0.1.0-rc.5",
+  "type": "module",
+  "description": "Using Agent Task: installation, setup and existing MCP tools for Pi, Claude Code and Codex",
+  "license": "MIT",
+  "author": "realqiyan",
+  "keywords": [
+    "pi-package",
+    "mcp",
+    "agent-task"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realqiyan/agent-task.git",
+    "directory": "hosts/agent-task"
+  },
+  "files": [
+    ".claude-plugin/plugin.json",
+    ".codex-plugin/plugin.json",
+    "mcp.json",
+    "pi-extension.js",
+    "hooks/",
+    "scripts/",
+    "skills/",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "pi": {
+    "extensions": ["./pi-extension.js"],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/hosts/agent-task/pi-extension.js

@@ -0,0 +1,26 @@
+import { inspectInstallation, onboardingNotice } from "./scripts/preflight.mjs";
+
+export default function (pi) {
+  let active;
+  pi.on("session_start", async (_event, ctx) => {
+    const controller = new AbortController();
+    const pending = inspectInstallation({ cwd: ctx.cwd, signal: controller.signal });
+    active = { controller, pending };
+    const state = await pending;
+    if (controller.signal.aborted) return;
+    const notice = onboardingNotice(state, "pi");
+    if (!notice) return;
+    if (ctx.hasUI) ctx.ui.notify(notice.systemMessage, "warning");
+    pi.sendMessage({
+      customType: "agent-task-onboarding",
+      content: notice.systemMessage + "\n" + notice.hookSpecificOutput.additionalContext,
+      display: !ctx.hasUI,
+      details: { state },
+    }, { triggerTurn: false });
+  });
+  pi.on("session_shutdown", async () => {
+    active?.controller.abort();
+    await active?.pending;
+    active = undefined;
+  });
+}

package/hosts/agent-task/scripts/preflight.mjs

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+
+// No shell, network, MCP connection, config writes or raw diagnostic output.
+// The service CLI owns private installation validation. The plugin sees only its summary.
+export async function inspectInstallation({ env = process.env, cwd = process.cwd(), signal } = {}) {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  if (!["linux", "darwin"].includes(process.platform) || major < 22 || (major === 22 && minor < 19)) return "unsupported-runtime";
+  if (signal?.aborted) return "cancelled";
+  const command = env.AGENT_TASK_PREFLIGHT_COMMAND ?? "agent-task";
+  const home = env.AGENT_TASK_PREFLIGHT_HOME;
+  // The explicit machine-output flag makes older CLIs reject before their setup path.
+  const args = ["setup", "--check", "--json", ...(home === undefined ? [] : ["--home", home])];
+  return new Promise(resolve => {
+    let child;
+    try { child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "ignore"] }); }
+    catch { resolve("check-failed"); return; }
+    let stdout = "", bytes = 0, failure;
+    const stop = state => {
+      failure ??= state;
+      child.kill("SIGKILL");
+      child.stdout.destroy();
+    };
+    const abort = () => stop("cancelled");
+    const timer = setTimeout(() => stop("check-failed"), 3000);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    child.on("error", error => { failure ??= error.code === "ENOENT" ? "command-unavailable" : "check-failed"; });
+    child.stdout.on("data", chunk => {
+      bytes += chunk.length;
+      if (bytes > 4096) stop("check-failed");
+      else stdout += chunk.toString("utf8");
+    });
+    child.on("close", code => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      if (failure) { resolve(failure); return; }
+      try {
+        const report = JSON.parse(stdout);
+        if (code === 0 && report.configuration === "valid" && typeof report.coordinatorConfigured === "boolean") {
+          resolve(report.coordinatorConfigured ? "ready" : "coordinator-missing");
+        } else if (code === 1 && ["missing", "incomplete", "invalid"].includes(report.configuration)) {
+          resolve({ missing: "setup-missing", incomplete: "setup-incomplete", invalid: "setup-invalid" }[report.configuration]);
+        } else resolve("check-failed");
+      } catch { resolve("check-failed"); }
+    });
+  });
+}
+
+const reasons = {
+  "command-unavailable": "The agent-task command could not start. It may be uninstalled, outside this host's PATH, or missing its Node interpreter.",
+  "setup-missing": "Agent Task is installed but setup is missing for the checked home.",
+  "setup-incomplete": "Agent Task initialization is incomplete. Inspect it before explicitly resuming; do not reset or reinstall it.",
+  "setup-invalid": "Agent Task installation or private configuration could not be validated. Check the selected home and existing files; do not automatically reinstall.",
+  "coordinator-missing": "Agent Task has no complete coordinator configuration. MCP inspection may work, but executable tasks need coordinator setup.",
+  "unsupported-runtime": "Agent Task needs Linux/macOS and Node.js 22.19 or later.",
+  "check-failed": "The Agent Task read-only check failed, is unsupported by this service build, or timed out. This does not prove the service is uninstalled. Inspect the command, Node version and selected home.",
+};
+
+export function onboardingNotice(state, host) {
+  const entry = { pi: "/skill:using-agent-task", claude: "/agent-task:using-agent-task", codex: "$using-agent-task" }[host];
+  if (!entry || !reasons[state]) return null;
+  const message = reasons[state] + " Run " + entry + " for guidance. No installation, repair or service start was attempted.";
+  return {
+    systemMessage: message,
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: "Agent Task startup check: " + reasons[state] +
+        " If the user wants Agent Task, read the installed using-agent-task skill before attempting MCP operations. Verify the configured command/home; the check is not a live MCP health test. Obtain confirmation before installation or configuration changes. Do not replay work.",
+    },
+  };
+}

package/hosts/agent-task/scripts/session-start.mjs

@@ -0,0 +1,13 @@
+import { inspectInstallation, onboardingNotice } from "./preflight.mjs";
+
+// Hook stdout is host JSON, not MCP stdout. Never echo hook input or child output.
+process.stdin.resume();
+process.stdin.unref?.();
+try {
+  const notice = onboardingNotice(await inspectInstallation(), process.argv[2]);
+  if (notice) console.log(JSON.stringify(notice));
+} catch {
+  const notice = onboardingNotice("check-failed", process.argv[2]);
+  if (notice) console.log(JSON.stringify(notice));
+}
+// A diagnostic must not block the host session or grant any tool permissions.

package/hosts/agent-task/skills/using-agent-task/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: using-agent-task
+description: Use Agent Task from Pi, Claude Code or Codex. Covers installing the service, setup and MCP connection, submitting caller-defined task DAGs, inspecting runs and deliveries, answering user-fact questions, and diagnosing connection failures.
+---
+
+# Using Agent Task
+
+Use this skill when the user wants to use or connect Agent Task. It is guidance for the existing CLI and MCP tools, not a task executor, planner, scheduler or separate task API.
+
+## Choose the next step
+
+- **First use, missing service, or setup/connection request:** read [installation](references/installation.md). With user confirmation, execute the npm installation through the host's shell tool; do not merely suggest the command when you can perform the approved operation. Credentials stay in the user's terminal or private files.
+- **Connected and ready to work:** read [task usage](references/tasks.md). Discover the host's actual MCP tools and their current schemas. Do not run setup or reinstall the service on every task request.
+- **Connection or execution problem:** read [troubleshooting](references/troubleshooting.md). Inspect before changing anything; an uncertain outcome is not permission to replay work.
+
+Resolve reference paths from this skill directory. These files ship inside the plugin, so onboarding does not require the service package or repository documentation.
+
+## Boundaries
+
+- MCP callers define the fixed DAG and assign an existing ready ACP executor to each node. The service coordinator advances that DAG; it does not decompose the goal or change the plan.
+- Use existing MCP tools directly. Learn fields, defaults and errors from their live schemas, not a copied contract or a new wrapper.
+- Installation, native login, adapter readiness and tool authorization are different facts. Never disable sandboxing or widen approvals to make an operation work.
+- Keep credentials out of chat, command arguments and host MCP configuration. Do not read private environment files into model context.
+- A completed protocol turn or successful task submission is not a completed task. Report accepted delivery, failure and waiting-for-user states distinctly.
+- No automatic retries of interrupted work, executor switching, history deletion or workspace cleanup to repair state.
+
+Explicit invocation: Pi `/skill:using-agent-task`; Claude Code `/agent-task:using-agent-task`; Codex `$using-agent-task` or select it in `/skills`.

package/hosts/agent-task/skills/using-agent-task/references/installation.md

@@ -0,0 +1,83 @@
+# Install and connect Agent Task
+
+The plugin can be installed before the service. Its read-only startup check can show a using-agent-task reminder even when MCP cannot start. This check does not grant installation permission or prove MCP health; do not treat an inconclusive check as proof the service is absent. Plugin installation itself has no npm install hook and does not initialize a service. Claude Code/Codex may report an unavailable bundled MCP server until installation and setup are complete; the skill remains usable.
+
+## Check and install
+
+1. Identify the host, OS, intended installation and configuration scope. Require Linux/macOS, Node.js 22.19+ and npm; check `node --version`, `npm --version`, `command -v agent-task` and, when found, `agent-task --version`. Do not infer the task workspace from the plugin directory.
+2. Check whether this is an existing installation, a custom `--home`, or an already configured MCP connection. If the command is not on PATH, first check the user's known installation and `npm prefix -g`; a PATH problem does not require a second install.
+3. If the service is absent, explain that installation downloads a global npm package into the current user's npm prefix. Ask for confirmation to install `@realqiyan/agent-task`. Use an explicitly requested version when supplied; do not invent a version or imply the integration bundle version is already published.
+4. After confirmation, **execute** `npm install -g @realqiyan/agent-task` with the host's shell tool and normal permission checks. Do not use sudo, change the user's npm prefix or relax host security automatically. If permission or network access is unavailable, report the failure and offer the same command for the user's terminal. Do not retry with broader access.
+5. Check the exit status and installed `agent-task --version`. If necessary, locate the executable under the confirmed prefix's `bin/` and use its absolute path. Keep an existing installation unchanged unless the user explicitly approves an upgrade.
+
+Do not run installation in an MCP command, session-start hook, or `npx -y` launcher. Reconnection must not install or upgrade the service. Do not silently fall back from a failed release install to source builds.
+
+## Initialize through the existing CLI
+
+Ask the user to run `agent-task setup` in their own terminal, or `agent-task setup --home /absolute/private/agent-task` for the chosen custom home. Let them confirm directories, port, independent service/admin tokens and coordinator provider/model in that wizard. Do not request secret values in chat, print credential files, or reuse the host's model login as coordinator credentials.
+
+For a user-requested noninteractive setup, read `agent-task setup --help` and use only explicitly confirmed options and a user-prepared private credentials file. You may execute that command after confirmation. Do not invent model settings, generate tokens without consent or put secret values in arguments. Without a configured coordinator, management can work but executable tasks cannot be accepted.
+
+Preserve existing setup. Interrupted initialization needs an explicitly approved `--resume`; do not delete history or guess repairs. At least one native pi, codex, claude or opencode CLI must be visible to the service, with its own native login and authorization. Explain before connecting that MCP initialization may download missing ACP adapters. Readiness is not proof of authentication or complete tool authorization.
+
+## Startup-check scope and trust
+
+The plugin checks `agent-task setup --check --json`, with bounded time/output and no automatic repair. Unsupported or failed checks are inconclusive. An initialized but stopped backend is not a missing installation.
+
+Check the user's selected command/home before acting on a notice. When configuring a custom MCP connection, also set `AGENT_TASK_PREFLIGHT_COMMAND` and `AGENT_TASK_PREFLIGHT_HOME` in the host launch environment after confirmation. These non-secret variables select only the diagnostic target, not MCP or the service. Do not write them into service credentials or assume the plugin inferred manual host configuration.
+
+Codex needs the user to review and trust the plugin hook in `/hooks`. Never bypass hook trust. If hooks/extensions are disabled or Node itself cannot start, use the explicit skill entry; lack of a notice does not establish readiness. The user can disable the check in the host while retaining the skill.
+
+## Register or reconnect
+
+Use the same OS user, native environment and home as setup. Stdio reads service credentials privately; do not copy token values or ports into host configuration. Inspect existing entries before adding or replacing one, preserve unrelated settings and keep only one Agent Task connection.
+
+### Pi 1.4.0+ native MCP
+
+After confirmation, execute:
+
+```bash
+pi mcp add agent-task -- agent-task mcp
+pi mcp list
+```
+
+For a custom installation, replace the add command with:
+
+```bash
+pi mcp add agent-task -- /absolute/bin/agent-task mcp --home /absolute/private/agent-task
+```
+
+These are user-level entries; use `--local` only if the user chooses project scope. `add` replaces an existing same-name entry. Reload with `/reload` or start a new session. If another extension replaces Pi's native MCP, ask the user which integration to keep instead of installing a second bridge.
+
+### Claude Code and Codex plugins
+
+The enabled plugin already declares `agent-task mcp`. Do not also add a manual connection for the default installation. Complete setup, then start a new session; Claude Code also allows reconnecting the plugin server in `/mcp`. Inspect `/mcp` in the new session.
+
+For a custom home or executable, keep the skill but disable the bundled MCP entry before registering a manual connection. Do not edit an update-managed plugin cache.
+
+- Claude Code: ask the user to disable the plugin's Agent Task server in `/mcp`, then, with confirmation, execute:
+
+```bash
+claude mcp add --transport stdio --scope user agent-task -- /absolute/bin/agent-task mcp --home /absolute/private/agent-task
+```
+
+- Codex: with confirmation, merge this single table into the user's config without replacing other settings, then register the manual connection:
+
+```toml
+[plugins."agent-task@agent-task".mcp_servers.agent-task]
+enabled = false
+```
+
+```bash
+codex mcp add agent-task -- /absolute/bin/agent-task mcp --home /absolute/private/agent-task
+```
+
+Restart the session and confirm only the intended connection is enabled. GUI hosts must also be able to find Node and the native execution CLI.
+
+## Verify without executing domain work
+
+1. Confirm the host reports a connected server and lists its existing tools. A static configuration listing alone is not evidence of connection.
+2. Discover and call `executor_list` and `task_list` with `{}` through the host's MCP interface. Pi uses native tool search/codemode by default. Use the actual server/tool namespace.
+3. Report connection and read-only call results separately from executor readiness. If adapters are preparing, inspect later; do not submit a task or invoke a paid model merely to test installation.
+
+Append the selected `--home` to later service CLI commands. `agent-task mcp` starts or reuses a shared background service; host exit does not stop it. Confirm before stopping or restarting active work.

package/hosts/agent-task/skills/using-agent-task/references/tasks.md

@@ -0,0 +1,31 @@
+# Work through the existing MCP tools
+
+Discover the host's Agent Task server, its instructions and current input/output schemas before calling tools. Use the actual host namespace. Do not implement a forwarding tool, copy full schemas into this skill, or replace MCP operations with direct database/file writes.
+
+## Submit work
+
+- Establish the user's goal, intended delivery, execution timing and existing absolute workspace. Ask for missing facts rather than guessing. The plugin/cache directory is not the task workspace; give an explicit workspace unless the stdio launch directory is known to be correct.
+- Call `executor_list`. Select only existing ready executors appropriate for the user-authorized work. Adapter readiness alone does not establish native model login or tool permissions.
+- As the MCP caller, define the complete DAG and executor assignment for each node to match the user's request. Make dependencies and each node's work/acceptance criteria explicit; use one node when sufficient. Clarify material ambiguity or consequential actions before submission. Do not ask the service coordinator to invent or change the plan.
+- Read `task_create`'s current schema for timing, limits and request-key semantics. Keep the original submission identity and parameters when checking an uncertain response; do not create a fresh request key to replay work.
+- Call `task_create` only for authorized work. Save/report the task ID and workspace. Submission confirms persistence, not successful execution.
+
+## Inspect progress and delivery
+
+Use `task_list` to locate tasks, `task_get` for definitions, `task_run_list` for run history and `task_run_get` for run details and accepted delivery. Follow pagination using the returned continuation value and unchanged filters; avoid rapid, unbounded polling.
+
+Distinguish task trigger state from a particular run's outcome. Explain whether work is scheduled, executing, waiting for user facts, failed or delivered using the returned facts. A protocol turn ending or raw executor output is not accepted delivery. Read the accepted content and disclose missing evidence instead of treating a success label as proof of completeness.
+
+## Answer questions
+
+When a run needs user facts, retrieve its current unanswered question and applicable deadlines. Present the actual question and relevant completed work to the user. Submit their answer through `task_run_reply` using that run and question's identities and the tool's request-key contract.
+
+Do not invent an answer, substitute your own assumptions, treat a fact reply as permission, or start a new task to bypass the wait. If a reply's outcome is uncertain, inspect the existing run before further writes.
+
+## Control future work or cancel a run
+
+Use `task_update` for future-trigger pause/resume/cancel, and `task_run_cancel` to stop a particular run. Confirm which scope the user intends; changing future triggers does not cancel the current run. Cancellation cannot undo external side effects.
+
+For interrupted or unknown external outcomes, report the block and ask for investigation. Do not automatically retry, replay completed nodes, switch executors, edit the DAG or create replacement work to evade the block.
+
+Service administration uses the existing `agent-task` CLI, not task MCP wrappers. Consult `agent-task --help` and the relevant subcommand help for settings, executor discovery and lifecycle actions. Ask before applying configuration, upgrading adapters or restarting a service with active work.

package/hosts/agent-task/skills/using-agent-task/references/troubleshooting.md

@@ -0,0 +1,12 @@
+# Diagnose before changing anything
+
+- **Command missing:** check the host's PATH and the user's known npm prefix. Use the existing absolute executable when available. If genuinely absent, follow [installation](installation.md) and obtain consent before executing npm.
+- **Setup incomplete or wrong home:** use the home selected during setup. Do not expose the private environment file, run reset scripts or delete history. Interrupted initialization requires explicit approval for the CLI's resume procedure.
+- **Host entry missing/duplicated:** inspect the host's MCP configuration and enabled plugin. Pi needs native registration; Claude/Codex normally use the bundled entry. Reconnect after setup, and preserve unrelated configuration. Custom home instructions are in [installation](installation.md).
+- **No executor or adapters preparing:** use `executor_list` after connecting, or the existing CLI management commands when connection is unavailable. Explain missing native CLI, disabled executor, installation progress or preparation error separately. Use native login and authorization; never widen permissions to make a probe pass.
+- **Connected but executable tasks rejected:** inspect `service_status` and the error, including coordinator configuration and executor readiness. Management access does not prove a usable model. Do not guess credentials or launch a task as an authentication probe.
+- **Task failure, lost response or unknown outcome:** retrieve the existing task/run before proposing changes. Do not silently resubmit, change request keys or switch execution agents. Read [task usage](tasks.md) for the distinction between task and run controls.
+
+Use `agent-task status` for the shared backend, with the same custom `--home` when selected. Host disconnection or plugin removal does not stop persisted tasks. Restarting can interrupt ACP sessions and waiting runs; inspect active work and obtain consent before `restart` or `stop`.
+
+Logs and agent outputs can contain sensitive content. Do not print credential files or upload logs blindly. Report what was actually verified: configuration, connection, tool call, adapter readiness and real task delivery are separate evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realqiyan/agent-task",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.5",
   "license": "MIT",
   "author": "realqiyan",
   "repository": {
@@ -14,6 +14,9 @@
   },
   "files": [
     "bin/agent-task.mjs",
+    ".claude-plugin/marketplace.json",
+    ".agents/plugins/marketplace.json",
+    "hosts/agent-task/",
     "dist/**/*.js",
     "dist/web/*.html",
     "dist/web/*.css",
@@ -53,6 +56,7 @@
     "setup": "node bin/agent-task.mjs setup",
     "prepack": "npm run build",
     "pack:release": "node scripts/pack-release.mjs",
+    "pack:hosts": "node scripts/pack-hosts.mjs",
     "test:install": "node scripts/verify-install.mjs"
   },
   "dependencies": {

package/scripts/install-lib.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 export const packageRoot = realpathSync(fileURLToPath(new URL("..", import.meta.url)));
 
 export function argumentsFor(argv) {
-  const flags = new Set(["check", "resume", "help", "yes", "generate-tokens"]), options = {};
+  const flags = new Set(["check", "json", "resume", "help", "yes", "generate-tokens"]), options = {};
   for (let i = 0; i < argv.length; i++) {
     const key = argv[i].replace(/^--/, "");
     if (!argv[i].startsWith("--") || key in options) throw new Error("Invalid or repeated option");

package/scripts/setup.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, realpathSync, lstatSync } from "node:fs";
+import { existsSync, mkdirSync, realpathSync, lstatSync, writeSync } from "node:fs";
 import { join, isAbsolute } from "node:path";
 import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
@@ -16,20 +16,48 @@ let unlock;
 try {
   const options = argumentsFor(process.argv.slice(2));
   if (options.help) {
-    console.log("Usage: agent-task setup [--home ABSOLUTE_PRIVATE_DIR]\nNew installation: confirm directories, port, tokens and coordinator in the terminal.\nNoninteractive: --home DIR --data-dir DIR --port NUMBER --generate-tokens|--credentials-file PRIVATE_JSON --yes [--provider openai|anthropic|deepseek|openai-compatible --model ID]\nCompatible provider: --base-url URL --api openai-completions|openai-responses --api-key-env NAME --context-window NUMBER --max-tokens NUMBER\nExisting installation: --check | --resume. Secrets are read from a private JSON file or hidden terminal input, never command arguments. No executor installation during setup.");
+    console.log("Usage: agent-task setup [--home ABSOLUTE_PRIVATE_DIR]\nNew installation: confirm directories, port, tokens and coordinator in the terminal.\nNoninteractive: --home DIR --data-dir DIR --port NUMBER --generate-tokens|--credentials-file PRIVATE_JSON --yes [--provider openai|anthropic|deepseek|openai-compatible --model ID]\nCompatible provider: --base-url URL --api openai-completions|openai-responses --api-key-env NAME --context-window NUMBER --max-tokens NUMBER\nExisting installation: --check [--json] (read-only) | --resume. Secrets are read from a private JSON file or hidden terminal input, never command arguments. No executor installation during setup.");
     process.exit(0);
   }
+  if (options.json && !options.check) throw new Error("--json is only supported with setup --check");
   let root = installRoot(options);
-  if (!existsSync(join(root, "installation.json")) && !options.check && !options.resume && !options.yes) {
+  if (options.check) {
+    if (Object.keys(options).some(key => !["home", "check", "json"].includes(key))) throw new Error("Use setup --check with only optional --json and --home");
+    // This branch never creates a directory, opens SQLite, starts a service or repairs files.
+    let report;
+    try {
+      let present = true;
+      try { lstatSync(join(root, "installation.json")); }
+      catch (error) { if (error.code === "ENOENT") present = false; else throw error; }
+      if (!present) {
+        report = { configuration: existsSync(join(root, "launch.json")) ? "invalid" : "missing" };
+      } else {
+        const manifest = readManifest(root);
+        if (manifest.phase === "initializing") report = { configuration: "incomplete" };
+        else {
+          if (manifest.phase !== "ready" || !existsSync(join(packageRoot, "dist/application/main.js"))) throw new Error("Invalid installation");
+          const paths = startupPaths(root), config = loadConfig(paths.configPath), environment = readEnvironment(paths.environmentPath);
+          validateServiceEnvironment(config, environment);
+          report = { configuration: "valid", coordinatorConfigured: Boolean(config.coordinator && environment[coordinatorCredentialEnv(config.coordinator)]) };
+        }
+      }
+    } catch {
+      // Do not serialize exceptions: schema/parser errors can include private values.
+      report = { configuration: "invalid" };
+    }
+    writeSync(1, JSON.stringify(report) + "\n");
+    process.exit(report.configuration === "valid" ? 0 : 1);
+  }
+  if (!existsSync(join(root, "installation.json")) && !options.resume && !options.yes) {
     await setupWizard(options, root); root = installRoot(options);
   }
   let manifest, initialEnvironment;
   if (existsSync(join(root, "installation.json"))) {
     manifest = readManifest(root);
-    if (Object.keys(options).some(key => !["home", "check", "resume"].includes(key))) throw new Error("Installation exists; use configuration commands instead of initialization flags");
+    if (Object.keys(options).some(key => !["home", "resume"].includes(key))) throw new Error("Installation exists; use configuration commands instead of initialization flags");
     if (manifest.phase !== "ready" && !options.resume) throw new Error("Incomplete initialization; inspect private files and use --resume explicitly");
   } else {
-    if (options.check || options.resume) throw new Error("No installation to check/resume");
+    if (options.resume) throw new Error("No installation to resume");
     if (!options.yes || !options.home || !options["data-dir"] || options.port === undefined ||
       (!options["generate-tokens"] && !options["credentials-file"])) throw new Error("Confirm initialization with --home, --data-dir, --port, --generate-tokens/--credentials-file and --yes");
     const dataDir = installRoot({ home: options["data-dir"] });
@@ -84,7 +112,7 @@ try {
   validateServiceEnvironment(config, readEnvironment(paths.environmentPath));
   console.log(JSON.stringify({ configuration: "valid", coordinator: config.coordinator ? "configured; authentication not verified" : "not configured",
     configPath: paths.configPath, credentialsPath: paths.environmentPath, executorDiscovery: "on MCP connection" }, null, 2));
-  if (!options.check) console.log("Add agent-task with args [mcp] to your MCP client (include --home for a custom installation). Token values are not printed. Use agent-task start for foreground management.");
+  console.log("Add agent-task with args [mcp] to your MCP client (include --home for a custom installation). Token values are not printed. Use agent-task start for foreground management.");
 } catch (error) {
   console.error(error.name === "ZodError" ? "Invalid initialization configuration; check provider, model, directories and port" : error.message);
   process.exitCode = 1;