agenttwin 0.2.2 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # AgentTwin
 
-Discover a project's dependencies, then run an explicitly configured Node workflow in a fresh hosted sandbox with stateful service adapters, faults and final-state checks.
+Discover a project's dependencies, then test an explicitly configured Node workflow through the CLI with stateful service adapters, faults and final-state checks.
 
-AgentTwin 0.2.0 executes application code in E2B. No local application containers are required. The E2B key belongs to the runtime operator; users of the hosted API receive separate revocable AgentTwin tokens.
+The default runner executes reviewed bundled Node code on your computer, with fresh in-process HTTP twins. No VM or containers are needed. Select a cloud runner explicitly when a workflow needs one. The E2B key belongs to the runtime operator; users of the hosted API receive separate revocable AgentTwin tokens.
 
 ## Install and discover
 
@@ -15,20 +15,29 @@ npx agenttwin example --out ./agenttwin-example
 
 `init` writes the inventory, workflow candidates, `agenttwin.config.json`, `ENVIRONMENT.md`, `REPLICATION.md`, and an offline browser report. Discovery is evidence, not an automatically executable environment. It never uploads source. `init --json --dry-run` writes nothing.
 
-## Run through an AgentTwin API
+## Test through the CLI
+
+```sh
+npx agenttwin run --file path/to/agenttwin.world.json
+npx agenttwin sync
+```
+
+Run from your original repository so receipts stay in its `.agenttwin/runs/` directory. Local execution currently supports bundled Node workflows with HTTP collections and bounded Slack operations. It stages the listed files, passes only generated twin credentials, and records assertions, faults, events and Git metadata. It is a process on your computer, not a filesystem or network isolation boundary. PostgreSQL/Redis worlds require explicit cloud execution. Review recorded output and synthetic state before syncing.
+
+## Optional cloud execution through an AgentTwin API
 
 Your operator supplies the API URL and your individual token:
 
 ```sh
 export AGENTTWIN_API_URL=https://your-agenttwin-api.example.com
 export AGENTTWIN_TOKEN=your_individual_token
-npx agenttwin run --file agenttwin-example/agenttwin.world.json
-npx agenttwin run --file agenttwin-example/safe.world.json
+npx agenttwin run --runtime hosted --file agenttwin-example/agenttwin.world.json
+npx agenttwin run --runtime hosted --file agenttwin-example/safe.world.json
 ```
 
 The first run should fail: a write commits but its response is delayed, and an unsafe retry creates two tickets. The safe version reuses an idempotency key and passes. Both execute real application code against a custom ticket API and a bounded Slack adapter. Every run starts from fresh seeds and credentials, then deletes its sandbox. These are examples you can replace, not a refund-specific product.
 
-`run --json` emits a receipt with source/spec hashes, application output, ordered service events, initial/final service state, assertions, fault activation and sandbox metadata. Evidence stays in `.agenttwin/runs/`. Exit codes: 0 passed; 1 failed/error; 2 incomplete/blocked; 3 invalid input. An unsupported adapter operation or an untriggered requested fault makes the run incomplete.
+`run --json` emits a receipt with source/spec hashes, application output, ordered service events, initial/final service state, assertions, fault activation, runner details and Git metadata when available. Evidence stays in `.agenttwin/runs/`. Exit codes: 0 passed; 1 failed/error; 2 incomplete/blocked; 3 invalid input. An unsupported adapter operation or an untriggered requested fault makes the run incomplete.
 
 ## Use your own E2B account
 
@@ -42,7 +51,7 @@ npx agenttwin run --runtime e2b --file agenttwin-example/safe.world.json
 
 ## Run your code
 
-Edit a world JSON file, listing only the built application files to upload. Bundle npm dependencies before the run; the sandbox has no outbound internet and performs no npm install. `command` is an argv array starting with `node`; the app runs as uid 1000. A world file resolves its application files relative to its own directory. Optional `workflowId` links to a workflow in the current discovery inventory.
+Edit a world JSON file, listing only the built application files to upload. Bundle npm dependencies before the run. Cloud sandboxes have no outbound internet and perform no npm install; local runs use the host network. `command` is an argv array starting with `node`; cloud apps run as uid 1000. A world file resolves its application files relative to its own directory. Optional `workflowId` links to a workflow in the current discovery inventory.
 
 Use the generated `AGENTTWIN_<SERVICE>_URL` and `AGENTTWIN_<SERVICE>_TOKEN` values to configure your test clients. Production accounts, OAuth sessions, `.env` files and host credentials are not copied. Tokens and service state are fresh per run. Source files may contain hardcoded secrets; review the explicit upload list and bundle before uploading it.
 
