Compare commits

...
Author SHA1 Message Date
renovate[bot] 3ce3d0e266 Update ghcr.io/element-hq/element-web:develop Docker digest to f7b5906 (#4462)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-15 01:53:38 +00:00
renovate[bot] 6f328d7304 Update ghcr.io/element-hq/element-web:develop Docker digest to 00133e9 (#4460)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-14 02:17:39 +00:00
Johannes Marbach 413b795459 Merge pull request #4452 from element-hq/johannes/agents-fixes
Compact AGENTS.md and split hand-off out into a skill
2026-11-13 14:22:39 +01:00
renovate[bot] e9c1e25542 Update ghcr.io/element-hq/element-web:develop Docker digest to 2901117 (#4453)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-13 09:06:50 +00:00
Timo f88d8d5830 Merge pull request #4456 from element-hq/toger5/getRTCTrasnport_and_getDomain
Use non deprecated non unstable names for getRTCTransports.
2026-11-12 16:12:02 +01:00
Timo K. 6c66f9a3e7 use non deprecated non unstable names for getRTCTransports.
Also remove getDomain where possible
2026-11-12 16:01:11 +01:00
Johannes Marbach d5f72f464d Compact AGENTS.md and split hand-off out into a skill 2026-11-11 16:33:46 +01:00
13 changed files with 96 additions and 92 deletions
+35
View File
@@ -0,0 +1,35 @@
---
name: handoff
description: Implement the first cut of a task and stop for a direction check before the quality pass.
argument-hint: <the task>
disable-model-invocation: true
---
Task: $ARGUMENTS
Stop after the first implementation and hand it back before the quality pass.
## Before the hand-off
- Run the narrowest check that rules out an obviously broken hand-off: the test
file for the touched code, `tsc` on its own, a single story. Not the full
`pnpm lint`, not the whole suite.
- If a wider check is needed before feedback can be useful, keep it to the touched
code and say why it was needed.
- Leave wider refactors, extra tests and documentation polish out. They are
follow-up work, not part of the first hand-off.
## The hand-off
Stop and ask whether the direction is right. The message says:
- what was built and where, in a few lines,
- which check ran and what it returned, verbatim if it failed,
- what was left out on purpose,
- the decisions that could have gone another way.
Do not continue past this point on your own.
## After the user confirms
The skill ends here. Continue with the quality pass as usual.
+4
View File
@@ -44,3 +44,7 @@ storybook-static
# Nested checkout made by scripts/layered.sh # Nested checkout made by scripts/layered.sh
/matrix-js-sdk/ /matrix-js-sdk/
# Claude
/.claude/*
!/.claude/skills/
+25 -4
View File
@@ -16,19 +16,35 @@ host's page. It is the MatrixRTC reference implementation.
`@media`, global `i18next` or the `widget` global — take it from a provider. `@media`, global `i18next` or the `widget` global — take it from a provider.
- The change works standalone, as a widget and as a component. Say what you checked. - The change works standalone, as a widget and as a component. Say what you checked.
- Every gate below is green before you push. - Every gate below is green before you push.
- Hand off after the first implementation, before the quality pass. Then commit on
the user's word where the setup allows it, or hand them the message.
## Read before you ## Read before you
| … | … | | … | … |
| -------------------------------- | ---------------------------------------------------------- | | -------------------------------- | ---------------------------------------------------------- |
| start a task of any size | [docs/agents/workflow.md](docs/agents/workflow.md) |
| touch call logic or a view model | [docs/agents/architecture.md](docs/agents/architecture.md) | | touch call logic or a view model | [docs/agents/architecture.md](docs/agents/architecture.md) |
| write any code | [docs/agents/code-style.md](docs/agents/code-style.md) | | write any code | [docs/agents/code-style.md](docs/agents/code-style.md) |
| write a test, story or e2e spec | [docs/agents/testing.md](docs/agents/testing.md) | | write a test, story or e2e spec | [docs/agents/testing.md](docs/agents/testing.md) |
| open a PR | [CONTRIBUTING.md](CONTRIBUTING.md) | | open a PR | [CONTRIBUTING.md](CONTRIBUTING.md) |
| implement from a feature spec | [FEATURES_SPEC/AGENTS.md](FEATURES_SPEC/AGENTS.md) |
## Scratch files live in `agent-workspace/`
Git-ignored. One kebab-case subfolder per task, matching the branch topic:
`agent-workspace/<slug>/`.
| File | Purpose |
| --------------------------- | -------------------------------------------------------------------------------- |
| `plan.md` | The concrete approach — files, symbols, edit order — once direction is confirmed |
| `commit-msg.txt` | `git commit -F agent-workspace/<slug>/commit-msg.txt` |
| `pr-body.md` | `gh pr create --body-file agent-workspace/<slug>/pr-body.md` |
| `implementation-summary.md` | What was built, decisions, trade-offs |
| `NN-prompt.md` | Raw prompt text, numbered, when worth keeping |
- Nothing here is durable. The folder is ignored, so anything worth keeping is
promoted into the PR body or a doc before the task ends.
- Never write scratch files to the repo root. Stray `load_test_summary.md` and
`config.json_` files are what this folder prevents.
- Start `pr-body.md` from `.github/PULL_REQUEST_TEMPLATE.md` and fill every
section.
## Gates ## Gates
@@ -42,6 +58,11 @@ pnpm i18n:check
`knip` fails on dead code; a file deliberately inert ahead of its consumer goes in `knip` fails on dead code; a file deliberately inert ahead of its consumer goes in
`knip.ts` `ignoreFiles` with a reason. `knip.ts` `ignoreFiles` with a reason.
Ready means every gate is green and the change is covered at the layers
[testing.md](docs/agents/testing.md) asks for. Read the diff against
[code-style.md](docs/agents/code-style.md) first. Re-run the whole checklist after
any fix.
## A good PR ## A good PR
- One slice, under ~400 changed lines, green on its own, linked to its issue. - One slice, under ~400 changed lines, green on its own, linked to its issue.
+2 -2
View File
@@ -19,10 +19,10 @@ services:
- ./backend/playwright_homeserver-othersite.yaml:/data/cfg/homeserver.yaml:Z - ./backend/playwright_homeserver-othersite.yaml:/data/cfg/homeserver.yaml:Z
element-web: element-web:
# Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates. # Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates.
image: ghcr.io/element-hq/element-web:develop@sha256:72791f0b2541208f8f7edd9c6b5a7eaf88accd8ed1f0c4db1bc62bfe18eb90fe image: ghcr.io/element-hq/element-web:develop@sha256:f7b5906e3784bf27f974d6da1298855d8b8670533fa9b1e95a55473fe431346e
element-web-1: element-web-1:
# Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates. # Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates.
image: ghcr.io/element-hq/element-web:develop@sha256:72791f0b2541208f8f7edd9c6b5a7eaf88accd8ed1f0c4db1bc62bfe18eb90fe image: ghcr.io/element-hq/element-web:develop@sha256:f7b5906e3784bf27f974d6da1298855d8b8670533fa9b1e95a55473fe431346e
volumes: volumes:
# The other site opens the embedded package under test in place of the # The other site opens the embedded package under test in place of the
# copy its image bundles (the first site opens the dev server's app. # copy its image bundles (the first site opens the dev server's app.
+5 -1
View File
@@ -14,7 +14,11 @@ This folder contains documentation for setup, usage, and development of Element
Entry point: [AGENTS.md](../AGENTS.md). Entry point: [AGENTS.md](../AGENTS.md).
- [Agent workflow](./agents/workflow.md)
- [Architecture](./agents/architecture.md) - [Architecture](./agents/architecture.md)
- [Code style](./agents/code-style.md) - [Code style](./agents/code-style.md)
- [Testing](./agents/testing.md) - [Testing](./agents/testing.md)
Opt-in skills in [`.claude/skills/`](../.claude/skills/):
- `/handoff <task>` — get the first implementation back for a direction check
before lint, the full suite and polish.
-50
View File
@@ -1,50 +0,0 @@
# Agent workflow
## Scratch files live in `agent-workspace/`
Git-ignored. One kebab-case subfolder per task, matching the branch topic:
`agent-workspace/<slug>/`.
| File | Purpose |
| --------------------------- | -------------------------------------------------------------------------------- |
| `plan.md` | The concrete approach — files, symbols, edit order — once direction is confirmed |
| `commit-msg.txt` | `git commit -F agent-workspace/<slug>/commit-msg.txt` |
| `pr-body.md` | `gh pr create --body-file agent-workspace/<slug>/pr-body.md` |
| `implementation-summary.md` | What was built, decisions, trade-offs |
| `NN-prompt.md` | Raw prompt text, numbered, when worth keeping |
- Nothing here is durable. The folder is ignored, so anything worth keeping is
promoted into the PR body, a doc, or a feature spec before the task ends.
- Never write scratch files to the repo root. Stray `load_test_summary.md` and
`config.json_` files are what this folder prevents.
- Start `pr-body.md` from `.github/PULL_REQUEST_TEMPLATE.md` and fill every
section.
- Commit subjects are plain imperative English. No conventional-commits prefixes.
- A `plan.md` and a feature spec sit at different altitudes; neither replaces the
other. A spec in `FEATURES_SPEC/` is durable and deliberately abstract —
behaviour, decisions, acceptance criteria — so the feature can be rebuilt against
a `main` nobody has seen yet. A plan is one slice of it landing on today's
`main`: the paths, symbols and edit order the spec's decisions and criteria must
not name. `FEATURES_SPEC/AGENTS.md` wins wherever the two genuinely overlap.
## Hand off before the quality pass
- Implement the change, run the narrowest check that rules out an obviously broken
handoff, then stop and ask whether the direction is right.
- Full `pnpm lint`, the whole suite, coverage and benchmarks come after the
direction is confirmed.
- Wider refactors, extra tests and documentation polish are follow-up work, not
part of the first handoff.
- If a check is needed before feedback, keep it to the touched code and say why.
## Commit and PR readiness
- Commit once the user confirms direction, or asks for one. Not before. Where the
setup has no git identity, a sandbox included, write the message to
`commit-msg.txt` and hand it over instead.
- Ready means every gate in [AGENTS.md](../../AGENTS.md#gates) is green and the
change is covered at the layers [testing.md](./testing.md) asks for. Read the diff
against [code-style.md](./code-style.md) first.
- Re-run the whole checklist after any fix. Only on green, either way.
- Once a human has started reviewing, fix forward — never force-push a
regeneration over a review in progress.
+1 -1
View File
@@ -107,7 +107,7 @@
"livekit-client": "^2.18.1", "livekit-client": "^2.18.1",
"lodash-es": "^4.17.21", "lodash-es": "^4.17.21",
"loglevel": "^1.9.1", "loglevel": "^1.9.1",
"matrix-js-sdk": "github:matrix-org/matrix-js-sdk#dc8610e796c92553c658300a4882dde961a0678a", "matrix-js-sdk": "github:matrix-org/matrix-js-sdk#10e4faabbb49baca655492d523b58faa9eea04b9",
"matrix-widget-api": "^1.18.0", "matrix-widget-api": "^1.18.0",
"node-stdlib-browser": "^1.3.1", "node-stdlib-browser": "^1.3.1",
"normalize.css": "^8.0.1", "normalize.css": "^8.0.1",
+10 -10
View File
@@ -191,8 +191,8 @@ importers:
specifier: ^1.9.1 specifier: ^1.9.1
version: 1.9.2 version: 1.9.2
matrix-js-sdk: matrix-js-sdk:
specifier: github:matrix-org/matrix-js-sdk#dc8610e796c92553c658300a4882dde961a0678a specifier: github:matrix-org/matrix-js-sdk#10e4faabbb49baca655492d523b58faa9eea04b9
version: https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/dc8610e796c92553c658300a4882dde961a0678a version: https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/10e4faabbb49baca655492d523b58faa9eea04b9
matrix-widget-api: matrix-widget-api:
specifier: ^1.18.0 specifier: ^1.18.0
version: 1.20.0 version: 1.20.0
@@ -1195,8 +1195,8 @@ packages:
'@types/dom-mediacapture-transform': ^0.1.9 '@types/dom-mediacapture-transform': ^0.1.9
livekit-client: ^1.12.0 || ^2.1.0 livekit-client: ^1.12.0 || ^2.1.0
'@matrix-org/matrix-sdk-crypto-wasm@18.9.0': '@matrix-org/matrix-sdk-crypto-wasm@18.9.2':
resolution: {integrity: sha512-NtLzNDTEfNASBjNCTGZHuk7N0jrQhS6Zx2CM857rCHZYYh/rpbKGQNrJ7azktm4S1P5Jy3WU3nwJTGohGw26qQ==} resolution: {integrity: sha512-GHeuSeb5Fj6Wg2+NE/WoLJJs9U3nOzttO+2sj7lOaS5gNBpGIksc48N/Q/kK/Z+Lxh7YMhopB7M8b6HyASXnGQ==}
engines: {node: '>= 18'} engines: {node: '>= 18'}
'@mdx-js/react@3.1.1': '@mdx-js/react@3.1.1':
@@ -4734,9 +4734,9 @@ packages:
matrix-events-sdk@0.0.1: matrix-events-sdk@0.0.1:
resolution: {integrity: sha512-1QEOsXO+bhyCroIe2/A5OwaxHvBm7EsSQ46DEDn8RBIfQwN5HWBpFvyWWR4QY0KHPPnnJdI99wgRiAl7Ad5qaA==} resolution: {integrity: sha512-1QEOsXO+bhyCroIe2/A5OwaxHvBm7EsSQ46DEDn8RBIfQwN5HWBpFvyWWR4QY0KHPPnnJdI99wgRiAl7Ad5qaA==}
matrix-js-sdk@https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/dc8610e796c92553c658300a4882dde961a0678a: matrix-js-sdk@https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/10e4faabbb49baca655492d523b58faa9eea04b9:
resolution: {gitHosted: true, integrity: sha512-Ldt/VkCzBtre6m1cn0FqgrzRV0GrgWIoARgQUQO58ef2Edu2ERFCINPzp/psFS5RwoN3RIy9Rm4oPVc1ATkEWA==, tarball: https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/dc8610e796c92553c658300a4882dde961a0678a} resolution: {gitHosted: true, integrity: sha512-7cbPN96wGt93B73jZieW2HBtTnasgKJ7wzTgiV0SjwkNyb50EK3vDa17LdSJpyOwEjFP5edyPRprk865HQJqww==, tarball: https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/10e4faabbb49baca655492d523b58faa9eea04b9}
version: 45.0.0 version: 45.1.0
engines: {node: '>=22.0.0'} engines: {node: '>=22.0.0'}
matrix-widget-api@1.20.0: matrix-widget-api@1.20.0:
@@ -7178,7 +7178,7 @@ snapshots:
'@types/dom-mediacapture-transform': 0.1.11 '@types/dom-mediacapture-transform': 0.1.11
livekit-client: 2.23.0(@types/dom-mediacapture-record@1.0.22) livekit-client: 2.23.0(@types/dom-mediacapture-record@1.0.22)
'@matrix-org/matrix-sdk-crypto-wasm@18.9.0': {} '@matrix-org/matrix-sdk-crypto-wasm@18.9.2': {}
'@mdx-js/react@3.1.1(@types/react@19.2.18)(react@19.3.1)': '@mdx-js/react@3.1.1(@types/react@19.2.18)(react@19.3.1)':
dependencies: dependencies:
@@ -10413,10 +10413,10 @@ snapshots:
matrix-events-sdk@0.0.1: {} matrix-events-sdk@0.0.1: {}
matrix-js-sdk@https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/dc8610e796c92553c658300a4882dde961a0678a: matrix-js-sdk@https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/10e4faabbb49baca655492d523b58faa9eea04b9:
dependencies: dependencies:
'@babel/runtime': 8.0.8 '@babel/runtime': 8.0.8
'@matrix-org/matrix-sdk-crypto-wasm': 18.9.0 '@matrix-org/matrix-sdk-crypto-wasm': 18.9.2
another-json: 0.2.0 another-json: 0.2.0
bs58: 6.0.0 bs58: 6.0.0
content-type: 3.1.1 content-type: 3.1.1
+1 -1
View File
@@ -140,7 +140,7 @@ function setup(
getDeviceId: () => deviceId, getDeviceId: () => deviceId,
getDomain: () => "example.org", getDomain: () => "example.org",
getSyncState: () => SyncState.Syncing, getSyncState: () => SyncState.Syncing,
_unstable_getRTCTransports: vi.fn().mockResolvedValue(homeserverTransports), getRTCTransports: vi.fn().mockResolvedValue(homeserverTransports),
_unstable_getLivekitToken: vi.fn().mockResolvedValue({ jwt: publisherJWT }), _unstable_getLivekitToken: vi.fn().mockResolvedValue({ jwt: publisherJWT }),
} as unknown as MatrixClient; } as unknown as MatrixClient;
const members$ = new BehaviorSubject<RTCMember[]>([]); const members$ = new BehaviorSubject<RTCMember[]>([]);
+2 -2
View File
@@ -31,7 +31,7 @@ function client(
): Parameters<typeof discoverLocalTransport>[0] { ): Parameters<typeof discoverLocalTransport>[0] {
return { return {
getDomain: () => "example.org", getDomain: () => "example.org",
_unstable_getRTCTransports: vi.fn().mockResolvedValue(advertised), getRTCTransports: vi.fn().mockResolvedValue(advertised),
}; };
} }
@@ -54,7 +54,7 @@ describe("discoverLocalTransport", () => {
logger, logger,
), ),
).resolves.toBe(hostTransport); ).resolves.toBe(hostTransport);
expect(c._unstable_getRTCTransports).not.toHaveBeenCalled(); expect(c.getRTCTransports).not.toHaveBeenCalled();
}); });
it("prefers the homeserver's transport over the host's fallback", async () => { it("prefers the homeserver's transport over the host's fallback", async () => {
+1 -1
View File
@@ -22,7 +22,7 @@ import { TransportAutoDiscovery } from "./TransportAutoDiscovery";
* @throws {MatrixRTCTransportMissingError} where none of these exists. * @throws {MatrixRTCTransportMissingError} where none of these exists.
*/ */
export async function discoverLocalTransport( export async function discoverLocalTransport(
client: Pick<MatrixClient, "getDomain" | "_unstable_getRTCTransports">, client: Pick<MatrixClient, "getDomain" | "getRTCTransports">,
transportTypes: readonly string[], transportTypes: readonly string[],
{ {
transport: override, transport: override,
@@ -36,11 +36,7 @@ const configTransport: Transport = {
function makeClient(): MockedObject<DiscoveryClient> { function makeClient(): MockedObject<DiscoveryClient> {
return { return {
getDomain: vi.fn().mockReturnValue("example.org"), getRTCTransports: vi.fn().mockResolvedValue([]),
baseUrl: "https://matrix.example.org",
_unstable_getRTCTransports: vi.fn().mockResolvedValue([]),
getOpenIdToken: vi.fn(),
getDeviceId: vi.fn(),
} as unknown as MockedObject<DiscoveryClient>; } as unknown as MockedObject<DiscoveryClient>;
} }
@@ -57,7 +53,7 @@ describe("TransportAutoDiscovery", () => {
"prefers backend transport other app config $transports", "prefers backend transport other app config $transports",
async ({ transports }) => { async ({ transports }) => {
const client = makeClient(); const client = makeClient();
client._unstable_getRTCTransports.mockResolvedValue(transports); client.getRTCTransports.mockResolvedValue(transports);
const discovery = new TransportAutoDiscovery({ const discovery = new TransportAutoDiscovery({
client, client,
@@ -71,7 +67,7 @@ describe("TransportAutoDiscovery", () => {
expect(discoveredTransport).toStrictEqual(backendTransport); expect(discoveredTransport).toStrictEqual(backendTransport);
expect(discoveredTransport).not.toStrictEqual(configTransport); expect(discoveredTransport).not.toStrictEqual(configTransport);
expect(client._unstable_getRTCTransports).toHaveBeenCalledTimes(1); expect(client.getRTCTransports).toHaveBeenCalledTimes(1);
}, },
); );
@@ -81,10 +77,7 @@ describe("TransportAutoDiscovery", () => {
url: "wss://sfu.example.org", url: "wss://sfu.example.org",
}; };
const client = makeClient(); const client = makeClient();
client._unstable_getRTCTransports.mockResolvedValue([ client.getRTCTransports.mockResolvedValue([backendTransport, mLivekit]);
backendTransport,
mLivekit,
]);
const discovery = new TransportAutoDiscovery({ const discovery = new TransportAutoDiscovery({
client, client,
@@ -100,7 +93,7 @@ describe("TransportAutoDiscovery", () => {
it("Retries limit_exceeded backend transport", async () => { it("Retries limit_exceeded backend transport", async () => {
const client = makeClient(); const client = makeClient();
client._unstable_getRTCTransports client.getRTCTransports
.mockRejectedValueOnce( .mockRejectedValueOnce(
new MatrixError( new MatrixError(
{ {
@@ -124,7 +117,7 @@ describe("TransportAutoDiscovery", () => {
backendTransport, backendTransport,
); );
expect(client._unstable_getRTCTransports).toHaveBeenCalledTimes(2); expect(client.getRTCTransports).toHaveBeenCalledTimes(2);
}); });
const INVALID_TEST_CASES: Array<{ transports: Transport[] }> = [ const INVALID_TEST_CASES: Array<{ transports: Transport[] }> = [
@@ -135,7 +128,7 @@ describe("TransportAutoDiscovery", () => {
"falls back to config when backend has no (valid) livekit transports $transports", "falls back to config when backend has no (valid) livekit transports $transports",
async ({ transports }) => { async ({ transports }) => {
const client = makeClient(); const client = makeClient();
client._unstable_getRTCTransports.mockResolvedValue(transports); client.getRTCTransports.mockResolvedValue(transports);
const discovery = new TransportAutoDiscovery({ const discovery = new TransportAutoDiscovery({
client, client,
@@ -152,7 +145,7 @@ describe("TransportAutoDiscovery", () => {
it("returns null when backend and config are all unavailable", async () => { it("returns null when backend and config are all unavailable", async () => {
const client = makeClient(); const client = makeClient();
client._unstable_getRTCTransports.mockResolvedValue([]); client.getRTCTransports.mockResolvedValue([]);
const discovery = new TransportAutoDiscovery({ const discovery = new TransportAutoDiscovery({
client, client,
+2 -5
View File
@@ -10,10 +10,7 @@ import { type Logger } from "matrix-js-sdk/lib/logger";
import { doNetworkOperationWithRetry } from "../utils/network"; import { doNetworkOperationWithRetry } from "../utils/network";
type TransportDiscoveryClient = Pick< type TransportDiscoveryClient = Pick<MatrixClient, "getRTCTransports">;
MatrixClient,
"getDomain" | "_unstable_getRTCTransports"
>;
export interface TransportAutoDiscoveryProps { export interface TransportAutoDiscoveryProps {
client: TransportDiscoveryClient; client: TransportDiscoveryClient;
@@ -74,7 +71,7 @@ export class TransportAutoDiscovery {
this.logger.info("First try to use getRTCTransports end point ..."); this.logger.info("First try to use getRTCTransports end point ...");
try { try {
const transportList = await doNetworkOperationWithRetry(async () => const transportList = await doNetworkOperationWithRetry(async () =>
client._unstable_getRTCTransports(), client.getRTCTransports(),
); );
for (const type of this.transportTypes) { for (const type of this.transportTypes) {
const first = transportList.find( const first = transportList.find(