@mercuryo-ai/agentbrowse 0.2.60 → 0.2.63

package/CHANGELOG.md

@@ -2,7 +2,39 @@
 
 ## Unreleased
 
-- No unreleased changes yet.
+- added `match`, `resolve`, and `fill` primitives for deciding which
+  caller-supplied value belongs in which observed field and applying it
+  through the existing browser runtime. Default match results expose
+  opaque value/artifact refs and never carry raw values through JSON
+  serialization
+- two resolver shapes accepted at the `fill(...)` `{ resolver }` slot:
+  the main `AgentbrowseMatchResolver` (required `resolve`, optional
+  `resolveBatch`, optional `fill`) and the narrow
+  `AgentbrowseGroupFillHandler` (just `fill`) for callers that only
+  apply ready grouped artifacts. `resolve(plan, { with })` only
+  accepts the main interface so `.resolve` is compile-time guaranteed.
+  Runtime picks the right capability through type guards and raises
+  `match_resolver_required` when a passed object lacks a capability
+  the current plan needs
+- `matchGroup` returns `ambiguous_group` when several candidates tie on
+  overlap and confidence, instead of silently picking the first by sort
+  order
+- stable resolved value/artifact refs (`value:${candidateRef}:resolved`,
+  `artifact:${candidateRef}:resolved`) so repeated resolves produce the
+  same refs
+- `ObserveTarget` now carries `pageRef` so observed targets flow
+  directly into `match(...)` without extra glue; `MatchableTarget` was
+  also relaxed to accept minimal target objects
+- `/testing` subpath now also exports `createFixtureMatchStore`,
+  `createFixtureGroupStore`, `createFixtureResolver`,
+  `fixtureResolvedValue`, and `fixtureResolvedArtifact` for wrapper
+  packages that test against the new primitives
+- added `docs/match-resolve-fill.md` and an `examples/match-resolve-fill.ts`
+  runnable example; repositioned the README as «browser runtime plus
+  deterministic field data-plane primitives»
+- `tsconfig.examples.json` and a `check-types:examples` script keep
+  example files type-checked against the project's public surface,
+  mirroring the pattern in `@mercuryo-ai/magicpay-sdk`
 
 ## 0.2.52
 

package/README.md

