deft-subspace-kernel 0.1.0a1__tar.gz

deft_subspace_kernel-0.1.0a1/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.DS_Store
+.env
+.env.*
+!.env.example
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+
+# A stray self-symlink to the checkout
+/subspace

deft_subspace_kernel-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deft_subspace_kernel-0.1.0a1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: deft-subspace-kernel
+Version: 0.1.0a1
+Summary: Protocol-neutral kernel: channels, NDJSON framing, a JSON-RPC peer with one owner for every request's lifecycle, and supervised agent processes. No dependencies.
+Project-URL: Homepage, https://github.com/deftai/subspace/tree/main/python
+Project-URL: Source, https://github.com/deftai/subspace
+Project-URL: Issues, https://github.com/deftai/subspace/issues
+Project-URL: Changelog, https://github.com/deftai/subspace/blob/main/python/CHANGELOG.md
+Author: Deft
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acp,agent-client-protocol,asyncio,json-rpc,ndjson
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# deft-subspace-kernel
+
+The protocol-neutral kernel of [Deft Subspace for Python](https://github.com/deftai/subspace/tree/main/python): channels, NDJSON framing, a JSON-RPC 2.0 peer (timeouts, cancellation, middleware, one owner for every request), abort signals, traces, and supervised child processes. Plain asyncio, Python 3.11 or later, no dependencies.
+
+```python
+from deft_subspace.kernel import RpcPeer, channel_pair
+
+a, b = channel_pair()
+server = RpcPeer(b).on_request("echo", lambda params, _ctx: params).start()
+client = RpcPeer(a).start()
+assert await client.request("echo", {"hi": 1}) == {"hi": 1}
+```
+
+Most programs want [`deft-subspace-acp`](https://pypi.org/project/deft-subspace-acp/), which builds the Agent Client Protocol on this.
+
+MIT licensed.

deft_subspace_kernel-0.1.0a1/README.md

@@ -0,0 +1,16 @@
+# deft-subspace-kernel
+
+The protocol-neutral kernel of [Deft Subspace for Python](https://github.com/deftai/subspace/tree/main/python): channels, NDJSON framing, a JSON-RPC 2.0 peer (timeouts, cancellation, middleware, one owner for every request), abort signals, traces, and supervised child processes. Plain asyncio, Python 3.11 or later, no dependencies.
+
+```python
+from deft_subspace.kernel import RpcPeer, channel_pair
+
+a, b = channel_pair()
+server = RpcPeer(b).on_request("echo", lambda params, _ctx: params).start()
+client = RpcPeer(a).start()
+assert await client.request("echo", {"hi": 1}) == {"hi": 1}
+```
+
+Most programs want [`deft-subspace-acp`](https://pypi.org/project/deft-subspace-acp/), which builds the Agent Client Protocol on this.
+
+MIT licensed.

deft_subspace_kernel-0.1.0a1/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "deft-subspace-kernel"
+version = "0.1.0a1"
+description = "Protocol-neutral kernel: channels, NDJSON framing, a JSON-RPC peer with one owner for every request's lifecycle, and supervised agent processes. No dependencies."
+keywords = ["json-rpc", "ndjson", "asyncio", "agent-client-protocol", "acp"]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Deft" }]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/deftai/subspace/tree/main/python"
+Source = "https://github.com/deftai/subspace"
+Issues = "https://github.com/deftai/subspace/issues"
+Changelog = "https://github.com/deftai/subspace/blob/main/python/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deft_subspace"]

deft_subspace_kernel-0.1.0a1/src/deft_subspace/kernel/__init__.py

@@ -0,0 +1,93 @@
+"""Protocol-neutral kernel: channels, NDJSON framing, a JSON-RPC peer, traces, and supervised processes."""
+
+from .abort import AbortController, AbortError, AbortSignal
+from .channel import (
+    Channel,
+    ChannelClosed,
+    EndOfChannel,
+    MemoryChannel,
+    StreamChannel,
+    Transform,
+    channel_pair,
+    iterate,
+    pipe_channel,
+    stream_channel,
+)
+from .clock import Clock, SystemClock, system_clock
+from .errors import ErrorCode, LocalError, LocalErrorKind, RpcError, SubspaceError
+from .framing import EncodeError, FramingDiagnostic, NdjsonDecoder, NdjsonEncoder, ndjson, ndjson_decoder, ndjson_encoder
+from .process import ExitInfo, SpawnError, SupervisedProcess, spawn_process
+from .rpc import (
+    NO_ID,
+    Call,
+    CancelInbound,
+    CancelOutbound,
+    CloseInfo,
+    InboundContext,
+    InboundMiddleware,
+    JsonRpcId,
+    NotificationHandler,
+    OutboundMiddleware,
+    PeerDiagnostic,
+    PeerState,
+    RequestHandler,
+    RpcPeer,
+    cancel_request,
+)
+from .trace import TRACE_VERSION, TraceRecord, TraceTap, format_trace, parse_trace, trace_tap
+
+__all__ = [
+    "SubspaceError",
+    "AbortController",
+    "AbortError",
+    "AbortSignal",
+    "Call",
+    "CancelInbound",
+    "CancelOutbound",
+    "Channel",
+    "ChannelClosed",
+    "Clock",
+    "CloseInfo",
+    "EncodeError",
+    "EndOfChannel",
+    "ErrorCode",
+    "ExitInfo",
+    "FramingDiagnostic",
+    "InboundContext",
+    "InboundMiddleware",
+    "JsonRpcId",
+    "LocalError",
+    "LocalErrorKind",
+    "MemoryChannel",
+    "NO_ID",
+    "NdjsonDecoder",
+    "NdjsonEncoder",
+    "NotificationHandler",
+    "OutboundMiddleware",
+    "PeerDiagnostic",
+    "PeerState",
+    "RequestHandler",
+    "RpcError",
+    "RpcPeer",
+    "SpawnError",
+    "StreamChannel",
+    "SupervisedProcess",
+    "SystemClock",
+    "TRACE_VERSION",
+    "TraceRecord",
+    "TraceTap",
+    "Transform",
+    "cancel_request",
+    "channel_pair",
+    "format_trace",
+    "iterate",
+    "ndjson",
+    "ndjson_decoder",
+    "ndjson_encoder",
+    "parse_trace",
+    "pipe_channel",
+    "spawn_process",
+    "stream_channel",
+    "system_clock",
+    "trace_tap",
+]

deft_subspace_kernel-0.1.0a1/src/deft_subspace/kernel/abort.py

@@ -0,0 +1,173 @@
+"""Cancellation as a value, like the Web's AbortController and AbortSignal.
+
+asyncio cancels tasks; Subspace also needs to say *why* something stopped and
+to let many waiters see one cancel (a turn's cancel answers every open
+permission question). A signal fires once, keeps its reason, and runs its
+listeners synchronously, in the order they were added.
+
+    controller = AbortController()
+    remove = controller.signal.add_listener(lambda reason: print("stopped", reason))
+    controller.abort("user pressed stop")
+    await controller.signal.wait()   # returns at once now
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from .errors import SubspaceError
+
+
+class AbortError(SubspaceError):
+    """The default reason of a signal aborted without one."""
+
+    def __init__(self, message: str = "This operation was aborted") -> None:
+        super().__init__(message)
+
+
+Listener = Callable[[Any], None]
+
+
+class AbortSignal:
+    __slots__ = ("_aborted", "_reason", "_listeners", "_dispose", "__weakref__")
+
+    def __init__(self) -> None:
+        self._aborted = False
+        self._reason: Any = None
+        self._listeners: list[Listener] = []
+        #: For a signal from `any`: removes its listeners from the source signals.
+        self._dispose: Callable[[], None] | None = None
+
+    @property
+    def aborted(self) -> bool:
+        return self._aborted
+
+    @property
+    def reason(self) -> Any:
+        return self._reason
+
+    def add_listener(self, listener: Listener) -> Callable[[], None]:
+        """Call `listener(reason)` once, when the signal fires. Returns a function that removes it.
+
+        On a signal that has already fired, the listener is not called (as on the Web).
+        """
+        if self._aborted:
+            return lambda: None
+        self._listeners.append(listener)
+
+        def remove() -> None:
+            try:
+                self._listeners.remove(listener)
+            except ValueError:
+                pass
+
+        return remove
+
+    def dispose(self) -> None:
+        """Stop following the source signals (a signal from `any`): its listeners on them
+        are removed, so a long-lived source does not keep it alive. It will not fire after
+        this. A no-op for any other signal, and once it fired."""
+        dispose, self._dispose = self._dispose, None
+        if dispose is not None:
+            dispose()
+
+    def __enter__(self) -> AbortSignal:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.dispose()
+
+    def throw_if_aborted(self) -> None:
+        if self._aborted:
+            reason = self._reason
+            raise reason if isinstance(reason, BaseException) else AbortError(str(reason))
+
+    async def wait(self) -> Any:
+        """Wait until the signal fires; returns its reason."""
+        if self._aborted:
+            return self._reason
+        future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
+
+        def done(reason: Any) -> None:
+            if not future.done():
+                future.set_result(reason)
+
+        remove = self.add_listener(done)
+        try:
+            return await future
+        finally:
+            remove()
+
+    def _fire(self, reason: Any) -> None:
+        if self._aborted:
+            return
+        self._aborted = True
+        self._reason = AbortError() if reason is None else reason
+        listeners, self._listeners = self._listeners, []
+        for listener in listeners:
+            try:
+                listener(self._reason)
+            except Exception:  # noqa: BLE001 - a listener must not stop the others
+                pass
+
+    @staticmethod
+    def abort(reason: Any = None) -> AbortSignal:
+        """A signal that has already fired."""
+        signal = AbortSignal()
+        signal._fire(reason)
+        return signal
+
+    @staticmethod
+    def any(signals: Iterable[AbortSignal | None]) -> AbortSignal:
+        """A signal that fires when the first of `signals` fires, with its reason.
+
+        It listens on every source until one fires. When you are done with it before
+        then, `dispose()` it (or use it as a context manager) so a long-lived source
+        does not keep it, and whatever listens on it, alive:
+
+            with AbortSignal.any([turn_signal, connection_signal]) as signal:
+                ...
+        """
+        combined = AbortSignal()
+        live = [s for s in signals if s is not None]
+        for signal in live:
+            if signal.aborted:
+                combined._fire(signal.reason)
+                return combined
+        removers: list[Callable[[], None]] = []
+
+        def dispose() -> None:
+            for remove in removers:
+                remove()
+            removers.clear()
+
+        def fire(reason: Any) -> None:
+            combined.dispose()
+            combined._fire(reason)
+
+        for signal in live:
+            removers.append(signal.add_listener(fire))
+        combined._dispose = dispose
+        return combined
+
+    @staticmethod
+    def timeout(ms: float) -> AbortSignal:
+        """A signal that fires after `ms` milliseconds (needs a running loop)."""
+        signal = AbortSignal()
+        asyncio.get_running_loop().call_later(ms / 1000, lambda: signal._fire(TimeoutError(f"timed out after {ms} ms")))
+        return signal
+
+    def __repr__(self) -> str:
+        return f"AbortSignal(aborted={self._aborted})"
+
+
+class AbortController:
+    __slots__ = ("signal",)
+
+    def __init__(self) -> None:
+        self.signal = AbortSignal()
+
+    def abort(self, reason: Any = None) -> None:
+        self.signal._fire(reason)

deft_subspace_kernel-0.1.0a1/src/deft_subspace/kernel/channel.py

@@ -0,0 +1,244 @@
+"""Channels: read what the other side sent, send what you send.
+
+Bytes on the edges (stdio, sockets), structured messages in process.
+
+    message = await channel.receive()   # raises EndOfChannel when the other side has ended
+    await channel.send(message)
+    await channel.close()               # end our side; the other side reads EndOfChannel
+
+A channel may also have `abort()`: close at once, dropping unsent data. The
+peer uses it when a write is stuck; without it, it calls `close()`.
+
+`channel_pair()` connects two in-process ends; `stream_channel()` wraps
+asyncio streams; `pipe_channel()` applies a transform to each direction (that
+is how `ndjson()` turns bytes into JSON values).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from collections.abc import AsyncIterator, Iterable
+from typing import Any, Generic, Protocol, TypeVar
+
+from .errors import SubspaceError
+
+T = TypeVar("T")
+A = TypeVar("A")
+B = TypeVar("B")
+In = TypeVar("In", contravariant=True)
+Out = TypeVar("Out", covariant=True)
+
+
+class EndOfChannel(SubspaceError):
+    """The other side ended its stream: nothing more will arrive."""
+
+
+class ChannelClosed(SubspaceError):
+    """Sending on a channel whose sending side was closed (or whose reader went away)."""
+
+
+class Channel(Protocol[T]):
+    async def receive(self) -> T:
+        """The next item. Raises `EndOfChannel` once the other side has ended."""
+        ...
+
+    async def send(self, item: T) -> None:
+        """Send an item, in order with earlier sends. Raises `ChannelClosed` when it cannot."""
+        ...
+
+    async def close(self) -> None:
+        """End this side's stream. Idempotent."""
+        ...
+
+
+async def iterate(channel: Channel[T]) -> AsyncIterator[T]:
+    """Every item until the other side ends."""
+    while True:
+        try:
+            yield await channel.receive()
+        except EndOfChannel:
+            return
+
+
+class _Pipe(Generic[T]):
+    """One direction: items in order, then the end."""
+
+    def __init__(self) -> None:
+        self.items: deque[T] = deque()
+        self.ended = False
+        # Every receive() waiting for an item. All are woken; each takes one or waits again.
+        self.waiters: list[asyncio.Future[None]] = []
+
+    def put(self, item: T) -> None:
+        if self.ended:
+            raise ChannelClosed("channel closed")
+        self.items.append(item)
+        self._wake()
+
+    def end(self) -> None:
+        self.ended = True
+        self._wake()
+
+    def _wake(self) -> None:
+        waiters, self.waiters = self.waiters, []
+        for waiter in waiters:
+            if not waiter.done():
+                waiter.set_result(None)
+
+    async def get(self) -> T:
+        while not self.items:
+            if self.ended:
+                raise EndOfChannel()
+            waiter = asyncio.get_running_loop().create_future()
+            self.waiters.append(waiter)
+            try:
+                await waiter
+            finally:
+                if waiter in self.waiters:
+                    self.waiters.remove(waiter)
+        return self.items.popleft()
+
+
+class MemoryChannel(Generic[T]):
+    """One end of an in-process pair."""
+
+    def __init__(self, inbox: _Pipe[T], outbox: _Pipe[T]) -> None:
+        self._inbox = inbox
+        self._outbox = outbox
+
+    async def receive(self) -> T:
+        return await self._inbox.get()
+
+    async def send(self, item: T) -> None:
+        self._outbox.put(item)
+
+    async def close(self) -> None:
+        self._outbox.end()
+
+    async def abort(self) -> None:
+        self._outbox.end()
+
+
+def channel_pair() -> tuple[MemoryChannel[Any], MemoryChannel[Any]]:
+    """Two connected channels in one process: what `a` sends, `b` receives, and the other way round.
+
+    No bytes, no JSON. Use it to run a client and an agent together in tests or in one app.
+    """
+    a_to_b: _Pipe[Any] = _Pipe()
+    b_to_a: _Pipe[Any] = _Pipe()
+    return MemoryChannel(b_to_a, a_to_b), MemoryChannel(a_to_b, b_to_a)
+
+
+class StreamChannel:
+    """asyncio streams (a socket, a child's stdio) as a byte channel."""
+
+    def __init__(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter | Any, *, chunk_size: int = 65536) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._chunk = chunk_size
+        self._closed = False
+
+    async def receive(self) -> bytes:
+        data = await self._reader.read(self._chunk)
+        if not data:
+            raise EndOfChannel()
+        return data
+
+    async def send(self, item: bytes) -> None:
+        if self._closed or self._writer.is_closing():
+            raise ChannelClosed("stream closed")
+        try:
+            self._writer.write(item)
+            await self._writer.drain()
+        except (ConnectionError, RuntimeError) as error:  # BrokenPipe, reset, closed transport
+            raise ChannelClosed(str(error)) from error
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            if self._writer.can_write_eof():
+                self._writer.write_eof()
+            else:
+                self._writer.close()
+        except (OSError, RuntimeError):
+            pass
+
+    async def abort(self) -> None:
+        """Close at once, dropping anything not yet written."""
+        self._closed = True
+        transport = getattr(self._writer, "transport", None)
+        try:
+            if transport is not None:
+                transport.abort()
+            else:
+                self._writer.close()
+        except (OSError, RuntimeError):
+            pass
+
+
+def stream_channel(reader: asyncio.StreamReader, writer: asyncio.StreamWriter | Any) -> StreamChannel:
+    return StreamChannel(reader, writer)
+
+
+class Transform(Protocol[In, Out]):
+    """Turns items into items, keeping state between them (a decoder, a re-chunker)."""
+
+    def feed(self, item: In, /) -> Iterable[Out]: ...
+
+    def flush(self) -> Iterable[Out]:
+        """What is left once the input has ended."""
+        ...
+
+
+class _Piped(Generic[A, B]):
+    def __init__(self, channel: Channel[A], read: Transform[A, B], write: Transform[B, A]) -> None:
+        self._channel = channel
+        self._read = read
+        self._write = write
+        self._ready: deque[B] = deque()
+        self._ended = False
+
+    async def receive(self) -> B:
+        while not self._ready:
+            if self._ended:
+                raise EndOfChannel()
+            try:
+                item = await self._channel.receive()
+            except EndOfChannel:
+                self._ended = True
+                self._ready.extend(self._read.flush())
+                continue
+            self._ready.extend(self._read.feed(item))
+        return self._ready.popleft()
+
+    async def send(self, item: B) -> None:
+        for out in self._write.feed(item):
+            await self._channel.send(out)
+
+    async def close(self) -> None:
+        try:
+            for out in self._write.flush():
+                await self._channel.send(out)
+        except ChannelClosed:
+            pass
+        await self._channel.close()
+
+    async def abort(self) -> None:
+        abort = getattr(self._channel, "abort", None)
+        await (abort() if abort is not None else self._channel.close())
+
+
+def pipe_channel(channel: Channel[A], *, read: Transform[A, B], write: Transform[B, A]) -> Channel[B]:
+    """Apply a transform to each direction of a channel."""
+    return _Piped(channel, read, write)
+
+
+class Identity(Generic[T]):
+    def feed(self, item: T) -> Iterable[T]:
+        return (item,)
+
+    def flush(self) -> Iterable[T]:
+        return ()

deft_subspace_kernel-0.1.0a1/src/deft_subspace/kernel/clock.py

@@ -0,0 +1,39 @@
+"""Time, as something tests can control.
+
+Every timer in the kernel goes through a Clock, so a test can fake it and
+check timeout behaviour without waiting. Times are milliseconds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class Clock(Protocol):
+    def now(self) -> float:
+        """Milliseconds since the epoch."""
+        ...
+
+    def set_timeout(self, callback: Callable[[], None], ms: float) -> Any:
+        """Run `callback` after `ms`; returns a handle for `clear_timeout`."""
+        ...
+
+    def clear_timeout(self, handle: Any) -> None: ...
+
+
+class SystemClock:
+    def now(self) -> float:
+        return time.time() * 1000
+
+    def set_timeout(self, callback: Callable[[], None], ms: float) -> asyncio.TimerHandle:
+        return asyncio.get_running_loop().call_later(max(0.0, ms) / 1000, callback)
+
+    def clear_timeout(self, handle: Any) -> None:
+        if handle is not None:
+            handle.cancel()
+
+
+system_clock: Clock = SystemClock()