Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions CURRENT-STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ coordination branch. Detailed state belongs in each linked status file.

| Name | Started | Goal | State | Branch association | Status file |
|---|---|---|---|---|---|
| `presentations` | 2026-11-16 | Deliver agent-driven E2E recording and presentation from Markdown or inline English in adopter DevCapsules | paused; PR #43 reviewed; awaits owner merge to release 0.3.1 | `ws-presentations/0.3.1-authoring` | [workstream status](engineering-docs/wip/2026-11-16-presentations/CURRENT-STATUS.md) |
| `github-auth` | 2026-11-16 | GitHub SSH authentication through a launcher-owned host proxy | paused; Pair Review #44 merged; PR #47 targets release-0.3.1; two inherited gate failures remain | `ws-github-auth/ssh-proxy` | [workstream status](engineering-docs/wip/2026-11-16-github-auth/CURRENT-STATUS.md) |
| `workflow-improvements` | 2026-08-09 | Improve the multiple-stream workflow from concrete dogfood findings during the recursive E2E cycle | active 2026-10-30; Pair Review Loop naming implemented and packaging verified for 0.3.0; mainline and release integration pending | `ws-workflow-improvements/v1` | [workstream status](engineering-docs/wip/2026-08-09-workflow-improvements/CURRENT-STATUS.md) |
| `project-management` | 2026-08-09 | Maintain project-wide priorities, sequencing, dependencies, and lifecycle coordination | paused 2026-10-11 at owner direction; consent and forced configuration before RC work; remaining diagnostics/image scope and release cut decisions retained | `ws-project-management/coordination` | [workstream status](engineering-docs/wip/2026-08-09-project-management/CURRENT-STATUS.md) |
Expand Down
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ default. You decide what additional access to grant.

See a sample of a full graphical IDE running inside DevCapsule's isolated Docker container. More scenario illustrations coming soon.

To record an E2E scenario in your own project, ask your agent to run it with recording
and presentation. `devcapsule presentations guide` provides the installed instructions;
`devcapsule presentations export <new-directory>` supplies the Python/Playwright helpers.
See the [agent recording guide](devcapsule-src/devcapsule/presentation_tools/README.md).

<!-- website:benefits -->
## Why switch to DevCapsule?

Expand Down
89 changes: 89 additions & 0 deletions devcapsule-src/devcapsule/commands/presentations.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
"""Entry points for the packaged agent recording instructions and Python helpers."""
import argparse
from importlib.resources import files
import os
from pathlib import Path
from typing import Mapping

from devcapsule.commands.framework import Command, Group
from devcapsule.compat import CliError
from devcapsule.presentation_authoring import export_tools, presentation_link

__all__ = ["COMMAND"]

PACKAGE = "devcapsule.presentation_tools"
ASSETS = ("__init__.py", "producer.py", "recording.py", "README.md", "example.py")


class GuideCommand(Command):
name = "guide"
help = "Read the agent instructions for English-specified E2E recordings."

@classmethod
def run(cls, arguments: argparse.Namespace, context: object | None) -> int:
print(files(PACKAGE).joinpath("README.md").read_text(encoding="utf-8"))
return 0

Check warning on line 25 in devcapsule-src/devcapsule/commands/presentations.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 24-25 are not covered by tests (advisory).


class ExportCommand(Command):
name = "export"
help = "Export the instructions and standalone Python helpers to a new directory."

@classmethod
def configure(cls, parser: argparse.ArgumentParser) -> None:
parser.add_argument("directory", type=Path, help="New directory; existing directories are preserved.")

Check warning on line 34 in devcapsule-src/devcapsule/commands/presentations.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 34-34 are not covered by tests (advisory).

@classmethod
def run(cls, arguments: argparse.Namespace, context: object | None) -> int:
assets = {name: files(PACKAGE).joinpath(name).read_bytes() for name in ASSETS}
try:
package = export_tools(arguments.directory, assets)
except (OSError, ValueError) as error:
raise CliError(f"cannot export presentation tools: {error}") from error
print(f"Presentation tools: {package}\nAgent instructions: {package / 'README.md'}")
return 0

Check warning on line 44 in devcapsule-src/devcapsule/commands/presentations.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 38-44 are not covered by tests (advisory).


