The plugin contract, the model task and the tools roledesk imports, copied rather than reached through an editable install of news, which also exposes a package named pipeline. news stays the source of truth for desk. Refreshed from news/desk at a275c38a1aa0fe80a7ec7dd5781ecccf683f71c6 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
383 lines
18 KiB
Python
383 lines
18 KiB
Python
"""What newsdesk will interrupt you about, and the sentence it uses.
|
|
|
|
The generic half of this — the notice a failed job gets, the check that stops
|
|
it being said twice, the rendering a terminal wants — is `pipeline/notices.py`,
|
|
and the pipeline uses only that. This module is the half that could only be
|
|
newsdesk's: a catalogue of the ways *its* model backends, *its* feeds and *its*
|
|
config keys fail, and what to tell you to do about each.
|
|
|
|
`classify` is the interface. Everything else is the table it reads.
|
|
|
|
Deliberately string-matching rather than exception-type-matching. These errors
|
|
arrive as text through two SDKs and a subprocess, and half of them are
|
|
`ResultMessage.errors` from a CLI that owes us no stable exception hierarchy.
|
|
Matching prose is the honest reflection of that. The fallback is a notice that
|
|
still says something and is marked `bug` — because a failure nobody wrote a
|
|
rule for is one to go and read about, and the property that matters most is
|
|
that nothing fails silently.
|
|
|
|
`job_failed`, `already_said` and `render` are re-exported so that a caller
|
|
reaching for newsdesk's notices gets the whole vocabulary from one import
|
|
rather than having to know which half a given name lives in.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from collections.abc import Iterable
|
|
|
|
from pipeline.models import Notice, NoticeKind, NoticeLevel
|
|
from pipeline.notices import (
|
|
already_said, job_failed, render, whose_fault as _whose_fault,
|
|
)
|
|
|
|
log = logging.getLogger(__name__)
|
|
|
|
|
|
|
|
class Rule:
|
|
"""One row of the catalogue: how to recognise a failure and what to say.
|
|
|
|
`per_backend` exists for the one case where the same failure wants
|
|
genuinely different advice depending on who hit it. A 401 means "run
|
|
`claude auth login`" on the subscription path and "check your
|
|
ANTHROPIC_API_KEY" on the API one, and telling you to re-run a CLI login
|
|
when the problem is an environment variable is worse than saying nothing.
|
|
|
|
Its keys are usually the backend that ran. `agent.unreachable` is the
|
|
exception, because there nobody ran: the caller passes the configured
|
|
`agent.backend` instead, and `off` is a real answer that wants its own
|
|
sentence — "you turned this off" is not "you have nothing installed".
|
|
|
|
`standing` says the cause is the account or the machine rather than this
|
|
batch, so every sibling batch of the same run will be told exactly the
|
|
same thing. A spend limit does not lift between one call and the next and
|
|
a signed-out CLI does not sign itself back in; a timeout or a reply that
|
|
was not JSON says nothing at all about the next batch. It is what a run
|
|
reads to stop before it spends the other twenty-two calls — see
|
|
`stops_the_run`.
|
|
"""
|
|
|
|
__slots__ = ("code", "fix", "kind", "level", "patterns", "per_backend",
|
|
"standing", "text")
|
|
|
|
def __init__(self, code: str, level: NoticeLevel, kind: NoticeKind,
|
|
text: str, fix: str, patterns: Iterable[str],
|
|
per_backend: dict[str, tuple[str, str]] | None = None,
|
|
*, standing: bool = False) -> None:
|
|
self.code = code
|
|
self.level = level
|
|
self.kind = kind
|
|
self.text = text
|
|
self.fix = fix
|
|
self.patterns = tuple(patterns)
|
|
self.per_backend = per_backend or {}
|
|
self.standing = standing
|
|
|
|
def matches(self, error: str) -> bool:
|
|
return any(p in error for p in self.patterns)
|
|
|
|
def say(self, backend: str) -> tuple[str, str]:
|
|
return self.per_backend.get(backend, (self.text, self.fix))
|
|
|
|
|
|
#: The catalogue, most specific first — `classify` takes the first match, so
|
|
#: "out of credit" must be tried before the generic "the API refused".
|
|
#:
|
|
#: Two backends produce these and they word things differently, so most rules
|
|
#: carry patterns from both: `credit balance is too low` is the API's phrasing,
|
|
#: `usage limit reached` is the subscription CLI's, and they are the same
|
|
#: problem from where you are sitting.
|
|
#:
|
|
#: Every one of these is `expected`. That is not an accident — between them
|
|
#: they are the ways a model call fails when nothing is wrong with newsdesk,
|
|
#: and the point of enumerating them is precisely so that what falls through
|
|
#: can be called a bug with a straight face.
|
|
RULES: tuple[Rule, ...] = (
|
|
Rule(
|
|
"agent.auth", "error", "expected",
|
|
"Claude Code is signed out, so nothing that needs a model can run.",
|
|
# Two places, two fixes. At a keyboard the login is interactive; in the
|
|
# container there is nobody to prompt, so the CLI is authenticated by a
|
|
# token in the server's env file and that is the thing to replace. One
|
|
# line naming only the login sends whoever is holding the server to a
|
|
# command that cannot work where they are running it.
|
|
"Run `claude auth login` here, or paste a fresh token from "
|
|
"`claude setup-token` into Settings. New calls use it without a restart.",
|
|
("oauth", "unauthor", "authentication", "not logged in", "sign in",
|
|
"log in", "login", "expired", "401", "invalid_api_key",
|
|
"invalid api key", "could not resolve authentication"),
|
|
{"api": ("The Claude API rejected the key.",
|
|
"Check ANTHROPIC_API_KEY, or set agent.backend: claude_code "
|
|
"in config.yaml to use your subscription instead.")},
|
|
standing=True,
|
|
),
|
|
Rule(
|
|
"agent.credit", "error", "expected",
|
|
"The Claude API account is out of credit.",
|
|
"Top up at console.anthropic.com, or set agent.backend: claude_code "
|
|
"in config.yaml to use your subscription instead.",
|
|
("credit balance", "insufficient_quota", "insufficient quota",
|
|
"billing", "payment"),
|
|
standing=True,
|
|
),
|
|
# The subscription CLI has more than one way of saying "not until it
|
|
# resets", and the patterns have to carry all of them, because what falls
|
|
# through here is filed as a defect of ours. "You've hit your monthly
|
|
# spend limit · raise it at claude.ai/settings/usage?from=cc_cli_limit_
|
|
# message · your weekly limit resets 6am" matched none of the original
|
|
# words — `usage` occurs in it only inside the URL — so twenty-three
|
|
# batches of one run each reported a working machine as a bug. The text
|
|
# arrives verbatim from the CLI (`desk/tools/agent.py:_explain`), so
|
|
# matching its own words is the only thing there is to match.
|
|
Rule(
|
|
"agent.limit", "warning", "expected",
|
|
"Claude's usage limit is reached — tagging will pick up where it left "
|
|
"off once it resets.",
|
|
"Nothing to do; it resets on its own. A spend limit can be raised at "
|
|
"claude.ai/settings/usage.",
|
|
("usage limit", "spend limit", "spend cap", "limit reached",
|
|
"limit resets", "weekly limit", "monthly limit", "hourly limit",
|
|
"hit your limit", "rate_limit", "rate limit", "429",
|
|
"too many requests", "overloaded", "quota"),
|
|
standing=True,
|
|
),
|
|
# A refusal about the *rows*, not about us and not about the account. The
|
|
# platform runs a classifier over the request, and a news archive walks
|
|
# into it regularly: reporting on a worm or a supply-chain compromise is
|
|
# written in the vocabulary the classifier watches for, and an outlet that
|
|
# covers security covers it weekly.
|
|
#
|
|
# Deliberately not `standing`. The account is fine and the next batch is
|
|
# about different rows, so stopping the run here would throw away every
|
|
# abstract the rest of the backlog was about to get. What it costs instead
|
|
# is one split — see `modeltask.one`, which re-asks the batch in halves so
|
|
# the flagged row is found and charged rather than taking its batch-mates
|
|
# down with it.
|
|
Rule(
|
|
"agent.refused", "warning", "expected",
|
|
# Short, because the title is appended to it and the two together are
|
|
# what the band shows — on a phone, over the article being read. What
|
|
# it means and what to do are the fix's, which is behind `more` there
|
|
# and open in the log. It says "item" and not "abstract": tagging
|
|
# meets the same refusal.
|
|
"The model's safeguards refused this item",
|
|
# The URL spelled out rather than left to the raw error. The one
|
|
# decision this notice exists to inform — whether the verification is
|
|
# worth applying for — cannot be made from a line that says a link
|
|
# exists.
|
|
"Usually security reporting, and the item itself is still here and "
|
|
"readable. Nothing to do: after three tries it is left alone rather "
|
|
"than sent again on every pull, it is said on screen only the first "
|
|
"time, and Jobs & history lists it under Given up with a Try again. "
|
|
"These stop for an account that has applied to "
|
|
"Anthropic's Cyber Verification Program — "
|
|
"https://support.claude.com/en/articles/"
|
|
"14604842-real-time-cyber-safeguards-on-claude",
|
|
("[cyber]", "safeguards flagged", "cyber verification program",
|
|
"flagged by safeguards"),
|
|
),
|
|
Rule(
|
|
"agent.output", "warning", "expected",
|
|
"The model's answer was longer than agent.max_tokens allows, so the "
|
|
"batch came back with nothing.",
|
|
"Raise agent.max_tokens in config.yaml, or lower the task's batch_size "
|
|
"so there is less to answer in one call.",
|
|
("output token maximum", "max_output_tokens", "max output tokens",
|
|
"claude_code_max_output_tokens", "exceed your max_tokens"),
|
|
),
|
|
Rule(
|
|
"agent.key", "error", "expected",
|
|
"No Claude API key, and no local `claude` to fall back on.",
|
|
"Set ANTHROPIC_API_KEY, or install Claude Code and run "
|
|
"`claude auth login`.",
|
|
("no model backend", "anthropic sdk isn't installed",
|
|
"claude agent sdk isn't installed"),
|
|
standing=True,
|
|
),
|
|
# The two halves of what a job that cannot reach a model has to be able to
|
|
# say — "none is reachable" and "the one there is would not answer".
|
|
# (`docs/pipeline-levels.md` used to promise both; the file is gone and
|
|
# the promise is not.) Both used to fall past every rule into the
|
|
# fallback, so a scratch box with `backend: off` and a machine with no
|
|
# `claude` on PATH each reported every batch as a defect of ours and sent
|
|
# you to a traceback about a program that is working correctly.
|
|
Rule(
|
|
"agent.unreachable", "error", "expected",
|
|
"No model is reachable from here, so nothing that needs one can run.",
|
|
"Install Claude Code and run `claude auth login`, or set "
|
|
"ANTHROPIC_API_KEY.",
|
|
("no model is reachable",),
|
|
{"off": ("agent.backend is `off`, so nothing that needs a model runs.",
|
|
"Set agent.backend to `auto` in config.yaml, or name `api` "
|
|
"or `claude_code` outright.")},
|
|
standing=True,
|
|
),
|
|
Rule(
|
|
"agent.cli", "error", "expected",
|
|
"Claude Code is the backend, but there is no `claude` here to run.",
|
|
"Install the CLI — `irm https://claude.ai/install.ps1 | iex` on "
|
|
"Windows, `npm install -g @anthropic-ai/claude-code` elsewhere — or "
|
|
"point agent.cli_path at one in config.yaml.",
|
|
("claude code not found", "cli path not resolved"),
|
|
standing=True,
|
|
),
|
|
Rule(
|
|
"agent.timeout", "warning", "expected",
|
|
"The model didn't answer in time.",
|
|
"Usually a slow moment; it retries on the next run. Raise "
|
|
"agent.timeout in config.yaml if it keeps happening.",
|
|
("no answer within", "timeout", "timed out"),
|
|
),
|
|
Rule(
|
|
"agent.offline", "warning", "expected",
|
|
"Couldn't reach Claude — the network looks down.",
|
|
"",
|
|
("connection", "getaddrinfo", "name or service not known",
|
|
"temporary failure in name resolution", "network is unreachable",
|
|
"ssl", "certificate"),
|
|
),
|
|
Rule(
|
|
"agent.response", "warning", "bug",
|
|
"The model answered with something that wasn't the JSON asked for.",
|
|
"",
|
|
("no json object", "wasn't valid json", "wasn't a json object",
|
|
"returned no result"),
|
|
),
|
|
)
|
|
|
|
#: Where an unrecognised failure lands, and marked `bug` on purpose: the rules
|
|
#: above are the ways this fails when nothing is wrong, so falling past all of
|
|
#: them is itself the signal. Better to send you to the log for something that
|
|
#: turns out to be mundane than to file a real defect under "expected".
|
|
FALLBACK = Rule(
|
|
"agent.failed", "warning", "bug",
|
|
"A model call failed for a reason newsdesk doesn't recognise.",
|
|
"", (),
|
|
)
|
|
|
|
#: Exception names that mean the *remote end* misbehaved rather than that we
|
|
#: mishandled it. A feed that 403s or times out is news about the feed; a
|
|
#: KeyError parsing its XML is news about us. Everything not listed is treated
|
|
#: as ours, which is the safer default — a bug filed as expected is a bug that
|
|
#: never gets looked at.
|
|
|
|
|
|
def classify(error: BaseException | str, *, backend: str = "",
|
|
key: str = "") -> Notice:
|
|
"""The notice for a model-backend failure.
|
|
|
|
`backend` is folded into the sentence when it is known, because "Claude
|
|
Code is signed out" and "the API rejected the key" want different hands on
|
|
different keyboards, and the caller is the only one that knows which ran.
|
|
When nothing ran at all, the caller passes the configured `agent.backend`
|
|
instead — see `Rule.per_backend`.
|
|
"""
|
|
detail = str(error).strip()
|
|
rule = next((r for r in RULES if r.matches(detail.lower())), FALLBACK)
|
|
text, fix = rule.say(backend)
|
|
if rule is FALLBACK:
|
|
text = _unrecognised(backend, detail)
|
|
return Notice(
|
|
code=rule.code, level=rule.level, kind=rule.kind, text=text, fix=fix,
|
|
detail=detail, key=key, where="the tagging lines in the server log",
|
|
)
|
|
def stops_the_run(notice: Notice) -> bool:
|
|
"""Whether the rest of this run should be abandoned rather than attempted.
|
|
|
|
True for the failures a `Rule` marks `standing`: the ones caused by the
|
|
account or the machine, which will answer every sibling batch of the run
|
|
identically. The batch that met it has already failed; what this decides
|
|
is whether the twenty-two behind it are worth the calls.
|
|
|
|
It is a question about the notice rather than about the exception because
|
|
the notice is where the catalogue's judgement already is. A caller that
|
|
classified a failure to say something useful about it has, by then, been
|
|
told everything it needs to know about whether to carry on.
|
|
"""
|
|
return any(rule.code == notice.code and rule.standing for rule in RULES)
|
|
|
|
|
|
def source_failed(source: str, error: BaseException | str) -> Notice:
|
|
"""A subscription that blew up mid-fetch.
|
|
|
|
Keyed by source, so a feed that has been failing all week collapses into
|
|
one line rather than one per pull — and, more to the point, is *visible*,
|
|
which a source quietly returning nothing has never been. That is the one
|
|
failure you cannot spot by reading the feed: a dead source and a quiet news
|
|
day look identical.
|
|
|
|
One failure gets its own sentence, because the general one sends you the
|
|
wrong way. When YouTube refuses the machine the show's feed is fine, so
|
|
the Check job would report every subscription healthy; what is wrong is
|
|
the address the request left from. See `source_blocked`.
|
|
"""
|
|
if any(said in str(error).lower() for said in BLOCKED):
|
|
return source_blocked(source, error)
|
|
return Notice(
|
|
code="source.failed", level="warning", kind=_whose_fault(error),
|
|
key=source,
|
|
text=f"{source} failed to fetch — its items are missing from this pull.",
|
|
fix="Run the Check job to see which subscriptions still resolve.",
|
|
detail=str(error).strip(),
|
|
where=f"the `source {source} blew up mid-fetch` traceback in the log",
|
|
)
|
|
|
|
|
|
#: How `desk.tools.video.youtube.Blocked` reads once it is text. Matched as
|
|
#: prose like everything else here, and for one more reason: `notices` sits
|
|
#: below `tools` in the layering, so the type is not this module's to import.
|
|
BLOCKED = ("youtube refused",)
|
|
|
|
|
|
def source_blocked(source: str, error: BaseException | str) -> Notice:
|
|
"""A source YouTube would not serve, because of where the request came from.
|
|
|
|
Always `expected`: nothing in newsdesk is wrong, and the episodes are not
|
|
lost. They were deliberately not marked done, so the first pull from an
|
|
address YouTube accepts reads them. Until then this is said on every pull,
|
|
which is the point — it used to be an INFO line that retried for ever.
|
|
"""
|
|
return Notice(
|
|
code="source.blocked", level="warning", kind="expected", key=source,
|
|
text=f"YouTube refused {source} — it takes this address for a bot, "
|
|
"so no episodes were read.",
|
|
fix="Usually a VPN or a datacentre address: pull again without it. "
|
|
"Nothing is lost; unread episodes are tried on every pull.",
|
|
detail=str(error).strip(),
|
|
where=f"the `source {source} blew up mid-fetch` traceback in the log",
|
|
)
|
|
|
|
|
|
|
|
def _unrecognised(backend: str, detail: str) -> str:
|
|
"""The fallback's sentence, with the failure's own words in it.
|
|
|
|
It used to say only "failed for a reason newsdesk doesn't recognise",
|
|
which is true and useless. This is precisely the case where nobody wrote a
|
|
rule, so the raw text is the only thing anyone has to go on — and it was
|
|
reachable only by pressing `why` on a notice that fades in half a minute,
|
|
or by going to the log.
|
|
|
|
Trimmed to the first line and a screenful, because a stack trace does not
|
|
belong in a strip. `Notice.detail` still carries every character of it.
|
|
"""
|
|
who = _name(backend) if backend else "A model call"
|
|
said = detail.splitlines()[0].strip() if detail else ""
|
|
if len(said) > 160:
|
|
said = said[:159].rstrip() + "…"
|
|
if not said:
|
|
return f"{who} failed for a reason newsdesk doesn't recognise."
|
|
return f"{who} failed: {said}"
|
|
|
|
|
|
def _name(backend: str) -> str:
|
|
return {"api": "The Claude API",
|
|
"claude_code": "Claude Code"}.get(backend, backend or "The model")
|
|
|
|
|
|
__all__ = [
|
|
"BLOCKED", "FALLBACK", "RULES", "Rule", "already_said", "classify",
|
|
"job_failed", "render", "source_blocked", "source_failed", "stops_the_run",
|
|
]
|