@superagnt/superagnt 2.0.5 → 2.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -18,9 +18,10 @@ openclaw superagnt connect
18
18
  ```
19
19
 
20
20
  OAuth in the browser; the consent screen doubles as signup if you don't have
21
- an account yet. After login the live tool surface is available in every
22
- OpenClaw session — and it grows server-side (`agnt_tools_enable`), no plugin
23
- update needed.
21
+ an account yet. After login the workspace tool surface is available in every
22
+ OpenClaw session. Which tool families are active is controlled by the user:
23
+ they are enabled explicitly, per workspace, in the superagnt app — the
24
+ plugin itself never turns anything on.
24
25
 
25
26
  <details>
26
27
  <summary>What connect does (or run it manually)</summary>
@@ -38,7 +39,9 @@ openclaw mcp login superagnt
38
39
 
39
40
  ## What you get
40
41
 
41
- One MCP connection carries the whole value layer:
42
+ One MCP connection to the user's own superagnt workspace. The tool families
43
+ below exist on the platform; each one is active only when the user has enabled
44
+ it for their workspace in the superagnt app:
42
45
 
43
46
  - **Data sources** — X, TikTok, YouTube, Instagram, Reddit, LinkedIn, and web
44
47
  scraping, as structured JSON tools
@@ -64,10 +67,10 @@ workflows on top of the tools:
64
67
  ## Prefer fixed, API-key tools?
65
68
 
66
69
  The per-platform data plugins (`@superagnt/reddit-data`,
67
- `@superagnt/linkedin-data`, …) and the `@superagnt/openclaw-agnt-data` master
68
- plugin ship baked toolsets that authenticate with just a `SUPERAGNT_API_KEY`
69
- — no OAuth, no MCP handshake. Install those instead when you want a minimal
70
- fixed surface.
70
+ `@superagnt/linkedin-data`, …) and the `@superagnt/social-data` master plugin
71
+ ship baked toolsets that authenticate with just a `SUPERAGNT_API_KEY` — no
72
+ OAuth, no MCP handshake. Install those instead when you want a minimal fixed
73
+ surface.
71
74
 
72
75
  ## CLI
73
76
 
@@ -79,5 +82,5 @@ openclaw superagnt doctor # connectivity + auth checks
79
82
  ## Links
80
83
 
81
84
  - Product: https://superagnt.com
82
- - Dashboard: https://app.superagnt.com/dashboard
85
+ - App: https://app.superagnt.com/dashboard
83
86
  - Docs: https://superagnt.com/docs
package/index.js CHANGED
@@ -50,7 +50,12 @@ function registerAgntCli(api) {
50
50
  .command('connect')
51
51
  .description('Wire up the live MCP tool surface: save the server config, then run OAuth login')
52
52
  .action(async () => {
53
- const MCP_ARGS = ['--url', 'https://mcp.superagnt.com/mcp', '--transport', 'streamable-http', '--auth', 'oauth']
53
+ // SUPERAGNT_MCP_URL points the saved server at a QA/staging MCP origin;
54
+ // customers never set it. The saved config entry overrides the
55
+ // manifest's prod default by name, so this is the one override that
56
+ // reaches OpenClaw (it does not expand env vars in plugin manifests).
57
+ const MCP_URL = process.env.SUPERAGNT_MCP_URL || 'https://mcp.superagnt.com/mcp'
58
+ const MCP_ARGS = ['--url', MCP_URL, '--transport', 'streamable-http', '--auth', 'oauth']
54
59
  const run = (args, quiet) => _spawnSync('openclaw', args, { stdio: quiet ? 'ignore' : 'inherit', shell: false })
55
60
  const probe = run(['mcp', 'show', 'superagnt'], true)
56
61
  if (probe.error) {
@@ -101,9 +106,11 @@ function registerAgntCli(api) {
101
106
  .description('Check connectivity and validate API key against api.superagnt.com')
102
107
  .action(async () => {
103
108
  console.log('\nsuperagnt doctor\n')
109
+ // SUPERAGNT_API_URL overrides the API origin (QA/staging); customers never set it.
110
+ const API_ORIGIN = process.env.SUPERAGNT_API_URL || 'https://api.superagnt.com'
104
111
 
105
112
  try {
106
- const publicRes = await fetch('https://api.superagnt.com/v1/platforms')
113
+ const publicRes = await fetch(API_ORIGIN + '/v1/platforms')
107
114
  console.log(' Public API: ' + (publicRes.ok ? 'OK (' + publicRes.status + ')' : 'HTTP ' + publicRes.status))
108
115
  } catch (err) {
109
116
  const msg = err instanceof Error ? err.message : String(err)
@@ -120,7 +127,7 @@ function registerAgntCli(api) {
120
127
  }
121
128
 
122
129
  try {
123
- const res = await fetch('https://api.superagnt.com/v1/platforms', {
130
+ const res = await fetch(API_ORIGIN + '/v1/platforms', {
124
131
  headers: { Authorization: 'Bearer ' + key },
125
132
  })
126
133
  const text = await res.text()
@@ -2,7 +2,7 @@
2
2
  "id": "superagnt",
3
3
  "name": "superagnt_",
4
4
  "description": "The agent value layer: one MCP connection = every data source (X, TikTok, YouTube, Instagram, Reddit, LinkedIn, web), people + company enrichment, a real workspace Postgres, schedules, webhooks and shareable canvases — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.",
5
- "version": "2.0.5",
5
+ "version": "2.0.7",
6
6
  "mcpServers": {
7
7
  "superagnt": {
8
8
  "url": "https://mcp.superagnt.com/mcp",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@superagnt/superagnt",
3
- "version": "2.0.5",
3
+ "version": "2.0.7",
4
4
  "type": "module",
5
5
  "description": "The agent value layer: one MCP connection = every data source (X, TikTok, YouTube, Instagram, Reddit, LinkedIn, web), people + company enrichment, a real workspace Postgres, schedules, webhooks and shareable canvases — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.",
6
6
  "main": "index.js",
@@ -28,9 +28,11 @@ system, then read deliveries with `receive_recent` when the session runs.
28
28
  `agnt_webhooks_create_endpoint`, `create_outbound`, `list_endpoints`,
29
29
  `link_agent`, `link_data_job`, `set_active`, `rotate_secret`,
30
30
  `list_deliveries`, `get_delivery`. Enable with
31
- `agnt_tools_enable(['webhooks'])` — sold under the Automation module (free
32
- trial); a `requires_upgrade` result carries a `confirm_url` for the human.
33
- Hand the link over and wait; never treat it as an error.
31
+ `agnt_tools_enable({ families: ['webhooks'] })`; it is on every plan. Plans
32
+ cap inbound events per billing period, and deliveries past the cap are
33
+ refused to the sender. A `requires_upgrade` result (a plan limit, or a trial
34
+ or plan that ended) carries a `confirm_url` for the human. Hand the link over
35
+ and wait; never treat it as an error.
34
36
 
35
37
  Three patterns, in the order clients usually need them:
36
38
 
@@ -54,10 +56,23 @@ Three patterns, in the order clients usually need them:
54
56
  `agnt_webhooks_list_deliveries` / `get_delivery` show what actually arrived
55
57
  and how it was acked. Check there before assuming the upstream never fired.
56
58
 
59
+ ## Tool names on grouped servers
60
+
61
+ This skill writes flat (per-operation) tool names. New superagnt servers list
62
+ grouped tools instead: one tool per resource with an `action` argument. Flat
63
+ names still resolve there but are not listed, so call the grouped form:
64
+
65
+ - `agnt_webhooks_inbound_url` / `agnt_webhooks_receive_recent` / `agnt_webhooks_list_endpoints` / `agnt_webhooks_list_deliveries` / `agnt_webhooks_get_delivery` → `agnt_webhooks_read`, action `inbound_url` / `receive_recent` / `list_endpoints` / `list_deliveries` / `get_delivery`
66
+ - `agnt_webhooks_send` / `agnt_webhooks_create_endpoint` / `agnt_webhooks_create_outbound` / `agnt_webhooks_link_agent` / `agnt_webhooks_link_data_job` → `agnt_webhooks_write`, action `send` / `create_endpoint` / `create_outbound` / `link_agent` / `link_data_job`
67
+ - `agnt_webhooks_set_active` / `agnt_webhooks_rotate_secret` → `agnt_webhooks_admin`, action `set_active` / `rotate_secret`
68
+
69
+ `agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
70
+ server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
71
+
57
72
  ## More
