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/mcp.py ADDED
@@ -0,0 +1,279 @@
1
+ # Copyright © 2026 EuKreate, Inc. All rights reserved.
2
+ """Streamable HTTP for MCP, standard library only: reading a server and calling its tools as an MCP client, and
3
+ the one send that `ekl mcp` forwards each message with.
4
+
5
+ `ekl add` runs on the publisher's machine, so a local or private server is read from there and the network
6
+ never receives its address. Servers on the initialization-based revision (2025-11-25) are initialized first and
7
+ whatever version they answer with is used for the rest of the read; a server that refuses initialization is asked
8
+ directly under 2026-07-28, which needs no handshake.
9
+
10
+ A server that asks for a key in a header (hosted MCP endpoints usually do) is read with the headers the publisher
11
+ gives, from --header or EKL_UPSTREAM_HEADERS, the same JSON object the connector sends; they go only to that address,
12
+ never to a redirect. An address with user info (https://user:password@host/mcp) is read with HTTP Basic, the
13
+ credentials sent as that header and the address used, shown and reported without them.
14
+ """
15
+
16
+ import base64
17
+ import json
18
+ import re
19
+ import urllib.error
20
+ import urllib.parse
21
+ import urllib.request
22
+ from dataclasses import dataclass
23
+ from typing import Any
24
+
25
+ from ekl_cli import client
26
+ from ekl_cli.client import CliError
27
+
28
+ LEGACY_VERSION = "2025-11-25"
29
+ CURRENT_VERSION = "2026-07-28"
30
+ MAX_PAGES = 20 # a tool list is short; this only stops a server that pages forever
31
+ UPSTREAM_HEADERS = "EKL_UPSTREAM_HEADERS"
32
+ _HEADER_NAME = re.compile(r"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$")
33
+ # Headers the MCP transport sets itself: a configured value would break the session rather than authenticate it.
34
+ # The connector refuses the same names.
35
+ _TRANSPORT_HEADERS = frozenset(
36
+ {
37
+ "accept",
38
+ "connection",
39
+ "content-length",
40
+ "content-type",
41
+ "host",
42
+ "last-event-id",
43
+ "mcp-method",
44
+ "mcp-protocol-version",
45
+ "mcp-session-id",
46
+ "transfer-encoding",
47
+ }
48
+ )
49
+
50
+
51
+ def _checked(name: str, value: object, where: str) -> str:
52
+ """The header's value once its name and value pass; errors name the header, never its value (usually a key)."""
53
+ if not _HEADER_NAME.match(name):
54
+ raise CliError("EKL-216", f"{where}: {name!r} isn't a valid header name.")
55
+ if name.lower() in _TRANSPORT_HEADERS:
56
+ raise CliError("EKL-216", f"{where}: {name} is set by the MCP transport and can't be configured.")
57
+ if not isinstance(value, str) or any(c in value for c in "\r\n\0"):
58
+ raise CliError("EKL-216", f"{where}: the value of {name} must be text on one line.")
59
+ return value
60
+
61
+
62
+ def upstream_headers(text: str | None) -> dict[str, str]:
63
+ """EKL_UPSTREAM_HEADERS as the connector reads it: a JSON object of header names and values."""
64
+ if not text or not text.strip():
65
+ return {}
66
+ try:
67
+ found = json.loads(text)
68
+ except ValueError:
69
+ found = None
70
+ if not isinstance(found, dict):
71
+ raise CliError("EKL-216", f'{UPSTREAM_HEADERS} must be a JSON object, e.g. {{"Authorization": "Bearer …"}}.')
72
+ return {name: _checked(name, value, UPSTREAM_HEADERS) for name, value in found.items()}
73
+
74
+
75
+ def header_options(given: list[str] | None) -> dict[str, str]:
76
+ """--header "Name: value", given once per header, as curl takes them."""
77
+ headers: dict[str, str] = {}
78
+ for option in given or []:
79
+ name, colon, value = option.partition(":")
80
+ if not colon:
81
+ # The value may be a key: say only that the colon is missing, never what was given.
82
+ raise CliError("EKL-216", '--header takes "Name: value", with a colon after the name.')
83
+ headers[name.strip()] = _checked(name.strip(), value.strip(), "--header")
84
+ return headers
85
+
86
+
87
+ def credentials_of(url: str) -> tuple[str, dict[str, str]]:
88
+ """An address and what its user info stands for: the address without it, and the HTTP Basic Authorization header
89
+ it carries (urllib can't send user info in the address itself). An address without user info is returned as it
90
+ is, with no header."""
91
+ parts = urllib.parse.urlsplit(url)
92
+ if parts.username is None and parts.password is None:
93
+ return url, {}
94
+ host = parts.hostname or ""
95
+ if ":" in host:
96
+ host = f"[{host}]"
97
+ netloc = host + (f":{parts.port}" if parts.port else "")
98
+ pair = f"{urllib.parse.unquote(parts.username or '')}:{urllib.parse.unquote(parts.password or '')}"
99
+ address = urllib.parse.urlunsplit((parts.scheme, netloc, parts.path, parts.query, parts.fragment))
100
+ return address, {"Authorization": "Basic " + base64.b64encode(pair.encode()).decode()}
101
+
102
+
103
+ def shown(url: str) -> str:
104
+ """An address as ekl prints it: without user info, which holds a password."""
105
+ return credentials_of(url)[0]
106
+
107
+
108
+ class _NoRedirect(urllib.request.HTTPRedirectHandler):
109
+ def redirect_request(self, *_: Any) -> None:
110
+ return None # urllib then raises the redirect as an HTTPError
111
+
112
+
113
+ def _keep_headers_here() -> urllib.request.OpenerDirector:
114
+ """urllib carries a request's headers to wherever a redirect points; a server's key, or the publisher's token, must
115
+ not travel that way. Built when used, with the handlers prepare_http chose: an opener made at import would miss
116
+ the system's certificates on a Python that trusts none, and every HTTPS request would fail."""
117
+ return urllib.request.build_opener(*client.handlers(), _NoRedirect)
118
+
119
+
120
+ def _decode(body: bytes, content_type: str) -> Any:
121
+ """One JSON-RPC message (or batch), from a JSON body or the first data event of a server-sent event stream."""
122
+ text = body.decode("utf-8", errors="replace")
123
+ if "text/event-stream" in content_type:
124
+ for line in text.splitlines():
125
+ if line.startswith("data:"):
126
+ return json.loads(line[5:].strip())
127
+ raise CliError("EKL-224", "Its event stream carried no message.")
128
+ return json.loads(text)
129
+
130
+
131
+ def send(
132
+ url: str, message: Any, headers: dict[str, str], timeout: float, *, follow_redirects: bool = True
133
+ ) -> tuple[Any, str | None]:
134
+ """POST one JSON-RPC message or batch over Streamable HTTP. Returns the answer (None for an accepted notification)
135
+ and the session ID the server gave, if any. HTTP and network errors are raised as urllib raises them."""
136
+ request = urllib.request.Request(
137
+ url,
138
+ json.dumps(message).encode(),
139
+ headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream", **headers},
140
+ method="POST",
141
+ )
142
+ opener = urllib.request.urlopen if follow_redirects else _keep_headers_here().open
143
+ with opener(request, timeout=timeout) as response:
144
+ session = response.headers.get("Mcp-Session-Id")
145
+ body = response.read()
146
+ if not body.strip():
147
+ return None, session
148
+ return _decode(body, response.headers.get("Content-Type", "")), session
149
+
150
+
151
+ @dataclass(frozen=True)
152
+ class ToolCall:
153
+ """One tool call's answer: the structured result, the text blocks, whether the tool said it failed, and a
154
+ transport or protocol error when the call did not complete (the tool then never ran)."""
155
+
156
+ data: dict[str, Any] | None
157
+ text: str
158
+ is_error: bool
159
+ error: str | None = None
160
+
161
+
162
+ class McpReader:
163
+ """An MCP client for one server: it initializes on first use, keeps the session and protocol version the server
164
+ chose, and reads what the server declares for EuKollab alongside its tools."""
165
+
166
+ def __init__(self, url: str, timeout: float = 20, headers: dict[str, str] | None = None):
167
+ # User info becomes HTTP Basic; a header given for Authorization takes its place. Either way the headers are
168
+ # sent to this address only, never to a redirect.
169
+ self.url, basic = credentials_of(url)
170
+ self.timeout = timeout
171
+ self.headers = basic | dict(headers or {})
172
+ self.session: str | None = None
173
+ self.version = LEGACY_VERSION
174
+ self.next_id = 0
175
+ self.server: dict[str, Any] = {}
176
+ self.initialized = False
177
+
178
+ def _post(
179
+ self, method: str, params: dict[str, Any] | None, *, notify: bool = False, timeout: float | None = None
180
+ ) -> dict[str, Any] | None:
181
+ message: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
182
+ if params is not None:
183
+ message["params"] = params
184
+ if not notify:
185
+ self.next_id += 1
186
+ message["id"] = self.next_id
187
+ headers = {**self.headers, "MCP-Protocol-Version": self.version}
188
+ if self.session:
189
+ headers["Mcp-Session-Id"] = self.session
190
+ try:
191
+ answer, session = self._send(message, headers, timeout or self.timeout)
192
+ except urllib.error.HTTPError as exc:
193
+ raise CliError(
194
+ "EKL-224", f"{self.url} answered {method} with HTTP {exc.code}{self._hint(exc.code)}."
195
+ ) from exc
196
+ except urllib.error.URLError as exc:
197
+ raise CliError("EKL-224", f"Can't reach {self.url}: {exc.reason}.") from exc
198
+ except (OSError, ValueError) as exc: # a timeout, a dropped connection or a body that isn't JSON
199
+ raise CliError("EKL-224", f"{method} failed: {type(exc).__name__}: {exc}.") from exc
200
+ self.session = session or self.session
201
+ if notify or not isinstance(answer, dict):
202
+ return None
203
+ if "error" in answer:
204
+ error = answer["error"] or {}
205
+ raise CliError("EKL-224", f"{method} refused: {error.get('message', error)}.")
206
+ result: dict[str, Any] = answer.get("result") or {}
207
+ return result
208
+
209
+ def _send(self, message: Any, headers: dict[str, str], timeout: float) -> tuple[Any, str | None]:
210
+ return send(self.url, message, headers, timeout, follow_redirects=not self.headers)
211
+
212
+ def _hint(self, code: int) -> str:
213
+ if code in (401, 403):
214
+ if self.headers:
215
+ return f": check the key in the headers given ({', '.join(self.headers)})"
216
+ return ': if the server needs a key, give it with --header "Authorization: Bearer <key>"'
217
+ if 300 <= code < 400 and self.headers:
218
+ return ": the server redirects, and its headers are only sent to the address given; use the final address"
219
+ return ""
220
+
221
+ def _initialize(self) -> None:
222
+ if self.initialized:
223
+ return
224
+ self.initialized = True
225
+ try:
226
+ result = (
227
+ self._post(
228
+ "initialize",
229
+ {
230
+ "protocolVersion": LEGACY_VERSION,
231
+ "capabilities": {},
232
+ "clientInfo": {"name": "ekl", "version": "1"},
233
+ },
234
+ )
235
+ or {}
236
+ )
237
+ # Whatever revision the server negotiated is spoken from here on; this read needs no feature of any one.
238
+ self.version = str(result.get("protocolVersion") or LEGACY_VERSION)
239
+ info = result.get("serverInfo") or {}
240
+ self.server = {
241
+ "name": info.get("name"),
242
+ "title": info.get("title"),
243
+ "description": info.get("description"),
244
+ "website_url": info.get("websiteUrl"),
245
+ "instructions": result.get("instructions"),
246
+ }
247
+ self.server = {k: v for k, v in self.server.items() if isinstance(v, str) and v}
248
+ icons = [i for i in info.get("icons") or [] if isinstance(i, dict) and i.get("src")]
249
+ if icons:
250
+ self.server["icons"] = icons
251
+ self._post("notifications/initialized", None, notify=True)
252
+ except CliError:
253
+ # A server on the current revision has no handshake: list its tools directly.
254
+ self.session, self.version = None, CURRENT_VERSION
255
+
256
+ def tools(self) -> list[dict[str, Any]]:
257
+ self._initialize()
258
+ found: list[dict[str, Any]] = []
259
+ cursor: str | None = None
260
+ for _ in range(MAX_PAGES):
261
+ page = self._post("tools/list", {"cursor": cursor} if cursor else {}) or {}
262
+ found += [t for t in page.get("tools", []) if isinstance(t, dict)]
263
+ cursor = page.get("nextCursor")
264
+ if not cursor:
265
+ return found
266
+ return found
267
+
268
+ def call(self, tool: str, arguments: dict[str, Any], timeout: float) -> ToolCall:
269
+ """Call one tool. A refusal or an unreachable server comes back as `error`, never raised: the example finder
270
+ reads what went wrong and carries on."""
271
+ self._initialize()
272
+ try:
273
+ result = self._post("tools/call", {"name": tool, "arguments": arguments}, timeout=timeout) or {}
274
+ except CliError as exc:
275
+ return ToolCall(None, "", True, str(exc))
276
+ blocks = result.get("content") or []
277
+ text = " ".join(str(b.get("text") or "") for b in blocks if isinstance(b, dict)).strip()
278
+ structured = result.get("structuredContent")
279
+ return ToolCall(structured if isinstance(structured, dict) else None, text, bool(result.get("isError")))
ekl_cli/messages.py ADDED
@@ -0,0 +1,245 @@
1
+ # Copyright © 2026 EuKreate, Inc. All rights reserved.
2
+ """ekl's standard messages (spec 13.14.13): each has a stable code, a one-line title and the fix, which is all the
3
+ terminal shows. What each one means and how to work through it is on the messages page, served to signed-in users
4
+ only, so this public package carries no more than the terminal prints. A code never changes meaning, and a retired
5
+ one is never reused; guardians/check_ekl_messages.py keeps this catalogue, its uses and the page in step.
6
+
7
+ Codes by area: 1xx sign-in, the network and ekl itself; 2xx the agent's folder (agent.json, eukollab.json, .env,
8
+ its MCP server); 3xx check and sync; 4xx deploy; 5xx status; 6xx find, show and try; 7xx account and settings;
9
+ 8xx coding-agent setup; 9xx the unexpected. Network refusals keep the protocol's own codes (NOT_FOUND,
10
+ POLICY_DENIED…), explained on the same page."""
11
+
12
+ from dataclasses import dataclass
13
+ from typing import Any
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class Message:
18
+ code: str
19
+ title: str
20
+ fix: str = ""
21
+
22
+
23
+ LOGIN_FIX = "Create an access token in the console (Account → Team → Developer access), then: ekl login"
24
+
25
+ CATALOGUE: dict[str, Message] = {
26
+ m.code: m
27
+ for m in (
28
+ # 1xx: sign-in, the network and ekl itself
29
+ Message("EKL-101", "You're not signed in", "ekl login"),
30
+ Message("EKL-102", "Your stored sign-in ({path}) is damaged", "ekl login"),
31
+ Message("EKL-103", "Your sign-in has expired", LOGIN_FIX),
32
+ Message("EKL-104", "That's a console session token; ekl needs an access token (eklt_…)", LOGIN_FIX),
33
+ Message("EKL-105", "No access token given", LOGIN_FIX),
34
+ Message("EKL-106", "That access token isn't valid", LOGIN_FIX),
35
+ Message(
36
+ "EKL-107",
37
+ "The token lasts less than the {days} days you asked for",
38
+ "Create a {days}-day token in the console",
39
+ ),
40
+ Message("EKL-110", "{url} isn't HTTPS", "Use the network's https address: ekl login --platform https://…"),
41
+ Message(
42
+ "EKL-111",
43
+ "{here} redirected to {there}; ekl doesn't follow redirects with your token",
44
+ "Check the network's address: ekl login --platform <https address>",
45
+ ),
46
+ Message("EKL-112", "Can't reach {address}", "Check your connection, or the network's address (EKL_PLATFORM)"),
47
+ Message("EKL-113", "EuKollab didn't answer within {seconds} seconds", "Try again"),
48
+ Message("EKL-114", "No agent {ref} in your organization", "ekl agents lists your agents"),
49
+ Message("EKL-120", "{address} doesn't publish ekl", "Check the network's address (EKL_PLATFORM)"),
50
+ Message("EKL-121", "ekl {version} isn't published on {address}", "ekl upgrade --check shows the latest"),
51
+ Message("EKL-122", "ekl {version} is retired", "ekl upgrade installs the latest ({latest})"),
52
+ Message(
53
+ "EKL-123", "{command} isn't on your PATH", "Install it, or install ekl from the network's Downloads page"
54
+ ),
55
+ Message("EKL-124", "Installing ekl failed", "Fix what it says, then run the command again"),
56
+ Message(
57
+ "EKL-125",
58
+ "{command} is another ekl install in the way",
59
+ "Uninstall it (uv tool uninstall ekl-cli, or pipx uninstall ekl-cli), or set EKL_BIN_DIR to another folder",
60
+ ),
61
+ Message(
62
+ "EKL-126",
63
+ "This ekl doesn't name a connector version",
64
+ "Install ekl again from the network's Downloads page",
65
+ ),
66
+ Message(
67
+ "EKL-127",
68
+ "Can't pin the connector: {address} doesn't list {wheel}",
69
+ "Try again later, or install uv, which installs it from the network's index",
70
+ ),
71
+ Message(
72
+ "EKL-130",
73
+ "A release didn't verify, so nothing was installed",
74
+ "Install ekl from the network's Downloads page",
75
+ ),
76
+ Message(
77
+ "EKL-131", "No signature verifier is available", "Install one as said above, then run the command again"
78
+ ),
79
+ Message("EKL-140", "ekl mcp doesn't take --json: it speaks MCP on its standard output", "ekl mcp"),
80
+ # 2xx: the agent's folder and its MCP server
81
+ Message(
82
+ "EKL-201", "No agent.json in {folder}", "Run this in the agent's folder, or create one: ekl add --mcp <url>"
83
+ ),
84
+ Message("EKL-202", "{path} isn't valid JSON", "Fix the file (agent.json itself is rewritten by ekl sync)"),
85
+ Message("EKL-203", "{path} names no handle", "ekl sync writes agent.json again"),
86
+ Message(
87
+ "EKL-204", "No agent named", "Give its handle (ekl status @my-agent), or run this in the agent's folder"
88
+ ),
89
+ Message("EKL-205", "This folder already holds an agent", "ekl sync here reads its server again"),
90
+ Message("EKL-206", "{env} lacks {names}", "ekl add writes them; or set them in .env"),
91
+ Message("EKL-207", "{env} not found", "Run this in the agent's folder"),
92
+ Message("EKL-208", "The key in .env isn't an agent key (eklp_…)", "ekl add writes one"),
93
+ Message("EKL-210", "{handle} isn't a valid handle", "Use @ and 2 to 31 lowercase letters, digits or hyphens"),
94
+ Message(
95
+ "EKL-211", "{path} must hold an object with agent and tools", "Fix the file, or remove it and run: ekl sync"
96
+ ),
97
+ Message("EKL-212", "uses in eukollab.json isn't valid", 'Write it as [{{"need": "Validate EU VAT numbers"}}]'),
98
+ Message("EKL-213", "That value isn't valid", "Correct it as said above"),
99
+ Message("EKL-214", "The terms file {file} isn't in {folder}", "Fix terms.text_file in eukollab.json"),
100
+ Message(
101
+ "EKL-215",
102
+ "The icon can't be used",
103
+ "Use a PNG, JPEG or WebP image of at most 256 KB, or an https:// address",
104
+ ),
105
+ Message("EKL-216", "A header can't be used", '--header "Authorization: Bearer $KEY", once per header'),
106
+ Message("EKL-217", "--header goes with --mcp", 'ekl add --mcp <url> --header "Name: value"'),
107
+ Message("EKL-220", "No MCP server named", "Set EKL_UPSTREAM_MCP_URL in .env, or: ekl add --mcp <url>"),
108
+ Message(
109
+ "EKL-221", "{url} isn't an MCP server's http(s) address", "Set EKL_UPSTREAM_MCP_URL in .env to its MCP URL"
110
+ ),
111
+ Message(
112
+ "EKL-222",
113
+ "{host} is on the web, but its address is http",
114
+ "Put its https address in EKL_UPSTREAM_MCP_URL in .env",
115
+ ),
116
+ Message("EKL-223", "{host} doesn't resolve from here", "Check EKL_UPSTREAM_MCP_URL in .env"),
117
+ Message(
118
+ "EKL-224",
119
+ "Can't read your MCP server",
120
+ "Start it, or check EKL_UPSTREAM_MCP_URL and EKL_UPSTREAM_HEADERS in .env",
121
+ ),
122
+ Message("EKL-225", "Stopped at a question", "Run the command again to answer it"),
123
+ # 3xx: check and sync
124
+ Message("EKL-301", "Announcing agent.json to the network failed", "Try again: ekl sync"),
125
+ Message("EKL-302", "Reading the relay address failed", "Try again"),
126
+ Message(
127
+ "EKL-303",
128
+ "The network's checks would refuse this agent.json",
129
+ "Change each item where it says (never agent.json itself), then run the command again",
130
+ ),
131
+ Message("EKL-304", "agent.json differs from what your server declares", "ekl sync"),
132
+ Message("EKL-305", "Rotating the agent key needs the network", "ekl login, then: ekl sync --rotate-key"),
133
+ Message("EKL-306", "No agent key in {path}", "ekl add writes one"),
134
+ # 4xx: deploy
135
+ Message(
136
+ "EKL-401", "Nothing deployed: no one is at the terminal to answer", "Run it at a terminal, or add --force"
137
+ ),
138
+ Message("EKL-402", "The agent stopped as it started", "Fix what its last lines say, then: ekl deploy"),
139
+ Message(
140
+ "EKL-403",
141
+ "Revision {revision} failed its checks; nothing changed for callers",
142
+ "Fix each item, then: ekl deploy",
143
+ ),
144
+ Message("EKL-404", "{folder} hasn't been deployed from here", "ekl deploy"),
145
+ Message("EKL-405", "Nothing stopped: no one is at the terminal to confirm", "ekl deploy --remove --confirm"),
146
+ Message(
147
+ "EKL-406",
148
+ "{destination} isn't ready on this machine; nothing was changed",
149
+ "Fix each item, then run it again",
150
+ ),
151
+ Message(
152
+ "EKL-407", "{name} can't name the deployment", "Use 1 to 28 lowercase letters, digits or hyphens (--name)"
153
+ ),
154
+ Message("EKL-408", "{command} failed", "Fix what it says, then run it again"),
155
+ Message(
156
+ "EKL-409",
157
+ "An agent that only uses services needs its agent credential",
158
+ "ekl status --settings --take-part",
159
+ ),
160
+ Message(
161
+ "EKL-410", "{file} not found: an agent that only uses services runs its callbacks", "ekl add writes it"
162
+ ),
163
+ Message(
164
+ "EKL-411",
165
+ "ekl new is gone: EuKollab adds agents you have built",
166
+ "Run your MCP server, then: ekl add --mcp <its MCP URL>",
167
+ ),
168
+ Message("EKL-412", "ekl agent {verb} is now {replaced}", "{replaced}"),
169
+ Message(
170
+ "EKL-413",
171
+ "ekl deploy takes no destination",
172
+ "ekl deploy (a server on the web runs on EuKollab, any other here)",
173
+ ),
174
+ # 5xx: status
175
+ Message("EKL-501", "{ref} is no longer one of your agents", "ekl agents lists your agents"),
176
+ Message("EKL-502", "One change at a time ({chosen})", "Run ekl status once for each"),
177
+ Message(
178
+ "EKL-503",
179
+ "{handle} has no version waiting for review",
180
+ "It appears once the agent announces one: ekl deploy",
181
+ ),
182
+ # 6xx: find, show and try
183
+ Message("EKL-601", "Name a service as @handle/service, not {ref}", "ekl find lists services by name"),
184
+ Message("EKL-602", "Say what you need", 'ekl find "validate EU VAT numbers"'),
185
+ Message("EKL-603", "--input must be a JSON object, or a file holding one", '--input \'{{"query": "…"}}\''),
186
+ Message(
187
+ "EKL-604",
188
+ "--expect isn't a valid expectation",
189
+ "Give a sentence, or a JSON object with checks and a threshold",
190
+ ),
191
+ # 7xx: account and settings
192
+ Message("EKL-701", "To change the budget, say which", "ekl budget set --daily <USD> --monthly <USD>"),
193
+ # 8xx: coding-agent setup
194
+ Message("EKL-801", "Claude Code's command line (claude) isn't on your PATH", "Install it, or use --project"),
195
+ Message("EKL-802", "{path} can't be updated", "Fix the file, or add the eukollab entry by hand"),
196
+ Message("EKL-803", "{command} failed", "Fix what it says, then run ekl setup again"),
197
+ # 9xx: the unexpected
198
+ Message(
199
+ "EKL-900", "ekl hit an unexpected error", "Run it again with EKL_DEBUG=1 for the details, and report it"
200
+ ),
201
+ Message("EKL-901", "ekl couldn't read that command", "{usage}"),
202
+ )
203
+ }
204
+
205
+
206
+ class CliError(Exception):
207
+ """A failure ekl reports as a standard message: its code, its title, the specifics, and the fix."""
208
+
209
+ def __init__(self, code: str, *details: str, **values: Any) -> None:
210
+ message = CATALOGUE[code]
211
+ self.code = code
212
+ self.title = message.title.format(**values)
213
+ self.fix = message.fix.format(**values)
214
+ self.details = [line for d in details if d for line in str(d).splitlines()]
215
+ super().__init__(self.reason())
216
+
217
+ def reason(self) -> str:
218
+ """The title and specifics, without the code: for text that quotes the failure ("not uploaded (…)")."""
219
+ details = " ".join(d.strip() for d in self.details)
220
+ return f"{self.title}: {details}" if details else self.title
221
+
222
+ def plain(self) -> str:
223
+ """Everything on one line, code and fix included: for the MCP server's answers and logs."""
224
+ return "; ".join([f"{self.code} {self.title}", *self.details, *([f"fix: {self.fix}"] if self.fix else [])])
225
+
226
+ def add(self, *lines: str) -> "CliError":
227
+ """What the command did about it, after the specifics: 'nothing was deployed'."""
228
+ self.details += [line for line in lines if line]
229
+ self.args = (self.reason(),)
230
+ return self
231
+
232
+
233
+ class RefusalError(CliError):
234
+ """The network refused: the protocol's own code and message, explained on the messages page."""
235
+
236
+ def __init__(self, code: str, message: str) -> None:
237
+ self.code = code
238
+ self.title = message
239
+ self.fix = ""
240
+ self.details = []
241
+ Exception.__init__(self, self.reason())
242
+
243
+ def reason(self) -> str:
244
+ details = " ".join(d.strip() for d in self.details)
245
+ return f"{self.title} ({self.code})" + (f": {details}" if details else "")