Something went wrong. Try again.
small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976from __future__ import annotations
import astimport base64import albedo_alarmsimport albedo_apiimport albedo_outputimport albedo_bundleimport albedo_statefrom albedo_values import Unencodable, decode, encodeimport albedo_capturefrom albedo_capture import Capture, CELL_PREVIEW, PREVIEWimport albedo_linkimport albedo_memoryimport albedo_noticesimport albedo_spillfrom albedo_protocol import parse_incomingimport albedo_procimport albedo_quiescenceimport albedo_shellfrom collections.abc import Awaitable, Callable, Iterable, Sequencefrom typing import castfrom types import CodeType, FrameType, ModuleTypeimport albedo_traceimport asyncioimport contextlibimport builtinsimport codecsimport collectionsimport contextvarsimport dataclassesimport faulthandlerimport inspectimport importlibimport ioimport jsonimport osimport pathlibimport reprlibimport selectimport shutilimport signalimport sysimport tempfileimport threadingimport timeimport tracebackimport reimport secretsimport warningsimport weakref
CLEANUP_DEADLINE = ( 1.5 # seconds: plugins must finish cleanup inside the supervisor's patience)LIMITS = {"cell": 16, "job": 64, "native": 1} # retained captures per kindCELL: contextvars.ContextVar[Capture | None] = contextvars.ContextVar( "cell", default=None)LINK: albedo_link.StdioLink | albedo_link.SocketLinkRUN_DIR: str | None = None # a detached kernel's run directory, None over stdioWATCH_INTERVAL = 1.0 # seconds between a detached kernel's lifetime checksFIRST_ATTACH_GRACE = 60.0 # seconds a detached kernel waits for its first attachLOOP = asyncio.new_event_loop()asyncio.set_event_loop(LOOP)
albedo_proc.reap_stopped_safely(LOOP)QUEUE: asyncio.Queue[albedo_api.Execute | albedo_api.State] = asyncio.Queue()PENDING: dict[str, asyncio.Future[albedo_api.HostReply]] = {}# Host calls a synchronous API waits for; the reader thread hands their reply# over directly, since the loop it would go through is the one waiting.WAITING: dict[str, tuple[threading.Event, list[albedo_api.HostReply]]] = {}HOST_NOW_TIMEOUT = 30.0HOST_SLOTS = asyncio.Semaphore(32)OWNER_CALLS = asyncio.Semaphore(32) # concurrent tool calls from the connection ownerOWNER_TASKS: dict[str, asyncio.Task[object]] = {} # interruptable by invoke idLIVE: collections.OrderedDict[str, object] = ( collections.OrderedDict()) # remote referencesLIVE_LIMIT = 64 # live references retained for the owner; LRU beyond thatPENDING_OBJECTS: collections.OrderedDict[str, asyncio.Future[tuple[bool, object]]] = ( collections.OrderedDict())MIRROR_INTERVAL = 0.15 # seconds between output-tail mirror frames while data flowsMIRROR_TAIL = PREVIEW # the same bounded tail window as a local jobBACKGROUND_SECONDS = max( 0.01, float(os.environ.get("ALBEDO_CELL_BACKGROUND_SECONDS", "60")))CELL_TASKS: dict[str, asyncio.Task[dict[str, object]]] = {}CELL_CAPTURES: dict[str, Capture] = {}CELL_STARTS: dict[ str, tuple[int, float]] = {} # (footprint, monotonic) as each running cell beganBACKGROUNDED: dict[str, dict[str, object]] = {}BACKGROUNDED_LOCK = threading.Lock()BACKGROUND_RESULTS: dict[str, dict[str, object]] = {}# Running cells by id, each with how to claim it after a daemon restart: its# done frame, after backgrounding it if it still runs (`claim_reply`).CLAIMS: dict[str, Callable[[], dict[str, object]]] = {}READ_CELLS: set[str] = set()CELL_NOTICES = albedo_notices.Notices("cells")NOTICED: set[str] = set() # cells a stored notice names whose result is unreadCELL_ANNOUNCER: asyncio.Task[None] | None = Noneinterrupt_capture: Capture | None = NoneARCHIVES: collections.OrderedDict[str, Capture] = collections.OrderedDict()# Finished executions by cell id: a replayed execute answers with its result# instead of running the cell twice. Queued or running ones are in EXECUTING.FINISHED: collections.OrderedDict[str, dict[str, object]] = collections.OrderedDict()FINISHED_LIMIT = 16# Base64 image text kept across finished results; older results drop theirs first.FINISHED_IMAGE_BYTES = 8 * 1024 * 1024EXECUTING: set[str] = set()# Interrupts that arrived while their cell was still queued, by cell id.INTERRUPTS: dict[str, str] = {}QUIESCENCE: albedo_quiescence.Quiescence | None = NoneRESOURCE_OWNERS: list[Callable[[], bool]] = []# Plugins naming the jobs a cell started that still run, for cells.cancel.CELL_JOBS: list[Callable[[str], list[tuple[str, str]]]] = []# Plugins' own saved state (the run plugin's job book), by plugin name.STATE_HOOKS: dict[str, tuple[albedo_api.SaveState, albedo_api.RestoreState]] = {}LAST_WORK: tuple[int, bool, bool, tuple[tuple[str, str, int], ...]] | None = None# Bumped by every message that may change what a snapshot writes: anything the# owner sends but a snapshot, a read, or an interrupt (whose cell already# counted), and every job start and end. A snapshot at an unchanged count, to# an unchanged file, answers with the last one.CHANGES = 0SAVED: tuple[str, int, tuple[int, int], dict[str, object]] | None = NoneUNCHANGING = frozenset({"snapshot", "interrupt", "introspect", "job_list", "job_read"})READY = threading.Event()
def _cannot_assign_tool(name: str) -> str: return f"cannot assign to kernel tool {name!r}; choose another variable name"
def _cannot_delete_tool(name: str) -> str: return f"cannot delete kernel tool {name!r}"
class Namespace(dict[str, object]): """The cell global namespace; tool bindings stay locked once plugins load."""
def __init__(self, initial: dict[str, object]) -> None: super().__init__(initial) self.protected: set[str] = set()
def __setitem__(self, key: str, value: object) -> None: if key in self.protected and value is not dict.get(self, key): raise albedo_shell.Refused(_cannot_assign_tool(key)) super().__setitem__(key, value)
def __delitem__(self, key: str) -> None: if key in self.protected: raise albedo_shell.Refused(_cannot_delete_tool(key)) super().__delitem__(key)
def pop(self, key: object, *default: object) -> object: if isinstance(key, str) and key in self.protected: raise albedo_shell.Refused(_cannot_delete_tool(key)) return super().pop(cast(str, key), *default)
def popitem(self) -> tuple[str, object]: for key in reversed(list(self)): if key not in self.protected: return key, super().pop(key) raise KeyError("popitem(): dictionary is empty")
def setdefault(self, key: str, default: object = None) -> object: if key in self: return self[key] self[key] = default return default
def update(self, *other: object, **kwargs: object) -> None: # type: ignore[override] for key, value in dict(*other, **kwargs).items(): self[key] = value
def __ior__(self, other: object) -> Namespace: # type: ignore[override] self.update(other) return self
def clear(self) -> None: for key in list(self): if key not in self.protected and key not in INJECTED: super().__delitem__(key)
NAMESPACE = Namespace({"__name__": "__main__"})DEFINITIONS: collections.OrderedDict[str, str] = collections.OrderedDict()CLEANUP: list[albedo_api.Cleanup] = []STOP_HANDLERS: list[Callable[[str], Awaitable[dict[str, object] | None]]] = []JOB_VIEWS: list[Callable[[dict[str, object]], Awaitable[dict[str, object] | None]]] = []HANDLES: list[type[object]] = [asyncio.Task]REPR = reprlib.Repr()REPR.maxstring = REPR.maxother = 4000REPR.maxdict = REPR.maxlist = REPR.maxtuple = 50
def forget_output(id: str) -> None: ARCHIVES.pop(id, None) READ_WATCHERS.pop(id, None) with BACKGROUNDED_LOCK: BACKGROUNDED.pop(id, None)
def show(value: object) -> str: return ( REPR.repr(value) .encode("utf-8", errors="replace")[:PREVIEW] .decode("utf-8", errors="ignore") )
def send(value: dict[str, object]) -> None: global CHANGES if value.get("type") in ("job_start", "job"): CHANGES += 1 LINK.send(value)
async def cleanup() -> None: """Run plugin cleanup; a callback may return an awaitable to clean up asynchronously.""" for close in reversed(CLEANUP): try: result = close() if inspect.isawaitable(result): await result except BaseException as error: try: send( { "type": "cleanup", "module": getattr(close, "__module__", "plugin"), "failures": [f"{type(error).__name__}: {error}"], } ) except (OSError, ValueError): pass # a disconnected owner must not prevent other cleanup callbacks
def record_death(reason: str) -> None: if DEATH_FD is not None: with contextlib.suppress(OSError): _ = os.write(DEATH_FD, (reason.strip() + "\n").encode("utf-8", "replace"))
def fatal_signal(signum: int, _frame: FrameType | None) -> None: if SHUTTING_DOWN: return try: name = signal.Signals(signum).name except ValueError: name = f"signal {signum}" record_death(f"received {name}") if RUN_DIR is not None: with contextlib.suppress(OSError): os.unlink(os.path.join(RUN_DIR, "kernel.sock")) os.killpg(os.getpid(), signal.SIGKILL)
def die() -> None: """Leave the session: clean up while the loop can still run it, then kill our group.
Called from the reader thread and from the main thread, never from a loop callback, so cleanup may await without deadlocking the interpreter. """ global SHUTTING_DOWN SHUTTING_DOWN = True failure = None try: if LOOP.is_running(): asyncio.run_coroutine_threadsafe(cleanup(), LOOP).result(CLEANUP_DEADLINE) else: LOOP.run_until_complete(asyncio.wait_for(cleanup(), CLEANUP_DEADLINE)) except TimeoutError: # cleanup() catches each callback's own errors, so this is the # deadline: a callback ran long, or a cell held the loop throughout. failure = f"plugin cleanup did not finish within {CLEANUP_DEADLINE} s" except BaseException as error: failure = f"{type(error).__name__}: {error}" if failure is not None: try: send( { "type": "cleanup", "module": "kernel", "failures": [f"cleanup incomplete: {failure}"], } ) except (OSError, ValueError): pass # the owner disconnected; it independently tracks our groups if RUN_DIR is not None: # No socket left behind: an attach from now on learns we are gone. shutil.rmtree(RUN_DIR, ignore_errors=True) # The interpreter and its subprocesses own a separate process group. os.killpg(os.getpid(), signal.SIGKILL)
def receive(frame: object) -> None: """Act on one frame from the owner, on the link's reader thread.""" global interrupt_capture try: message = parse_incoming(frame) except ValueError: die() return if message["type"] == "shutdown": die() elif message["type"] == "interrupt": capture = CELL_CAPTURES.get(message["id"]) if capture is not None: interrupt_capture = capture capture.interruption = message.get("reason", "cancelled") os.kill(os.getpid(), signal.SIGINT) _ = LOOP.call_soon_threadsafe(interrupt_queued, message) else: # The loop takes it after the execute it may name, not started yet. _ = LOOP.call_soon_threadsafe(deliver, message) elif message["type"] == "reply" and message["id"] in WAITING: arrived, answer = WAITING[message["id"]] answer.append(message["value"]) arrived.set() elif message["type"] == "cell_claim": # Here rather than on the loop, which a cell's own code may hold. send(claim_reply(message)) else: _ = LOOP.call_soon_threadsafe(deliver, message)
def claim_reply(message: albedo_api.CellClaim) -> dict[str, object]: """A restarted daemon's question about a cell whose call it lost: its result, or a backgrounded one that wakes the session when it ends.""" reply: dict[str, object] = {"type": "cell_claim", "id": message["id"], "ok": True} # The claim first: a cell leaves CLAIMS only once FINISHED has it. claim = CLAIMS.get(message["cell"]) done = claim() if claim is not None else FINISHED.get(message["cell"]) if done is not None: reply["done"] = done return reply
def reader() -> None: try: LINK.serve(receive) except Exception: pass die()
def watch() -> None: """A detached kernel ends itself: when its run directory is gone (its home was removed), or when nothing attached for the grace period and no job or cell is still running.""" assert isinstance(LINK, albedo_link.SocketLink) and RUN_DIR is not None while True: time.sleep(WATCH_INTERVAL) if not os.path.isdir(RUN_DIR): die() busy = bool(CELL_TASKS) or not QUEUE.empty() or LINK.jobs.live() > 0 if not busy and LINK.idle_for() > LINK.grace: die()
def guard_memory() -> None: """Interrupts every running cell once the kernel's footprint passes its threshold (albedo_memory), so a runaway cell ends instead of the kernel. A thread, like the deadline timer: a synchronous cell holds the loop.
Cancelling a cell does not stop the threads it started, so each sample past the cap also stops every thread still running cell code, until none is left or the kernel is back under its cap: a pool starts its next item as soon as the last one is stopped.""" stopping = False while True: time.sleep(albedo_memory.INTERVAL) if not CELL_STARTS and not stopping: continue try: used = albedo_memory.footprint() if used is None: return now = time.monotonic() for id, (start, began) in list(CELL_STARTS.items()): if now - began < albedo_memory.INTERVAL: continue capture = CELL_CAPTURES.get(id) if capture is None or capture.interruption == "memory": continue # already told; it is unwinding if used > albedo_memory.threshold(start): receive({"type": "interrupt", "id": id, "reason": "memory"}) stopping = True if stopping: over = used > albedo_memory.LIMIT stopping = over and albedo_memory.stop_cell_threads() > 0 except Exception: continue # an allocation failed at the limit: sample again
def hello() -> dict[str, object]: """What a detached kernel tells each attach about itself.""" pgid = os.getpgid(0) return { "pid": os.getpid(), "pgid": pgid if pgid == os.getpid() else None, "leader": albedo_proc.leader_token(os.getpid()), "ready": READY.is_set(), "cells": len(CELL_TASKS), "background_cells": live_background_cells(), "quiescent": LAST_WORK[1] if LAST_WORK is not None else False, "bloated": LAST_WORK[2] if LAST_WORK is not None else False, }
def deliver(message: albedo_api.Incoming) -> None: global CHANGES if message["type"] not in UNCHANGING: CHANGES += 1 if message["type"] == "interrupt": interrupt_queued(message) elif message["type"] == "reply": future = PENDING.pop(message["id"], None) if future is not None and not future.done(): future.set_result(message["value"]) elif message["type"] == "invoke": _ = LOOP.create_task(serve_invoke(message)) elif message["type"] == "introspect": send( { "type": "introspected", "id": message["id"], "names": sorted( name for name in NAMESPACE if name.isidentifier() and not name.startswith("_") ), "handles": [ {"id": key, "repr": show(value)} for key, value in LIVE.items() ], } ) elif message["type"] == "release": LIVE.pop(message["handle"], None) elif message["type"] == "job_stop": _ = LOOP.create_task(serve_job_stop(message["id"])) elif message["type"] in ("job_list", "job_read"): _ = LOOP.create_task(serve_job_view(cast(dict[str, object], message))) elif message["type"] == "snapshot" and (bool(CELL_TASKS) or not QUEUE.empty()): # A namespace mid-cell is no state to carry: the owner tries again later. send(state_reply(message, {"error": "a cell is still running"})) elif message["type"] == "execute" and message["id"] in FINISHED: send(FINISHED[message["id"]]) elif message["type"] == "execute" and message["id"] in EXECUTING: pass # already queued or running; its done frame answers both else: if message["type"] == "execute": EXECUTING.add(message["id"]) QUEUE.put_nowait(cast(albedo_api.Execute | albedo_api.State, message))
def interrupt_queued(message: albedo_api.Interrupt) -> None: """An interrupt the reader thread found no running cell for. Here on the loop, the cell it names is still queued, or has started since and waits at an await, where cancelling reaches it.""" reason = message.get("reason", "cancelled") task = OWNER_TASKS.get(message["id"]) capture = CELL_CAPTURES.get(message["id"]) if task is not None: _ = task.cancel() elif capture is not None: capture.interruption = reason _ = CELL_TASKS[message["id"]].cancel() elif message["id"] in EXECUTING: INTERRUPTS[message["id"]] = reason
class WorkError(Exception): def __init__(self, code: str, message: str) -> None: super().__init__(message) self.code: str = code
async def host(method: str, args: dict[str, object]) -> object: async with HOST_SLOTS: return await _host(method, args)
async def _host(method: str, args: dict[str, object]) -> object: key = secrets.token_hex(16) future: asyncio.Future[albedo_api.HostReply] = LOOP.create_future() PENDING[key] = future send({"type": "call", "id": key, "method": method, "args": args}) try: answer = await future finally: _ = PENDING.pop(key, None) if answer["ok"]: return answer["value"] raise WorkError(answer["code"], answer["message"])
def host_now(method: str, args: dict[str, object]) -> object: """A host call for a synchronous API: blocks the calling thread, the loop's included, until the reply. Only for calls the host answers at once; an interrupt still ends the wait.""" key = secrets.token_hex(16) arrived = threading.Event() answers: list[albedo_api.HostReply] = [] WAITING[key] = (arrived, answers) send({"type": "call", "id": key, "method": method, "args": args}) try: if not arrived.wait(HOST_NOW_TIMEOUT): raise WorkError( "timeout", f"{method} had no answer within {HOST_NOW_TIMEOUT:.0f}s" ) finally: _ = WAITING.pop(key, None) answer = answers[0] if answer["ok"]: return answer["value"] raise WorkError(answer["code"], answer["message"])
def attach_image(data: bytes) -> str: """Attach image bytes to the running cell; plugins reach this as api.attach_image.""" return _image_capture().attach(bytes(data))
def require_images() -> None: """Raise before costly work when the running cell cannot return images.""" _image_capture().accept_images()
def _image_capture() -> Capture: capture = CELL.get() # Spawned tasks inherit context even after their creating cell finishes. if capture is None or capture.kind != "cell" or capture.id not in ACTIVE_CAPTURES: raise RuntimeError( "images attach to a running cell; background work has no result to carry them" ) return capture
def show_image( source: bytes | bytearray | memoryview | str | os.PathLike[str], *sources: bytes | bytearray | memoryview | str | os.PathLike[str],) -> albedo_api.Text: """Show PNG/JPEG/WebP bytes or paths, several at once, after the cell finishes.
At most 4 images and 5 MiB attach per cell, within the model's edge limit. Overflow is saved to paths named in the result; a single image over 5 MiB raises. """ capture = _image_capture() results = [] for item in (source, *sources): if isinstance(item, (bytes, bytearray, memoryview)): data = bytes(item) elif isinstance(item, (str, os.PathLike)): data = pathlib.Path(item) else: raise TypeError( f"show_image takes image bytes or a path, not {type(item).__name__}" ) results.append(capture.attach(data)) return albedo_api.Text("\n".join(results))
def display( content: str, title: str = "", description: str = "",) -> albedo_api.Text: """Display text, code, or a diff directly to the user in the transcript, with an optional title and description, instead of repeating it in your reply.""" if not isinstance(content, str): raise TypeError(f"display content must be str, not {type(content).__name__}") if not isinstance(title, str): raise TypeError(f"display title must be str, not {type(title).__name__}") if not isinstance(description, str): raise TypeError( f"display description must be str, not {type(description).__name__}" ) capture = CELL.get() if capture is None or capture.kind != "cell" or capture.id not in ACTIVE_CAPTURES: raise RuntimeError( "display attaches to a running cell; background work has no trace to carry it" ) capture.trace.display(content, title=title, description=description) lines = len(content.splitlines()) if content else 0 unit = "line" if lines == 1 else "lines" return albedo_api.Text(f"displayed content to user ({lines} {unit})")
async def parallel(*items: object, return_exceptions: bool = False) -> list[object]: """Await several awaitables at once and return their results in order.
Pass job handles and calls together as they are created, or one iterable of them: `await parallel(run("a"), run("b"))`, `await parallel(files.find(...), files.find(...))`, `await parallel([job1, job2])`. Results come back in argument order; the first failure raises unless `return_exceptions=True`, which keeps the successes in their place.""" calls: list[Awaitable[object]] = [] for item in items: if inspect.isawaitable(item): calls.append(item) continue if isinstance(item, Iterable) and not isinstance(item, (str, bytes)): for part in item: if not inspect.isawaitable(part): raise TypeError( "parallel takes awaitables, not " f"{type(part).__name__} in an iterable" ) calls.append(part) continue raise TypeError( "parallel takes awaitables or an iterable of them, not " f"{type(item).__name__}" ) return list( await asyncio.gather( *(_awaited(call) for call in calls), return_exceptions=return_exceptions ) )
async def _awaited(item: Awaitable[object]) -> object: """Await one item from inside its own coroutine. asyncio.gather keys its arguments in a dict, so it needs them hashable; a handle like a remote reference compares by value and is not.""" return await item
async def no_reply(reason: str = "") -> None: """End this turn without a reply once this cell finishes, for a letter, notice or message that needs no answer. `reason` is yours alone; it is not sent anywhere.""" await host("cells.no_reply", {})
NATIVE = Capture("native", "native")NATIVE_LOCK = threading.RLock()NATIVE_FD = -1DEATH_FD: int | None = NoneSHUTTING_DOWN = False# Cells whose threads kept the kernel past its memory cap: a waiting caller's# result asks the owner to replace the kernel (stop_threads).HELD_PAST_CAP: set[str] = set()DECODER = codecs.getincrementaldecoder("utf-8")("replace")NATIVE_SINKS: dict[asyncio.Task[object], Capture] = {}ACTIVE_CAPTURES: set[str] = set()
def retained(id: str) -> Capture: capture = ARCHIVES.get(id) if capture is None: raise LookupError( f"no retained output for {id!r}: only the 16 most recent cells and 64 most recent jobs " f"keep output, so it may have rolled out; output.list() names what is kept, and a " f"background job keeps its own output on its handle: jobs[{id!r}].tail()" ) return capture
READ_WATCHERS: dict[str, Callable[[], None] | weakref.WeakMethod] = {}
def watch_output(id: str, notify: Callable[[], None]) -> None: """Notify reads while the output is retained, without owning a bound method's job."""
def expired(reference: weakref.WeakMethod) -> None: if READ_WATCHERS.get(id) is reference: READ_WATCHERS.pop(id, None)
try: READ_WATCHERS[id] = weakref.WeakMethod(notify, expired) except TypeError: # Functions and other callables need a strong reference to stay usable. READ_WATCHERS[id] = notify
class Output: async def read_shell( self, id: str, offset: int = 0, limit: int = 4000 ) -> albedo_api.Record: """Read this session's retained human shell output, without running a command.
Offsets count sanitized UTF-8 bytes. Follow next_offset until it is None; each page has text and next_offset and never splits a codepoint. """ if not isinstance(id, str) or not id: raise ValueError("id must identify a user shell command in this session") if type(offset) is not int or offset < 0: raise ValueError("offset must be a nonnegative byte offset") if type(limit) is not int or not 4 <= limit <= PREVIEW: raise ValueError(f"limit must be between 4 and {PREVIEW} bytes") page = await host( "user_shell_output.read", {"id": id, "offset": offset, "limit": limit} ) return albedo_api.Record(cast(dict[str, object], page))
def read(self, id: str, offset: int = 0, limit: int = 4000) -> albedo_api.Text: """Read retained output by cell or job id, at most 64 KiB per call. The 16 most recent cells and 64 most recent jobs keep up to 1 MiB each; page through it with offset.""" if limit > PREVIEW: raise ValueError( f"limit is at most {PREVIEW} per read; page through the rest with offset=" ) capture = retained(id) result = albedo_output.read_page(capture, offset, limit) notify = READ_WATCHERS.get(id) if isinstance(notify, weakref.WeakMethod): notify = notify() if notify is not None: try: notify() except Exception: pass # a plugin's bookkeeping must not fail the read return result
def list(self): """Every retained channel: cells, background jobs, and 'native'.
'native' holds bytes written to fd 1/2 while no cell was running; bytes a cell's subprocesses write land in that cell's own output instead. """ return albedo_api.ReadyList( {"id": c.id, "kind": c.kind, "bytes": c.seen, "retained": c.retained} for c in ARCHIVES.values() )
class Stream(io.TextIOBase): def writable(self) -> bool: return True
def write(self, text: str) -> int: with NATIVE_LOCK: # bytes already in the pipe were written first and stay first _ = drain() (CELL.get() or NATIVE).write(text) return len(text)
def flush(self) -> None: pass
def fileno(self) -> int: return 1
def drain() -> bool: """Fold whatever fd 1/2 already holds into the running cell; False once the pipe closes.
Subprocesses and C extensions cannot be attributed through contextvars, so they are credited to the cell that is running, the way a terminal does. Both the pump thread and Python-level writes drain, so the two surfaces interleave in the order the bytes were produced. """ with NATIVE_LOCK: while True: try: data = os.read(NATIVE_FD, 65536) except BlockingIOError: return True except OSError: return False if not data: return False text = DECODER.decode(data) if text: sinks = list(NATIVE_SINKS.values()) (sinks[0] if len(sinks) == 1 else NATIVE).write(text)
def native_output(fd: int) -> None: """Wake on output produced while no cell is writing.""" try: while select.select([fd], [], [])[0] and drain(): pass except OSError: return
def interrupt_after(caller: FrameType) -> None: """Raises KeyboardInterrupt in `caller` once the statement it runs has finished: at its next line, or as it returns. A trace that fires once, and then puts back whatever trace the cell had.""" previous = sys.gettrace()
def once(frame: FrameType, event: str, _arg: object) -> object: if frame is not caller: return None if event in ("line", "return"): caller.f_trace = None sys.settrace(previous) raise KeyboardInterrupt() return once
caller.f_trace = once sys.settrace(lambda *_: None)
def interrupt(_signal: int, _frame: FrameType | None) -> None: # A job's supervising task inherits the cell's context; the interrupt is # for the cell, which the queued cancellation reaches either way. if albedo_proc.SUPERVISING.get(): return capture = CELL.get() # Only while its code runs: a SIGINT that lands after evaluate returns # would escape execute_cell's cleanup and end the kernel. if ( capture is not None and capture is interrupt_capture and capture.id in ACTIVE_CAPTURES ): task = asyncio.current_task() # The queued cancellation already reached this cell. A delayed SIGINT # must not interrupt its cleanup, including the still-running job note. if task is not None and not task.cancelling(): cur = _frame while cur is not None: if cur.f_code is Namespace.__delitem__.__code__ and cur.f_back: # `del name` reports anything __delitem__ raises as a # NameError and drops it: let the delete finish. interrupt_after(cur.f_back) return if cur.f_code is Namespace.__setitem__.__code__: ns = cur.f_locals.get("self") key = cur.f_locals.get("key") if ( isinstance(ns, Namespace) and isinstance(key, str) and key not in ns.protected and "value" in cur.f_locals ): dict.__setitem__(ns, key, cur.f_locals["value"]) break cur = cur.f_back raise KeyboardInterrupt()
KERNEL_DIRS = { os.path.dirname(__file__) + os.sep, os.path.dirname(os.path.realpath(__file__)) + os.sep,}# Kernel frames a cell's code passes through without either raising there.PASSAGES = {os.path.realpath(__file__), os.path.realpath(albedo_memory.__file__)}CELL_FILE = re.compile(r"<albedo:[^>\"]*>")
def cell_traceback(error: BaseException) -> str: """`error`'s traceback for the cell's author: its own and library frames, plus the kernel frame that raised it, with the cell's file named `<cell>`.""" report = traceback.TracebackException.from_exception(error) pending: list[traceback.TracebackException | None] = [report] seen: list[traceback.TracebackException] = [] while pending: part = pending.pop() if part is None or any(part is done for done in seen): continue seen.append(part) frames = list(part.stack) kept = [ frame for frame in frames if not any(frame.filename.startswith(root) for root in KERNEL_DIRS) ] if ( frames and frames[-1] not in kept and os.path.realpath(frames[-1].filename) not in PASSAGES ): kept.append(frames[-1]) part.stack = traceback.StackSummary.from_list(kept) pending += [part.__cause__, part.__context__, *(part.exceptions or [])] return CELL_FILE.sub("<cell>", "".join(report.format()))
_COUNTER_SUFFIX = re.compile(r"\b([A-Za-z_]+)[0-9A-F]\b")_CORRUPTED_PREFIX = re.compile( r"^(?:n+|u32|u33|u4e|u00004e|(?:gpui)+)(?:[ ]{2,}\S|\}\s*$)")
def degenerate_reason(source: str) -> str | None: """Why an unstarted cell's source looks like token-stream corruption, or None.""" if "\x00" in source: return "null bytes in cell source" lines = [ _COUNTER_SUFFIX.sub(r"\1", line.strip()) for line in source.splitlines() if len(line.strip()) > 20 and not line.strip().startswith("#") ] run = 1 for prev, cur in zip(lines, lines[1:]): run = run + 1 if prev == cur else 1 if run >= 4: return "repeated-line generation loop" for idx in range(len(lines) - 5): if ( lines[idx] == lines[idx + 2] == lines[idx + 4] and lines[idx + 1] == lines[idx + 3] == lines[idx + 5] ): return "repeated-line generation loop" stray = sum( 1 for line in source.splitlines() if _CORRUPTED_PREFIX.match(line) is not None ) if stray >= 2: return "corrupted newline prefixes in multiline string" return None
def _raise_syntax(source: str, filename: str, node: ast.AST, message: str) -> None: lineno = getattr(node, "lineno", 1) col = getattr(node, "col_offset", 0) + 1 end_lineno = getattr(node, "end_lineno", lineno) end_col_offset = getattr(node, "end_col_offset", None) end_col = col if end_col_offset is None else end_col_offset + 1 lines = source.splitlines(keepends=True) line = lines[lineno - 1] if 1 <= lineno <= len(lines) else "" raise SyntaxError(message, (filename, lineno, col, line, end_lineno, end_col))
def _raise_tool( source: str, filename: str, node: ast.AST, name: str, deleting: bool = False) -> None: message = _cannot_delete_tool(name) if deleting else _cannot_assign_tool(name) _raise_syntax(source, filename, node, message)
def _open_call(call: ast.Call) -> tuple[ast.AST | None, ast.AST | None]: target: ast.AST | None = None mode: ast.AST | None = None if isinstance(call.func, ast.Name) and call.func.id == "open" and call.args: target = call.args[0] mode = call.args[1] if len(call.args) >= 2 else None elif ( isinstance(call.func, ast.Attribute) and call.func.attr == "open" and isinstance(call.func.value, ast.Name) and call.func.value.id == "io" and call.args ): target = call.args[0] mode = call.args[1] if len(call.args) >= 2 else None elif isinstance(call.func, ast.Attribute) and call.func.attr == "open": target = call.func.value mode = call.args[0] if call.args else None for kw in call.keywords: if kw.arg == "mode": mode = kw.value return target, mode
def _open_write_target(node: ast.AST) -> str | None: if not isinstance(node, ast.Call): return None target, mode = _open_call(node) if ( target is not None and isinstance(mode, ast.Constant) and isinstance(mode.value, str) and "w" in mode.value ): return ast.dump(target) return None
def _open_read_target(node: ast.AST) -> str | None: if not isinstance(node, ast.Call): return None if isinstance(node.func, ast.Attribute) and node.func.attr in ( "read_text", "read_bytes", ): return ast.dump(node.func.value) target, mode = _open_call(node) if target is not None and ( mode is None or ( isinstance(mode, ast.Constant) and isinstance(mode.value, str) and "r" in mode.value and "w" not in mode.value ) ): return ast.dump(target) return None
def _guard_truncate_before_read(source: str, tree: ast.Module, filename: str) -> None: for node in ast.walk(tree): if ( isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr in ("write", "writelines") ): target = _open_write_target(node.func.value) if target is None: continue for arg in [*node.args, *(kw.value for kw in node.keywords)]: if any( _open_read_target(sub) == target for sub in ast.walk(arg) if isinstance(sub, ast.Call) ): _raise_syntax( source, filename, node, "open(path, 'w') truncates the file before evaluating .write(...) arguments; " "read the file into a variable first, or use files.edit(path, old, new)", )
def _guard_tools(source: str, tree: ast.Module, filename: str) -> None: _guard_truncate_before_read(source, tree, filename) protected = NAMESPACE.protected if not protected: return
def walk_module(node: ast.AST) -> None: if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): if node.name in protected: _raise_tool(source, filename, node, node.name) for dec in node.decorator_list: walk_module(dec) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): for default in node.args.defaults + [ item for item in node.args.kw_defaults if item is not None ]: walk_module(default) else: for base in node.bases: walk_module(base) for keyword in node.keywords: walk_module(keyword.value) walk_nested(node) return if isinstance(node, ast.Lambda): for default in node.args.defaults + [ item for item in node.args.kw_defaults if item is not None ]: walk_module(default) walk_nested(node.body) return if isinstance( node, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp) ): for sub in ast.walk(node): if isinstance(sub, ast.NamedExpr) and sub.target.id in protected: _raise_tool(source, filename, sub.target, sub.target.id) return if isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)): if node.id in protected: _raise_tool( source, filename, node, node.id, isinstance(node.ctx, ast.Del) ) elif isinstance(node, ast.ExceptHandler): if node.name in protected: _raise_tool(source, filename, node, node.name) elif isinstance(node, (ast.MatchAs, ast.MatchStar)): if node.name in protected: _raise_tool(source, filename, node, node.name) elif isinstance(node, ast.MatchMapping): if node.rest in protected: _raise_tool(source, filename, node, node.rest) elif isinstance(node, ast.Import): for alias in node.names: bound = alias.asname or alias.name.split(".")[0] if bound in protected: _raise_tool(source, filename, alias, bound) elif isinstance(node, ast.ImportFrom): for alias in node.names: bound = alias.asname or alias.name if bound in protected and not ( node.module == "albedo" and bound == alias.name ): _raise_tool(source, filename, alias, bound) for child in ast.iter_child_nodes(node): walk_module(child)
def walk_nested(node: ast.AST) -> None: for sub in ast.walk(node): if isinstance(sub, ast.Global): for name in sub.names: if name in protected: _raise_tool(source, filename, sub, name)
for statement in tree.body: walk_module(statement)
def compile_cell( source: str, filename: str) -> tuple[CodeType, CodeType | None, ast.Module]: """Compile every part before running; return the unmodified tree for state capture.""" with warnings.catch_warnings(): # A regex in a plain string ("\d") runs fine; its SyntaxWarning would # only ride along in the result. warnings.simplefilter("ignore", SyntaxWarning) tree = ast.parse(source, filename=filename) _guard_tools(source, tree, filename) original = ast.Module(body=list(tree.body), type_ignores=tree.type_ignores) last = tree.body[-1] if tree.body else None trailing = None if isinstance(last, ast.Expr): _ = tree.body.pop() trailing = ast.Expression(last.value) prefix = cast( CodeType, compile(tree, filename, "exec", ast.PyCF_ALLOW_TOP_LEVEL_AWAIT) ) suffix = ( cast( CodeType, compile(trailing, filename, "eval", ast.PyCF_ALLOW_TOP_LEVEL_AWAIT), ) if trailing else None ) return prefix, suffix, original
def _bound_names(node: ast.AST) -> set[str]: names = { item.id for item in ast.walk(node) if isinstance(item, ast.Name) and isinstance(item.ctx, (ast.Store, ast.Del)) } for item in ast.walk(node): if isinstance(item, ast.ExceptHandler) and item.name: names.add(item.name) elif isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): names.add(item.name) return names
def _drop_definition(name: str) -> None: for key in list(DEFINITIONS): if key == name or key.startswith(name + "#"): DEFINITIONS.pop(key, None)
def _definition_changes( source: str, tree: ast.Module) -> list[tuple[ast.stmt, set[str], str | None, bool]]: changes: list[tuple[ast.stmt, set[str], str | None, bool]] = [] # Match Python source lines without splitting formfeeds or Unicode separators. lines = re.split(r"\r\n|\r|\n", source) previous_end = 0 for statement in tree.body: source_span = statement if ( isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and statement.decorator_list ): # A decorator expression may start after its @ on another line. # The preceding statement bounds the scan away from string contents. for index in range(previous_end, statement.lineno - 1): if lines[index].lstrip(" \t\f").startswith("@"): source_span = ast.copy_location(ast.Pass(), statement) source_span.lineno = index + 1 source_span.col_offset = 0 break previous_end = statement.end_lineno or statement.lineno names: set[str] = set() definition = isinstance( statement, ( ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Import, ast.ImportFrom, ), ) if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): names.add(statement.name) elif isinstance(statement, ast.Import): names.update( alias.asname or alias.name.split(".")[0] for alias in statement.names ) elif isinstance(statement, ast.ImportFrom): names.update( alias.asname or alias.name for alias in statement.names if alias.name != "*" ) else: names = _bound_names(statement) if names: changes.append( ( statement, names, ast.get_source_segment(source, source_span) if definition else None, isinstance(statement, ast.Import), ) ) return changes
def capture_definitions( source: str, tree: ast.Module, upto_line: int | None = None) -> None: for statement, names, segment, is_import in _definition_changes(source, tree): if ( upto_line is not None and (statement.end_lineno or statement.lineno) >= upto_line ): continue for name in names: # Plain dotted imports share their root binding and must accumulate. plain_dotted = ( is_import and any( alias.name.startswith(name + ".") and alias.asname is None for alias in statement.names ) if isinstance(statement, ast.Import) else False ) if not plain_dotted: _drop_definition(name) if segment is not None: key = next(iter(names), "definition") if ( is_import and isinstance(statement, ast.Import) and any( "." in alias.name and alias.asname is None for alias in statement.names ) ): while key in DEFINITIONS: key += "#2" elif key in DEFINITIONS: _drop_definition(key) # One source segment is replayed once; its imports bind every listed name. if segment not in DEFINITIONS.values(): DEFINITIONS[key] = segment
async def evaluate( source: str, cell_id: str, durable: bool = False, on_started: Callable[[], None] | None = None,) -> object: ACTIVE_CAPTURES.add(cell_id) try: prefix, suffix, tree = compile_cell(source, "<albedo:" + cell_id + ">") if durable: _ = await host("cells.started", {"id": cell_id}) if on_started is not None: on_started() # Only a trailing expression has a value; a cell with an await runs # as a coroutine, which is not one. value: object = None ran = cast(object, eval(prefix, NAMESPACE)) if inspect.isawaitable(ran): _ = await cast(Awaitable[object], ran) if suffix is not None: value = cast(object, eval(suffix, NAMESPACE)) if inspect.isawaitable(value) and not isinstance(value, tuple(HANDLES)): value = await cast(Awaitable[object], value) NAMESPACE["_"] = value capture_definitions(source, tree) return value except BaseException as error: filename = "<albedo:" + cell_id + ">" line = next( ( lineno for frame, lineno in traceback.walk_tb(error.__traceback__) if frame.f_code.co_filename == filename ), None, ) if "tree" in locals() and line is not None: capture_definitions(source, tree, line) if "prefix" not in locals(): setattr(error, "_albedo_unstarted", True) if not hasattr(error, "_albedo_cell_id"): setattr(error, "_albedo_cell_id", cell_id) raise finally: ACTIVE_CAPTURES.discard(cell_id)
class Cells: """Immutable saved source. Repairs never automatically repeat side effects."""
last_id: str | None = None
async def read( self, id: str, *, start_line: object = 1, end_line: object = None, limit: object = 8000, ) -> str: """Return source lines, capped at `limit` bytes. Narrow with start_line/end_line.""" if ( not isinstance(start_line, int) or start_line < 1 or ( end_line is not None and (not isinstance(end_line, int) or end_line < start_line) ) ): raise ValueError("expected positive inclusive line numbers") if not isinstance(limit, int) or limit < 1: raise ValueError("limit must be a positive byte count") cell_read(id) cell = cast(albedo_api.SavedCell, await host("cells.read", {"id": id})) lines = cell["source"].splitlines(keepends=True) data = "".join(lines[start_line - 1 : end_line]).encode( "utf-8", errors="replace" ) if len(data) <= limit: return data.decode("utf-8", errors="ignore") return data[:limit].decode("utf-8", errors="ignore") + ( f"\n[{limit} of {len(data)} bytes; the cell has {len(lines)} lines; " f"narrow with start_line/end_line or raise limit]" )
async def info(self, id: str) -> albedo_api.Record: """Status (ok, error, interrupted, started, saved, lost, unavailable), parentage, whether the cell started, and how long a finished cell ran, without its source.""" cell_read(id) cell = cast(albedo_api.SavedCell, await host("cells.read", {"id": id})) return albedo_api.Record( (key, value) for key, value in cell.items() if key != "source" )
async def cancel(self, id: str) -> bool: """Request cancellation of a running cell and suppress its completion wake.""" return cancel_cell(id, quiet=False)
async def list(self, limit: int = 20) -> albedo_api.ReadyList: """This session's cells, newest first: id, status, parent, and first line. Unlike output.list(), it reaches cells whose output has rolled out.""" cells = cast( list[dict[str, object]], await host("cells.list", {"limit": limit}) ) return albedo_api.ReadyList(albedo_api.Record(cell) for cell in cells)
async def trace(self, id: str) -> dict[str, object]: """What the cell read, ran and changed: activities plus diffs of files it wrote.
Diffs can be large; inspect the fields rather than printing the whole trace. """ cell_read(id) return cast(dict[str, object], await host("cells.trace", {"id": id}))
async def run( self, id: str, replacements: Iterable[Sequence[object]] = (), *, allow_partial: bool = False, check: bool = False, ) -> object: """Repair exact unique text and execute a new saved copy.
check=True compiles the rewrite and returns its compile error, or None when it compiles; nothing is saved and nothing runs. A cell that started needs allow_partial=True after inspecting its effects. Syntax/compile failures are safe to repair without that override. """ pairs = [tuple(pair) for pair in replacements] for pair in pairs: if len(pair) != 2 or not all(isinstance(s, str) for s in pair): raise ValueError("replacements must be (old, new) string pairs") if check: source = cast( str, await host("cells.draft", {"id": id, "replacements": pairs}) ) try: _ = compile_cell(source, "<albedo:" + id + ":check>") except (SyntaxError, ValueError) as error: return "".join( traceback.format_exception_only(type(error), error) ).strip() return None cell = cast( albedo_api.SavedCell, await host( "cells.prepare", {"id": id, "replacements": pairs, "allow_partial": allow_partial}, ), ) self.last_id = cell["id"] outer = CELL.get() capture = Capture( cell["id"], max_edge=None if outer is None else outer.max_edge, text_only=outer is not None and outer.text_only, ) remember(capture) capture.trace.snapshots = outer is not None and outer.trace.snapshots token = CELL.set(capture) outer_sink = swap_sink(capture) began = LOOP.time() value: object = None error: BaseException | None = None status = "ok" try: value = await evaluate(cell["source"], cell["id"], True) text = "" if value is None else show(value) except BaseException as failure: error = failure status = ( "interrupted" if isinstance( failure, ( KeyboardInterrupt, asyncio.CancelledError, albedo_memory.CellMemoryCap, ), ) else "error" ) capture.write(cell_traceback(failure)) text = "" finally: _ = drain() _ = swap_sink(outer_sink) CELL.reset(token) if outer is not None: outer.write( "[cell " + cell["id"] + "]\n" + capture.read(0, CELL_PREVIEW) ) for image in capture.images: try: _ = outer.attach(image) except ValueError as dropped: outer.write( f"[image from cell {cell['id']} dropped: {dropped}]\n" ) deliver_trace(capture) _ = await host( "cells.finish", { "id": cell["id"], "outcome": { "id": cell["id"], "status": status, "duration": round(LOOP.time() - began, 3), "output": capture.preview(status), "value": text, "truncated": capture.seen > CELL_PREVIEW, "images": capture.encoded_images(), }, }, ) capture.images.clear() if error is not None: raise error return value
INJECTED: set[str] = {"__name__", "__builtins__", "_"}
def swap_sink(capture: Capture | None) -> Capture | None: task = cast(asyncio.Task[object], asyncio.current_task()) with NATIVE_LOCK: previous = NATIVE_SINKS.pop(task, None) if capture is not None: NATIVE_SINKS[task] = capture return previous
def current_cell() -> str | None: capture = CELL.get() return capture.id if capture is not None else None
def background_capture(id: str) -> Capture: """A retained channel for a plugin's background work, addressable through `output`.""" capture = Capture(id, "job") remember(capture) return capture
def remember(capture: Capture) -> None: """Keep the newest captures of each kind, so a flood of jobs never evicts cell output.""" ARCHIVES[capture.id] = capture ARCHIVES.move_to_end(capture.id) counts = collections.Counter(held.kind for held in ARCHIVES.values()) for key, held in list(ARCHIVES.items()): if counts[held.kind] > LIMITS[held.kind] and key not in EXECUTING: forget_output(key) counts[held.kind] -= 1
def save_kernel(path: str) -> dict[str, object]: """Retained cell and job output, described by spill files, and the plugins' own state, so a kernel restored from `path` reads them as this one did. What could not be kept is named in "lost" for the restore to report.""" archives: list[dict[str, object]] = [] lost: list[str] = [] for capture in ARCHIVES.values(): if capture.kind in ("cell", "job", "native"): saved = capture.persist() if saved is None: lost.append(capture.id) else: archives.append(saved) plugins: dict[str, object] = {} for name, (save, _) in STATE_HOOKS.items(): try: plugins[name] = save(path) except albedo_api.PartialSave as partial: plugins[name] = partial.state lost.extend(f"{name}: {part}" for part in partial.lost) except Exception as error: # Lost like before it could be saved; the reason reaches the daemon. lost.append(f"{name}: {type(error).__name__}: {error}"[:200]) return { "archives": archives, "backgrounded": save_backgrounded_jobs(path), "plugins": plugins, "lost": lost, }
def restore_kernel(saved: object) -> list[str]: """Revive retained output and the plugins' state; returns what was lost: output the save could not keep or whose file is gone, and plugin state that would not save or restore.""" global NATIVE if not isinstance(saved, dict): return [] lost = list(cast(list[str], saved.get("lost", []))) captures: dict[str, Capture] = {} for entry in cast(list[dict[str, object]], saved.get("archives", [])): try: capture = Capture.revive(entry) if capture.spill is not None and not os.path.exists(capture.spill): raise FileNotFoundError(capture.spill) except OSError: lost.append(str(entry["id"])) continue captures[capture.id] = capture if capture.kind == "native": with NATIVE_LOCK: NATIVE = capture remember(capture) elif capture.id not in ARCHIVES: remember(capture) with BACKGROUNDED_LOCK: for e in cast(list[dict[str, object]], saved.get("backgrounded", [])): if (cid := str(e["id"])) in captures and cid not in BACKGROUNDED: BACKGROUNDED[cid] = {**e, "state": "exited", "capture": captures[cid]} plugins = cast(dict[str, object], saved.get("plugins", {})) for name, (_, restore) in STATE_HOOKS.items(): if name in plugins: try: restore(plugins[name], captures) except Exception as error: lost.append(f"{name}: {type(error).__name__}: {error}"[:200]) return lost
def snapshot(path: str) -> dict[str, object]: """Save the namespace to `path`, unless nothing changed since the last save there: an idle kernel kept for names it cannot save writes nothing.""" global SAVED if SAVED is not None and SAVED[:2] == (path, CHANGES) and file_id(path) == SAVED[2]: return SAVED[3] changes = CHANGES kernel = save_kernel(path) state = albedo_state.save_state(path, NAMESPACE, DEFINITIONS, INJECTED, kernel) state["output_lost"] = kernel["lost"] written = file_id(path) SAVED = ( None if "error" in state or written is None else (path, changes, written, state) ) return state
def file_id(path: str) -> tuple[int, int] | None: try: stat = os.stat(path) except OSError: return None return stat.st_mtime_ns, stat.st_size
def state_reply( message: albedo_api.State, state: dict[str, object] | None = None) -> dict[str, object]: if state is None: path = message["path"] state = ( snapshot(path) if message["type"] == "snapshot" else albedo_state.load_state(path, NAMESPACE, DEFINITIONS, restore_kernel) ) return { "type": "done", "id": message["id"], "status": "error" if "error" in state else "ok", "output": "", "value": "", "truncated": False, "state": state, }
MAX_RESULT_BYTES = ( 4 * 1024 * 1024) # one invoke reply ceiling, below the 8 MiB frame guard
def retain(value: object) -> str: """Keep one live object addressable by the owner; identity-stable, oldest rolls out.""" for key, held in LIVE.items(): if held is value: LIVE.move_to_end(key) return key key = secrets.token_hex(16) LIVE[key] = value LIVE.move_to_end(key) while len(LIVE) > LIVE_LIMIT: LIVE.popitem(last=False) capture = getattr(value, "capture", None) if isinstance(capture, Capture): _ = LOOP.create_task(_mirror(key, value, capture)) return key
def _mirror_state(obj: object) -> dict[str, object]: """One snapshot of a captured object: what the owner's tail() and poll() answer from.""" capture = cast(Capture, getattr(obj, "capture")) tail = capture.tail(MIRROR_TAIL) return { "job": getattr(obj, "id", None), "seen": capture.seen, "tail": tail.decode("utf-8", errors="ignore"), "tail_bytes": len(tail), "exit_code": getattr(obj, "exit_code", None), "timed_out": getattr(obj, "timed_out", False), "duration": getattr(obj, "duration", None), }
async def _mirror(key: str, obj: object, capture: Capture) -> None: """Stream one live reference's output tail, so the owner reads it without a round trip.
Frames are coalesced to the mirror interval; the final frame carries the completion state, and the pump ends once the object has settled and quieted. """ seen, quiet = -1, 0 while LIVE.get(key) is obj: await asyncio.sleep(MIRROR_INTERVAL) changed = capture.seen != seen if changed: seen, quiet = capture.seen, 0 else: quiet += 1 finished = getattr(obj, "exit_code", None) if changed or (finished is not None and quiet <= 1): send({"type": "mirror", "handle": key, **_mirror_state(obj)}) if finished is not None and quiet >= 3: return
def _invoke_reply( call_id: str, result: object, state: dict[str, object] | None = None) -> dict[str, object]: """One reference per result: inline the value when it can cross, retain it live.
Typed composites (dataclasses, list subclasses) get both, so the owner can read them as values and still call methods on the live remote object. Plain data crosses raw: its methods are pure and its state already crossed, so a remote call would be the same computation plus a network fee, and retaining it would evict live references worth keeping. """ try: wire = encode(result) encoded = json.dumps(wire, ensure_ascii=True) except (Unencodable, TypeError, ValueError, RecursionError): reply: dict[str, object] = { "type": "invoked", "id": call_id, "ok": True, "handle": retain(result), } if state is not None: reply["state"] = state return reply if len(encoded) > MAX_RESULT_BYTES: return { "type": "invoked", "id": call_id, "ok": False, "error": { "ename": "RemoteValueError", "evalue": f"result is {len(encoded)} bytes, over the " f"{MAX_RESULT_BYTES}-byte ceiling", "traceback": [], }, } typed = ( isinstance(result, list) and type(result) is not list or dataclasses.is_dataclass(result) and not isinstance(result, type) ) if typed: return { "type": "invoked", "id": call_id, "ok": True, "handle": retain(result), "value": wire, } if state is not None: return { "type": "invoked", "id": call_id, "ok": True, "handle": retain(result), "state": state, } return {"type": "invoked", "id": call_id, "ok": True, "value": wire}
async def _owner_args(value: object) -> object: """Resolve owner argument markers back to what the call expects.
`{"__ref__": id}` names a live reference and `{"pending": id}` a call whose result this argument uses, resolved in order like a pending target, so an argument raced ahead of its own reply still lands. `{"__bytes__": b64}` is byte data, the same marker a reply value uses, decoded by albedo_values. """ if isinstance(value, dict): if set(value) == {"__ref__"} and isinstance(value.get("__ref__"), str): obj = LIVE.get(value["__ref__"]) if obj is None: raise LookupError(f"live reference {value['__ref__']!r} is gone") return obj if set(value) == {"pending"} and isinstance(value.get("pending"), str): pending = value["pending"] future = PENDING_OBJECTS.get(pending) if future is None: raise LookupError(f"pending call {pending!r} is gone") ok, resolved = await cast(Awaitable[tuple[bool, object]], future) if not ok: raise cast(BaseException, resolved) return resolved if set(value) == {"__bytes__"} and isinstance(value.get("__bytes__"), str): return decode(value) return {key: await _owner_args(item) for key, item in value.items()} if isinstance(value, list): return [await _owner_args(item) for item in value] return value
def _resolve(name: str) -> object: """The callable a namespace-path invoke addresses; handles resolve before this.""" parts = name.split(".") if name else [] if not all(part.isidentifier() and not part.startswith("_") for part in parts): raise ValueError(f"unaddressable owner invoke: {name!r}") obj = NAMESPACE.get(parts[0]) if parts else None if obj is None: raise LookupError( "no remote binding " + repr(parts[0] if parts else name) + "; rem.tools() lists what exists" ) for part in parts[1:]: obj = getattr(obj, part) return obj
async def _target_object(target: object) -> object | None: """The object a target names: a live reference, a pending call's result, or nothing.
A `{"pending": id}` target waits for the call that produced the object, so method calls raced ahead of their own reply still resolve in order. """ if not isinstance(target, dict): return None key = target.get("handle") if isinstance(key, str): obj = LIVE.get(key) if obj is None: raise LookupError(f"live reference {key!r} is gone") return obj pending = target.get("pending") if isinstance(pending, str): future = PENDING_OBJECTS.get(pending) if future is None: raise LookupError(f"pending call {pending!r} is gone") ok, value = await cast(Awaitable[tuple[bool, object]], future) if not ok: raise cast(BaseException, value) return value return None
async def serve_invoke(message: albedo_api.Invoke) -> None: """One owner tool call: resolve, call, await by the cell rule, answer one reference.
The reply inlines the value when it can cross and otherwise retains the object as a live reference; `value` and `handle` are one concept. Awaitables run to completion unless their class is a registered handle, the same rule the local evaluator applies, so a tool's remote shape matches its local one. An explicit await of a live reference awaits it only when the object is awaitable (a job); otherwise the object is the answer, as a reference, so awaiting a call whose result is a plain live object (a spawned Browser) settles into that reference instead of raising. A job's reply carries its state, final when awaited, so the owner's poll() is never racy and the owner can match the job's wake to its reference before any mirror frame arrives. Every call's result object is retained briefly as a pending target for method calls that raced ahead of the reply. """ call_id = message["id"] OWNER_TASKS[call_id] = cast(asyncio.Task[object], asyncio.current_task()) future: asyncio.Future[tuple[bool, object]] = LOOP.create_future() PENDING_OBJECTS[call_id] = future PENDING_OBJECTS.move_to_end(call_id) while len(PENDING_OBJECTS) > LIVE_LIMIT: PENDING_OBJECTS.popitem(last=False) reply: dict[str, object] result: object = None state: dict[str, object] | None = None failure: BaseException | None = None try: async with OWNER_CALLS: base = await _target_object(message.get("target")) if message.get("await") is True: if base is None: raise ValueError("await needs a live or pending reference target") if inspect.isawaitable(base): result = await cast(Awaitable[object], base) else: # A settled object that cannot be awaited (a spawned # Browser) is the result itself; the reply retains it as # the same live reference, so nothing is orphaned. result = base else: name = message.get("name", "") if base is None: call = _resolve(name) else: parts = name.split(".") if name else [] if not all( part.isidentifier() and not part.startswith("_") for part in parts ): raise ValueError(f"unaddressable owner invoke: {name!r}") call = base for part in parts: call = getattr(call, part) args = [ await _owner_args(item) for item in cast(Sequence[object], message.get("args", ())) ] kwargs = { key: await _owner_args(item) for key, item in message.get("kwargs", {}).items() } if not callable(call): raise TypeError(f"owner invoke {name!r} is not callable") result = call(*args, **kwargs) if inspect.isawaitable(result) and not isinstance( result, tuple(HANDLES) ): result = await cast(Awaitable[object], result) # A call such as text() can see its job end, and the owner reads # exit_code from the mirror, so the job's state goes ahead of the reply. if isinstance(getattr(base, "capture", None), Capture): key = next( (key for key, held in LIVE.items() if held is base), None ) if key is not None: send({"type": "mirror", "handle": key, **_mirror_state(base)}) if isinstance(getattr(result, "capture", None), Capture): state = _mirror_state(result) except asyncio.CancelledError as error: failure = error # The owner cancelled its wait; the remote effect may continue, and the # live reference (a running job, for instance) stays addressable. reply = { "type": "invoked", "id": call_id, "ok": False, "cancelled": True, "error": { "ename": "CancelledError", "evalue": "the owner cancelled this wait; the remote effect " "may continue and its reference stays addressable", "traceback": [], }, } except BaseException as error: failure = error reply = { "type": "invoked", "id": call_id, "ok": False, "error": { "ename": type(error).__name__, "evalue": str(error)[:8192], "traceback": traceback.format_exc().splitlines()[-8:], }, } else: reply = _invoke_reply(call_id, result, state) finally: OWNER_TASKS.pop(call_id, None) if not future.done(): future.set_result( (failure is None, failure if failure is not None else result) ) send(reply)
def cancel_cell(id: str, *, quiet: bool = False) -> bool: task = CELL_TASKS.get(id) if task is None or task.done(): cell_read(id) return False READ_CELLS.add(id) CELL_CAPTURES[id].interruption = "cancelled" if not quiet: running = [job for named in CELL_JOBS for job in named(id)] if running: listed = "; ".join(f"{job} ({command[:200]})" for job, command in running) print( f"[cell {id} started jobs that the cancel leaves running, each " f"waking the session when it ends: {listed}. stop one through its " "handle (await job.stop()), or a local one with await jobs[id].stop()]" ) if task is asyncio.current_task(): # task.cancel() would land only once the cell returns, ending the # task cancelled instead of interrupted, and serve() with it. raise asyncio.CancelledError() return task.cancel()
async def serve_job_stop(job_id: str) -> None: """Stop a background job or backgrounded cell on behalf of the port owner.""" with BACKGROUNDED_LOCK: known = job_id in BACKGROUNDED if known: ok = cancel_cell(job_id, quiet=True) err = {} if ok else {"error": "cell already finished"} send({"type": "job_stop", "id": job_id, "ok": ok, **err}) return answer: dict[str, object] = { "type": "job_stop", "id": job_id, "ok": False, "error": "job not found", "code": "not_found", } for handler in reversed(STOP_HANDLERS): try: res = await handler(job_id) if res is not None: answer = {"type": "job_stop", "id": job_id, **res} break except Exception as error: answer = { "type": "job_stop", "id": job_id, "ok": False, "error": str(error).lower() or "could not stop job", } break send(answer)
def cell_job_record(entry: dict[str, object]) -> dict[str, object]: return {k: v for k, v in entry.items() if k != "capture"} | { "bytes": cast(Capture, entry["capture"]).seen }
def live_background_cells() -> list[dict[str, object]]: with BACKGROUNDED_LOCK: return [ {k: e[k] for k in ("id", "command", "started_at")} for e in BACKGROUNDED.values() if e["state"] == "running" ]
def record_backgrounded(capture: Capture, code: str, started_at: int) -> None: title = next( (s.lstrip("#").strip()[:120] for r in code.splitlines() if (s := r.strip())), "", ) with BACKGROUNDED_LOCK: if capture.id in BACKGROUNDED: return BACKGROUNDED[capture.id] = { "id": capture.id, "command": title or "python cell", "state": "running", "exit_code": None, "timed_out": False, "service": False, "kind": "cell", "parent_id": None, "started_at": started_at, "ended_at": None, "capture": capture, } for k, v in list(BACKGROUNDED.items()): if len(BACKGROUNDED) > LIMITS["cell"] and v["state"] != "running": BACKGROUNDED.pop(k, None)
def normalize_job_record(r: dict[str, object]) -> dict[str, object]: pid = r.get("parent_id") if r.get("kind", "command") == "command" and isinstance(pid, str): with BACKGROUNDED_LOCK: p = BACKGROUNDED.get(pid) keep = p is not None and ( r.get("state") == "exited" or p["state"] == "running" ) if not keep: r["parent_id"] = None return r
async def view_background_cells(msg: dict[str, object]) -> dict[str, object] | None: with BACKGROUNDED_LOCK: if msg["type"] == "job_list": entries = list(BACKGROUNDED.values()) return {"ok": True, "jobs": [cell_job_record(e) for e in reversed(entries)]} e = BACKGROUNDED.get(cast(str, msg["job"])) if e is None: return None s, n, t = albedo_output.read_window( cast(Capture, e["capture"]), cast("int | None", msg.get("offset")), cast(int, msg["limit"]), e["state"] != "running", ) return { "ok": True, "job": cell_job_record(e), "offset": s, "next_offset": n, "text": t, }
def save_backgrounded_jobs(path: str) -> list[dict[str, object]]: with BACKGROUNDED_LOCK: entries = [dict(e) for e in BACKGROUNDED.values() if e["state"] != "running"] saved, jobs = [], [] for e in entries: if p := cast(Capture, e["capture"]).persist(): rec, tail = cell_job_record(e), p.get("tail") saved.append(rec) jobs.append( { **rec, "spill": p["spill"], "spilled": p["spilled"], "tail": base64.b64encode(tail).decode() if isinstance(tail, bytes) else None, } ) sidecar, seen = path + ".jobs.json", {str(r["id"]) for r in jobs} with contextlib.suppress(OSError, ValueError): with open(sidecar) as f: raw = json.load(f) if isinstance(raw, dict) and isinstance(raw.get("jobs"), list): jobs += [ normalize_job_record(dict(i)) for i in raw["jobs"] if isinstance(i, dict) and str(i.get("id")) not in seen ] if jobs: jobs.sort(key=lambda r: cast(int, r.get("started_at", 0)), reverse=True) os.makedirs(os.path.dirname(sidecar) or ".", exist_ok=True) fd, tmp = tempfile.mkstemp(dir=os.path.dirname(sidecar) or ".", prefix=".jobs.") try: with os.fdopen(fd, "w") as f: json.dump({"jobs": jobs[:100]}, f) os.replace(tmp, sidecar) except BaseException: with contextlib.suppress(OSError): os.unlink(tmp) raise return saved
async def serve_job_view(message: dict[str, object]) -> None: """Answer a `job_list` or `job_read` for the port owner: each plugin that runs jobs lists its own, and the first to know a job's id reads it.""" listing = message["type"] == "job_list" jobs: list[dict[str, object]] = [] answer: dict[str, object] = ( {"ok": True} if listing else {"ok": False, "code": "not_found", "error": "job not found"} ) for handler in (view_background_cells, *reversed(JOB_VIEWS)): try: res = await handler(message) except ValueError as error: answer = {"ok": False, "code": "invalid", "error": str(error)} break except LookupError as error: answer = {"ok": False, "code": "lost", "error": str(error)} break except Exception as error: answer = {"ok": False, "code": "failed", "error": str(error).lower()} break if res is None: continue if not listing: res["job"] = normalize_job_record(cast(dict[str, object], res["job"])) answer = res break jobs.extend(cast(list[dict[str, object]], res["jobs"])) if listing and answer["ok"]: answer["jobs"] = sorted( (normalize_job_record(dict(i)) for i in jobs), key=lambda i: ( i.get("state") != "running", i.get("kind") != "cell", -cast(int, i["started_at"]), ), )[:100] send({**answer, "type": message["type"], "id": message["id"]})
def called_bindings(source: str) -> list[str]: """The injected bindings a cell's code calls, as dotted names such as `files.find` or `run`, sorted; the loop compares them across steps.""" try: tree = ast.parse(source) except (SyntaxError, ValueError): return ["syntax_error"] names: set[str] = set() for node in ast.walk(tree): if not isinstance(node, ast.Call): continue parts: list[str] = [] target = node.func while isinstance(target, ast.Attribute): parts.append(target.attr) target = target.value if ( isinstance(target, ast.Name) and (target.id in INJECTED or target.id == "open") and not target.id.startswith("_") ): names.add(".".join([target.id, *reversed(parts)][:3])) return sorted(names)[:64]
def deliver_trace(capture: Capture, source: str | None = None) -> None: payload = capture.trace.finish() if source is not None: payload["calls"] = called_bindings(source) send({"type": "trace", "id": capture.id, "trace": payload}) capture.trace.release()
def cell_read(id: str) -> None: task = CELL_TASKS.get(id) if id in BACKGROUND_RESULTS or (task is not None and task.done()): READ_CELLS.add(id) BACKGROUND_RESULTS.pop(id, None) if id in NOTICED: NOTICED.discard(id) CELL_NOTICES.poke()
def first_line(code: str) -> str: """The cell's first line that is not blank or a comment, for one-line displays.""" for line in code.splitlines(): line = line.strip() if line and not line.startswith("#"): return line[:200] return "python cell"
def unjournaled(result: dict[str, object]) -> str: return "" if result.get("journaled", True) else ", result not journaled"
async def announce_cells() -> None: while BACKGROUND_RESULTS: batch = dict(BACKGROUND_RESULTS) display = "\n".join( f"cell finished (status={result['status']}{unjournaled(result)}, ran {result['duration']}s): {result['summary']}" for result in batch.values() ) listed = "; ".join( f"{id}: status={result['status']}{unjournaled(result)}, ran {result['duration']}s" for id, result in batch.items() ) text = ( "<system-note>background python cells finished: " + listed + ". output.read(id) reads the output and await cells.info(id) reads " f"the status; {albedo_notices.IDLE}</system-note>" ) posted: str | None = albedo_notices.key() while True: try: await host( "cells.completed", {"key": posted, "display": display, "text": text}, ) break except Exception as error: # The daemon may have stored it before the call broke off; the # same key stores it once. if getattr(error, "code", "") == "unknown": await asyncio.sleep(2) continue for id in batch: capture = ARCHIVES.get(id) if capture is not None: capture.write(f"\n[completion notice not delivered: {error}]\n") posted = None break # A cell read while the notice was being stored left these already. unread = [id for id in batch if id in BACKGROUND_RESULTS] for id in batch: BACKGROUND_RESULTS.pop(id, None) if posted is not None: NOTICED.update(unread) CELL_NOTICES.watch( host, posted, lambda batch=list(batch): not NOTICED.intersection(batch) ) if len(unread) < len(batch): CELL_NOTICES.poke()
async def stop_threads() -> bool: """Stops the threads still running cell code before a cell the memory cap interrupted reports, so the next cell does not start while they grow. With the kernel back under its cap, one still running past STOP_WAIT is left to the guard. True when some still run RESTART_AFTER on with the kernel past its cap: the stop cannot reach them (blocked in a C call, or catching BaseException), so the kernel must restart.""" began = LOOP.time() while albedo_memory.stop_cell_threads(): waited = LOOP.time() - began if waited >= albedo_memory.STOP_WAIT and not over_cap(): return False if waited >= albedo_memory.RESTART_AFTER: return True # The interrupt's queued cancellation lands here when its SIGINT # already ended a synchronous cell: the wait goes on. with contextlib.suppress(asyncio.CancelledError): await asyncio.sleep(albedo_memory.INTERVAL / 5) return False
def over_cap() -> bool: return (albedo_memory.footprint() or 0) > albedo_memory.LIMIT
RESTARTING = ( "so the kernel is restarting: albedo ends it and its jobs, and the next cell" " starts a fresh kernel that restores the variables last saved to disk; check" " side effects before rerunning anything.")# A backgrounded cell's result reaches no caller the owner could hold it for.STAYING = ( "and nothing can replace the kernel from a backgrounded cell: /kernel restart," " which the user runs, replaces it now, and a session recycles a kernel past" " its cap when it rests.")
def held_note(outcome: str) -> str: return ( f"\n[threads this cell started still ran {albedo_memory.RESTART_AFTER:g} s" " after the cap interrupted it (blocked in a C call, or catching" f" BaseException) and keep the kernel past its cap, {outcome}]\n" )
async def execute_cell( message: albedo_api.Execute, capture: Capture, on_started: Callable[[], None] | None = None,) -> dict[str, object]: token = CELL.set(capture) status, value, failed = "ok", "", None stuck = False tail = contextlib.ExitStack() began = LOOP.time() _ = swap_sink(capture) try: if capture.interruption: raise asyncio.CancelledError() result = await evaluate( message["code"], capture.id, message.get("durable", False), on_started ) if result is not None: value = show(result) except (KeyboardInterrupt, asyncio.CancelledError, albedo_memory.CellMemoryCap): status = "interrupted" if capture.interruption == "deadline": capture.write("\n[cell deadline exceeded; execution interrupted]\n") elif capture.interruption == "memory": stuck = await stop_threads() used = albedo_memory.footprint() or 0 capture.write( f"\n[kernel memory passed its cap: {albedo_memory.mebibytes(used)} held," f" cap {albedo_memory.mebibytes(albedo_memory.LIMIT)}; execution interrupted." " The namespace is kept: del large variables, gc.collect(), or work in smaller pieces.]\n" ) except BaseException as error: status = "error" failed = getattr(error, "_albedo_cell_id", capture.id) if isinstance(error, MemoryError): # The kernel must still be able to report: room above the limit # until the result is built. _ = tail.enter_context(albedo_memory.headroom()) capture.write(cell_traceback(error)) if getattr(error, "_albedo_unstarted", False): reason = degenerate_reason(message["code"]) if reason is not None: capture.write( f"\n[albedo: this cell failed to compile before any code ran, so no files or " f"variables were changed. The cell source contains corrupted output ({reason}). " "Do not repair this cell in place or patch string literals with regexes inside " "the cell; write a new, short cell (<40 lines) using files.write(path, content) " "or files.edit(path, old, new).]\n" ) finally: _ = drain() _ = swap_sink(None) CELL.reset(token) try: # The cell's code has finished; what follows is optional bookkeeping, and # its failure (even an interrupt arriving now) must not replace the # cell's status or end the kernel. try: moved = albedo_spill.relieve(NAMESPACE, INJECTED) except BaseException as error: moved = ( f"[large values were not moved to disk: {fault_description(error)}]\n" ) if moved: capture.write("\n" + moved) if stuck and over_cap() and albedo_memory.stop_cell_threads(): HELD_PAST_CAP.add(capture.id) try: deliver_trace(capture, message["code"]) except BaseException as error: capture.write( f"\n[file-change trace not delivered: {fault_description(error)}]\n" ) # A notice this cell made old news is withdrawn before its result goes. await albedo_notices.settle() result = { "type": "done", "id": capture.id, "status": status, "duration": round(LOOP.time() - began, 3), "output": capture.preview(status) + capture.spill_note(), "value": value, "truncated": capture.seen > CELL_PREVIEW, "images": capture.encoded_images(), "failed": failed, } tail.close() return result except BaseException as error: return failed_outcome(capture, error)
async def finish_background( message: albedo_api.Execute, task: asyncio.Task[dict[str, object]]) -> None: global CELL_ANNOUNCER _ = await asyncio.wait({task}) capture = ARCHIVES[message["id"]] done = cell_outcome(task, capture) try: if done["value"]: capture.write("\n[result]\n" + str(done["value"]) + "\n") reread_output(done, capture) if message["id"] in HELD_PAST_CAP: HELD_PAST_CAP.discard(message["id"]) capture.write(held_note(STAYING)) reread_output(done, capture) except BaseException as error: done["output"] = str(done.get("output", "")) + ( "\n[background result formatting failed: " + fault_description(error) + "]\n" ) # Commit before the wake, so cells.info/read see the terminal outcome. journaled = True if message.get("durable", False): failure = await journal_result(message["id"], done) if failure is not None: journaled = False warning = ( f"\n[cell result could not be journaled: {failure}. Its durable " "outcome is unconfirmed; this result lives only in this kernel, " "so a kernel restart may lose it]\n" ) try: capture.write(warning) reread_output(done, capture) except BaseException as error: done["output"] = str(done.get("output", "")) + ( "\n[background result formatting failed: " + fault_description(error) + "]\n" ) if warning not in str(done["output"]): done["output"] = str(done["output"]) + warning else: send(done) retain_cell_result(message["id"], done) if message["id"] in READ_CELLS: READ_CELLS.discard(message["id"]) return BACKGROUND_RESULTS[message["id"]] = { **done, "summary": first_line(message["code"]), "journaled": journaled, } if CELL_ANNOUNCER is None or CELL_ANNOUNCER.done(): CELL_ANNOUNCER = LOOP.create_task(announce_cells())
async def journal_result(id: str, done: dict[str, object]) -> str | None: """Record a durable cell's result through `cells.finish`: None once the journal holds an outcome for the cell, this one or one recorded earlier, else why it does not. A call the daemon restarted under may or may not have committed, so it is sent once more, which commits or finds it did.""" retried = False while True: try: _ = await host("cells.finish", {"id": id, "outcome": done}) return None except WorkError as error: if error.code == "finished": return None if error.code != "unknown" or retried: return str(error) retried = True except Exception as error: return str(error)
def reread_output(done: dict[str, object], capture: Capture) -> None: """Refresh a finished result's output after more was written to its capture.""" done["output"] = capture.preview(str(done["status"])) + capture.spill_note() done["truncated"] = capture.seen > CELL_PREVIEW
def link_resources() -> tuple[set[threading.Thread], set[int]]: if isinstance(LINK, albedo_link.SocketLink): return LINK.resources() return set(), set()
RECHECK: asyncio.TimerHandle | None = None
def recheck_work() -> None: global RECHECK RECHECK = None publish_work()
def publish_work() -> None: global LAST_WORK, RECHECK quiet = QUIESCENCE is not None and QUIESCENCE.ready() bg_cells = live_background_cells() bg_key = tuple( (str(e["id"]), str(e["command"]), int(cast(int, e["started_at"]))) for e in bg_cells ) observation = (len(CELL_TASKS), quiet, albedo_memory.bloated(), bg_key) if not quiet and not CELL_TASKS and RECHECK is None: # A finishing cell's own task and timer thread are still unwinding; # sample again soon instead of waiting for the periodic refresh. RECHECK = LOOP.call_later(0.05, recheck_work) if observation != LAST_WORK: LAST_WORK = observation send( { "type": "cells", "live": observation[0], "background_cells": bg_cells, "quiescent": quiet, "bloated": observation[2], } )
def refresh_work() -> None: publish_work() LOOP.call_later(1.0, refresh_work)
def cell_outcome( task: asyncio.Task[dict[str, object]], capture: Capture) -> dict[str, object]: """The finished cell task's done frame. A task that raised anyway still ends its cell, as an error naming the fault, so the cell's bookkeeping clears and the kernel goes on serving.""" try: return task.result() except BaseException as error: return failed_outcome(capture, error)
def fault_description(error: BaseException) -> str: try: return repr(error) except BaseException: return "unprintable finalization error"
def failed_outcome(capture: Capture, error: BaseException) -> dict[str, object]: started = CELL_STARTS.get(capture.id) return { "type": "done", "id": capture.id, "status": "error", "duration": round(time.monotonic() - started[1], 3) if started else 0.0, "output": f"[the kernel could not finish cell {capture.id}: {fault_description(error)};" f" output.read({capture.id!r}) reads what it printed]\n", "value": "", "truncated": False, "images": [], "failed": capture.id, }
def retain_cell_result(id: str, done: dict[str, object]) -> None: FINISHED[id] = done _ = CLAIMS.pop(id, None) while len(FINISHED) > FINISHED_LIMIT: old, _ = FINISHED.popitem(last=False) BACKGROUND_RESULTS.pop(old, None) READ_CELLS.discard(old) budget = FINISHED_IMAGE_BYTES for result in reversed(FINISHED.values()): images = cast(list[str], result.get("images", [])) budget -= sum(map(len, images)) if budget < 0 and images: result["images"] = [] result["output"] = ( f"{result['output']}\n[{len(images)} image(s) not kept for a replayed result]" ) EXECUTING.discard(id) CELL_TASKS.pop(id, None) CELL_CAPTURES.pop(id, None) CELL_STARTS.pop(id, None) capture = ARCHIVES.get(id) if capture is not None: capture.end_spill() capture.images.clear() remember(capture) with BACKGROUNDED_LOCK: if (entry := BACKGROUNDED.get(id)) and entry["state"] == "running": status = done.get("status") entry.update( state="exited", ended_at=int(time.time() * 1000), timed_out=capture is not None and capture.interruption == "deadline", exit_code=0 if status == "ok" else (None if status == "interrupted" else 1), ) publish_work()
def cell_timers( capture: Capture, code: str, task: asyncio.Task[dict[str, object]], timeout_ms: int,) -> tuple[ threading.Event, threading.Event, threading.Lock, asyncio.Future[None], albedo_alarms.Alarm, Callable[[], None],]: began, started_wall = time.monotonic(), int(time.time() * 1000) detached = threading.Event() settled = threading.Event() response_lock = threading.Lock() released: asyncio.Future[None] = LOOP.create_future()
def background() -> None: with response_lock: if settled.is_set() or task.done() or detached.is_set(): return detached.set() record_backgrounded(capture, code, started_wall) send(background_reply(capture)) LOOP.call_soon_threadsafe(publish_work) LOOP.call_soon_threadsafe(released.set_result, None)
def claim() -> dict[str, object]: """The cell's done frame for a daemon that lost its call; one still running goes on in the background, as if past BACKGROUND_SECONDS.""" ran = time.monotonic() - began with response_lock: if detached.is_set(): return background_reply(capture, ran) if settled.is_set() or task.done(): return cell_outcome(task, capture) detached.set() record_backgrounded(capture, code, started_wall) LOOP.call_soon_threadsafe(publish_work) LOOP.call_soon_threadsafe(released.set_result, None) return background_reply(capture, ran)
CLAIMS[capture.id] = claim
# Alarms also fire while synchronous cell code occupies the asyncio loop. background_timer = albedo_alarms.Alarm(background) deadline_timer = albedo_alarms.deadlines.after( timeout_ms / 1000, lambda: receive({"type": "interrupt", "id": capture.id, "reason": "deadline"}), ) task.add_done_callback(lambda _: deadline_timer.cancel())
def start_background() -> None: with response_lock: if not settled.is_set() and not task.done(): _ = albedo_alarms.backgrounds.arm(background_timer, BACKGROUND_SECONDS)
return ( detached, settled, response_lock, released, background_timer, start_background, )
async def serve(): while True: message = await QUEUE.get() if message["type"] != "execute": send(state_reply(message)) continue capture = Capture( message["id"], max_edge=message.get("max_edge"), text_only=message.get("text_only", False), ) capture.trace.snapshots = message.get("snapshots", False) capture.interruption = "" remember(capture) interrupted = INTERRUPTS.pop(capture.id, None) if len(CELL_TASKS) >= LIMITS["cell"]: done: dict[str, object] = { "type": "done", "id": capture.id, "status": "error", "duration": 0, "output": "16 cells are still running; cancel an unused cell with await cells.cancel(id), or end your turn and wait for completion.", "value": "", "truncated": False, "images": [], } retain_cell_result(capture.id, done) send(done) continue arm_background: Callable[[], None] | None = None task = LOOP.create_task( execute_cell( message, capture, lambda: arm_background() if arm_background is not None else None, ) ) CELL_TASKS[capture.id] = task CELL_CAPTURES[capture.id] = capture CELL_STARTS[capture.id] = (albedo_memory.footprint() or 0, time.monotonic()) publish_work() if interrupted is not None: capture.interruption = interrupted ( detached, settled, response_lock, released, background_timer, arm_background, ) = cell_timers( capture, message["code"], task, message.get("timeout_ms", 300_000) ) _ = await asyncio.wait({task, released}, return_when=asyncio.FIRST_COMPLETED) with response_lock: settled.set() background_timer.cancel() is_background = detached.is_set() if is_background: watch_output(capture.id, lambda id=capture.id: cell_read(id)) _ = LOOP.create_task(finish_background(message, task)) else: done = cell_outcome(task, capture) if capture.id in HELD_PAST_CAP: # The owner ends this kernel before the caller hears the result. capture.write(held_note(RESTARTING)) reread_output(done, capture) done["restart"] = True retain_cell_result(capture.id, done) READ_CELLS.discard(capture.id) send(done)
def background_reply( capture: Capture, ran: float = BACKGROUND_SECONDS) -> dict[str, object]: return { "type": "done", "id": capture.id, "status": "backgrounded", "duration": round(ran, 3), "output": capture.preview("ok") + capture.spill_note() + ( f"\n[cell {capture.id} is still running in the background. " "the session will wake automatically when it finishes; give the user a " "short status report and end your turn instead of polling or sleeping, " "or do other work without changing variables this cell uses.]\n" ), "value": "", "truncated": capture.seen > CELL_PREVIEW, "images": capture.encoded_images(), }
def flush(timeout: float) -> None: """Give the owner a moment to attach and take what we sent, before a detached kernel that failed to start leaves.""" if isinstance(LINK, albedo_link.SocketLink): deadline = time.monotonic() + timeout while time.monotonic() < deadline and ( not LINK.attached() or LINK.outbox.entries ): time.sleep(0.02)
def open_link(argv: list[str]) -> list[str]: """Stdio for `kernel.py <modules>`; a socket for `kernel.py --run <dir> <modules>`, whose bridge writes the attach token on our stdin. Returns the module list.""" global LINK, RUN_DIR if argv[1:2] != ["--run"]: LINK = albedo_link.StdioLink() return cast(list[str], json.loads(argv[1])) RUN_DIR = argv[2] token = sys.stdin.buffer.readline().decode().strip() LINK = albedo_link.SocketLink( RUN_DIR, token, hello, bundle=albedo_bundle.digest(), grace=FIRST_ATTACH_GRACE, ) return cast(list[str], json.loads(argv[3]))
PRELOADED = ( "asyncio base64 collections datetime functools hashlib itertools json math os re shutil sys textwrap time").split()
def session_builtins(bindings: dict[str, object]) -> dict[str, object]: """Python's builtins plus the common standard-library modules and the injected bindings. Standard-library modules may be shadowed and `del` reveals them again; injected tool bindings are locked in cell globals.""" modules = {name: importlib.import_module(name) for name in PRELOADED} return vars(builtins) | modules | {"Path": pathlib.Path} | bindings
class Bindings(ModuleType): """`import albedo` and `from albedo import files` answer the injected bindings, for code written as if they were a library."""
def __init__(self, bindings: dict[str, object]) -> None: super().__init__("albedo", "The tool bindings every cell already has.") self.bindings = bindings
def __getattr__(self, name: str) -> object: try: return self.bindings[name] except KeyError: raise AttributeError(f"albedo has no binding {name!r}") from None
def __dir__(self) -> list[str]: return sorted(self.bindings)
class CellMain(ModuleType): """`sys.modules['__main__']` over the cell namespace, so `import __main__` and `pickle` resolve cell definitions instead of the harness module."""
@property def __dict__(self) -> dict[str, object]: # type: ignore[override] return NAMESPACE
def __getattr__(self, name: str) -> object: try: return NAMESPACE[name] except KeyError: raise AttributeError( f"module '__main__' has no attribute {name!r}" ) from None
def __setattr__(self, name: str, value: object) -> None: NAMESPACE[name] = value
def __delattr__(self, name: str) -> None: try: del NAMESPACE[name] except KeyError: raise AttributeError( f"module '__main__' has no attribute {name!r}" ) from None
def __dir__(self) -> list[str]: return sorted(NAMESPACE)
def main(): global DEATH_FD, NATIVE_FD, QUIESCENCE if os.getpgrp() != os.getpid(): os.setsid() modules = open_link(sys.argv) # Beside the run directories: $ALBEDO_HOME/output, ~/.albedo-remote/output. # A shared /tmp directory another user created would refuse every spill. albedo_capture.prune_spills( os.path.join(os.path.dirname(os.path.dirname(RUN_DIR)), "output") if RUN_DIR is not None else os.path.join(os.path.expanduser("~"), ".albedo-remote", "output") if os.environ.get("ALBEDO_REMOTE_TARGET") else os.path.join(tempfile.gettempdir(), "albedo-output") ) _ = os.dup2(os.open(os.devnull, os.O_RDONLY), 0) read_fd, write_fd = os.pipe() _ = os.dup2(write_fd, 1) _ = os.dup2(write_fd, 2) os.close(write_fd) os.set_blocking(read_fd, False) NATIVE_FD = read_fd remember(NATIVE) sys.stdin = open(os.devnull) sys.stdout = sys.stderr = Stream() threading.Thread(target=native_output, args=(read_fd,), daemon=True).start() threading.Thread(target=reader, daemon=True).start() if RUN_DIR is not None: threading.Thread(target=watch, daemon=True).start() threading.Thread(target=guard_memory, daemon=True).start() albedo_alarms.start() if RUN_DIR is not None: with contextlib.suppress(OSError): DEATH_FD = os.open( os.path.join(RUN_DIR, "kernel.log"), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600, ) faulthandler.enable(DEATH_FD) _ = albedo_memory.install() _ = signal.signal(signal.SIGINT, interrupt) _ = signal.signal(signal.SIGTERM, fatal_signal) _ = signal.signal(signal.SIGHUP, fatal_signal) albedo_shell.install() # refusals precede observational audit hooks albedo_trace.install(CELL.get) api = albedo_api.PythonApi( version=2, loop=LOOP, host=host, host_now=host_now, HostError=WorkError, forget_output=forget_output, capture=background_capture, preview=PREVIEW, send=send, on_shutdown=CLEANUP.append, background_handle=HANDLES.append, modules=modules, watch_output=watch_output, attach_image=attach_image, require_images=require_images, on_stop_job=STOP_HANDLERS.append, cell=current_cell, on_cell_jobs=CELL_JOBS.append, on_job_view=JOB_VIEWS.append, owns_resources=RESOURCE_OWNERS.append, on_state=lambda name, save, restore: STATE_HOOKS.update( {name: (save, restore)} ), ) NAMESPACE.update( cells=Cells(), output=Output(), show_image=show_image, display=display, parallel=parallel, no_reply=no_reply, ) try: LOOP.run_until_complete(albedo_api.load_plugins(modules, api, NAMESPACE)) except Exception as error: send({"type": "startup_error", "message": str(error)}) flush(5.0) die() return # Match an interactive Python session only after loading trusted plugins. sys.path[0] = "" # Plugin bindings and session objects are rebuilt on every start, never saved. INJECTED.update(NAMESPACE) bindings = { name: value for name, value in NAMESPACE.items() if not name.startswith("_") } NAMESPACE["__builtins__"] = session_builtins(bindings) NAMESPACE.protected.update(bindings) sys.modules["albedo_cells"] = sys.modules[__name__] sys.modules["__main__"] = CellMain("__main__") sys.modules["albedo"] = Bindings(bindings) # Declare our own process group; a group we do not lead is never the supervisor's target. pgid = os.getpgid(0) send( { "type": "ready", "pid": os.getpid(), "pgid": pgid if pgid == os.getpid() else None, "leader": albedo_proc.leader_token(os.getpid()), } ) READY.set() task = LOOP.create_task(serve()) # Release eligibility is for the local owner; a remote kernel's stdio link # has nobody reading it, and the timer would wake it every second. if RUN_DIR is not None: QUIESCENCE = albedo_quiescence.Quiescence(LOOP, RESOURCE_OWNERS, link_resources) LOOP.call_soon(refresh_work) while not task.done(): try: LOOP.run_until_complete(task) except KeyboardInterrupt: if interrupt_capture is not None: running = CELL_TASKS.get(interrupt_capture.id) if running is not None: _ = running.cancel() die()
if __name__ == "__main__": main()