58
73
 
59
74
  - Schedules (cron) moved to the task-agents skill — see its `schedules.md`.
60
75
  - Live setup + endpoint reference: https://superagnt.com/agent-setup/prompt.md
61
- - Packaged event-driven workflows: https://superagnt.com/blueprints
76
+ - Packaged event-driven workflows: https://superagnt.com/skills
62
77
 
63
78
  <!-- skill_id: automations · source: https://github.com/superagnt/plugins -->
@@ -32,14 +32,32 @@ opens for anyone — no account needed on the viewer's side.
32
32
  accent.
33
33
  - Time widgets need `event_at`/`created_at` timestamptz columns; funnels and
34
34
  kanbans bind to stable status strings — schema rules in workspace-db.
35
- - If the canvas family is not enabled: `agnt_tools_enable(['canvas'])` —
36
- sold under the Database & Canvas module (free trial, `confirm_url` to the
37
- human on `requires_upgrade`).
35
+ - The canvas tools are missing only when neither the flat
36
+ `agnt_canvas_put_widget` nor the grouped `agnt_canvas_write` (action
37
+ `put_widget`) is listed. Then enable the family:
38
+ `agnt_tools_enable({ families: ['canvas'] })`, or on a grouped server
39
+ `agnt_tools_write` with `action: "enable"` and the same `families`.
40
+ Canvases are on every plan and count against no limit; what the plan caps
41
+ is the workspace database behind them (tables, rows, storage).
42
+
43
+ ## Tool names on grouped servers
44
+
45
+ New servers list one tool per family with an `action` argument. The flat
46
+ names above map to:
47
+
48
+ | Flat | Grouped tool, action |
49
+ |---|---|
50
+ | `agnt_canvas_get`, `_introspect_schema`, `_preview_query`, `_chart_render`, `_snapshot`, `_share_list` | `agnt_canvas_read`: `get`, `introspect_schema`, `preview_query`, `chart_render`, `snapshot`, `share_list` |
51
+ | `agnt_canvas_put_widget`, `_update_widget`, `_set_layout`, `_share_create` | `agnt_canvas_write`: `put_widget`, `update_widget`, `set_layout`, `share_create` |
52
+ | `agnt_canvas_remove_widget`, `_share_revoke` | `agnt_canvas_remove`: `remove_widget`, `share_revoke` |
53
+
54
+ Flat names still resolve on a grouped server but are not listed, so most
55
+ clients will not let you call them: use the grouped tool.
38
56
 