@@ -50,19 +59,19 @@ Supported now:
 
 - Generic JSON collections: GET/list, POST/create, seed records, bearer authentication and same-key idempotency replay/conflict. This is a custom API contract, not a CRM vendor clone.
 - Slack subset: `chat.postMessage` with channel/text, `conversations.list` without parameters, `conversations.history` with channel. JSON and form POSTs are supported; reads also accept GET. Unknown methods or parameters fail visibly. OAuth, pagination, threads, files and complete SDK/provider parity are not supported.
-- Real PostgreSQL 15: optional seed SQL, generated `DATABASE_URL`, read-only SELECT final-state assertions.
-- Real Redis: generated `REDIS_URL`/`REDISCLI_AUTH`, string-key final-state assertions.
+- Cloud runner: real PostgreSQL 15: optional seed SQL, generated `DATABASE_URL`, read-only SELECT final-state assertions.
+- Cloud runner: real Redis: generated `REDIS_URL`/`REDISCLI_AUTH`, string-key final-state assertions.
 - One fault: a committed HTTP write followed by a delayed response. State count/filter assertions, DB rows and Redis values can verify side effects.
 
 There is no automatic cloning of arbitrary software, provider account provisioning, complete vendor catalog, browser workflow runtime, coordinated snapshots, replay of LLM responses or automatic regression-code generation. Receipts verify the configured assertions, not complete production equivalence or adversarial program correctness.
 
 ## Discovery and reports
 
-`discover`, `decide`, `plan`, `status`, `inspect`, `grant`, `schema`, `export`, `report`, and `feedback` remain available. `--json` sends results to stdout and logs to stderr. Discovery inspects files and bounded commands; remote reads require scoped grants. `--probe` explicitly requests provider reads. Local application observation and the legacy refund `demo/trial/check/reset` commands are retired in the public CLI; use hosted `run` instead. Development unit tests still exercise adapter code locally.
+`discover`, `decide`, `plan`, `status`, `inspect`, `grant`, `schema`, `export`, `report`, and `feedback` remain available. `--json` sends results to stdout and logs to stderr. Discovery inspects files and bounded commands; remote reads require scoped grants. `--probe` explicitly requests provider reads. Local application observation and the legacy refund `demo/trial/check/reset` commands are retired in the public CLI; use `run` instead. Development unit tests still exercise adapter code locally.
 
 ## Operate the API
 
-The package includes `dist/gateway.js`. Deploy it on a server with Node 22+, HTTPS ingress and persistent disk. See the repository's `docs/HOSTED-RUNTIME.md` for deployment, accounts, limits and operational boundaries. The gateway is a control plane; applications execute in separate E2B sandboxes.
+The package includes `dist/gateway.js`. Deploy it on a server with Node 22.12+, HTTPS ingress and persistent disk. See the repository's `docs/HOSTED-RUNTIME.md` for deployment, accounts, limits and operational boundaries. The gateway stores synced discovery and CLI results, serves chat, and can optionally dispatch cloud jobs. It starts without E2B credentials; cloud submissions then return a clear unavailable response. Applications submitted for cloud execution run in separate E2B sandboxes.
 
 MIT license.
 
@@ -70,11 +79,11 @@ MIT license.
 
 `agenttwin init --yes` detects project dependencies, tooling and available connector configuration, then writes `.agenttwin/dashboard/index.html`. Open that file to review the detected environment without selecting every connector or uploading inventory. The dashboard includes its assets and an allowlisted discovery payload; account records, credential values and evidence paths are excluded. It starts with no saved run receipts. Detection does not verify provider access or implement an adapter.
 
