agenttwin 0.1.0 → 0.2.1

package/README.md

@@ -1,48 +1,118 @@
-# agenttwin
+# AgentTwin
 
-**Give your agent a test world before it touches the real one.**
+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.
 
-A safe, executable copy of the systems your agent reads from and writes to, so you
-can run the same workflow against a replica, inject real failure conditions, and
-turn a discovered failure into a regression test.
+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.
 
-> **Early preview.** This package is the CLI shell for that vision. `agenttwin init`
-> works today. The runtime commands (`up`, `run`, `fault`, `diff`, `adopt`) are
-> coming soon.
+## Install and discover
 
-## Usage
+Node.js 22+ is required. Run discovery from your project; npx installs the CLI automatically:
 
 ```sh
 npx agenttwin init
+npx agenttwin example --out ./agenttwin-example
 ```
 
-Writes a starter `agenttwin.config.json` into the current directory:
+`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
+
+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
+```
+
+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.
+
+## Use your own E2B account
+
+```sh
+export E2B_API_KEY=your_key
+npx agenttwin setup
+npx agenttwin run --runtime e2b --file agenttwin-example/safe.world.json
+```
+
+`setup` builds a Node 22/PostgreSQL 15/Redis template on E2B and stores its nonsecret ID in `~/.agenttwin/runtime.json`. `E2B_TEMPLATE_ID` overrides that ID. It creates no local Docker containers. Sandboxes are created only for runs. The runtime boundary permits adding another hosted provider later; only E2B is implemented today.
+
+## 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.
+
+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.
+
+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.
+- 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.
+
+## 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.
+
+MIT license.
+
+## Discovery dashboard
+
+`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.
+
+## 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:
 
 ```json
 {
-  "version": 1,
-  "world": "default",
-  "twins": []
+  "schema": "agenttwin/preparation-v1",
+  "workflowId": "YOUR_DISCOVERED_WORKFLOW_ID",
+  "world": {
+    "schema": "agenttwin/world-v1",
+    "name": "notification",
+    "files": ["workflow.mjs"],
+    "command": ["node", "workflow.mjs"],
+    "timeoutSeconds": 20,
+    "services": [{"name":"slack","adapter":"slack","collections":[{"path":"/messages","seed":[]},{"path":"/channels","seed":[{"id":"C_TEST","name":"test"}]}]}],
+    "assertions": [{"service":"slack","path":"/messages","count":1}]
+  },
+  "mappings": [{"toolId":"YOUR_DISCOVERED_SLACK_TOOL_ID","service":"slack","contract":"slack","operations":["chat.postMessage"],"reviewed":true}]
 }
 ```
 
-Re-run with `--force` to overwrite an existing config.
+Use your actual discovered IDs and include every operation recorded for the candidate. Configure code to use the generated `AGENTTWIN_SLACK_URL` and `AGENTTWIN_SLACK_TOKEN`; an SDK needs its base URL overridden. The runtime does not install dependencies or transpile source: include a built, self-contained Node entrypoint and every required application file. Preparation never executes your code.
 
 ```sh
-npx agenttwin --help
-npx agenttwin --version
+npx agenttwin prepare --file preparation.json --out .agenttwin/prepared/notification
+npx agenttwin run --file .agenttwin/prepared/notification/agenttwin.world.json
 ```
 
-## Requirements
+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.
+
+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.
+
+
+### Coding session and dashboard discovery
 
-Node.js 18 or newer.
+Run `npx agenttwin init` inside your repository (Node.js 22+). Interactive init offers an OpenCode session when the CLI is installed; `npx agenttwin init --agent opencode` launches explicitly with your configured provider and its normal permission controls. Provider authentication and usage belong to your coding-agent account. Other coding agents can use `.agenttwin/AGENT-TASK.md`.
 
-## Status
+The session traces workflows across files, records intents and production failure hypotheses in `.agenttwin/WORKFLOWS.md`, and writes metadata to `.agenttwin/agent-discovery.json`. Static candidates retain their original evidence. Agent candidates remain unverified until the workflow is explicitly prepared and executed. Static discovery preserves distinct exported side-effect entrypoints, including repositories with 100 candidates; it does not prove that every business workflow has been found.
 
-`agenttwin init` is the only implemented command. Nothing here connects to real
-providers, requests credentials, or executes code. See the project repository for
-the product thesis and roadmap.
+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.
 
-## License
+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.
 
-MIT
+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.