README.md

# Ample plugin

The plugin connects Codex (and, as a ChatGPT app, ChatGPT on the web and mobile)
to Ample's hosted MCP server at `https://api.ample.computer/mcp` (`.mcp.json`).
The host links the person's Ample account through browser sign-in (OAuth 2.1
with PKCE, `crates/ample-api/src/routes/oauth.rs`); nothing runs on their machine.
Projects reach Ample through workspaces (`ample_workspace_*`), and the panel
(`ui://ample/app`) is served by the same remote server
(`crates/ample-api/src/routes/mcp_app.rs`), which answers its tools directly
from the API. Snapshots from the remote server carry `hosted: true`, so the panel
leaves connection and disconnection to the host.

`npm run build` writes the panel to `dist/app.html` and to
`crates/ample-api/assets/mcp-app.html`, which the API compiles in: commit that
copy with UI changes and deploy the API. `npm run package` writes the remote
plugin (manifest, `.mcp.json`, skills, assets) to `target/ample-desktop-plugin`.

The rest of this document describes the local desktop variant, still built with
`npm run package -- --local`: a stdio server (`.mcp.local.json`) that drives a
private CLI against a local checkout. It requires Node.js 22+ and a desktop
account with the OpenAI MCP Extensions alpha.
The UI contract and vendored SDK are pinned to OpenAI-Early-Access/mcp-extensions
`fbb078073cb6ad0a3c6e8c8ebf3c6abb7fcdef1c` (see vendor/README.md).

## Source and runtime layout

The plugin source is `plugins/ample/` in the Ample repository:

```text
plugins/ample/
├── .codex-plugin/plugin.json  # plugin manifest
├── .mcp.json                  # the remote MCP (default package)
├── .mcp.local.json            # launches node ./dist/server.js (--local)
├── src/app/                   # React panels and host integration
├── src/server/                # local MCP server, entrypoint index.ts
├── scripts/                   # build, packaging, and acceptance checks
├── vendor/                    # pinned alpha SDK
└── dist/                      # generated server, HTML, catalog, and skills
```

Codex launches the bundled `dist/server.js` as a local Node.js process and talks
to it over stdin/stdout. It has no listening port or public MCP endpoint. The
server manages accounts and sessions, reads cloud status, and forwards generated
tools to its private CLI. Both use the Ample API over HTTPS. The existing cloud
control plane remains in `crates/ample-api/`; deployed apps run in Ample's cloud.

Packaging writes `target/ample-desktop-plugin/` relative to the repository root.
The local personal-marketplace source used for this alpha installation is
`~/plugins/ample/`; Codex installs a versioned copy under
`~/.codex/plugins/cache/personal/ample/<plugin-version>/`. These are generated
copies: edit the repository source, then rebuild, package, and reinstall.
Runtime credentials and session state are separate, in `~/.ample-desktop/`.

## Build and package

From the repository root, build the compatible CLI with `cargo build -p ample-cli`.
Then in this directory:

```sh
npm ci
npm run typecheck
npm test
npm run test:ui
npm run build
npm run package -- --local
```

Development packaging includes the locally built CLI, pinned by hash. It works
only on that build's OS/architecture. The result is `target/ample-desktop-plugin`.
Install this directory in a personal development marketplace using the Codex
plugin workflow. Quit/reopen Codex after plugin installation if required by the
alpha host. The plugin creates its own Ample sidebar entry.

For distribution, publish the compatible CLI after its required canaries and
agent journeys, then package using `npm run package -- --local --cli <matching-cli>
--release <published-release.json> --out <output-directory>`. This pins the five
published target checksums. Never distribute a development bundle as a universal
release. Node is a prerequisite; the alpha host does not promise to install it.

## Onboarding and storage

Choose **Try Ample** to explicitly provision the plugin-private CLI and create a
free temporary account. **Keep your apps** opens Ample's email claim flow. The
expiry is read from the account, never extended by renewal. Unknown claim status
from an older API is displayed as unknown, not treated as claimed.

