# Actionlayer

ActionLayer component for Bijection — run tasks on any website and get reactive status updates in your Bijection app.

- Package: @bijectionhq/actionlayer
- Category: AI & Agents
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/actionlayer/tree/6b66b49d7e1fbeaac0a024132a4fc7cf526c33d4
- Upstream: https://github.com/ActionLayer-io/actionlayer-convex/tree/02b7741acb312e51eb6398bc10f8f78c113ea188
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/actionlayer

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/actionlayer.git
cd actionlayer
git checkout 6b66b49d7e1fbeaac0a024132a4fc7cf526c33d4
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @actionlayer/convex; check the Bijection adaptation separately.

ActionLayer is a Convex component that submits tasks, then streams task status updates into your Convex database via a scheduled poll loop. It handles anything in the physical world - from restaurant reservations, flower delivery, ride booking, and much more. Task state is stored in a component-owned table and surfaced through reactive queries, so your UI updates without any client-side polling logic.

### Use cases

- Deliver flowers to a loved one
- Find a plumber or electrician nearby
- Get food delivered
- Sort out your grocery shopping
- Absolutely anything in the physical world, we'll handle it for you!

### How it works

Register the component in `convex/convex.config.ts` using `app.use(actionlayer)`, set your `ACTIONLAYER_API_KEY` environment variable, and run `npx convex dev` to generate the typed `components.actionlayer` reference. Then instantiate `new ActionLayer(components.actionlayer)` inside your Convex functions to get access to the client API.

Call `actionLayer.startTask(ctx, { goal })` from a Convex action to submit a task. This calls the ActionLayer API, writes a ticket record to a component-owned table, and schedules a poll loop using the Convex scheduler. The poll loop updates the row as the task progresses through states: `pending`, `blocked_on_user`, `completed`, `failed`, or `cancelled`.

Your frontend subscribes to `actionLayer.get(ctx, { ticketId })` wrapped in a Convex query and uses `useQuery` to receive reactive updates. When a task reaches `blocked_on_user`, the `infoRequest` field contains what is needed from the user. Call `actionLayer.reply(ctx, { ticketId, message })` to resume it, or `actionLayer.cancel(ctx, { ticketId })` to stop it. Your app's own tables are never written to by the component.

### Upstream README

# @actionlayer/convex

Run tasks on any website from your Convex app. ActionLayer operates a real
browser end-to-end — bookings, signups, checkouts, form fills, data pulls —
and this component streams task status into your Convex database, so your UI
updates reactively as the task progresses.

## Setup

**1. Install the package:**

```bash
npm install @actionlayer/convex
```

**2. Register the component** in your app's `convex/convex.config.ts` (create
the file if it doesn't exist):

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import actionlayer from "@actionlayer/convex/convex.config";

const app = defineApp();
app.use(actionlayer);
export default app;
```

**3. Set your API key** in the Convex dashboard (Settings → Environment
Variables) — get one at [actionlayer.io/app#settings](https://actionlayer.io/app#settings):

```
ACTIONLAYER_API_KEY=ak_...
```

**4. Run codegen** so `components.actionlayer` shows up in your generated API:

```bash
npx convex dev
```

**5. Instantiate the `ActionLayer` client** in your Convex functions and call
it — see below.

## Use

```ts
// convex/tasks.ts
import { action, query } from "./_generated/server";
import { components } from "./_generated/api";
import { ActionLayer } from "@actionlayer/convex";
import { v } from "convex/values";

const actionLayer = new ActionLayer(components.actionlayer);

export const book = action({
  args: { goal: v.string() },
  handler: async (ctx, args) => {
    // e.g. "Book a table for 2 at Lilia Brooklyn this Saturday around 7pm"
    return await actionLayer.startTask(ctx, { goal: args.goal });
  },
});

export const status = query({
  args: { ticketId: v.string() },
  handler: async (ctx, args) => {
    return await actionLayer.get(ctx, args);
  },
});
```

Your frontend subscribes with `useQuery(api.tasks.status, { ticketId })` and
re-renders on every state change — no polling code on your side.

### Task lifecycle

`state` moves through `pending → completed | failed | cancelled`. If the
task needs something from your user (a choice, a missing detail), it parks at
`blocked_on_user` with the ask in `infoRequest` / `reason`. Send the answer
back and it resumes:

```ts
await actionLayer.reply(ctx, { ticketId, message: "the 7:30pm slot works" });
```

`cancel(ctx, { ticketId })` stops an in-flight task.

## How it works

`startTask` calls the ActionLayer API, records the ticket in a component-owned
table, and schedules a poll loop with the Convex scheduler. The loop updates
the row until the task reaches a terminal state; every update flows to your
subscribed queries. Your app's tables are untouched — the component keeps its
state to itself.

## Development

```bash
npm install
npm run typecheck
npm run build
```

`src/component/_generated` is committed — running `npx convex dev` in an app
that mounts the component regenerates it.

Publishing follows the standard Convex component flow — see
[docs.convex.dev/components/authoring](https://docs.convex.dev/components/authoring).