-For this repository’s website preview (`python3 serve.py 4173`), the dashboard automatically loads the latest handoff from init every five seconds while visible. Other projects use their generated dashboard or the manual discovery import. No inventory is uploaded to a hosted website automatically. Removed detected resources stay excluded until a fresh init scan.
+The website starts empty and does not import this repository’s inventory automatically. Connect your individual API account in Settings and run `npx agenttwin sync` with `AGENTTWIN_TOKEN` configured, or import discovery JSON manually. Removed detected resources stay excluded until a fresh discovery revision. The generated project dashboard loads its own embedded discovery.
 
 ## Prepare an actual discovered workflow
 
-After `init`, select a candidate from `.agenttwin/inventory.json` or the dashboard's New world view. Write `preparation.json` beside your application files:
+After `init`, select a candidate from `.agenttwin/inventory.json` or the dashboard's Workflows view. Write `preparation.json` beside your application files:
 
 ```json
 {
@@ -100,7 +109,7 @@ npx agenttwin prepare --file preparation.json --out .agenttwin/prepared/notifica
 npx agenttwin run --file .agenttwin/prepared/notification/agenttwin.world.json
 ```
 
-The output contains your unchanged source, a world spec, a SHA-256 manifest, and `agenttwin.bundle.json`. In Hosted runs, connect with an individual API token, choose that bundle, review the upload and execute. Jobs can be refreshed, cancelled and inspected. Tokens stay in page memory. Discovery imports remain in the browser; executing uploads the explicit bundle to the API.
+The output contains your unchanged source, a world spec, a SHA-256 manifest, and `agenttwin.bundle.json`. In Workflows, connect with an individual API token through Settings, choose that bundle, review the upload and execute. Runs lists jobs for refresh, cancellation and inspection. Tokens stay in page memory. Discovery imports remain in the browser; executing uploads the explicit bundle to the API.
 
 Supported mapping contracts: bounded Slack operations, PostgreSQL, Redis and custom JSON collections (`GET /path` / `POST /path`). Preparation rejects missing/unreviewed mappings and unsupported vendor SDK operations. Discovery and mappings remain user-reviewed declarations, not proof that every operation or dependency in arbitrary source was discovered. Hosted execution checks the declared assertions.
 
@@ -113,6 +122,13 @@ The session traces workflows across files, records intents and production failur
 
 After reviewing discovery, configure `AGENTTWIN_TOKEN` using your individual account token (never paste it into an agent prompt) and run `npx agenttwin sync`. Optional `AGENTTWIN_API_URL` selects your API. The website loads account discovery after you connect in Settings, then refreshes while visible. Sync sends names, operations and relative entrypoint metadata; application source uploads happen separately through reviewed bundles. Avoid sensitive names or identifiers in discovery metadata.
 
-To execute a workflow, supply an executable Node entrypoint, reviewed supported dependency mappings, synthetic fixtures and expected observable outcomes. Run `npx agenttwin prepare --file preparation.json`, review the bundle, and run it through your AgentTwin API or E2B account. Browser/desktop automation and arbitrary vendor SDKs require additional runtimes/adapters. Every application execution is hosted; no local Docker is used.
+To execute a workflow, supply an executable Node entrypoint, reviewed supported dependency mappings, synthetic fixtures and expected observable outcomes. Run `npx agenttwin prepare --file preparation.json`, review the bundle, and run it through your AgentTwin API or E2B account. Browser/desktop automation and arbitrary vendor SDKs require additional runtimes/adapters. The CLI is the default runner; select a hosted runner only when the workflow requires it. No local Docker is used.
 
 A run receipt's **Fix & retest** tab exports an evidence-based task for your coding agent. Edit the code in the original project, prepare a new bundle, execute in a fresh sandbox, and compare receipts. This is an interactive coding loop, not an unattended universal repair service.
+
+
+### Dashboard settings and account controls
+
+The website’s Settings page saves workspace name, default execution limit (1–300 seconds for new templates), automatic refresh, compact lists and reduced motion in this browser. Existing reviewed bundles retain their limits. The account section supports token visibility, connection status, manual workspace refresh and disconnect; tokens are never persisted with preferences.
+
+Top-right initials open account actions. The sidebar closes into a full-width layout. See `docs-site/src/dashboard.mdx` for the complete guide. The website/API UI has received additional fixes after npm 0.2.2; the published package remains 0.2.2.