@gaiventures/pilotfish-mcp-managed 0.1.24 → 0.1.26

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.
Files changed (3) hide show
  1. package/README.md +30 -19
  2. package/cli.js +87 -18
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -38,10 +38,10 @@ Want a browser on your own computer for free, driven by your agent's own model,
38
38
  1. **Have an account.** [Sign up with Google](https://pilotfish.gai.ventures/signup) and name your organization (you
39
39
  become its primary admin), or accept an emailed invitation to join an existing one as a member or an admin.
40
40
  2. **Make sure the organization has credits.** Admins add them under **Usage → Credits** in the app (pay as you go,
41
- from $10, with optional auto reload). Members run tasks on the organization's credits within any allowance an
41
+ from $5, with optional auto reload). Members run tasks on the organization's credits within any allowance an
42
42
  admin sets for them.
43
43
  3. **Connect your agent** (below). The simplest way is to sign in from your client, which then acts as you. Scripts,
44
- servers and shared agents use one of the organization's API keys instead. The app's **MCP** page
44
+ servers and shared agents use an API key instead (Org settings → API keys). The app's **MCP** page
45
45
  (`https://pilotfish.gai.ventures/connect`) has the endpoint and every client's setup.
46
46
 
47
47
  ## Connect
@@ -102,7 +102,8 @@ In `~/.codex/config.toml`, through this package:
102
102
  command = "npx"
103
103
  args = ["-y", "@gaiventures/pilotfish-mcp-managed"]
104
104
  env = { PILOTFISH_KEY = "pf_YOUR_KEY" }
105
- # A call returns within 120 s (the task carries on); Codex stops a call after 60 s by default.
105
+ # A call returns within 50 s, or 120 s when the client asks for progress updates; the task carries on either way.
106
+ # Codex stops a call after 60 s by default.
106
107
  tool_timeout_sec = 180
