ekl-cli 0.10.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ekl_cli/__init__.py +2 -0
- ekl_cli/bridge.py +160 -0
- ekl_cli/client.py +232 -0
- ekl_cli/clients/.agents/plugins/marketplace.json +20 -0
- ekl_cli/clients/.claude-plugin/marketplace.json +16 -0
- ekl_cli/clients/README.md +3 -0
- ekl_cli/clients/claude-code/.claude-plugin/plugin.json +14 -0
- ekl_cli/clients/claude-code/.mcp.json +10 -0
- ekl_cli/clients/claude-code/commands/check.md +11 -0
- ekl_cli/clients/claude-code/commands/deploy.md +49 -0
- ekl_cli/clients/claude-code/commands/status.md +10 -0
- ekl_cli/clients/claude-code/skills/agent-behaviour/SKILL.md +112 -0
- ekl_cli/clients/claude-code/skills/agent-config-in-repo/SKILL.md +92 -0
- ekl_cli/clients/claude-code/skills/connect-mcp-server/SKILL.md +296 -0
- ekl_cli/clients/claude-code/skills/operate-agent/SKILL.md +54 -0
- ekl_cli/clients/claude-code/skills/plan-with-the-network/SKILL.md +60 -0
- ekl_cli/clients/codex/mcp.json +11 -0
- ekl_cli/clients/codex/plugin.json +8 -0
- ekl_cli/clients/codex/skills/agent-behaviour/SKILL.md +112 -0
- ekl_cli/clients/codex/skills/agent-config-in-repo/SKILL.md +92 -0
- ekl_cli/clients/codex/skills/connect-mcp-server/SKILL.md +296 -0
- ekl_cli/clients/codex/skills/operate-agent/SKILL.md +54 -0
- ekl_cli/clients/codex/skills/plan-with-the-network/SKILL.md +60 -0
- ekl_cli/clients/cursor/.cursor-plugin/plugin.json +8 -0
- ekl_cli/clients/cursor/commands/check.md +11 -0
- ekl_cli/clients/cursor/commands/deploy.md +49 -0
- ekl_cli/clients/cursor/commands/status.md +10 -0
- ekl_cli/clients/cursor/mcp.json +10 -0
- ekl_cli/clients/cursor/rules/eukollab.mdc +81 -0
- ekl_cli/clients/cursor/skills/agent-behaviour/SKILL.md +112 -0
- ekl_cli/clients/cursor/skills/agent-config-in-repo/SKILL.md +92 -0
- ekl_cli/clients/cursor/skills/connect-mcp-server/SKILL.md +296 -0
- ekl_cli/clients/cursor/skills/operate-agent/SKILL.md +54 -0
- ekl_cli/clients/cursor/skills/plan-with-the-network/SKILL.md +60 -0
- ekl_cli/clients/gemini/GEMINI.md +76 -0
- ekl_cli/clients/gemini/gemini-extension.json +14 -0
- ekl_cli/clients/generic/AGENTS.md +76 -0
- ekl_cli/clients/generic/mcp.json +10 -0
- ekl_cli/clients/vscode/instructions/eukollab.instructions.md +80 -0
- ekl_cli/clients/vscode/mcp.json +11 -0
- ekl_cli/command_help.py +223 -0
- ekl_cli/declarations.py +492 -0
- ekl_cli/deploy.py +432 -0
- ekl_cli/deploy_command.py +556 -0
- ekl_cli/derive.py +217 -0
- ekl_cli/design.py +339 -0
- ekl_cli/finder.py +695 -0
- ekl_cli/icon.py +102 -0
- ekl_cli/install.py +185 -0
- ekl_cli/lifecycle.py +357 -0
- ekl_cli/main.py +643 -0
- ekl_cli/mcp.py +279 -0
- ekl_cli/messages.py +245 -0
- ekl_cli/onboard.py +1040 -0
- ekl_cli/participation.py +247 -0
- ekl_cli/project.py +211 -0
- ekl_cli/prompt.py +176 -0
- ekl_cli/py.typed +0 -0
- ekl_cli/release_root.json +9 -0
- ekl_cli/release_trust.py +376 -0
- ekl_cli/repair.py +266 -0
- ekl_cli/schema.py +117 -0
- ekl_cli/setup.py +326 -0
- ekl_cli/supervise.py +162 -0
- ekl_cli/templates/python/eukollab-agent.md.tmpl +202 -0
- ekl_cli/templates/python/eukollab_callbacks.py.tmpl +509 -0
- ekl_cli/templates/versions.json +3 -0
- ekl_cli/ui.py +158 -0
- ekl_cli/versions.py +402 -0
- ekl_cli-0.10.0.dist-info/METADATA +72 -0
- ekl_cli-0.10.0.dist-info/RECORD +75 -0
- ekl_cli-0.10.0.dist-info/WHEEL +5 -0
- ekl_cli-0.10.0.dist-info/entry_points.txt +2 -0
- ekl_cli-0.10.0.dist-info/licenses/LICENSE +10 -0
- ekl_cli-0.10.0.dist-info/top_level.txt +1 -0
ekl_cli/participation.py
ADDED
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# Copyright © 2026 EuKreate, Inc. All rights reserved.
|
|
2
|
+
"""The questions `ekl add` asks about a newly registered agent on the network, and
|
|
3
|
+
`ekl status --settings` asks again later: whether it takes part in the network, which issues its agent-operation
|
|
4
|
+
credential into .env; whether people may run its services on Explore; and who accepts paid agreements for its
|
|
5
|
+
services (spec 13.12, 18.2). Each has a default, taken with nobody at a terminal or with `ekl add --keep-defaults`.
|
|
6
|
+
|
|
7
|
+
The credential is shown once, so it goes straight into .env and is never printed.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
import argparse
|
|
11
|
+
from dataclasses import dataclass, field
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
from ekl_cli import project, prompt
|
|
16
|
+
from ekl_cli.client import CliError, OwnerApi
|
|
17
|
+
|
|
18
|
+
CREDENTIAL = "EKL_AGENT_CREDENTIAL"
|
|
19
|
+
# Every activity: the Behaviour tab and the spending limits still decide what the agent may do.
|
|
20
|
+
SCOPES = ["events", "posts", "messages", "connections", "services", "spending"]
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def ask(question: str, default: bool, given: bool | None, *details: str) -> bool:
|
|
24
|
+
"""The flag's answer, else the person's, else the default when nobody is at a terminal."""
|
|
25
|
+
if given is not None:
|
|
26
|
+
return given
|
|
27
|
+
if not prompt.interactive():
|
|
28
|
+
return default
|
|
29
|
+
return prompt.confirm(question, default, *details)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def issue(api: OwnerApi, agent_id: str) -> str:
|
|
33
|
+
"""A new agent-operation credential with every scope; the network shows it this once."""
|
|
34
|
+
issued = api.request("POST", f"/agents/{agent_id}/credentials", {"scopes": SCOPES})
|
|
35
|
+
return str(issued["token"])
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
# Who accepts paid agreements for the agent's services (spec 18.2): the answers and the default. Paid runs need no
|
|
39
|
+
# approval: each is paid from the consumer's prepaid wallet.
|
|
40
|
+
ACCEPTS = [
|
|
41
|
+
prompt.Option("a", "the agent", "it accepts paid agreements itself, within its published plans and terms"),
|
|
42
|
+
prompt.Option("y", "you", "each paid agreement waits for you in the console"),
|
|
43
|
+
]
|
|
44
|
+
ACCEPTS_MODE = {"a": "agent", "y": "publisher"}
|
|
45
|
+
DEFAULT_ACCEPTS = "agent"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _rules(api: OwnerApi, agent_id: str) -> dict[str, Any]:
|
|
49
|
+
"""The agent's rules as they stand (GET answers them under `config`), so a change keeps every other rule."""
|
|
50
|
+
found: dict[str, Any] = api.request("GET", f"/agents/{agent_id}/config")
|
|
51
|
+
rules: dict[str, Any] = found.get("config") or {}
|
|
52
|
+
return rules
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _save(api: OwnerApi, agent_id: str, rules: dict[str, Any]) -> None:
|
|
56
|
+
api.request("PUT", f"/agents/{agent_id}/config", rules)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _mode(
|
|
60
|
+
choices: list[prompt.Option], modes: dict[str, str], question: str, current: str, given: str | None, *details: str
|
|
61
|
+
) -> str:
|
|
62
|
+
"""A mode from an option, else the person's choice, else the current or default one."""
|
|
63
|
+
if given is not None:
|
|
64
|
+
return given
|
|
65
|
+
if not prompt.interactive():
|
|
66
|
+
return current
|
|
67
|
+
default = next(k for k, v in modes.items() if v == current)
|
|
68
|
+
return modes[prompt.pick(question, choices, default, *details)]
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
@dataclass(frozen=True)
|
|
72
|
+
class Settings:
|
|
73
|
+
"""Answers given as options; None asks, or takes the current or default value."""
|
|
74
|
+
|
|
75
|
+
take_part: bool | None = None
|
|
76
|
+
explore: bool | None = None
|
|
77
|
+
accepts: str | None = None
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
# No option given: every question is asked, or takes its default.
|
|
81
|
+
UNANSWERED = Settings()
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
@dataclass
|
|
85
|
+
class Answers:
|
|
86
|
+
"""What the answers produced: values to write into .env and lines to show the person."""
|
|
87
|
+
|
|
88
|
+
env: dict[str, str] = field(default_factory=dict)
|
|
89
|
+
notes: list[str] = field(default_factory=list)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _take_part(api: OwnerApi, handle: str, agent_id: str, given: bool | None, answers: Answers) -> None:
|
|
93
|
+
if not ask(
|
|
94
|
+
f"Should {handle} take part in the network?",
|
|
95
|
+
True,
|
|
96
|
+
given,
|
|
97
|
+
"Yes: it can answer needs, post, and use other agents' services, within the rules you set in the "
|
|
98
|
+
"console; its agent-operation credential goes into .env. No: it only serves calls.",
|
|
99
|
+
):
|
|
100
|
+
answers.notes.append(f"{handle} serves calls only; to change that later: ekl status {handle} --settings")
|
|
101
|
+
return
|
|
102
|
+
try:
|
|
103
|
+
answers.env[CREDENTIAL] = issue(api, agent_id)
|
|
104
|
+
answers.notes.append(f"{handle} takes part: its agent-operation credential is in .env ({CREDENTIAL})")
|
|
105
|
+
except CliError as exc:
|
|
106
|
+
answers.notes.append(
|
|
107
|
+
f"{handle} serves calls only: the credential wasn't issued ({exc}). "
|
|
108
|
+
f"An admin can run: ekl status {handle} --settings --take-part"
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _offering(api: OwnerApi, handle: str, agent_id: str, given: Settings, rules: dict[str, Any]) -> list[str]:
|
|
113
|
+
"""Explore and paid agreements, saved in one change of the agent's rules. Lines saying where each stands."""
|
|
114
|
+
portal, commerce = dict(rules.get("portal") or {}), dict(rules.get("commerce") or {})
|
|
115
|
+
on = ask(
|
|
116
|
+
f"List {handle} on Explore?",
|
|
117
|
+
bool(portal.get("consumers")),
|
|
118
|
+
given.explore,
|
|
119
|
+
"Yes: once it is published, signed-in people find it on Explore and run its services; while it is in testing, "
|
|
120
|
+
"only you see it there, labelled Test.",
|
|
121
|
+
)
|
|
122
|
+
accepts = _mode(
|
|
123
|
+
ACCEPTS,
|
|
124
|
+
ACCEPTS_MODE,
|
|
125
|
+
f"Who accepts paid agreements for {handle}'s services?",
|
|
126
|
+
str(commerce.get("acceptance") or DEFAULT_ACCEPTS),
|
|
127
|
+
given.accepts,
|
|
128
|
+
"Applies once a service is paid.",
|
|
129
|
+
)
|
|
130
|
+
rules["portal"] = portal | {"consumers": on}
|
|
131
|
+
rules["commerce"] = commerce | {"acceptance": accepts}
|
|
132
|
+
_save(api, agent_id, rules)
|
|
133
|
+
return [
|
|
134
|
+
f"{handle} will be on Explore: for you now, labelled Test, and for everyone once you publish it"
|
|
135
|
+
if on
|
|
136
|
+
else f"{handle} isn't on Explore",
|
|
137
|
+
"paid agreements: " + ("the agent accepts them within its terms" if accepts == "agent" else "you accept each"),
|
|
138
|
+
]
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def answer(
|
|
142
|
+
api: OwnerApi,
|
|
143
|
+
registered: dict[str, Any],
|
|
144
|
+
given: Settings = UNANSWERED,
|
|
145
|
+
*,
|
|
146
|
+
serves: bool = True,
|
|
147
|
+
) -> Answers:
|
|
148
|
+
"""Ask the network questions for a newly registered agent and act on the answers. A person without the Admin role
|
|
149
|
+
can't issue credentials, nor one without the role for paid agreements change them: the notes say what stayed as
|
|
150
|
+
it was and who can change it."""
|
|
151
|
+
handle, agent_id = str(registered.get("handle") or registered["agent_id"]), str(registered["agent_id"])
|
|
152
|
+
answers = Answers()
|
|
153
|
+
_take_part(api, handle, agent_id, given.take_part, answers)
|
|
154
|
+
if serves:
|
|
155
|
+
try:
|
|
156
|
+
rules = _rules(api, agent_id)
|
|
157
|
+
answers.notes += _offering(api, handle, agent_id, given, rules)
|
|
158
|
+
except CliError as exc:
|
|
159
|
+
answers.notes.append(
|
|
160
|
+
f"Explore and paid work weren't set ({exc}); someone with the role can run: "
|
|
161
|
+
f"ekl status {handle} --settings"
|
|
162
|
+
)
|
|
163
|
+
answers.notes.append(f"to change these later: ekl status {handle} --settings")
|
|
164
|
+
return answers
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def _takes_part(api: OwnerApi, agent_id: str) -> bool:
|
|
168
|
+
found = api.request("GET", f"/agents/{agent_id}/credentials").get("credentials") or []
|
|
169
|
+
return any(c.get("kind") == "agent_operation" and not c.get("revoked") for c in found)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def _stop_taking_part(api: OwnerApi, agent_id: str, env: Path) -> str:
|
|
173
|
+
"""Revoke the agent's agent-operation credentials and take the credential out of .env: it serves calls only, and
|
|
174
|
+
its console rules make its decisions."""
|
|
175
|
+
found = api.request("GET", f"/agents/{agent_id}/credentials").get("credentials") or []
|
|
176
|
+
for credential in found:
|
|
177
|
+
if credential.get("kind") == "agent_operation" and not credential.get("revoked"):
|
|
178
|
+
api.request("DELETE", f"/agents/{agent_id}/credentials/{credential['credential_id']}")
|
|
179
|
+
if env.is_file():
|
|
180
|
+
kept = [line for line in env.read_text().splitlines() if not line.startswith(f"{CREDENTIAL}=")]
|
|
181
|
+
env.write_text("\n".join(kept) + "\n")
|
|
182
|
+
return (
|
|
183
|
+
f"it no longer takes part: its agent-operation credential is revoked and out of {env}; "
|
|
184
|
+
"run ekl deploy again so the running agent follows"
|
|
185
|
+
)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def cmd_agent_settings(api: OwnerApi, args: Any) -> tuple[dict[str, Any], str]:
|
|
189
|
+
"""The setup questions again for an agent, its current answers the defaults: take part, Explore and paid
|
|
190
|
+
agreements. Options answer them without asking; with neither, nothing changes and the settings are shown."""
|
|
191
|
+
agent_id = api.agent_id(args.agent)
|
|
192
|
+
given = Settings(args.take_part, args.explore, args.accepts)
|
|
193
|
+
rules = _rules(api, agent_id)
|
|
194
|
+
taking_part = _takes_part(api, agent_id)
|
|
195
|
+
changing = prompt.interactive() or given != UNANSWERED
|
|
196
|
+
lines: list[str] = []
|
|
197
|
+
if changing and not taking_part and given.take_part is not False:
|
|
198
|
+
env = Path(args.env)
|
|
199
|
+
wanted = ask(
|
|
200
|
+
f"Should {args.agent} take part in the network?",
|
|
201
|
+
False,
|
|
202
|
+
given.take_part,
|
|
203
|
+
f"Yes issues its agent-operation credential into {env}; then deploy it again.",
|
|
204
|
+
)
|
|
205
|
+
if wanted:
|
|
206
|
+
if not env.exists():
|
|
207
|
+
raise CliError("EKL-207", env=env)
|
|
208
|
+
project.write_env(env, {CREDENTIAL: issue(api, agent_id)})
|
|
209
|
+
taking_part = True
|
|
210
|
+
lines.append(
|
|
211
|
+
f"its agent-operation credential is in {env} ({CREDENTIAL}); run ekl deploy again so agent.json and "
|
|
212
|
+
"the running agent follow"
|
|
213
|
+
)
|
|
214
|
+
lines.insert(0, f"{args.agent} " + ("takes part in the network" if taking_part else "serves calls only"))
|
|
215
|
+
if changing:
|
|
216
|
+
lines += _offering(api, args.agent, agent_id, given, rules)
|
|
217
|
+
else:
|
|
218
|
+
commerce = rules.get("commerce") or {}
|
|
219
|
+
lines += [
|
|
220
|
+
f"Explore: {'on' if (rules.get('portal') or {}).get('consumers') else 'off'}",
|
|
221
|
+
f"paid agreements: {commerce.get('acceptance') or 'not set'}",
|
|
222
|
+
]
|
|
223
|
+
if taking_part and given.take_part is False:
|
|
224
|
+
lines.append(_stop_taking_part(api, agent_id, Path(args.env)))
|
|
225
|
+
taking_part = False
|
|
226
|
+
lines[0] = f"{args.agent} serves calls only"
|
|
227
|
+
return {"agent_id": agent_id, "takes_part": taking_part, "config": rules}, "\n".join(lines)
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def network_questions(parser: Any) -> None:
|
|
231
|
+
"""The settings on the network as options of ekl status --settings, for scripts; without them ekl asks, or with
|
|
232
|
+
nobody at a terminal shows them."""
|
|
233
|
+
parser.add_argument(
|
|
234
|
+
"--take-part",
|
|
235
|
+
dest="take_part",
|
|
236
|
+
action=argparse.BooleanOptionalAction,
|
|
237
|
+
help="take part in the network (issue the agent-operation credential into .env), or --no-take-part to "
|
|
238
|
+
"serve calls only",
|
|
239
|
+
)
|
|
240
|
+
parser.add_argument(
|
|
241
|
+
"--explore", action=argparse.BooleanOptionalAction, help="list the agent on Explore, or --no-explore"
|
|
242
|
+
)
|
|
243
|
+
parser.add_argument(
|
|
244
|
+
"--accepts",
|
|
245
|
+
choices=["agent", "publisher"],
|
|
246
|
+
help="who accepts paid agreements for its services: the agent within its terms (default), or you, each one",
|
|
247
|
+
)
|
ekl_cli/project.py
ADDED
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
# Copyright © 2026 EuKreate, Inc. All rights reserved.
|
|
2
|
+
"""The files and the key of an agent's folder on the publisher's machine, as `ekl add` writes them.
|
|
3
|
+
|
|
4
|
+
The key is generated here and never leaves the machine: registration sends only its SHA-256, and the agent presents
|
|
5
|
+
the key itself when it announces. It is written to .env only, which is kept out of git.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import base64
|
|
9
|
+
import hashlib
|
|
10
|
+
import hmac
|
|
11
|
+
import json
|
|
12
|
+
import re
|
|
13
|
+
import secrets
|
|
14
|
+
import urllib.error
|
|
15
|
+
import urllib.request
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
from typing import Any
|
|
18
|
+
|
|
19
|
+
from ekl_cli import ui
|
|
20
|
+
from ekl_cli.client import CliError, OwnerApi, write_private
|
|
21
|
+
|
|
22
|
+
# The adapter profile, the only one (EKP 3.0): every agent is the folder `ekl add` writes, served by the connector.
|
|
23
|
+
ADAPTER = "adapter"
|
|
24
|
+
# Which variable holds the profile's key, and its prefix (the contract's key table).
|
|
25
|
+
KEY_VARIABLE = {ADAPTER: "EKL_PROVIDER_CREDENTIAL"}
|
|
26
|
+
KEY_PREFIX = {ADAPTER: "eklp_"}
|
|
27
|
+
HANDLE = re.compile(r"^@[a-z0-9-]{2,31}$")
|
|
28
|
+
ENV_LINE = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=")
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def templates_dir(lang: str = "python") -> Path:
|
|
32
|
+
return Path(__file__).parent / "templates" / lang
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
ADAPTER_PACKAGE = "ekl-provider-adapter"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def adapter_version() -> str:
|
|
39
|
+
"""The provider adapter version this ekl was released with: the connector `ekl deploy` runs for a local server."""
|
|
40
|
+
try:
|
|
41
|
+
return str(json.loads((Path(__file__).parent / "templates" / "versions.json").read_text())["provider_adapter"])
|
|
42
|
+
except (OSError, ValueError, KeyError) as exc:
|
|
43
|
+
raise CliError("EKL-126") from exc
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def adapter_requirement(network: str, extras: str = "") -> str:
|
|
47
|
+
"""The provider adapter as a direct reference to the wheel on the network, with its SHA-256 when the network's
|
|
48
|
+
index lists it. Never a bare name with PyPI as a second index: anyone could publish that name there with a higher
|
|
49
|
+
version, and pip would install theirs."""
|
|
50
|
+
wheel = f"ekl_provider_adapter-{adapter_version()}-py3-none-any.whl"
|
|
51
|
+
url = f"{network.rstrip('/')}/downloads/{wheel}"
|
|
52
|
+
pinned = False
|
|
53
|
+
try:
|
|
54
|
+
with urllib.request.urlopen(f"{network.rstrip('/')}/simple/{ADAPTER_PACKAGE}/", timeout=10) as page: # nosec B310 - the network's address, checked as HTTPS or this machine
|
|
55
|
+
listing = page.read().decode("utf-8", "replace")
|
|
56
|
+
found = re.search(rf"{re.escape(wheel)}#sha256=([0-9a-f]{{64}})", listing)
|
|
57
|
+
if found:
|
|
58
|
+
url += f"#sha256={found.group(1)}"
|
|
59
|
+
pinned = True
|
|
60
|
+
except (urllib.error.URLError, OSError):
|
|
61
|
+
pass
|
|
62
|
+
if not pinned:
|
|
63
|
+
# Without the index's hash, the wheel installed later could be any file served at that address.
|
|
64
|
+
raise CliError(
|
|
65
|
+
"EKL-127",
|
|
66
|
+
"Without the index's SHA-256, ekl can't pin the file it installs.",
|
|
67
|
+
address=f"{network.rstrip('/')}/simple/",
|
|
68
|
+
wheel=wheel,
|
|
69
|
+
)
|
|
70
|
+
return f"{ADAPTER_PACKAGE}{f'[{extras}]' if extras else ''} @ {url}"
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def render(template: str, values: dict[str, str], lang: str = "python") -> str:
|
|
74
|
+
"""A template from the wheel (`ekl_cli/templates/`) with its {{placeholders}} filled."""
|
|
75
|
+
text = (templates_dir(lang) / f"{template}.tmpl").read_text()
|
|
76
|
+
for key, value in values.items():
|
|
77
|
+
text = text.replace("{{" + key + "}}", value)
|
|
78
|
+
return text
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def new_key(profile: str) -> str:
|
|
82
|
+
# The prefix tells the profile apart (profile_of) and lets secret scanners recognise a leaked key.
|
|
83
|
+
return KEY_PREFIX[profile] + secrets.token_urlsafe(32)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def key_hash(key: str) -> str:
|
|
87
|
+
return hashlib.sha256(key.encode()).hexdigest()
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def profile_of(key: str) -> str:
|
|
91
|
+
for profile, prefix in KEY_PREFIX.items():
|
|
92
|
+
if key.startswith(prefix):
|
|
93
|
+
return profile
|
|
94
|
+
raise CliError("EKL-208")
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def check_handle(handle: str | None) -> str | None:
|
|
98
|
+
"""The handle asked for, checked here so a bad one fails before anything is written or registered."""
|
|
99
|
+
if handle is not None and not HANDLE.match(handle):
|
|
100
|
+
raise CliError("EKL-210", handle=handle)
|
|
101
|
+
return handle
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def register(api: OwnerApi, profile: str, key: str, handle: str | None) -> dict[str, Any]:
|
|
105
|
+
"""Register the key's hash, with the handle asked for, to the signed-in publisher's organisation. The network
|
|
106
|
+
makes the handle unique, so the answer's handle is the one to keep."""
|
|
107
|
+
# The proof key goes once, now: the network keys endpoint challenges and enrollment with it (EKP 1.2 §3.1).
|
|
108
|
+
body = {"profile": profile, "key_hash": key_hash(key), "handle": handle, "proof_key": proof_key(key)}
|
|
109
|
+
registered: dict[str, Any] = api.request("POST", "/agents/register", body)
|
|
110
|
+
return registered
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def refuse_existing(paths: list[Path]) -> None:
|
|
114
|
+
"""An agent is added once: its key and agent.json are never replaced by a second add."""
|
|
115
|
+
found = [p.name for p in paths if p.exists()]
|
|
116
|
+
if found:
|
|
117
|
+
raise CliError("EKL-205", f"{', '.join(found)} already exist in {paths[0].parent}.")
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def read_env(path: Path) -> dict[str, str]:
|
|
121
|
+
"""The plain `KEY=value` lines of a .env (an `export` prefix and surrounding quotes allowed); no interpolation."""
|
|
122
|
+
values = {}
|
|
123
|
+
for line in path.read_text().splitlines() if path.exists() else []:
|
|
124
|
+
if (match := ENV_LINE.match(line)) and not line.lstrip().startswith("#"):
|
|
125
|
+
values[match.group(1)] = line.split("=", 1)[1].strip().strip("'\"")
|
|
126
|
+
return values
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def write_env(path: Path, values: dict[str, str]) -> None:
|
|
130
|
+
""".env with these values. Lines already there for other variables are kept, so a key rotation or a second run
|
|
131
|
+
keeps the publisher's own settings."""
|
|
132
|
+
kept = [
|
|
133
|
+
line
|
|
134
|
+
for line in (path.read_text().splitlines() if path.exists() else [])
|
|
135
|
+
if not ((match := ENV_LINE.match(line)) and match.group(1) in values)
|
|
136
|
+
]
|
|
137
|
+
if not kept:
|
|
138
|
+
kept = ["# Secrets for this agent, written by ekl. Never commit this file; .gitignore keeps it out of git."]
|
|
139
|
+
write_private(path, "\n".join([*kept, *(f"{k}={v}" for k, v in values.items())]) + "\n")
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def callback_key(credential: str) -> str:
|
|
143
|
+
"""EKL_CALLBACK_KEY: what the agent's callbacks file checks and signs the connector's events with (callback v2),
|
|
144
|
+
derived from the credential so the file never holds the credential itself."""
|
|
145
|
+
return hmac.new(credential.encode(), b"ekl-callback-v2", hashlib.sha256).hexdigest()
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def proof_key(credential: str) -> str:
|
|
149
|
+
"""The endpoint proof key (EKP 1.2 §3.1), sent once when the key is registered or rotated, as hex."""
|
|
150
|
+
return hmac.new(credential.encode(), b"ekl-endpoint-proof-v2", hashlib.sha256).hexdigest()
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def ensure_local_secrets(directory: Path) -> dict[str, str]:
|
|
154
|
+
"""The values the connector and the agent's callbacks share on this machine, written to .env when missing:
|
|
155
|
+
EKL_LOCAL_TOKEN, which the connector's local API requires from the moment it is set, and EKL_CALLBACK_KEY, kept
|
|
156
|
+
in step with the credential that signs the callbacks. Returns .env as it is now."""
|
|
157
|
+
path = directory / ".env"
|
|
158
|
+
env = read_env(path)
|
|
159
|
+
wanted: dict[str, str] = {}
|
|
160
|
+
if not env.get("EKL_LOCAL_TOKEN"):
|
|
161
|
+
wanted["EKL_LOCAL_TOKEN"] = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
|
|
162
|
+
signer = env.get("EKL_AGENT_CREDENTIAL") or env.get("EKL_PROVIDER_CREDENTIAL")
|
|
163
|
+
if signer and env.get("EKL_CALLBACK_KEY") != callback_key(signer):
|
|
164
|
+
wanted["EKL_CALLBACK_KEY"] = callback_key(signer)
|
|
165
|
+
if wanted:
|
|
166
|
+
write_env(path, wanted)
|
|
167
|
+
return env | wanted
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def write_agent_env(directory: Path, env: dict[str, str], registered: dict[str, Any] | None) -> None:
|
|
171
|
+
"""A new agent's .env: its values, its agent ID once registered (callback v2 binds each event to it), and the
|
|
172
|
+
local API's token and the callbacks' key."""
|
|
173
|
+
if registered and registered.get("agent_id"):
|
|
174
|
+
env = env | {"EKL_AGENT_ID": str(registered["agent_id"])}
|
|
175
|
+
write_env(directory / ".env", env)
|
|
176
|
+
ensure_local_secrets(directory)
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def missing_ignores(path: Path, entries: tuple[str, ...]) -> list[str]:
|
|
180
|
+
lines = path.read_text().splitlines() if path.exists() else []
|
|
181
|
+
return [e for e in entries if e not in lines]
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def add_ignores(path: Path, entries: list[str]) -> None:
|
|
185
|
+
lines = path.read_text().splitlines() if path.exists() else []
|
|
186
|
+
path.write_text("\n".join([*lines, *entries]) + "\n")
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def ensure_gitignored(directory: Path) -> None:
|
|
190
|
+
"""Add .env to the folder's .gitignore unless a pattern there already covers it: the key must never be committed."""
|
|
191
|
+
path = directory / ".gitignore"
|
|
192
|
+
lines = path.read_text().splitlines() if path.exists() else []
|
|
193
|
+
if not any(line.strip() in {".env", "/.env", ".env*", "*.env"} for line in lines):
|
|
194
|
+
path.write_text("\n".join([*lines, ".env"]) + "\n")
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def registration_note(profile: str, registered: dict[str, Any] | None, directory: Path) -> str:
|
|
198
|
+
"""What happened to the key, for the command's output: registered (and by when the agent must announce), or not.
|
|
199
|
+
The key itself is never shown, only where it is."""
|
|
200
|
+
variable = KEY_VARIABLE[profile]
|
|
201
|
+
if registered is None:
|
|
202
|
+
return (
|
|
203
|
+
f"generated the agent key in {directory / '.env'} ({variable}) but did not register it (--no-register): "
|
|
204
|
+
"the network will refuse its announcement until it is registered"
|
|
205
|
+
)
|
|
206
|
+
expires = ui.local_time(registered["expires_at"]) if registered.get("expires_at") else ""
|
|
207
|
+
return (
|
|
208
|
+
f"registered the agent key's hash as {registered.get('handle') or registered['agent_id']} "
|
|
209
|
+
f"({registered['agent_id']}); the key is in {directory / '.env'} ({variable})"
|
|
210
|
+
+ (f". The agent must announce itself by {expires}" if expires else "")
|
|
211
|
+
)
|
ekl_cli/prompt.py
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# Copyright © 2026 EuKreate, Inc. All rights reserved.
|
|
2
|
+
"""How ekl asks the person at the terminal: a titled section that explains a question once, then short answers.
|
|
3
|
+
|
|
4
|
+
Questions go to standard error, so a command's own output (and its --json) on standard output stays clean. Styling
|
|
5
|
+
is used only on a terminal and never when NO_COLOR is set (https://no-color.org)."""
|
|
6
|
+
|
|
7
|
+
import os
|
|
8
|
+
import sys
|
|
9
|
+
import textwrap
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
from typing import TextIO
|
|
12
|
+
|
|
13
|
+
from ekl_cli.client import CliError
|
|
14
|
+
|
|
15
|
+
WIDTH = 88
|
|
16
|
+
# Whether this run has asked anything, so the command's output can start apart from the questions.
|
|
17
|
+
ASKED = {"any": False}
|
|
18
|
+
# --keep-defaults: every question takes its default, as it does with nobody at a terminal.
|
|
19
|
+
DEFAULTS = {"only": False}
|
|
20
|
+
BOLD, DIM, CYAN = "1", "2", "36"
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def interactive() -> bool:
|
|
24
|
+
"""Whether to ask: someone is at the terminal and --keep-defaults wasn't given."""
|
|
25
|
+
return sys.stdin.isatty() and not DEFAULTS["only"]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def styled(stream: TextIO) -> bool:
|
|
29
|
+
return stream.isatty() and not os.environ.get("NO_COLOR")
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def style(text: str, *codes: str, stream: TextIO | None = None) -> str:
|
|
33
|
+
"""The text in the given ANSI styles, when the stream shows them."""
|
|
34
|
+
if not codes or not styled(stream or sys.stdout):
|
|
35
|
+
return text
|
|
36
|
+
return f"\033[{';'.join(codes)}m{text}\033[0m"
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def heading(text: str, stream: TextIO | None = None) -> str:
|
|
40
|
+
return style(text, BOLD, stream=stream)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def wrap(text: str, indent: str = " ") -> list[str]:
|
|
44
|
+
# Paths, addresses and commands stay whole, so they can be copied.
|
|
45
|
+
return textwrap.wrap(
|
|
46
|
+
text, WIDTH, initial_indent=indent, subsequent_indent=indent, break_long_words=False, break_on_hyphens=False
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _say(line: str = "") -> None:
|
|
51
|
+
print(line, file=sys.stderr)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
# The answer marker: a right-pointing quotation mark, chosen over ">" because it reads as a prompt, not a shell
|
|
55
|
+
# redirect.
|
|
56
|
+
MARK = "\u203a"
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _reply(answers: str) -> str:
|
|
60
|
+
return _raw(answers).lower()
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def after_questions() -> list[str]:
|
|
64
|
+
"""A blank line to start the output with, when questions came before it."""
|
|
65
|
+
return [""] if ASKED["any"] else []
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def section(title: str, *paragraphs: str) -> None:
|
|
69
|
+
"""A blank line, the title and what the questions under it are about."""
|
|
70
|
+
_say()
|
|
71
|
+
_say(heading(title, sys.stderr))
|
|
72
|
+
for paragraph in paragraphs:
|
|
73
|
+
for line in wrap(paragraph):
|
|
74
|
+
_say(style(line, DIM, stream=sys.stderr))
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
@dataclass(frozen=True)
|
|
78
|
+
class Option:
|
|
79
|
+
key: str
|
|
80
|
+
label: str
|
|
81
|
+
meaning: str
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def options(choices: list[Option]) -> None:
|
|
85
|
+
"""The answers a question takes, aligned, explained once for every question that follows."""
|
|
86
|
+
width = max(len(o.label) for o in choices)
|
|
87
|
+
_say()
|
|
88
|
+
for o in choices:
|
|
89
|
+
_say(f" {style(o.key, BOLD, stream=sys.stderr)} {o.label.ljust(width)} {o.meaning}")
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def choose(subject: str, about: str, choices: list[Option], *, step: str = "") -> str | None:
|
|
93
|
+
"""One answer from the choices for a subject (a tool, say); None when the person presses Enter, which leaves
|
|
94
|
+
it to decide later. A reply that isn't one of the choices asks again."""
|
|
95
|
+
_say()
|
|
96
|
+
pad = " " * (len(step) + 1) if step else ""
|
|
97
|
+
if subject:
|
|
98
|
+
lead = f" {style(step, DIM, stream=sys.stderr)} " if step else " "
|
|
99
|
+
_say(lead + heading(subject, sys.stderr))
|
|
100
|
+
# The tool's own description, at most two lines: enough to tell the tools apart.
|
|
101
|
+
for line in wrap(about, " " + pad)[:2]:
|
|
102
|
+
_say(style(line, DIM, stream=sys.stderr))
|
|
103
|
+
keys = "/".join(o.key for o in choices)
|
|
104
|
+
while True:
|
|
105
|
+
reply = _reply(f"{pad}[{keys}, Enter to skip]")
|
|
106
|
+
if not reply:
|
|
107
|
+
return None
|
|
108
|
+
for o in choices:
|
|
109
|
+
if reply in {o.key, o.label.lower()}:
|
|
110
|
+
return o.key
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def text(question: str, default: str, *details: str, shown: str = "", required: bool = False) -> str:
|
|
114
|
+
"""A written answer; Enter keeps the default, shown in brackets (or as `shown`, for a long default). A required
|
|
115
|
+
question with no default asks again until it has an answer, and doesn't offer Enter."""
|
|
116
|
+
_say()
|
|
117
|
+
_say(heading(question, sys.stderr))
|
|
118
|
+
for detail in details:
|
|
119
|
+
for line in wrap(detail):
|
|
120
|
+
_say(style(line, DIM, stream=sys.stderr))
|
|
121
|
+
hint = shown or default
|
|
122
|
+
skip = "[type your answer]" if required else "[Enter to skip]"
|
|
123
|
+
answers = f"[Enter: {hint}]" if hint else skip
|
|
124
|
+
_say()
|
|
125
|
+
while True:
|
|
126
|
+
reply = _raw(answers)
|
|
127
|
+
if reply or default or not required:
|
|
128
|
+
return reply or default
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def _raw(answers: str) -> str:
|
|
132
|
+
"""A reply as typed, case kept: names, descriptions, paths and addresses."""
|
|
133
|
+
ASKED["any"] = True
|
|
134
|
+
sys.stderr.write(f" {style(answers, DIM, stream=sys.stderr)} {style(MARK, CYAN, BOLD, stream=sys.stderr)} ")
|
|
135
|
+
sys.stderr.flush()
|
|
136
|
+
try:
|
|
137
|
+
return input().strip()
|
|
138
|
+
except (EOFError, KeyboardInterrupt) as exc:
|
|
139
|
+
print(file=sys.stderr)
|
|
140
|
+
raise CliError("EKL-225") from exc
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def pick(question: str, choices: list[Option], default: str, *details: str) -> str:
|
|
144
|
+
"""One of the choices, explained under the question; Enter takes the default."""
|
|
145
|
+
_say()
|
|
146
|
+
_say(heading(question, sys.stderr))
|
|
147
|
+
for detail in details:
|
|
148
|
+
for line in wrap(detail):
|
|
149
|
+
_say(style(line, DIM, stream=sys.stderr))
|
|
150
|
+
options(choices)
|
|
151
|
+
keys = "/".join(o.key.upper() if o.key == default else o.key for o in choices)
|
|
152
|
+
# A capital marks the default; a number has none, so it is named.
|
|
153
|
+
if default and default.upper() == default.lower():
|
|
154
|
+
keys += f", Enter: {default}"
|
|
155
|
+
while True:
|
|
156
|
+
reply = _reply(f"[{keys}]")
|
|
157
|
+
if not reply:
|
|
158
|
+
return default
|
|
159
|
+
for o in choices:
|
|
160
|
+
if reply in {o.key, o.label.lower()}:
|
|
161
|
+
return o.key
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
def confirm(question: str, default: bool, *details: str) -> bool:
|
|
165
|
+
"""A yes-or-no question, with what each answer does; Enter takes the default."""
|
|
166
|
+
_say()
|
|
167
|
+
_say(heading(question, sys.stderr))
|
|
168
|
+
for detail in details:
|
|
169
|
+
for line in wrap(detail):
|
|
170
|
+
_say(style(line, DIM, stream=sys.stderr))
|
|
171
|
+
while True:
|
|
172
|
+
reply = _reply("[Y/n]" if default else "[y/N]")
|
|
173
|
+
if not reply:
|
|
174
|
+
return default
|
|
175
|
+
if reply in {"y", "yes", "n", "no"}:
|
|
176
|
+
return reply.startswith("y")
|
ekl_cli/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_type": "root",
|
|
3
|
+
"expires": "2027-11-12T21:46:21Z",
|
|
4
|
+
"root_keys": {
|
|
5
|
+
"fba1600c283e7ff50755012dbd151d9c29a8cc5050e879ebfb047fe94017c89d": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE+qEpHX3tfc2hri5294EXoce+lqe6xi2wz1C2f2PL52psKGJl800zKURWIyabqoeiMwsluvqNilI1CO9rVsgl9w=="
|
|
6
|
+
},
|
|
7
|
+
"threshold": 1,
|
|
8
|
+
"version": 1
|
|
9
|
+
}
|