class HandOffCommand(Command):
name = "hand-off"
help = "Print the recorded presentation's console link for the engineer."

@classmethod
def configure(cls, parser: argparse.ArgumentParser) -> None:
parser.add_argument("folder", type=Path)
parser.add_argument("--project", type=Path, help="Console project root; defaults to PROJECT_PATH or cwd.")
parser.add_argument("--console-url", help="Defaults to DEVCAPSULE_CONSOLE_URL.")
parser.add_argument("--token-file", type=Path, help="Defaults to the capsule console token file.")

Check warning on line 56 in devcapsule-src/devcapsule/commands/presentations.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 53-56 are not covered by tests (advisory).

@classmethod
def run(cls, arguments: argparse.Namespace, context: object | None) -> int:
root = (arguments.project or Path(os.environ.get("PROJECT_PATH") or ".")).resolve()
folder = arguments.folder.resolve()
origin = arguments.console_url or os.environ.get("DEVCAPSULE_CONSOLE_URL", "")
token_path = arguments.token_file or Path(os.environ.get("DEVCAPSULE_CONSOLE_TOKEN_FILE") or "/run/devcapsule-console-token")
try:
token = token_path.read_text(encoding="utf-8").strip()
except (OSError, UnicodeError):
token = ""
try:
if not (folder / "presentation.json").is_file():
raise ValueError(f"no presentation.json in {folder}")
link = presentation_link(folder, project=root, console_url=origin, token=token)
except (OSError, ValueError) as error:
raise CliError(str(error)) from error
if not token:
print("Open the console first to establish a browser session; no readable run token was found.")
print(link)
return 0

Check warning on line 77 in devcapsule-src/devcapsule/commands/presentations.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 60-77 are not covered by tests (advisory).


class PresentationsCommand(Group):
name = "presentations"
help = "Record E2E scenarios and make presentations: agent guide, Python toolkit and console link."

@classmethod
def subcommands(cls) -> Mapping[str, type[Command] | type[Group]]:
return {command.name: command for command in (GuideCommand, ExportCommand, HandOffCommand)}

Check warning on line 86 in devcapsule-src/devcapsule/commands/presentations.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 86-86 are not covered by tests (advisory).


COMMAND = PresentationsCommand
47 changes: 47 additions & 0 deletions devcapsule-src/devcapsule/presentation_authoring.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
"""Export the portable authoring kit and form console links from explicit inputs.

Public operations: ``export_tools`` and ``presentation_link``.
"""
from collections.abc import Mapping
from pathlib import Path
from urllib.parse import quote, urlencode, urlsplit, urlunsplit

__all__ = ["export_tools", "presentation_link"]


def export_tools(destination: Path, assets: Mapping[str, bytes]) -> Path:
"""Create a new directory with the supplied kit; never overwrite a prior kit."""
if any(Path(name).name != name or name in ("", ".", "..") for name in assets):
raise ValueError("kit assets must be simple filenames")
destination.mkdir(parents=True, exist_ok=False)
package = destination / "presentation_tools"
package.mkdir()
for name, data in assets.items():
(package / name).write_bytes(data)
return package


def presentation_link(folder: Path, *, project: Path, console_url: str, token: str) -> str:
"""Link a visible descendant of the console project, preserving no URL query.

Paths are absolute and resolved by the caller. The token is optional; without
it the user's browser must already have a console session. Never save a tokened
link in the evidence or project records.
"""
relative = folder.relative_to(project)
if not project.is_absolute() or not relative.parts or any(
part in ("..", "node_modules") or part.startswith(".") for part in relative.parts
):
raise ValueError("presentation must be in a visible subdirectory of the console project")
if not console_url or any(ch.isspace() for ch in console_url):
raise ValueError("supply the capsule's HTTP(S) console URL")
origin = urlsplit(console_url)
try:
_ = origin.port
except ValueError as error:
raise ValueError("supply the capsule's HTTP(S) console URL") from error
if (origin.scheme not in ("http", "https") or not origin.hostname
or origin.username is not None or origin.password is not None):
raise ValueError("supply the capsule's HTTP(S) console URL")
path = "/presentations/" + quote(relative.as_posix(), safe="/")
return urlunsplit((origin.scheme, origin.netloc, path, urlencode({"token": token}) if token else "", ""))
104 changes: 104 additions & 0 deletions devcapsule-src/devcapsule/presentation_tools/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# Run an E2E scenario with recording and presentation