39
57
  ## More
40
58
 
41
59
  - A canvas over a table a task agent keeps fresh is a live dashboard with
42
60
  zero upkeep — pair with the task-agents skill.
43
- - Worked examples with real dashboards: https://superagnt.com/blueprints
61
+ - Worked examples with real dashboards: https://superagnt.com/skills
44
62
 
45
63
  <!-- skill_id: canvas · source: https://github.com/superagnt/plugins -->
@@ -26,19 +26,22 @@ you fetch).
26
26
 
27
27
  ## Running the job
28
28
 
29
- 1. The job itself (the per-item recipe) is created once — via the dashboard's
30
- data-pipelines page or the `data-jobs` management family
31
- (`agnt_data_job_create` / `list` / `read` / `inspect_run`). The family is
32
- sold under the Data Jobs module (free trial):
33
- `agnt_tools_enable(['data-jobs'])`, and on `requires_upgrade` hand the
29
+ 1. The job itself (the per-item recipe) is created once, via the
30
+ data-pipelines page in the superagnt app or the `data-jobs` management
31
+ family (`agnt_data_job_create` / `list` / `read` / `inspect_run`), on
32
+ every plan:
33
+ `agnt_tools_enable({ families: ['data-jobs'] })`. Plans cap active
34
+ pipelines and items per month; on `requires_upgrade` hand the
34
35
  `confirm_url` to the human and wait.
35
36
  2. `agnt_data_job_submit` (always available) pushes 1–1000 payloads onto an
36
- existing job — each payload a row pointer like `{ "row_id": ... }`.
37
+ existing job, each payload a row pointer like `{ "row_id": ... }`. A batch
38
+ that would cross the monthly item cap is refused whole, and the refusal
39
+ says how many items are left.
37
40
  3. **Results must be written back to a workspace table.** Make sure the
38
41
  job's recipe upserts each item's output into a table with a `status`
39
42
  column — that table is the ONLY place this session, later sessions, task
40
43
  agents, and canvases can read outcomes from. A recipe that merely returns
41
- its result stores it where only the dashboard can see it.
44
+ its result stores it where only the superagnt app can show it.
42
45
  4. Report progress from the table, not memory: counts by status via
43
46
  `agnt_db_select`. Failed items keep their error (`agnt_data_job_inspect_run`
44
47
  shows failures and sandbox logs); fix the cause and resubmit the failures,
@@ -52,6 +55,20 @@ in-session first to prove the step, then scale. Webhook-fed jobs (one
52
55
  delivery = one item, automations skill) inherit the same rule: know the
53
56
  expected volume before binding.
54
57
 