**Use existing Ample account** copies the regular account login from the standard
CLI configuration after verifying identity. It does not modify the original.
Operator credentials are rejected. Settings shows the account ID and owner email
from the authenticated API; unclaimed accounts show “Not added yet.” Older
APIs without the email field show “Unavailable.” Disconnect only removes the plugin login.

Private state lives in `~/.ample-desktop` (Unix directories 0700, files 0600).
`AMPLE_PLUGIN_HOME` may select an isolated directory for development/tests.
Credentials are never included in UI snapshots or model-visible tool results.
The claim link is returned only to the app-only claim tool and opened via the host.

## Deployment flow

The agent calls `ample_ui_begin` with an explicit absolute `project_dir`. The
returned `session_id` is passed to `ample_deploy` or `ample_up` with the same
project directory. Underlying tool schemas come from the pinned CLI; calls travel
through `ample mcp`, retaining its mapping, results, cancellation, and exit codes.

`AMPLE_CONFIG_PATH` selects the private credentials profile. Client credentials
are renewed before API requests. `AMPLE_DEPLOY_EVENTS_FILE` points to a private,
pre-created append-only event file; it carries only stages and resource IDs.
Regular CLI output is unchanged. The panel reads events and cloud status while
the single synchronous deployment runs. An uncertain interrupted run is never
replayed. Read its existing operation; create another session only for an
intentional new deployment or retry.

The plugin's first release has no file handler or direct infrastructure mutation
buttons. App logs are treated as untrusted text, bounded, and attached to model
context only by an explicit user action. Sensitive values known to the plugin and
common credential patterns are redacted; applications should not log secrets.

Attachment status follows the alpha host’s per-instance model-context lifecycle.
“Context attached” appears only when the host reports the selected app attached;
a missing acceptance ID is surfaced as an error. Attachments are not promised
to transfer into a new conversation: @mention Ample there and select the app.

## Verification and current release boundary

Run `node scripts/profile-contract.mjs` against the built candidate to verify CLI
profile isolation and environment precedence. After packaging, run
`node scripts/smoke.mjs` and `node scripts/packaged-ui.mjs` for the stdio resource
contract and the light/dark, narrow/wide accessibility capture matrix.
`node scripts/live.mjs` is an opt-in beta test: it creates a temporary account,
deploys a disposable static app, verifies its content, then deletes that app.
It retains private state on failure for diagnosis. Reusing a directory through
`AMPLE_LIVE_DIR` is deliberately refused: acceptance always provisions its own
fresh account and cleanup deletes only observed deployment IDs after an account
identity check. Do not repeatedly run live trials while diagnosing a failure.

See [VALIDATION.md](VALIDATION.md) for the current evidence and outstanding gates.
The September 25, 2026 alpha release is pinned to published CLI 0.1.23 and its
five-platform checksum manifest. The identity API extension is deployed. The
production-packaged plugin passed real trial setup, private CLI provisioning,
deployment, public-content verification, mentions/resource resolution, and local
server restart recovery. The earlier copied-executable network timeout did not
recur with the release build.

Use a new Codex task after installing an updated plugin. Native Codex
sidebar/keyboard/theme behavior, the actual email claim flow, and Windows/Linux
native plugin acceptance remain to be checked. Automated protocol-host tests do
not establish native desktop acceptance. Distribution remains private to the
alpha audience; there is no public marketplace listing.

Connected users can choose **Finish setup** after an update without disconnecting.
Registration retries keep the original request key; after the recovery window,
starting a new trial requires the explicit **Start a new trial** action. Unclaimed-account disconnection requires an additional warning
and confirmation.

Deployment locks use a refreshed 30-second lease and an atomic one-shot session
marker. Wait for the lease to expire after a killed process, then inspect the
interrupted session. A new deployment always requires a deliberate new session.
Waiting and uncertain panels keep polling at a capped slow interval while visible;
Refresh or panel focus checks again. Trial identity refresh is separate.