107
108
  ```
108
109
 
@@ -159,11 +160,12 @@ working at once; rotate a key when someone who had it leaves. Each key has its o
159
160
  through the MCP and the API, and its sessions. An admin can give a key an allowance: a spending limit on the
160
161
  organization's credits, with an optional automatic top-up.
161
162
 
162
- **Personal MCP keys.** Admins (the primary admin included) can also make a key of their own on the app's **MCP**
163
- page: it acts as them, in their Personal project, for their own scripts. A member can have them too once an admin turns
164
- on **Allow personal MCP keys** on the member's page (Org settings → the person); turning it off revokes their keys at
165
- once. Until then a member is told whom to ask, and connects their AI tool by signing in (no key needed). Admins see
166
- each person's key usage.
163
+ **Personal API keys.** An API key always belongs to a project. For your own scripts and tools that can't sign in,
164
+ make one in the app's **Org settings → API keys** and pick the project **Personal (you)**: it acts as you, in your
165
+ Personal project, with your own saved logins, and only you can see or manage it. Admins (the primary admin included)
166
+ can always do this; a member can once an admin turns on **Allow personal API keys** on the member's page (turning it
167
+ off revokes their keys at once), and then finds their keys on their Org settings page. Admins see each person's key
168
+ usage, never the keys. Most people need no key at all: Claude Code, the Claude app, Cursor and VS Code sign in.
167
169
 
168
170
  ## Projects
169
171
 
@@ -175,8 +177,10 @@ Every task runs in a project.
175
177
  users. They hold no one's personal logins and no saved or scheduled tasks: each end user is an **identity** there. A
176
178
  task with no identity gets a fresh browser of its own, and nothing of it is kept for other sessions.
177
179
 
178
- Switch in the app's project switcher, or with `switch_project` (no argument lists your projects); the MCP remembers
179
- your choice for your next connections. An organization API key always works in its own project.
180
+ Switch in the app's project switcher, or with `switch_project` (no argument lists your projects). Signed in from your
181
+ client (OAuth), the MCP remembers your choice for your next connections. With a personal API key the switch lasts for
182
+ that connection only, and the key starts in Personal again next time. An organization API key always works in its own
183
+ project.
180
184
 
181
185
  ## Identities: tasks for your own users
182
186
 
@@ -260,7 +264,7 @@ Acme HR runs LinkedIn tasks for its users Priya (in India) and Rahul (in the US)
260
264
  the link in its own app; Priya signs in to LinkedIn there. Rahul does the same with his.
261
265
  3. Tasks by identity: `browser_task {identity: "idn_priya…", task: "Read my new LinkedIn messages and list who wrote"}`.
262
266
  It runs on Priya's LinkedIn session, from an Indian residential IP on her own device; Rahul's runs from the US on his.
263
- 4. The cost: each result ends with `Cost: …` and `identity: idn_priya…`; at month end Acme reads
267
+ 4. The cost: each result ends with `Cost: …`, `Project: …` and `Identity: idn_priya…`; at month end Acme reads
264
268
  `GET /identities/idn_priya…/usage?since=…` for each user and bills them.
265
269
  5. Priya leaves: `identities {action: "delete", id: "idn_priya…"}` wipes her LinkedIn login, session and device. Her
266
270
  past tasks and their costs stay in Acme's usage.
@@ -276,7 +280,7 @@ Everyone is in one organization, and its credits pay for every task its people a
276
280
  | Monthly limit and overage | Yes | Yes | No |
277
281
  | Invite people, change roles, set allowances | Yes | Yes | No |
278
282
  | Create and manage API keys, and shared projects | Yes | Yes | No |
279
- | A personal MCP key | Yes | Yes | When an admin turns it on (else they sign in from their client) |
283
+ | A personal API key | Yes | Yes | When an admin turns it on (else they sign in from their client) |
280
284
  | See everyone's tasks and spending | Yes | Yes | No: their own, and their allowance |
281
285
  | Hand the primary admin role to someone else | Yes | No | No |
282
286
 
@@ -305,8 +309,8 @@ the monthly limit and spending by category and by model.
305
309
 
306
310
  | Tool | What it does |
307
311
  | --- | --- |
308
- | `browser_task` `{task, start_url?, region?, sites?, login?, accounts?, identity?, credentials?, stealth?, solve?, model?, quality?, max_steps?, pre_approved?, files?, wait?, wait_seconds?}` | Run a whole web task, however many sites and steps. Waits up to `wait_seconds` (default 120) and returns the result with its cost by kind and its project and identity, or the job id if it is still running (it carries on; `get_job` waits again). `wait: false` returns the id at once. `model`: `gpt-6-luna` (the default), `auto` (Haiku does the task, Sonnet checks it), or one model for every step: `opus`, `sonnet`, `haiku`, `gpt-5-mini` or `gpt-5-nano`. `quality` (`auto`, `economy`, `accurate`) instead of one model; `model` wins. `region`: the country to browse from (`"us"`, `"in"`). `start_url`: the page to open first. `sites`: further sites whose saved logins the task may use. `login`: which of your accounts on those sites; `accounts` (`{"linkedin.com": "work"}`, `""` the main one): which account on each site. `identity` (`idn_…`, in a shared project): run as that end user; `credentials` (`["cred_…"]`): which of its saved logins. `stealth` and `solve`: on by default; `false` turns them off for this run. `max_steps`: browser actions across the run. `pre_approved` (`{actions: [pay, delete, send, transfer, cancel], max_amount?, currency?}`): only with the person's say-so, final steps that run without asking. `files`: up to 10 attachments (`{name, type?, data}` in base64, 25 MB each). |
309
- | `get_job` `{id, wait_seconds?}` | A job's status, its open question with the link to answer it, the result, the cost so far, the live-view link while it runs, and the session's files. `wait_seconds` waits for it to finish or need you first. |
312
+ | `browser_task` `{task, start_url?, region?, sites?, login?, accounts?, identity?, credentials?, stealth?, solve?, model?, quality?, max_steps?, pre_approved?, files?, wait?, wait_seconds?}` | Run a whole web task, however many sites and steps. Waits up to `wait_seconds` (default 120 when your client asks for progress updates, else 50) and returns the result with its cost by kind and its project and identity, or the job id if it is still running (it carries on; `get_job` waits again). A call that is cancelled or times out stops waiting and leaves the task running. `wait: false` returns the id at once. `model`: `gpt-6-luna` (the default), `auto` (Haiku does the task, Sonnet checks it), or one model for every step: `opus`, `sonnet`, `haiku`, `gpt-5-mini` or `gpt-5-nano`. `quality` (`auto`, `economy`, `accurate`) instead of one model; `model` wins. `region`: the country to browse from (`"us"`, `"in"`). `start_url`: the page to open first. `sites`: further sites whose saved logins the task may use. `login`: which of your accounts on those sites; `accounts` (`{"linkedin.com": "work"}`, `""` the main one): which account on each site. `identity` (`idn_…`, in a shared project): run as that end user; `credentials` (`["cred_…"]`): which of its saved logins. `stealth` and `solve`: on by default; `false` turns them off for this run. `max_steps`: browser actions across the run. `pre_approved` (`{actions: [pay, delete, send, transfer, cancel], max_amount?, currency?}`): only with the person's say-so, final steps that run without asking. `files`: up to 10 attachments (`{name, type?, data}` in base64, 25 MB each). |
313
+ | `get_job` `{id, wait_seconds?}` | A job's status, its open question with the link to answer it, the result, the cost so far, the live-view link while it runs, and the session's files. `wait_seconds` waits for it to finish or need you first, with progress updates while it waits. |
310
314
  | `get_file` `{id, file_id}` | One of the session's files, attached or downloaded. Up to 5 MB comes back in the result (an image as an image, text as text); larger files are linked in the app. |
311
315
  | `list_jobs` `{status?, limit?}` | Your recent jobs, newest first, with their cost; `[replay]` marks recorded ones. `status`: `queued`, `running`, `needs_input`, `done`, `failed` or `cancelled`. |
312
316
  | `follow_up` `{id, text, model?, region?, files?, wait?, wait_seconds?}` | Carry on in the same session: the same browser while it is kept, the same sign-ins, what earlier turns found ("now also…", "open the second one", "try again with…"). `model` changes this turn's model (`auto` routes again). `region` runs the turn from another country, in a new browser session there. The session keeps its project and identity. |
@@ -314,7 +318,7 @@ the monthly limit and spending by category and by model.
314
318
  | `answer_job` `{id, question_id, answer}` | Answer a job's question: `yes`, `no`, `done` (handled in the browser), `cancel`, or text. The id is in the job's `Question …` line, which also says what answer it takes. Codes and passwords go on the answer page, never here. |
315
319
  | `message_job` `{id, text}` | Pass on what the person says while a job runs ("take the cheaper one", a detail it asked for), in their words. It reads the message before its next step, and the person's newest words win over the task; sent while the job waits on a question, it answers it. |
316
320
  | `take_control` `{id}` / `hand_back` `{id}` | Pause a running job and get a link to drive its browser yourself, then let it carry on from where you left it. |
317
- | `cancel_job` `{id}` | Stop a job. Cancelling a tool call that is waiting on a job stops the job too. |
321
+ | `cancel_job` `{id}` | Stop a job. It is the only way to: a tool call that is cancelled or times out stops waiting, and the job carries on. |
318
322
  | `get_replay` `{id}` | The job's steps with timings and what got in the way, and a link to its replay video (valid for an hour) when one was recorded. |
319
323
  | `list_saved_tasks` | Your saved tasks: id, name, settings, how often and when they last ran, and what their last run needed. |
320
324
  | `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?, wait_seconds?}` | Run a saved task with its saved settings, with optional changes for this run only. |
@@ -325,7 +329,7 @@ the monthly limit and spending by category and by model.
325
329
  | `list_logins` | Sites with saved logins in your Personal project: which accounts, whether a password and authenticator key are stored, what recent runs met there. Never a password or code. |
326
330
  | `manage_login` `{action, site, account?}` | Your Personal logins. `add`: a link to the app where you type the login yourself (never in the chat). `set_default`: the account tasks use on a site with several when they don't say. `delete`: forget one. `save_offered` / `discard_offered`: a sign-in a run offered for saving. |
327
331
  | `projects` `{action, id?, name?, days?}` | Admins: your organization's shared projects. `list` (each with its API keys, identities and this month's spend), `create`, `rename`, `delete` (wipes its identities, revokes its keys; its tasks' cost stays), `usage` (one project's spend by kind and per key over `days`), `keys` (its keys and what each spent). New API keys are made in the app (Org settings → API keys): a key's value never passes through a chat. |
328
- | `switch_project` `{project?}` | Which project your tasks run in: `personal`, `default` or a project's id or name. No argument lists them. Remembered for your next connections; an organization API key stays in its own. |
332
+ | `switch_project` `{project?}` | Which project your tasks run in: `personal`, `default` or a project's id or name. No argument lists them. Signed in (OAuth), remembered for your next connections; with a personal API key, for that connection only. An organization API key stays in its own. |
329
333
  | `identities` `{action, id?, external_user_id?, label?, query?, country?, device_os?, email?, save_logins?, sites?, account?, credential?}` | Your end users in a shared project. `list` (by `external_user_id` or `query`), `create`, `get` (logins by credential id, masked; signed-in sites; cost so far), `update`, `delete` (wipes logins, sessions and device; costs stay), `login_link` (`sites`: a one-time page for the user to type their own login), `set_default` and `delete_login` (by `credential`). |
330
334
  | `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` | Your sites and their settings, and change one site's: residential IP (`auto`, `always` or `never`), stealth browsing, CAPTCHA solving. A change applies to every later task on that site. |
331
335
  | `get_usage` `{days?}` | Your organization's credits as your role sees them (an admin: its balance and auto reload; a member: whether it is fine, low, out or at its limit), what is left of your allowance (or the key's), this month's spending against the organization's monthly limit, and the last `days` (default 30) of spending by category (model, residential IP, browser, CAPTCHA) and by model. |
@@ -334,8 +338,10 @@ the monthly limit and spending by category and by model.
334
338
 
335
339
  A finished job starts with `SUCCESS`, `PARTLY DONE` or `NOT DONE`. One that did not fully pass lists what of the task
336
340
  is done, what is not (each with its evidence) and why it stopped. Every finished job ends with a `Cost:` line (model,
337
- residential IP, browser, CAPTCHA) and a `Project:` line naming its project and identity. A job still running says `Still running after
338
- 120 s; the job carries on`, and your agent waits again with `get_job`. A job that needs a person shows the question,
341
+ residential IP, browser, CAPTCHA), a `Project:` line naming its project, and an `Identity:` line when it ran as one. A
342
+ job still running says `Still running after 120 s; the job carries on` (50 s for a client that takes no progress
343
+ updates), and your agent waits again with `get_job`. A tool call that is cancelled or times out leaves the job running
344
+ too: `get_job` (or `list_jobs`, for its id) gets it, and only `cancel_job` stops it. A job that needs a person shows the question,
339
345
  a `Question <id>` line saying how to answer it, and the answer link.
340
346
 
341
347
  ## Whole tasks or steps?
@@ -358,7 +364,8 @@ the site the search found; a price or availability for particular dates is alway
358
364
  ## When the person says more mid-task
359
365
 
360
366
  Your agent reads what the person types only between tool calls, so `browser_task`, `follow_up` and `get_job` return
361
- within two minutes by default while the task carries on. Anything the person says meanwhile (a correction, a detail,
367
+ within two minutes by default (50 s for a client that takes no progress updates, since most give up on a call after
368
+ 60 s) while the task carries on. Anything the person says meanwhile (a correction, a detail,
362
369
  the answer to the task's question) goes to the task with `message_job`, in their words, and the agent keeps waiting
363
370
  with `get_job`.
364
371
 
@@ -390,6 +397,10 @@ Only for this package (the relay). Clients that connect to the URL need none.
390
397
  - **401 Unauthorized:** the key was revoked or rotated, or your organization was deleted. Ask an admin for a current
391
398
  key (**Org settings → API keys**), or sign in from your client instead.
392
399
  - **Codex stops the call after a minute:** keep `tool_timeout_sec = 180` as above; the task itself carries on.
400
+ - **A call timed out or was cancelled:** the task carries on. `get_job {id}` gets its result (`list_jobs` lists the id);
401
+ `cancel_job` stops it.
402
+ - **Session not found (404):** pilotfish was updated, or the connection sat unused for 30 minutes. This relay opens a
403
+ new session by itself; a client connected by URL reconnects (restart it if it does not).
393
404
  - **`npx` fails, or the relay won't start:** check `node --version` is 22 or newer; on Windows, start it through
394
405
  `cmd /c` as above.
395
406
  - **`shared_project` or `personal_project`:** saved logins and saved tasks are in Personal, identities in a shared
package/cli.js CHANGED
@@ -10,7 +10,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
10
10
  import { isJSONRPCRequest, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
11
11
 
12
12
  // packages/mcp-managed/dist/version.js
13
- var VERSION = true ? "0.1.24" : "0.0.0-dev";
13
+ var VERSION = true ? "0.1.26" : "0.0.0-dev";
14
14
 
15
15
  // packages/mcp-managed/dist/bridge.js
16
16
  var DEFAULT_URL = "https://pilotfish-be.gai.ventures";
@@ -34,14 +34,22 @@ function remoteTransport(o) {
34
34
  function explain(e) {
35
35
  const m = e instanceof Error ? e.message : String(e);
36
36
  if (/\b401\b|unauthori[sz]ed/i.test(m))
37
- return "pilotfish refused the MCP key (revoked, rotated, mistyped, or its organization was deleted). Ask an admin of your organization for a current one (Org settings \u2192 API keys).";
37
+ return "pilotfish refused the API key (revoked, rotated, mistyped, or its organization was deleted). Ask an admin of your organization for a current one (Org settings \u2192 API keys).";
38
38
  if (/fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT/i.test(m))
39
39
  return `Cannot reach pilotfish (${m}). Check PILOTFISH_URL and your connection.`;
40
40
  return `pilotfish: ${m}`;
41
41
  }
42
+ function sessionGone(e) {
43
+ const code = e?.code;
44
+ return code === 404 || /\bHTTP 404\b|Session not found/i.test(e instanceof Error ? e.message : String(e));
45
+ }
42
46
  async function relay(local, o) {
43
- const remote = remoteTransport(o);
47
+ let remote = remoteTransport(o);
44
48
  const initIds = /* @__PURE__ */ new Set();
49
+ let initRequest = null;
50
+ let reopening = null;
51
+ const replays = /* @__PURE__ */ new Map();
52
+ let reopened = 0;
45
53
  let closed = false;
46
54
  const close = async () => {
47
55
  if (closed)
@@ -50,27 +58,88 @@ async function relay(local, o) {
50
58
  await remote.terminateSession().catch(() => void 0);
51
59
  await Promise.all([remote.close().catch(() => void 0), local.close().catch(() => void 0)]);
52
60
  };
53
- local.onmessage = (m) => {
54
- if (isJSONRPCRequest(m) && m.method === "initialize")
55
- initIds.add(m.id);
56
- remote.send(m).catch((e) => {
57
- o.log?.(explain(e));
58
- if (isJSONRPCRequest(m))
59
- void local.send({ jsonrpc: "2.0", id: m.id, error: { code: -32e3, message: explain(e) } }).catch(() => void 0);
61
+ const protocolFrom = (t, m) => {
62
+ const v = isJSONRPCResultResponse(m) ? m.result.protocolVersion : void 0;
63
+ if (typeof v === "string")
64
+ t.setProtocolVersion(v);
65
+ };
66
+ const wire = (t) => {
67
+ t.onmessage = (m) => {
68
+ if ("id" in m && m.id !== void 0 && replays.has(m.id) && !("method" in m)) {
69
+ replays.get(m.id)(m);
70
+ replays.delete(m.id);
71
+ return;
72
+ }
73
+ if (isJSONRPCResultResponse(m) && initIds.delete(m.id))
74
+ protocolFrom(t, m);
75
+ void local.send(m).catch((e) => o.log?.(`relay to client: ${e instanceof Error ? e.message : String(e)}`));
76
+ };
77
+ t.onerror = (e) => o.log?.(explain(e));
78
+ t.onclose = () => {
79
+ if (t === remote)
80
+ void close();
81
+ };
82
+ };
83
+ const reopen = (stale) => {
84
+ if (remote !== stale)
85
+ return reopening ?? Promise.resolve();
86
+ reopening ??= (async () => {
87
+ o.log?.("pilotfish ended the session (a restart or a long idle): opening a new one");
88
+ const next = remoteTransport(o);
89
+ wire(next);
90
+ remote = next;
91
+ void stale.close().catch(() => void 0);
92
+ await next.start();
93
+ const id = `pilotfish-relay-reinit-${++reopened}`;
94
+ let timer;
95
+ const answered = new Promise((resolve, reject) => {
96
+ replays.set(id, resolve);
97
+ timer = setTimeout(() => reject(new Error("pilotfish did not answer the new session in 30 s")), 3e4);
98
+ });
99
+ const res = await Promise.all([answered, next.send({ ...initRequest, id })]).then(([r]) => r).finally(() => {
100
+ clearTimeout(timer);
101
+ replays.delete(id);
102
+ });
103
+ if (!isJSONRPCResultResponse(res))
104
+ throw new Error(`pilotfish refused the new session: ${JSON.stringify(res.error ?? res)}`);
105
+ protocolFrom(next, res);
106
+ await next.send({ jsonrpc: "2.0", method: "notifications/initialized" });
107
+ })().finally(() => {
108
+ reopening = null;
60
109
  });
110
+ return reopening;
111
+ };
112
+ const fail = (m, e) => {
113
+ o.log?.(explain(e));
114
+ if (isJSONRPCRequest(m))
115
+ void local.send({ jsonrpc: "2.0", id: m.id, error: { code: -32e3, message: explain(e) } }).catch(() => void 0);
61
116
  };
62
- remote.onmessage = (m) => {
63
- if (isJSONRPCResultResponse(m) && initIds.delete(m.id)) {
64
- const v = m.result.protocolVersion;
65
- if (typeof v === "string")
66
- remote.setProtocolVersion(v);
117
+ local.onmessage = (m) => {
118
+ if (isJSONRPCRequest(m) && m.method === "initialize") {
119
+ initIds.add(m.id);
120
+ initRequest = m;
67
121
  }
68
- void local.send(m).catch((e) => o.log?.(`relay to client: ${e instanceof Error ? e.message : String(e)}`));
122
+ void (async () => {
123
+ if (reopening)
124
+ await reopening.catch(() => void 0);
125
+ const via = remote;
126
+ try {
127
+ await via.send(m);
128
+ } catch (e) {
129
+ if (!sessionGone(e) || !initRequest || m === initRequest || closed)
130
+ return fail(m, e);
131
+ try {
132
+ await reopen(via);
133
+ await remote.send(m);
134
+ } catch (e2) {
135
+ fail(m, e2);
136
+ }
137
+ }
138
+ })();
69
139
  };
70
- remote.onerror = (e) => o.log?.(explain(e));
140
+ wire(remote);
71
141
  local.onerror = (e) => o.log?.(`client transport: ${e.message}`);
72
142
  local.onclose = () => void close();
73
- remote.onclose = () => void close();
74
143
  await remote.start();
75
144
  await local.start();
76
145
  return { close };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gaiventures/pilotfish-mcp-managed",
3
- "version": "0.1.24",
3
+ "version": "0.1.26",
4
4
  "description": "Whole browser tasks done in pilotfish's cloud for any MCP agent, signed in with your saved logins. mcprush.com-37c48d491684ec6011385ea5",
5
5
  "license": "MIT",
6
6
  "type": "module",