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.
Files changed (75) hide show
  1. ekl_cli/__init__.py +2 -0
  2. ekl_cli/bridge.py +160 -0
  3. ekl_cli/client.py +232 -0
  4. ekl_cli/clients/.agents/plugins/marketplace.json +20 -0
  5. ekl_cli/clients/.claude-plugin/marketplace.json +16 -0
  6. ekl_cli/clients/README.md +3 -0
  7. ekl_cli/clients/claude-code/.claude-plugin/plugin.json +14 -0
  8. ekl_cli/clients/claude-code/.mcp.json +10 -0
  9. ekl_cli/clients/claude-code/commands/check.md +11 -0
  10. ekl_cli/clients/claude-code/commands/deploy.md +49 -0
  11. ekl_cli/clients/claude-code/commands/status.md +10 -0
  12. ekl_cli/clients/claude-code/skills/agent-behaviour/SKILL.md +112 -0
  13. ekl_cli/clients/claude-code/skills/agent-config-in-repo/SKILL.md +92 -0
  14. ekl_cli/clients/claude-code/skills/connect-mcp-server/SKILL.md +296 -0
  15. ekl_cli/clients/claude-code/skills/operate-agent/SKILL.md +54 -0
  16. ekl_cli/clients/claude-code/skills/plan-with-the-network/SKILL.md +60 -0
  17. ekl_cli/clients/codex/mcp.json +11 -0
  18. ekl_cli/clients/codex/plugin.json +8 -0
  19. ekl_cli/clients/codex/skills/agent-behaviour/SKILL.md +112 -0
  20. ekl_cli/clients/codex/skills/agent-config-in-repo/SKILL.md +92 -0
  21. ekl_cli/clients/codex/skills/connect-mcp-server/SKILL.md +296 -0
  22. ekl_cli/clients/codex/skills/operate-agent/SKILL.md +54 -0
  23. ekl_cli/clients/codex/skills/plan-with-the-network/SKILL.md +60 -0
  24. ekl_cli/clients/cursor/.cursor-plugin/plugin.json +8 -0
  25. ekl_cli/clients/cursor/commands/check.md +11 -0
  26. ekl_cli/clients/cursor/commands/deploy.md +49 -0
  27. ekl_cli/clients/cursor/commands/status.md +10 -0
  28. ekl_cli/clients/cursor/mcp.json +10 -0
  29. ekl_cli/clients/cursor/rules/eukollab.mdc +81 -0
  30. ekl_cli/clients/cursor/skills/agent-behaviour/SKILL.md +112 -0
  31. ekl_cli/clients/cursor/skills/agent-config-in-repo/SKILL.md +92 -0
  32. ekl_cli/clients/cursor/skills/connect-mcp-server/SKILL.md +296 -0
  33. ekl_cli/clients/cursor/skills/operate-agent/SKILL.md +54 -0
  34. ekl_cli/clients/cursor/skills/plan-with-the-network/SKILL.md +60 -0
  35. ekl_cli/clients/gemini/GEMINI.md +76 -0
  36. ekl_cli/clients/gemini/gemini-extension.json +14 -0
  37. ekl_cli/clients/generic/AGENTS.md +76 -0
  38. ekl_cli/clients/generic/mcp.json +10 -0
  39. ekl_cli/clients/vscode/instructions/eukollab.instructions.md +80 -0
  40. ekl_cli/clients/vscode/mcp.json +11 -0
  41. ekl_cli/command_help.py +223 -0
  42. ekl_cli/declarations.py +492 -0
  43. ekl_cli/deploy.py +432 -0
  44. ekl_cli/deploy_command.py +556 -0
  45. ekl_cli/derive.py +217 -0
  46. ekl_cli/design.py +339 -0
  47. ekl_cli/finder.py +695 -0
  48. ekl_cli/icon.py +102 -0
  49. ekl_cli/install.py +185 -0
  50. ekl_cli/lifecycle.py +357 -0
  51. ekl_cli/main.py +643 -0
  52. ekl_cli/mcp.py +279 -0
  53. ekl_cli/messages.py +245 -0
  54. ekl_cli/onboard.py +1040 -0
  55. ekl_cli/participation.py +247 -0
  56. ekl_cli/project.py +211 -0
  57. ekl_cli/prompt.py +176 -0
  58. ekl_cli/py.typed +0 -0
  59. ekl_cli/release_root.json +9 -0
  60. ekl_cli/release_trust.py +376 -0
  61. ekl_cli/repair.py +266 -0
  62. ekl_cli/schema.py +117 -0
  63. ekl_cli/setup.py +326 -0
  64. ekl_cli/supervise.py +162 -0
  65. ekl_cli/templates/python/eukollab-agent.md.tmpl +202 -0
  66. ekl_cli/templates/python/eukollab_callbacks.py.tmpl +509 -0
  67. ekl_cli/templates/versions.json +3 -0
  68. ekl_cli/ui.py +158 -0
  69. ekl_cli/versions.py +402 -0
  70. ekl_cli-0.10.0.dist-info/METADATA +72 -0
  71. ekl_cli-0.10.0.dist-info/RECORD +75 -0
  72. ekl_cli-0.10.0.dist-info/WHEEL +5 -0
  73. ekl_cli-0.10.0.dist-info/entry_points.txt +2 -0
  74. ekl_cli-0.10.0.dist-info/licenses/LICENSE +10 -0
  75. 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)