Skip to content

docs: prepare Chatroom 0.1.1 release #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NWYLZW merged 1 commit into from
Sep 19, 2026
Merged

docs: prepare Chatroom 0.1.1 release #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
289 changes: 65 additions & 224 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <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).
69 changes: 69 additions & 0 deletions README.zh-Hans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <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)。
Loading
Loading