archal 0.9.14 → 0.9.16

package/README.md

@@ -1,27 +1,19 @@
 # archal
 
-Pre-deployment testing for AI agents via Archal's hosted digital twins,
-including route-mode twins for Discord, GitHub, Slack, Stripe, Linear, Jira,
-Ramp, Supabase, and Google Workspace.
+Pre-deployment testing for AI agents via Archal's hosted service clones,
+including route-mode clones for Discord, GitHub, Slack, Stripe, Linear, Jira,
+Ramp, Apify, Tavily, Supabase, and Google Workspace.
 
-## Early access — expect rough edges
+## Known compatibility notes
 
-`archal@0.9.x` is early access. The CLI and twins work, but the surface is
-still being polished:
+- `npm install -g archal` may print peer-dependency warnings from the
+  vendored CLI runtime. These are safe to ignore; all required modules
+  are bundled.
+- The `vitest` integration under `archal/vitest` requires `vitest@^2.1.0`.
+  Projects on vitest 3 should pin a workspace to vitest 2 for Archal tests
+  to avoid duplicate module resolution.
 
-- `npm install -g archal` prints a handful of peer-dependency warnings
-  from the vendored CLI runtime. They are safe to ignore; nothing is
-  missing at runtime.
-- A few commands still print one or two help lines to `stderr` instead of
-  `stdout`. Scripts that redirect streams will mostly see what they expect,
-  but be aware of it.
-- The `vitest` integration under `archal/vitest` depends on `vitest@^2.1.0`.
-  If your project is on vitest 3, the shared helper may resolve the wrong
-  copy. Pinning a workspace to vitest 2 for your Archal tests fixes it.
-
-We're shipping `0.9.x` so that early users can start running the CLI against
-hosted twins. File anything surprising at
-<https://github.com/Archal-Labs/archal/issues>.
+File issues at <https://github.com/Archal-Labs/archal/issues>.
 
 ## Install
 
@@ -36,13 +28,20 @@ archal login
 ```
 
 This writes credentials to `~/.archal/credentials.json`. You can also set
-`ARCHAL_TOKEN` directly in CI.
+`ARCHAL_TOKEN` directly in CI. Use a workspace API key (`archal_ws_...`) for
+CI instead of a personal token.
+
+Workspace API keys are runtime and CI credentials bound to one workspace. They
+can run clones, upload and read traces, and read usage for that workspace. They
+cannot manage audit events or workspace API keys. Use an owner/admin user
+credential, either `archal login` or a dashboard-issued user API key, for
+workspace administration.
 
-## CLI — primary use case
+## CLI
 
-The CLI is the primary way to use Archal today. `archal run` executes a
+The CLI is the primary interface. `archal run` executes a
 scenario (a markdown file describing a task, the expected behavior, and
-success criteria) against a hosted twin session and reports a satisfaction
+success criteria) against a hosted clone session and reports a satisfaction
 score.
 
 ### Quick start
@@ -51,35 +50,40 @@ score.
 # 1. Log in
 archal login
 
-# 2. Browse the twin catalog
-archal twin
+# 2. Initialize your project
+archal init
 
-# 3. Start a persistent session with one or more twins
-archal twin start github stripe
+# 3. Edit .archal/harness.mjs to call your agent
 
-# 4. Run a scenario from .archal.json in the current directory
+# 4. Run the starter scenario from .archal.json
 archal run
-
-# 5. When you're done
-archal twin stop
 ```
 
-`archal run` auto-discovers an `.archal.json` at the project root. A
-minimal config looks like this:
+`archal init` creates `.archal.json`, `.archal/harness.mjs`, and
+`scenarios/first-run.md`. The generated harness is a guarded stub: Archal
+refuses to run it until you edit the file to call your real agent, so a first
+run cannot be scored from placeholder text.
+
+`archal run` auto-discovers an `.archal.json` at the project root. A minimal
+config looks like this:
 
 ```json
 {
-  "scenarios": "./scenarios",
-  "twins": ["github", "stripe"],
+  "agent": {
+    "command": "node",
+    "args": [".archal/harness.mjs"]
+  },
+  "scenarios": ["scenarios/first-run.md"],
+  "clones": ["github", "stripe"],
   "runs": 1
 }
 ```
 
-### Supported twins
+### Supported clones
 
-`archal twin` lists the nine twins available today:
+`archal clone` lists the eleven clones available today:
 
