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
@@ -0,0 +1,556 @@
1
+ # Copyright © 2026 EuKreate, Inc. All rights reserved.
2
+ """`ekl deploy`: one command makes the agent available, where it belongs (spec 13.14.8).
3
+
4
+ Where the agent runs follows from where its MCP server is, so the publisher never chooses a host:
5
+
6
+ - A server on the web (an https address that resolves to public addresses only) is served by EuKollab: the deploy
7
+ uploads agent.json, its declarations, the server's address and headers and the agent key, nothing else from the
8
+ folder, and the network's shared connector workers serve the agent from then on, with no terminal open and no
9
+ hosting of the publisher's. Running it again uploads a new revision; a revision whose checks fail leaves the
10
+ previous one serving.
11
+ - A server on this machine or a private network, and an agent that only uses services, run here (no option: the
12
+ address decides): the connector in a supervised background process, in relay mode (the network relays calls to it)
13
+ or, for an agent that only uses services, in use-only mode with its callbacks, still running after the terminal
14
+ closes, while this machine is awake.
15
+
16
+ The address in .env decides, every time: when it moves between this machine and the web, the deploy moves the agent
17
+ with it and says so, stopping the other copy first so two never serve the same agent.
18
+
19
+ A deploy ends with what the agent announced, for the publisher to confirm, and `--remove` asks before it stops the
20
+ agent; `--confirm` answers yes for a script. `ekl status` reports the rest.
21
+ """
22
+
23
+ import argparse
24
+ import contextlib
25
+ import ipaddress
26
+ import json
27
+ import socket
28
+ import sys
29
+ from collections.abc import Callable
30
+ from dataclasses import dataclass
31
+ from pathlib import Path
32
+ from typing import Any
33
+
34
+ from ekl_cli import declarations, lifecycle, onboard, project, prompt, repair, supervise, ui
35
+ from ekl_cli.client import CliError, OwnerApi
36
+ from ekl_cli.deploy import (
37
+ CALLBACKS_FILE,
38
+ REQUIRED_ENV,
39
+ Runner,
40
+ load_agent,
41
+ offers_nothing,
42
+ prepare_local,
43
+ urllib_host,
44
+ )
45
+ from ekl_cli.finder import report
46
+ from ekl_cli.lifecycle import LOCAL, MANAGED, SAVED, saved
47
+ from ekl_cli.mcp import upstream_headers
48
+ from ekl_cli.repair import callbacks_file
49
+
50
+ # Names that never reach the web: this machine, mDNS, and the suffixes private networks and hosts use.
51
+ LOOPBACK_NAMES = {"localhost", "127.0.0.1", "::1", "0.0.0.0", "host.docker.internal"} # nosec B104 - compared only
52
+ PRIVATE_SUFFIXES = (".localhost", ".local", ".internal", ".lan", ".home.arpa", ".intranet", ".corp", ".private")
53
+ # What `ekl agent deploy` took before managed registration; named so the refusal says what replaced it.
54
+ RETIRED_DESTINATIONS = (
55
+ "railway",
56
+ "fly",
57
+ "gcp-cloud-run",
58
+ "aws",
59
+ "kubernetes",
60
+ "docker",
61
+ "other",
62
+ "local",
63
+ "systemd",
64
+ "aws-lightsail",
65
+ )
66
+ # The commands of the `ekl agent` and `ekl new` groups, and what replaced each.
67
+ REPLACED = {
68
+ "init": "ekl add",
69
+ "run": "ekl deploy (for a server on this machine it runs the agent here, in the background)",
70
+ "sync": "ekl sync",
71
+ "check": "ekl check",
72
+ "deploy": "ekl deploy",
73
+ "status": "ekl status",
74
+ "review": "ekl status (it shows what waits for your review)",
75
+ "confirm": "ekl status --confirm",
76
+ "checks": "ekl status --recheck",
77
+ "publish": "ekl status --publish",
78
+ "unpublish": "ekl status --unpublish",
79
+ "settings": "ekl status --settings",
80
+ "rotate-key": "ekl sync --rotate-key",
81
+ "export": "the console (the agent's page) or your repository",
82
+ "credentials": "the console (the agent's page)",
83
+ }
84
+
85
+
86
+ @dataclass(frozen=True)
87
+ class Placement:
88
+ """Where the agent runs and why, in words the publisher reads."""
89
+
90
+ location: str
91
+ reason: str
92
+
93
+
94
+ def _is_private_ip(text: str) -> bool:
95
+ ip = ipaddress.ip_address(text.split("%", 1)[0])
96
+ if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
97
+ ip = ip.ipv4_mapped
98
+ return not ip.is_global or ip.is_multicast
99
+
100
+
101
+ def classify(url: str, resolve: Callable[[str], list[str]] | None = None) -> Placement:
102
+ """Where an agent in front of the MCP server at `url` runs: here, when the server is on this machine or a private
103
+ network; on EuKollab, when it is on the web. Anything else stops with what to do."""
104
+ resolve = resolve or _addresses
105
+ host = urllib_host(url)
106
+ if not host or not url.lower().startswith(("http://", "https://")):
107
+ raise CliError("EKL-221", url=url)
108
+ if host in LOOPBACK_NAMES or host.endswith(PRIVATE_SUFFIXES) or ("." not in host.strip("[]") and ":" not in host):
109
+ return Placement(LOCAL, f"its MCP server ({host}) is on this machine or a private network")
110
+ try:
111
+ literal = [str(ipaddress.ip_address(host))]
112
+ except ValueError:
113
+ literal = []
114
+ try:
115
+ addresses = literal or resolve(host)
116
+ except OSError as exc:
117
+ raise CliError(
118
+ "EKL-223",
119
+ "So ekl can't tell where the agent should run. A name your VPN or hosts file resolves runs here.",
120
+ host=host,
121
+ ) from exc
122
+ if any(_is_private_ip(a) for a in addresses):
123
+ return Placement(LOCAL, f"its MCP server ({host}) is on a private address")
124
+ if not url.lower().startswith("https://"):
125
+ raise CliError("EKL-222", "EuKollab serves an MCP server on the web over https only.", host=host)
126
+ return Placement(MANAGED, f"its MCP server ({host}) is on the web, so EuKollab serves the agent")
127
+
128
+
129
+ def _addresses(host: str) -> list[str]:
130
+ return [str(info[4][0]) for info in socket.getaddrinfo(host, None)]
131
+
132
+
133
+ def _upstream_url(folder: Path) -> str:
134
+ env = project.read_env(folder / ".env")
135
+ if env.get("EKL_UPSTREAM_MCP_URL"):
136
+ return env["EKL_UPSTREAM_MCP_URL"]
137
+ try:
138
+ named = str((json.loads((folder / "agent.json").read_text()).get("upstream") or {}).get("mcp_url") or "")
139
+ except (OSError, ValueError):
140
+ named = ""
141
+ if named and "${" not in named:
142
+ return named
143
+ raise CliError("EKL-220", f"{folder / '.env'} sets no EKL_UPSTREAM_MCP_URL.")
144
+
145
+
146
+ def decide(args: argparse.Namespace, resolve: Callable[[str], list[str]] | None = None) -> Placement:
147
+ """Where this folder's agent runs, from its MCP server's address."""
148
+ folder = Path(args.dir)
149
+ file = folder / "agent.json"
150
+ if offers_nothing(file):
151
+ return Placement(LOCAL, "it only uses services: its callbacks run here, with the connector's use-only mode")
152
+ return classify(_upstream_url(folder), resolve)
153
+
154
+
155
+ def _save(folder: Path, data: dict[str, Any]) -> None:
156
+ (folder / ".ekl").mkdir(parents=True, exist_ok=True)
157
+ (folder / SAVED).write_text(json.dumps(data, indent=2) + "\n")
158
+ project.ensure_gitignored(folder)
159
+
160
+
161
+ def needs_sign_in(args: argparse.Namespace) -> bool:
162
+ """Whether this deploy talks to the network as the publisher: every deploy does, for its checks; stopping an agent
163
+ run here doesn't."""
164
+ folder = Path(args.dir)
165
+ before = (saved(folder) or {}).get("location")
166
+ if args.remove:
167
+ return before == MANAGED
168
+ # Every deploy runs the network's checks first, which need the publisher's sign-in, wherever the agent runs.
169
+ return True
170
+
171
+
172
+ # --- the command ---------------------------------------------------------------------------------------------------
173
+
174
+
175
+ def cmd_agent_deploy(
176
+ api: OwnerApi | None, args: argparse.Namespace, runner: Runner | None = None
177
+ ) -> tuple[dict[str, Any], str]:
178
+ runner = runner or Runner()
179
+ folder = Path(args.dir)
180
+ previous = saved(folder)
181
+ if args.remove:
182
+ return _remove(api, args, folder, previous)
183
+ repair.offer(folder, confirm=args.confirm or args.force)
184
+ placement = decide(args)
185
+ stopped, steps = steps_before(api, args, folder, placement)
186
+ if stopped is not None:
187
+ return stopped
188
+ before = (previous or {}).get("location")
189
+ if supervise.read_state(folder) is not None and before is None:
190
+ before = LOCAL
191
+ if before and before != placement.location:
192
+ print(f"Moving the agent from {_where(before)} to {_where(placement.location)}: {placement.reason}", flush=True)
193
+ if placement.location == LOCAL:
194
+ data, text = _deploy_here(api, args, runner, folder, placement, before)
195
+ else:
196
+ data, text = _deploy_managed(_api(api), args, folder, placement, before)
197
+ return data | steps, text
198
+
199
+
200
+ # --- before deploying: sync, then check ----------------------------------------------------------------------------
201
+
202
+ STEPS = 3
203
+ WHEN_READY = "Run ekl deploy again when you're ready."
204
+
205
+
206
+ def _step(number: int, title: str) -> None:
207
+ print(
208
+ ("\n" if number > 1 else "") + prompt.heading(f"{number}/{STEPS} {title}", sys.stderr),
209
+ file=sys.stderr,
210
+ flush=True,
211
+ )
212
+
213
+
214
+ def _say(text: str) -> None:
215
+ if text:
216
+ print(text, file=sys.stderr, flush=True)
217
+
218
+
219
+ def _go_on(args: argparse.Namespace, question: str, *details: str) -> bool:
220
+ """Yes with --force; else the publisher's answer at a terminal. With no one to ask, the deploy stops."""
221
+ if args.force:
222
+ return True
223
+ if not prompt.interactive():
224
+ raise CliError("EKL-401", "ekl deploy asks before it writes agent.json and before it deploys.")
225
+ return prompt.confirm(question, True, *details)
226
+
227
+
228
+ def _not_now(step: str, text: str) -> tuple[dict[str, Any], str]:
229
+ return {"deployed": False, "stopped_at": step}, text
230
+
231
+
232
+ def steps_before(
233
+ api: OwnerApi | None, args: argparse.Namespace, folder: Path, placement: Placement
234
+ ) -> tuple[tuple[dict[str, Any], str] | None, dict[str, Any]]:
235
+ """`ekl sync` and `ekl check` as the deploy's first two steps (spec 13.14.8), so what is deployed is agent.json as
236
+ the server and eukollab.json declare it, and passes the network's checks. Each step shows what it found and asks
237
+ before the deploy goes on (--force goes on without asking); an error stops it, saying what to fix. Returns what to
238
+ answer when the publisher stopped it, and what the steps found."""
239
+ file = folder / "agent.json"
240
+ if not file.is_file():
241
+ # No agent.json: the deploy itself says what to do, and there is nothing to sync.
242
+ return None, {}
243
+ where = _where_at(placement.location)
244
+ sync_args = argparse.Namespace(file=str(file), mcp=None, header=None)
245
+ # An agent that only uses services has no server: its agent.json comes from eukollab.json alone.
246
+ try:
247
+ serves = bool(json.loads(file.read_text()).get("capabilities"))
248
+ except ValueError:
249
+ serves = True # a damaged file: the sync below says what is wrong with it
250
+ _step(1, "Sync agent.json from " + ("your server and eukollab.json" if serves else "eukollab.json"))
251
+ try:
252
+ plan = onboard.plan_sync(file, sync_args)
253
+ except CliError as failed:
254
+ raise failed.add("The deploy stopped at sync: nothing was written or deployed.") from failed
255
+ if plan.outcomes is not None:
256
+ _say(ui.bold("Examples tried on your server", sys.stderr) + "\n" + report(plan.outcomes))
257
+ if plan.diff:
258
+ _say(plan.diff.rstrip() + plan.notes())
259
+ if not _go_on(args, f"Write these changes to {file.name}?", "Yes writes them and goes on to the checks."):
260
+ return _not_now("sync", f"Nothing written or deployed: {file} is unchanged. {WHEN_READY}"), {}
261
+ plan.write()
262
+ _say(ui.ok(f"Wrote {file}", sys.stderr))
263
+ else:
264
+ plan.write() # the icon, when eukollab.json names a file here
265
+ _say(ui.ok(f"{file.name} already matches your server and {declarations.FILE}", sys.stderr))
266
+ synced = {"differences": plan.changed if plan.diff else [], "written": bool(plan.diff)}
267
+ _step(2, "Check it as the network would")
268
+ checked, text = onboard.check(_api(api), argparse.Namespace(file=str(file), mcp=sync_args.mcp, header=None))
269
+ _say(text)
270
+ errors = [p for p in checked.get("problems") or [] if p.get("level") == "error"]
271
+ if errors or checked.get("differences"):
272
+ raise _check_failed(folder, errors, checked.get("differences") or [])
273
+ handle = lifecycle.handle_in(folder)
274
+ if not _go_on(args, f"Deploy {handle} {where}?", f"{placement.reason}."):
275
+ kept = f"; {file} keeps the changes the sync wrote" if plan.diff else ""
276
+ return _not_now("check", f"Nothing deployed{kept}. {WHEN_READY}"), {}
277
+ _step(3, f"Deploy {where}")
278
+ return None, {"sync": synced, "check": checked}
279
+
280
+
281
+ def _check_failed(folder: Path, errors: list[dict[str, Any]], drift: list[str]) -> CliError:
282
+ """The errors the network's checks would stop on, each with the field and where to change it: a tool's schemas
283
+ come only from the server, the rest from eukollab.json or .env."""
284
+ lines = [f"✗ {p.get('field') or 'agent.json'}: {p['message']}\n change it {_fix_in(folder, p)}" for p in errors]
285
+ if drift:
286
+ lines.append("✗ agent.json differs from what your server declares (did the server change meanwhile?):")
287
+ lines += [f" {d}" for d in drift]
288
+ return CliError("EKL-303", *lines).add("The deploy stopped at check: nothing was deployed.")
289
+
290
+
291
+ def _fix_in(folder: Path, problem: dict[str, Any]) -> str:
292
+ """Where a problem's field is set. A tool's input and output schemas come from the MCP server, and eukollab.json
293
+ may declare them under the tool instead, so either place fixes them."""
294
+ field = str(problem.get("field") or "")
295
+ if field.startswith(".env"):
296
+ return f"in {folder / '.env'}"
297
+ if field.endswith(("input_schema", "output_schema")):
298
+ return f"in your MCP server, or under the tool in {folder / declarations.FILE}"
299
+ return f"in {folder / declarations.FILE}"
300
+
301
+
302
+ def _where(location: str) -> str:
303
+ return "this machine" if location == LOCAL else "EuKollab"
304
+
305
+
306
+ def _api(api: OwnerApi | None) -> OwnerApi:
307
+ if api is None:
308
+ raise CliError("EKL-101")
309
+ return api
310
+
311
+
312
+ # --- here ----------------------------------------------------------------------------------------------------------
313
+
314
+
315
+ def _deploy_here(
316
+ api: OwnerApi | None,
317
+ args: argparse.Namespace,
318
+ runner: Runner,
319
+ folder: Path,
320
+ placement: Placement,
321
+ before: str | None,
322
+ ) -> tuple[dict[str, Any], str]:
323
+ if before == MANAGED:
324
+ # Moving here: EuKollab stops serving it first, so two copies never serve the same agent.
325
+ handle = load_agent(folder, None).handle
326
+ _remove_there(_api(api), handle)
327
+ print(ui.ok(f"EuKollab no longer serves {handle}; its secrets there are deleted"), flush=True)
328
+ launch = prepare_local(args, runner)
329
+ updated = supervise.stop(folder)
330
+ state = runner.background(folder, launch)
331
+ _save(folder, {"location": LOCAL})
332
+ if not runner.settled(folder):
333
+ lines = supervise.tail(folder)
334
+ raise CliError("EKL-402", "Its last lines:", *(f" {line}" for line in lines))
335
+ log = supervise.log_file(folder)
336
+ lines = [
337
+ ui.ok(f"{'Updated' if updated else 'Started'} on this machine: {launch.about}"),
338
+ f" {ui.dim('Why here: ' + placement.reason)}",
339
+ f" {ui.dim(f'It keeps running in the background while this machine is awake. Log: {log}')}",
340
+ f" {ui.dim('Stop it: ekl deploy --remove')}",
341
+ "",
342
+ ]
343
+ if launch.handle:
344
+ # A local run needs no sign-in; the review does, when this machine is signed in to the agent's network.
345
+ api = api or onboard.signed_in_to(onboard.folder_network(folder))
346
+ lines = lifecycle.offer_review(
347
+ api, launch.handle, confirm=args.confirm, wait=lifecycle.ANNOUNCE_WAIT_SECONDS, before=lines
348
+ )
349
+ data = {"location": LOCAL, "updated": updated, "pid": state.get("pid"), "log": str(log)}
350
+ return data, "\n".join(lines)
351
+
352
+
353
+ # --- on EuKollab ---------------------------------------------------------------------------------------------------
354
+
355
+
356
+ # How a managed deploy reports where the agent's own decisions are made.
357
+ CALLBACKS_SHOWN: dict[str | None, str] = {
358
+ "hosted": f"your {CALLBACKS_FILE} runs on EuKollab, in a sandbox of its own, started when events wait for it "
359
+ "(connection requests too, once the console's Connection requests rule is set to your code)",
360
+ None: "the agent's console rules make them",
361
+ }
362
+ # The packages hosted callbacks need beyond Python's standard library and the provider adapter, one per line.
363
+ CALLBACKS_REQUIREMENTS = "callbacks-requirements.txt"
364
+
365
+
366
+ def hosted_callbacks(folder: Path, env: dict[str, str]) -> dict[str, Any]:
367
+ """What a managed deploy sends for the agent's own decisions: its callbacks file, whoever wrote it (ekl's
368
+ defaults answer matching needs and connection requests for the agent's services, so leaving them out would change
369
+ what the agent does), and the packages it needs, with the agent-operation credential that lets the agent take
370
+ part. Nothing when the agent doesn't take part: its console rules decide."""
371
+ credential = env.get("EKL_AGENT_CREDENTIAL", "")
372
+ if not credential:
373
+ return {}
374
+ if callbacks_file(folder) == "none":
375
+ return {}
376
+ listed = folder / CALLBACKS_REQUIREMENTS
377
+ requirements = [
378
+ line.strip()
379
+ for line in (listed.read_text().splitlines() if listed.is_file() else [])
380
+ if line.strip() and not line.lstrip().startswith("#")
381
+ ]
382
+ return {
383
+ "callbacks": (folder / CALLBACKS_FILE).read_text(),
384
+ "requirements": requirements,
385
+ "agent_credential": credential,
386
+ }
387
+
388
+
389
+ def submission(folder: Path) -> tuple[str, dict[str, Any]]:
390
+ """What a managed deploy uploads, and nothing else: agent.json as the network keeps it (local settings stripped,
391
+ terms inlined), the declarations behind it, the MCP server's address and headers, the agent key, and the agent's
392
+ own callbacks when it has them."""
393
+ agent = load_agent(folder, None)
394
+ content = json.loads(agent.announced(None))
395
+ for section in ("upstream", "network"):
396
+ content.pop(section, None)
397
+ adapter = {k: v for k, v in (content.get("adapter") or {}).items() if k not in ("path", "storage", "endpoint")}
398
+ content["adapter"] = adapter
399
+ decl_path = folder / declarations.FILE
400
+ declared: dict[str, Any] = json.loads(decl_path.read_text()) if decl_path.is_file() else {}
401
+ body = {
402
+ "agent_file": content,
403
+ "declarations": declared,
404
+ "upstream_url": agent.env["EKL_UPSTREAM_MCP_URL"],
405
+ "upstream_headers": upstream_headers(agent.env.get("EKL_UPSTREAM_HEADERS")),
406
+ "agent_key": agent.env["EKL_PROVIDER_CREDENTIAL"],
407
+ } | hosted_callbacks(folder, agent.env)
408
+ return agent.handle, body
409
+
410
+
411
+ def _deploy_managed(
412
+ api: OwnerApi, args: argparse.Namespace, folder: Path, placement: Placement, before: str | None
413
+ ) -> tuple[dict[str, Any], str]:
414
+ env = project.read_env(folder / ".env")
415
+ missing = [v for v in REQUIRED_ENV if not env.get(v)]
416
+ if missing:
417
+ raise CliError("EKL-206", env=folder / ".env", names=", ".join(missing))
418
+ handle, body = submission(folder)
419
+ agent_id = api.agent_id(handle)
420
+ if before == LOCAL and supervise.stop(folder):
421
+ print(ui.ok(f"Stopped {handle} on this machine"), flush=True)
422
+ print(ui.dim(f"Deploying {handle} to EuKollab ({placement.reason}) and checking it there…"), flush=True)
423
+ answer = api.request("POST", f"/agents/{agent_id}/deployment", body)
424
+ if answer.get("revision_status") != "active":
425
+ failed = [c for c in answer.get("checks") or [] if not c.get("ok")]
426
+ lines = []
427
+ for check in failed:
428
+ lines.append(f"✗ {check['check']}: {check['message']}")
429
+ lines += ui.problem_list(check.get("problems") or [], indent=" ")
430
+ if answer.get("active_revision"):
431
+ lines.append(f"Revision {answer['active_revision']} keeps serving {handle}.")
432
+ raise CliError("EKL-403", *lines, revision=answer.get("revision"))
433
+ _save(folder, {"location": MANAGED, "agent_id": agent_id, "deployment_id": answer.get("deployment_id")})
434
+ lines = _managed_summary(handle, answer)
435
+ if answer.get("waiting_for_review"):
436
+ lines = lifecycle.offer_review(api, handle, confirm=args.confirm, before=[*lines, ""])
437
+ return answer, "\n".join(lines)
438
+
439
+
440
+ def _managed_summary(handle: str, answer: dict[str, Any]) -> list[str]:
441
+ verb = "Unchanged" if answer.get("unchanged") else "Deployed"
442
+ checks = answer.get("checks") or []
443
+ lines = [
444
+ ui.ok(f"{verb}: {handle} on EuKollab, revision {answer['revision']} ") + ui.dim(f"({answer['digest'][:12]})"),
445
+ f" Checks {ui.ok(f'{len(checks)} passed')}"
446
+ + (f": {', '.join(c['check'] for c in checks)}" if checks else ""),
447
+ ]
448
+ lines += ui.problem_list([p for c in checks for p in c.get("problems") or []], indent=" ")
449
+ lines += [
450
+ f" Runs {answer['availability']}; EuKollab starts it when a call arrives",
451
+ f" Decisions {CALLBACKS_SHOWN.get(answer.get('callbacks'), CALLBACKS_SHOWN[None])}",
452
+ ]
453
+ if not answer.get("waiting_for_review"):
454
+ lines.append(
455
+ f"Nothing waits for your review ({str(answer.get('agent_state')).lower()}). Next: ekl status {handle}"
456
+ )
457
+ return lines
458
+
459
+
460
+ def _remove_there(api: OwnerApi, handle: str) -> dict[str, Any]:
461
+ found: dict[str, Any] = api.request("DELETE", f"/agents/{api.agent_id(handle)}/deployment")
462
+ return found
463
+
464
+
465
+ def _remove(
466
+ api: OwnerApi | None, args: argparse.Namespace, folder: Path, previous: dict[str, Any] | None
467
+ ) -> tuple[dict[str, Any], str]:
468
+ """Stop the agent wherever it runs, after asking at a terminal (--confirm answers for a script). It stays
469
+ registered, and ekl deploy makes it available again."""
470
+ location = (previous or {}).get("location") or (LOCAL if supervise.read_state(folder) else None)
471
+ if location is None:
472
+ raise CliError("EKL-404", folder=folder.resolve())
473
+ handle = lifecycle.handle_in(folder)
474
+ effect = (
475
+ "Callers are told it is away until you deploy it again."
476
+ if location == LOCAL
477
+ else "EuKollab stops serving it and deletes your server's address, headers and agent key it kept."
478
+ )
479
+ if not (args.confirm or args.force):
480
+ if not prompt.interactive():
481
+ raise CliError("EKL-405", f"{handle} runs {_where_at(location)}.")
482
+ if not prompt.confirm(f"Stop {handle} {_where_at(location)}?", False, effect, "It stays registered."):
483
+ return {
484
+ "location": location,
485
+ "stopped": False,
486
+ }, f"Nothing stopped: {handle} keeps running {_where_at(location)}."
487
+ if location == LOCAL:
488
+ stopped = supervise.stop(folder)
489
+ (folder / SAVED).unlink(missing_ok=True)
490
+ said = ui.ok("Stopped on this machine") if stopped else ui.ok("It wasn't running")
491
+ # The network takes it out of search and Explore at once; it is listed again when it runs again. Stopping it
492
+ # needs no sign-in, so this uses the machine's sign-in to the agent's network when there is one.
493
+ told = api or onboard.signed_in_to(onboard.folder_network(folder))
494
+ if told is not None:
495
+ with contextlib.suppress(CliError):
496
+ told.request("POST", f"/agents/{told.agent_id(handle)}/stopped")
497
+ return {
498
+ "location": LOCAL,
499
+ "stopped": stopped,
500
+ }, f"{said}\n {ui.dim('It stays registered, and callers are told it is away. ekl deploy starts it again.')}"
501
+ found = _remove_there(_api(api), handle)
502
+ (folder / SAVED).unlink(missing_ok=True)
503
+ text = "\n".join(
504
+ [
505
+ ui.ok(f"EuKollab no longer serves {handle}; its secrets there are deleted"),
506
+ f" {ui.dim('It stays registered. ekl deploy makes it available again.')}",
507
+ ]
508
+ )
509
+ return found, text
510
+
511
+
512
+ def _where_at(location: str) -> str:
513
+ return "on this machine" if location == LOCAL else "on EuKollab"
514
+
515
+
516
+ # --- the parser ----------------------------------------------------------------------------------------------------
517
+
518
+
519
+ def add_parser(sub: Any) -> None:
520
+ deploy = sub.add_parser(
521
+ "deploy",
522
+ help="in the agent's folder: make it available, on EuKollab when its MCP server is on the web, else on this "
523
+ "machine; --remove stops it",
524
+ )
525
+ deploy.add_argument(
526
+ "--remove", action="store_true", help="stop it where it runs; the agent stays registered (asks first)"
527
+ )
528
+ deploy.add_argument(
529
+ "--force",
530
+ action="store_true",
531
+ help="sync, check and deploy without asking: agent.json is written from the server and the deploy goes on "
532
+ "when the checks find no error",
533
+ )
534
+ deploy.add_argument(
535
+ "--confirm",
536
+ action="store_true",
537
+ help="answer yes without asking, for a script: confirm what it announced, or stop it with --remove",
538
+ )
539
+ # Always the folder it runs in: the agent's address and key are in its .env.
540
+ deploy.set_defaults(fn=cmd_agent_deploy, needs_api=needs_sign_in, dir=".")
541
+
542
+
543
+ def refuse_retired(argv: list[str]) -> None:
544
+ """The `ekl agent` and `ekl new` groups and deploying to a host are gone: say what replaced them, before argparse's
545
+ usage line."""
546
+ words = [w for w in argv if not w.startswith("-")]
547
+ if words[:1] == ["new"]:
548
+ raise CliError("EKL-411")
549
+ if words[:1] == ["agent"]:
550
+ verb = words[1] if len(words) > 1 else ""
551
+ replaced = REPLACED.get(verb)
552
+ raise CliError(
553
+ "EKL-412", verb=verb if replaced else "…", replaced=replaced or "ekl add, check, sync, deploy and status"
554
+ )
555
+ if words[:1] == ["deploy"] and len(words) > 1 and words[1] in RETIRED_DESTINATIONS:
556
+ raise CliError("EKL-413", f"It was given {words[1]}.")