These instructions are for the agent in the engineer's project. Accept the
scenario from the engineer's existing Markdown file or their inline English.
Read it yourself; do not require the engineer to translate it into a schema.
Execute the requested test, check its observations, and give the engineer the
result and a link to the recorded presentation in their DevCapsule web console.

## Get the tools

`devcapsule presentations guide` prints this guide from the installed executable.
No DevCapsule source checkout is needed. Export the supporting Python package:

```sh
devcapsule presentations export /var/tmp/e2e-authoring
```

The destination must be new. It contains `presentation_tools/` with this guide,
the producer, recorder and a runnable example. Add the export directory to
`PYTHONPATH` when running the project's driver. The helpers use only the Python
standard library and the Playwright page you supply. They import no test harness.

Use the capsule's `browser-automation` capability, supplied by the `playwright`
component. Its interpreter is `$DEVCAPSULE_PLAYWRIGHT_PYTHON`, normally
`/opt/playwright/venv/bin/python`, and `$PLAYWRIGHT_BROWSERS_PATH` names its
browser directory. The directory's `ffmpeg-*/ffmpeg-linux` is the video encoder
on Linux. Locate the installed executable and pass its absolute path to the
driver. A full system `ffmpeg` also works. Do not download browsers or change
the capsule configuration silently. If the capability is missing, report it
and use the project's normal configuration/relaunch procedure with the engineer.

## Execute the engineer's scenario

1. Read the supplied scenario and the project's run/test instructions. Identify
the real application URL, required data, actions and observable assertions.
Ask only about a missing decision that prevents executing the test.
2. Export the tools. Adapt `presentation_tools/example.py` into a driver in the
project's normal E2E location. Translate the English into `Script` and
`ScriptStep` values in that driver. The engineer's Markdown stays unchanged.
3. Use ordinary synchronous Playwright operations for this project's UI. A
browser page can be the application itself or the capsule's noVNC desktop
when testing an IDE. The helper does not provision applications, databases
or capsules; use the project's established setup and teardown.
4. Create `Recording` with a **new visible evidence subdirectory beneath the
console's project root**: for example `evidence/login-success/run-001`.
Hidden directories, `node_modules`, paths outside the project, and the project
root itself do not appear in the presentation list. Do not overwrite attempts.
5. Call `recording.action(page, step_number, caption, callback)` around each small
real interaction and its assertions. Step numbers start at 1 and proceed in
order; several actions may belong to one step. Captions describe the action.
The callback can use locators, keyboard/mouse operations and project checks.
Assert expected observations independently of the screenshots; a recording
is evidence of a run, not proof the test passed.
6. Keep `record_video_dir=str(recording.evidence / "raw")` on the Playwright
context. The helper captures bursts before and after each action, following
the existing recorder's sparse-frame approach. Its presentation movie excludes
the agent's thinking pauses; the native video preserves motion during the
action. Split long callbacks into smaller recorded actions when viewers need
to follow intermediate UI states. Neither file is a generated explainer video.
7. Call `recording.finish()` while cleaning up, including after a test assertion
fails. Close the browser context to flush its native video. Keep the failure
exit code. Failed/incomplete runs receive labelled presentations containing
only steps reached. If capture or encoding prevents a deck, report that failure
and preserve the logs; do not claim a presentation exists.

The helper writes `action-log.json`, `scenario-result.json`, JPEG frame data,
the encoded `scenario-video.webm`, `poster.png`, step screenshots and finally
`presentation.json`. Chapters and captions come from the recorded frame counts.
Do not estimate timestamps or hand-edit the manifest to hide a failed step.
The existing webconsole schema and viewer are used unchanged.

## Verify and hand off

Read `scenario-result.json` and the driver's exit status. Open the presentation
in the webconsole with Playwright; check its title, overview, screenshots and
chapter playback, including the last chapter. A failing assertion is a failed
test even when its presentation renders correctly. Report failed and unexecuted
steps explicitly. Keep evidence only under the project's normal retention rules;
avoid committing recordings or captured secrets automatically.

