Files
WolfandClaude Opus 5.5 248ea1636d Bring in desk from news
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>
2026-09-23 12:29:17 +02:00

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",
]