@@ -2,18 +2,33 @@
 
 [![npm version](https://img.shields.io/npm/v/@mercuryo-ai/agentbrowse)](https://www.npmjs.com/package/@mercuryo-ai/agentbrowse) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 
-Give your AI agent a real browser.
-
-AgentBrowse is the browser layer for agent systems that need to work with real
-web pages — launch a browser, read what's on screen, interact with it, and
-extract structured data. Your app keeps full control of orchestration and
-business logic; AgentBrowse handles the page.
+Give your AI agent a real browser — and a deterministic way to fill fields
+on it.
+
+AgentBrowse is the browser runtime for agent systems that need to work with
+real web pages, plus a small set of data-plane primitives for deciding which
+value belongs in which observed field without routing the values through
+the LLM prompt. Your app keeps full control of orchestration and business
+logic; AgentBrowse handles the page and the deterministic apply step.
+
+The package has two main parts:
+
+- **Browser runtime** — launch or attach a browser, `observe(...)` the page,
+  `act(...)` on targets, `extract(...)` structured data, `close(...)` when
+  done.
+- **Data-plane primitives** — `match(subject, { from })` picks a candidate
+  for an observed target or form, `resolve(plan, { with })` turns a plan
+  into a ready value or artifact through a caller-supplied adapter, and
+  `fill(session, subject, plan, { resolver? })` applies the result to the
+  browser deterministically. Default match results never expose raw values
+  to serializable output.
 
 Typical workflow:
 
 1. open a browser (or attach to an existing one) and get a `session`;
 2. ask AgentBrowse what's on the page with `observe(...)`;
-3. act on what you found with `act(...)`;
+3. either `act(...)` directly, or `match(...) → fill(...)` when you want
+   a deterministic field-value decision;
 4. use `extract(...)` when you need structured data instead of an action;
 5. close the session when you are done.
 
@@ -25,9 +40,13 @@ runtime you already have.
 Three terms come up repeatedly in the API:
 
 - **`session`** — the handle AgentBrowse returns from `launch(...)` or
-  `attach(...)`. You pass it into every later call. A session is valid
-  only while the underlying browser connection is live; `status(session)`
-  tells you whether it still is.
+  `attach(...)`. You pass it into every later call. The session carries
+  browser identity, runtime state, and sticky-owner metadata so healthy
+  commands reuse one browser owner instead of opening a fresh root CDP
+  attach for every call. If you persist a session across process runs,
+  the next command may repair that owner while the underlying browser is
+  still alive; otherwise the session fails closed and you should
+  `launch(...)` or `attach(...)` again.
 - **`ref`** (also `targetRef`, `scopeRef`, `fillRef`) — a stable reference
   returned by `observe(...)`. You act on references, never on raw CSS
   selectors. **Refs are valid for the page state that produced them, not
@@ -105,8 +124,8 @@ try {
   }
 
   const statusResult = await status(session);
-  if (!statusResult.success) {
-    throw new Error(statusResult.reason ?? statusResult.message);
+  if (!statusResult.alive) {
+    throw new Error('Browser is no longer reachable.');
   }
 } finally {
   await close(session);
@@ -119,10 +138,86 @@ Runnable examples live in [`examples/`](./examples/README.md):
 - `npx tsx examples/basic.ts`
 - `npx tsx examples/attach.ts`
 - `npx tsx examples/extract.ts`
+- `npx tsx examples/match-resolve-fill.ts`
 
 The library entrypoint does not load `.env` files. Environment loading only
 happens in the CLI entrypoint.
 
+Both `launch(...)` and `attach(...)` bootstrap the same sticky-owner
+lifecycle. That owner may live in-process or in an internal detached host,
+but it is not a user-managed daemon contract.
+
+## Match, Resolve, Fill
+
+Once `observe(...)` has returned a target or a fillable form, three
+primitives cover the end-to-end decision of putting a value into a field:
+
+- **`match`** decides which candidate value fits the observed target or
+  fillable form. Pure and local.
+- **`resolve`** turns a `needs_resolution` plan into a ready value by
+  calling a caller-supplied adapter. This is the only step that may reach
+  a network, a vault, or an approval UI.
+- **`fill`** applies the matched value to the browser through the same
+  deterministic path as `act(...)`.
+
+Simplest case — the value is already in memory:
+
+```ts
+import { match, resolve, fill } from '@mercuryo-ai/agentbrowse';
+
+const matched = await match(emailTarget, {
+  from: { email: 'traveler@example.com' },
+});
+// matched.kind === 'ready'
+await fill(session, emailTarget, matched);
+```
+
+When the value lives behind a lookup, the candidate carries a `resolve`
+plan and your adapter handles the fetch:
+
+```ts
+const pending = await match(passwordTarget, {
+  from: [
+    {
+      fieldKey: 'password',
+      type: 'secret',
+      resolve: { kind: 'vault_lookup', key: 'login.password' },
+    },
+  ],
+});
+// pending.kind === 'needs_resolution'
+
+const ready = await resolve(pending, { with: vaultResolver });
+await fill(session, passwordTarget, ready);
+```
+
+Core rules:
+
+- **No raw values in public results.** `match` returns plans and refs, not
+  secrets; dereferencing happens inside `fill(...)` through a non-enumerable
+  accessor. Serialising a `ready` result across a process boundary drops
+  the value — ship the `needs_resolution` plan instead and let the
+  downstream side run `resolve → fill`.
+- **One resolver slot, two accepted shapes.** The main
+  `AgentbrowseMatchResolver` has a required `resolve` plus optional
+  `resolveBatch` and optional `fill`; the narrow
+  `AgentbrowseGroupFillHandler` has just `fill`. Both are accepted in
+  the same `{ resolver }` slot on `fill(...)`; `resolve(plan, { with })`
+  only accepts the main interface. Use the narrow handler when the
+  caller already has the grouped artifact in hand and only needs to
+  apply it.
+- **Determinism first.** Resolved value/artifact refs are stable
+  (`value:${candidateRef}:resolved`), so the same plan produces the same
+  refs across calls — safe to use in snapshot tests and trace correlation.
+
+See:
+
+- [Match / Resolve / Fill Guide](./docs/match-resolve-fill.md) for the
+  full mental model, walk-throughs, and design rules.
+- [Testing Guide](./docs/testing.md) for fixture builders
+  (`createFixtureMatchStore`, `createFixtureResolver`, …) used in unit
+  tests for wrappers around these primitives.
+
 ## Attach To An Existing Browser
 
 If you already have a browser that exposes a CDP WebSocket URL, use
@@ -158,6 +253,11 @@ const attached = await attach(remoteCdpUrl, {
 });
 ```
 
+`attach(...)` is not a separate reconnect mode. It is the second bootstrap
+path into the same sticky-owner execution model as `launch(...)`. After
+attach succeeds, later browser commands reuse or repair that owner instead of
+performing a fresh provider-level root attach on every healthy command.
+
 ## What Each Main API Does
 
 | API | Use it when | Typical result |
@@ -166,6 +266,9 @@ const attached = await attach(remoteCdpUrl, {
 | `attach(cdpUrl, options?)` | You already have a running browser that exposes CDP | `session`, current `url`, current `title` |
 | `observe(session, goal?)` | You want to understand the page | targets, scopes, signals, fillable forms |
 | `act(session, targetRef, action, value?)` | You want to click, type, select, fill, or press | action result and target metadata |
+| `match(subject, { from })` | You want to pick a deterministic candidate for an observed target or fillable form | match result (plan or ready ref; no raw value) |
+| `resolve(plan, { with })` | You want to turn one or many `needs_resolution` plans into ready refs through a caller-supplied adapter | match result(s) marked as `ready` |
+| `fill(session, subject, plan, { resolver? })` | You want to apply a match result to the browser through the deterministic path | browser action result or structured failure |
 | `navigate(session, url)` | You want to move to another page | page metadata after navigation |
 | `extract(session, schema, scopeRef?)` | You want structured JSON from the page | `data` that matches your schema |
 | `screenshot(session, path?)` | You want a screenshot artifact | saved path and page metadata |
@@ -175,8 +278,10 @@ const attached = await attach(remoteCdpUrl, {
 Two common questions:
 
 - `observe(session)` gives you a general inventory of the page.
-- `observe(session, goal)` focuses that inventory around a question such as
-  `"find the checkout total"` or `"find the email field"`.
+- `observe(session, goal)` focuses that inventory around a single control
+  to find. Goals shaped as `"find <target> in <surface>"` (`"find the
+  email field"`, `"find May 5 in the open calendar"`) give the strongest
+  match. For multi-step work, run one goal per `observe` call.
 
 All main APIs return the same broad result shape:
 
@@ -240,6 +345,18 @@ store.save(session);
 const restoredFromCustomRoot = store.load();
 ```
 
+Persisted session files contain versioned sticky-owner metadata, not a live
+Playwright connection. `loadBrowserSession()` and custom stores intentionally
+return `null` for incompatible reconnect-era records or incomplete owner
+metadata instead of auto-migrating them. After loading a session, call
+`status(restored)` or let the next browser command verify or repair
+ownership. If the underlying browser is gone, the session fails closed and
+you start fresh with `launch(...)` or `attach(...)`.
+
+There is no separate daemon API to supervise. `close(session)` is the public
+lifecycle boundary for shutting down the internal owner host and, when
+applicable, the managed browser itself.
+
 If you want to use a proxy, pass it directly to `launch(...)`:
 
 ```ts
@@ -305,6 +422,7 @@ See:
 
 - [Getting Started](./docs/getting-started.md)
 - [API Reference](./docs/api-reference.md)
+- [Match / Resolve / Fill Guide](./docs/match-resolve-fill.md)
 - [Configuration Guide](./docs/configuration.md)
 - [Assistive Runtime Guide](./docs/assistive-runtime.md)
 - [Protected Fill Guide](./docs/protected-fill.md)

package/dist/browser-session-state.d.ts

@@ -1,8 +1,27 @@
 import type { BrowseRuntimeState } from './runtime-state.js';
 import type { ProxyConfig } from './solver/types.js';
-/** Browser capabilities discovered or provisioned for the session. */
-export interface BrowserSessionCapabilities {
-    captchaSolve?: boolean;
+export declare const STICKY_OWNER_SCHEMA_VERSION: 1;
+export type StickyOwnerState = 'bootstrapping' | 'active' | 'recovering' | 'dead';
+export interface StickyOwnerPlaywrightBindTransport {
+    type: 'playwright_bind';
+    endpoint: string;
+    mode: 'pipe' | 'ws';
+}
+export interface StickyOwnerInProcessTransport {
+    type: 'in_process';
+}
+export type StickyOwnerTransport = StickyOwnerPlaywrightBindTransport | StickyOwnerInProcessTransport;
+export interface StickyOwnerMetadata {
+    version: typeof STICKY_OWNER_SCHEMA_VERSION;
+    hostId: string;
+    state: StickyOwnerState;
+    startedAt: string;
+    lastUsedAt?: string;
+    ttlMs?: number;
+    touchPath?: string;
+    browserSessionId: string;
+    transport: StickyOwnerTransport;
+    pid?: number;
 }
 /** Persisted browser session state shared across AgentBrowse commands. */
 export interface BrowserSessionState {
@@ -13,8 +32,8 @@ export interface BrowserSessionState {
     profile?: string;
     identity?: BrowseSessionIdentity;
     transport?: BrowseSessionTransport;
-    capabilities?: BrowserSessionCapabilities;
     runtime?: BrowseRuntimeState;
+    stickyOwner?: StickyOwnerMetadata;
 }
 /** Browser session state plus transient run-scoped metadata. */
 export interface BrowserCommandSession extends BrowserSessionState {
@@ -44,15 +63,28 @@ export interface BrowserSessionStore {
     load(): BrowserSessionState | null;
     delete(): void;
 }
-type ManagedBrowserSessionInput = Omit<BrowserSessionState, 'port' | 'identity' | 'pid' | 'capabilities'> & {
+type ManagedBrowserSessionInput = Omit<BrowserSessionState, 'port' | 'identity' | 'pid'> & {
     pid: number;
-    capabilities?: BrowserSessionCapabilities;
 };
-type AttachedBrowserSessionInput = Omit<BrowserSessionState, 'port' | 'identity' | 'pid' | 'profile' | 'capabilities'> & {
-    capabilities?: BrowserSessionCapabilities;
+type AttachedBrowserSessionInput = Omit<BrowserSessionState, 'port' | 'identity' | 'pid' | 'profile'> & {
     browserInstanceRef?: string;
     provider?: string;
 };
+export declare function isStickyOwnerMetadata(value: unknown): value is StickyOwnerMetadata;
+export declare function canPersistStickyOwnerMetadata(value: unknown): value is StickyOwnerMetadata & {
+    transport: StickyOwnerPlaywrightBindTransport;
+};
+export declare function buildStickyOwnerMetadata(input: {
+    hostId: string;
+    state: StickyOwnerState;
+    startedAt: string;
+    lastUsedAt?: string;
+    ttlMs?: number;
+    touchPath?: string;
+    browserSessionId: string;
+    transport: StickyOwnerTransport;
+    pid?: number;
+}): StickyOwnerMetadata;
 export declare function parseSessionPort(cdpUrl: string): number | undefined;
 /** Converts a CDP websocket or HTTP endpoint into the matching DevTools HTTP endpoint. */
 export declare function buildCdpHttpEndpointUrl(cdpUrl: string, resourcePath?: '/json/version' | '/json/list'): string | null;
@@ -79,8 +111,6 @@ export declare function buildOwnedSession(session: ManagedBrowserSessionInput):
 export declare function buildAttachedSession(session: AttachedBrowserSessionInput): BrowserSessionState;
 /** Returns the most likely DevTools port for the current session. */
 export declare function getSessionPort(session: BrowserSessionState | null): number;
-/** Returns `true` when the session advertises captcha-solving capability. */
-export declare function supportsCaptchaSolve(session: BrowserSessionState | null): boolean;
 /** Returns `true` when the session belongs to an AgentBrowse-managed browser. */
 export declare function isOwnedSession(session: BrowserSessionState | null | undefined): session is BrowserSessionState & {
     identity: BrowseSessionIdentity;

package/dist/browser-session-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-session-state.d.ts","sourceRoot":"","sources":["../src/browser-session-state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-session-state.d.ts","sourceRoot":"","sources":["../src/browser-session-state.ts"],"names":[],"mappings":"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"}

package/dist/browser-session-state.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, wr
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { scrubProtectedExactValues } from './secrets/protected-exact-value-redaction.js';
+export const STICKY_OWNER_SCHEMA_VERSION = 1;
 const BLOCKED_SESSION_KEYS = new Set([
     'rawValue',
     'rawValues',
@@ -21,6 +22,67 @@ function ensureStateDir(stateDir) {
         mkdirSync(stateDir, { recursive: true });
     }
 }
+function isStickyOwnerTransport(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    if (candidate.type === 'in_process') {
+        return true;
+    }
+    if (candidate.type !== 'playwright_bind') {
+        return false;
+    }
+    const endpointCandidate = candidate.endpoint;
+    const endpoint = typeof endpointCandidate === 'string' ? endpointCandidate.trim() : '';
+    const mode = candidate.mode;
+    return endpoint.length > 0 && (mode === 'pipe' || mode === 'ws');
+}
+function isStickyOwnerState(value) {
+    return (value === 'bootstrapping' || value === 'active' || value === 'recovering' || value === 'dead');
+}
+export function isStickyOwnerMetadata(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.version === STICKY_OWNER_SCHEMA_VERSION &&
+        typeof candidate.hostId === 'string' &&
+        candidate.hostId.trim().length > 0 &&
+        isStickyOwnerState(candidate.state) &&
+        typeof candidate.startedAt === 'string' &&
+        candidate.startedAt.trim().length > 0 &&
+        (candidate.lastUsedAt === undefined ||
+            (typeof candidate.lastUsedAt === 'string' && candidate.lastUsedAt.trim().length > 0)) &&
+        (candidate.ttlMs === undefined ||
+            (typeof candidate.ttlMs === 'number' &&
+                Number.isFinite(candidate.ttlMs) &&
+                candidate.ttlMs > 0)) &&
+        (candidate.touchPath === undefined ||
+            (typeof candidate.touchPath === 'string' && candidate.touchPath.trim().length > 0)) &&
+        typeof candidate.browserSessionId === 'string' &&
+        candidate.browserSessionId.trim().length > 0 &&
+        isStickyOwnerTransport(candidate.transport) &&
+        (candidate.pid === undefined ||
+            (typeof candidate.pid === 'number' && Number.isFinite(candidate.pid) && candidate.pid > 0)));
+}
+export function canPersistStickyOwnerMetadata(value) {
+    return isStickyOwnerMetadata(value) && value.transport.type === 'playwright_bind';
+}
+export function buildStickyOwnerMetadata(input) {
+    return {
+        version: STICKY_OWNER_SCHEMA_VERSION,
+        hostId: input.hostId,
+        state: input.state,
+        startedAt: input.startedAt,
+        ...(input.lastUsedAt ? { lastUsedAt: input.lastUsedAt } : {}),
+        ...(typeof input.ttlMs === 'number' ? { ttlMs: input.ttlMs } : {}),
+        ...(input.touchPath ? { touchPath: input.touchPath } : {}),
+        browserSessionId: input.browserSessionId,
+        transport: input.transport,
+        ...(typeof input.pid === 'number' ? { pid: input.pid } : {}),
+    };
+}
 function atomicWriteJson(path, contents) {
     const tempPath = `${path}.${process.pid}.tmp`;
     try {
@@ -136,7 +198,7 @@ export function createBrowserSessionStore(options = {}) {
             }
             try {
                 const raw = JSON.parse(readFileSync(sessionPath, 'utf-8'));
-                if (!raw.cdpUrl) {
+                if (!raw.cdpUrl || !canPersistStickyOwnerMetadata(raw.stickyOwner)) {
                     return null;
                 }
                 return raw;
@@ -221,10 +283,6 @@ export function getSessionPort(session) {
     }
     return 9222;
 }
-/** Returns `true` when the session advertises captcha-solving capability. */
-export function supportsCaptchaSolve(session) {
-    return session?.capabilities?.captchaSolve === true;
-}
 /** Returns `true` when the session belongs to an AgentBrowse-managed browser. */
 export function isOwnedSession(session) {
     if (!session?.identity) {

package/dist/commands/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/commands/act.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAgBzE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AA6BtB,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA4CxF,2DAA2D;AAC3D,eAAO,MAAM,eAAe,oWAgBlB,CAAC;AAEX,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,8FAMpB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,GAAG;IAC9D,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,EAAE,UAAU,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,yBAAyB,GAAG,YAAY,GAAG;IACrD,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,EAAE,QAAQ,CAAC;IACzB,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,GAAG,SAAS,CAAC,CAAC;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,yBAAyB,GAAG,yBAAyB,CAAC;AAErF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAmK5D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,CAAC;AA+Q7B,wBAAsB,UAAU,CAC9B,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,CAAC,CAu2BpB;AAED,wBAAsB,GAAG,CACvB,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAaf"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/commands/act.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAgBzE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AA6BtB,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAwCxF,2DAA2D;AAC3D,eAAO,MAAM,eAAe,oWAgBlB,CAAC;AAEX,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,8FAMpB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,GAAG;IAC9D,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,EAAE,UAAU,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,yBAAyB,GAAG,YAAY,GAAG;IACrD,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,EAAE,QAAQ,CAAC;IACzB,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,GAAG,SAAS,CAAC,CAAC;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,yBAAyB,GAAG,yBAAyB,CAAC;AAErF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAmK5D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,CAAC;AA+Q7B,wBAAsB,UAAU,CAC9B,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,CAAC,CA24BpB;AAED,wBAAsB,GAAG,CACvB,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAaf"}