@gaiventures/pilotfish-mcp-managed 0.1.25 → 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 +22 -12
  2. package/cli.js +87 -18
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -38,7 +38,7 @@ 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
44
  servers and shared agents use an API key instead (Org settings → API keys). The app's **MCP** page
@@ -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
 
@@ -176,8 +177,10 @@ Every task runs in a project.
176
177
  users. They hold no one's personal logins and no saved or scheduled tasks: each end user is an **identity** there. A
177
178
  task with no identity gets a fresh browser of its own, and nothing of it is kept for other sessions.
178
179
 
179
- Switch in the app's project switcher, or with `switch_project` (no argument lists your projects); the MCP remembers
180
- 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.
181
184
 
182
185
  ## Identities: tasks for your own users
183
186
 
@@ -261,7 +264,7 @@ Acme HR runs LinkedIn tasks for its users Priya (in India) and Rahul (in the US)
261
264
  the link in its own app; Priya signs in to LinkedIn there. Rahul does the same with his.
262
265
  3. Tasks by identity: `browser_task {identity: "idn_priya…", task: "Read my new LinkedIn messages and list who wrote"}`.
263
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.
264
- 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
265
268
  `GET /identities/idn_priya…/usage?since=…` for each user and bills them.
266
269
  5. Priya leaves: `identities {action: "delete", id: "idn_priya…"}` wipes her LinkedIn login, session and device. Her
267
270
  past tasks and their costs stay in Acme's usage.
@@ -306,8 +309,8 @@ the monthly limit and spending by category and by model.
306
309
 
307
310
  | Tool | What it does |
308
311
  | --- | --- |
309
- | `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). |
310
- | `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. |
311
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. |
312
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`. |
313
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. |
@@ -315,7 +318,7 @@ the monthly limit and spending by category and by model.
315
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. |
316
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. |
317
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. |
318
- | `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. |
319
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. |
320
323
  | `list_saved_tasks` | Your saved tasks: id, name, settings, how often and when they last ran, and what their last run needed. |
321
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. |
@@ -326,7 +329,7 @@ the monthly limit and spending by category and by model.
326
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. |
327
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. |
328
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. |
329
- | `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. |
330
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`). |
331
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. |
332
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. |
@@ -335,8 +338,10 @@ the monthly limit and spending by category and by model.
335
338
 
336
339
  A finished job starts with `SUCCESS`, `PARTLY DONE` or `NOT DONE`. One that did not fully pass lists what of the task
337
340
  is done, what is not (each with its evidence) and why it stopped. Every finished job ends with a `Cost:` line (model,
338
- residential IP, browser, CAPTCHA) and a `Project:` line naming its project and identity. A job still running says `Still running after
339
- 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,
340
345
  a `Question <id>` line saying how to answer it, and the answer link.
341
346
 
342
347
  ## Whole tasks or steps?
@@ -359,7 +364,8 @@ the site the search found; a price or availability for particular dates is alway
359
364
  ## When the person says more mid-task
360
365
 
361
366
  Your agent reads what the person types only between tool calls, so `browser_task`, `follow_up` and `get_job` return
362
- 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,
363
369
  the answer to the task's question) goes to the task with `message_job`, in their words, and the agent keeps waiting
364
370
  with `get_job`.
365
371
 
@@ -391,6 +397,10 @@ Only for this package (the relay). Clients that connect to the URL need none.
391
397
  - **401 Unauthorized:** the key was revoked or rotated, or your organization was deleted. Ask an admin for a current
392
398
  key (**Org settings → API keys**), or sign in from your client instead.
393
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).
394
404
  - **`npx` fails, or the relay won't start:** check `node --version` is 22 or newer; on Windows, start it through
395
405
  `cmd /c` as above.
396
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.25" : "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.25",
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",