Skip to content
Closed
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
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,9 @@ and deserialized through a registry.
| `agents/` | The `agents` bundle: the agents agent-env ships, one folder each under `agents/agents/`, with a smoke task each under `agents/tasks/`. Its Claude Code, `@local/agentenv-framework/agents/claude-code`, is the default agent. An agent's Python packages are its folder's `requirements.txt`, installed in its image, never in agent-env's own environment. A run that pulls one of its agents reads the whole bundle, so `tst/unit/bundle/shipped_bundles_test.py` parses and checks every shipped bundle. |
| `computers/` | The `computers` bundle: the base computers agent-env ships as `computer` artifacts, `ubuntu-24.04` (XFCE on Xvfb, settings as `AGENTENV_SETTING_<NAME>`; it starts as root, its container form's `start_as`, whose supervisord, `root.conf`, runs the clock follower as `agentenv-clock` and the session's supervisord as the session user, which runs every session program), and `omarchy-4.5`, a disk alone built on the composing machine from Omarchy's own VM image (its `[forms.disk]` `source`) by `disk/omarchy/`'s recipe, its services systemd user units of the graphical session that start through `with-seed`, booted by the launcher as a `linux-desktop` guest (`env/envs/computer/utils/omarchy_disk.py`, on `thin_disk.py`, which Windows' disks use too), aliased through `[artifacts]`. It has no tasks either. `disk/linux/` is the Linux disk form's recipe: `boot/`, whose Dockerfile makes a disk form (a GPT disk of an EFI system partition holding one UKI, Ubuntu's kernel with a busybox initramfs whose init reads a NoCloud seed and `switch_root`s into the image's entrypoint, and an ext4 root filesystem that is a container image's, plus `/etc/agentenv/vm/image.env` from its OCI config), `tools/`, the disk tools that make it unprivileged on the builder's own platform (`mkfs.ext4 -d`), and `launcher/`, the QEMU launcher that boots one under KVM. A base's `[forms.disk]` with no image is made from its container form; the composer makes each arch's disk from its composed container, keeping the base disk's EFI system partition, keyed by the container's key, the base disk and the recipe; gate 3 probes it where a provider boots disks natively (`disk_image_platforms()`), and a deploy's first boot with KVM probes one left `unverified`; a deploy naming `form = "disk"` boots it through `create_vm(image=..., env=...)`, its settings in the seed. `artifacts/ubuntu-24.04/clock/` is the computer's clock, in the base's folder since an image builds only from its own: agent-env's build of libfaketime 0.9.12 (`libfaketime.patch` and the two `agentenv_clock_*.c` files it includes, GPL-2.0-only as libfaketime is, built by `build.sh` from upstream's sha256-pinned tarball, in a stage of the base's Dockerfile of its own) and the TLS shim, which `/etc/ld.so.preload` loads into every process and which fake only the session user's: clock reads and waits for a set clock time follow the page the follower (`clock-follower`) writes (`clockpage.py`), monotonic and relative waits staying real, with its default settings (`clock.conf`); `tst/clock` gates it. The follower long-polls the gateway's `/clock/watch` under the config core writes through the root channel when a multi env deploys the computer and after a reset (`env/envs/computer/utils/clock.py`), each time waiting on the computer's `sync_time` until it follows, a warning naming why when it doesn't (arming the clock refuses such a computer), and the driver serves `clock/v1` `sync_time` where the follower is (`agentenv_protocol.computer.clock`), not on a disk guest, whose follower core can't reach. |
| `browsers/` | The `browsers` bundle: the website browsers agent-env ships, today `chromium`, a `computer_app` env (Chrome for Testing at the build Playwright pins, for amd64 and arm64, set up for unattended use by managed policies in `/etc/opt/chrome_for_testing/policies/managed`, opened at boot on its `start_urls`, its profile its data). All of it, its pin, install step, policies and command, is in `envs/chromium/chromium.py`; `tst/integration/computer/chromium_app_test.py` runs it. Like `drivers`, it has no tasks. |
| `apps/` | The `apps` bundle: the computer apps agent-env ships, today `libreoffice`, a `computer_app` env (Writer, Impress and Calc from Ubuntu's apt with GTK3 and fonts with Office's metrics, for x11 on amd64 and arm64). Its install step writes `agentenv.xcd` into `/etc/libreoffice/registry/`, a configuration layer under the profile that keeps it from asking anything (no tips, no first-run or version bars, no keep-format question, no lock files, no document recovery), and writes each of LibreOffice's desktop entries into `/usr/local/share/applications/`, opening through its `open.py`, which has the app's server launch it when none runs and then hands the files to that copy (LibreOffice runs one per user), so a file opened by its type, as the file manager does, and every launcher, go to the copy the server stops around a load and a reset; a launch while it runs goes to that copy, starting no other (`_launch_running`). It launches on demand, the Start Center first, ready once a LibreOffice window shows; its data is its profile, which a reset takes back to none. Like `browsers`, it has no tasks; the `office` example uses it. |
| `drivers/` | The `drivers` bundle: the computer drivers agent-env ships as `computer_driver` envs, the reference driver (X11 on Linux, recording through `x11grab`) aliased `reference`, the page driver aliased `page`, a browser computer's, whose screen is the browser's active tab and which serves Playwright MCP's `browser_*` tools beside `computer_*` from a Playwright MCP it runs attached to the browser over a CDP address the relay issues it (`browser_evaluate` and `browser_run_code_unsafe` hidden by default; each call an entry in the browser's log, begun and ended with `browser/v1` `calls/begin` and `calls/end`, that its CDP commands name as `for`; `scripts/upgrade_playwright_mcp.py` pins its version), and trycua's cua-driver aliased `cua-driver` (its daemon from the pinned PyPI wheel, its own instructions, tools and skill resources served to agents through `@server_instructions`, `forwarded_tools` and `@resource`, its tools beside `computer_*`, `computer/v1` on its desktop-scope calls, its skill pack leading the computer skill; `tst/integration/computer/cua_driver_test.py` runs it). It has no tasks: a bundle with neither tasks nor evals is refused unless its `aliases.toml` names something for other bundles to use. The shipped `desktop` example composes it with the `ubuntu-24.04` base into a computer env, which `tst/integration/computer/` deploys, probes, records and has an agent use. |
| `examples/` | The example bundles agent-env ships (`hello`, and `echo-mcp`, which needs Docker, and `desktop`, a computer env of `ubuntu-24.04` and `reference` with a probe task and an agent task). Tests run them, but they are examples for users, not fixtures. Every shipped bundle is registered under `agent_env.bundles` in `pyproject.toml`, `<name> = "<package>"` shipping `src/<package as a path>/<name>/`. |
| `examples/` | The example bundles agent-env ships (`hello`, and `echo-mcp`, which needs Docker, and `desktop`, a computer env of `ubuntu-24.04` and `reference` with a probe task and an agent task, and `office`, the same with the `apps` bundle's `libreoffice`, whose agent task writes a .docx and a .pptx with an animation). Tests run them, but they are examples for users, not fixtures. Every shipped bundle is registered under `agent_env.bundles` in `pyproject.toml`, `<name> = "<package>"` shipping `src/<package as a path>/<name>/`. |

### Training helpers

Expand Down
2 changes: 2 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,7 @@ agent-env = "agent_env.cli:cli"

[project.entry-points."agent_env.bundles"]
agents = "agent_env"
apps = "agent_env"
browsers = "agent_env"
computers = "agent_env"
drivers = "agent_env"
Expand All @@ -190,6 +191,7 @@ hello = "agent_env.examples"
echo-mcp = "agent_env.examples"
mail-mcp = "agent_env.examples"
next-env-event = "agent_env.examples"
office = "agent_env.examples"
advance-to-next-event = "agent_env.examples"

[project.urls]
Expand Down
28 changes: 28 additions & 0 deletions src/agent_env/apps/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
The computer apps that come with agent-env, today `libreoffice`, a `computer_app` env a computer env lists in its
`apps`. Name it from another bundle as `libreoffice`, the alias `aliases.toml` gives it, or by its id,
`@local/agentenv-framework/apps/libreoffice`.

`envs/libreoffice/` is LibreOffice for an X11 desktop on Linux (`amd64` and `arm64`): Writer, Impress and Calc from
Ubuntu's apt, with the GTK3 interface, at the versions a put's package lock pins, and fonts with the metrics of
Office's, Carlito for Calibri, Caladea for Cambria and Liberation for Arial, Times New Roman and Courier New, so Office
files keep their layout.

- **Unattended use:** its install step writes `agentenv.xcd` into `/etc/libreoffice/registry/`, a layer of LibreOffice's
configuration under the session user's profile: no tip of the day, no first-run, new-version, "Get involved" or
donation bar, no question whether to keep an Office format on save, no lock files beside documents, and no document
recovery after the app was stopped around a load or a reset.
- **Launch:** on demand, through its server, the Start Center first (`soffice --nologo`), ready once a LibreOffice
window shows. Every LibreOffice launcher on the computer runs `open.py`: the install step writes each of LibreOffice's
desktop entries into `/usr/local/share/applications/`, which takes precedence, the same but for that. With no copy
running, `open.py` has the server launch one and waits until it's ready, then hands the files to it, as LibreOffice
runs one copy per user, so the server starts every copy and a load or a reset can stop it. A file the file manager or
`exo-open` opens goes there by its type: a .docx, .doc, .odt or .rtf to Writer, a .pptx, .ppt or .odp to Impress, an
.xlsx, .xls, .ods or .csv to Calc, a CSV comma-separated in UTF-8 with no import dialog. A launch while it runs goes
to the copy that runs, as one of LibreOffice's own does, starting no other.
- **Data:** its profile, `~/.config/libreoffice`, which the image has none of, so each deploy and each reset starts with
a clean one, under the same defaults. Documents are the computer's own, in Documents and Downloads.
- **Skill:** `SKILL.md`, for an agent working through its windows: opening each app, saving in Office formats, slides,
animations and formulas.

The `office` example's desktop composes it with the `ubuntu-24.04` base and the `reference` driver, and
`tst/integration/computer/libreoffice_app_test.py` deploys it.
3 changes: 3 additions & 0 deletions src/agent_env/apps/aliases.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Ids a computer env's apps, or a task, can name these apps by; a store's env of the id wins over an alias.
[envs]
libreoffice = ["libreoffice"]
48 changes: 48 additions & 0 deletions src/agent_env/apps/envs/libreoffice/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
description: Write documents, presentations and spreadsheets in LibreOffice on this computer, and save them in Office formats.
---
# LibreOffice on this computer

LibreOffice Writer (documents), Impress (presentations) and Calc (spreadsheets) are installed, with fonts that match
Office's (Carlito for Calibri, Caladea for Cambria, Liberation for Arial, Times New Roman and Courier New). It asks
nothing when it starts and keeps no lock files beside documents.

## Opening

- **A file:** double-click it in the file manager, for instance in Documents or Downloads. A .docx, .doc, .odt or .rtf
opens in Writer; a .pptx, .ppt or .odp in Impress; an .xlsx, .xls, .ods or .csv in Calc. A CSV opens as
comma-separated UTF-8, with no import dialog.
- **Something new:** Applications menu > Office > LibreOffice Writer, Impress or Calc. LibreOffice alone opens the Start
Center, where Writer Document, Impress Presentation and Calc Spreadsheet each start a new file.

## Saving in Office formats

- **File > Save As** (Ctrl+Shift+S). Choose the type in the dialog's file type list, "Word 2007–365 (.docx)",
"PowerPoint 2007–365 (.pptx)" or "Excel 2007–365 (.xlsx)", type the name, and press Save. It saves in that format
without asking whether to keep it.
- **Ctrl+S** saves a file opened in an Office format in that format. A new file's first Ctrl+S opens Save As.
- Save into Documents unless you're told where.

## Writer

- Headings: the paragraph style box on the toolbar, or Ctrl+1 and Ctrl+2; body text is Ctrl+0.
- Bold, italic and underline: Ctrl+B, Ctrl+I, Ctrl+U. Lists: the bullet and numbering buttons on the toolbar.
- A table: Table > Insert Table (Ctrl+F12).

## Impress

- A new slide: Slide > New Slide (Ctrl+M). Its layout: the sidebar's Properties deck, Layouts.
- Click a placeholder to type its title or text.
- **An animation:** click the object to select it, open View > Animation, press the + button (Add Effect) and pick an
effect, for instance Entrance > Appear or Fade In. A slide's transition is Slide > Slide Transition.
- The slideshow: F5; Esc leaves it.

## Calc

- Type in a cell and press Enter or Tab. A formula starts with =, for instance =SUM(B2:B10).
- Ctrl+Home goes to A1.

## When something's in the way

- A dialog waits for an answer; Esc closes most.
- A window you can't see is in the panel's window list at the top of the screen.
31 changes: 31 additions & 0 deletions src/agent_env/apps/envs/libreoffice/agentenv.xcd
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- agentenv's defaults for LibreOffice on a computer, a layer of its configuration (/etc/libreoffice/registry/) under
the session user's profile, so every profile starts with them, a reset's fresh one too. They keep it from asking
anything an agent didn't: no tip of the day, no first-run or new-version bar, no "Get involved" or donation bar,
no "keep current format" question when it saves in Office's formats, no lock files beside documents (a computer has
one user, and a stopped app's would ask "Document in use" next time), and no document recovery after the app was
stopped around a load or a reset. -->
<oor:data xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:oor="http://openoffice.org/2001/registry">
<dependency file="main"/>
<oor:component-data oor:name="Common" oor:package="org.openoffice.Office">
<node oor:name="Misc">
<prop oor:name="ShowTipOfTheDay" oor:op="fuse"><value>false</value></prop>
<prop oor:name="FirstRun" oor:op="fuse"><value>false</value></prop>
<prop oor:name="UseLocking" oor:op="fuse"><value>false</value></prop>
<prop oor:name="UseDocumentOOoLockFile" oor:op="fuse"><value>false</value></prop>
<prop oor:name="UseDocumentSystemFileLocking" oor:op="fuse"><value>false</value></prop>
</node>
<node oor:name="Save"><node oor:name="Document"><prop oor:name="WarnAlienFormat" oor:op="fuse"><value>false</value></prop></node></node>
</oor:component-data>
<oor:component-data oor:name="Setup" oor:package="org.openoffice">
<node oor:name="Product">
<prop oor:name="ooSetupLastVersion" oor:op="fuse"><value>24.2</value></prop>
<prop oor:name="LastTimeGetInvolvedShown" oor:op="fuse"><value>4102444800</value></prop>
<prop oor:name="LastTimeDonateShown" oor:op="fuse"><value>4102444800</value></prop>
</node>
</oor:component-data>
<oor:component-data oor:name="Recovery" oor:package="org.openoffice.Office">
<node oor:name="RecoveryInfo"><prop oor:name="Enabled" oor:op="fuse"><value>false</value></prop></node>
<node oor:name="AutoSave"><prop oor:name="Enabled" oor:op="fuse"><value>false</value></prop></node>
</oor:component-data>
</oor:data>
4 changes: 4 additions & 0 deletions src/agent_env/apps/envs/libreoffice/env.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
type = "computer_app"
module = "libreoffice.py:LibreOffice"
computer = "ubuntu-24.04"
driver = "reference"
Loading
Loading