Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion libs/code/deepagents_code/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -6333,7 +6333,7 @@ async def _handle_version_command(self) -> None:
if report.sdk.status == "resolved":
from deepagents_code.update_check import format_sdk_age_suffix

sdk_version = report.sdk.primary_version
sdk_version = report.effective_sdk_version
sdk_age_suffix = await asyncio.to_thread(format_sdk_age_suffix, sdk_version)
sdk_annotation = format_sdk_version_annotation(report)
lines.append(
Expand Down
2 changes: 1 addition & 1 deletion libs/code/deepagents_code/doctor.py
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ def _sdk_diagnostic(report: VersionReport) -> tuple[str, bool]:
return "not installed", False
if sdk.status != "resolved":
return "unknown", False
value = f"{sdk.primary_version}{format_sdk_version_annotation(report)}"
value = f"{report.effective_sdk_version}{format_sdk_version_annotation(report)}"
return value, not report.sdk_requirement_mismatch


Expand Down
212 changes: 171 additions & 41 deletions libs/code/deepagents_code/extras_info.py
Original file line number Diff line number Diff line change
Expand Up @@ -212,7 +212,7 @@ class VersionReport:

Bundles the running CLI and installed SDK version facts with the result of
comparing the `deepagents` requirement that `deepagents-code` declares
against the installed SDK metadata version.
against the effective SDK version for diagnostics.
"""

cli: DistributionVersion
Expand All @@ -225,15 +225,20 @@ class VersionReport:
"""The `deepagents` requirement declared by `deepagents-code`, if found."""

sdk_requirement_satisfied: bool | None
"""Whether the installed SDK metadata satisfies `sdk_requirement`.
"""Whether the effective SDK version satisfies `sdk_requirement`.

`None` when the comparison cannot be made (no declared requirement, the SDK
is not installed, or an unparseable version).
"""

@property
def effective_sdk_version(self) -> str | None:
"""SDK version diagnostics should present as effective."""
return _effective_sdk_version(self.cli, self.sdk, self.sdk_requirement)

@property
def sdk_requirement_mismatch(self) -> bool:
"""Whether the installed SDK metadata violates the declared requirement."""
"""Whether the effective SDK version violates the declared requirement."""
# `is False`, not `not`: an inconclusive comparison (`None`) is *not* a
# mismatch. Collapsing this to `not self.sdk_requirement_satisfied` would
# silently report every unknown as a mismatch and flag doctor unhealthy.
Expand Down Expand Up @@ -436,29 +441,142 @@ def sdk_requirement_from_cli(
return None


def _exact_pin(requirement: Requirement | None) -> str | None:
"""Return the single `==` pin from `requirement`, if it has one."""
if requirement is None:
return None
specs = list(requirement.specifier)
if len(specs) == 1 and specs[0].operator == "==":
return specs[0].version
return None


def _parse_version(value: str | None) -> Version | None:
"""Parse a version string for best-effort diagnostic comparisons.

Returns:
The parsed version, or `None` when the input is absent or unparseable.
"""
if value is None:
return None
try:
return Version(value)
except InvalidVersion:
logger.debug("Could not parse version %r", value, exc_info=True)
return None


def _resolve_source_path(path: str | None) -> Path | None:
"""Resolve an editable source path for workspace-shape comparisons.

Returns:
The resolved path, or `None` when the path is absent or unusable.
"""
if path is None:
return None
try:
return Path(path).expanduser().resolve(strict=False)
except (OSError, RuntimeError, ValueError):
logger.debug("Could not resolve editable source path %r", path, exc_info=True)
return None


def _editable_sdk_is_cli_workspace_sibling(
cli: DistributionVersion, sdk: DistributionVersion
) -> bool:
"""Whether editable SDK and dcode installs are sibling monorepo packages.

Returns:
`True` for the known `<repo>/libs/code` and `<repo>/libs/deepagents`
checkout shape.
"""
if not cli.editable or not sdk.editable:
return False
cli_path = _resolve_source_path(cli.source_path)
sdk_path = _resolve_source_path(sdk.source_path)
if cli_path is None or sdk_path is None:
return False
return (
cli_path.name == "code"
and sdk_path.name == "deepagents"
and cli_path.parent == sdk_path.parent
and cli_path.parent.name == "libs"
)


def _uses_exact_requirement_as_effective_version(
cli: DistributionVersion, sdk: DistributionVersion, requirement: Requirement | None
) -> bool:
"""Whether an exact `deepagents-code` pin should override editable SDK markers.

Main does not track every SDK alpha release in `libs/deepagents`, so the
sibling SDK package in the same monorepo checkout can carry the previous
stable marker while `deepagents-code` intentionally declares a newer exact
alpha requirement. In that case the exact requirement is the better client
SDK generation for diagnostics. Ranged requirements and unrelated editable
SDK checkouts are never inferred this way.

Returns:
`True` when the exact pin is newer than every known editable SDK marker
and the SDK checkout is the monorepo sibling of the dcode checkout.
"""
if not _editable_sdk_is_cli_workspace_sibling(cli, sdk):
return False
pinned = _parse_version(_exact_pin(requirement))
if pinned is None:
return False
parsed_source = _parse_version(sdk.source_version)
parsed_metadata = _parse_version(sdk.metadata_version)
markers = [
parsed for parsed in (parsed_source, parsed_metadata) if parsed is not None
]
return bool(markers) and pinned > max(markers)


def _effective_sdk_version(
cli: DistributionVersion, sdk: DistributionVersion, requirement: Requirement | None
) -> str | None:
"""Return the SDK version diagnostics should treat as effective."""
pinned = _exact_pin(requirement)
if _uses_exact_requirement_as_effective_version(cli, sdk, requirement):
return pinned
Comment thread
robin-agent[bot] marked this conversation as resolved.
Resolved
return sdk.primary_version


def _sdk_requirement_comparison_version(
cli: DistributionVersion, sdk: DistributionVersion, requirement: Requirement | None
) -> str | None:
"""Return the SDK version to compare against the declared requirement."""
if sdk.status != "resolved":
return None
if sdk.editable:
return _effective_sdk_version(cli, sdk, requirement)
return sdk.metadata_version


def _requirement_satisfied(
requirement: Requirement | None, metadata_version: str | None
requirement: Requirement | None, version: str | None
) -> bool | None:
"""Return whether `metadata_version` satisfies `requirement`.
"""Return whether `version` satisfies `requirement`.

Args:
requirement: The declared requirement, or `None`.
metadata_version: The installed SDK metadata version, or `None`.
version: The SDK version to compare, or `None`.

Returns:
`True`/`False` when the comparison can be made, or `None` when either
input is absent or the version cannot be parsed. Prereleases are
allowed so a prerelease pin (e.g. `==0.7.0a7`) is evaluated
correctly.
"""
if requirement is None or metadata_version is None:
if requirement is None or version is None:
return None
try:
parsed = Version(metadata_version)
parsed = Version(version)
except InvalidVersion:
logger.debug(
"Could not parse SDK metadata version %r for requirement comparison",
metadata_version,
"Could not parse SDK version %r for requirement comparison",
version,
exc_info=True,
)
return None
Expand All @@ -470,16 +588,15 @@ def collect_version_report() -> VersionReport:

Returns:
A `VersionReport` bundling CLI and SDK version facts with the declared
`deepagents` requirement and whether the installed SDK metadata
`deepagents` requirement and whether the effective SDK version
satisfies it. Performs no network or subprocess calls.
"""
cli = collect_cli_version_info()
sdk = collect_sdk_version_info()
requirement = sdk_requirement_from_cli()
# Compare against the metadata version — what the environment actually
# installed — rather than the (possibly ahead) editable source version, so
# the mismatch reflects the real dependency resolution.
satisfied = _requirement_satisfied(requirement, sdk.metadata_version)
satisfied = _requirement_satisfied(
requirement, _sdk_requirement_comparison_version(cli, sdk, requirement)
)
return VersionReport(
cli=cli,
sdk=sdk,
Expand Down Expand Up @@ -541,51 +658,64 @@ def format_sdk_version_annotation(report: VersionReport) -> str:
report: The collected version report.

Returns:
A trailing ` (...)` suffix flagging an editable SDK install, any drift
between the source and installed metadata versions, and an
actionable requirement mismatch when the installed SDK metadata does
not satisfy the requirement declared by `deepagents-code`. Empty
A trailing ` (...)` suffix flagging an editable SDK install, raw
source/metadata facts when they differ from the effective version,
and an actionable requirement mismatch when the effective SDK version
does not satisfy the requirement declared by `deepagents-code`. Empty
when none applies.

The mismatch is judged against the installed SDK *metadata* version (what
the environment actually resolved), not the source version shown as primary
for editable installs. When the two differ, the accompanying
`installed metadata:` note makes that basis explicit, so an editable source
version that appears to match the requirement can still read as a mismatch.
"""
info = report.sdk
parts: list[str] = []
if info.editable:
parts.append("editable")
if info.has_drift and info.metadata_version is not None:
if (
info.editable
and info.source_version is not None
and info.source_version != report.effective_sdk_version
):
parts.append(f"editable source: {info.source_version}")
metadata_needs_annotation = info.has_drift or (
info.editable
and info.source_version is None
and info.metadata_version != report.effective_sdk_version
)
if metadata_needs_annotation and info.metadata_version is not None:
parts.append(f"installed metadata: {info.metadata_version}")
if report.sdk_requirement_mismatch and report.sdk_requirement is not None:
# Compared against `metadata_version` (see docstring), which is why the
# drift note above is emitted alongside so the basis is visible.
if (
report.sdk_requirement is not None
and _uses_exact_requirement_as_effective_version(
report.cli, info, report.sdk_requirement
)
):
required = _format_requirement_display(report.sdk_requirement)
parts.append(f"required by deepagents-code: {required}")
elif report.sdk_requirement_mismatch and report.sdk_requirement is not None:
required = _format_requirement_display(report.sdk_requirement)
parts.append(f"required by deepagents-code: {required} — mismatch")
return _join_annotation_parts(parts)


def resolve_sdk_version() -> tuple[str | None, DistributionMetadataStatus]:
"""Resolve the installed `deepagents` SDK version.
"""Resolve the effective `deepagents` SDK version.

Compatibility wrapper over `collect_sdk_version_info` for callers that only
need the primary version and lookup status. Editable installs can have stale
package metadata after local version files change, so they prefer the source
tree's `_version.py` and fall back to metadata when the source version is
unavailable. Distinguishes a genuinely missing package from an unexpected
metadata error so diagnostic callers can report the two differently, while
collapse-friendly callers can ignore the split.
Compatibility wrapper for callers that only need the effective SDK version
and lookup status. Editable installs can carry a stale stable marker on
`main`; when `deepagents-code` declares a newer exact SDK pin, that pin is
treated as the effective client SDK generation. Distinguishes a genuinely
missing package from an unexpected metadata error so diagnostic callers can
report the two differently, while collapse-friendly callers can ignore the
split.

Returns:
`(version, status)`. `version` is the resolved version string when
`status` is `"resolved"`, otherwise `None`.
"""
info = collect_sdk_version_info()
if info.status != "resolved":
return None, info.status
return info.primary_version, "resolved"
cli = collect_cli_version_info()
sdk = collect_sdk_version_info()
if sdk.status != "resolved":
return None, sdk.status
requirement = sdk_requirement_from_cli()
return _effective_sdk_version(cli, sdk, requirement), "resolved"


_EXTRA_MARKER_RE = re.compile(r"""extra\s*==\s*["']([^"']+)["']""")
Expand Down
2 changes: 1 addition & 1 deletion libs/code/deepagents_code/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ def build_version_text() -> str:
report = collect_version_report()
cli_annotation = format_cli_version_annotation(report.cli)
if report.sdk.status == "resolved":
sdk_version = report.sdk.primary_version
sdk_version = report.effective_sdk_version
sdk_annotation = format_sdk_version_annotation(report)
else:
sdk_version = "unknown"
Expand Down
39 changes: 37 additions & 2 deletions libs/code/tests/unit_tests/test_doctor.py
Original file line number Diff line number Diff line change
Expand Up @@ -122,13 +122,48 @@ def test_sdk_requirement_mismatch_is_unhealthy(self) -> None:
sdk=DistributionVersion(
"deepagents", "0.6.12", "0.6.12", True, "~/src/sdk", "resolved"
),
sdk_requirement=Requirement("deepagents==0.7.0a7"),
sdk_requirement=Requirement("deepagents>=0.7,<0.8"),
sdk_requirement_satisfied=False,
)
items = self._diagnostics(report)
sdk = items["deepagents (SDK)"]
assert sdk.ok is False
assert "required by deepagents-code: 0.7.0a7 — mismatch" in sdk.value
assert "required by deepagents-code: <0.8,>=0.7 — mismatch" in sdk.value

def test_newer_exact_sdk_pin_is_informational_for_editable_sdk(self) -> None:
"""A newer exact dcode pin is healthy for an editable main SDK checkout."""
from packaging.requirements import Requirement

from deepagents_code._version import __version__
from deepagents_code.extras_info import DistributionVersion, VersionReport

report = VersionReport(
cli=DistributionVersion(
"deepagents-code",
__version__,
__version__,
True,
"/repo/libs/code",
"resolved",
),
sdk=DistributionVersion(
"deepagents",
"0.6.12",
"0.6.12",
True,
"/repo/libs/deepagents",
"resolved",
),
sdk_requirement=Requirement("deepagents==0.7.0a8"),
sdk_requirement_satisfied=True,
)
items = self._diagnostics(report)
sdk = items["deepagents (SDK)"]
assert sdk.ok is True
assert sdk.value == (
"0.7.0a8 (editable; editable source: 0.6.12; "
"required by deepagents-code: 0.7.0a8)"
)

def test_source_metadata_drift_is_informational(self) -> None:
"""Source/metadata drift annotates the values but stays healthy."""
Expand Down
Loading
Loading