fairshare-cli 0.1.1__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.
- fairshare/__init__.py +2 -0
- fairshare/browser.py +91 -0
- fairshare/cli.py +3266 -0
- fairshare/hub.py +272 -0
- fairshare/model.py +411 -0
- fairshare/plans/__init__.py +0 -0
- fairshare/plans/claude-max.toml +15 -0
- fairshare/plans/claude-pro.toml +13 -0
- fairshare/plans/claude-ultra.toml +17 -0
- fairshare/policy.py +73 -0
- fairshare/providers/__init__.py +12 -0
- fairshare/providers/base.py +193 -0
- fairshare/providers/claude.py +1176 -0
- fairshare/providers/claude_skill/SKILL.md +55 -0
- fairshare/session.py +113 -0
- fairshare/store.py +648 -0
- fairshare_cli-0.1.1.dist-info/METADATA +152 -0
- fairshare_cli-0.1.1.dist-info/RECORD +21 -0
- fairshare_cli-0.1.1.dist-info/WHEEL +4 -0
- fairshare_cli-0.1.1.dist-info/entry_points.txt +2 -0
- fairshare_cli-0.1.1.dist-info/licenses/LICENSE +21 -0
fairshare/hub.py
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
"""The hub: one folder that makes several accounts one assistant. Provider-neutral; a provider
|
|
2
|
+
says only which items are shared (`Provider.shared`, a name ending in "/" is a folder).
|
|
3
|
+
|
|
4
|
+
<hub>/shared/ the shared items
|
|
5
|
+
<hub>/accounts/<id>/ one config folder per account: its own login and state, and a RELATIVE
|
|
6
|
+
link for every shared item (projects -> ../../shared/projects), so the
|
|
7
|
+
whole hub can be moved
|
|
8
|
+
<hub>/backups/ whatever fairshare moves aside. fairshare never deletes.
|
|
9
|
+
|
|
10
|
+
Nothing here writes outside the hub except `seed`, which only reads the user's folder."""
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import difflib
|
|
14
|
+
import filecmp
|
|
15
|
+
import os
|
|
16
|
+
import shutil
|
|
17
|
+
import tempfile
|
|
18
|
+
import time
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
|
|
21
|
+
from . import store
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def shared_dir(hub: Path) -> Path:
|
|
25
|
+
return hub / "shared"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def accounts_dir(hub: Path) -> Path:
|
|
29
|
+
return hub / "accounts"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def account_dir(hub: Path, account_id: str) -> Path:
|
|
33
|
+
return accounts_dir(hub) / account_id
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def present(hub: Path, account_id: str | None = None) -> bool:
|
|
37
|
+
"""Whether a hub is at `hub` (its shared/ and accounts/ folders, and the account's folder
|
|
38
|
+
when one is named). A launch never builds a hub: after a move it would silently start an
|
|
39
|
+
empty one at the old path."""
|
|
40
|
+
return shared_dir(hub).is_dir() and accounts_dir(hub).is_dir() and (
|
|
41
|
+
account_id is None or account_dir(hub, account_id).is_dir())
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def lock(hub: Path):
|
|
45
|
+
"""Held while the hub's links or shared items change: two launches must not repair at once."""
|
|
46
|
+
return store.locked(hub / ".lock")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def backup_dir(hub: Path, label: str) -> Path:
|
|
50
|
+
"""A new folder name under backups/ for what one run moves aside (created when used)."""
|
|
51
|
+
return store.free_name(hub / "backups" / f"{time.strftime('%Y%m%d-%H%M%S')}-{label}")
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _items(prov) -> list[tuple[str, bool]]:
|
|
55
|
+
return [(i.rstrip("/"), i.endswith("/")) for i in prov.shared]
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _same(a: Path, b: Path) -> bool:
|
|
59
|
+
if a.is_symlink() or b.is_symlink():
|
|
60
|
+
return a.is_symlink() and b.is_symlink() and os.readlink(a) == os.readlink(b)
|
|
61
|
+
return a.is_file() and b.is_file() and filecmp.cmp(a, b, shallow=False)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _suffixed(p: Path, label: str, n: int) -> Path:
|
|
65
|
+
tag = f"from-{label}" + (f"-{n}" if n > 1 else "")
|
|
66
|
+
return p.with_name(f"{p.stem}.{tag}{p.suffix}")
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _place(src: Path, dest: Path, label: str, move: bool) -> bool:
|
|
70
|
+
"""Put the file (or link) `src` at `dest` in shared/. A clash keeps both: the incoming one
|
|
71
|
+
takes a name naming `label`. An identical file is not placed twice. True when placed."""
|
|
72
|
+
target, n = dest, 1
|
|
73
|
+
while os.path.lexists(target):
|
|
74
|
+
if _same(src, target):
|
|
75
|
+
return False
|
|
76
|
+
target, n = _suffixed(dest, label, n), n + 1
|
|
77
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
78
|
+
if move:
|
|
79
|
+
os.rename(src, target)
|
|
80
|
+
elif src.is_symlink():
|
|
81
|
+
os.symlink(os.readlink(src), target)
|
|
82
|
+
else: # a copy keeps the times: sessions sort by them
|
|
83
|
+
fd, tmp = tempfile.mkstemp(dir=target.parent)
|
|
84
|
+
os.close(fd)
|
|
85
|
+
shutil.copy2(src, tmp)
|
|
86
|
+
os.replace(tmp, target)
|
|
87
|
+
return True
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _merge_tree(src: Path, dest: Path, label: str, move: bool) -> int:
|
|
91
|
+
"""Every file under `src` into `dest` by `_place`; returns how many were placed."""
|
|
92
|
+
placed = 0
|
|
93
|
+
for root, dirs, files in os.walk(src):
|
|
94
|
+
here = Path(root)
|
|
95
|
+
links = [d for d in dirs if (here / d).is_symlink()] # a linked folder is an entry
|
|
96
|
+
dirs[:] = [d for d in dirs if d not in links]
|
|
97
|
+
for name in sorted(files + links):
|
|
98
|
+
placed += _place(here / name, dest / here.relative_to(src) / name, label, move)
|
|
99
|
+
return placed
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def _append_missing(src: Path, dest: Path) -> int:
|
|
103
|
+
"""Append to `dest` the lines of `src` it lacks, in their order; returns how many."""
|
|
104
|
+
have = dest.read_bytes() if dest.exists() else b""
|
|
105
|
+
seen, add = set(have.splitlines()), []
|
|
106
|
+
for line in src.read_bytes().splitlines():
|
|
107
|
+
if line and line not in seen:
|
|
108
|
+
seen.add(line)
|
|
109
|
+
add.append(line)
|
|
110
|
+
if add:
|
|
111
|
+
with open(dest, "ab") as f:
|
|
112
|
+
f.write((b"\n" if have and not have.endswith(b"\n") else b"") + b"\n".join(add) + b"\n")
|
|
113
|
+
return len(add)
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _write_bytes(dest: Path, data: bytes, mode_from: Path | None = None) -> None:
|
|
117
|
+
"""Write a new file atomically (through a symlink, never over it)."""
|
|
118
|
+
if dest.is_symlink():
|
|
119
|
+
dest = dest.resolve()
|
|
120
|
+
dest.parent.mkdir(parents=True, exist_ok=True)
|
|
121
|
+
fd, tmp = tempfile.mkstemp(dir=dest.parent)
|
|
122
|
+
with os.fdopen(fd, "wb") as f:
|
|
123
|
+
f.write(data)
|
|
124
|
+
if mode_from is not None:
|
|
125
|
+
os.chmod(tmp, mode_from.stat().st_mode & 0o777)
|
|
126
|
+
os.replace(tmp, dest)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def diff(prov, item: str, ours: bytes, theirs: bytes, theirs_name: str) -> str:
|
|
130
|
+
"""The differences the user is shown, values that may be secrets hidden by the provider."""
|
|
131
|
+
try:
|
|
132
|
+
a = prov.masked(item, ours.decode("utf-8"))
|
|
133
|
+
b = prov.masked(item, theirs.decode("utf-8"))
|
|
134
|
+
except UnicodeDecodeError:
|
|
135
|
+
return " (not text: no diff shown)\n"
|
|
136
|
+
return "".join(difflib.unified_diff(a.splitlines(True), b.splitlines(True),
|
|
137
|
+
f"shared/{item}", theirs_name))
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def check(hub: Path, account_id: str, prov) -> list[str]:
|
|
141
|
+
"""The start check, run before every launch: make the account's links right, never losing
|
|
142
|
+
content. Returns one line per item it changed (a diff follows the line where one is due).
|
|
143
|
+
- missing link: created (all new links of one run are reported in one line);
|
|
144
|
+
- a real folder: its files are merged into shared/ (a clash keeps both, the incoming one
|
|
145
|
+
named after the account), then the emptied folder goes to backups/ and the link is made;
|
|
146
|
+
- a real `.jsonl` file: shared/ gets the lines it lacks, in order; the file goes to backups/;
|
|
147
|
+
- another real file: moved into shared/ when shared/ has none; else, identical or not, it
|
|
148
|
+
goes to backups/ and shared/'s is kept (a difference is shown);
|
|
149
|
+
- a link pointing anywhere else (absolute links included): the link goes to backups/.
|
|
150
|
+
Raises OSError when the hub cannot be changed; nothing is lost when it does."""
|
|
151
|
+
shared, acct = shared_dir(hub), account_dir(hub, account_id)
|
|
152
|
+
notes, linked, aside = [], [], None
|
|
153
|
+
|
|
154
|
+
def put_aside(p: Path) -> Path:
|
|
155
|
+
nonlocal aside
|
|
156
|
+
aside = aside or backup_dir(hub, account_id)
|
|
157
|
+
aside.mkdir(parents=True, exist_ok=True)
|
|
158
|
+
dest = store.free_name(aside / p.name)
|
|
159
|
+
os.rename(p, dest)
|
|
160
|
+
return dest
|
|
161
|
+
|
|
162
|
+
with lock(hub):
|
|
163
|
+
acct.mkdir(parents=True, exist_ok=True)
|
|
164
|
+
for name, is_dir in _items(prov):
|
|
165
|
+
if is_dir:
|
|
166
|
+
(shared / name).mkdir(parents=True, exist_ok=True)
|
|
167
|
+
for name, is_dir in _items(prov):
|
|
168
|
+
link, want, ours = acct / name, f"../../shared/{name}", shared / name
|
|
169
|
+
what = f"{account_id}: {name}{'/' if is_dir else ''}"
|
|
170
|
+
if link.is_symlink():
|
|
171
|
+
if os.readlink(link) == want:
|
|
172
|
+
continue
|
|
173
|
+
target = os.readlink(link)
|
|
174
|
+
notes.append(f"{what} pointed to {target}; that link is now in "
|
|
175
|
+
f"{put_aside(link)}")
|
|
176
|
+
elif not os.path.lexists(link):
|
|
177
|
+
linked.append(name)
|
|
178
|
+
elif is_dir != link.is_dir():
|
|
179
|
+
notes.append(f"{what} was a {'file' if is_dir else 'folder'}; moved to "
|
|
180
|
+
f"{put_aside(link)}")
|
|
181
|
+
elif is_dir:
|
|
182
|
+
n = _merge_tree(link, ours, account_id, move=True)
|
|
183
|
+
notes.append(f"{what} was a real folder: {n} file{'s' * (n != 1)} merged into "
|
|
184
|
+
f"the shared one; the rest is in {put_aside(link)}")
|
|
185
|
+
elif name.endswith(".jsonl"):
|
|
186
|
+
n = _append_missing(link, ours)
|
|
187
|
+
notes.append(f"{what} was a real file: {n} line{'s' * (n != 1)} added to the "
|
|
188
|
+
f"shared one; the file is in {put_aside(link)}")
|
|
189
|
+
elif not os.path.lexists(ours):
|
|
190
|
+
os.rename(link, ours)
|
|
191
|
+
notes.append(f"{what} was a real file and the hub had none: it is now the "
|
|
192
|
+
"shared one")
|
|
193
|
+
elif _same(link, ours):
|
|
194
|
+
notes.append(f"{what} was a real copy of the shared one; moved to "
|
|
195
|
+
f"{put_aside(link)}")
|
|
196
|
+
else:
|
|
197
|
+
shown = diff(prov, name, ours.read_bytes(), link.read_bytes(),
|
|
198
|
+
f"{account_id}'s {name} (set aside)")
|
|
199
|
+
notes.append(f"{what} differed from the shared one, which is kept; this "
|
|
200
|
+
f"account's copy is in {put_aside(link)}:\n{shown}".rstrip("\n"))
|
|
201
|
+
os.symlink(want, link)
|
|
202
|
+
if linked:
|
|
203
|
+
notes.insert(0, f"{account_id}: linked {', '.join(linked)}")
|
|
204
|
+
return notes
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def seed(hub: Path, source: Path, account_id: str, prov,
|
|
208
|
+
prepare: dict[str, object] | None = None) -> list[str]:
|
|
209
|
+
"""Copy the shared items of the user's folder `source` into shared/, never writing `source`.
|
|
210
|
+
Folders merge as in `check` (a clash keeps both); `.jsonl` files add the lines shared/ lacks;
|
|
211
|
+
another file is copied when shared/ has none (`prepare[name]`, when given, turns its text into
|
|
212
|
+
what is stored and raises ValueError for one it cannot use; a shared file equal to what it
|
|
213
|
+
makes of an empty text holds nothing of the user's and counts as none), and otherwise the
|
|
214
|
+
first seed wins and a difference is shown, not applied. Returns one line per item."""
|
|
215
|
+
shared, notes, prepare = shared_dir(hub), [], prepare or {}
|
|
216
|
+
skip = {i.rstrip("/") for i in prov.not_copied}
|
|
217
|
+
with lock(hub):
|
|
218
|
+
for name, is_dir in _items(prov):
|
|
219
|
+
src, ours = source / name, shared / name
|
|
220
|
+
if name in skip or not src.exists():
|
|
221
|
+
continue
|
|
222
|
+
if is_dir != src.is_dir():
|
|
223
|
+
notes.append(f"{name}: not a {'folder' if is_dir else 'file'} in {source}; "
|
|
224
|
+
"not copied")
|
|
225
|
+
elif is_dir:
|
|
226
|
+
if n := _merge_tree(src, ours, account_id, move=False):
|
|
227
|
+
notes.append(f"{name}/: copied {n} file{'s' * (n != 1)}")
|
|
228
|
+
elif name.endswith(".jsonl"):
|
|
229
|
+
if n := _append_missing(src, ours):
|
|
230
|
+
notes.append(f"{name}: added {n} line{'s' * (n != 1)}")
|
|
231
|
+
else:
|
|
232
|
+
data = src.read_bytes()
|
|
233
|
+
if name in prepare:
|
|
234
|
+
try:
|
|
235
|
+
data = prepare[name](data.decode("utf-8")).encode("utf-8")
|
|
236
|
+
except (UnicodeDecodeError, ValueError) as e:
|
|
237
|
+
notes.append(f"{name}: cannot be read in {source} ({e}); not copied")
|
|
238
|
+
continue
|
|
239
|
+
if not ours.exists():
|
|
240
|
+
_write_bytes(ours, data, src)
|
|
241
|
+
notes.append(f"{name}: copied")
|
|
242
|
+
elif name in prepare and ours.read_bytes() == prepare[name]("").encode("utf-8"):
|
|
243
|
+
store.write_with_backup(ours, data.decode("utf-8"),
|
|
244
|
+
backup_dir(hub, f"seed-{account_id}"))
|
|
245
|
+
notes.append(f"{name}: copied (the hub's held only what fairshare adds)")
|
|
246
|
+
elif ours.read_bytes() != data:
|
|
247
|
+
shown = diff(prov, name, ours.read_bytes(), data, f"{source}/{name}")
|
|
248
|
+
keep = ", keeping fairshare's own entries" if name in prepare else ""
|
|
249
|
+
notes.append(f"{name}: differs from the hub's, which is kept (the first "
|
|
250
|
+
f"folder copied wins); not applied:\n{shown}".rstrip("\n")
|
|
251
|
+
+ f"\nto adopt {source}/{name} instead, edit {ours}{keep}")
|
|
252
|
+
return notes
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def edit_shared(hub: Path, path: Path, change, label: str) -> str | None:
|
|
256
|
+
"""Apply `change` (current text or None -> new text or None for no change; may raise
|
|
257
|
+
ValueError) to the shared file `path`, under the hub's lock: read, change, back up into
|
|
258
|
+
backups/, write atomically, read back. Returns what happened, or None when nothing changed.
|
|
259
|
+
A file that cannot be read or decoded is refused, never taken for absent."""
|
|
260
|
+
with lock(hub):
|
|
261
|
+
try:
|
|
262
|
+
text = path.read_text(encoding="utf-8") if path.exists() else None
|
|
263
|
+
except (OSError, UnicodeDecodeError) as e:
|
|
264
|
+
return f"{path} cannot be read ({e}); left as it is"
|
|
265
|
+
try:
|
|
266
|
+
new = change(text)
|
|
267
|
+
except ValueError as e:
|
|
268
|
+
return f"{path}: {e}; left as it is"
|
|
269
|
+
if new is None:
|
|
270
|
+
return None
|
|
271
|
+
backup = store.write_with_backup(path, new, backup_dir(hub, label))
|
|
272
|
+
return f"updated {path}" + (f" (backup: {backup})" if backup else "")
|
fairshare/model.py
ADDED
|
@@ -0,0 +1,411 @@
|
|
|
1
|
+
"""Provider-neutral data model. Nothing here knows about any one provider."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import json
|
|
5
|
+
import math
|
|
6
|
+
import re
|
|
7
|
+
import shlex
|
|
8
|
+
import tomllib
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
from importlib import resources
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from . import browser
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass(frozen=True)
|
|
17
|
+
class Window:
|
|
18
|
+
"""One usage window as the provider reports it."""
|
|
19
|
+
used_pct: float # 0-100
|
|
20
|
+
resets_at: float # unix seconds
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True)
|
|
24
|
+
class Plan:
|
|
25
|
+
name: str
|
|
26
|
+
provider: str
|
|
27
|
+
capacity: float # relative budget size; Pro = 1.0
|
|
28
|
+
long_name: str # provider's name for the long window
|
|
29
|
+
long_hours: float # its length: the fallback for an unknown reset
|
|
30
|
+
short_name: str | None = None # provider's name for the short window; None: the plan has none
|
|
31
|
+
short_hours: float | None = None # its length, when the plan file gives it
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass(frozen=True)
|
|
35
|
+
class Account:
|
|
36
|
+
id: str
|
|
37
|
+
provider: str
|
|
38
|
+
plan: Plan | None # None: the configured plan has no plan file (see plan_error)
|
|
39
|
+
config_dir: Path
|
|
40
|
+
status_args: tuple[str, ...] | None = None # overrides the provider's sign-in check command
|
|
41
|
+
usage_args: tuple[str, ...] | None = None # overrides its usage probe; () turns it off
|
|
42
|
+
capacity: float | None = None # the account's own override; it survives plan detection
|
|
43
|
+
plan_error: str | None = None # why `plan` is None: the account is left out of ranking
|
|
44
|
+
browser: str | None = None # how its sign-in link opens (`browser.parse`); None: default
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass(frozen=True)
|
|
48
|
+
class AccountStatus:
|
|
49
|
+
"""What the provider says about one account's sign-in. Held in memory only."""
|
|
50
|
+
logged_in: bool
|
|
51
|
+
usable: bool # a subscription login (the provider's own kind), not an API key
|
|
52
|
+
identity: str | None = None # opaque: equal identities share one quota
|
|
53
|
+
plan: str | None = None # a fairshare plan name, None when the provider's maps to none
|
|
54
|
+
expires_at: float | None = None # when the sign-in ends (unix seconds), when the provider says
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
# Why a usage probe read nothing: short and value-free. A provider may add a detail after
|
|
58
|
+
# USAGE_NO_ANSWER only (`no answer: timed out`); the CLI tells USAGE_MODEL_TURN apart (it spends
|
|
59
|
+
# usage, so it is said loudly).
|
|
60
|
+
USAGE_NO_ANSWER = "no answer"
|
|
61
|
+
USAGE_SIGNED_OUT = "not signed in"
|
|
62
|
+
USAGE_NOT_UNDERSTOOD = "not understood"
|
|
63
|
+
USAGE_MODEL_TURN = "ran as a model turn"
|
|
64
|
+
|
|
65
|
+
MODEL_WINDOW_SEP = ":"
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def model_window(long_name: str, model: str) -> str:
|
|
69
|
+
"""The snapshot key of a per-model week (`seven_day:Fable`): kept beside the plan's windows,
|
|
70
|
+
never read by the policy."""
|
|
71
|
+
return f"{long_name}{MODEL_WINDOW_SEP}{model}"
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def window_model(key: str) -> str | None:
|
|
75
|
+
"""The model a snapshot key names a week for, else None (a plan window)."""
|
|
76
|
+
return key.partition(MODEL_WINDOW_SEP)[2] or None
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@dataclass(frozen=True)
|
|
80
|
+
class Candidate:
|
|
81
|
+
"""An account found on disk, before the user confirms it."""
|
|
82
|
+
id: str
|
|
83
|
+
provider: str
|
|
84
|
+
config_dir: Path
|
|
85
|
+
found: str # where it was found, shown to the user
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
@dataclass(frozen=True)
|
|
89
|
+
class Capture:
|
|
90
|
+
"""A usage hook the provider calls, as found in its settings: which fairshare command it
|
|
91
|
+
runs (`runner`, the argv before `capture`) and the user's own command it wraps, if any."""
|
|
92
|
+
runner: tuple[str, ...]
|
|
93
|
+
then: str | None
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
EFFORT_NONE = "none" # the model takes no effort level: no effort argument is passed
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
@dataclass(frozen=True)
|
|
100
|
+
class SessionSeen:
|
|
101
|
+
"""A running session as the provider describes it to a usage hook or a hook: its id, and its
|
|
102
|
+
folder and transcript when given. The usage hook's payload also names the model (and its
|
|
103
|
+
effort level, EFFORT_NONE when the model takes none); None: not said, keep what is known."""
|
|
104
|
+
id: str
|
|
105
|
+
cwd: str | None = None
|
|
106
|
+
transcript: str | None = None
|
|
107
|
+
model: str | None = None # the provider's model id
|
|
108
|
+
model_name: str | None = None # its display name
|
|
109
|
+
effort: str | None = None
|
|
110
|
+
cost: float | None = None # the session's running cost so far, in the payload's unit
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
@dataclass(frozen=True)
|
|
114
|
+
class SessionRecord:
|
|
115
|
+
"""What fairshare keeps of one session (`store.note_session`)."""
|
|
116
|
+
id: str
|
|
117
|
+
account: str
|
|
118
|
+
cwd: str | None
|
|
119
|
+
transcript: str | None
|
|
120
|
+
seen: float # when a usage hook or a hook last saw it
|
|
121
|
+
stranded_at: float | None = None # when its account's limit stopped it, if it did
|
|
122
|
+
role: str | None = None # ROLE_WORKER for a worker; None: a main session
|
|
123
|
+
parent: str | None = None # a worker's main session (its id)
|
|
124
|
+
checkpoint_requested: float | None = None # when its main session asked for a checkpoint
|
|
125
|
+
request_said: float | None = None # the request a hook last passed on (its time)
|
|
126
|
+
warned: dict = field(default_factory=dict) # plan window -> [its reset, level warned]
|
|
127
|
+
reported: dict = field(default_factory=dict) # what `watch` already said: key -> value
|
|
128
|
+
model: str | None = None # the latest model id a usage hook saw
|
|
129
|
+
model_name: str | None = None # its display name
|
|
130
|
+
effort: str | None = None # the latest effort level (EFFORT_NONE: the model takes none)
|
|
131
|
+
waiting_until: float | None = None # stranded, left for the provider's own resume at this reset
|
|
132
|
+
costs: list = field(default_factory=list) # the running cost seen: series (a new one each
|
|
133
|
+
# time it fell) of [time, cost], see store.add_cost
|
|
134
|
+
continues: str | None = None # the session this one continues under a new id
|
|
135
|
+
moved_to: str | None = None # the session that continues this one (store.link_session)
|
|
136
|
+
drawn: dict = field(default_factory=dict) # the windows its usage hook last drew:
|
|
137
|
+
# {account: {key: [used_pct, resets_at]}}
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
ROLE_WORKER = "worker"
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
@dataclass(frozen=True)
|
|
144
|
+
class Worker:
|
|
145
|
+
"""A background session a main session started (`fairshare worker`). Its session id is
|
|
146
|
+
known once joined: the provider lists sessions by name."""
|
|
147
|
+
name: str
|
|
148
|
+
parent: str # the main session's id
|
|
149
|
+
account: str
|
|
150
|
+
cwd: str
|
|
151
|
+
started: float
|
|
152
|
+
session: str | None = None
|
|
153
|
+
model: str | None = None # what the main session chose for it
|
|
154
|
+
effort: str | None = None
|
|
155
|
+
cost: float | None = None # its measured cost when it ended or went still (unread yet)
|
|
156
|
+
duration: float | None = None # seconds from its start to its last cost movement
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
@dataclass(frozen=True)
|
|
160
|
+
class Request:
|
|
161
|
+
"""What a command asks the launcher to do with its child's session (`kind`), with the
|
|
162
|
+
user's flags: a model, an effort, an account. `manual`: asked by the user (no check that the
|
|
163
|
+
account is out); `pid`: the session's own process, when known."""
|
|
164
|
+
session: str
|
|
165
|
+
manual: bool
|
|
166
|
+
pid: int | None = None
|
|
167
|
+
kind: str = "pickup"
|
|
168
|
+
model: str | None = None
|
|
169
|
+
effort: str | None = None
|
|
170
|
+
account: str | None = None
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
@dataclass(frozen=True)
|
|
174
|
+
class LiveSession:
|
|
175
|
+
"""A running session as the provider lists it."""
|
|
176
|
+
id: str
|
|
177
|
+
name: str | None
|
|
178
|
+
busy: bool | None # None: the provider did not say
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
NOTE_THINKING, NOTE_WRITING = "thinking", "writing"
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
@dataclass(frozen=True)
|
|
185
|
+
class NoteEvent:
|
|
186
|
+
"""One line of the handoff note turn's output, as the provider reads it: the model is
|
|
187
|
+
thinking (NOTE_THINKING) or writing its answer (NOTE_WRITING, with the text that arrived)."""
|
|
188
|
+
kind: str
|
|
189
|
+
text: str = ""
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
@dataclass(frozen=True)
|
|
193
|
+
class Snapshot:
|
|
194
|
+
captured_at: float
|
|
195
|
+
windows: dict[str, Window] = field(default_factory=dict)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
@dataclass(frozen=True)
|
|
199
|
+
class Tuning:
|
|
200
|
+
short_hot_pct: float = 85.0 # a short window this full counts as "hot"
|
|
201
|
+
long_exhausted_pct: float = 98.0 # a long window this full cannot take work
|
|
202
|
+
grace_hours: float = 1.0 # a hot account resetting this soon is still usable
|
|
203
|
+
min_hours: float = 1.0 # floor on time-to-reset, so a near reset stays finite
|
|
204
|
+
refresh_minutes: float = 5.0 # usage this old is asked for again (the usage probe)
|
|
205
|
+
launch_pause: float = 3.0 # seconds a launch with a close choice waits; 0: never
|
|
206
|
+
resume_wait_minutes: float = 30.0 # a limit resetting this soon is waited for, not picked up
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def _plan_data(name: str) -> dict:
|
|
210
|
+
return tomllib.loads((resources.files("fairshare.plans") / f"{name}.toml").read_text())
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def plan_for(provider: str, native: str | None) -> str | None:
|
|
214
|
+
"""The plan whose `names` list the provider's own name for it, else None."""
|
|
215
|
+
for name in plan_names():
|
|
216
|
+
d = _plan_data(name)
|
|
217
|
+
if d["provider"] == provider and native in d.get("names", []):
|
|
218
|
+
return d["name"]
|
|
219
|
+
return None
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def window_names(provider: str) -> set[str]:
|
|
223
|
+
"""Every window name the plan files give for `provider`: what its usage payload may carry."""
|
|
224
|
+
return {w["name"] for n in plan_names() if (d := _plan_data(n))["provider"] == provider
|
|
225
|
+
for w in d["windows"].values()}
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def load_plan(name: str, capacity: float | None = None) -> Plan:
|
|
229
|
+
d = _plan_data(name)
|
|
230
|
+
w = d["windows"]
|
|
231
|
+
cap = float(d["capacity"]) if capacity is None else float(capacity)
|
|
232
|
+
if cap <= 0:
|
|
233
|
+
raise ValueError(f"capacity must be positive (got {cap}) for plan {name}")
|
|
234
|
+
short = w.get("short", {})
|
|
235
|
+
return Plan(d["name"], d["provider"], cap, w["long"]["name"], float(w["long"]["hours"]),
|
|
236
|
+
short.get("name"), float(short["hours"]) if "hours" in short else None)
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
DEFAULT_HUB = "~/.local/share/fairshare/hub" # where setup proposes the hub
|
|
240
|
+
ACCOUNT_ID = re.compile(r"\w[\w.-]*") # an id is also a folder name in the hub
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
class ConfigError(ValueError):
|
|
244
|
+
"""accounts.toml cannot be used. The message says what is wrong and where; callers add the
|
|
245
|
+
file's name."""
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
def _sole_provider() -> str | None:
|
|
249
|
+
"""The one provider the plan files serve, or None when there are several."""
|
|
250
|
+
found = {_plan_data(n)["provider"] for n in plan_names()}
|
|
251
|
+
return found.pop() if len(found) == 1 else None
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
def _account(a: dict, hub: Path) -> Account:
|
|
255
|
+
if "config_dir" in a:
|
|
256
|
+
raise ValueError("config_dir is no longer used: each account lives in the hub, at "
|
|
257
|
+
"<hub>/accounts/<id>; move this file aside, then run `fairshare setup`")
|
|
258
|
+
if not isinstance(a["id"], str) or not ACCOUNT_ID.fullmatch(a["id"]):
|
|
259
|
+
raise ValueError(f"id {a['id']!r}: use letters, digits, '.', '-' or '_'")
|
|
260
|
+
capacity = None if a.get("capacity") is None else float(a["capacity"])
|
|
261
|
+
try:
|
|
262
|
+
plan, error = load_plan(a["plan"], capacity), None
|
|
263
|
+
except FileNotFoundError: # a renamed or removed plan file must not take the rest down
|
|
264
|
+
plan, error = None, f"plan {a['plan']} not found; known: {', '.join(plan_names())}"
|
|
265
|
+
provider = a.get("provider") or (plan.provider if plan else _sole_provider())
|
|
266
|
+
if not provider:
|
|
267
|
+
raise ValueError(f"{error}, and no provider is named")
|
|
268
|
+
args, usage = _args(a, "status_args"), _args(a, "usage_args")
|
|
269
|
+
if (spec := a.get("browser")) is not None:
|
|
270
|
+
browser.parse(spec) # raises ValueError saying what is accepted
|
|
271
|
+
return Account(a["id"], provider, plan, hub / "accounts" / a["id"], args or None, usage,
|
|
272
|
+
capacity, error, spec)
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
def _args(a: dict, key: str) -> tuple[str, ...] | None:
|
|
276
|
+
"""An account's command override `key`: a string (split as a shell would) or a list of
|
|
277
|
+
strings; None when absent."""
|
|
278
|
+
v = a.get(key)
|
|
279
|
+
if v is None:
|
|
280
|
+
return None
|
|
281
|
+
if isinstance(v, str):
|
|
282
|
+
return tuple(shlex.split(v))
|
|
283
|
+
if isinstance(v, list) and all(isinstance(x, str) for x in v):
|
|
284
|
+
return tuple(v)
|
|
285
|
+
raise ValueError(f"{key} of {a['id']} must be a string or a list of strings")
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def load_accounts(path: Path) -> tuple[list[Account], Tuning, Path]:
|
|
289
|
+
"""The accounts, the tuning and the hub folder. Raises ConfigError, never anything else, for
|
|
290
|
+
a file that cannot be used. An account whose plan has no plan file loads with `plan` None and
|
|
291
|
+
`plan_error` set."""
|
|
292
|
+
try:
|
|
293
|
+
d = tomllib.loads(path.read_text())
|
|
294
|
+
except tomllib.TOMLDecodeError as e:
|
|
295
|
+
raise ConfigError(str(e)) from None
|
|
296
|
+
except (OSError, UnicodeDecodeError):
|
|
297
|
+
raise ConfigError("cannot be read as text") from None
|
|
298
|
+
if not isinstance(d.get("account", []), list):
|
|
299
|
+
raise ConfigError("account must be a list of [[account]] tables")
|
|
300
|
+
if not isinstance(d.get("hub", DEFAULT_HUB), str):
|
|
301
|
+
raise ConfigError("hub must be a folder path in quotes")
|
|
302
|
+
hub = Path(d.get("hub", DEFAULT_HUB)).expanduser()
|
|
303
|
+
accounts = []
|
|
304
|
+
for i, a in enumerate(d.get("account", []), 1):
|
|
305
|
+
try:
|
|
306
|
+
accounts.append(_account(a, hub))
|
|
307
|
+
except KeyError as e:
|
|
308
|
+
raise ConfigError(f"account {i}: missing {e}") from None
|
|
309
|
+
except (TypeError, ValueError, AttributeError) as e:
|
|
310
|
+
raise ConfigError(f"account {i}: {e}") from None
|
|
311
|
+
if [x.id for x in accounts].count(accounts[-1].id) > 1:
|
|
312
|
+
raise ConfigError(f"account {i}: id {accounts[-1].id!r} is used twice")
|
|
313
|
+
policy, valid = d.get("policy", {}), ", ".join(Tuning.__dataclass_fields__)
|
|
314
|
+
if not isinstance(policy, dict):
|
|
315
|
+
raise ConfigError("[policy] must be a table")
|
|
316
|
+
for k, v in policy.items():
|
|
317
|
+
if k not in Tuning.__dataclass_fields__:
|
|
318
|
+
raise ConfigError(f"[policy] unknown key {k!r}; valid keys: {valid}")
|
|
319
|
+
if isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v):
|
|
320
|
+
raise ConfigError(f"[policy] {k} must be a number (not nan or inf)")
|
|
321
|
+
if policy.get("refresh_minutes", 1) < 1:
|
|
322
|
+
raise ConfigError("[policy] refresh_minutes must be at least 1")
|
|
323
|
+
if policy.get("launch_pause", 0) < 0:
|
|
324
|
+
raise ConfigError("[policy] launch_pause must be 0 (off) or more")
|
|
325
|
+
if policy.get("resume_wait_minutes", 0) < 0:
|
|
326
|
+
raise ConfigError("[policy] resume_wait_minutes must be 0 (always pick up) or more")
|
|
327
|
+
return accounts, Tuning(**policy), hub
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
def plan_names() -> list[str]:
|
|
331
|
+
return sorted(f.name[:-5] for f in resources.files("fairshare.plans").iterdir()
|
|
332
|
+
if f.name.endswith(".toml"))
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
# accounts.toml is edited as text: a change touches only its own lines, so the user's comments and
|
|
336
|
+
# layout survive, and every result is parsed again before it is returned.
|
|
337
|
+
|
|
338
|
+
_TABLE = re.compile(r"^\s*\[")
|
|
339
|
+
_HUB_LINE = re.compile(r"^\s*hub\s*=")
|
|
340
|
+
_ACCOUNT_TABLE = re.compile(r"^\s*\[\[\s*account\s*\]\]")
|
|
341
|
+
|
|
342
|
+
|
|
343
|
+
def account_table(entry: dict) -> str:
|
|
344
|
+
"""One [[account]] table. Refuses what would not load."""
|
|
345
|
+
if not ACCOUNT_ID.fullmatch(entry["id"]):
|
|
346
|
+
raise ValueError(f"account id {entry['id']!r}: use letters, digits, '.', '-' or '_'")
|
|
347
|
+
if entry["plan"] not in plan_names():
|
|
348
|
+
raise ValueError(f"unknown plan {entry['plan']!r} (known: {', '.join(plan_names())})")
|
|
349
|
+
load_plan(entry["plan"], entry.get("capacity"))
|
|
350
|
+
return "\n".join(["[[account]]", *(f"{k} = {_toml(v)}" for k, v in entry.items())]) + "\n"
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def with_hub(text: str, hub: str) -> str:
|
|
354
|
+
"""`text` whose top-level `hub` key is `hub`: its one line replaced, or added at the top."""
|
|
355
|
+
old = tomllib.loads(text)
|
|
356
|
+
if old.get("hub") == hub:
|
|
357
|
+
return text
|
|
358
|
+
new = f"hub = {_toml(hub)}\n" + ("\n" + text if text.strip() else "")
|
|
359
|
+
if "hub" in old:
|
|
360
|
+
lines = text.splitlines(keepends=True)
|
|
361
|
+
at = next((i for i, line in enumerate(lines) if _HUB_LINE.match(line)
|
|
362
|
+
and not any(_TABLE.match(x) for x in lines[:i])), None)
|
|
363
|
+
if at is None:
|
|
364
|
+
raise ValueError("could not find the hub line in accounts.toml")
|
|
365
|
+
new = "".join(lines[:at] + [f"hub = {_toml(hub)}\n"] + lines[at + 1:])
|
|
366
|
+
if tomllib.loads(new) != {**old, "hub": hub}:
|
|
367
|
+
raise ValueError("could not set the hub in accounts.toml")
|
|
368
|
+
return new
|
|
369
|
+
|
|
370
|
+
|
|
371
|
+
def with_account(text: str, entry: dict) -> str:
|
|
372
|
+
"""`text` with one more [[account]] table at its end."""
|
|
373
|
+
old = tomllib.loads(text).get("account", [])
|
|
374
|
+
if any(a.get("id") == entry["id"] for a in old):
|
|
375
|
+
raise ValueError(f"account id {entry['id']!r} is already configured")
|
|
376
|
+
body = text if not text or text.endswith("\n") else text + "\n"
|
|
377
|
+
new = body + ("\n" if body.strip() else "") + account_table(entry)
|
|
378
|
+
if tomllib.loads(new).get("account", []) != [*old, entry]:
|
|
379
|
+
raise ValueError("could not add the account to accounts.toml")
|
|
380
|
+
return new
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
def without_account(text: str, account_id: str) -> str:
|
|
384
|
+
"""`text` without the [[account]] table whose id is `account_id`: its lines, from its header
|
|
385
|
+
to the next table, are removed and nothing else."""
|
|
386
|
+
lines = text.splitlines(keepends=True)
|
|
387
|
+
starts = [i for i, line in enumerate(lines) if _TABLE.match(line)] + [len(lines)]
|
|
388
|
+
for i, end in zip(starts, starts[1:]):
|
|
389
|
+
if _ACCOUNT_TABLE.match(lines[i]):
|
|
390
|
+
try:
|
|
391
|
+
found = tomllib.loads("".join(lines[i:end]))["account"][0].get("id")
|
|
392
|
+
except (tomllib.TOMLDecodeError, KeyError, IndexError):
|
|
393
|
+
continue
|
|
394
|
+
if found == account_id:
|
|
395
|
+
new = "".join(lines[:i] + lines[end:])
|
|
396
|
+
old = tomllib.loads(text).get("account", [])
|
|
397
|
+
if tomllib.loads(new).get("account", []) != [a for a in old
|
|
398
|
+
if a.get("id") != account_id]:
|
|
399
|
+
raise ValueError("could not remove the account from accounts.toml")
|
|
400
|
+
return new
|
|
401
|
+
raise ValueError(f"no account {account_id!r} in accounts.toml")
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
def _toml(v) -> str:
|
|
405
|
+
if isinstance(v, bool):
|
|
406
|
+
return str(v).lower()
|
|
407
|
+
if isinstance(v, (int, float)):
|
|
408
|
+
return repr(v)
|
|
409
|
+
if isinstance(v, str):
|
|
410
|
+
return json.dumps(v, ensure_ascii=False)
|
|
411
|
+
raise ValueError(f"cannot write {v!r} to accounts.toml")
|
|
File without changes
|