Workspace Loading and Session Lifecycle

The resident host loads workspace definitions at the point each feature needs them. Connecting an app starts session capture and event delivery. Connected triggers can react to those events; tests and tasks wait for an explicit run, and automatic Trends evaluation happens after capture is finalized.

Session flow

This shows the usual sequence: prepare the host and workspace before launching the app. Trigger work runs alongside capture, so the app does not wait for it.

flowchart TD
    accTitle: Workspace session lifecycle
    accDescr: Link a workspace and load triggers before the session starts. Capture continues alongside event-driven triggers. Finalized sessions receive Trends checks and saved results. Select a step for details.

    link("Link workspace") --> load("Load triggers")
    load --> start(["Session starts"])
    start --> capture("Capture evidence")
    capture --> finish("Finalize session")
    finish --> trends("Check trends")
    trends --> save[("Save results")]

    start -. "Start event" .-> match{"Trigger match?"}
    capture -. "New events" .-> match
    match -- "Yes" --> run("Run trigger")
    match -- "No" --> skip("Keep capturing")

    classDef setup fill:#fff0e8,stroke:#df7450,color:#78331b
    classDef capture fill:#eef3fc,stroke:#7c9ac7,color:#29466e
    classDef automation fill:#f3effa,stroke:#a18ac3,color:#584076
    classDef result fill:#eaf4ee,stroke:#77a68a,color:#2b593c
    class link,load setup
    class start,capture,finish capture
    class match,run,skip automation
    class trends,save result

The event-matching branch also applies to capture lifecycle events, including session.capture.started. If no trigger catalog is connected, ordinary session capture still works. Automatic Trends evaluation needs a registered workspace but does not depend on the trigger connection being enabled.

1. Associate the app with a workspace

The host uses an exact App ID to associate a session with a trusted local workspace path. The app does not upload workspace code or choose that path.

For a new workspace:

ansight workspace init . --app-id com.example.app

For an existing workspace:

ansight app register com.example.app --codebase /path/to/workspace

Both commands register the codebase and enable repository automation for that app. Linking Agent workspace in the local player also enables it. Review trigger code before making this association. Use workspace init . --no-register to create files without registering or enabling a workspace connection.

2. Load trigger definitions before the event arrives

At host startup, repository automation loads any explicitly configured repository paths and restores enabled workspace links from registered apps. Changes to app registration resynchronize those links while the host is running. A manual repo automation connect also loads a catalog immediately.

Discovery reads ansight/triggers/**/*.ts, derives IDs from relative paths, extracts each static trigger descriptor, and validates its App ID, event kind, conditions, and execution limits. It does not import the module or run its top-level code. Disabled triggers remain visible but do not match events.

A repository with invalid trigger definitions fails to connect; inspect its warnings and fix it before retrying. --disable-repository-automations disables trigger execution across the host.

3. Open the app session

After pairing authorizes the app, the host accepts its session connection, registers the live connection, and publishes session.capture.started. Capture and subsequent app/session events then flow through the host.

Session started means the connection is open. It does not guarantee that the first screen, app data, or a particular app-owned tool is ready. For a snapshot that depends on completed initialization, have the app emit a stable app.event label when that state is ready and match that label in the trigger.

Connect startup triggers before launching the app. Connecting a catalog later only affects future events; it does not replay a missed start event. A reopened connection can emit another capture-start event, so do not treat that event as a once-per-install setup hook.

4. Match first, then execute

For each eligible event, the host matches enabled triggers by exact App ID and event kind, then checks every declarative condition. A trigger only runs when every condition matches.

A match enters a bounded queue. For each admitted attempt, the CLI loads the module and runs its default handler with the matched event. Module initialization code and imported dependencies also run, so review the complete module before enabling it. The handler returns no action or one app-tool action. The host validates and executes a returned action under its separate timeout and records the attempt. Eligible failures follow the trigger’s retry policy.

Triggers run asynchronously alongside capture. Multiple handlers can run concurrently; their completion order is not a startup sequence. A full queue rejects work rather than blocking app startup. Use an explicitly invoked task when several actions must run in a defined order.

What else runs, and when?

An explicit ansight test run has its own preparation and execution flow: it loads the selected definition, prepares and launches the installed app, waits for the matching session, runs the scenario, and stops the app. See Tests for that workflow.

5. Finalize capture and evaluate Trends

When the connection closes, the host publishes session.capture.stopped. After it finishes stopping capture sources such as native logs and external screenshots, it publishes session.capture.finalized and queues automatic Trends evaluation.

The evaluator resolves the session’s App ID to its registered codebase, loads the current enabled Trends definitions for that app, and evaluates the windows observed in the captured evidence. Unobserved windows are recorded as inconclusive without evaluating their metrics. Results are saved in trends-results.json and applicable history is updated. Missing registrations or applicable definitions leave the capture available without a Trends evaluation.

Capture finalization does not wait for all trigger runs to finish. An app-tool action also needs a live connection, so a stopped or finalized event should not be used to request a last snapshot from an already disconnected app.

Refresh and verify the connection

Workspace files are not watched automatically. Inspect after editing and reconnect to refresh trigger descriptors and matching rules:

ansight repo automation inspect com.example.app . --json
ansight repo automation connect com.example.app .
ansight repo automation list --json
ansight repo automation runs com.example.app --limit 100 --json

Inspection alone does not replace the active catalog. The CLI loads the saved module for each attempt, while event matching uses the connected descriptor; reconnect after edits to keep those two consistent. Starting another app session does not itself reload the catalog.

The CLI connect and disconnect commands affect the running host. Persisted, enabled workspace links can be restored at the next host startup or app-link resynchronization. Use the local player’s Disconnect control to persistently disable a registered app’s trigger connection.

See Triggers for matching and run-history details, Authoring and Validation for discovery refresh, and Execution Security for execution permissions and limits.