Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
1 change: 1 addition & 0 deletions docs/system-specs/common/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ instead of the row simply disappearing.
| Integer field in a dashboard JSON body | Read through `dashboard/body_numbers.body_int`, which raises `ValueError` for `1e999`/`-1e999` (infinite floats after `json.loads`) where `int()` raises `OverflowError`. The handler's own `except (TypeError, ValueError)` then gives the infinite value the same 400 or fallback any other malformed value gets there, never a 500. A site does not add `OverflowError` to its own except clause instead |
| Skill index (`list_skills`) | One global SKILL.md that is not UTF-8 or cannot be opened → one warning naming the file, that row dropped, every other row listed. Never a failed listing: the index feeds every chat turn and `GET /api/skills`. Rationale: [memory-skills-hooks](../modules/memory-skills-hooks.md) |
| Process spawn | Backend-specific executable resolver, including trusted-path checks where required; clear error if missing |
| A host that does not answer (`kirocrew kas login`, the KAS engine manifest fetch) | The message names the host and leads with the cause in plain words. `asset_downloader.network_failure_cause` reads it from the exception types (urllib's `URLError.reason`, aiohttp's `os_error`), never their text: `connection refused`, `the host name could not be resolved` or `timed out`. Any other failure keeps the library's own text, which is then the only clue there is, and so does an aiohttp exception with no `host` (a connect timeout names its host only in its text) |
| Notes git subprocess (`md_notebook/git_ops.py`) | A non-zero exit reports git's last 3 stderr lines PLUS the first transport-caused line when one sits outside that tail. git ends every fetch/push failure with the same access-rights boilerplate and prints an SSH diagnosis first, so a tail alone reports a permission problem the operator does not have (a host reachable only via `~/.ssh/config` never resolved at all). The extra line widens what the message reports; it does not decide whether the command failed. |
| Auto-Improvement git step (`auto_improvement/backend/clone_setup.py`) | A failed clone, branch list, checkout or fetch reports git's last 2 stderr lines after dropping blank lines and git's access-rights advisory (`Please make sure you have the correct access rights` / `and the repository exists.`), redacted and then bounded. The advisory follows every transport or auth fatal, so keeping it reports a repository problem in place of the `Permission denied (publickey).` line above it. |
| App Store install clone, pinned fetch and pull (`apps/registry_pipeline/checkout.py`) | A credential-free (catalog or `index`-tier registry) fetch of an ssh remote whose output holds ssh's own `ssh: Could not resolve hostname` line returns `git_clone_failed_strict_ssh_route` with a fixed sentence: the fetch ran in the strict sandbox, which hides `~/.ssh`, so neither `~/.ssh/config` nor the ssh-agent applied, and a host reachable only through an ssh config route is installed from the operator's own clone with `kirocrew app install <dir>`. It carries no proxy hint, because ssh never reads `HTTPS_PROXY`; an owner-credentialed clone and an HTTPS remote keep the network hint. |
Expand Down
5 changes: 4 additions & 1 deletion src/kiro_crew/acp/kas_bundle.py
Original file line number Diff line number Diff line change
Expand Up @@ -391,7 +391,10 @@ def _read_json_url(url: str, opener: Any, *, sha256: str | None = None) -> Any:
except (OSError, ValueError) as exc:
# ValueError is urllib's answer to a url it cannot parse (an unclosed
# IPv6 bracket in a hand-typed --url), the same refusal as an unreachable one.
raise KasBundleError(f"could not fetch {asset_downloader.redact_url(url)}: {exc}") from exc
why = asset_downloader.network_failure_cause(exc) or exc
raise KasBundleError(
f"could not download the KAS engine from {asset_downloader.redact_url(url)}: {why}"
) from exc
if len(body) > _MANIFEST_MAX_BYTES:
raise KasBundleError(f"{asset_downloader.redact_url(url)} is too large to be a manifest")
if sha256 is not None and hashlib.sha256(body).hexdigest() != sha256:
Expand Down
18 changes: 18 additions & 0 deletions src/kiro_crew/asset_downloader.py
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@
import io
import logging
import os
import socket
import ssl
import stat
import time
Expand Down Expand Up @@ -348,6 +349,22 @@ def redact_url(url: str) -> str:
return "<unparseable-url>"


def network_failure_cause(exc: BaseException) -> str:
"""Why a connection failed, in a user's words, or ``""`` for any other failure.

Read from the exception types, never their text: urllib carries the socket
error in ``URLError.reason``, aiohttp in ``ClientConnectorError.os_error``.
"""
for err in (exc, getattr(exc, "reason", None), getattr(exc, "os_error", None)):
if isinstance(err, socket.gaierror):
return "the host name could not be resolved"
if isinstance(err, ConnectionRefusedError):
return "connection refused"
if isinstance(err, TimeoutError):
return "timed out"
return ""


#: ``O_BINARY`` exists only on Windows (where a text-mode descriptor translates
#: bytes); ``O_NOFOLLOW`` only on POSIX. Both read as 0 where absent.
_O_BINARY = getattr(os, "O_BINARY", 0)
Expand Down Expand Up @@ -1057,6 +1074,7 @@ def download_to(
"file_identity",
"install_verified",
"make_ssl_context",
"network_failure_cause",
"open_staging_nofollow",
"redact_url",
]
29 changes: 26 additions & 3 deletions src/kiro_crew/cli_kas_login.py
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,28 @@ def _login(args: argparse.Namespace) -> int:
return 130


def _unreachable(lead: str, exc: BaseException) -> str:
"""*lead*, the host and why in plain words, then what to do next.

The library's own text is the reason only when it is none of the causes
:func:`kiro_crew.asset_downloader.network_failure_cause` names, or when the
exception carries no host: aiohttp's connect timeout names it only in its
text (``Connection timeout to host <url>``).
"""
# Local for the reason _run_device_login gives: `--help` must not pay for it.
from kiro_crew.asset_downloader import network_failure_cause

