kuzybackup 0.1.5__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.
kuzybackup/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """kuzybackup: scheduled, verifiable backups of AI agent sessions via Needlecast."""
2
+
3
+ __version__ = "0.1.5"
kuzybackup/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
kuzybackup/agents.py ADDED
@@ -0,0 +1,435 @@
1
+ """Discover the agent sessions to back up.
2
+
3
+ Two sources are supported:
4
+
5
+ * ``static``: agents listed in the configuration file. This is the portable
6
+ default for anyone not running kuzywrap.
7
+ * ``kuzywrap``: targets configured under ``~/.config/kuzywrap/<runtime>/targets``.
8
+ The session bindings are read the same way kuzywrap stores them.
9
+
10
+ With ``system_targets``, the kuzywrap source also reads the targets of separate
11
+ system users under ``/etc/kuzywrap``, their bindings under ``/var/lib/kuzywrap``
12
+ and the sessions in each user's own home. That needs root, so it is opt-in.
13
+
14
+ Several kuzywrap targets can share one session (aliases). They are captured
15
+ once, and every alias is listed in the report.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import json
21
+ import os
22
+ import pwd
23
+ from dataclasses import dataclass, field
24
+ from pathlib import Path
25
+ from typing import Any
26
+
27
+ from .config import Config, ConfigError
28
+
29
+ KUZYWRAP_RUNTIMES = ("claude", "codex", "codewhale", "antigravity", "opencode")
30
+ # OpenCode keeps every session of a user in one SQLite database. Several targets
31
+ # can share it, each pinned to its own session (and that session's children).
32
+ OPENCODE_DATA_DIR = Path(".local/share/opencode")
33
+ OPENCODE_DB = "opencode.db"
34
+ # kuzywrap-opencode's app-server persists the session it is pinned to here and
35
+ # loads it first at every start; the target file's session_id is only the pin
36
+ # it starts from when nothing was persisted yet. `chat --new`, `pin` and `fork`
37
+ # move the persisted pin and leave the target file as it was.
38
+ OPENCODE_SYNC_DIR = Path("kuzywrap/opencode/sync-state")
39
+ SYSTEM_CONFIG_ROOT = Path("/etc/kuzywrap")
40
+ SYSTEM_STATE_ROOT = Path("/var/lib/kuzywrap")
41
+ SYSTEM_USER_KIND = "system-user"
42
+
43
+
44
+ class DiscoveryError(ConfigError):
45
+ """System targets cannot be read, so the list of agents would be partial."""
46
+
47
+
48
+ @dataclass
49
+ class AgentSession:
50
+ """One session to capture, possibly shared by several target names."""
51
+
52
+ name: str
53
+ runtime: str
54
+ root: Path | None
55
+ session_id: str | None
56
+ aliases: list[str] = field(default_factory=list)
57
+ skip_reason: str | None = None
58
+ excluded_reason: str | None = None
59
+ system_user: str | None = None
60
+ # OpenCode only, per target name: where the pin is persisted and the target
61
+ # file's session, so the binding can be read again once the agent is stopped.
62
+ pin_sources: dict[str, tuple[Path, str | None]] = field(default_factory=dict)
63
+
64
+ @property
65
+ def label(self) -> str:
66
+ return f"{self.runtime}/{self.name}"
67
+
68
+
69
+ class BindingError(ValueError):
70
+ """The session a target is bound to cannot be read reliably."""
71
+
72
+
73
+ def _read_json(path: Path) -> dict[str, Any] | None:
74
+ try:
75
+ data = json.loads(path.read_text(encoding="utf-8"))
76
+ except (OSError, UnicodeError, json.JSONDecodeError):
77
+ # One unreadable file marks its target, never the whole discovery.
78
+ return None
79
+ return data if isinstance(data, dict) else None
80
+
81
+
82
+ def claude_transcript_exists(root: Path, session_id: str) -> bool:
83
+ projects = root / "projects"
84
+ return projects.is_dir() and any(projects.glob(f"*/{session_id}.jsonl"))
85
+
86
+
87
+ def _home_of(user: str) -> Path | None:
88
+ try:
89
+ return Path(pwd.getpwnam(user).pw_dir)
90
+ except KeyError:
91
+ return None
92
+
93
+
94
+ def _system_user(config: dict[str, Any]) -> str | None:
95
+ if config.get("kind") != SYSTEM_USER_KIND:
96
+ return None
97
+ user = config.get("system_user")
98
+ return user if isinstance(user, str) and user else None
99
+
100
+
101
+ def _target_home(config: dict[str, Any]) -> Path | None:
102
+ """The home of a target; None when its system user does not exist."""
103
+ declared = config.get("home")
104
+ if declared:
105
+ return Path(str(declared)).expanduser()
106
+ user = _system_user(config)
107
+ return _home_of(user) if user else Path.home()
108
+
109
+
110
+ def user_state_home() -> Path:
111
+ """Where kuzywrap keeps a current-user target's state (as kuzywrap reads it)."""
112
+ xdg = os.environ.get("XDG_STATE_HOME")
113
+ return Path(xdg) if xdg else Path.home() / ".local/state"
114
+
115
+
116
+ def _opencode_pin_path(
117
+ name: str,
118
+ system_user: str | None,
119
+ state_root: Path | None = None,
120
+ state_home: Path | None = None,
121
+ ) -> Path:
122
+ if system_user:
123
+ base = (state_root or SYSTEM_STATE_ROOT) / "opencode/sync-state"
124
+ else:
125
+ base = (state_home or user_state_home()) / OPENCODE_SYNC_DIR
126
+ return base / f"session-{name}.json"
127
+
128
+
129
+ def opencode_pin(path: Path, configured: str | None) -> str | None:
130
+ """The session kuzywrap-opencode is pinned to, or will pin at its next start.
131
+
132
+ A persisted pin wins, as in the app-server. With none, the app-server pins
133
+ the target file's session when it starts, so that one is the binding. A pin
134
+ file that exists but cannot be read is an error, never a reason to fall back
135
+ to the target file: that session may be an old one.
136
+ """
137
+ try:
138
+ raw = path.read_text(encoding="utf-8")
139
+ except FileNotFoundError:
140
+ return configured
141
+ except OSError as exc:
142
+ raise BindingError(f"cannot read the persisted OpenCode pin: {exc}") from exc
143
+ except UnicodeError as exc:
144
+ raise BindingError("the persisted OpenCode pin is not UTF-8") from exc
145
+ try:
146
+ data = json.loads(raw)
147
+ except json.JSONDecodeError as exc:
148
+ raise BindingError("the persisted OpenCode pin is not JSON") from exc
149
+ session = data.get("session_id") if isinstance(data, dict) else None
150
+ if not isinstance(session, str) or not session:
151
+ raise BindingError("the persisted OpenCode pin names no session")
152
+ return session
153
+
154
+
155
+ def current_binding(agent: AgentSession) -> dict[str, str | None]:
156
+ """Read again, for every name of an OpenCode agent, the session it is bound to.
157
+
158
+ Called once the agent is stopped: its app-server can no longer move the pin,
159
+ so this is the binding the capture must match.
160
+ """
161
+ return {
162
+ name: opencode_pin(path, configured)
163
+ for name, (path, configured) in sorted(agent.pin_sources.items())
164
+ }
165
+
166
+
167
+ def _codex_binding_path(
168
+ name: str, system_user: str | None, state_root: Path | None = None
169
+ ) -> Path:
170
+ if system_user:
171
+ base = state_root or SYSTEM_STATE_ROOT
172
+ return base / "codex/sessions" / f"{system_user}.json"
173
+ return Path.home() / ".local/share/kuzywrap/codex/sessions" / f"{name}.json"
174
+
175
+
176
+ def session_source_exists(
177
+ runtime: str,
178
+ root: Path,
179
+ session_id: str,
180
+ name: str,
181
+ *,
182
+ system_user: str | None = None,
183
+ state_root: Path | None = None,
184
+ ) -> bool:
185
+ """Whether the canonical session data is present on disk."""
186
+ if runtime == "claude":
187
+ return claude_transcript_exists(root, session_id)
188
+ if runtime == "codex":
189
+ binding = _codex_binding_path(name, system_user, state_root)
190
+ return binding.is_file() and (root / "state_5.sqlite").is_file()
191
+ if runtime == "codewhale":
192
+ return (root / "sessions" / f"{session_id}.json").is_file()
193
+ if runtime == "opencode":
194
+ # Whether the session row exists is Needlecast's to check: kuzybackup
195
+ # does not open the database of running agents.
196
+ return (root / OPENCODE_DB).is_file()
197
+ return root.exists()
198
+
199
+
200
+ def _kuzywrap_binding(
201
+ runtime: str,
202
+ name: str,
203
+ config: dict[str, Any],
204
+ state_root: Path | None = None,
205
+ state_home: Path | None = None,
206
+ ) -> tuple[Path | None, str | None]:
207
+ home = _target_home(config)
208
+ if runtime == "claude":
209
+ session = config.get("canonical_session_id")
210
+ root = home / ".claude" if home else None
211
+ return root, session if isinstance(session, str) else None
212
+ if runtime == "codex":
213
+ binding = _read_json(
214
+ _codex_binding_path(name, _system_user(config), state_root)
215
+ )
216
+ thread = binding.get("thread_id") if binding else None
217
+ root = home / ".codex" if home else None
218
+ return root, thread if isinstance(thread, str) else None
219
+ if runtime == "codewhale":
220
+ session = config.get("session_id")
221
+ app_home = config.get("app_home")
222
+ root = Path(str(app_home)).expanduser() / ".codewhale" if app_home else None
223
+ return root, session if isinstance(session, str) else None
224
+ if runtime == "antigravity":
225
+ session = config.get("session_id")
226
+ root = home / ".gemini/antigravity-cli" if home else None
227
+ return root, session if isinstance(session, str) else None
228
+ if runtime == "opencode":
229
+ path, configured = _opencode_pin_source(name, config, state_root, state_home)
230
+ root = home / OPENCODE_DATA_DIR if home else None
231
+ return root, opencode_pin(path, configured)
232
+ return None, None
233
+
234
+
235
+ def _opencode_pin_source(
236
+ name: str,
237
+ config: dict[str, Any],
238
+ state_root: Path | None,
239
+ state_home: Path | None,
240
+ ) -> tuple[Path, str | None]:
241
+ path = _opencode_pin_path(name, _system_user(config), state_root, state_home)
242
+ configured = config.get("session_id")
243
+ return path, configured if isinstance(configured, str) and configured else None
244
+
245
+
246
+ def _agent_from_target(
247
+ runtime: str,
248
+ name: str,
249
+ data: dict[str, Any],
250
+ state_root: Path | None = None,
251
+ state_home: Path | None = None,
252
+ ) -> AgentSession:
253
+ system_user = _system_user(data)
254
+ try:
255
+ root, session_id = _kuzywrap_binding(
256
+ runtime, name, data, state_root, state_home
257
+ )
258
+ except BindingError as exc:
259
+ return AgentSession(
260
+ name=name,
261
+ runtime=runtime,
262
+ root=None,
263
+ session_id=None,
264
+ system_user=system_user,
265
+ skip_reason=str(exc),
266
+ )
267
+ agent = AgentSession(
268
+ name=name,
269
+ runtime=runtime,
270
+ root=root,
271
+ session_id=session_id,
272
+ system_user=system_user,
273
+ )
274
+ if runtime == "opencode":
275
+ agent.pin_sources[name] = _opencode_pin_source(
276
+ name, data, state_root, state_home
277
+ )
278
+ if root is None or session_id is None:
279
+ agent.skip_reason = "target has no canonical local session binding"
280
+ elif not session_source_exists(
281
+ runtime, root, session_id, name, system_user=system_user, state_root=state_root
282
+ ):
283
+ agent.skip_reason = "canonical session source is absent locally"
284
+ return agent
285
+
286
+
287
+ def _unreadable_target(path: Path, runtime: str) -> AgentSession:
288
+ return AgentSession(
289
+ name=path.stem,
290
+ runtime=runtime,
291
+ root=None,
292
+ session_id=None,
293
+ skip_reason="target configuration is unreadable",
294
+ )
295
+
296
+
297
+ def discover_kuzywrap(
298
+ config_root: Path | None = None, state_home: Path | None = None
299
+ ) -> list[AgentSession]:
300
+ base = (config_root or Path.home() / ".config/kuzywrap").expanduser()
301
+ found: list[AgentSession] = []
302
+ for runtime in KUZYWRAP_RUNTIMES:
303
+ target_dir = base / runtime / "targets"
304
+ if not target_dir.is_dir():
305
+ continue
306
+ for path in sorted(target_dir.glob("*.json")):
307
+ data = _read_json(path)
308
+ if data is None:
309
+ found.append(_unreadable_target(path, runtime))
310
+ continue
311
+ found.append(
312
+ _agent_from_target(
313
+ runtime,
314
+ str(data.get("target") or path.stem),
315
+ data,
316
+ state_home=state_home,
317
+ )
318
+ )
319
+ return found
320
+
321
+
322
+ def _require_readable(directory: Path) -> None:
323
+ """A directory we cannot list would silently shorten the list of agents."""
324
+ if directory.exists() and not os.access(directory, os.R_OK | os.X_OK):
325
+ raise DiscoveryError(
326
+ f"cannot read {directory}: [discovery].system_targets needs root"
327
+ )
328
+
329
+
330
+ def _implicit_codex_targets(state_root: Path, known: set[str]) -> list[dict[str, Any]]:
331
+ """Codex serves a system user as a target even with no file under /etc."""
332
+ sessions = state_root / "codex/sessions"
333
+ _require_readable(sessions)
334
+ if not sessions.is_dir():
335
+ return []
336
+ return [
337
+ {"target": path.stem, "kind": SYSTEM_USER_KIND, "system_user": path.stem}
338
+ for path in sorted(sessions.glob("*.json"))
339
+ if path.stem not in known and _home_of(path.stem) is not None
340
+ ]
341
+
342
+
343
+ def discover_system_targets(
344
+ config_root: Path = SYSTEM_CONFIG_ROOT, state_root: Path = SYSTEM_STATE_ROOT
345
+ ) -> list[AgentSession]:
346
+ """Targets of separate system users, for a host where agents do not share one."""
347
+ found: list[AgentSession] = []
348
+ for runtime in KUZYWRAP_RUNTIMES:
349
+ target_dir = config_root / runtime / "targets"
350
+ _require_readable(target_dir)
351
+ records: list[dict[str, Any]] = []
352
+ if target_dir.is_dir():
353
+ for path in sorted(target_dir.glob("*.json")):
354
+ data = _read_json(path)
355
+ if data is None:
356
+ found.append(_unreadable_target(path, runtime))
357
+ else:
358
+ records.append({"target": path.stem, **data})
359
+ if runtime == "codex":
360
+ known = {str(r.get("system_user") or r["target"]) for r in records}
361
+ records += _implicit_codex_targets(state_root, known)
362
+ for data in records:
363
+ found.append(
364
+ _agent_from_target(runtime, str(data["target"]), data, state_root)
365
+ )
366
+ return found
367
+
368
+
369
+ def discover_static(config: Config) -> list[AgentSession]:
370
+ agents: list[AgentSession] = []
371
+ for item in config.agents:
372
+ root = item.root.expanduser()
373
+ agent = AgentSession(
374
+ name=item.name,
375
+ runtime=item.runtime,
376
+ root=root,
377
+ session_id=item.session_id,
378
+ system_user=item.system_user,
379
+ )
380
+ if not session_source_exists(
381
+ item.runtime, root, item.session_id, item.name, system_user=item.system_user
382
+ ):
383
+ agent.skip_reason = "session source is absent locally"
384
+ agents.append(agent)
385
+ return agents
386
+
387
+
388
+ def group_aliases(agents: list[AgentSession]) -> list[AgentSession]:
389
+ """Merge targets that point at the same session into one capture."""
390
+ groups: dict[tuple[str, str, str], list[AgentSession]] = {}
391
+ singles: list[AgentSession] = []
392
+ for agent in agents:
393
+ if agent.root is None or agent.session_id is None or agent.skip_reason:
394
+ singles.append(agent)
395
+ continue
396
+ key = (agent.runtime, str(agent.root.resolve()), agent.session_id)
397
+ groups.setdefault(key, []).append(agent)
398
+ merged: list[AgentSession] = []
399
+ for members in groups.values():
400
+ # A shared session is excluded only when every alias is excluded.
401
+ included = sorted(m.name for m in members if not m.excluded_reason)
402
+ names = included + sorted(m.name for m in members if m.excluded_reason)
403
+ primary = members[0]
404
+ pins: dict[str, tuple[Path, str | None]] = {}
405
+ for member in members:
406
+ pins.update(member.pin_sources)
407
+ merged.append(
408
+ AgentSession(
409
+ name=names[0],
410
+ runtime=primary.runtime,
411
+ root=primary.root,
412
+ session_id=primary.session_id,
413
+ aliases=names[1:],
414
+ excluded_reason=None if included else primary.excluded_reason,
415
+ system_user=primary.system_user,
416
+ pin_sources=pins,
417
+ )
418
+ )
419
+ return sorted(merged + singles, key=lambda a: (a.runtime, a.name))
420
+
421
+
422
+ def discover(config: Config) -> list[AgentSession]:
423
+ if config.discovery == "kuzywrap":
424
+ agents = discover_kuzywrap()
425
+ if config.system_targets:
426
+ agents += discover_system_targets()
427
+ else:
428
+ agents = discover_static(config)
429
+ for agent in agents:
430
+ names = {agent.name, f"{agent.runtime}/{agent.name}"}
431
+ if config.include and not names & set(config.include):
432
+ agent.excluded_reason = "not in [discovery].include"
433
+ elif names & set(config.exclude):
434
+ agent.excluded_reason = "listed in [discovery].exclude"
435
+ return group_aliases(agents)
kuzybackup/backend.py ADDED
@@ -0,0 +1,217 @@
1
+ """Client for backend scripts.
2
+
3
+ A backend is an executable in a backends directory. kuzybackup calls it as
4
+ ``<backend> <command> [args...]`` and reads one JSON object from stdout. The
5
+ protocol is documented in ``docs/BACKENDS.md``.
6
+
7
+ Credentials never pass through kuzybackup: the configuration only names a
8
+ file, and the backend reads it through ``KUZYBACKUP_CREDENTIALS_FILE``.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import os
15
+ import pwd
16
+ import subprocess
17
+ from dataclasses import dataclass, field
18
+ from pathlib import Path
19
+ from typing import Any
20
+
21
+ PROTOCOL_VERSION = 1
22
+ EXIT_NOT_IMPLEMENTED = 2
23
+ COMMANDS = ("put", "list", "get", "delete")
24
+
25
+
26
+ class BackendError(RuntimeError):
27
+ """The backend failed or answered outside the protocol."""
28
+
29
+
30
+ class NotImplementedByBackend(BackendError):
31
+ """The backend explicitly declined a command (exit status 2)."""
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class Capabilities:
36
+ name: str
37
+ tested: bool
38
+ list_is_remote: bool
39
+ supports: dict[str, bool]
40
+ note: str | None = None
41
+
42
+ def can(self, command: str) -> bool:
43
+ return bool(self.supports.get(command, False))
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class RemoteEntry:
48
+ name: str
49
+ type: str
50
+ size: int | None = None
51
+ sha256: str | None = None
52
+
53
+
54
+ @dataclass
55
+ class Backend:
56
+ """A backend script plus the environment it runs with."""
57
+
58
+ executable: Path
59
+ credentials_file: Path | None = None
60
+ options: dict[str, str] = field(default_factory=dict)
61
+ timeout_seconds: float = 3600.0
62
+ run_as: str | None = None
63
+
64
+ @classmethod
65
+ def locate(
66
+ cls,
67
+ name: str,
68
+ search_dirs: list[Path],
69
+ *,
70
+ credentials_file: Path | None = None,
71
+ options: dict[str, str] | None = None,
72
+ timeout_seconds: float = 3600.0,
73
+ run_as: str | None = None,
74
+ ) -> Backend:
75
+ if "/" in name or name.startswith("."):
76
+ raise BackendError(f"invalid backend name: {name!r}")
77
+ for directory in search_dirs:
78
+ candidate = directory.expanduser() / name
79
+ if candidate.is_file() and os.access(candidate, os.X_OK):
80
+ return cls(
81
+ executable=candidate,
82
+ credentials_file=credentials_file,
83
+ options=dict(options or {}),
84
+ timeout_seconds=timeout_seconds,
85
+ run_as=run_as,
86
+ )
87
+ searched = ", ".join(str(d) for d in search_dirs)
88
+ raise BackendError(f"backend {name!r} not found in: {searched}")
89
+
90
+ def _environment(self) -> dict[str, str]:
91
+ env = dict(os.environ)
92
+ # Never leak a credentials path from the caller's environment into a
93
+ # backend that was configured without one.
94
+ env.pop("KUZYBACKUP_CREDENTIALS_FILE", None)
95
+ if self.credentials_file is not None:
96
+ env["KUZYBACKUP_CREDENTIALS_FILE"] = str(self.credentials_file.expanduser())
97
+ for key, value in self.options.items():
98
+ env[f"KUZYBACKUP_OPT_{key.upper()}"] = value
99
+ env["KUZYBACKUP_PROTOCOL"] = str(PROTOCOL_VERSION)
100
+ return env
101
+
102
+ def _identity(self) -> dict[str, Any]:
103
+ """How to run the script as run_as: root switches, anyone else must be it."""
104
+ if self.run_as is None:
105
+ return {"env": self._environment()}
106
+ try:
107
+ account = pwd.getpwnam(self.run_as)
108
+ except KeyError as exc:
109
+ raise BackendError(f"backend user {self.run_as!r} does not exist") from exc
110
+ if os.geteuid() != 0:
111
+ if os.geteuid() != account.pw_uid:
112
+ raise BackendError(f"the backend must run as {self.run_as}")
113
+ return {"env": self._environment()}
114
+ # Nothing from root's own environment reaches the script.
115
+ inherited = self._environment()
116
+ env = {k: v for k, v in inherited.items() if k.startswith("KUZYBACKUP_")}
117
+ env.update(
118
+ PATH=inherited.get("PATH", "/usr/bin:/bin"),
119
+ LANG=inherited.get("LANG", "C.UTF-8"),
120
+ HOME=account.pw_dir,
121
+ USER=self.run_as,
122
+ LOGNAME=self.run_as,
123
+ )
124
+ return {
125
+ "env": env,
126
+ "user": account.pw_uid,
127
+ "group": account.pw_gid,
128
+ "extra_groups": [],
129
+ "cwd": account.pw_dir,
130
+ }
131
+
132
+ def _call(self, *args: str) -> dict[str, Any]:
133
+ identity = self._identity()
134
+ try:
135
+ result = subprocess.run(
136
+ [str(self.executable), *args],
137
+ capture_output=True,
138
+ text=True,
139
+ timeout=self.timeout_seconds,
140
+ check=False,
141
+ **identity,
142
+ )
143
+ except subprocess.TimeoutExpired as exc:
144
+ raise BackendError(
145
+ f"backend {self.executable.name} {args[0]} timed out"
146
+ ) from exc
147
+ if result.returncode == EXIT_NOT_IMPLEMENTED:
148
+ raise NotImplementedByBackend(
149
+ f"backend {self.executable.name} does not implement {args[0]}"
150
+ )
151
+ try:
152
+ data = json.loads(result.stdout) if result.stdout.strip() else {}
153
+ except json.JSONDecodeError as exc:
154
+ raise BackendError(
155
+ f"backend {self.executable.name} {args[0]} returned invalid JSON"
156
+ ) from exc
157
+ if not isinstance(data, dict):
158
+ raise BackendError(
159
+ f"backend {self.executable.name} {args[0]} did not return an object"
160
+ )
161
+ if result.returncode != 0 or data.get("status") != "ok":
162
+ detail = data.get("error")
163
+ if not isinstance(detail, str) or not detail:
164
+ lines = result.stderr.strip().splitlines()
165
+ detail = lines[-1] if lines else f"exit status {result.returncode}"
166
+ raise BackendError(
167
+ f"backend {self.executable.name} {args[0]} failed: {detail}"
168
+ )
169
+ return data
170
+
171
+ def capabilities(self) -> Capabilities:
172
+ data = self._call("capabilities")
173
+ if data.get("protocol") != PROTOCOL_VERSION:
174
+ raise BackendError(
175
+ f"backend {self.executable.name} speaks protocol "
176
+ f"{data.get('protocol')!r}, expected {PROTOCOL_VERSION}"
177
+ )
178
+ supports = data.get("supports")
179
+ if not isinstance(supports, dict):
180
+ raise BackendError("capabilities.supports must be an object")
181
+ return Capabilities(
182
+ name=str(data.get("name") or self.executable.name),
183
+ tested=data.get("tested") is True,
184
+ list_is_remote=data.get("list_is_remote") is True,
185
+ supports={k: supports.get(k) is True for k in COMMANDS},
186
+ note=str(data["note"]) if data.get("note") else None,
187
+ )
188
+
189
+ def put(self, local_path: Path, remote_path: str) -> None:
190
+ self._call("put", str(local_path), remote_path)
191
+
192
+ def get(self, remote_path: str, local_path: Path) -> None:
193
+ self._call("get", remote_path, str(local_path))
194
+
195
+ def delete(self, remote_path: str) -> None:
196
+ self._call("delete", remote_path)
197
+
198
+ def list(self, remote_dir: str) -> list[RemoteEntry]:
199
+ data = self._call("list", remote_dir)
200
+ entries = data.get("entries")
201
+ if not isinstance(entries, list):
202
+ raise BackendError("list.entries must be an array")
203
+ parsed: list[RemoteEntry] = []
204
+ for item in entries:
205
+ if not isinstance(item, dict) or not isinstance(item.get("name"), str):
206
+ raise BackendError("list entry without a name")
207
+ size = item.get("size")
208
+ sha = item.get("sha256")
209
+ parsed.append(
210
+ RemoteEntry(
211
+ name=item["name"],
212
+ type=str(item.get("type") or "file"),
213
+ size=size if isinstance(size, int) else None,
214
+ sha256=sha if isinstance(sha, str) else None,
215
+ )
216
+ )
217
+ return parsed