megacode-agent-sdk 0.31.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,101 @@
1
+ """Drive a MEGA harness agent session from a Python program.
2
+
3
+ A `Client` holds one session: `Client.start(options)` (or `Client.resume`)
4
+ begins it, `send(prompt)` runs one turn and returns its events, and the other
5
+ methods steer, abort, compact or inspect it while a turn's events are read.
6
+ `query(prompt, options)` is one prompt, one turn, then the end. Spec:
7
+ `docs/specs/slice-ar.md` R8, R10.
8
+ """
9
+ from ._version import __version__
10
+ from .client import Client, Done, Events, Queued, TurnStream, query
11
+ from .errors import (
12
+ BinaryUnavailable,
13
+ Diagnostics,
14
+ HandshakeError,
15
+ ProtocolError,
16
+ Refused,
17
+ SdkError,
18
+ SessionEnded,
19
+ SlowConsumer,
20
+ TooLarge,
21
+ TurnInProgress,
22
+ )
23
+ from .options import Append, Options, Replace
24
+ from .tools import Tool, ToolContext, ToolOutput, tool
25
+ from .wire import (
26
+ AllowForTurn,
27
+ AllowOnce,
28
+ Approval,
29
+ ApprovalRequest,
30
+ Assistant,
31
+ Compacted,
32
+ ContextState,
33
+ Cost,
34
+ Decision,
35
+ Denied,
36
+ Deny,
37
+ DenyAndStop,
38
+ Escape,
39
+ Event,
40
+ Info,
41
+ Init,
42
+ Reasoning,
43
+ Result,
44
+ RunningTurn,
45
+ State,
46
+ ToolResult,
47
+ ToolUse,
48
+ Usage,
49
+ User,
50
+ )
51
+
52
+ __all__ = [
53
+ "__version__",
54
+ "Client",
55
+ "TurnStream",
56
+ "Events",
57
+ "Queued",
58
+ "Done",
59
+ "query",
60
+ "Options",
61
+ "Replace",
62
+ "Append",
63
+ "tool",
64
+ "Tool",
65
+ "ToolContext",
66
+ "ToolOutput",
67
+ "Event",
68
+ "Info",
69
+ "Init",
70
+ "User",
71
+ "Reasoning",
72
+ "Assistant",
73
+ "ToolUse",
74
+ "ToolResult",
75
+ "Approval",
76
+ "ApprovalRequest",
77
+ "Escape",
78
+ "Compacted",
79
+ "Result",
80
+ "Usage",
81
+ "Denied",
82
+ "Cost",
83
+ "State",
84
+ "RunningTurn",
85
+ "ContextState",
86
+ "Decision",
87
+ "AllowOnce",
88
+ "AllowForTurn",
89
+ "Deny",
90
+ "DenyAndStop",
91
+ "SdkError",
92
+ "BinaryUnavailable",
93
+ "HandshakeError",
94
+ "SessionEnded",
95
+ "Diagnostics",
96
+ "ProtocolError",
97
+ "Refused",
98
+ "TurnInProgress",
99
+ "SlowConsumer",
100
+ "TooLarge",
101
+ ]
@@ -0,0 +1,161 @@
1
+ """Which harness binary a session runs (spec slice-ar R12). In order: the
2
+ `binary` option; `MEGACODE_AGENT_SDK_BINARY`; the verified cache; a download
3
+ of the exact matching release, checked against the digests pinned in this
4
+ package (`_pins.py`)."""
5
+ import asyncio
6
+ import hashlib
7
+ import os
8
+ import platform
9
+ import sys
10
+ from typing import Any, Dict, Optional, Tuple
11
+
12
+ BINARY_ENV = "MEGACODE_AGENT_SDK_BINARY"
13
+ """The environment variable naming a harness binary; defined before the
14
+ submodules are imported, as `cache` names it."""
15
+
16
+ from .. import _pins # noqa: E402
17
+ from .._version import __version__ # noqa: E402
18
+ from ..errors import BinaryUnavailable # noqa: E402
19
+ from . import archive as _archive # noqa: E402
20
+ from . import cache as _cache # noqa: E402
21
+ from . import download as _download # noqa: E402
22
+
23
+ DEFAULT_BASE = "https://megacode-harness.vercel.app/dl"
24
+ """Where releases are downloaded from (`crates/cli/src/update.rs`'s `SITE_DL`)."""
25
+ BASE_ENV = "MEGACODE_AGENT_SDK_DOWNLOAD_BASE"
26
+ """Overrides `DEFAULT_BASE`."""
27
+
28
+ TARGETS = ("x86_64-unknown-linux-musl", "aarch64-apple-darwin", "x86_64-apple-darwin")
29
+ """The release targets (spec R12.6, `release.yml`'s matrix)."""
30
+
31
+
32
+ async def locate(options: Any) -> str:
33
+ """The binary a session runs (R12.1)."""
34
+ named = _named(options.binary, os.environ.get(BINARY_ENV))
35
+ if named is not None:
36
+ return named
37
+ release = _current()
38
+ return await release.fetch()
39
+
40
+
41
+ def _named(option: Any, env: Optional[str]) -> Optional[str]:
42
+ """The binary the program named: the option, else the environment
43
+ variable. Both are trusted as given."""
44
+ if option is not None:
45
+ return os.fspath(option)
46
+ if env:
47
+ return env
48
+ return None
49
+
50
+
51
+ def target_for(os_name: str, arch: str) -> str:
52
+ """The release target for `sys.platform` and `platform.machine()`."""
53
+ if os_name == "linux" and arch == "x86_64":
54
+ return TARGETS[0]
55
+ if os_name == "darwin" and arch == "arm64":
56
+ return TARGETS[1]
57
+ if os_name == "darwin" and arch == "x86_64":
58
+ return TARGETS[2]
59
+ raise BinaryUnavailable(
60
+ f"no harness release is built for {os_name} on {arch}: releases exist for {TARGETS[0]}, "
61
+ f"{TARGETS[1]} and {TARGETS[2]}. Name an installed harness with the `binary` option "
62
+ f"(Options::binary) or {BINARY_ENV}"
63
+ )
64
+
65
+
66
+ def cache_root_from(os_name: str, xdg_cache_home: Optional[str], home: Optional[str]) -> str:
67
+ """`<cache>` (R12.3): `~/Library/Caches` on macOS; elsewhere
68
+ `$XDG_CACHE_HOME` when it is an absolute path, else `~/.cache`."""
69
+ if os_name != "darwin" and xdg_cache_home and os.path.isabs(xdg_cache_home):
70
+ return xdg_cache_home
71
+ if not home or not os.path.isabs(home):
72
+ raise BinaryUnavailable(
73
+ "no cache folder for the harness download: HOME is not set to an absolute "
74
+ f"path. Name an installed harness with Options::binary or {BINARY_ENV}"
75
+ )
76
+ if os_name == "darwin":
77
+ return os.path.join(home, "Library", "Caches")
78
+ return os.path.join(home, ".cache")
79
+
80
+
81
+ def pinned(
82
+ pins_version: str, pins: Dict[str, Tuple[str, str]], version: str, target: str
83
+ ) -> Optional[Tuple[str, str]]:
84
+ """`(archive_sha256, executable_sha256)` for `target` when the pins are
85
+ for `version`; pins for another version are none."""
86
+ if pins_version != version:
87
+ return None
88
+ return pins.get(target)
89
+
90
+
91
+ class Release:
92
+ """One version's release for one target, where it is downloaded from,
93
+ the cache it goes to, and its pins."""
94
+
95
+ def __init__(
96
+ self, version: str, target: str, base: str, cache: str, archive_sha256: str, executable_sha256: str
97
+ ) -> None:
98
+ self.version = version
99
+ self.target = target
100
+ self.base = base.rstrip("/")
101
+ self.cache = os.fspath(cache)
102
+ self.archive_sha256 = archive_sha256
103
+ self.executable_sha256 = executable_sha256
104
+
105
+ async def fetch(self) -> str:
106
+ """The verified cached executable, downloading it when it is missing
107
+ or its digest is not the pinned one (R12.3–R12.4). Nothing that fails
108
+ a check is run or kept."""
109
+ return await asyncio.get_running_loop().run_in_executor(None, self.fetch_blocking)
110
+
111
+ def fetch_blocking(self) -> str:
112
+ layout = _cache.Layout(self.cache, self.version, self.target)
113
+ # A file with another digest is never run; the verified download is
114
+ # renamed over it. It is not removed first: another program may have
115
+ # renamed its own verified file into place since this check.
116
+ if _cache.check(layout, self.executable_sha256) == _cache.VERIFIED:
117
+ return layout.file
118
+ executable = self._download()
119
+ _cache.install(layout, executable, self.executable_sha256)
120
+ if _cache.check(layout, self.executable_sha256) != _cache.VERIFIED:
121
+ raise BinaryUnavailable(
122
+ f"the harness cached at {layout.file} does not match its pinned SHA-256 after a fresh "
123
+ "download; it is not run"
124
+ )
125
+ return layout.file
126
+
127
+ def _download(self) -> bytes:
128
+ """The archive, checked, and the executable from it, checked; both in
129
+ memory, before any folder or file is made."""
130
+ url = f"{self.base}/v{self.version}/harness-{self.target}.tar.gz"
131
+ try:
132
+ gz = _download.archive(url, self.archive_sha256)
133
+ except _download.DownloadError as e:
134
+ raise BinaryUnavailable(str(e)) from None
135
+ try:
136
+ executable = _archive.executable(gz)
137
+ except _archive.ArchiveError as e:
138
+ raise BinaryUnavailable(f"cannot use {url}: {e}; nothing was cached") from None
139
+ got = hashlib.sha256(executable).hexdigest()
140
+ if got != self.executable_sha256:
141
+ raise BinaryUnavailable(
142
+ f"cannot use {url}: the harness in the archive does not match its pinned SHA-256 "
143
+ f"(got {got}, pinned {self.executable_sha256}); nothing was cached"
144
+ )
145
+ return executable
146
+
147
+
148
+ def _current() -> Release:
149
+ """This package's version for this platform, with its pins."""
150
+ target = target_for(sys.platform, platform.machine())
151
+ version = __version__
152
+ pin = pinned(_pins.PINS_VERSION, _pins.PINS, version, target)
153
+ if pin is None:
154
+ raise BinaryUnavailable(
155
+ f"this build of megacode-agent-sdk {version} carries no pinned harness release for "
156
+ f"{target}, so it cannot download one. Name an installed harness with Options::binary "
157
+ f"or {BINARY_ENV}"
158
+ )
159
+ base = os.environ.get(BASE_ENV) or DEFAULT_BASE
160
+ cache = cache_root_from(sys.platform, os.environ.get("XDG_CACHE_HOME"), os.environ.get("HOME"))
161
+ return Release(version, target, base, cache, pin[0], pin[1])
@@ -0,0 +1,6 @@
1
+ """The test-only constructor (as the Rust crate's `__testing`): a `Release`
2
+ with an explicit cache root, injected pins and an injected download base.
3
+ Not part of the public API; a program's sessions use `locate`."""
4
+ from . import Release
5
+
6
+ __all__ = ["Release"]
@@ -0,0 +1,183 @@
1
+ """The release archive reader (spec slice-ar R12.2), a port of the Rust
2
+ crate's `sdk/rust/src/binary/tar.rs`: gzip, then tar; the one regular file
3
+ `harness` (or `./harness`) is the executable. Pax headers (`x`, `g`) and
4
+ AppleDouble members (`._*`) are skipped; any other member type, a second
5
+ regular file, or a path with `..` is an error. Only the first gzip member is
6
+ read, as the crate's `GzDecoder` reads it; once the tar is read, the rest of
7
+ that member is inflated so zlib checks its trailer (CRC-32 and length), as it
8
+ checks the header CRC when present. Nothing is written to disk."""
9
+ import zlib
10
+ from typing import Optional
11
+
12
+ MAX_EXECUTABLE = 256 * 1024 * 1024
13
+ """The largest executable accepted."""
14
+
15
+ MAX_SKIPPED = 16 * 1024 * 1024
16
+ """What the skipped members (pax headers, AppleDouble files, empty folders)
17
+ may add up to."""
18
+
19
+ MAX_INFLATED = MAX_EXECUTABLE + MAX_SKIPPED + 16 * 1024 * 1024
20
+ """The most the first member may inflate to: the executable, the skipped
21
+ members, and 16 MiB of headers and padding."""
22
+
23
+ BLOCK = 512
24
+ _FEED = 64 * 1024
25
+
26
+
27
+ class ArchiveError(Exception):
28
+ """The archive is refused; the text says why."""
29
+
30
+
31
+ class _FirstMember:
32
+ """The decompressed bytes of the first gzip member, read on demand;
33
+ whatever follows that member is never read."""
34
+
35
+ def __init__(self, gz: bytes) -> None:
36
+ self._z = zlib.decompressobj(16 + zlib.MAX_WBITS)
37
+ self._input = memoryview(gz)
38
+ self._at = 0
39
+ self._out = bytearray()
40
+ self._total = 0
41
+
42
+ def _inflate(self, want: int) -> bytes:
43
+ # Fed in pieces, so the unconsumed input is never copied whole.
44
+ data = self._z.unconsumed_tail
45
+ if not data:
46
+ data = self._input[self._at : self._at + _FEED]
47
+ self._at += len(data)
48
+ if not data:
49
+ return b""
50
+ out = self._z.decompress(data, want)
51
+ self._total += len(out)
52
+ if self._total > MAX_INFLATED:
53
+ raise ArchiveError(f"the archive unpacks to over {MAX_INFLATED // (1024 * 1024)} MiB")
54
+ return out
55
+
56
+ def finish(self) -> None:
57
+ """Inflates the rest of the member, discarding it, so zlib checks
58
+ its trailer; refuses a member cut short or corrupt."""
59
+ self._out.clear()
60
+ try:
61
+ while not self._z.eof:
62
+ if not self._z.unconsumed_tail and self._at >= len(self._input):
63
+ raise ArchiveError("the archive ends early: the gzip stream is cut short")
64
+ self._inflate(_FEED)
65
+ except zlib.error as e:
66
+ raise ArchiveError(f"the archive is corrupt: {e}") from None
67
+
68
+ def read(self, n: int) -> bytes:
69
+ """At most `n` bytes; fewer only at the member's end."""
70
+ while len(self._out) < n and not self._z.eof:
71
+ if not self._z.unconsumed_tail and self._at >= len(self._input):
72
+ break
73
+ self._out += self._inflate(max(n - len(self._out), _FEED))
74
+ out = bytes(self._out[:n])
75
+ del self._out[:n]
76
+ return out
77
+
78
+
79
+ def _read_exact(f: _FirstMember, n: int) -> bytes:
80
+ """`n` bytes, or the refusal of an archive that ends early or is not
81
+ gzip."""
82
+ try:
83
+ out = f.read(n)
84
+ except zlib.error as e:
85
+ raise ArchiveError(f"the archive ends early: {e}") from None
86
+ if len(out) < n:
87
+ raise ArchiveError("the archive ends early: failed to fill whole buffer")
88
+ return out
89
+
90
+
91
+ def _octal(field: bytes) -> Optional[int]:
92
+ """A NUL- or space-ended octal field; `None` when it is not one (a
93
+ base-256 size is over any limit here, so it is refused as malformed)."""
94
+ digits = field.lstrip(b" ")
95
+ for i, b in enumerate(digits):
96
+ if b in (0, 0x20):
97
+ digits = digits[:i]
98
+ break
99
+ if not digits:
100
+ return 0
101
+ if len(digits) > 21 or any(d not in b"01234567" for d in digits):
102
+ return None
103
+ return int(digits, 8)
104
+
105
+
106
+ def _text(field: bytes) -> str:
107
+ return field.split(b"\0", 1)[0].decode("utf-8", "replace")
108
+
109
+
110
+ def _kind(k: int) -> str:
111
+ """A member type as the Rust crate's `{:?}` of a `char` prints it."""
112
+ escapes = {0x09: "\\t", 0x0A: "\\n", 0x0D: "\\r", 0x27: "\\'", 0x5C: "\\\\", 0x00: "\\0"}
113
+ if k in escapes:
114
+ return f"'{escapes[k]}'"
115
+ c = chr(k)
116
+ return f"'{c}'" if c.isprintable() else f"'\\u{{{k:x}}}'"
117
+
118
+
119
+ def _header(h: bytes):
120
+ """`(path, kind, size)` from a header block, its checksum checked."""
121
+ stored = _octal(h[148:156])
122
+ if stored is None or sum(h[:148]) + 8 * 32 + sum(h[156:]) != stored:
123
+ raise ArchiveError("the archive has a bad header checksum")
124
+ size = _octal(h[124:136])
125
+ if size is None:
126
+ raise ArchiveError("the archive has a bad member size")
127
+ name = _text(h[0:100])
128
+ prefix = _text(h[345:500]) if h[257:262] == b"ustar" else ""
129
+ return (f"{prefix}/{name}" if prefix else name), h[156], size
130
+
131
+
132
+ def _body(f: _FirstMember, size: int, keep: Optional[bytearray]) -> None:
133
+ """Reads a member's body of `size` bytes and its padding to the block;
134
+ keeps the body in `keep` when given."""
135
+ padded = -(-size // BLOCK) * BLOCK
136
+ done = 0
137
+ while done < padded:
138
+ want = min(padded - done, 64 * 1024)
139
+ buf = _read_exact(f, want)
140
+ if keep is not None:
141
+ keep += buf[: max(0, min(want, size - done))]
142
+ done += want
143
+
144
+
145
+ def executable(gz: bytes) -> bytes:
146
+ """The executable's bytes from a gzipped tar, or `ArchiveError`."""
147
+ found: Optional[bytearray] = None
148
+ skipped = 0
149
+ f = _FirstMember(gz)
150
+ while True:
151
+ header = _read_exact(f, BLOCK)
152
+ if header == bytes(BLOCK):
153
+ break
154
+ path, kind, size = _header(header)
155
+ if ".." in path.split("/"):
156
+ raise ArchiveError(f"the archive holds a path with ..: {path}")
157
+ name = path[2:] if path.startswith("./") else path
158
+ base = name.rsplit("/", 1)[-1]
159
+ regular = kind in (ord("0"), 0)
160
+ if kind in (ord("x"), ord("g")) or (regular and base.startswith("._")) or (
161
+ kind == ord("5") and size == 0
162
+ ):
163
+ skipped += size
164
+ if skipped > MAX_SKIPPED:
165
+ raise ArchiveError("the archive's other members are over 16 MiB")
166
+ _body(f, size, None)
167
+ elif regular and name == "harness":
168
+ if found is not None:
169
+ raise ArchiveError("the archive holds a second harness")
170
+ if size > MAX_EXECUTABLE:
171
+ raise ArchiveError(f"the archive's harness is {size} bytes, over 256 MiB")
172
+ found = bytearray()
173
+ _body(f, size, found)
174
+ elif regular:
175
+ raise ArchiveError(f"the archive holds a regular file other than harness: {path}")
176
+ else:
177
+ raise ArchiveError(
178
+ f"the archive holds a member of type {_kind(kind)} that is not a regular file: {path}"
179
+ )
180
+ if found is None:
181
+ raise ArchiveError("the archive holds no harness")
182
+ f.finish()
183
+ return bytes(found)