archal 0.9.18 → 0.9.19

package/dist/vitest/runtime/hosted-session-reaper.js

@@ -4,7 +4,7 @@ import {
   createHostedAuthLease,
   parsePositiveInteger,
   runHostedSessionReaper
-} from "../chunk-CTSN67QR.js";
+} from "../chunk-WZ7SA4CK.js";
 
 // src/runtime/hosted-session-reaper.ts
 var VITEST_AUTH_LEASE_OPTIONS = {

package/dist/vitest/runtime/setup-files.js

@@ -1,7 +1,7 @@
 import {
   bootstrapArchalVitestRouting
-} from "../chunk-IVXSSEYS.js";
-import "../chunk-CTSN67QR.js";
+} from "../chunk-L36NXAU6.js";
+import "../chunk-WZ7SA4CK.js";
 
 // src/runtime/setup-files.ts
 import { existsSync, rmSync } from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archal",
-  "version": "0.9.18",
+  "version": "0.9.19",
   "description": "Test your agents & integrations against service clones",
   "type": "module",
   "main": "dist/index.cjs",
@@ -49,13 +49,6 @@
     "clone-assets",
     "LICENSE"
   ],
-  "scripts": {
-    "verify:artifacts": "node scripts/assert-artifacts.mjs",
-    "prepack": "pnpm run verify:artifacts",
-    "prepare": "node scripts/prepare.cjs",
-    "typecheck:raw": "node --check bin/archal.cjs && node --check scripts/assert-artifacts.mjs && node --check scripts/prepare.cjs",
-    "typecheck": "pnpm run typecheck:raw"
-  },
   "peerDependencies": {
     "vitest": ">=2.1.0"
   },
@@ -65,6 +58,13 @@
     }
   },
   "dependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.1001.0",
+    "e2b": "^2.19.5",
     "picomatch": "^4.0.4"
+  },
+  "scripts": {
+    "verify:artifacts": "node scripts/assert-artifacts.mjs",
+    "typecheck:raw": "node --check bin/archal.cjs && node --check scripts/assert-artifacts.mjs && node --check scripts/prepare.cjs",
+    "typecheck": "pnpm run typecheck:raw"
   }
-}
+}

