diff --git a/AGENTS.md b/AGENTS.md index 8fbd1f0..df60b7c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,3 +26,18 @@ See the [Host notification guide](https://github.com/cordisx/cordisx/blob/3cfe37 for the interaction contract and older-Host capability boundary. Dependency setup: [notification migration](./.agents/docs/notifications.md). + +## Development and release + +- Requires Node.js 22 or newer. Install dependencies with `npm ci`. +- Run `npm run check`, `npm run format:check`, `npm run lint:source`, + `npm pack --dry-run`, and `git diff --check` before a release checkpoint. +- Keep the public READMEs focused on installation and use. Architecture, + source layout, local development, tests, contribution, and release operations + belong here or in the indexed `.agents` maintainer documentation. +- Releases use a GitHub prerelease, not npm. Build the exact merged main commit, + create the private package tarball with `npm pack`, attach it with + `SHA256SUMS`, and verify both assets by downloading and hashing them. +- The package descriptor, package version, README version, tag, and archive + must agree. Marketplace artifact URLs and digests are updated by the + Marketplace owner after the release; do not copy older trust records. diff --git a/README.md b/README.md index e810465..e1c8d3f 100644 --- a/README.md +++ b/README.md @@ -1,239 +1,80 @@ # Chatroom -Chatroom is a CordisX plugin for internal Room relationships, Agent identity, -message routing, and collaboration timelines. External channels are not part -of this version. - -It does not own Agent execution. Public Agent and Session services create or -resume each member runtime, send content, and expose replayable events. -Chatroom persists only the returned opaque Session identity under one Room -member run; it never parses, constructs, or emulates a Connector handle. - -## Status - -See [Room UI ownership](.agents/docs/room-ui-ownership.md) for the renderer boundary -and the separate native migration gates. - -The plugin contributes a body-only React page through the public CordisX page -API. Chatroom owns its title, timeline, member panel, composer, approval cards, -and direct OneWorks Avatar rendering. CordisX still owns the page seat, route, -shared React runtime, lifecycle, and application chrome. Chatroom never -fabricates a reply or projects opaque runtime handles. - -Each Room freezes a cycle-free membership forest with any number of leaders. -Role and attention policy are independent: ordinary messages fan out to every -ambient member, while mention-only members start receiving only when mentioned -or delegated to. Every member may own several independently fenced Agent -runs; identity never causes implicit cross-Room or cross-run reuse. Assistant -messages, approval state, failures, and lifecycle events from all runs are -merged into one Room timeline. Page-mounted avatars may capture a completed PNG -for a bounded Chatroom cache; sidebar navigation receives only the generic -`{ kind: "image", image }` value, or a semantic icon while no capture exists. - -The distributable runtime is a closed ESM graph. Plugin activation loads the -small registration entry only. On the plugin-page fallback, mounting the Room loads its page module and -stylesheet; the OneWorks renderer module and renderer-only stylesheet remain -deferred until a resolved avatar is actually displayed. Closing and reopening -the page creates a fresh React mount while the immutable module request is -reused by the browser. CordisX owns generation URLs, integrity checks, shared -React/ReactDOM singletons, replacement fencing, and stylesheet cleanup. - -## Scope - -- Expand `seedLeaderIds` into a frozen Agent membership snapshot with multiple - roots, leader-to-leader reporting, and cycle rejection. -- Route ambient, `@member`, `@member/run`, and leader-delegated messages to - deduplicated member/run recipients. -- Keep one generation-fenced Agent owner and Session event cursor isolated to - each run. -- Present real Session messages, approvals, failures, and lifecycle events in - a chronological plugin-owned timeline. -- Resolve and render the exact five OneWorks RC.9 animal assets directly in the - page, with deterministic initials for unsupported or absent references. - -Out of scope: host adapters, credentials, external channels, automation, -application chrome, arbitrary Host DOM access, rich-media messages, and Agent -execution. - -## Start a chatroom - -The new Room page presents its configured Leader avatars above the normal chat -composer. Choose one or send without selecting to use the default global Leader. -A first message should use the selected entity's bound project and a single -Host create-and-submit operation; existing Room Sessions are not migrated. - -The versioned Entity execution context service supplies explicit projectless -workspaces or verifies the Entity's saved project binding. Configure a future -Session's default project from the member's existing Team overview; only actual -Host projects are offered. An unbound global Leader needs no project or manual -directory. Existing Session associations remain unchanged. Older Hosts without -the service leave the draft intact and report the missing capability. - -This candidate consumes the Host context implementation under review in -[Host #387](https://github.com/cordisx/cordisx/pull/387), with formal -[Protocol #133](https://github.com/cordisx/cordisx-protocol/pull/133). -Native product acceptance remains separate from compilation and fixture checks. - -## Agent configuration - -The optional `team` configuration supplies seed leaders, a team graph, and the -complete inheritance catalog consumed by the public Agent service. Definitions support ordered -`extends`, explicit inheritance modes, prompt sections, rules, skills, tool and -MCP filters, runtime defaults, and formal Avatar references. Chatroom resolves -Avatar inheritance once while creating a Room and freezes the result with its -member and participant snapshot. Avatar references are never interpreted as -URLs or paths. Only plugin-generated, completed PNG snapshots cross the generic -sidebar image contract. - -```json -{ - "team": { - "seedLeaderIds": ["lead"], - "members": [ - { - "memberId": "lead", - "label": "Lead", - "definition": { "agentId": "chatroom.lead", "revision": "v1" }, - "role": "leader", - "attentionPolicy": "ambient" - }, - { - "memberId": "reviewer", - "label": "Reviewer", - "definition": { "agentId": "chatroom.reviewer", "revision": "v1" }, - "role": "member", - "attentionPolicy": "mention-only", - "reportsToMemberId": "lead" - } - ], - "definitions": [ - { - "$schema": "https://raw.githubusercontent.com/cordisx/cordisx-protocol/main/schemas/agent-definition.v1.schema.json", - "contract": "cordisx.agent-definition/v1", - "schemaVersion": 1, - "identity": { "agentId": "chatroom.lead", "revision": "v1" }, - "extends": [], - "inherit": { - "promptSections": "append", - "rules": "merge", - "skills": "merge", - "tools": "replace", - "mcpServers": "replace", - "runtimeDefaults": "merge", - "avatar": "none" - }, - "avatar": { - "kind": "definition", - "ref": "avatar-definitions:chatroom-lead", - "schema": "oneworks.avatar", - "definitionVersion": 1 - }, - "promptSections": [ - { - "sectionId": "intro", - "kind": "introduction", - "text": "You lead the current Room." - }, - { - "sectionId": "personality", - "kind": "personality", - "text": "Be concise and direct." - }, - { - "sectionId": "memory", - "kind": "memory", - "text": "Use only this Room TaskBinding context." - } - ], - "rules": ["chatroom.room-isolation", "chatroom.no-fabricated-replies"], - "skills": ["review"], - "tools": { - "include": ["read", "search"], - "exclude": ["external-channel"] - }, - "mcpServers": { "exclude": ["external-channel"] }, - "runtimeDefaults": { "adapterId": "codex", "effort": "medium" } - }, - { - "$schema": "https://raw.githubusercontent.com/cordisx/cordisx-protocol/main/schemas/agent-definition.v1.schema.json", - "contract": "cordisx.agent-definition/v1", - "schemaVersion": 1, - "identity": { "agentId": "chatroom.reviewer", "revision": "v1" }, - "extends": [{ "agentId": "chatroom.lead", "revision": "v1" }], - "inherit": { - "promptSections": "append", - "rules": "append", - "skills": "append", - "tools": "merge", - "mcpServers": "merge", - "runtimeDefaults": "merge", - "avatar": "inherit" - }, - "promptSections": [ - { - "sectionId": "reviewer-role", - "kind": "role", - "text": "Review work delegated to this member." - } - ] - } - ] - } -} +Chatroom creates multi-Agent Rooms inside CordisX. Use it when a task benefits +from several named Agent roles sharing one conversation, such as a lead, +reviewer, implementer, documentation owner, and QA owner. + +## Install + +Plugin ID: `chatroom`. Current release: `0.1.1`. + +The CordisX Community Marketplace feed must already be configured and enabled +before `--source` can select it: + +```sh +FEED_URL=https://raw.githubusercontent.com/cordisx/marketplace/main/marketplace.json +npx cordisx@beta source add "$FEED_URL" --yes +npx cordisx@beta plugin install chatroom --source "$FEED_URL" --version 0.1.1 ``` -The domain reserves both room-scoped and member-scoped opaque `ChannelLink` -records. External Channel runtime integration remains out of scope for this -version. +Skip `source add` when that exact feed is already enabled. For another profile, +add the same `--profile ` argument to both commands. `--yes` confirms +the source change only; it does not approve plugin permissions. A discovery +source is not a trust root. -## Explicit Agent reports +The install command becomes available after the Marketplace entry lists the +`0.1.1` artifact. Until then, download the archive and `SHA256SUMS` from the +[GitHub release](https://github.com/cordisx/plugin-chatroom/releases/tag/v0.1.1). -The experimental [CLI integration guide](.agents/docs/chatroom-cli.md) covers -opt-in reports, the packaged Skill, Room persistence, and current runtime gaps. +## Use -## Development +Open Chatroom in CordisX and create a Room. Choose a Leader or send the first +message with the default Leader. Add `@member` or `@member/run` to target a +specific participant; ordinary messages also reach members configured for +ambient attention. -For missing history, cold-start identity, source changes or CLI evidence, see -the [Room runtime debugging guide](.agents/docs/runtime-debugging.md). +Each member run keeps its own Agent and Session identity. Chatroom combines +their real messages, approvals, failures, and lifecycle events into the Room +timeline. It does not fabricate replies or reuse a run across Rooms. -Requires Node.js 22 or newer. +The package includes generalist, reviewer, integrator, documentation, and QA +Entity templates, plus additional playground templates. Saved project bindings +are respected when a new Session is created; existing Session associations are +not migrated. -```sh -npm ci -npm run check -npm run dev:dry-run -``` +## Configuration -`cordisx-package.json` is the CordisX package descriptor and points to the -Vite-built `dist/runtime/chatroom.js` graph entry. `src/chatroom.ts` registers the lazy -React page, routes, Room management commands, Manager content, and the v3 -generic-image sidebar collection. The build emits hashed page, renderer, and -CSS chunks while keeping CordisX's public React/UI modules Host-shared. -The dated [CSS and build audit](.agents/docs/css-and-build-audit.md) records -Team's retained inline styles, output consumers, and lifecycle validation limits. -OneWorks license and provenance details are in `THIRD_PARTY_NOTICES.md`. Local -experimental Host, Protocol, and Avatar checkpoints may be used for combination -validation; that does not make them a merged or released dependency. - -## Plugin artwork and distribution - -The selected 256×256 brand artwork is tracked at `assets/chatroom.png` and -included in the package file allowlist. The plugin entry exports `icon` through -the public `CordisXPluginBrandIcon` contract (`mediaType` and base64 `data`). -The Host validates this local artwork and renders it in its plugin list and -details; action and navigation icons continue to use Host semantic tokens. -`test/brand-icon.mjs` verifies the PNG digest, dimensions, embedded bytes, and -production graph inclusion. - -Chatroom remains a private npm package with `explicit-local-v1` distribution. -This artwork ships through the repository source and the normal built local -package; no npm release or new version is required. Marketplace artwork can -reference `assets/chatroom.png` at an immutable repository commit. +Room membership is supplied through the optional `team` configuration. It can +define seed leaders, members, reporting relationships, attention policies, and +Agent definitions. Configure teams through CordisX rather than editing the +installed package. A Room freezes its membership and resolved definitions when +it is created, so later configuration changes apply to new Rooms. -## License +## Permissions and limits + +Chatroom requires Agent create, resume, lookup, message submit, message cancel, +Session lookup, and Session subscription capabilities. Approval request and +answer capabilities are optional and scoped to the active command or Session +route. Review requested permissions in CordisX before enabling the plugin. -[MIT](LICENSE) +External channels, credentials, rich-media messages, automation, and Host +application chrome are outside this release. Avatar references are treated as +definitions, not arbitrary URLs or filesystem paths. Plugin data and Agent +execution remain subject to the configured CordisX Host and Connector. -## Notification feedback +## Troubleshooting + +- **Install cannot find version `0.1.1`:** confirm the Marketplace entry lists + the release artifact. `--source` does not add or repair a feed. +- **A member does not receive a message:** check its attention policy and use an + exact `@member` or `@member/run` mention. +- **A Room cannot start or resume a run:** verify the member's project binding + and the required Agent and Session permissions. +- **Approvals are unavailable:** enable the optional approval permissions for + the active Room workflow. + +## License -See [operation notifications and development dependencies](./.agents/docs/notifications.md). +Chatroom is licensed under the [MIT License](LICENSE). Third-party artwork and +dependency notices are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). +Maintainer setup, checks, and release instructions are in [AGENTS.md](AGENTS.md). diff --git a/README.zh-Hans.md b/README.zh-Hans.md new file mode 100644 index 0000000..91ab6be --- /dev/null +++ b/README.zh-Hans.md @@ -0,0 +1,69 @@ +# Chatroom + +Chatroom 在 CordisX 中创建多 Agent 协作 Room。当一个任务需要 Lead、Reviewer、 +实现、文档和 QA 等多个具名角色共享同一段对话时，可以使用本插件。 + +## 安装 + +插件 ID：`chatroom`。当前版本：`0.1.1`。 + +CordisX Community Marketplace feed 必须先完成配置并启用，`--source` 才能选择它： + +```sh +FEED_URL=https://raw.githubusercontent.com/cordisx/marketplace/main/marketplace.json +npx cordisx@beta source add "$FEED_URL" --yes +npx cordisx@beta plugin install chatroom --source "$FEED_URL" --version 0.1.1 +``` + +若该 feed 已启用，可跳过 `source add`。使用其他 profile 时，两条命令都要添加 +相同的 `--profile `。`--yes` 只确认来源变更，不会批准插件权限；发现来源 +也不等同于 trust root。 + +Marketplace 条目列出 `0.1.1` artifact 后，安装命令才可用。在此之前，可从 +[GitHub Release](https://github.com/cordisx/plugin-chatroom/releases/tag/v0.1.1) +下载压缩包与 `SHA256SUMS`。 + +## 使用 + +在 CordisX 中打开 Chatroom 并创建 Room。选择一个 Leader，或直接发送第一条消息 +来使用默认 Leader。通过 `@member` 或 `@member/run` 指定参与者；普通消息也会发送给 +attention policy 为 ambient 的成员。 + +每个成员运行都保留独立的 Agent 与 Session 身份。Chatroom 将真实消息、审批、失败 +和生命周期事件汇总到 Room timeline，不会伪造回复，也不会跨 Room 复用运行。 + +包内包含 generalist、reviewer、integrator、documentation 和 QA Entity 模板，以及 +额外的 playground 模板。创建新 Session 时会遵循已保存的项目绑定，已有 Session +关联不会被迁移。 + +## 配置 + +可选的 `team` 配置可以定义 seed leader、成员、汇报关系、attention policy 和 Agent +定义。请通过 CordisX 配置团队，不要直接修改已安装的包。Room 创建时会冻结成员和 +解析后的定义，因此后续配置变更只影响新 Room。 + +## 权限与限制 + +Chatroom 需要 Agent 创建、恢复、查询、消息提交、消息取消，以及 Session 查询和订阅 +能力。审批请求与答复能力是可选的，并限定在当前命令或 Session 路由范围内。启用插件 +前，请在 CordisX 中检查请求的权限。 + +本版本不包含外部 Channel、凭据、富媒体消息、自动化或 Host 应用 chrome。Avatar +引用按定义处理，不会当作任意 URL 或文件路径。插件数据和 Agent 执行仍受已配置的 +CordisX Host 与 Connector 约束。 + +## 排错 + +- **找不到 `0.1.1`：**确认 Marketplace 条目已列出 release artifact；`--source` + 不会添加或修复 feed。 +- **成员没有收到消息：**检查其 attention policy，并使用精确的 `@member` 或 + `@member/run` mention。 +- **Room 无法启动或恢复运行：**检查成员的项目绑定，以及必需的 Agent 和 Session + 权限。 +- **审批不可用：**为当前 Room 工作流启用可选的审批权限。 + +## 许可证 + +Chatroom 使用 [MIT License](LICENSE)。第三方图像与依赖声明见 +[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。维护者环境、检查和发布步骤见 +[AGENTS.md](AGENTS.md)。 diff --git a/cordisx-package.json b/cordisx-package.json index 7470e64..4524132 100644 --- a/cordisx-package.json +++ b/cordisx-package.json @@ -2,7 +2,7 @@ "$schema": "https://raw.githubusercontent.com/cordisx/cordisx-protocol/main/schemas/plugin-package.v12.schema.json", "schemaVersion": 12, "id": "chatroom", - "version": "0.1.0", + "version": "0.1.1", "entry": "./dist/runtime/chatroom.js", "readme": "./README.md", "canonicalSource": "https://github.com/cordisx/plugin-chatroom", diff --git a/package-lock.json b/package-lock.json index 90b8a1b..6ef0308 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@cordisx/chatroom", - "version": "0.1.0", + "version": "0.1.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@cordisx/chatroom", - "version": "0.1.0", + "version": "0.1.1", "license": "MIT", "bin": { "cordisx-chatroom": "dist/agent-tools/cli/chatroom.mjs" diff --git a/package.json b/package.json index cf81092..be31c52 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@cordisx/chatroom", - "version": "0.1.0", + "version": "0.1.1", "private": true, "description": "Chatroom Room collaboration plugin for CordisX", "license": "MIT", @@ -11,6 +11,8 @@ "assets/chatroom.png", "dist", "entities", + "README.md", + "README.zh-Hans.md", "cordisx-package.json", "runtime-manifest.json", "THIRD_PARTY_NOTICES.md",