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
|
@@ -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]}.")
|