-| Twin | Notes |
+| Clone | Notes |
 |---|---|
 | Discord | Guilds, channels, messages, members |
 | GitHub | Repos, issues, PRs, labels, reviews |
@@ -88,6 +92,8 @@ minimal config looks like this:
 | Linear | Teams, issues, projects, cycles |
 | Jira | Projects, issues, workflows, components |
 | Ramp | Cards, transactions, reimbursements, users |
+| Apify | Actors, tasks, runs, datasets |
+| Tavily | Search and extraction responses |
 | Supabase | Auth, Postgres, storage, edge functions |
 | Google Workspace | Gmail, Drive, Calendar, Docs, People |
 
@@ -97,34 +103,36 @@ minimal config looks like this:
 |---|---|
 | `archal login` | Authenticate with Archal |
 | `archal logout` | Remove stored credentials |
-| `archal twin` | Browse the twin catalog |
-| `archal twin start [twins...]` | Start a hosted twin session |
-| `archal twin status` | Inspect the active session |
-| `archal twin stop` | Stop the active session |
-| `archal twin list` | List all your active sessions |
-| `archal twin attach <uuid>` | Reattach to a session by id |
-| `archal twin renew <seconds>` | Extend the session lifetime |
-| `archal twin reset` | Reset twin state without tearing down the session |
-| `archal twin seed <twin> <name>` | Load a named seed into a running twin |
-| `archal run [.archal.json]` | Run scenarios from a config file |
+| `archal clone` | Browse the clone catalog |
+| `archal clone start [clones...]` | Start a hosted clone session |
+| `archal clone status` | Inspect the active session |
+| `archal clone stop` | Stop the active session |
+| `archal clone list` | List all your active sessions |
+| `archal clone attach <uuid>` | Reattach to a session by id |
+| `archal clone renew <seconds>` | Extend the session lifetime |
+| `archal clone reset` | Reset clone state without tearing down the session |
+| `archal clone seed <clone> <name>` | Load a named seed into a running clone |
+| `archal run [scenario]` | Run a scenario file (or use `--config` for `.archal.json`) |
 | `archal scenario list` | Browse local and hosted scenarios |
-| `archal seed list [twin]` | List prebuilt twin seeds |
+| `archal seed list [clone]` | List prebuilt clone seeds |
 | `archal trace` | View recent scenario traces |
 | `archal trace <name>` | View trace details for a run |
-| `archal usage` | Check session minutes and plan |
+| `archal usage` | Check active workspace session-minutes and plan |
 
 Run `archal <command> --help` for flag details.
 
 ## Vitest integration (secondary use case)
 
 You can also import `archal/vitest` to route SDK traffic from a vitest
-suite through a hosted twin, with no code changes to your production
+suite through a hosted clone, with no code changes to your production
 code. This is useful if you want to test the HTTP side of an integration
 without hitting real provider APIs.
 
-> Note: the vitest helper is still evolving. If you're just getting
-> started with Archal, prefer the CLI flow above — it's the best-tested
-> path today.
+> The vitest helper supports the hosted route-mode clone catalog: Apify,
+> Discord, GitHub, Google Workspace, Jira, Linear, Ramp, Slack, Stripe,
+> Supabase, and Tavily.
+> If you only need scenario-level evaluation, the CLI flow above is
+> simpler to set up.
 
 ### Minimal config
 