## Account states and production preview

The main header identifies Ample and its web app hosting purpose. Disconnected
users see explicit setup actions without CLI implementation details or a Settings
navigation button. Connected users see Your apps and an outlined Settings button.
Unclaimed accounts get the claim prompt after an app is live, or in Settings;
expired accounts also see recovery guidance without needing a live app. The
prompt shows remaining hours and the authoritative expiry timestamp. Claimed
accounts retain identity settings without a claim banner.

Live apps on HTTPS `*.apps.ample.computer` can load in a sandboxed production
preview beside details on wide panels and below details on narrow panels. The
resource CSP permits that hosting domain only. Custom domains and non-live apps
show a fallback; Open app remains available. Embedded pages may block framing,
and loading a preview can wake a sleeping app. Native alpha-host iframe acceptance
remains unverified; automated browser checks are not a substitute.

## App activity

App details show a compact, full-width orange request chart above details and the
production preview. Wide panels keep the preview on the right; narrow panels stack
activity, details, preview, then logs. The time window stays at 24 hours, with 96
15-minute intervals. The vertical scale follows the busiest interval, so even one
request is visible. The total and hover/arrow-key details always show real counts;
zero stays flat. Requests include page assets, bots, and embedded-preview visits,
not unique visitors. A request can wake an app; reading the chart does not.

The app-only `ample_ui_traffic` tool reads the account-authorized
`GET /v1/deployments/:id/traffic` endpoint every 30 seconds while the detail view
is mounted. It does not poll by deploying or calling the public app. Errors show
an unavailable state instead of a misleading zero, and selection changes discard
late responses for the previous app.

The API's `traffic` module independently tails completed Caddy access records,
including retained rotated/gzipped logs. Postgres stores only a deduplication hash,
account/app IDs and timestamp, with 24-hour retention; it does not store URLs,
headers or client IPs. Replay after restart does not double-count. Counts are
best-effort gateway observations: historical logs beyond gateway retention cannot
be recovered after a long outage. New installations say they are still collecting
the first 24 hours. Missing or stale collection returns unavailable. Route
reassignment resets the binding timestamp so previous app traffic is not imported.

Ship the compatible API before installing this UI. No public CLI release is needed
for this read-only app tool. Unit/integration tests cover deduplication, retention,
account/scope isolation, stale collection, and route reassignment. Component and
packaged-browser checks cover sparse/empty/error states, keyboard detail, selection
races, preview placement, light/dark mode, and narrow panels. Actual alpha desktop
acceptance remains a separate manual check.

Traffic release validation: the macOS-compatible Rust baseline passed (497 tests),
the focused traffic and routing integration checks passed, and the plugin passed
57 Vitest tests, 12 Node/package checks, and 32 packaged-browser captures. The live
packaged-plugin journey created its own trial, deployed one static fixture, verified
public content and observed that request in `ample_ui_traffic`, then verified
mentions/restart recovery and deleted only its own observed deployment.

Additional live canaries: Vite deployed and served its expected content, but its
batch reported a cleanup timeout on an older April fixture (`dep_a896e5d6`). The
Next.js sleep/wake fixture exceeded the initial deploy wait and later became live;
reusing that operation (without another deploy) reached the runtime measurement,
but standby was correctly deferred for an established guest connection (409), so
there is no passing sleep/wake result for this release. The newly created Next.js
fixture was deleted successfully after that check. These limitations are separate
from the passing real-request traffic journey above.


## Interface copy

Visible copy explains what users can do with Ample, without describing private
CLI installation, local profiles, or global-login preservation. Setup and
connection errors give a plain-language recovery action. Settings uses “Email
added” and “Not added yet”; the disconnect explanation about local/global logins
is omitted. Trial expiry, account-access loss and incomplete deployment warnings
remain explicit. Technical deployment logs and agent-facing tool contracts retain
the diagnostic details needed to resolve errors.