58
+ ## Tool names on grouped servers
59
+
60
+ This skill writes flat (per-operation) tool names. New superagnt servers list
61
+ grouped tools instead: one tool per resource with an `action` argument. Flat
62
+ names still resolve there but are not listed, so call the grouped form:
63
+
64
+ - `agnt_data_job_create` / `agnt_data_job_submit` → `agnt_data_job_write`, action `create` / `submit`
65
+ - `agnt_data_job_list` / `agnt_data_job_read` / `agnt_data_job_inspect_run` → `agnt_data_job_lookup`, action `list` / `read` / `inspect_run`
66
+ - `agnt_db_load_csv` → `agnt_db_write`, action `load_csv`
67
+ - `agnt_db_select` → `agnt_db_read`, action `select`
68
+
69
+ `agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
70
+ server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
71
+
55
72
  ## More
56
73
 
57
74
  - Table design for pipelines: the workspace-db skill
@@ -1,59 +1,102 @@
1
1
  ---
2
2
  name: superagnt-data-sources
3
- description: This skill should be used when the agent needs external data: searching or scraping X/Twitter, TikTok, YouTube, Instagram, Reddit, Facebook, or LinkedIn; running web or SERP searches; crawling pages; enriching a person or company; or finding and verifying emails. Also whenever normal fetching is blocked — bot detection, login walls, crawl prevention. Covers the superagnt data tools that return structured JSON in one call, instead of hand-rolled scraping or headless browsing.
3
+ description: This skill should be used when the agent needs external data: searching or scraping X/Twitter, TikTok, YouTube, Instagram, Reddit, Facebook, or LinkedIn; running web or SERP searches; crawling pages; enriching a person or company; or finding and verifying emails. Also whenever normal fetching is blocked: bot detection, login walls, crawl prevention. Covers the superagnt data tools that return structured results in one call, instead of hand-rolled scraping or headless browsing.
4
4
  version: 0.2.0
5
5
  ---
6
6
 
7
7
  # External data through superagnt
8
8
 
9
9
  Query, don't scrape. Every source below is one authenticated MCP call
10
- returning structured JSON — no headless browser, no HTML parsing, no
11
- per-vendor API keys. Calls spend workspace data credits; new workspaces carry
12
- a signup credit balance, and `agnt_credits_balance` shows what's left.
10
+ returning structured results: no headless browser, no HTML parsing, no
11
+ per-vendor API keys. Calls spend workspace data credits: the no-card trial
12
+ starts with a one-time data grant, each builder plan includes a monthly
13
+ amount, and `agnt_credits_balance` shows what's left.
13
14
 
14
15
  **When you're blocked, this is the unblock.** Social platforms and many sites
15
16
  stop direct fetching cold — bot detection, login walls, rate limits,
16
- JS-rendered pages. The data tools return the same content as structured JSON
17
+ JS-rendered pages. The data tools return the same content as structured data
17
18
  anyway: an X profile behind a login wall is one `data_x_*` call, a
18
19
  JS-rendered page is one `web` crawl call. Reach here the moment a fetch
19
20
  returns a challenge page instead of burning turns fighting it.
20
21
 
22
+ **Codex:** superagnt's tools can take a few seconds to appear in a new chat.
23
+ If none are listed, wait about 10 seconds and check again before concluding
24
+ superagnt isn't connected or falling back to web search.
25
+
26
+ ## Two tool surfaces
27
+
28
+ A server lists the data tools one of two ways, fixed when it was created:
29
+
30
+ - **Grouped** (every new server): one tool per source and resource with an
31
+ `action` argument, e.g. `data_x_users` action `tweets`,
32
+ `data_linkedin_posts` action `reactions`, `data_agnt_people` action
33
+ `enrich`. Every curated data source is always on: nothing to enable.
34
+ Results come back as a compact markdown table (lists) or `key: value` lines
35
+ (one item), with a footer naming the next-page parameter and the cost. The
36
+ web tools (`data_web_*`) and a few single tools stay listed under their own
37
+ names and answer in their usual JSON.
38
+ Pass `response_format: "json"` for the same view as JSON with every view
39
+ field, `"raw"` for the full upstream payload, `response_fields` to pick
40
+ fields, and `response_limit` to cap rows.
41
+ - **Flat** (servers created before grouped tools shipped): one tool per
42
+ operation, e.g. `data_x_user_s_tweets_get_user_tweets`,
43
+ `data_agnt_people_enrich`. Results are the raw JSON payload. Curated
44
+ families other than the first-party `data_agnt_*` tools start off and need
45
+ enabling.
46
+
47
+ Flat names still resolve on a grouped server, but they are not listed, so
48
+ most clients will not let you call them: use the grouped tool.
49
+
21
50
  ## Picking the tool
22
51
 
23
52
  1. `agnt_tools_list_enabled` — what this workspace already serves.
24
53
  2. `agnt_tools_search` with a plain-language query ("tiktok video comments",
25
54
  "company headcount", "serp") — finds the tool whether or not its family is
26
- enabled yet. If the family is disabled, enable it: `agnt_tools_enable`
27
- with the family id from the search result. Free families enable
28
- instantly; a `requires_upgrade` result carries a `confirm_url` for the
29
- human — never treat that as an error, hand the link over and wait.
55
+ enabled yet. On a grouped server each hit carries `grouped_name` and
56
+ `action`: call that. On a flat server, if the family is disabled, enable
57
+ it: `agnt_tools_enable` with the family id from the search result. Every
58
+ family enables instantly.
59
+ 3. On the trial or a builder plan, when the data credits run out a data
60
+ call returns `requires_upgrade` with a `confirm_url` for the human
61
+ instead of data; never treat that as an error, hand the link over and
62
+ wait. Everything that is not a data call keeps working. On other plans
63
+ it is a credit error: the human tops up in the superagnt app.
30
64
 
31
65
  ## The surfaces
32
66
 
33
67
  - **Social**: `data_x_*`, `data_tiktok_*`, `data_youtube_*`,
34
- `data_instagram_*`, `data_reddit_*`, `data_facebook_*`, `data_linkedin_*` —
35
- search, profiles, posts, comments, transcripts per platform.
36
- - **People + companies (first-party, always on)**: `data_agnt_people_search`,
37
- `data_agnt_people_enrich`, `data_agnt_people_email_finder`,
38
- `data_agnt_people_email_verifier`, `data_agnt_companies_search`,
39
- `data_agnt_companies_enrich`, `data_agnt_companies_discover`.
40
- - **Web**: the `web` family — crawl, scrape, and search for pages that
41
- aren't behind a social platform.
68
+ `data_instagram_*`, `data_reddit_*`, `data_facebook_*`, `data_linkedin_*`:
69
+ search, profiles, posts, comments, transcripts per platform. Grouped tools
70
+ are named per resource (`data_x_users`, `data_x_posts`,
71
+ `data_linkedin_profiles`, `data_reddit_subreddits`, `data_youtube_videos`,
72
+ `data_tiktok_read`, ...).
73
+ - **People + companies (first-party, always on)**: the table below.
74
+ - **Web**: `data_web_search`, `data_web_scrape`, `data_web_map`: search,
75
+ scrape and crawl pages that aren't behind a social platform. Same names on
76
+ both surfaces.
77
+
78
+ | Flat | Grouped |
79
+ |---|---|
80
+ | `data_agnt_people_search` / `_enrich` / `_bulk_enrich` | `data_agnt_people` action `search` / `enrich` / `bulk_enrich` |
81
+ | `data_agnt_companies_search` / `_discover` / `_enrich` / `_bulk_enrich` / `_intelligence` | `data_agnt_companies` action `search` / `discover` / `enrich` / `bulk_enrich` / `intelligence` |
82
+ | `data_agnt_people_email_finder` / `_email_verifier` | `data_agnt_contacts` action `find_email` / `verify_email` |
83
+ | `data_agnt_companies_domain_emails` | `data_agnt_contacts` action `domain_emails` |
84
+ | `data_agnt_people_find_mobile` | same name on both |
42
85
 
43
86
  ## Rules
44
87
 
45
88
  - Prefer one search call with good parameters over many broad ones — each
46
89
  call is metered, and tight queries return better data anyway.
47
90
  - Batch enrichment goes through `data_agnt_people_bulk_enrich` /
48
- `data_agnt_companies_bulk_enrich`, or a data job for large sets (see the
49
- data-pipelines skill).
91
+ `data_agnt_companies_bulk_enrich` (grouped: action `bulk_enrich`), or a
92
+ data job for large sets (see the data-pipelines skill).
50
93
  - Results worth keeping belong in the workspace database (see the
51
94
  workspace-db skill), not in chat scrollback.
52
95
 
53
96
  ## More
54
97
 
55
98
  - Every source, with live tool lists: `agnt_platform_map`, or
56
- https://superagnt.com/agent-toolkit
57
- - Packaged research workflows: https://superagnt.com/blueprints
99
+ https://superagnt.com
100
+ - Packaged research workflows: https://superagnt.com/skills
58
101
 
59
102
  <!-- skill_id: data-sources · source: https://github.com/superagnt/plugins -->
@@ -10,6 +10,10 @@ The workflow: pin the ICP → discover companies → find the people → verify
10
10
  emails → score → store → draft. Everything lands in the workspace database so
11
11
  runs compound instead of starting over.
12
12
 
13
+ **Codex:** superagnt's tools can take a few seconds to appear in a new chat.
14
+ If none are listed, wait about 10 seconds and check again before concluding
15
+ superagnt isn't connected or falling back to web search.
16
+
13
17
  ## Procedure
14
18
 
15
19
  1. **Pin the ICP once.** Ask the user for company filters (size, industry,
@@ -42,11 +46,28 @@ runs compound instead of starting over.
42
46
  - Large lists (500+): move enrichment to a data job (data-pipelines skill)
43
47
  instead of looping calls in-session.
44
48
 
49
+ ## Tool names on grouped servers
50
+
51
+ This skill writes flat (per-operation) tool names. New superagnt servers list
52
+ grouped tools instead: one tool per resource with an `action` argument. Flat
53
+ names still resolve there but are not listed, so call the grouped form:
54
+
55
+ - `data_agnt_companies_search` / `data_agnt_companies_discover` / `data_agnt_companies_enrich` → `data_agnt_companies`, action `search` / `discover` / `enrich`
56
+ - `data_agnt_people_search` / `data_agnt_people_enrich` → `data_agnt_people`, action `search` / `enrich`
57
+ - `data_agnt_people_email_finder` / `data_agnt_people_email_verifier` → `data_agnt_contacts`, action `find_email` / `verify_email`
58
+ - `agnt_db_insert` / `agnt_db_upsert` → `agnt_db_write`, action `insert` / `upsert`
59
+ - `agnt_db_select` → `agnt_db_read`, action `select`
60
+
61
+ `agnt_tools_search` and `agnt_tools_list_enabled` keep their names. Grouped
62
+ data calls return a compact markdown view: pass `response_format: "json"` for
63
+ every view field, or `"raw"` for the full payload, when a step needs a field
64
+ the table leaves out.
65
+
45
66
  ## More
46
67
 
47
68
  - A standing weekly refresh belongs on a task agent (task-agents skill), not
48
69
  in repeated client sessions.
49
70
  - The packaged end-to-end version of this workflow:
50
- https://superagnt.com/blueprints (Outbound Pipeline Engine)
71
+ https://superagnt.com/skills (Outbound Pipeline Engine)
51
72
 
52
73
  <!-- skill_id: lead-generation · source: https://github.com/superagnt/plugins -->
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: superagnt-setup
3
- description: This skill should be used when a superagnt MCP call fails (401/403, tool not found, missing connection, credit or entitlement errors), when connecting or reconnecting the superagnt server, right after a fresh connection (run onboarding first), or when the user asks "what can superagnt do", about pricing or trials, or how to add tools, skills, or blueprints. Covers agnt_onboarding, agnt_platform_map, agnt_tools_search/enable, and the human-confirmed upgrade flow. Money never moves without a human tap on a confirmation link.
3
+ description: This skill should be used when a superagnt MCP call fails (401/403, tool not found, missing connection, credit, plan limit or trial errors), when connecting or reconnecting the superagnt server, right after a fresh connection (run onboarding first), or when the user asks "what can superagnt do", about pricing or trials, or how to add tools or skills. Covers agnt_onboarding, agnt_platform_map, agnt_tools_search/enable, and the human-confirmed upgrade flow. Money never moves without a human tap on a confirmation link.
4
4
  version: 0.2.0
5
5
  ---
6
6
 
@@ -11,50 +11,99 @@ version: 0.2.0
11
11
  The live setup doc handles every client:
12
12
  `https://superagnt.com/agent-setup/prompt.md` — fetch and follow it. The