@@ -158,7 +166,7 @@ import Stripe from 'stripe';
 
 it('creates a customer', async () => {
   const stripe = new Stripe('sk_test_fake');        // fake key is fine
-  const customer = await stripe.customers.create({  // goes to twin, not real Stripe
+  const customer = await stripe.customers.create({  // goes to clone, not real Stripe
     email: 'test@example.com',
   });
   expect(customer.id).toMatch(/^cus_/);
@@ -169,18 +177,18 @@ it('creates a customer', async () => {
 
 ```ts
 import { beforeEach } from 'vitest';
-import { resetArchalTwins } from 'archal/vitest';
+import { resetArchalClones } from 'archal/vitest';
 
 beforeEach(async () => {
-  await resetArchalTwins();
+  await resetArchalClones();
 });
 ```
 
 ### Webhook testing
 
-The hosted twin runs in AWS ECS, so it can't POST to your localhost.
+The hosted clone runs in AWS ECS, so it can't POST to your localhost.
 Instead, your test pulls queued deliveries with `waitForArchalWebhook()`
-and invokes your handler directly with the exact payload the twin would
+and invokes your handler directly with the exact payload the clone would
 have sent.
 
 ```ts
@@ -192,7 +200,7 @@ import { handleStripeWebhook } from './src/webhooks';
 const stripe = new Stripe('sk_test_fake');
 
 it('records a subscription when customer.subscription.created fires', async () => {
-  // 1. Register a webhook endpoint — the twin needs to know what events to queue
+  // 1. Register a webhook endpoint (the clone needs to know what events to queue)
   await stripe.webhookEndpoints.create({
     url: 'http://test.local/stripe-wh',
     enabled_events: ['customer.subscription.created'],
@@ -223,7 +231,7 @@ it('records a subscription when customer.subscription.created fires', async () =
 | Slack | ✅ | Receiver-side signature only |
 | Jira | ✅ | Delivered via history buffer (also POSTed to registered URLs) |
 | Linear | ✅ | Delivered via history buffer (also POSTed to registered URLs) |
-| Supabase | ❌ | Database-triggered — test against real Postgres |
+| Supabase | ❌ | Database-triggered; test against real Postgres |
 | Google Workspace | ❌ | GCP Pub/Sub push notifications, not webhooks |
 
 **Parallel workers caveat**: `waitForArchalWebhook()` consumes deliveries
@@ -233,18 +241,18 @@ depend on webhook events, set `testIsolation: 'serial'` in your config.
 
 ### Test isolation across parallel workers
 
-Each vitest worker is routed to its own per-worker state on the twin —
-parallel tests across workers don't see each other's writes. The
+Each vitest worker is routed to its own per-worker state on the clone,
+so parallel tests across workers don't see each other's writes. The
 integration reads `VITEST_WORKER_ID` in each worker process and tags
-every outbound SDK request with an `X-Archal-Worker-Id` header. The twin
+every outbound SDK request with an `X-Archal-Worker-Id` header. The clone
 maintains a separate state engine per worker id, seeded from the
 baseline on first request.
 
-**Isolation-enabled twins**: Stripe, GitHub, Slack, Jira, Linear.
+**Isolation-enabled clones**: Stripe, GitHub, Slack, Jira, Linear.
 
-**Twins without isolation** (Supabase, Google Workspace, Ramp) fall back
+**Clones without isolation** (Supabase, Google Workspace, Ramp) fall back
 to shared state. If your tests depend on global assertions against those
-twins, set `testIsolation: 'serial'`.
+clones, set `testIsolation: 'serial'`.
 
 ## Authentication
 
@@ -255,8 +263,8 @@ In priority order:
 
 This auth is only for Archal's hosted session provisioning. Your app's
 provider credentials do not need to be real when traffic is routed through
-a twin — use placeholder tokens that satisfy the SDK's local validation
-rules, such as `sk_test_fake`, `ghp_fake_token_for_twin`, or a dummy
+a clone. Use placeholder tokens that satisfy the SDK's local validation
+rules, such as `sk_test_fake`, `ghp_fake_token_for_clone`, or a dummy
 Google bearer token.
 
 ## What you'll see in the terminal
@@ -266,18 +274,18 @@ On the first `archal run`, session provisioning takes about 30 seconds
 the wait is visible:
 
 ```
-[archal] provisioning stripe twin... 5s
-[archal] provisioning stripe twin... 10s
+[archal] provisioning stripe clone... 5s
+[archal] provisioning stripe clone... 10s
 ...
 ```
 
 Subsequent runs with the same configuration reuse the warm session
 (~2 seconds).
 
-At the end of every run, the estimated twin-minute usage is printed:
+At the end of every run, the estimated workspace session-minute usage is printed:
 
 ```
-[archal] ~2 twin-minutes for this run (38.5s × 1 twin: stripe)
+[archal] ~2 clone-minutes for this run (38.5s × 1 clone: stripe)
 ```
 
 ## Docs

package/bin/archal.cjs

@@ -3,7 +3,7 @@
 const { existsSync } = require("node:fs");
 const { join } = require("node:path");
 
-const localDist = join(__dirname, "..", "dist", "index.cjs");
+const localDist = join(__dirname, "..", "dist", "cli.cjs");
 
 if (existsSync(localDist)) {
   require(localDist);