Nexts Actions: Use the App and Create Your Own Scripts
Connect browser accounts, query and publish content, and ask the Agent to build, register, and test custom platform scripts.
Open: Apps → Market → Nexts Actions → Install, then open it from Installed.
Nexts Actions uses platform accounts in your connected browser to run queries and specified operations, prepare content, and retain execution records. Use its interface directly or ask the Nexts Agent to call it.
First use
- Follow the browser extension guide to connect the Nexts AI extension and native bridge.
- Open Actions settings, refresh the browser list, and select your browser. If compatibility fails, update the Nexts AI extension in that browser.
- Find a platform under platform accounts, open its login page, and complete sign-in in the browser.
- Refresh account status in Actions and inspect the platform's available operations and parameters.
- Run a read-only query first. Check its result in execution records before publishing, replying, or making other changes.
Browsers use their own signed-in accounts. Cookie detection is a login signal, not proof of a valid server session. A catalog entry does not mean every operation has been tested against the website's current version.
Everyday workflows
| Entry | How to use it |
|---|---|
| Platform accounts | Find platforms, open their home or login pages, refresh status, and inspect operations |
| Queries and actions | Select a command, enter parameters, and inspect its receipt; review writes before submitting |
| Content distribution | Create or import Markdown and choose supported destinations |
| Subscriptions | Configure supported sources and notification conditions; no automatic replies |
| Execution records | Check output, failures, and operations whose results are uncertain |
| AI connection | Read invocation instructions and enable Agent integration in app permissions |
Subscriptions run only while the app backend is running. They do not continue in the cloud after it closes. App business data stays in its private directory; do not paste browser credentials into chat.
Prepare and distribute content
In versions with Content distribution, create or import a Markdown document, edit its title and body, attach images, a cover, or a video, and save. Select signed-in platforms that support the content type, fill in their required options, and confirm distribution.
Saving does not publish. Inspect each platform receipt: drafts, pending review, and public publication are different outcomes. Use files you selected for media. Check the platform before retrying an operation with an uncertain result.
Ask the Agent to use existing scripts
Enable Agent integration, then ask in the main Nexts conversation:
Use Nexts Actions to inspect the queries supported for my account.
Read recent content records and summarize them. Do not publish or reply.For content preparation:
Use Nexts Actions to prepare my selected document as a publishing draft.
Check supported content types and required fields for each target platform.
Show the preview and publishing plan. Wait for my confirmation before publishing.The Agent describes the app through the host, then uses actions.capabilities and actions.guide to discover operations. Queries use actions.query, writes use actions.run, and task polling uses actions.task. These are application actions, not standalone MCP tools.
Create your own script through an Agent conversation
A custom extension here means an Actions platform script, or adapter. You do not need to create another browser extension. It is also distinct from a standalone Nexts plugin: the existing Nexts AI browser extension executes browser operations.
The Agent currently needs access to an Actions development workspace. It must be able to edit that source tree and run Node tests. Agent integration in an installed Actions app only discovers and calls existing commands; there is currently no actions.* API for uploading, saving, or hot-installing new scripts. New scripts must be registered, packaged, and installed as part of the app.
A prompt you can copy
Open the Actions source project and replace the site and task in this prompt:
Create a custom browser script in the current Nexts Actions development workspace.
Site: https://example.com/
Task: Read HTTP/HTTPS links. Do not sign in, click links, or publish anything.
Command: nexts-demo:links
Parameter: limit, an integer from 1 to 20, default 10.
Output: rank, title, url. Remove duplicates and non-HTTP links.
Read AGENTS.md, .nexts-app/app.json, existing adapters, the bridge, and the catalog first.
Reuse the Nexts page interface and browser bridge; do not start a PublishPort daemon.
Implement the script, cli-manifest.json entry, necessary app domain declarations, and offline tests.
Verify parameters, errors, output shape, and manifest consistency.
Do not report mock tests as verification against the live website.
Before a live test, explain which pages it will visit. Wait for my action or confirmation for login or writes.
After testing, generate the app package and report its path, test results, and remaining live checks.
Do not change unrelated platform scripts or automatically publish the app or content.For a real platform, also specify the account, query scope, pagination, required fields, media source, and whether the task changes content. Do not supply passwords or cookies as development parameters. Have the Agent inspect authorized pages when the API or DOM is unknown instead of inventing selectors or endpoints.
Expected deliverables
- Readable JavaScript, parameter definitions, and an output example.
- A matching catalog entry and necessary permission declarations.
- Automated tests and live-browser acceptance steps, with completed and outstanding checks distinguished.
- An installable Actions package whose new operation is discoverable in the UI and through
actions.guide.
The following complete example can be implemented manually or used by your Agent. It targets Actions 0.1.1 and bundled adapter runtime 1.0.40; check the source when working with other versions. Run all development commands from the Actions source root, not this documentation website's repository.
Complete example: read links from a page
Execution flows from the App SDK through the Actions worker and adapter runtime to page, the Nexts local bridge, and the browser extension. The current bridge uses 127.0.0.1:18765, and the worker requires extension version 1.0.9 or later. Keep bridge addresses, credentials, and version checks out of individual adapters.
Create examples/browser-script/links.js:
import { cli, Strategy } from '@jackwener/opencli/registry';
import { ArgumentError } from '@jackwener/opencli/errors';
// Install this file at clis/nexts-demo/links.js in the vendored runtime.
export const command = cli({
site: 'nexts-demo',
name: 'links',
description: 'Read HTTP links from the Example Domain page',
access: 'read',
domain: 'example.com',
strategy: Strategy.UI,
browser: true,
navigateBefore: false,
siteSession: 'persistent',
args: [
{ name: 'limit', type: 'int', default: 10, help: 'Maximum rows, from 1 to 20' },
],
columns: ['rank', 'title', 'url'],
func: async (page, args) => {
const limit = Number(args.limit ?? 10);
if (!Number.isInteger(limit) || limit < 1 || limit > 20) {
throw new ArgumentError('limit must be an integer from 1 to 20');
}
await page.goto('https://example.com/');
await page.wait({ selector: 'h1', timeout: 10000 });
return page.evaluate((maxRows) => {
// This callback runs in the browser. Pass values as arguments;
// do not capture Node variables or concatenate user input into code.
if (location.origin !== 'https://example.com') {
throw new Error('Unexpected page origin; check redirects or browser access');
}
const rows = [];
const seen = new Set();
for (const element of document.querySelectorAll('a[href]')) {
const url = new URL(element.getAttribute('href'), location.href);
if (!['https:', 'http:'].includes(url.protocol) || seen.has(url.href)) continue;
seen.add(url.href);
rows.push({
rank: rows.length + 1,
title: (element.textContent || '').trim().slice(0, 200),
url: url.href,
});
if (rows.length >= maxRows) break;
}
return rows;
}, limit);
},
});func(page, args) receives the page and parameters. navigateBefore:false lets the script navigate explicitly. Reading DOM from a public page is still a browser task, so the example sets Strategy.UI and browser:true.
The page.evaluate() callback runs in the browser. It cannot capture Node variables or use the local filesystem. Pass dynamic values as arguments instead of concatenating JavaScript. This script reads links without following them and returns an empty array when none match.
Register the script in Actions
Create its catalog entry
Save this as examples/browser-script/manifest-entry.json:
{
"site": "nexts-demo",
"name": "links",
"description": "Read HTTP links from the Example Domain page",
"access": "read",
"domain": "example.com",
"strategy": "ui",
"browser": true,
"navigateBefore": false,
"siteSession": "persistent",
"args": [
{ "name": "limit", "type": "int", "default": 10, "help": "Maximum rows, from 1 to 20" }
],
"columns": ["rank", "title", "url"],
"type": "js",
"modulePath": "nexts-demo/links.js",
"sourceFile": "nexts-demo/links.js"
}A JavaScript file alone does not appear in Actions. The worker reads the bundled cli-manifest.json on startup. modulePath and sourceFile are relative to the runtime's clis/ directory. Actions uses site:name as the operation ID; the internal registry uses site/name.
Install it in the development workspace
Stop the development worker and preserve the original file versions. Run this PowerShell snippet from the Actions source root. It updates the development script, catalog, and app domain declaration:
$runtimeDir = 'backend/vendor/node_modules/@jackwener/opencli'
New-Item -ItemType Directory -Force "$runtimeDir/clis/nexts-demo" | Out-Null
Copy-Item -LiteralPath examples/browser-script/links.js -Destination "$runtimeDir/clis/nexts-demo/links.js"
@'
import fs from 'node:fs';
const manifestPath = 'backend/vendor/node_modules/@jackwener/opencli/cli-manifest.json';
const entries = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
const entry = JSON.parse(fs.readFileSync('examples/browser-script/manifest-entry.json', 'utf8'));
const remaining = entries.filter(item => !(item.site === entry.site && item.name === entry.name));
fs.writeFileSync(manifestPath, JSON.stringify([...remaining, entry], null, 2) + '\n');
const appPath = '.nexts-app/app.json';
const app = JSON.parse(fs.readFileSync(appPath, 'utf8'));
if (!app.network.outboundDomains.includes('example.com')) {
app.network.outboundDomains.push('example.com');
fs.writeFileSync(appPath, JSON.stringify(app, null, 2) + '\n');
}
'@ | node --input-type=moduleRestart the worker to discover nexts-demo. A normal query command does not require another React page or host action. Production adapters can add display metadata in backend/data/platforms.json and backend/data/logos.json. App domain declarations neither grant browser extension permissions nor provide an arbitrary-network sandbox.
Do not substitute installation into your personal ~/.ppcli/clis directory. Actions uses an app-private execution environment. When upgrading the bundled runtime, review and apply the Nexts bridge changes in scripts/patch-runtime.mjs.
Test your script
Offline tests
After installing the example in the development workspace, create tests/nexts-demo.test.mjs:
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import vm from 'node:vm';
import { command } from '../backend/vendor/node_modules/@jackwener/opencli/clis/nexts-demo/links.js';
import { buildArguments } from '../backend/operations.mjs';
function pageFixture(href = 'https://example.com/') {
const calls = [];
const context = vm.createContext({
URL,
location: { href, origin: new URL(href).origin },
document: { querySelectorAll: () => [
['javascript:alert(1)', 'Ignore'], ['/docs', ' Docs '], ['/docs', 'Duplicate'],
['https://www.iana.org/help/example-domains', 'Learn more'],
].map(([url, text]) => ({ getAttribute: () => url, textContent: text })) },
});
return {
calls,
goto: async url => { calls.push(url); },
wait: async () => {},
evaluate: async (fn, ...args) => JSON.parse(JSON.stringify(
await vm.runInContext(`(${fn.toString()})(...${JSON.stringify(args)})`, context),
)),
};
}
test('manifest matches the registered command and produces safe argv', () => {
const catalog = JSON.parse(fs.readFileSync('backend/vendor/node_modules/@jackwener/opencli/cli-manifest.json', 'utf8'));
const entry = catalog.find(item => item.site === 'nexts-demo' && item.name === 'links');
assert.ok(entry);
for (const key of ['access', 'args', 'columns', 'navigateBefore', 'siteSession']) {
assert.deepEqual(entry[key], command[key]);
}
assert.deepEqual(buildArguments(entry, { limit: 2 }), ['nexts-demo', 'links', '--limit=2', '--format', 'json']);
assert.throws(() => buildArguments(entry, { unexpected: true }), /Unknown argument/);
});
test('extracts links, filters unsafe schemes, removes duplicates and respects limit', async () => {
const page = pageFixture();
assert.deepEqual(await command.func(page, { limit: 1 }), [
{ rank: 1, title: 'Docs', url: 'https://example.com/docs' },
]);
assert.deepEqual(page.calls, ['https://example.com/']);
});
test('rejects invalid limits before navigation and detects unexpected origins', async () => {
for (const limit of [0, 21, 1.5, 'bad']) {
const page = pageFixture();
await assert.rejects(command.func(page, { limit }), /integer from 1 to 20/);
assert.deepEqual(page.calls, []);
}
await assert.rejects(command.func(pageFixture('https://unexpected.example/'), {}), /Unexpected page origin/);
});Run:
node --test tests/nexts-demo.test.mjs
npm testThese tests use a mock DOM and do not access the network. They do not verify the real extension or website. The current tests/integration.test.mjs has a fixed catalog-count assertion of 1543. Update that assertion when adding the example, or check the reviewed manifest count and the new operation explicitly. Do not remove the entire test to accommodate the new count.
Live browser acceptance
- Run
npm run devand open the address it prints. Confirm the extension is connected and the correct browser is selected. The development host performs real browser operations. - Find
nexts-demo, runlinkswithlimit=2, and confirm it opens the example page and returns at most two HTTP links. - Check
succeeded, exit code 0, and actual output in the run record. Link text may change; do not hard-code the live page's wording. - Try
limit=0: it should fail before script navigation. A disconnected browser should produce an unavailable error rather than switch accounts automatically. - Reusing a requestId should return the original task. Use a fresh UUID for a new task. Keep a redacted acceptance record without credentials.
For new UI, also verify desktop and 390px touch viewports. Primary actions must work without hover. An H5 container without the desktop bridge must show an unavailable capability; do not introduce a separate H5 backend to bypass the host boundary.
Call the new script through the Agent
After packaging and installing, ask: “Use nexts-demo:links in Nexts Actions to read the first two links from the example page.” The underlying host calls are shown below; use the actual tool names exposed by your environment:
{"applicationId":"ai.nexts.actions","action":"actions.guide","input":{"operationId":"nexts-demo:links"}}{"applicationId":"ai.nexts.actions","action":"actions.query","input":{"operationId":"nexts-demo:links","parameters":{"limit":2},"requestId":"dfb6ab3b-d58c-4a68-b21d-54fd932f5c1d","timeoutSeconds":60}}Generate a new UUID for each new logical task instead of repeatedly copying the example requestId. Submit returns a task record; pass its returned id, not requestId, to actions.task. Poll using next.afterMs and stop when terminal:true. The task's stdout string contains JSON output; stderr contains diagnostics.
Writes, authentication, and uncertain outcomes
Publishing, replying, and deleting must declare access:'write'. Submit through actions.run with confirmed:true only after the user has authorized the concrete operation. actions.query rejects writes. Clicking a button is not proof of publication: verify platform records or return a checkable ID, URL, and state.
| Task status | Meaning |
|---|---|
running | Execution is in progress |
succeeded | A read-only command exited with code 0 |
failed | A read-only command failed or was interrupted |
reported_success | A write reported success; inspect its platform receipt |
unknown | A write failed, timed out, or was cancelled, or the worker restarted with an unfinished task |
Check the platform before retrying an unknown result. Nexts disables navigation-error replay in Page.evaluate(); adapters must not unconditionally repeat writes either. requestId deduplicates retained local records, not platform operations permanently.
Authenticated platforms can register whoami and authStatus.quickCheck in auth.js or whoami.js. Background checks only receive getCookies. Declare quickCheckRequiresNavigation:true when verification needs a page, then use an interactive flow. Do not write cookies, tokens, or sensitive API responses to stdout/stderr: they are retained in execution records.
Package and install
npm test
npm run packagenpm run package runs type checking and the frontend build, then packages .nexts-app, dist, backend, and third-party notices. The version comes from .nexts-app/app.json; the example baseline produces release/ai.nexts.actions-0.1.1.zip. Version numbers are not incremented automatically.
Install the generated package through Nexts app management, reopen the app, and run another query. Editing source or rebuilding dist alone does not update an installed backend. Keep .dev-data, account data, and bridge credentials out of packaged directories. Creating a package does not publish it to the market.
Troubleshooting
| Problem | What to check |
|---|---|
| The Agent can call scripts but cannot create one | Open an Actions development workspace with file and test tools; the installed app has no dynamic script-install action |
| The command is missing | Check the manifest, modulePath, packaged file, and worker restart |
| The parameter form differs from the script | Update args in both the script and manifest |
| The extension is disconnected or outdated | Check the native bridge and selected browser, then update the browser extension |
| A page variable is undefined | Pass values into evaluate instead of capturing Node variables |
| The outcome is uncertain | Inspect platform records before repeating a write |
| A new publishing command is absent from distribution | Also check content-type and argument mappings in backend/distribution.mjs |
For a separate application rather than an Actions adapter, see the app SDK. For independent plugins, see the plugin guide.