@pmndre/pine 0.0.0-stage → 0.22.0
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/LICENSE +21 -0
- package/README.md +226 -2
- package/bin/pine.js +27 -0
- package/docs/SKILL.md +234 -0
- package/docs/references/agents.md +454 -0
- package/docs/references/coding.md +311 -0
- package/docs/references/computer.md +212 -0
- package/docs/references/configuration.md +310 -0
- package/docs/references/events.md +267 -0
- package/docs/references/mcp.md +420 -0
- package/docs/references/operations.md +394 -0
- package/docs/references/overview.md +195 -0
- package/docs/references/security.md +896 -0
- package/docs/references/setup.md +385 -0
- package/docs/references/sources.md +772 -0
- package/docs/references/stack.md +121 -0
- package/docs/references/tui.md +575 -0
- package/examples/home/.env.example +7 -0
- package/examples/home/USER.md +4 -0
- package/examples/home/agents/main/agent.json +4 -0
- package/examples/home/agents/main/workspace/AGENTS.md +14 -0
- package/examples/home/agents/main/workspace/MEMORY.md +4 -0
- package/examples/home/agents/main/workspace/SOUL.md +4 -0
- package/examples/home/models.json +62 -0
- package/examples/home/pine.json +34 -0
- package/examples/home/skills/README.txt +7 -0
- package/examples/launchd/com.pine.daemon.plist +32 -0
- package/examples/systemd/pine.service +22 -0
- package/mcp/browser.d.ts +99 -0
- package/mcp/browser.js +496 -0
- package/mcp/commands.d.ts +20 -0
- package/mcp/commands.js +88 -0
- package/mcp/computer.d.ts +139 -0
- package/mcp/computer.js +698 -0
- package/mcp/computer.swift +989 -0
- package/mcp/lib.d.ts +23 -0
- package/mcp/lib.js +52 -0
- package/mcp/web.d.ts +6 -0
- package/mcp/web.js +140 -0
- package/package.json +32 -4
- package/src/access.d.ts +112 -0
- package/src/access.js +438 -0
- package/src/actions.d.ts +75 -0
- package/src/actions.js +167 -0
- package/src/admin.d.ts +167 -0
- package/src/admin.js +625 -0
- package/src/agent-admin.d.ts +24 -0
- package/src/agent-admin.js +55 -0
- package/src/agents.d.ts +540 -0
- package/src/agents.js +2776 -0
- package/src/background.d.ts +29 -0
- package/src/background.js +100 -0
- package/src/cli.d.ts +2 -0
- package/src/cli.js +777 -0
- package/src/computer.d.ts +30 -0
- package/src/computer.js +32 -0
- package/src/config.d.ts +396 -0
- package/src/config.js +549 -0
- package/src/dev/claude-model.d.ts +37 -0
- package/src/dev/claude-model.js +204 -0
- package/src/env-file.d.ts +4 -0
- package/src/env-file.js +40 -0
- package/src/goals.d.ts +133 -0
- package/src/goals.js +316 -0
- package/src/http.d.ts +46 -0
- package/src/http.js +509 -0
- package/src/limiter.d.ts +32 -0
- package/src/limiter.js +84 -0
- package/src/login.d.ts +23 -0
- package/src/login.js +130 -0
- package/src/manual.d.ts +61 -0
- package/src/manual.js +443 -0
- package/src/mcp-config.d.ts +49 -0
- package/src/mcp-config.js +182 -0
- package/src/models.d.ts +90 -0
- package/src/models.js +274 -0
- package/src/net.d.ts +50 -0
- package/src/net.js +150 -0
- package/src/pine.d.ts +32 -0
- package/src/pine.js +134 -0
- package/src/programs.d.ts +123 -0
- package/src/programs.js +412 -0
- package/src/router.d.ts +56 -0
- package/src/router.js +164 -0
- package/src/sandbox-fs.d.ts +34 -0
- package/src/sandbox-fs.js +186 -0
- package/src/sandbox-linux.d.ts +96 -0
- package/src/sandbox-linux.js +297 -0
- package/src/sandbox-setup.d.ts +70 -0
- package/src/sandbox-setup.js +216 -0
- package/src/security.d.ts +238 -0
- package/src/security.js +660 -0
- package/src/skills.d.ts +67 -0
- package/src/skills.js +163 -0
- package/src/snapshots.d.ts +68 -0
- package/src/snapshots.js +306 -0
- package/src/source-types.d.ts +61 -0
- package/src/source-types.js +1 -0
- package/src/sources/command.d.ts +4 -0
- package/src/sources/command.js +77 -0
- package/src/sources/folder.d.ts +6 -0
- package/src/sources/folder.js +116 -0
- package/src/sources/ftp.d.ts +4 -0
- package/src/sources/ftp.js +307 -0
- package/src/sources/http.d.ts +4 -0
- package/src/sources/http.js +201 -0
- package/src/sources/mqtt.d.ts +18 -0
- package/src/sources/mqtt.js +97 -0
- package/src/sources/telegram.d.ts +22 -0
- package/src/sources/telegram.js +283 -0
- package/src/sources/webhook.d.ts +4 -0
- package/src/sources/webhook.js +52 -0
- package/src/sources.d.ts +344 -0
- package/src/sources.js +966 -0
- package/src/store.d.ts +99 -0
- package/src/store.js +277 -0
- package/src/timers.d.ts +83 -0
- package/src/timers.js +318 -0
- package/src/tools.d.ts +11 -0
- package/src/tools.js +1297 -0
- package/src/tui/app.d.ts +305 -0
- package/src/tui/app.js +3195 -0
- package/src/tui/client.d.ts +236 -0
- package/src/tui/client.js +131 -0
- package/src/tui/code-pane.d.ts +68 -0
- package/src/tui/code-pane.js +535 -0
- package/src/tui/highlight.d.ts +8 -0
- package/src/tui/highlight.js +86 -0
- package/src/tui/picture.d.ts +206 -0
- package/src/tui/picture.js +801 -0
- package/src/tui/run.d.ts +8 -0
- package/src/tui/run.js +97 -0
- package/src/tui/theme.d.ts +32 -0
- package/src/tui/theme.js +128 -0
- package/src/tui/undo.d.ts +5 -0
- package/src/tui/undo.js +50 -0
- package/src/tui/voice.d.ts +49 -0
- package/src/tui/voice.js +155 -0
- package/src/tui/voice.swift +223 -0
- package/src/types.d.ts +139 -0
- package/src/types.js +1 -0
- package/src/undo.d.ts +224 -0
- package/src/undo.js +465 -0
- package/src/update.d.ts +35 -0
- package/src/update.js +130 -0
- package/src/util.d.ts +65 -0
- package/src/util.js +171 -0
- package/src/watching.d.ts +20 -0
- package/src/watching.js +68 -0
- package/src/workspace-view.d.ts +72 -0
- package/src/workspace-view.js +221 -0
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { type McpServerConfig, type PineConfig } from "./config.ts";
|
|
2
|
+
/** Change a JSON configuration file in place, keeping what is not touched (including ${NAME} placeholders). */
|
|
3
|
+
export declare function editJson(file: string, change: (json: any) => void): void;
|
|
4
|
+
export declare function validateServer(cfg: PineConfig, name: string, server: McpServerConfig, agentId?: string): void;
|
|
5
|
+
/**
|
|
6
|
+
* A command line as its program and arguments. No shell reads it, so what only a shell would act
|
|
7
|
+
* on is refused instead of being handed to the program as text.
|
|
8
|
+
*/
|
|
9
|
+
export declare function splitCommand(line: string): string[];
|
|
10
|
+
/**
|
|
11
|
+
* Add or replace an MCP server: in pine.json for everyone, or in one agent's agent.json. The file
|
|
12
|
+
* and the loaded configuration are both updated; sessions pick the server up when they next start.
|
|
13
|
+
*/
|
|
14
|
+
export declare function addServer(cfg: PineConfig, name: string, server: McpServerConfig, agentId?: string): void;
|
|
15
|
+
/** The name under which a key of a server's environment is kept in .env. */
|
|
16
|
+
export declare function mcpEnvName(server: string, agentId: string | undefined, variable: string): string;
|
|
17
|
+
export declare function removeServer(cfg: PineConfig, name: string, agentId?: string): boolean;
|
|
18
|
+
export interface ServerInfo {
|
|
19
|
+
name: string;
|
|
20
|
+
/** "global", or the id of the agent that owns it. */
|
|
21
|
+
scope: string;
|
|
22
|
+
/** The one conversation of that agent that has it, when it was added for a conversation alone. */
|
|
23
|
+
session?: string;
|
|
24
|
+
/** Agents that end up with it. */
|
|
25
|
+
agents: string[];
|
|
26
|
+
target: string;
|
|
27
|
+
remote: boolean;
|
|
28
|
+
taints: boolean;
|
|
29
|
+
approve: string;
|
|
30
|
+
enabled: boolean;
|
|
31
|
+
}
|
|
32
|
+
export declare function listServers(cfg: PineConfig): ServerInfo[];
|
|
33
|
+
export declare function findServer(cfg: PineConfig, name: string, agentId?: string): McpServerConfig | undefined;
|
|
34
|
+
/**
|
|
35
|
+
* Run pi's own `mcp` command (list, login, logout) for the given servers. pi keeps OAuth tokens per
|
|
36
|
+
* server name and URL in its agent folder; pine points that folder at data/pi, which is where the
|
|
37
|
+
* daemon's sessions look too. The servers are written to a temporary mcp.json there, because the
|
|
38
|
+
* command only knows that file. The daemon's sessions never read that file (see createMcpExtension
|
|
39
|
+
* in agents.ts), so it cannot hand a server to an agent that is not meant to have it.
|
|
40
|
+
*/
|
|
41
|
+
export declare function piMcp(cfg: PineConfig, servers: Record<string, McpServerConfig>, args: string[], opts?: {
|
|
42
|
+
capture?: boolean;
|
|
43
|
+
onOutput?: (text: string) => void;
|
|
44
|
+
}): Promise<{
|
|
45
|
+
code: number;
|
|
46
|
+
out: string;
|
|
47
|
+
}>;
|
|
48
|
+
/** Connection state of every configured server, as pi reports it ("connected", "needs sign-in", an error). */
|
|
49
|
+
export declare function serverStates(cfg: PineConfig): Promise<Record<string, string>>;
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import fs from "node:fs";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
import { mcpTaints, toPiMcp } from "./config.js";
|
|
6
|
+
import { unsetEnv } from "./env-file.js";
|
|
7
|
+
/** Change a JSON configuration file in place, keeping what is not touched (including ${NAME} placeholders). */
|
|
8
|
+
export function editJson(file, change) {
|
|
9
|
+
const json = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
10
|
+
change(json);
|
|
11
|
+
const mode = fs.statSync(file).mode & 0o777;
|
|
12
|
+
fs.writeFileSync(file, `${JSON.stringify(json, null, 2)}\n`, { mode });
|
|
13
|
+
}
|
|
14
|
+
const fileFor = (cfg, agentId) => (agentId ? path.join(cfg.agents[agentId].dir, "agent.json") : path.join(cfg.home, "pine.json"));
|
|
15
|
+
export function validateServer(cfg, name, server, agentId) {
|
|
16
|
+
if (!/^[A-Za-z0-9_-]{1,40}$/.test(name))
|
|
17
|
+
throw new Error(`"${name}" is not a usable server name (letters, digits, - and _)`);
|
|
18
|
+
if (agentId && !cfg.agents[agentId])
|
|
19
|
+
throw new Error(`unknown agent "${agentId}"`);
|
|
20
|
+
if (!server.url && !server.command && !server.pine)
|
|
21
|
+
throw new Error("an MCP server needs a url, a command, or the name of a bundled server");
|
|
22
|
+
if (server.url) {
|
|
23
|
+
let url;
|
|
24
|
+
try {
|
|
25
|
+
url = new URL(server.url);
|
|
26
|
+
}
|
|
27
|
+
catch {
|
|
28
|
+
throw new Error(`"${server.url}" is not a valid URL`);
|
|
29
|
+
}
|
|
30
|
+
if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))
|
|
31
|
+
throw new Error("a remote MCP server must use https");
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* A command line as its program and arguments. No shell reads it, so what only a shell would act
|
|
36
|
+
* on is refused instead of being handed to the program as text.
|
|
37
|
+
*/
|
|
38
|
+
export function splitCommand(line) {
|
|
39
|
+
const out = [];
|
|
40
|
+
let cur = "";
|
|
41
|
+
let quote = "";
|
|
42
|
+
let open = false;
|
|
43
|
+
for (const ch of line.trim()) {
|
|
44
|
+
if (quote) {
|
|
45
|
+
if (ch === quote)
|
|
46
|
+
quote = "";
|
|
47
|
+
else
|
|
48
|
+
cur += ch;
|
|
49
|
+
}
|
|
50
|
+
else if (ch === '"' || ch === "'") {
|
|
51
|
+
quote = ch;
|
|
52
|
+
open = true;
|
|
53
|
+
}
|
|
54
|
+
else if (/\s/.test(ch)) {
|
|
55
|
+
if (cur || open)
|
|
56
|
+
out.push(cur);
|
|
57
|
+
cur = "";
|
|
58
|
+
open = false;
|
|
59
|
+
}
|
|
60
|
+
else if ("|&;<>`$()".includes(ch))
|
|
61
|
+
throw new Error(`a server is one program with its arguments. "${ch}" means something to a shell only, and no shell runs this; leave it out`);
|
|
62
|
+
else
|
|
63
|
+
cur += ch;
|
|
64
|
+
}
|
|
65
|
+
if (quote)
|
|
66
|
+
throw new Error("a quote in the command is not closed");
|
|
67
|
+
if (cur || open)
|
|
68
|
+
out.push(cur);
|
|
69
|
+
return out;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Add or replace an MCP server: in pine.json for everyone, or in one agent's agent.json. The file
|
|
73
|
+
* and the loaded configuration are both updated; sessions pick the server up when they next start.
|
|
74
|
+
*/
|
|
75
|
+
export function addServer(cfg, name, server, agentId) {
|
|
76
|
+
validateServer(cfg, name, server, agentId);
|
|
77
|
+
editJson(fileFor(cfg, agentId), (json) => {
|
|
78
|
+
json.mcp ??= {};
|
|
79
|
+
json.mcp[name] = server;
|
|
80
|
+
});
|
|
81
|
+
(agentId ? cfg.agents[agentId].mcp : cfg.mcp)[name] = server;
|
|
82
|
+
}
|
|
83
|
+
/** The name under which a key of a server's environment is kept in .env. */
|
|
84
|
+
export function mcpEnvName(server, agentId, variable) {
|
|
85
|
+
return `PINE_MCP_${[server, ...(agentId ? [agentId] : []), variable].join("_").replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()}`;
|
|
86
|
+
}
|
|
87
|
+
export function removeServer(cfg, name, agentId) {
|
|
88
|
+
const target = agentId ? cfg.agents[agentId]?.mcp : cfg.mcp;
|
|
89
|
+
if (!target || !(name in target))
|
|
90
|
+
return false;
|
|
91
|
+
const kept = [];
|
|
92
|
+
editJson(fileFor(cfg, agentId), (json) => {
|
|
93
|
+
// The keys pine put into .env for it go too. One the owner wrote there under a name of their own stays.
|
|
94
|
+
for (const value of Object.values(json.mcp?.[name]?.env ?? {})) {
|
|
95
|
+
const m = typeof value === "string" ? /^\$\{(PINE_MCP_[A-Z0-9_]+)\}$/.exec(value) : null;
|
|
96
|
+
if (m)
|
|
97
|
+
kept.push(m[1]);
|
|
98
|
+
}
|
|
99
|
+
delete json.mcp?.[name];
|
|
100
|
+
// Nothing is left behind: an empty list of servers is no entry at all.
|
|
101
|
+
if (json.mcp && !Object.keys(json.mcp).length)
|
|
102
|
+
delete json.mcp;
|
|
103
|
+
});
|
|
104
|
+
unsetEnv(cfg.home, kept);
|
|
105
|
+
delete target[name];
|
|
106
|
+
return true;
|
|
107
|
+
}
|
|
108
|
+
export function listServers(cfg) {
|
|
109
|
+
const describe = (s) => s.url ?? (s.pine ? `bundled: ${s.pine}` : [s.command, ...(s.args ?? [])].join(" "));
|
|
110
|
+
const out = [];
|
|
111
|
+
for (const [name, s] of Object.entries(cfg.mcp)) {
|
|
112
|
+
const agents = Object.values(cfg.agents).filter((a) => {
|
|
113
|
+
if (name in a.mcp)
|
|
114
|
+
return false;
|
|
115
|
+
const scope = s.agents ?? ["*"];
|
|
116
|
+
return a.globalMcp === true ? scope.includes("*") || scope.includes(a.id) : Array.isArray(a.globalMcp) && a.globalMcp.includes(name);
|
|
117
|
+
});
|
|
118
|
+
out.push({ name, scope: "global", agents: agents.map((a) => a.id), target: describe(s), remote: Boolean(s.url), taints: mcpTaints(s), approve: s.approve ?? "never", enabled: s.enabled !== false });
|
|
119
|
+
}
|
|
120
|
+
for (const a of Object.values(cfg.agents))
|
|
121
|
+
for (const [name, s] of Object.entries(a.mcp))
|
|
122
|
+
out.push({ name, scope: a.id, ...(s.session ? { session: s.session } : {}), agents: [a.id], target: describe(s), remote: Boolean(s.url), taints: mcpTaints(s), approve: s.approve ?? "never", enabled: s.enabled !== false });
|
|
123
|
+
return out;
|
|
124
|
+
}
|
|
125
|
+
export function findServer(cfg, name, agentId) {
|
|
126
|
+
if (agentId)
|
|
127
|
+
return cfg.agents[agentId]?.mcp[name];
|
|
128
|
+
return cfg.mcp[name] ?? Object.values(cfg.agents).map((a) => a.mcp[name]).find(Boolean);
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* Run pi's own `mcp` command (list, login, logout) for the given servers. pi keeps OAuth tokens per
|
|
132
|
+
* server name and URL in its agent folder; pine points that folder at data/pi, which is where the
|
|
133
|
+
* daemon's sessions look too. The servers are written to a temporary mcp.json there, because the
|
|
134
|
+
* command only knows that file. The daemon's sessions never read that file (see createMcpExtension
|
|
135
|
+
* in agents.ts), so it cannot hand a server to an agent that is not meant to have it.
|
|
136
|
+
*/
|
|
137
|
+
export function piMcp(cfg, servers, args, opts = {}) {
|
|
138
|
+
const dir = path.join(cfg.dataDir, "pi");
|
|
139
|
+
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
140
|
+
const file = path.join(dir, "mcp.json");
|
|
141
|
+
const mcpServers = Object.fromEntries(Object.entries(servers).map(([name, s]) => [name, toPiMcp(name, s)]));
|
|
142
|
+
fs.writeFileSync(file, JSON.stringify({ mcpServers }, null, 2), { mode: 0o600 });
|
|
143
|
+
const cli = path.join(path.dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "bundle", "cli.js");
|
|
144
|
+
return new Promise((resolve) => {
|
|
145
|
+
const child = spawn(process.execPath, [cli, "mcp", ...args], {
|
|
146
|
+
cwd: dir,
|
|
147
|
+
env: { ...process.env, PI_CODING_AGENT_DIR: dir, PI_SKIP_VERSION_CHECK: "1", PI_TELEMETRY: "0" },
|
|
148
|
+
stdio: opts.capture ? ["ignore", "pipe", "pipe"] : "inherit",
|
|
149
|
+
});
|
|
150
|
+
let out = "";
|
|
151
|
+
const take = (d) => {
|
|
152
|
+
out += d;
|
|
153
|
+
opts.onOutput?.(d.toString("utf8"));
|
|
154
|
+
};
|
|
155
|
+
child.stdout?.on("data", take);
|
|
156
|
+
child.stderr?.on("data", take);
|
|
157
|
+
const done = (code) => {
|
|
158
|
+
fs.rmSync(file, { force: true });
|
|
159
|
+
resolve({ code, out });
|
|
160
|
+
};
|
|
161
|
+
child.on("error", (e) => ((out += e.message), done(1)));
|
|
162
|
+
child.on("close", (code) => done(code ?? 1));
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
/** Connection state of every configured server, as pi reports it ("connected", "needs sign-in", an error). */
|
|
166
|
+
export async function serverStates(cfg) {
|
|
167
|
+
const all = {};
|
|
168
|
+
for (const a of Object.values(cfg.agents))
|
|
169
|
+
Object.assign(all, a.mcp);
|
|
170
|
+
Object.assign(all, cfg.mcp);
|
|
171
|
+
const enabled = Object.fromEntries(Object.entries(all).filter(([, s]) => s.enabled !== false));
|
|
172
|
+
if (!Object.keys(enabled).length)
|
|
173
|
+
return {};
|
|
174
|
+
const { out } = await piMcp(cfg, enabled, ["list"], { capture: true });
|
|
175
|
+
const states = {};
|
|
176
|
+
for (const line of out.split("\n")) {
|
|
177
|
+
const m = line.match(/^([A-Za-z0-9_-]+): (.+?)(?: \([^)]*\))?$/);
|
|
178
|
+
if (m && m[1] in enabled)
|
|
179
|
+
states[m[1]] = m[2];
|
|
180
|
+
}
|
|
181
|
+
return states;
|
|
182
|
+
}
|
package/src/models.d.ts
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import type { PineConfig } from "./config.ts";
|
|
3
|
+
/**
|
|
4
|
+
* The API keys that models.json takes from pine's .env file, by provider, and what is wrong:
|
|
5
|
+
* a name that is nowhere, or a header that names an .env entry (pi reads headers itself, so
|
|
6
|
+
* only `apiKey` can).
|
|
7
|
+
*/
|
|
8
|
+
export declare function modelKeys(home: string): {
|
|
9
|
+
keys: Record<string, string>;
|
|
10
|
+
problems: string[];
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* Where the model servers of models.json are. The daemon gives requests to these their own
|
|
14
|
+
* timeouts (pi has none for a stream that goes quiet), so one that is added later is put here
|
|
15
|
+
* before the first request to it.
|
|
16
|
+
*/
|
|
17
|
+
export declare const modelOrigins: Set<string>;
|
|
18
|
+
/** pi's model runtime on pine's home, with the keys from .env in place. */
|
|
19
|
+
export declare function modelRuntime(home: string, warn?: (problem: string) => void): Promise<ModelRuntime>;
|
|
20
|
+
export interface ServerModel {
|
|
21
|
+
id: string;
|
|
22
|
+
/** Tokens of context one request gets, where the server says. */
|
|
23
|
+
contextWindow?: number;
|
|
24
|
+
images: boolean;
|
|
25
|
+
reasoning: boolean;
|
|
26
|
+
/**
|
|
27
|
+
* For a model that thinks, on a server that says so (llama.cpp): the levels of effort its chat
|
|
28
|
+
* template tells apart, lowest first. Its own default is not among them.
|
|
29
|
+
*/
|
|
30
|
+
efforts?: string[];
|
|
31
|
+
}
|
|
32
|
+
/** What a server answered: its models, or that it wants a key first. */
|
|
33
|
+
export type Look = {
|
|
34
|
+
locked: true;
|
|
35
|
+
} | {
|
|
36
|
+
locked: false;
|
|
37
|
+
models: ServerModel[];
|
|
38
|
+
};
|
|
39
|
+
/** The name under which a server's key is kept in .env. */
|
|
40
|
+
export declare const modelKeyName: (name: string) => string;
|
|
41
|
+
/** The address as it goes into models.json: http or https, no sign-in in it, "/v1" where no path is given. */
|
|
42
|
+
export declare function serverUrl(text: string): string;
|
|
43
|
+
export declare function checkServerName(name: string, taken: readonly string[]): void;
|
|
44
|
+
/**
|
|
45
|
+
* What is sent for each of pi's thinking levels, for a model whose template knows `efforts`.
|
|
46
|
+
* Without this a level the template does not know is answered with the template's default,
|
|
47
|
+
* which is often its highest, and "off" sends nothing at all, so thinking stays on.
|
|
48
|
+
* - off: "none", which is how llama.cpp turns thinking off.
|
|
49
|
+
* - a level the template knows: itself.
|
|
50
|
+
* - a level it does not know: the next one up that it does (never less than was asked for).
|
|
51
|
+
* - a level above all it knows is left out: pi lowers xhigh and max to the highest there is,
|
|
52
|
+
* and "high" goes as it is, to the template's own default.
|
|
53
|
+
*/
|
|
54
|
+
export declare function effortMap(efforts: string[]): Record<string, string>;
|
|
55
|
+
/**
|
|
56
|
+
* Ask a server what it serves. Nothing follows a redirect: the address the owner agreed to is
|
|
57
|
+
* the only one that gets a request, and the only one that sees the key.
|
|
58
|
+
*/
|
|
59
|
+
export declare function lookAt(baseUrl: string, key?: string): Promise<Look>;
|
|
60
|
+
export interface NewServer {
|
|
61
|
+
name: string;
|
|
62
|
+
baseUrl: string;
|
|
63
|
+
/** The server's key. It goes into .env; the file gets its name. */
|
|
64
|
+
key?: string;
|
|
65
|
+
models: ServerModel[];
|
|
66
|
+
/** For models whose context the server does not say. */
|
|
67
|
+
context?: number;
|
|
68
|
+
/** Overrides what the server says about thinking. */
|
|
69
|
+
reasoning?: boolean;
|
|
70
|
+
}
|
|
71
|
+
/** Write a server into models.json, and its key into .env. Returns its models as "provider/id". */
|
|
72
|
+
export declare function addModelServer(home: string, server: NewServer): string[];
|
|
73
|
+
/** Who has a model of this server set: agents, the default, the judge of goals. */
|
|
74
|
+
export declare function modelServerUsers(cfg: PineConfig, name: string): string[];
|
|
75
|
+
/** Take a server out of models.json again, with the key pine keeps for it. False when there is none of that name. */
|
|
76
|
+
export declare function removeModelServer(cfg: PineConfig, name: string): boolean;
|
|
77
|
+
export interface ServerInfo {
|
|
78
|
+
name: string;
|
|
79
|
+
baseUrl: string;
|
|
80
|
+
/** Where its key comes from, in words. */
|
|
81
|
+
key: string;
|
|
82
|
+
models: Array<{
|
|
83
|
+
id: string;
|
|
84
|
+
contextWindow?: number;
|
|
85
|
+
images: boolean;
|
|
86
|
+
reasoning: boolean;
|
|
87
|
+
}>;
|
|
88
|
+
}
|
|
89
|
+
/** The model servers in models.json. */
|
|
90
|
+
export declare function listModelServers(home: string): ServerInfo[];
|
package/src/models.js
ADDED
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { parseEnv } from "node:util";
|
|
4
|
+
import { setEnv, unsetEnv } from "./env-file.js";
|
|
5
|
+
import { errText } from "./util.js";
|
|
6
|
+
// models.json is pi's file, and pi fills a "$NAME" in it from the process environment. pine's
|
|
7
|
+
// secrets are in .env and are kept out of that environment on purpose (agent shells and MCP
|
|
8
|
+
// servers would inherit them). So a provider's API key that names an .env entry is filled in
|
|
9
|
+
// here and handed to pi as a key it holds in memory: it is in no file and in no environment.
|
|
10
|
+
/** pi's form for a value: "$NAME" or "${NAME}" is a variable, "$$" a dollar sign, "$!" an exclamation mark. */
|
|
11
|
+
const REF = /\$(?:([$!])|\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g;
|
|
12
|
+
const namesIn = (value) => [...new Set([...value.matchAll(REF)].map((m) => m[2] ?? m[3]).filter(Boolean))];
|
|
13
|
+
function read(make, otherwise) {
|
|
14
|
+
try {
|
|
15
|
+
return make();
|
|
16
|
+
}
|
|
17
|
+
catch {
|
|
18
|
+
return otherwise;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* The API keys that models.json takes from pine's .env file, by provider, and what is wrong:
|
|
23
|
+
* a name that is nowhere, or a header that names an .env entry (pi reads headers itself, so
|
|
24
|
+
* only `apiKey` can).
|
|
25
|
+
*/
|
|
26
|
+
export function modelKeys(home) {
|
|
27
|
+
const keys = {};
|
|
28
|
+
const problems = [];
|
|
29
|
+
// A missing or broken models.json is reported where pi loads it.
|
|
30
|
+
const providers = read(() => JSON.parse(fs.readFileSync(path.join(home, "models.json"), "utf8")).providers, undefined) ?? {};
|
|
31
|
+
const envFile = path.join(home, ".env");
|
|
32
|
+
const fileEnv = read(() => parseEnv(fs.readFileSync(envFile, "utf8")), {});
|
|
33
|
+
const known = (name) => fileEnv[name] || process.env[name] || undefined;
|
|
34
|
+
for (const [id, provider] of Object.entries(providers)) {
|
|
35
|
+
for (const [header, value] of Object.entries(provider?.headers ?? {})) {
|
|
36
|
+
const named = typeof value === "string" && !value.startsWith("!") ? namesIn(value).filter((name) => fileEnv[name] && !process.env[name]) : [];
|
|
37
|
+
if (named.length)
|
|
38
|
+
problems.push(`models.json: provider "${id}", header "${header}" names ${named.join(", ")} from .env. Only "apiKey" is filled in from .env`);
|
|
39
|
+
}
|
|
40
|
+
const raw = provider?.apiKey;
|
|
41
|
+
// "!command" is a program pi runs, and a key without a name in it is the key itself.
|
|
42
|
+
if (typeof raw !== "string" || raw.startsWith("!"))
|
|
43
|
+
continue;
|
|
44
|
+
const names = namesIn(raw);
|
|
45
|
+
if (!names.length)
|
|
46
|
+
continue;
|
|
47
|
+
const missing = names.filter((name) => !known(name));
|
|
48
|
+
if (missing.length) {
|
|
49
|
+
problems.push(`models.json: provider "${id}" takes its key from ${missing.join(", ")}, which ${missing.length === 1 ? "is" : "are"} not in ${envFile}. Its models are not available until you add ${missing.length === 1 ? "a line" : "lines"} ${missing.map((name) => `${name}=...`).join(", ")} there`);
|
|
50
|
+
continue;
|
|
51
|
+
}
|
|
52
|
+
// pi fills in what the environment alone answers.
|
|
53
|
+
if (!names.some((name) => fileEnv[name]))
|
|
54
|
+
continue;
|
|
55
|
+
keys[id] = raw.replace(REF, (_all, escaped, braced, bare) => escaped ?? known(braced ?? bare));
|
|
56
|
+
}
|
|
57
|
+
return { keys, problems };
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Where the model servers of models.json are. The daemon gives requests to these their own
|
|
61
|
+
* timeouts (pi has none for a stream that goes quiet), so one that is added later is put here
|
|
62
|
+
* before the first request to it.
|
|
63
|
+
*/
|
|
64
|
+
export const modelOrigins = new Set();
|
|
65
|
+
function noteOrigins(home) {
|
|
66
|
+
const providers = read(() => JSON.parse(fs.readFileSync(path.join(home, "models.json"), "utf8")).providers, undefined) ?? {};
|
|
67
|
+
for (const p of Object.values(providers)) {
|
|
68
|
+
const origin = typeof p?.baseUrl === "string" ? read(() => new URL(p.baseUrl).origin, undefined) : undefined;
|
|
69
|
+
if (origin)
|
|
70
|
+
modelOrigins.add(origin);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
/** pi's model runtime on pine's home, with the keys from .env in place. */
|
|
74
|
+
export async function modelRuntime(home, warn = () => { }) {
|
|
75
|
+
noteOrigins(home);
|
|
76
|
+
// Loaded here so that commands which only look at the keys (pine check) do not load pi.
|
|
77
|
+
const { ModelRuntime } = await import("@earendil-works/pi-coding-agent");
|
|
78
|
+
const runtime = await ModelRuntime.create({ authPath: path.join(home, "auth.json"), modelsPath: path.join(home, "models.json") });
|
|
79
|
+
const { keys, problems } = modelKeys(home);
|
|
80
|
+
for (const [provider, key] of Object.entries(keys))
|
|
81
|
+
await runtime.setRuntimeApiKey(provider, key);
|
|
82
|
+
for (const problem of problems)
|
|
83
|
+
warn(problem);
|
|
84
|
+
return runtime;
|
|
85
|
+
}
|
|
86
|
+
const MODEL_ID = /^[A-Za-z0-9._:@/+=,()[\]-]{1,160}$/;
|
|
87
|
+
const SERVER_NAME = /^[a-z][a-z0-9-]{0,30}$/;
|
|
88
|
+
/** The name under which a server's key is kept in .env. */
|
|
89
|
+
export const modelKeyName = (name) => `PINE_MODEL_${name.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()}_API_KEY`;
|
|
90
|
+
/** The address as it goes into models.json: http or https, no sign-in in it, "/v1" where no path is given. */
|
|
91
|
+
export function serverUrl(text) {
|
|
92
|
+
const url = read(() => new URL(text.trim()), undefined);
|
|
93
|
+
if (!url || (url.protocol !== "http:" && url.protocol !== "https:"))
|
|
94
|
+
throw new Error(`"${text}" is not the address of a model server. Give it as http://host:port, for example http://127.0.0.1:8080`);
|
|
95
|
+
if (url.username || url.password)
|
|
96
|
+
throw new Error("the address must not contain a user name or password; a server's key is asked for separately and kept in .env");
|
|
97
|
+
if (url.search || url.hash)
|
|
98
|
+
throw new Error("the address must not contain a query or a fragment");
|
|
99
|
+
const pathname = url.pathname.replace(/\/+$/, "");
|
|
100
|
+
return `${url.origin}${pathname || "/v1"}`;
|
|
101
|
+
}
|
|
102
|
+
export function checkServerName(name, taken) {
|
|
103
|
+
if (!SERVER_NAME.test(name))
|
|
104
|
+
throw new Error(`"${name}" is not a usable name for a model server: lowercase letters, digits and -, starting with a letter (for example studio)`);
|
|
105
|
+
if (taken.includes(name))
|
|
106
|
+
throw new Error(`a model provider called "${name}" exists already; pick another name`);
|
|
107
|
+
}
|
|
108
|
+
/** The levels of effort a request can name, lowest first. */
|
|
109
|
+
const EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"];
|
|
110
|
+
/**
|
|
111
|
+
* What is sent for each of pi's thinking levels, for a model whose template knows `efforts`.
|
|
112
|
+
* Without this a level the template does not know is answered with the template's default,
|
|
113
|
+
* which is often its highest, and "off" sends nothing at all, so thinking stays on.
|
|
114
|
+
* - off: "none", which is how llama.cpp turns thinking off.
|
|
115
|
+
* - a level the template knows: itself.
|
|
116
|
+
* - a level it does not know: the next one up that it does (never less than was asked for).
|
|
117
|
+
* - a level above all it knows is left out: pi lowers xhigh and max to the highest there is,
|
|
118
|
+
* and "high" goes as it is, to the template's own default.
|
|
119
|
+
*/
|
|
120
|
+
export function effortMap(efforts) {
|
|
121
|
+
const map = { off: "none" };
|
|
122
|
+
const known = EFFORTS.filter((level) => efforts.includes(level));
|
|
123
|
+
for (const level of EFFORTS) {
|
|
124
|
+
const next = known.find((k) => EFFORTS.indexOf(k) >= EFFORTS.indexOf(level));
|
|
125
|
+
if (next)
|
|
126
|
+
map[level] = next;
|
|
127
|
+
}
|
|
128
|
+
return map;
|
|
129
|
+
}
|
|
130
|
+
const positive = (n) => (typeof n === "number" && Number.isInteger(n) && n > 0 ? n : undefined);
|
|
131
|
+
/**
|
|
132
|
+
* Ask a server what it serves. Nothing follows a redirect: the address the owner agreed to is
|
|
133
|
+
* the only one that gets a request, and the only one that sees the key.
|
|
134
|
+
*/
|
|
135
|
+
export async function lookAt(baseUrl, key) {
|
|
136
|
+
modelOrigins.add(new URL(baseUrl).origin);
|
|
137
|
+
const get = async (url) => {
|
|
138
|
+
try {
|
|
139
|
+
return await fetch(url, { headers: key ? { authorization: `Bearer ${key}` } : {}, redirect: "error", signal: AbortSignal.timeout(10_000) });
|
|
140
|
+
}
|
|
141
|
+
catch (e) {
|
|
142
|
+
throw new Error(`no model server answers at ${url} (${errText(e?.cause ?? e)})`);
|
|
143
|
+
}
|
|
144
|
+
};
|
|
145
|
+
const res = await get(`${baseUrl}/models`);
|
|
146
|
+
if (res.status === 401 || res.status === 403)
|
|
147
|
+
return { locked: true };
|
|
148
|
+
const body = res.ok ? await res.json().catch(() => undefined) : undefined;
|
|
149
|
+
const list = Array.isArray(body?.data) ? body.data : undefined;
|
|
150
|
+
if (!list)
|
|
151
|
+
throw new Error(`${baseUrl}/models did not answer with a list of models${res.ok ? "" : ` (HTTP ${res.status})`}. A server that speaks OpenAI's API has one there; check the address and its path`);
|
|
152
|
+
// llama.cpp says in /props what one request really gets: the context of a slot, and whether it reads pictures.
|
|
153
|
+
let props;
|
|
154
|
+
if (baseUrl.endsWith("/v1") && list.length === 1) {
|
|
155
|
+
const r = await get(`${baseUrl.slice(0, -3)}/props`).catch(() => undefined);
|
|
156
|
+
props = r?.ok ? await r.json().catch(() => undefined) : undefined;
|
|
157
|
+
}
|
|
158
|
+
const models = [];
|
|
159
|
+
for (const m of list.slice(0, 100)) {
|
|
160
|
+
// A name is shown to agents and written into the file, so it is a name and nothing else.
|
|
161
|
+
if (typeof m?.id !== "string" || !MODEL_ID.test(m.id))
|
|
162
|
+
continue;
|
|
163
|
+
const caps = props?.chat_template_caps;
|
|
164
|
+
const reasoning = caps?.supports_reasoning_effort === true;
|
|
165
|
+
models.push({
|
|
166
|
+
id: m.id,
|
|
167
|
+
contextWindow: positive(props?.default_generation_settings?.n_ctx) ?? positive(m.max_model_len) ?? positive(m.context_length) ?? positive(m.context_window),
|
|
168
|
+
images: props?.modalities?.vision === true || (Array.isArray(m.architecture?.input_modalities) && m.architecture.input_modalities.includes("image")),
|
|
169
|
+
reasoning,
|
|
170
|
+
// Only the names pine knows are kept: what a server says goes into a file.
|
|
171
|
+
...(reasoning ? { efforts: EFFORTS.filter((level) => Array.isArray(caps.reasoning_effort_levels) && caps.reasoning_effort_levels.includes(level)) } : {}),
|
|
172
|
+
});
|
|
173
|
+
}
|
|
174
|
+
if (!models.length)
|
|
175
|
+
throw new Error(`${baseUrl} lists no model with a usable name${list.length ? ` (it has ${list.length}, named with spaces or other characters; llama-server takes a plain name with --alias)` : ""}`);
|
|
176
|
+
return { locked: false, models };
|
|
177
|
+
}
|
|
178
|
+
const modelsFile = (home) => path.join(home, "models.json");
|
|
179
|
+
function editModels(home, change) {
|
|
180
|
+
const file = modelsFile(home);
|
|
181
|
+
const json = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
|
|
182
|
+
json.providers ??= {};
|
|
183
|
+
change(json.providers);
|
|
184
|
+
fs.writeFileSync(file, `${JSON.stringify(json, null, 2)}\n`, { mode: 0o600 });
|
|
185
|
+
}
|
|
186
|
+
/** Write a server into models.json, and its key into .env. Returns its models as "provider/id". */
|
|
187
|
+
export function addModelServer(home, server) {
|
|
188
|
+
const unsized = server.models.filter((m) => !m.contextWindow && !server.context).map((m) => m.id);
|
|
189
|
+
if (unsized.length)
|
|
190
|
+
throw new Error(`the server does not say how much context ${unsized.length === 1 ? `its model ${unsized[0]} gets` : "its models get"}. Give it: the number of tokens one request may use (what the server was started with)`);
|
|
191
|
+
if (server.context !== undefined && !positive(server.context))
|
|
192
|
+
throw new Error("the context is a whole number of tokens, for example 65536");
|
|
193
|
+
const entry = {
|
|
194
|
+
name: `${server.name} (${new URL(server.baseUrl).host})`,
|
|
195
|
+
baseUrl: server.baseUrl,
|
|
196
|
+
api: "openai-completions",
|
|
197
|
+
apiKey: server.key ? `$${modelKeyName(server.name)}` : "none",
|
|
198
|
+
models: server.models.map((m) => {
|
|
199
|
+
const contextWindow = server.context ?? m.contextWindow;
|
|
200
|
+
const reasoning = server.reasoning ?? m.reasoning;
|
|
201
|
+
// Where the server said which levels the model knows, the level chosen in pine is the one it gets.
|
|
202
|
+
const mapped = reasoning && m.efforts !== undefined;
|
|
203
|
+
return {
|
|
204
|
+
id: m.id,
|
|
205
|
+
contextWindow,
|
|
206
|
+
maxTokens: Math.min(8192, Math.floor(contextWindow / 2)),
|
|
207
|
+
input: m.images ? ["text", "image"] : ["text"],
|
|
208
|
+
...(reasoning ? { reasoning: true } : {}),
|
|
209
|
+
...(mapped ? { thinkingLevelMap: effortMap(m.efforts) } : {}),
|
|
210
|
+
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
211
|
+
// What a plain server may reject is not sent.
|
|
212
|
+
compat: { supportsStore: false, supportsDeveloperRole: false, supportsReasoningEffort: reasoning, ...(mapped ? { thinkingFormat: "openai" } : {}), maxTokensField: "max_tokens" },
|
|
213
|
+
};
|
|
214
|
+
}),
|
|
215
|
+
};
|
|
216
|
+
// Checked before anything is written: the key of a server that is there must not be touched.
|
|
217
|
+
const there = read(() => JSON.parse(fs.readFileSync(modelsFile(home), "utf8")).providers, undefined) ?? {};
|
|
218
|
+
if (there[server.name])
|
|
219
|
+
throw new Error(`a model provider called "${server.name}" exists already; pick another name`);
|
|
220
|
+
if (server.key)
|
|
221
|
+
setEnv(home, { [modelKeyName(server.name)]: server.key });
|
|
222
|
+
try {
|
|
223
|
+
editModels(home, (providers) => {
|
|
224
|
+
providers[server.name] = entry;
|
|
225
|
+
});
|
|
226
|
+
}
|
|
227
|
+
catch (e) {
|
|
228
|
+
if (server.key)
|
|
229
|
+
unsetEnv(home, [modelKeyName(server.name)]);
|
|
230
|
+
throw e;
|
|
231
|
+
}
|
|
232
|
+
return entry.models.map((m) => `${server.name}/${m.id}`);
|
|
233
|
+
}
|
|
234
|
+
/** Who has a model of this server set: agents, the default, the judge of goals. */
|
|
235
|
+
export function modelServerUsers(cfg, name) {
|
|
236
|
+
const of = (ref) => typeof ref === "string" && ref.startsWith(`${name}/`);
|
|
237
|
+
return [
|
|
238
|
+
...Object.values(cfg.agents).filter((a) => of(a.model)).map((a) => `agent ${a.id}`),
|
|
239
|
+
...(of(cfg.defaults.model) ? [`the default model (${Object.values(cfg.agents).filter((a) => !a.model).map((a) => a.id).join(", ") || "no agent right now"})`] : []),
|
|
240
|
+
...(of(cfg.defaults.judge) ? ["the judge of goals (defaults.judge)"] : []),
|
|
241
|
+
];
|
|
242
|
+
}
|
|
243
|
+
/** Take a server out of models.json again, with the key pine keeps for it. False when there is none of that name. */
|
|
244
|
+
export function removeModelServer(cfg, name) {
|
|
245
|
+
const providers = read(() => JSON.parse(fs.readFileSync(modelsFile(cfg.home), "utf8")).providers, undefined) ?? {};
|
|
246
|
+
if (!providers[name])
|
|
247
|
+
return false;
|
|
248
|
+
const users = modelServerUsers(cfg, name);
|
|
249
|
+
if (users.length)
|
|
250
|
+
throw new Error(`"${name}" is in use by ${users.join(", ")}. Give ${users.length === 1 ? "it" : "them"} another model first (/model in the terminal UI)`);
|
|
251
|
+
const key = modelKeyName(name);
|
|
252
|
+
// The key pine put into .env goes too. One the owner named themselves stays.
|
|
253
|
+
const ours = [`$${key}`, `\${${key}}`].includes(providers[name].apiKey);
|
|
254
|
+
editModels(cfg.home, (all) => {
|
|
255
|
+
delete all[name];
|
|
256
|
+
});
|
|
257
|
+
if (ours)
|
|
258
|
+
unsetEnv(cfg.home, [key]);
|
|
259
|
+
return true;
|
|
260
|
+
}
|
|
261
|
+
/** The model servers in models.json. */
|
|
262
|
+
export function listModelServers(home) {
|
|
263
|
+
const providers = read(() => JSON.parse(fs.readFileSync(modelsFile(home), "utf8")).providers, undefined) ?? {};
|
|
264
|
+
return Object.entries(providers).filter(([, p]) => typeof p?.baseUrl === "string").map(([name, p]) => {
|
|
265
|
+
const raw = typeof p.apiKey === "string" ? p.apiKey : "";
|
|
266
|
+
const names = raw.startsWith("!") ? [] : namesIn(raw);
|
|
267
|
+
return {
|
|
268
|
+
name,
|
|
269
|
+
baseUrl: p.baseUrl,
|
|
270
|
+
key: raw.startsWith("!") ? "from a command" : names.length ? `${names.join(", ")} in .env` : !raw || raw === "none" ? "none" : "written in models.json",
|
|
271
|
+
models: (Array.isArray(p.models) ? p.models : []).filter((m) => typeof m?.id === "string").map((m) => ({ id: m.id, contextWindow: positive(m.contextWindow), images: Array.isArray(m.input) && m.input.includes("image"), reasoning: m.reasoning === true })),
|
|
272
|
+
};
|
|
273
|
+
});
|
|
274
|
+
}
|
package/src/net.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { Agent } from "undici";
|
|
2
|
+
/** Addresses that are not on the public internet: loopback, private ranges, link-local, multicast. */
|
|
3
|
+
export declare function isPrivateAddress(ip: string): boolean;
|
|
4
|
+
/**
|
|
5
|
+
* Connections that refuse private addresses. The check runs when the connection is made, on the
|
|
6
|
+
* address actually used, so a DNS answer that changes between check and use does not help an attacker.
|
|
7
|
+
*/
|
|
8
|
+
export declare function publicOnlyAgent(timeoutMs: number, allowPrivate?: boolean): Agent;
|
|
9
|
+
/** Names that say by themselves that they are on this computer or the local network. */
|
|
10
|
+
export declare const isLocalName: (host: string) => boolean;
|
|
11
|
+
/** "host:port" the way a web address writes it. */
|
|
12
|
+
export declare const hostPort: (host: string, port: number) => string;
|
|
13
|
+
/**
|
|
14
|
+
* A web address whose host says by itself that it is this computer or the local network:
|
|
15
|
+
* "localhost", a ".local" name, an IP address in a private range. A name that only turns out to
|
|
16
|
+
* be local when it is looked up is not one: what such a name points at can change after a yes.
|
|
17
|
+
*/
|
|
18
|
+
export declare function localTarget(raw: unknown): {
|
|
19
|
+
host: string;
|
|
20
|
+
port: number;
|
|
21
|
+
key: string;
|
|
22
|
+
} | undefined;
|
|
23
|
+
export interface Fetched {
|
|
24
|
+
/** A file with a random name in the system's temp folder. The caller moves or deletes it. */
|
|
25
|
+
file: string;
|
|
26
|
+
url: string;
|
|
27
|
+
bytes: number;
|
|
28
|
+
sha256: string;
|
|
29
|
+
type: string;
|
|
30
|
+
/** Every hop was one of the trusted origins. */
|
|
31
|
+
trusted: boolean;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Download an address to a temporary file, byte for byte.
|
|
35
|
+
*
|
|
36
|
+
* `trusted` are origins the owner has already connected the caller to (its MCP servers): they are
|
|
37
|
+
* fetched as they are. Any other address is fetched only when `open` is set, and then only over
|
|
38
|
+
* https and never from a private or local address. Redirects are followed by the same rules.
|
|
39
|
+
* `headers` says what to send along to a trusted address (a server's key, for a link it gave).
|
|
40
|
+
*/
|
|
41
|
+
export declare function fetchToFile(o: {
|
|
42
|
+
url: string;
|
|
43
|
+
trusted: Set<string>;
|
|
44
|
+
open: boolean | ((host: string) => string | true);
|
|
45
|
+
allowPrivate?: boolean;
|
|
46
|
+
maxBytes: number;
|
|
47
|
+
timeoutMs?: number;
|
|
48
|
+
signal?: AbortSignal;
|
|
49
|
+
headers?: (url: URL) => Record<string, string> | undefined;
|
|
50
|
+
}): Promise<Fetched>;
|