Print the engineer's link with the installed CLI:

```sh
devcapsule presentations hand-off evidence/login-success/run-001 --project "$PROJECT_PATH"
```

Run this from the console project root: a relative evidence folder resolves
from the current working directory, and `--project` supplies the console root
used to form the relative link. It uses `$DEVCAPSULE_CONSOLE_URL` and the
mounted console token; `--console-url` and `--token-file` supply explicit values. Keep tokened links in chat only, never
in a source file, log or committed record. If no token can be read, the link
requires a browser session that already opened the console. If there is no
console URL, report that missing environment input rather than inventing a URL.

Finish the response with the test outcome, any limitation, and the clickable
presentation link. The engineer should not need to reconstruct a path themselves.

## Existing replay scripts

The exported `producer` also supports the existing structured replay format:
`parse_script`, `plan_presentation`, `PresentationPlan.timed` and
`write_presentation`. `plan_for_scenario(scenario, root)` reads the scenario's
script relative to the supplied project directory. This adapter is for agents
with existing structured scripts; it is not an input requirement for engineers.
1 change: 1 addition & 0 deletions devcapsule-src/devcapsule/presentation_tools/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
"""Portable E2E presentation tools; also exported for the Playwright interpreter."""
65 changes: 65 additions & 0 deletions devcapsule-src/devcapsule/presentation_tools/example.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
"""Adapt this two-step browser test to the engineer's English scenario.

Run with the Playwright interpreter, from the exported kit's parent directory:
python -m presentation_tools.example --url http://127.0.0.1:8000 \
--expected-text 'Welcome' --evidence /project/evidence/welcome/run-001 \
--ffmpeg /opt/playwright/browsers/ffmpeg-1011/ffmpeg-linux

The ffmpeg revision above is illustrative; locate the installed encoder.
Public operation: ``main``. All host discovery stays at this entry point.
"""
import argparse
import importlib
from pathlib import Path

Check warning on line 13 in devcapsule-src/devcapsule/presentation_tools/example.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 11-13 are not covered by tests (advisory).

from .producer import Script, ScriptStep
from .recording import Recording

Check warning on line 16 in devcapsule-src/devcapsule/presentation_tools/example.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 15-16 are not covered by tests (advisory).

__all__ = ["main"]

Check warning on line 18 in devcapsule-src/devcapsule/presentation_tools/example.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 18-18 are not covered by tests (advisory).


def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--url", required=True)
parser.add_argument("--expected-text", required=True)
parser.add_argument("--evidence", type=Path, required=True)
parser.add_argument("--ffmpeg", required=True)
args = parser.parse_args()
playwright = importlib.import_module("playwright.sync_api")
script = Script(

Check warning on line 29 in devcapsule-src/devcapsule/presentation_tools/example.py

View workflow job for this annotation

GitHub Actions / Python 3.12

Uncovered changed lines

Changed executable lines 21-29 are not covered by tests (advisory).
goal="Verify the application's welcome page survives a reload.",
stack=(("Browser", "Chromium driven by Playwright"),), illustrates=(),
steps=(
ScriptStep("Open the application", "Navigate to the application.", args.expected_text),
ScriptStep("Reload", "Reload the page.", args.expected_text),
),
)
recording = Recording(args.evidence, script=script, scenario_id="welcome",
title="Welcome page", summary=script.goal, ffmpeg=(args.ffmpeg,))
with playwright.sync_playwright() as runtime:
browser = runtime.chromium.launch(headless=True)
context = browser.new_context(viewport={"width": 1280, "height": 800},
record_video_dir=str(args.evidence / "raw"))
page = context.new_page()

def open_application() -> None:
page.goto(args.url)
playwright.expect(page.get_by_text(args.expected_text, exact=True)).to_be_visible()

def reload_application() -> None:
page.reload()
playwright.expect(page.get_by_text(args.expected_text, exact=True)).to_be_visible()

try:
recording.action(page, 1, "Open the application and check its welcome message", open_application)
recording.action(page, 2, "Reload and check the message remains visible", reload_application)
finally:
try:
recording.finish()
finally:
context.close()
browser.close()


if __name__ == "__main__":
main()
Loading
Loading