13
13
  endpoint is `https://mcp.superagnt.com/mcp`, OAuth-first (the consent screen
14
- doubles as signup). Tokens, when a client needs one, are revealed on the
15
- dashboard's MCP page — never invent or reuse one.
14
+ doubles as signup). On Claude the server is a claude.ai connector, not part of
15
+ the plugin: give the user https://claude.ai/customize/connectors/yours?modal=add-custom-connector&connectorName=superagnt&connectorUrl=https%3A%2F%2Fmcp.superagnt.com%2Fmcp&open_in_browser=1
16
+ (claude.ai's Add custom connector dialog, prefilled) and they click Add. It
17
+ opens in the browser, and the Claude desktop app only loads connectors when it
18
+ starts: in the desktop app, tell them to refresh it with Cmd+R (Ctrl+R on
19
+ Windows) or quit and reopen it once they've approved. Tokens, when a client needs one, are revealed on the MCP page in the superagnt app —
20
+ never invent or reuse one.
21
+
22
+ **Codex: the tools may not be loaded yet.** Codex starts the first turn of a
23
+ new chat before its MCP servers finish connecting, so superagnt's tools can be
24
+ missing for the first few seconds. If you see none (in Codex's code mode,
25
+ nothing named `mcp__superagnt__*` in `ALL_TOOLS`), wait about 10 seconds and
26
+ check again before telling the user superagnt isn't connected or falling back
27
+ to web search. `codex mcp list` showing `superagnt` enabled, with an Auth
28
+ column that doesn't read "Not logged in", means it is connected; "Not logged
29
+ in" means the sign-in never finished (see 401 below).
16
30
 
17
31
  ## First call on a fresh connection: `agnt_onboarding`
18
32
 
19
- Once tools respond, call `agnt_onboarding` before anything else. Pass a
20
- sentence or two about who the user is and what they want from an agent (ask
21
- them: "tell me a little about yourself and what you'd like automated"), plus
22
- which client this is. It returns the full platform brief — every surface,
23
- what it's for, and live links. Then:
33
+ Once tools respond, call `agnt_onboarding` before anything else, with
34
+ `client` (which client this is) and nothing else. It needs nothing from the
35
+ user, so don't ask them questions for it. It returns the full platform brief
36
+ (every surface, what it's for, live links) and, when the user started from a
37
+ skill on superagnt.com, that skill and its first-run prompt in
38
+ `skill_setups`. Then:
24
39
 
25
40
  - Save what's relevant to this user in your memory (if this client has one),
26
41
  so later sessions skip rediscovery.
27
- - Give the user a short brief of the 3–5 use cases most useful to THEM,
28
- drawn from what they told you — not the whole catalog.
42
+ - If `skill_setups` names a skill, offer its first-run prompt. Otherwise give
43
+ the user a short brief of the 3–5 most useful use cases, not the whole
44
+ catalog.
45
+
46
+ For a raw capability map any time later (always current):
47
+ `agnt_platform_map`.
48
+
49
+ ## Tool names: flat and grouped servers
50
+
51
+ A server lists its tools one of two ways, fixed when it was created. New
52
+ servers (including every new workspace's default server) are **grouped**:
53
+ one tool per family and risk level with an `action` argument, e.g.
54
+ `agnt_db_write` with `action: "insert"`, `agnt_agents_write` with
55
+ `action: "create"`, `data_linkedin_posts` with `action: "reactions"`. Servers
56
+ created before grouped tools shipped are **flat**: one tool per operation (`agnt_db_insert`, `agnt_agents_create`,
57
+ `data_linkedin_get_post_reactions`). These skills write flat names; on a
58
+ grouped server call the grouped tool whose description lists that name as an
59
+ action (each action line reads `- insert (agnt_db_insert): ...`). Flat names
60
+ still resolve server-side there, but they are not listed, so most clients
61
+ will not let you call them.
29
62
 
30
- For a raw capability map any time later (no intent collection, always
31
- current): `agnt_platform_map`.
63
+ On grouped servers the `agnt_email_*` tools are
64
+ `agnt_inbox_automation_read` / `_write` / `_delete`, and `data_*` results come
65
+ back as a compact markdown view. Pass `response_format: "json"` for every
66
+ view field as JSON, or `"raw"` for the full upstream payload, when a step
67
+ needs a field the table leaves out.
32
68
 
33
69
  ## Error triage
34
70
 
35
71
  - **401 / auth expired**: re-run the client's login step
36
- (`openclaw mcp login superagnt` or equivalent). If the client is token-based,
37
- the user re-reveals the token in the dashboard.
38
- - **Tool not found**: the family is not enabled. `agnt_tools_search` for it,
39
- then `agnt_tools_enable` — free families enable instantly. After enabling,
40
- some clients only pick up new tools on reconnect/restart; say so instead of
41
- retrying blind.
42
- - **`requires_upgrade` with a `confirm_url`**: not an error. The family is
43
- sold under a named module with a free trial; give the user the link, they
44
- review price and trial in the browser, then re-run the enable. Money moves
45
- only on that page, never from a tool call.
72
+ (`openclaw mcp login superagnt`, `codex mcp login superagnt` or equivalent).
73
+ For a Claude connector, the user reconnects superagnt in claude.ai under
74
+ Customize, Connectors. If the client is token-based, the user re-reveals
75
+ the token in the superagnt app.
76
+ - **Tool not found**: first check which surface this server lists (see
77
+ "Tool names" above). On a grouped server the operation usually lives inside
78
+ a grouped tool: look for the tool whose description lists it as an action,
79
+ or run `agnt_tools_search`, whose hits carry `grouped_name` and `action`.
80
+ Only a family missing under both names is off: enable it with
81
+ `agnt_tools_enable` (grouped: `agnt_tools_write` with `action: "enable"`);
82
+ every family enables instantly on every plan. Data sources are always on
83
+ for a grouped server, so never enable `data:*` there. After enabling, some
84
+ clients only pick up new tools on reconnect/restart; say so instead of
85
+ calling enable again.
86
+ - **`requires_upgrade` with a `confirm_url`**: not an error, and the call did
87
+ not run. The organization hit a plan limit, spent its included or trial
88
+ data credits, or its trial or plan ended; `reason` says which, and the
89
+ result names the next plan and what it unlocks. Give the user the link,
90
+ they review the plan in the browser, then re-run the call. `rate_limited`
91
+ only means wait `retry_after_seconds`. Money moves only on that page, never
92
+ from a tool call.
46
93
  - **`requires_connection`**: the tool needs the user's own account
47
94
  (a vendor integration). The result carries a connect link — hand it over.
48
95
  - **Credit errors**: `agnt_credits_balance` for the number;
49
- `agnt_usage_recent` for where it went. Top-ups are dashboard actions.
96
+ `agnt_usage_recent` for where it went. Top-ups happen in the superagnt
97
+ app. AI credits (what running agents spend) are topped up there on the
98
+ builder plans and during the trial; those plans include data credits only.
50
99
 
51
100
  ## Finding more
52
101
 
53
102
  - `agnt_platform_map` — the whole platform in one call, with live links.
54
103
  - `agnt_tools_search` — every tool family, enabled or not, with what it does.
55
104
  - `agnt_guidance_search` — how-to guidance for building on the platform.
56
- - Blueprints (packaged workflows: skill + tools):
57
- `https://superagnt.com/blueprints`.
105
+ - Packaged skills (a skill plus the tools it needs):
106
+ `https://superagnt.com/skills`.
58
107
  - Open-source skill library (this plugin's skills and more, MIT):
59
108
  `https://github.com/superagnt/leverage`.
60
109
  - A duplicate of an installed skill under two names (plugin copy + a loose
@@ -1,17 +1,42 @@
1
1
  ---
2
2
  name: superagnt-task-agents
3
- description: This skill should be used when a task must recur — "run this every day", "on a schedule", "set up a cron", "keep this updated while I sleep", "check X every morning" — or when a recurring job keeps re-running inside this client and eating its usage. Covers building a superagnt task agent: a small deployed agent that runs one job on the hosted runtime, fired by a schedule or webhook, with state in the workspace database. Cron mechanics in schedules.md.
4
- version: 0.1.0
3
+ description: This skill should be used when a task must recur — "run this every day", "on a schedule", "set up a cron", "keep this updated while I sleep", "check X every morning" — or when a recurring job keeps re-running inside this client and eating its usage. Covers the two ways to run it: this client's own scheduler when it can run the superagnt tools, or a superagnt task agent, a small deployed agent that runs one job on the hosted runtime, fired by a schedule or webhook, with state in the workspace database. Cron mechanics in schedules.md.
4
+ version: 0.2.0
5
5
  ---
6
6
 
7
- # Task agents: recurring work off the client
7
+ # Task agents: recurring work
8
8
 
9
- Re-running a recurring task in this client is the wrong tool: every run
10
- spends the client's own usage and context, and nothing fires with the laptop
11
- closed. A task agent is a small deployed superagnt agent that carries ONE
12
- job. It runs on the hosted runtime, billed per run to the workspace, and a
13
- schedule or webhook fires it with nobody at a keyboard. Build one whenever a
14
- task has run in-session more than twice and will keep recurring.
9
+ A recurring task can run two ways. Offer whichever fits the human:
10
+
11
+ - **This client's own scheduler.** If the client can schedule a recurring
12
+ task whose runs have the superagnt tools, use it. Each run starts with no
13
+ chat history, so write the task to stand alone and keep its state in the
14
+ workspace database. Runs use the human's plan for this client; superagnt
15
+ data calls still spend data credits. A scheduled run starts with nobody
16
+ signed in: check that the client can run unattended on this machine and
17
+ that something will fire it (the client's scheduler, cron or launchd), and
18
+ test one run. Nobody approves calls in a scheduled run and superagnt
19
+ doesn't gate tools for a client, so give the run an allowlist of only the
20
+ tools the job needs, with nothing that sends a message or starts a
21
+ campaign (on a grouped server that's the whole group tool, such as
22
+ `connection_gmail_mail_send`), and check in the test run that the
23
+ scheduled run's tool list has none of them. If the client can't restrict
24
+ tools for a scheduled run, build a task agent. Have
25
+ each run write its result where the human looks, and check the last run's
26
+ timestamp in the next attended session. If you are not sure the client can
27
+ schedule, or that its scheduled runs see the superagnt tools, say so and
28
+ build a task agent.
29
+ - **A task agent.** A small deployed superagnt agent that carries ONE job.
30
+ It runs on the hosted runtime, billed per run to the workspace, and a
31
+ schedule or webhook fires it with nobody at a keyboard and the laptop
32
+ closed. Use it when the client can't schedule, when the job reacts to
33
+ events (webhooks), or when it must run whether or not the human's machine
34
+ is on.
35
+
36
+ What doesn't work is re-running the job by hand in chat each time. Once a
37
+ task has run in-session more than twice and will keep recurring, offer one
38
+ of the two. The recipe below builds a task agent; steps 1 and 2 apply to a
39
+ client-scheduled task too.
15
40
 
16
41
  ## Recipe
17
42
 
@@ -19,10 +44,11 @@ task has run in-session more than twice and will keep recurring.
19
44
  not succeeded once end to end.
20
45
  2. **State in the workspace database** (workspace-db skill). A hosted run has
21
46
  no chat history — everything it needs to resume must be in a table.
22
- 3. **Enable the families.** `agnt_tools_enable(['lifecycle'])` for
23
- create/deploy; `['schedules']` for cron. Sold under the Agent Runtime and
24
- Automation modules (free trials): a `requires_upgrade` result carries a
25
- `confirm_url` — hand it to the human and wait; not an error.
47
+ 3. **Enable the families.** `agnt_tools_enable({ families: ['lifecycle'] })`
48
+ for create/deploy; `['schedules']` for cron. Both are on every plan. Plans
49
+ cap deployed agents and enabled schedules, so a `requires_upgrade` result
50
+ carries a `confirm_url` naming the next plan: hand it to the human and
51
+ wait; not an error.
26
52
  4. **Create narrow.** `agnt_agents_create` with a name and a system prompt
27
53
  that is the full job: the task, the tables it reads/writes, what done
28
54
  looks like, what to do on failure. Then `agnt_agents_update_config` with
@@ -30,7 +56,9 @@ task has run in-session more than twice and will keep recurring.
30
56
  `agnt_tools_search`, and only the tools the job needs. A task agent with
31
57
  every tool is a liability, not a convenience.
32
58
  5. **Deploy.** `agnt_agents_deploy` flips it live and it starts billing from
33
- its first session — confirm with the human before calling.
59
+ its first session, so confirm with the human before calling. Runs spend
60
+ AI credits, which the builder plans and the trial don't include: the human
61
+ tops them up in the superagnt app.
34
62
  6. **Wire the trigger.** An event exists → bind a webhook to the agent
35
63
  (automations skill). Purely time-based → create a schedule
36
64
  ([schedules.md](schedules.md)). On-demand from another agent or session →
@@ -50,6 +78,21 @@ task has run in-session more than twice and will keep recurring.
50
78
  - Misbehaving agent: `agnt_agents_set_enabled(false)` stops triggers
51
79
  reversibly — prefer it over archiving.
52
80
 
81
+ ## Tool names on grouped servers
82
+
83
+ This skill writes flat (per-operation) tool names. New superagnt servers list
84
+ grouped tools instead: one tool per resource with an `action` argument. Flat
85
+ names still resolve there but are not listed, so call the grouped form:
86
+
87
+ - `agnt_agents_create` / `agnt_agents_update_config` / `agnt_agents_deploy` / `agnt_agents_set_enabled` → `agnt_agents_write`, action `create` / `update_config` / `deploy` / `set_enabled`
88
+ - `agnt_agents_dispatch` / `agnt_agents_session_start` / `agnt_agents_session_send` → `agnt_agents_run`, action `dispatch` / `session_start` / `session_send`
89
+ - `agnt_agents_session_poll` → `agnt_agents_read`, action `session_poll`
90
+ - `agnt_observability_read_session` → `agnt_observability_read`, action `read_session`
91
+ - `agnt_schedules_create` / `agnt_schedules_update` → `agnt_schedules_write`, action `create` / `update`
92
+
93
+ `agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
94
+ server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
95
+
53
96
  ## More
54
97
 
55
98
  - Cron syntax, cadence discipline, timezones: [schedules.md](schedules.md)
@@ -9,8 +9,10 @@ version: 0.2.0
9
9
  Every superagnt workspace can carry a real Postgres the agent owns:
10
10
  `agnt_db_list_tables`, `agnt_db_execute_sql`, `agnt_db_apply_migration`,
11
11
  `agnt_db_insert` / `select` / `update` / `upsert` / `delete`,
12
- `agnt_db_load_csv`. If the tools are missing, enable the `database` family
13
- (`agnt_tools_enable`); if the database is not yet provisioned,
12
+ `agnt_db_load_csv`. On a grouped server these are actions of `agnt_db_read`,
13
+ `agnt_db_write` and `agnt_db_sql` (see the end of this file). If the tools are
14
+ missing under both names, enable the `database` family (`agnt_tools_enable`);
15
+ if the database is not yet provisioned,
14
16
  `agnt_db_status` says so and provisioning is automatic on first use.
15
17
 
16
18
  Local files die with the session. Anything a later run, another agent, a
@@ -38,6 +40,20 @@ schedule, or a canvas must read belongs here.
38
40
  stable status strings are exactly what canvas widgets bind to (see the
39
41
  canvas skill).
40
42
 
43
+ ## Tool names on grouped servers
44
+
45
+ This skill writes flat (per-operation) tool names. New superagnt servers list
46
+ grouped tools instead: one tool per resource with an `action` argument. Flat
47
+ names still resolve there but are not listed, so call the grouped form:
48
+
49
+ - `agnt_db_status` / `agnt_db_list_tables` / `agnt_db_select` → `agnt_db_read`, action `status` / `list_tables` / `select`
50
+ - `agnt_db_insert` / `agnt_db_upsert` / `agnt_db_update` / `agnt_db_load_csv` → `agnt_db_write`, action `insert` / `upsert` / `update` / `load_csv`
51
+ - `agnt_db_execute_sql` / `agnt_db_apply_migration` → `agnt_db_sql`, action `execute_sql` / `apply_migration`
52
+ - `agnt_db_delete` keeps its name on both surfaces
53
+
54
+ `agnt_tools_enable` is `agnt_tools_write`, action `enable`, on a grouped
55
+ server. `agnt_tools_search` and `agnt_tools_list_enabled` keep their names.
56
+
41
57
  ## More
42
58
 
43
59
  - CSVs and exports land as tables in one call: `agnt_db_load_csv` — then