package/skills/attach/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: attach
+description: Connect Archal Attach to a repo and trace source, validate prerequisites, configure trace schema mapping, and diagnose import, grade, reproduction, and PR-fix runs.
+user-invocable: true
+argument-hint: "[repo, trace source, or failure description]"
+---
+
+# Archal Attach
+
+You help users connect real agent traces to Archal. Your job is to wire the repo,
+trace source, harness contract, scenario contract, and GitHub PR path without
+guessing or leaking secrets.
+
+Attach is not a replacement for `archal run`. It uses the same harness and clone
+routing ideas, but the trigger is a trace that already happened.
+
+## Product mental model
+
+Attach does this loop:
+
+1. Import a trace and its child spans from a read-only source.
+2. Grade whether the trace contains a real failure.
+3. Build a reproduction scenario and clone seed from trace evidence plus
+   repo-owned seed templates.
+4. Run the reproduction against service clones through the customer harness.
+5. If reproduced, patch the repo and open a GitHub issue or PR.
+
+Default policy is `fix`. Narrower policies stop earlier:
+
+| Policy | Stops after |
+|--------|-------------|
+| `observe` | import |
+| `grade` | grading |
+| `reproduce` | reproduction |
+| `fix` | PR or blocked fix status |
+
+Do not invent or promote separate top-level judge, reproduce, fix, or
+trace-replay commands. The public command is `archal attach`. Local stop
+command is `archal detach` for file-backed trace directories.
+
+## Discover first
+
+Before changing anything, inspect the repo:
+
+1. `package.json` and scripts: how is the agent run? What tests should a fix PR
+   pass?
+2. Existing Archal files:
+   - `.archal.json`
+   - `.archal/harness.*`
+   - `archal/harness.json`
+   - `archal/scenario.md`
+   - `archal/run-input.yaml`
+   - `archal/seeds/*.json`
+   - `scenarios/*.md`
+3. Service SDKs and likely clones:
+   - `stripe` -> `stripe`
+   - `@octokit/rest`, `octokit` -> `github`
+   - `@slack/web-api`, `@slack/bolt` -> `slack`
+   - `jira`, `jira-client`, `jira.js` -> `jira`
+   - `@linear/sdk` -> `linear`
+   - `@supabase/supabase-js`, `pg` -> `supabase`
+   - `googleapis` -> `google-workspace`
+4. GitHub remote:
+   ```bash
+   git remote get-url origin
+   ```
+   Hosted sources and `--execution-policy fix` need a GitHub remote.
+5. Trace source shape, if available:
+   - provider: local files, Postgres, Supabase
+   - trace table and span table names
+   - id columns
+   - parent span column
+   - timestamp/cursor columns
+   - status, workspace, trace group, and agent filters
+
+Never print secrets while inspecting. If you need to show a database URL, show
+only the env var name or secret reference.
+
+## Preconditions
+
+You need these before a full hosted Attach setup:
+
+- Archal CLI installed in the repo or reachable with `npx archal`
+- authenticated user (`archal login`) or `ARCHAL_TOKEN=archal_ws_...`
+- GitHub App installed on the target repo
+- repo origin that resolves to `github.com/<owner>/<repo>`
+- read-only trace source credential
+- headless harness command
+- `archal/scenario.md` for the trace family
+- optional but strongly recommended `archal/seeds/*.json`
+- model/provider keys required by the user's agent and tests
+
+If any prerequisite is missing, make the smallest safe change and explain what
+is still required. Do not continue into a fake reproduction.
+
+## Safe setup flow
+
+### 1. Install and authenticate
+
+Prefer project-local install:
+
+```bash
+npm install -D archal
+npx archal login
+npx archal usage
+```
+
+In CI or a customer repo, use:
+
+```bash
+export ARCHAL_TOKEN=archal_ws_...
+npx archal usage
+```
+
+Use a workspace API key for automated runs. Do not commit it.
+
+### 2. Add or verify `archal/harness.json`
+
+Minimal shape:
+
+```json
+{
+  "version": 1,
+  "local": {
+    "command": "node",
+    "args": ["agent.mjs"]
+  }
+}
+```
+
+The command must be headless and repeatable. It should run the real agent path,
+not a hand-authored mock. During reproduction, Archal invokes this command
+through `archal run`, so the agent should read the task from `AGENT_TASK` and
+print its final answer to stdout. If the project already has `.archal.json` for
+`archal run`, align the Attach harness with that command.
+
+### 3. Add or verify `archal/scenario.md`
+
+The scenario describes the standing task and checks for this trace family.
+
+Required sections:
+
+```md
+# Scenario title
+
+## Setup
+Trace-family context and the starting state Archal should reconstruct.
+
+## Prompt
+The task the agent should complete.
+
+## Expected Behavior
+The answer key for grading and reproduction.
+
+## Success Criteria
+- [D] Deterministic clone-state check
+- [P] Probabilistic trace/output check
+
+## Config
+clones: stripe, slack
+timeout: 120
+```
+
+Keep model-visible instructions realistic. Do not tell the tested agent that it
+is in Archal, a clone-backed environment, or a special replay.
+
+### 4. Add seed templates when trace evidence is thin
+
+Recommended:
+
+```text
+archal/seeds/
+  stripe-billing-support.json
+  jira-escalations.json
+```
+
+Seed templates should contain stable service state for the task family. Attach
+can then fill in trace-specific identifiers. This is much safer than expecting
+weak traces to reconstruct full service state.
+
+## Hosted database source
+
+Use this when traces live in Postgres or Supabase.
+
+First, create or request a read-only database user. Then keep the URL in an env
+var:
+
+```bash
+export TRACE_DATABASE_URL='postgres://readonly:...'
+```
+
+Run a check:
+
+```bash
+npx archal attach \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --source-id prod-agent-traces \
+  --check
+```
+
+Register:
+
+```bash
+npx archal attach \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --source-id prod-agent-traces
+```
+
+This posts the source config to Archal and returns. It does not start a local
+watcher and does not write local source state.
+
+Use a secret reference when the customer already has one:
+
+```bash
+npx archal attach \
+  --repo . \
+  --source postgres \
+  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces
+```
+
+`--database-url-secret-ref` must not contain a plaintext credential.
+
+## Trace schema mapping
+
+Defaults:
+
+| Concept | Default |
+|---------|---------|
+| trace table | `ai_traces` |
+| span table | `ai_spans` |
+| trace id | `id` |
+| span id | `id` |
+| span trace id | `trace_id` |
+| trace updated cursor | `updated_at` |
+| span updated cursor | `updated_at` |
+| cursor mode | `updated_at_id` |
+
+For a custom schema, pass mapping flags:
+
+```bash
+npx archal attach \
+  --repo . \
+  --source postgres \
+  --database-url-env TRACE_DATABASE_URL \
+  --trace-table public.agent_traces \
+  --span-table public.agent_spans \
+  --trace-id-column trace_id \
+  --span-id-column span_id \
+  --span-trace-id-column trace_id \
+  --parent-span-id-column parent_span_id \
+  --trace-updated-at-column updated_at \
+  --span-updated-at-column updated_at
+```
+
+For append-only sources:
+
+```bash
+npx archal attach \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --cursor-mode created_at_id \
+  --trace-created-at-column created_at \
+  --span-created-at-column created_at
+```
+
+Use filters for noisy sources:
+
+```bash
+npx archal attach \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --source-workspace-id workspace_123 \
+  --source-agent-id support-agent \
+  --source-status failed error \
+  --source-trace-group billing-support \
+  --source-limit 250
+```
+
+## Local trace directory
+
+Use this for a local pilot or exported trace files:
+
+```bash
+npx archal attach ./prod-traces --repo . --execution-policy reproduce
+```
+
+Artifacts are written under:
+
+```text
+.archal/attach/
+  attachments.json
+  runs.jsonl
+  raw/
+  grades/
+  seeds/
+  runs/
+  fixes/
+  failed/
+  logs/
+```
+
+Stop the local file-backed loop:
+
+```bash
+npx archal detach ./prod-traces --repo .
+```
+
+Do not describe `archal detach` as a hosted source disable command.
+
+## Dashboard expectations
+
+The workspace dashboard has three Attach pages:
+
+- Imported traces: source status, imported rows, grade verdict, blocked reason.
+- Reproduced failures: seed evidence, reproduction status, clone parity, run
+  artifacts.
+- Opened issues/PRs: GitHub issue, PR, branch, checks, and fix status.
+
+Do not route users to an old single Attach page. The user-facing pages are the
+three workspace dashboard pages above.
+
+## How to diagnose failures
+
+Classify failures precisely:
+
+- Trace import failure: database/source auth, mapping, cursor, filters, bad
+  trace shape.
+- Grade failure: judge could not determine expected outcome, missing evaluator
+  contract, trace lacks task context.
+- Missing evidence: trace does not contain enough state to seed. Add spans,
+  state snapshots, or repo-owned seed templates.
+- Reproduction failure: scenario or seed could not replay the failure against
+  clones. Inspect generated `scenario.md`, `seed.json`, and run manifest.
+- Agent behavior: the reproduced run shows the agent making the same wrong
+  service action it made in the original trace.
+- Harness issue: the agent command crashes, hangs, needs UI auth, or does not
+  reach clone-routed services.
+- Fix generation issue: patch does not apply, tests fail, no changes produced,
+  or generated PR metadata is incomplete.
+- GitHub issue: GitHub App missing, branch protection, permission denied, PR
+  checks unavailable.
+
+When evidence is insufficient, say so directly. Do not manufacture a seed or
+claim reproduction succeeded.
+
+## Artifact reading guide
+
+Local file-backed Attach uses repo-local artifacts. Hosted Attach exposes the
+same phase information in the dashboard.
+
+| Artifact | What to inspect |
+|----------|-----------------|
+| `grades/<trace>/routing.json` | trace import route and selected phase |
+| `grades/<trace>/grade.json` | verdict, summary, and reproduction decision |
+| `seeds/<trace>/scenario.md` | generated reproduction scenario |
+| `seeds/<trace>/seed.json` | generated seed request or materialized seed metadata |
+| `runs/<trace>/manifest.json` | reproduction status, command, attempts, evidence |
+| `runs/<trace>/stdout.json` | machine-readable run output |
+| `runs/<trace>/stderr.log` | reproduction stderr |
+| `fixes/<trace>/status.json` | blocked fix status |
+| `fixes/<trace>/pr-details.md` | PR reviewer summary |
+| `fixes/<trace>/repo.patch` | patch captured when PR creation cannot complete |
+
+## Security rules
+
+- Use read-only trace database credentials.
+- Never commit database URLs, API keys, model keys, or GitHub tokens.
+- Prefer `--database-url-env` locally and `--database-url-secret-ref` in hosted
+  production setup.
+- Do not pass production write credentials to a clone-routed reproduction.
+- Do not add model-visible copy that reveals Archal or clone routing to the
+  tested agent.
+- Do not bypass the GitHub App PR workflow with direct pushes.
+- Redact raw trace payloads before sharing artifacts outside the workspace.
+
+## What to report back
+
+After setup or debugging, give the user:
+
+- command run
+- source provider and source id
+- repo full name
+- execution policy
+- dashboard pages to inspect
+- artifacts produced, if local
+- whether import, grade, seed, reproduce, and fix phases are ready
+- exact blocker if any
+- next command or next owner
+
+## Docs
+
+- Attach production traces: https://docs.archal.ai/guides/attach-production-traces
+- CLI reference: https://docs.archal.ai/cli/attach
+- Running with an agent: https://docs.archal.ai/guides/run-with-agent
+- Writing scenarios: https://docs.archal.ai/guides/writing-scenarios
+- Seeds: https://docs.archal.ai/guides/seeds

