ekl-cli 0.10.0__py3-none-any.whl
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.
- ekl_cli/__init__.py +2 -0
- ekl_cli/bridge.py +160 -0
- ekl_cli/client.py +232 -0
- ekl_cli/clients/.agents/plugins/marketplace.json +20 -0
- ekl_cli/clients/.claude-plugin/marketplace.json +16 -0
- ekl_cli/clients/README.md +3 -0
- ekl_cli/clients/claude-code/.claude-plugin/plugin.json +14 -0
- ekl_cli/clients/claude-code/.mcp.json +10 -0
- ekl_cli/clients/claude-code/commands/check.md +11 -0
- ekl_cli/clients/claude-code/commands/deploy.md +49 -0
- ekl_cli/clients/claude-code/commands/status.md +10 -0
- ekl_cli/clients/claude-code/skills/agent-behaviour/SKILL.md +112 -0
- ekl_cli/clients/claude-code/skills/agent-config-in-repo/SKILL.md +92 -0
- ekl_cli/clients/claude-code/skills/connect-mcp-server/SKILL.md +296 -0
- ekl_cli/clients/claude-code/skills/operate-agent/SKILL.md +54 -0
- ekl_cli/clients/claude-code/skills/plan-with-the-network/SKILL.md +60 -0
- ekl_cli/clients/codex/mcp.json +11 -0
- ekl_cli/clients/codex/plugin.json +8 -0
- ekl_cli/clients/codex/skills/agent-behaviour/SKILL.md +112 -0
- ekl_cli/clients/codex/skills/agent-config-in-repo/SKILL.md +92 -0
- ekl_cli/clients/codex/skills/connect-mcp-server/SKILL.md +296 -0
- ekl_cli/clients/codex/skills/operate-agent/SKILL.md +54 -0
- ekl_cli/clients/codex/skills/plan-with-the-network/SKILL.md +60 -0
- ekl_cli/clients/cursor/.cursor-plugin/plugin.json +8 -0
- ekl_cli/clients/cursor/commands/check.md +11 -0
- ekl_cli/clients/cursor/commands/deploy.md +49 -0
- ekl_cli/clients/cursor/commands/status.md +10 -0
- ekl_cli/clients/cursor/mcp.json +10 -0
- ekl_cli/clients/cursor/rules/eukollab.mdc +81 -0
- ekl_cli/clients/cursor/skills/agent-behaviour/SKILL.md +112 -0
- ekl_cli/clients/cursor/skills/agent-config-in-repo/SKILL.md +92 -0
- ekl_cli/clients/cursor/skills/connect-mcp-server/SKILL.md +296 -0
- ekl_cli/clients/cursor/skills/operate-agent/SKILL.md +54 -0
- ekl_cli/clients/cursor/skills/plan-with-the-network/SKILL.md +60 -0
- ekl_cli/clients/gemini/GEMINI.md +76 -0
- ekl_cli/clients/gemini/gemini-extension.json +14 -0
- ekl_cli/clients/generic/AGENTS.md +76 -0
- ekl_cli/clients/generic/mcp.json +10 -0
- ekl_cli/clients/vscode/instructions/eukollab.instructions.md +80 -0
- ekl_cli/clients/vscode/mcp.json +11 -0
- ekl_cli/command_help.py +223 -0
- ekl_cli/declarations.py +492 -0
- ekl_cli/deploy.py +432 -0
- ekl_cli/deploy_command.py +556 -0
- ekl_cli/derive.py +217 -0
- ekl_cli/design.py +339 -0
- ekl_cli/finder.py +695 -0
- ekl_cli/icon.py +102 -0
- ekl_cli/install.py +185 -0
- ekl_cli/lifecycle.py +357 -0
- ekl_cli/main.py +643 -0
- ekl_cli/mcp.py +279 -0
- ekl_cli/messages.py +245 -0
- ekl_cli/onboard.py +1040 -0
- ekl_cli/participation.py +247 -0
- ekl_cli/project.py +211 -0
- ekl_cli/prompt.py +176 -0
- ekl_cli/py.typed +0 -0
- ekl_cli/release_root.json +9 -0
- ekl_cli/release_trust.py +376 -0
- ekl_cli/repair.py +266 -0
- ekl_cli/schema.py +117 -0
- ekl_cli/setup.py +326 -0
- ekl_cli/supervise.py +162 -0
- ekl_cli/templates/python/eukollab-agent.md.tmpl +202 -0
- ekl_cli/templates/python/eukollab_callbacks.py.tmpl +509 -0
- ekl_cli/templates/versions.json +3 -0
- ekl_cli/ui.py +158 -0
- ekl_cli/versions.py +402 -0
- ekl_cli-0.10.0.dist-info/METADATA +72 -0
- ekl_cli-0.10.0.dist-info/RECORD +75 -0
- ekl_cli-0.10.0.dist-info/WHEEL +5 -0
- ekl_cli-0.10.0.dist-info/entry_points.txt +2 -0
- ekl_cli-0.10.0.dist-info/licenses/LICENSE +10 -0
- ekl_cli-0.10.0.dist-info/top_level.txt +1 -0
ekl_cli/deploy.py
ADDED
|
@@ -0,0 +1,432 @@
|
|
|
1
|
+
# Copyright © 2026 EuKreate, Inc. All rights reserved.
|
|
2
|
+
"""The agent folder and the agent run on this machine: what `ekl deploy` starts for a local server (spec 13.14.8).
|
|
3
|
+
|
|
4
|
+
The folder `ekl add` writes: agent.json, its declarations and .env, for the publisher's working MCP server; on this
|
|
5
|
+
machine the connector (`ekl-provider-connector`, from the `ekl-provider-adapter` package) serves it in front of that
|
|
6
|
+
server, its calls relayed by the network; for an agent that only uses services, the connector's use-only mode runs its
|
|
7
|
+
callbacks and nothing is relayed. Commands run with argument lists, never a shell, and secret values reach the
|
|
8
|
+
process in its environment, never on a command line.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
import argparse
|
|
12
|
+
import base64
|
|
13
|
+
import gzip
|
|
14
|
+
import json
|
|
15
|
+
import os
|
|
16
|
+
import re
|
|
17
|
+
import shlex
|
|
18
|
+
import shutil
|
|
19
|
+
import socket
|
|
20
|
+
import subprocess
|
|
21
|
+
import sys
|
|
22
|
+
import time
|
|
23
|
+
from collections.abc import Iterable
|
|
24
|
+
from dataclasses import dataclass
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Any, TextIO
|
|
27
|
+
|
|
28
|
+
from ekl_cli import project, prompt, supervise
|
|
29
|
+
from ekl_cli.client import CliError
|
|
30
|
+
from ekl_cli.mcp import upstream_headers
|
|
31
|
+
|
|
32
|
+
REQUIRED_ENV = ("EKL_PROVIDER_CREDENTIAL", "EKL_NETWORK_URL", "EKL_UPSTREAM_MCP_URL")
|
|
33
|
+
OPTIONAL_ENV = (
|
|
34
|
+
"EKL_UPSTREAM_HEADERS",
|
|
35
|
+
"EKL_AGENT_CREDENTIAL",
|
|
36
|
+
"EKL_ADAPTER_STORAGE",
|
|
37
|
+
"EKL_LOCAL_TOKEN",
|
|
38
|
+
"EKL_CALLBACK_KEY",
|
|
39
|
+
"EKL_AGENT_ID",
|
|
40
|
+
)
|
|
41
|
+
# Values that grant access: the agent key and credential, the server's address (it may carry the server's own token)
|
|
42
|
+
# and headers (they usually carry its key), and the journal store's URL (it may carry a password). They are redacted
|
|
43
|
+
# from everything printed.
|
|
44
|
+
SECRET_ENV = (
|
|
45
|
+
"EKL_PROVIDER_CREDENTIAL",
|
|
46
|
+
"EKL_AGENT_CREDENTIAL",
|
|
47
|
+
"EKL_UPSTREAM_MCP_URL",
|
|
48
|
+
"EKL_UPSTREAM_HEADERS",
|
|
49
|
+
"EKL_ADAPTER_STORAGE",
|
|
50
|
+
"EKL_LOCAL_TOKEN",
|
|
51
|
+
"EKL_CALLBACK_KEY",
|
|
52
|
+
)
|
|
53
|
+
# What a use-only connector reads (an agent that only uses services): the agent takes part with its credential, its
|
|
54
|
+
# events go to its callbacks file, and its journal store is optional.
|
|
55
|
+
USE_ONLY_ENV = (
|
|
56
|
+
"EKL_AGENT_CREDENTIAL",
|
|
57
|
+
"EKL_ADAPTER_STORAGE",
|
|
58
|
+
"EKL_LOCAL_TOKEN",
|
|
59
|
+
"EKL_CALLBACK_KEY",
|
|
60
|
+
"EKL_AGENT_ID",
|
|
61
|
+
)
|
|
62
|
+
PORT = 8000
|
|
63
|
+
# The callbacks `ekl add` writes; the connector runs them itself when the agent takes part.
|
|
64
|
+
CALLBACKS_FILE = "eukollab_callbacks.py"
|
|
65
|
+
PACKAGE, ENTRY = "ekl-provider-adapter", "ekl-provider-connector"
|
|
66
|
+
# ekl-<name> names the container; kept short enough for the hosts it is taken to.
|
|
67
|
+
NAME = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,26}[a-z0-9])?$")
|
|
68
|
+
REDACTED = "<redacted>"
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
# --- the machine ---------------------------------------------------------------------------------------------------
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
@dataclass(frozen=True)
|
|
75
|
+
class Done:
|
|
76
|
+
"""A finished command: its exit code and captured output."""
|
|
77
|
+
|
|
78
|
+
code: int
|
|
79
|
+
out: str = ""
|
|
80
|
+
err: str = ""
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class Runner:
|
|
84
|
+
"""Every command deploy runs and every fact it reads from this machine, in one place, so tests replace it."""
|
|
85
|
+
|
|
86
|
+
def which(self, name: str) -> str | None:
|
|
87
|
+
return shutil.which(name)
|
|
88
|
+
|
|
89
|
+
def exists(self, path: str) -> bool:
|
|
90
|
+
return Path(path).exists()
|
|
91
|
+
|
|
92
|
+
def environ(self, name: str) -> str | None:
|
|
93
|
+
return os.environ.get(name)
|
|
94
|
+
|
|
95
|
+
def run(self, argv: list[str], input_text: str | None = None, cwd: Path | None = None) -> Done:
|
|
96
|
+
try:
|
|
97
|
+
done = subprocess.run(argv, input=input_text, capture_output=True, text=True, check=False, cwd=cwd)
|
|
98
|
+
except FileNotFoundError:
|
|
99
|
+
return Done(127, err=f"{argv[0]}: command not found")
|
|
100
|
+
return Done(done.returncode, done.stdout, done.stderr)
|
|
101
|
+
|
|
102
|
+
def background(self, folder: Path, launch: "Launch") -> dict[str, Any]:
|
|
103
|
+
"""Start the agent supervised in the background (`ekl deploy` for a server on this machine)."""
|
|
104
|
+
return supervise.start(folder, launch.argv, launch.env, launch.cwd, launch.about)
|
|
105
|
+
|
|
106
|
+
def settled(self, folder: Path, seconds: float = 3.0) -> bool:
|
|
107
|
+
"""Whether the agent started in the background is still running a moment later, not stopping at once."""
|
|
108
|
+
time.sleep(seconds)
|
|
109
|
+
return not any("ekl: the agent stopped" in line for line in supervise.tail(folder, 5))
|
|
110
|
+
|
|
111
|
+
def interactive(self) -> bool:
|
|
112
|
+
"""Whether to ask: someone is at the terminal and --yes wasn't given."""
|
|
113
|
+
return prompt.interactive()
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class Session:
|
|
117
|
+
"""Runs a destination's commands, or under --print only lists them with secrets redacted."""
|
|
118
|
+
|
|
119
|
+
def __init__(self, runner: Runner, *, dry: bool, secrets: Iterable[str], stream: TextIO | None) -> None:
|
|
120
|
+
self.runner = runner
|
|
121
|
+
self.dry = dry
|
|
122
|
+
self.secrets = sorted({s for s in secrets if s}, key=len, reverse=True)
|
|
123
|
+
self.stream = stream
|
|
124
|
+
self.lines: list[str] = []
|
|
125
|
+
|
|
126
|
+
def redact(self, text: str) -> str:
|
|
127
|
+
for secret in self.secrets:
|
|
128
|
+
text = text.replace(secret, REDACTED)
|
|
129
|
+
return text
|
|
130
|
+
|
|
131
|
+
def show(self, argv: list[str]) -> str:
|
|
132
|
+
return self.redact(shlex.join(argv))
|
|
133
|
+
|
|
134
|
+
def say(self, line: str) -> None:
|
|
135
|
+
self.lines.append(line)
|
|
136
|
+
if self.stream is not None and not self.dry:
|
|
137
|
+
print(line, file=self.stream, flush=True)
|
|
138
|
+
|
|
139
|
+
def act(
|
|
140
|
+
self,
|
|
141
|
+
argv: list[str],
|
|
142
|
+
what: str,
|
|
143
|
+
*,
|
|
144
|
+
input_text: str | None = None,
|
|
145
|
+
tolerate: tuple[str, ...] = (),
|
|
146
|
+
cwd: Path | None = None,
|
|
147
|
+
) -> Any:
|
|
148
|
+
"""A change. `tolerate` names errors that mean it is already so (an ingress rule that exists)."""
|
|
149
|
+
if self.dry:
|
|
150
|
+
self.lines.append(f" $ {self.show(argv)}" + (" < " + REDACTED if input_text else ""))
|
|
151
|
+
return {}
|
|
152
|
+
self.say(f" {what}")
|
|
153
|
+
done = self.runner.run(argv, input_text, cwd)
|
|
154
|
+
if done.code:
|
|
155
|
+
if any(marker in done.err for marker in tolerate):
|
|
156
|
+
return {}
|
|
157
|
+
raise CliError("EKL-408", self.redact(done.err.strip() or done.out.strip()), command=self.show(argv))
|
|
158
|
+
try:
|
|
159
|
+
return json.loads(done.out) if done.out.strip() else {}
|
|
160
|
+
except json.JSONDecodeError:
|
|
161
|
+
return {"output": done.out}
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
@dataclass
|
|
165
|
+
class Need:
|
|
166
|
+
"""A requirement on this machine. ok None: it could not be told; that never stops a deploy."""
|
|
167
|
+
|
|
168
|
+
label: str
|
|
169
|
+
ok: bool | None
|
|
170
|
+
fix: str = ""
|
|
171
|
+
|
|
172
|
+
def lines(self, indent: str = " ") -> list[str]:
|
|
173
|
+
mark = {True: "✓", False: "✗", None: "?"}[self.ok]
|
|
174
|
+
out = [f"{indent}{mark} {self.label}"]
|
|
175
|
+
if self.fix and self.ok is not True:
|
|
176
|
+
out += [f"{indent} {line}" for line in self.fix.splitlines()]
|
|
177
|
+
return out
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
# --- the agent -----------------------------------------------------------------------------------------------------
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
@dataclass
|
|
184
|
+
class Agent:
|
|
185
|
+
"""The agent folder being deployed: its agent.json, its .env and the name its resources carry (ekl-<name>)."""
|
|
186
|
+
|
|
187
|
+
directory: Path
|
|
188
|
+
content: dict[str, Any]
|
|
189
|
+
env: dict[str, str]
|
|
190
|
+
name: str
|
|
191
|
+
|
|
192
|
+
@property
|
|
193
|
+
def handle(self) -> str:
|
|
194
|
+
return str(self.content["agent"]["handle"])
|
|
195
|
+
|
|
196
|
+
@property
|
|
197
|
+
def secret_names(self) -> list[str]:
|
|
198
|
+
return [v for v in SECRET_ENV if self.env.get(v)]
|
|
199
|
+
|
|
200
|
+
@property
|
|
201
|
+
def secrets(self) -> list[str]:
|
|
202
|
+
return [self.env[k] for k in self.secret_names]
|
|
203
|
+
|
|
204
|
+
def announced(self, endpoint: str | None) -> str:
|
|
205
|
+
"""agent.json as the connector receives it in EKL_AGENT_JSON: the terms file inlined (the connector has no
|
|
206
|
+
folder to read it from) and the deployed endpoint, or none until it is known (it then announces nothing)."""
|
|
207
|
+
content = json.loads(json.dumps(self.content))
|
|
208
|
+
terms = content.get("terms") or {}
|
|
209
|
+
if terms.get("text_file") and not terms.get("text"):
|
|
210
|
+
text_path = self.directory / str(terms["text_file"])
|
|
211
|
+
if not text_path.exists():
|
|
212
|
+
raise CliError("EKL-214", file=terms["text_file"], folder=self.directory)
|
|
213
|
+
content["terms"] = {**terms, "text": text_path.read_text()}
|
|
214
|
+
content["terms"].pop("text_file")
|
|
215
|
+
adapter = content.setdefault("adapter", {})
|
|
216
|
+
if endpoint:
|
|
217
|
+
adapter["endpoint"] = endpoint
|
|
218
|
+
else:
|
|
219
|
+
adapter.pop("endpoint", None)
|
|
220
|
+
return json.dumps(content, separators=(",", ":"), ensure_ascii=False)
|
|
221
|
+
|
|
222
|
+
def connector_env(self, endpoint: str | None, port: int = PORT) -> dict[str, str]:
|
|
223
|
+
"""The connector's whole environment: agent.json base64-encoded, so it needs no quoting, and the callbacks the
|
|
224
|
+
connector runs itself when the agent takes part."""
|
|
225
|
+
found = {v: self.env[v] for v in (*REQUIRED_ENV, *OPTIONAL_ENV) if self.env.get(v)}
|
|
226
|
+
found["EKL_AGENT_JSON"] = base64.b64encode(self.announced(endpoint).encode()).decode()
|
|
227
|
+
callbacks = self.directory / CALLBACKS_FILE
|
|
228
|
+
if found.get("EKL_AGENT_CREDENTIAL") and callbacks.is_file():
|
|
229
|
+
# The connector runs the callbacks itself, so they need no host of their own; gzip keeps the value small.
|
|
230
|
+
packed = gzip.compress(callbacks.read_bytes(), mtime=0)
|
|
231
|
+
found["EKL_CALLBACKS_PY"] = base64.b64encode(packed).decode()
|
|
232
|
+
if endpoint:
|
|
233
|
+
found["EKL_ADAPTER_ENDPOINT"] = endpoint
|
|
234
|
+
found["PORT"] = str(port)
|
|
235
|
+
return found
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def urllib_host(url: str) -> str:
|
|
239
|
+
"""The host of a URL, lowercased, without user info, port or IPv6 brackets; empty when it has none."""
|
|
240
|
+
match = re.match(r"^[a-z][a-z0-9+.-]*://(?:[^@/]*@)?(\[[^\]]+\]|[^:/?#]+)", url, re.I)
|
|
241
|
+
return (match.group(1).strip("[]") if match else "").lower()
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
def load_agent(directory: Path, name: str | None) -> Agent:
|
|
245
|
+
"""The agent folder: agent.json, and the .env beside it."""
|
|
246
|
+
file = directory / "agent.json"
|
|
247
|
+
if not file.exists():
|
|
248
|
+
raise CliError("EKL-201", folder=directory)
|
|
249
|
+
try:
|
|
250
|
+
content: dict[str, Any] = json.loads(file.read_text())
|
|
251
|
+
except json.JSONDecodeError as exc:
|
|
252
|
+
raise CliError("EKL-202", str(exc), path=file) from exc
|
|
253
|
+
handle = str((content.get("agent") or {}).get("handle") or "")
|
|
254
|
+
if not handle:
|
|
255
|
+
raise CliError("EKL-203", path=file)
|
|
256
|
+
env = project.read_env(directory / ".env")
|
|
257
|
+
missing = [v for v in REQUIRED_ENV if not env.get(v)]
|
|
258
|
+
if missing:
|
|
259
|
+
raise CliError("EKL-206", env=directory / ".env", names=", ".join(missing))
|
|
260
|
+
# Refused here rather than by the connector once deployed: a malformed value would stop it at start.
|
|
261
|
+
upstream_headers(env.get("EKL_UPSTREAM_HEADERS"))
|
|
262
|
+
chosen = name or handle.removeprefix("@")
|
|
263
|
+
if not NAME.match(chosen):
|
|
264
|
+
raise CliError("EKL-407", name=chosen)
|
|
265
|
+
return Agent(directory, content, env, chosen)
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
adapter_version = project.adapter_version
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
def package_index(network: str) -> str:
|
|
272
|
+
"""EuKollab's packages come from its network's own index until they are published elsewhere."""
|
|
273
|
+
return f"{network.rstrip('/')}/simple/"
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
# --- what every destination shares ---------------------------------------------------------------------------------
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
@dataclass
|
|
280
|
+
class Context:
|
|
281
|
+
"""One run of `ekl deploy`: what a destination reads and writes. `notes` are lines added to the summary."""
|
|
282
|
+
|
|
283
|
+
args: argparse.Namespace
|
|
284
|
+
runner: Runner
|
|
285
|
+
session: Session
|
|
286
|
+
agent: Agent | None
|
|
287
|
+
|
|
288
|
+
@property
|
|
289
|
+
def a(self) -> Agent:
|
|
290
|
+
if self.agent is None:
|
|
291
|
+
raise CliError("EKL-900", "No agent folder was loaded.")
|
|
292
|
+
return self.agent
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def _cancel_if_failing(needs: list[Need], destination: str) -> None:
|
|
296
|
+
failing = [n for n in needs if n.ok is False]
|
|
297
|
+
if failing:
|
|
298
|
+
lines = [line for n in failing for line in n.lines()]
|
|
299
|
+
raise CliError("EKL-406", *lines, destination=destination)
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
# --- the connector on this machine ---------------------------------------------------------------------------------
|
|
303
|
+
|
|
304
|
+
|
|
305
|
+
class Launcher:
|
|
306
|
+
"""How `ekl deploy` starts the connector here, for a local server: with uv, `uvx --from ekl-provider-adapter`
|
|
307
|
+
from the network's package index; without it, a virtual environment in <dir>/.ekl."""
|
|
308
|
+
|
|
309
|
+
@staticmethod
|
|
310
|
+
def needs(ctx: Context) -> list[Need]:
|
|
311
|
+
uv, python = ctx.runner.which("uvx"), ctx.runner.which("python3.13")
|
|
312
|
+
label = "uv (it runs the connector on Python 3.13)" if uv else "Python 3.13 (python3.13)"
|
|
313
|
+
return [Need(label, bool(uv or python), "install uv, or Python 3.13")]
|
|
314
|
+
|
|
315
|
+
@staticmethod
|
|
316
|
+
def command(ctx: Context, listen: list[str]) -> list[str]:
|
|
317
|
+
"""The connector's command line on this machine, ending with `listen` (--relay)."""
|
|
318
|
+
index = package_index(ctx.a.env["EKL_NETWORK_URL"])
|
|
319
|
+
spec = f"{PACKAGE}>={adapter_version()}"
|
|
320
|
+
if uvx := ctx.runner.which("uvx"):
|
|
321
|
+
# --index is searched before PyPI and wins for the packages it has (uv's first-index strategy).
|
|
322
|
+
# Pinned: uv otherwise picks the newest Python it has, where the connector's dependencies may have no
|
|
323
|
+
# wheels yet.
|
|
324
|
+
if source := ctx.runner.environ("EKL_CONNECTOR_SOURCE"):
|
|
325
|
+
# Development: a checkout of the adapter, rebuilt each run, in place of the published package.
|
|
326
|
+
return [uvx, "--python", "3.13", "--no-cache", "--from", source, ENTRY, *listen]
|
|
327
|
+
return [uvx, "--python", "3.13", "--index", index, "--from", spec, ENTRY, *listen]
|
|
328
|
+
venv = ctx.a.directory / ".ekl" / "connector-venv"
|
|
329
|
+
scripts = venv / ("Scripts" if os.name == "nt" else "bin")
|
|
330
|
+
python = ctx.runner.which("python3.13") or sys.executable
|
|
331
|
+
if not ctx.runner.exists(str(venv)):
|
|
332
|
+
ctx.session.act([python, "-m", "venv", str(venv)], f"creating a virtual environment in {venv}")
|
|
333
|
+
_gitignore(ctx.a.directory, ".ekl/")
|
|
334
|
+
pinned = project.adapter_requirement(ctx.a.env["EKL_NETWORK_URL"])
|
|
335
|
+
ctx.session.act([str(scripts / "pip"), "install", "--quiet", "--upgrade", pinned], f"installing {spec}")
|
|
336
|
+
return [str(scripts / ENTRY), *listen]
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
def _gitignore(directory: Path, entry: str) -> None:
|
|
340
|
+
path = directory / ".gitignore"
|
|
341
|
+
lines = path.read_text().splitlines() if path.exists() else []
|
|
342
|
+
if entry not in lines:
|
|
343
|
+
path.write_text("\n".join([*lines, entry]) + "\n")
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
LOCAL_API_PORT = 8765
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
@dataclass(frozen=True)
|
|
350
|
+
class Launch:
|
|
351
|
+
"""The agent's process on this machine, as `ekl deploy` starts it: the command, its environment
|
|
352
|
+
(secrets included, given to the process directly), the folder it runs in, and what it is, in a line."""
|
|
353
|
+
|
|
354
|
+
argv: list[str]
|
|
355
|
+
env: dict[str, str]
|
|
356
|
+
cwd: Path | None
|
|
357
|
+
about: str
|
|
358
|
+
handle: str = ""
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
def _port_free(port: int) -> bool:
|
|
362
|
+
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
|
|
363
|
+
return probe.connect_ex(("127.0.0.1", port)) != 0
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
def _free_port() -> int:
|
|
367
|
+
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
|
|
368
|
+
probe.bind(("127.0.0.1", 0))
|
|
369
|
+
return int(probe.getsockname()[1])
|
|
370
|
+
|
|
371
|
+
|
|
372
|
+
def _api_port(env: dict[str, str]) -> int:
|
|
373
|
+
"""8765 unless something listens there already (another agent run here): then a free port, said aloud."""
|
|
374
|
+
port = int(env.get("EKL_AGENT_API_PORT") or os.environ.get("EKL_AGENT_API_PORT") or LOCAL_API_PORT)
|
|
375
|
+
if not _port_free(port):
|
|
376
|
+
port = _free_port()
|
|
377
|
+
print(f"the agent's local API listens on 127.0.0.1:{port} ({LOCAL_API_PORT} is in use)", flush=True)
|
|
378
|
+
return port
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
def offers_nothing(file: Path) -> bool:
|
|
382
|
+
"""agent.json of an agent that only uses services: no services and no upstream server."""
|
|
383
|
+
if not file.exists():
|
|
384
|
+
return False
|
|
385
|
+
try:
|
|
386
|
+
content = json.loads(file.read_text())
|
|
387
|
+
except json.JSONDecodeError:
|
|
388
|
+
return False # let load_agent report what is wrong with the file
|
|
389
|
+
return not content.get("capabilities") and not content.get("upstream")
|
|
390
|
+
|
|
391
|
+
|
|
392
|
+
def _use_only(folder: Path, runner: Runner, args: argparse.Namespace) -> Launch:
|
|
393
|
+
"""An agent that only uses services takes no calls, so nothing is relayed: the connector serves only its loopback
|
|
394
|
+
API, runs the agent's eukollab_callbacks.py beside it and posts the agent's events to them. It announces the
|
|
395
|
+
agent's agent.json, with its key."""
|
|
396
|
+
env = project.read_env(folder / ".env")
|
|
397
|
+
missing = [v for v in ("EKL_PROVIDER_CREDENTIAL", "EKL_NETWORK_URL") if not env.get(v)]
|
|
398
|
+
if missing:
|
|
399
|
+
raise CliError("EKL-206", env=folder / ".env", names=", ".join(missing))
|
|
400
|
+
if not env.get("EKL_AGENT_CREDENTIAL"):
|
|
401
|
+
raise CliError("EKL-409", f"{folder / '.env'} sets no EKL_AGENT_CREDENTIAL.")
|
|
402
|
+
if not (folder / CALLBACKS_FILE).is_file():
|
|
403
|
+
raise CliError("EKL-410", file=folder / CALLBACKS_FILE)
|
|
404
|
+
agent = Agent(folder, {}, env, folder.resolve().name)
|
|
405
|
+
ctx = Context(args, runner, Session(runner, dry=False, secrets=agent.secrets, stream=sys.stdout), agent)
|
|
406
|
+
_cancel_if_failing(Launcher.needs(ctx), "deploy")
|
|
407
|
+
passed = {v: env[v] for v in ("EKL_NETWORK_URL", "EKL_PROVIDER_CREDENTIAL", *USE_ONLY_ENV) if env.get(v)}
|
|
408
|
+
# The connector finds eukollab_callbacks.py beside agent.json and runs it.
|
|
409
|
+
passed["EKL_AGENT_FILE"] = str((folder / "agent.json").resolve())
|
|
410
|
+
passed["EKL_AGENT_API_PORT"] = str(_api_port(env))
|
|
411
|
+
handle = str((json.loads((folder / "agent.json").read_text()).get("agent") or {}).get("handle") or "")
|
|
412
|
+
about = f"{handle or agent.name}'s connector: it runs the callbacks, uses services and takes no calls"
|
|
413
|
+
return Launch(Launcher.command(ctx, ["--use-only"]), passed, None, about, handle)
|
|
414
|
+
|
|
415
|
+
|
|
416
|
+
def prepare_local(args: argparse.Namespace, runner: Runner) -> Launch:
|
|
417
|
+
"""What runs the agent on this machine, with no public address: the connector in front of the MCP server, its
|
|
418
|
+
calls relayed by the network, or, for an agent that only uses services, in use-only mode."""
|
|
419
|
+
folder = Path(args.dir)
|
|
420
|
+
file = folder / "agent.json"
|
|
421
|
+
if (folder / ".env").exists():
|
|
422
|
+
# The local API's token and the callbacks' key, before anything starts that reads them.
|
|
423
|
+
project.ensure_local_secrets(folder)
|
|
424
|
+
if offers_nothing(file):
|
|
425
|
+
return _use_only(folder, runner, args)
|
|
426
|
+
agent = load_agent(folder, None)
|
|
427
|
+
ctx = Context(args, runner, Session(runner, dry=False, secrets=agent.secrets, stream=sys.stdout), agent)
|
|
428
|
+
_cancel_if_failing(Launcher.needs(ctx), "deploy")
|
|
429
|
+
env = agent.connector_env(None)
|
|
430
|
+
env["EKL_AGENT_API_PORT"] = str(_api_port(agent.env))
|
|
431
|
+
argv = Launcher.command(ctx, ["--relay"])
|
|
432
|
+
return Launch(argv, env, None, f"{agent.handle}'s connector, through the network's relay", agent.handle)
|