@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.
- package/README.md +22 -12
- package/cli.js +87 -18
- 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 $
|
|
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
|
|
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)
|
|
180
|
-
your choice for your next connections.
|
|
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 `
|
|
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.
|
|
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.
|
|
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)
|
|
339
|
-
120 s; the job carries on
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
63
|
-
if (
|
|
64
|
-
|
|
65
|
-
|
|
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
|
|
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
|
|
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.
|
|
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",
|