host = getattr(exc, "host", "")
if host:
why = f" ({host}): {network_failure_cause(exc) or exc}"
else:
why = f": {str(exc) or network_failure_cause(exc)}"
return (
f"❌ {lead}{why}.\n"
" Nothing was stored. Check your network connection, then run the command again."
)


async def _run_device_login(
store: Any, *, provider: str, start_url: str, region: str, replaces: str = ""
) -> int:
Expand Down Expand Up @@ -257,7 +279,7 @@ async def _run_device_login(
print(f"❌ the sign-in service refused to start a sign-in: {exc}", file=sys.stderr)
return 1
except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
print(f"❌ could not reach the sign-in service: {exc}", file=sys.stderr)
print(_unreachable("could not reach the sign-in service", exc), file=sys.stderr)
return 1
# Line-buffered on purpose: the cloud sign-in reads these two lines out of
# a log this process writes under nohup, where stdout is block-buffered.
Expand All @@ -274,8 +296,9 @@ async def _run_device_login(
# The service absorbs a few dropped polls itself; past its budget
# the outage is real, and the user gets a line, not a traceback.
print(
f"❌ lost contact with the sign-in service while waiting for approval: "
f"{exc}; nothing was stored. Run the command again.",
_unreachable(
"lost contact with the sign-in service while waiting for approval", exc
),
file=sys.stderr,
)
return 1
Expand Down
42 changes: 42 additions & 0 deletions test/test_cli_kas_login.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@
from __future__ import annotations

import argparse
import errno
from datetime import datetime, timezone
from types import SimpleNamespace

import pytest

Expand Down Expand Up @@ -328,6 +330,46 @@ async def _drop(self, login_id):
assert "lost contact with the sign-in service" in err
assert "Traceback" not in err

def test_an_unreachable_sign_in_service_names_the_host_and_the_cause(
self, home_store, fake_service, capsys, monkeypatch
):
"""aiohttp's ``ssl:default [Multiple exceptions: [Errno 111] ...]`` is Python
internals: the user reads the host, the cause in plain words and what to do."""
import aiohttp

async def _refused(self, provider, **kwargs):
key = SimpleNamespace(host="oidc.us-east-1.amazonaws.com", port=443, ssl=True)
both = "Multiple exceptions: [Errno 111] Connect call failed ('::1', 443, 0, 0)"
raise aiohttp.ClientConnectorError(
key, ConnectionRefusedError(errno.ECONNREFUSED, both)
)

monkeypatch.setattr(fake_service, "begin_device", _refused)
assert cli_kas.kas_cmd(_parse("login")) == 1
assert capsys.readouterr().err == (
"❌ could not reach the sign-in service (oidc.us-east-1.amazonaws.com): "
"connection refused.\n"
" Nothing was stored. Check your network connection, then run the command again.\n"
)

def test_a_connect_timeout_keeps_the_host_its_text_names(
self, home_store, fake_service, capsys, monkeypatch
):
"""aiohttp's connect timeout carries no ``host``; its text is the one place that
names the host, so it stays the reason instead of a bare ``timed out``."""
import aiohttp

url = "https://oidc.us-east-1.amazonaws.com/client/register"

async def _slow(self, provider, **kwargs):
raise aiohttp.ConnectionTimeoutError(f"Connection timeout to host {url}")

monkeypatch.setattr(fake_service, "begin_device", _slow)
assert cli_kas.kas_cmd(_parse("login")) == 1
assert capsys.readouterr().err.startswith(
f"❌ could not reach the sign-in service: Connection timeout to host {url}.\n"
)

def test_a_sign_out_during_the_login_is_a_line_not_a_traceback(
self, home_store, fake_service, capsys, monkeypatch
):
Expand Down
28 changes: 27 additions & 1 deletion test/test_kas_bundle.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,17 @@

from __future__ import annotations

import errno
import hashlib
import io
import json
import logging
import os
import socket
import stat
import tarfile
import time
import urllib.error
from pathlib import Path
from unittest.mock import patch

Expand Down Expand Up @@ -239,9 +242,32 @@ def open(self, url, timeout):
def test_fetch_from_a_malformed_url_is_a_refusal_not_a_traceback(self):
"""urllib raises ValueError for a url it cannot parse; the operator typed it, so
the answer is the installer's one error type, which the CLI prints and exits."""
with pytest.raises(kas_bundle.KasBundleError, match="could not fetch"):
with pytest.raises(kas_bundle.KasBundleError, match="could not download the KAS engine"):
kas_bundle.fetch_manifest("https://[mirror", version="0.66.33")

@pytest.mark.parametrize(
"reason, cause",
[
(
ConnectionRefusedError(errno.ECONNREFUSED, "Connection refused"),
"connection refused",
),
(socket.gaierror("Name or service not known"), "the host name could not be resolved"),
(TimeoutError("timed out"), "timed out"),
],
)
def test_an_unreachable_host_is_named_with_the_cause_in_plain_words(self, reason, cause):
"""urllib's ``<urlopen error [Errno 111] Connection refused>`` is Python
internals; the installer prints this message as the whole failure."""

class _Opener:
def open(self, url, timeout):
raise urllib.error.URLError(reason)

with pytest.raises(kas_bundle.KasBundleError) as info:
kas_bundle.fetch_manifest("https://h.test", version="0.66.33", opener=_Opener())
assert str(info.value) == f"could not download the KAS engine from https://h.test: {cause}"

def test_fetch_pinned_version_must_match_the_document(self, source_dir):
class _Resp(io.BytesIO):
def __enter__(self):
Expand Down
Loading