localcode 0.3.36__tar.gz → 0.3.38__tar.gz

{localcode-0.3.36/src/localcode.egg-info → localcode-0.3.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localcode
-Version: 0.3.36
+Version: 0.3.38
 Summary: High-performance AI coding on consumer hardware.
 Author: LocalCode contributors
 License-Expression: Apache-2.0
@@ -70,7 +70,7 @@ Dynamic: license-file
 ## Install
 
 ```bash
-pip install localcode
+pip install localcode      # or: uv pip install localcode
 ```
 
 ## Run
@@ -80,8 +80,6 @@ cd your-project
 localcode
 ```
 
-That's it. First launch builds the inference server and downloads the model (~5 min, one time). After that, startup is ~15 seconds.
-
 ## Docs
 
 Docs are published at [mjwsolo.github.io/localcode](https://mjwsolo.github.io/localcode/).
@@ -119,11 +117,15 @@ LocalCode is early software. Hardware support is expected to broaden, but only t
 
 | Mac | Memory | Status | Notes |
 | --- | ---: | --- | --- |
-| M4 MacBook | 16 GB | Tested | Primary development and validation machine |
+| M5 Apple Silicon | up to 128 GB | Tested | Primary development machine (M5 Max) |
+| M4 MacBook | 16 GB | Tested | Validated at the 16 GB floor |
 | M1/M2/M3 Apple Silicon | 16 GB+ | Not yet tested | Expected to work, but needs validation |
 | M4 Apple Silicon | 24 GB+ | Not yet tested | Expected to support larger contexts, but needs validation |
 | Intel Mac | Any | Not supported | LocalCode targets Apple Silicon |
 
+> Linux installs and runs in CI for development, but Apple Silicon is the
+> supported target — the Metal-accelerated inference path is Mac-only.
+
 ## Models
 
 On launch, LocalCode recommends the best model for **your Mac's RAM** — there's no fixed default. You can pick any of these (or a different quant) in the model picker.

{localcode-0.3.36 → localcode-0.3.38}/README.md

@@ -23,7 +23,7 @@
 ## Install
 
 ```bash
-pip install localcode
+pip install localcode      # or: uv pip install localcode
 ```
 
 ## Run
@@ -33,8 +33,6 @@ cd your-project
 localcode
 ```
 
-That's it. First launch builds the inference server and downloads the model (~5 min, one time). After that, startup is ~15 seconds.
-
 ## Docs
 
 Docs are published at [mjwsolo.github.io/localcode](https://mjwsolo.github.io/localcode/).
@@ -72,11 +70,15 @@ LocalCode is early software. Hardware support is expected to broaden, but only t
 
 | Mac | Memory | Status | Notes |
 | --- | ---: | --- | --- |
-| M4 MacBook | 16 GB | Tested | Primary development and validation machine |
+| M5 Apple Silicon | up to 128 GB | Tested | Primary development machine (M5 Max) |
+| M4 MacBook | 16 GB | Tested | Validated at the 16 GB floor |
 | M1/M2/M3 Apple Silicon | 16 GB+ | Not yet tested | Expected to work, but needs validation |
 | M4 Apple Silicon | 24 GB+ | Not yet tested | Expected to support larger contexts, but needs validation |
 | Intel Mac | Any | Not supported | LocalCode targets Apple Silicon |
 
+> Linux installs and runs in CI for development, but Apple Silicon is the
+> supported target — the Metal-accelerated inference path is Mac-only.
+
 ## Models
 
 On launch, LocalCode recommends the best model for **your Mac's RAM** — there's no fixed default. You can pick any of these (or a different quant) in the model picker.

{localcode-0.3.36 → localcode-0.3.38}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "localcode"
-version = "0.3.36"
+version = "0.3.38"
 description = "High-performance AI coding on consumer hardware."
 readme = "README.md"
 requires-python = ">=3.10"

localcode-0.3.38/src/localcode/__init__.py

@@ -0,0 +1,11 @@
+__all__ = ["__version__"]
+
+# Read the version from installed package metadata so it can never drift from
+# pyproject.toml (it was hardcoded and went ~12 releases stale). Falls back to a
+# hardcoded value only when running from a source tree that isn't installed.
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("localcode")
+except PackageNotFoundError:  # not installed (e.g. raw source checkout)
+    __version__ = "0.3.38"

{localcode-0.3.36 → localcode-0.3.38}/src/localcode/agent/turn_finalization.py

@@ -123,6 +123,7 @@ def finalize_turn(
         app._last_turn_task_status = task_status
         app._last_turn_task_stage = final_task_stage
         app._last_turn_blocked_reason = blocked_reason
+        app._last_turn_loop_exit_reason = loop_exit_reason
         app._last_turn_goal = goal_state.as_dict()
     except Exception as exc:
         _emit_finalization_error(turn_id, "turn_store_update", exc)

{localcode-0.3.36 → localcode-0.3.38}/src/localcode/headless_json.py

@@ -98,6 +98,25 @@ def _as_int(value: Any) -> int:
         return 0
 
 
+def _terminal_from_status(
+    *, completion_status: str, blocked_reason: str, loop_exit_reason: str,
+    final_text: str = "",
+) -> tuple[str, int, str, str]:
+    """Map the loop's persisted turn status to a headless (status, exit, reason).
+
+    A completion_status of `completed` (the only success value from
+    `status_for_exit`) exits 0/`ok`; any other non-empty status (blocked,
+    interrupted, stopped_early, error, incomplete) exits 1/`incomplete`. An
+    unset status falls through to `ok` so a run that never populated it isn't
+    reported as a false failure.
+    """
+    completion = (completion_status or "").strip()
+    reason = (blocked_reason or loop_exit_reason or "completed").strip() or "completed"
+    if completion and completion != "completed":
+        return "incomplete", 1, reason, final_text or ""
+    return "ok", 0, reason, final_text or ""
+
+
 def run_headless_json(config, args) -> int:
     """Headless run that emits the agent event stream as JSONL on stdout.
 
@@ -202,12 +221,17 @@ def run_headless_json(config, args) -> int:
         except Exception:
             pass
 
-    turn_end = emitter.last_turn_end
-    completion = str(turn_end.get("completion_status") or "")
-    reason = str(turn_end.get("loop_exit_reason") or "completed")
-    if completion and completion != "completed":
-        return _emit_result("incomplete", 1, reason, result_text or "")
-    return _emit_result("ok", 0, reason, result_text or "")
+    # `turn_end` is emitted to the events file, not through the OutputManager
+    # callback, so `emitter.last_turn_end` is always empty and can't drive the
+    # exit code. Read the status the loop persisted on the app instead
+    # (finalize_turn sets these `_last_turn_*` attrs every turn).
+    status, code, reason, text = _terminal_from_status(
+        completion_status=str(getattr(app, "_last_turn_completion_status", "") or ""),
+        blocked_reason=str(getattr(app, "_last_turn_blocked_reason", "") or ""),
+        loop_exit_reason=str(getattr(app, "_last_turn_loop_exit_reason", "") or ""),
+        final_text=result_text or "",
+    )
+    return _emit_result(status, code, reason, text)
 
 
 def open_clean_stdout() -> TextIO:

{localcode-0.3.36 → localcode-0.3.38}/src/localcode/output.py

@@ -285,8 +285,11 @@ class OutputManager:
         self._stop_indicator()
         lines = result.strip().splitlines()
         if error:
+            # A tool returning an error is normal, recoverable agentic operation
+            # (the model reads it and adjusts) — render it calm amber, NOT alarm
+            # red. Red is reserved for a terminal, turn-ending failure (set_error).
             for line in lines[:5]:
-                sys.stdout.write(f"\033[31m  └ {line[:90]}\033[0m\n")
+                sys.stdout.write(f"\033[33m  └ {line[:90]}\033[0m\n")
         elif lines:
             max_lines = 8
             for i, line in enumerate(lines[:max_lines]):

localcode-0.3.38/src/localcode/protocol/__init__.py

@@ -0,0 +1,56 @@
+"""LocalCode public automation protocol.
+
+The single, versioned, dependency-light definition of the `localcode run --json`
+event stream. Both the native `eval/` harness and the Harbor plugin consume
+LocalCode through this package — neither maintains its own JSONL parser or
+failure taxonomy (integration plan §7.2.1). Standard library only, so any
+consumer can import it without pulling in LocalCode's full dependency tree.
+
+Typical use:
+
+    from localcode.protocol import parse_stream, outcome_from_parse
+
+    parsed = parse_stream(process.stdout)      # incremental, memory-bounded
+    outcome = outcome_from_parse(parsed)       # normalized RunOutcome
+    if outcome.clean_finish:                    # LocalCode's loop finished...
+        ...                                     # ...verifier still decides pass/fail
+"""
+from __future__ import annotations
+
+from .events import (
+    SCHEMA_MAJOR,
+    SCHEMA_MINOR,
+    SCHEMA_VERSION,
+    Event,
+    SchemaVersion,
+    UnsupportedSchemaError,
+)
+from .jsonl import ParseProblem, ParseResult, iter_events, parse_stream
+from .outcomes import (
+    FailureCategory,
+    RunOutcome,
+    normalize_reason,
+    outcome_from_parse,
+    redact,
+)
+
+__all__ = [
+    # schema
+    "SCHEMA_MAJOR",
+    "SCHEMA_MINOR",
+    "SCHEMA_VERSION",
+    "SchemaVersion",
+    "UnsupportedSchemaError",
+    # events + parsing
+    "Event",
+    "ParseProblem",
+    "ParseResult",
+    "parse_stream",
+    "iter_events",
+    # outcomes
+    "FailureCategory",
+    "RunOutcome",
+    "normalize_reason",
+    "outcome_from_parse",
+    "redact",
+]

localcode-0.3.38/src/localcode/protocol/events.py

@@ -0,0 +1,116 @@
+"""Typed envelope + schema versioning for the `localcode run --json` stream.
+
+This is the single public definition of a LocalCode automation event. Both the
+native `eval/` harness and the Harbor plugin consume it through
+`localcode.protocol` — neither may re-interpret the raw stream itself (see the
+integration plan, §7.2.1). Keeping the envelope here means a schema change is a
+review of one file with one compatibility policy.
+
+Compatibility policy (semantic-version style, on the SCHEMA only):
+  • MAJOR — a breaking change to the meaning/shape of existing fields. A reader
+    built for major N MUST reject major N+1 rather than guess.
+  • MINOR — purely additive: new event types or new fields on existing events.
+    Older readers ignore what they don't recognise and keep working.
+So a reader accepts a stream iff `stream.major == reader.major`, regardless of
+minor. Unknown event types and unknown fields are always preserved verbatim on
+the `Event` so a newer producer never breaks an older consumer.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "SCHEMA_MAJOR",
+    "SCHEMA_MINOR",
+    "SCHEMA_VERSION",
+    "Event",
+    "SchemaVersion",
+    "UnsupportedSchemaError",
+]
+
+# The schema version this build of LocalCode emits and reads. Bump MINOR for
+# additive changes (new event types/fields); bump MAJOR only for a breaking
+# reshape of existing fields, and only with a documented deprecation.
+SCHEMA_MAJOR = 1
+SCHEMA_MINOR = 0
+SCHEMA_VERSION = f"{SCHEMA_MAJOR}.{SCHEMA_MINOR}"
+
+
+class UnsupportedSchemaError(Exception):
+    """Raised when a stream declares a MAJOR schema this reader can't interpret.
+
+    Explicit failure, never silent misinterpretation — a major bump means the
+    meaning of existing fields changed, so guessing would produce wrong metrics.
+    """
+
+    def __init__(self, found_major: int, reader_major: int = SCHEMA_MAJOR) -> None:
+        self.found_major = found_major
+        self.reader_major = reader_major
+        super().__init__(
+            f"stream schema major {found_major} is not readable by this build "
+            f"(supports major {reader_major}); upgrade localcode or the consumer"
+        )
+
+
+@dataclass(frozen=True)
+class SchemaVersion:
+    """A parsed `MAJOR.MINOR` schema version with a readable-by check."""
+
+    major: int
+    minor: int
+
+    @classmethod
+    def parse(cls, raw: Any) -> "SchemaVersion":
+        """Parse `1`, `"1"`, or `"1.0"` into a SchemaVersion.
+
+        A bare integer/`"1"` means major 1, minor 0. Anything unparseable is
+        treated as the baseline (1.0) rather than crashing the stream — the
+        stricter major-rejection happens in `readable_by`, driven by a value we
+        could actually parse.
+        """
+        s = str(raw).strip()
+        if not s:
+            return cls(SCHEMA_MAJOR, 0)
+        parts = s.split(".")
+        try:
+            major = int(parts[0])
+            minor = int(parts[1]) if len(parts) > 1 else 0
+        except (ValueError, IndexError):
+            return cls(SCHEMA_MAJOR, 0)
+        return cls(major, minor)
+
+    def readable_by(self, reader_major: int = SCHEMA_MAJOR) -> bool:
+        return self.major == reader_major
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}"
+
+
+@dataclass(frozen=True)
+class Event:
+    """One decoded stream record.
+
+    `type` and `payload` are always present; `payload` holds every field the
+    producer emitted for this record EXCEPT `type` (so unknown/future fields are
+    preserved verbatim, never dropped). `raw` keeps the exact source dict for
+    consumers that want lossless passthrough.
+    """
+
+    type: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_obj(cls, obj: dict[str, Any]) -> "Event":
+        etype = str(obj.get("type") or "")
+        payload = {k: v for k, v in obj.items() if k != "type"}
+        return cls(type=etype, payload=payload, raw=dict(obj))
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.payload.get(key, default)
+
+    @property
+    def is_terminal(self) -> bool:
+        """The single mandatory closing record of every run."""
+        return self.type == "result"

localcode-0.3.38/src/localcode/protocol/jsonl.py

@@ -0,0 +1,153 @@
+"""Incremental JSONL parser for the `localcode run --json` stream.
+
+Consumes the event stream one line at a time from a text or byte iterable
+without buffering the whole transcript, so a long agent run or a live process
+pipe never has to be held in memory. It is deliberately tolerant of the messy
+realities of a subprocess stream (partial final line after a kill, an
+occasional non-JSON line, non-UTF-8 bytes) up to a small threshold, while still
+surfacing genuine protocol violations (a missing or duplicated terminal event,
+an unreadable major schema) as structured problems rather than swallowing them.
+
+The parser NEVER decides whether a benchmark task passed. It reports what the
+stream said; grading lives in the caller's verifier (integration plan §9).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Iterator
+
+from .events import Event, SchemaVersion, UnsupportedSchemaError
+
+__all__ = ["ParseProblem", "ParseResult", "parse_stream", "iter_events"]
+
+# Stop tolerating junk once this many lines fail to decode — a stream that is
+# mostly noise is a real problem, not a stray line, and should be reported.
+_MAX_MALFORMED = 50
+
+
+@dataclass
+class ParseProblem:
+    """A non-fatal issue found while parsing, kept for diagnostics."""
+
+    kind: str          # "malformed_line" | "missing_terminal" | "duplicate_terminal" | "decode_error"
+    detail: str
+    line_no: int = 0
+
+
+@dataclass
+class ParseResult:
+    """Everything a consumer needs from one parsed run stream."""
+
+    events: list[Event] = field(default_factory=list)
+    schema: SchemaVersion | None = None
+    terminal: Event | None = None          # the mandatory `result` event, if present
+    problems: list[ParseProblem] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        """True when the stream was well-formed: a terminal event, no protocol problems."""
+        return self.terminal is not None and not any(
+            p.kind in {"missing_terminal", "duplicate_terminal"} for p in self.problems
+        )
+
+    def events_of(self, event_type: str) -> list[Event]:
+        return [e for e in self.events if e.type == event_type]
+
+
+def _to_text_lines(source: Iterable[Any]) -> Iterator[str]:
+    """Yield decoded text lines from a text- or byte-iterable.
+
+    Accepts an open file, a list of str/bytes, or any iterable of lines. Bytes
+    are decoded as UTF-8 with replacement so a stray non-UTF-8 byte degrades one
+    character instead of killing the stream. Handles the case of a single string
+    blob (splitlines) as well as a pre-split iterable.
+    """
+    if isinstance(source, (str, bytes)):
+        blob = source.decode("utf-8", "replace") if isinstance(source, bytes) else source
+        yield from blob.splitlines()
+        return
+    for line in source:
+        if isinstance(line, bytes):
+            yield line.decode("utf-8", "replace")
+        else:
+            yield str(line)
+
+
+def iter_events(source: Iterable[Any]) -> Iterator[Event]:
+    """Stream `Event`s lazily, skipping blank/malformed lines silently.
+
+    Use this for memory-bounded live consumption where you handle terminal /
+    schema logic yourself. Use `parse_stream` for a fully-checked result.
+    """
+    import json
+
+    for raw_line in _to_text_lines(source):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (ValueError, TypeError):
+            continue
+        if isinstance(obj, dict):
+            yield Event.from_obj(obj)
+
+
+def parse_stream(source: Iterable[Any]) -> ParseResult:
+    """Fully parse a run stream into a checked `ParseResult`.
+
+    - Decodes each line; a small number of malformed lines are recorded and
+      skipped, but crossing `_MAX_MALFORMED` records a `decode_error` problem.
+    - Reads `schema_version` from any record that carries it (typically the
+      leading `run_start`); a MAJOR mismatch raises `UnsupportedSchemaError`
+      rather than risk misreading reshaped fields.
+    - Requires exactly one terminal (`result`) event: zero → `missing_terminal`,
+      more than one → `duplicate_terminal`.
+    """
+    import json
+
+    result = ParseResult()
+    malformed = 0
+
+    for line_no, raw_line in enumerate(_to_text_lines(source), start=1):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (ValueError, TypeError) as exc:
+            malformed += 1
+            if malformed <= _MAX_MALFORMED:
+                result.problems.append(ParseProblem("malformed_line", str(exc), line_no))
+            elif malformed == _MAX_MALFORMED + 1:
+                result.problems.append(ParseProblem(
+                    "decode_error",
+                    f"more than {_MAX_MALFORMED} malformed lines; stream is likely not JSONL",
+                    line_no,
+                ))
+            continue
+        if not isinstance(obj, dict):
+            result.problems.append(ParseProblem("malformed_line", "line is not a JSON object", line_no))
+            continue
+
+        # Schema version can ride on any record; the first one we see wins and
+        # gates the whole stream. A major we can't read is a hard stop.
+        if result.schema is None and "schema_version" in obj:
+            sv = SchemaVersion.parse(obj.get("schema_version"))
+            if not sv.readable_by():
+                raise UnsupportedSchemaError(sv.major)
+            result.schema = sv
+
+        event = Event.from_obj(obj)
+        result.events.append(event)
+        if event.is_terminal:
+            if result.terminal is not None:
+                result.problems.append(ParseProblem(
+                    "duplicate_terminal", "more than one terminal 'result' event", line_no))
+            else:
+                result.terminal = event
+
+    if result.terminal is None:
+        result.problems.append(ParseProblem(
+            "missing_terminal", "stream ended with no terminal 'result' event"))
+    return result