package/skills/onboard/SKILL.md

@@ -122,6 +122,17 @@ Do not paste a sample config here. The right shape depends on what's already in
 
 Run: `archal clone start <detected clones>` - gives live clone URLs the user's SDK clients can point at. `archal clone status` shows the active session; `archal clone stop` tears down.
 
+### Option E - Attach real trace sources
+
+Use this when the repo already has agent traces from pre-production or
+production and the user wants Archal to import, grade, reproduce, and turn
+reproduced failures into GitHub issues or PRs.
+
+**Delegate to the `attach` skill.** It owns the trace-source mapping,
+`archal/harness.json`, `archal/scenario.md`, seed templates, `archal attach`
+commands, dashboard expectations, and failure taxonomy. Do not inline the
+Attach flow here; it changes faster than starter scenario setup.
+
 ## Verify
 
 Run the first scenario or task. For Options A and B, hand off to the `eval` skill to interpret the satisfaction score and diagnose failures - that skill owns the runtime mental model (`[D]` vs `[P]` criteria, trace inspection, harness execution diagnostics).
@@ -144,3 +155,4 @@ Run the first scenario or task. For Options A and B, hand off to the `eval` skil
 
 - Quickstart: https://docs.archal.ai/quickstart
 - Full docs: https://docs.archal.ai
+- Attach production traces: https://docs.archal.ai/guides/attach-production-traces