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

462 lines
20 KiB
Python

"""Who answers when a job needs a model.
There is one question this module exists to answer — *ask Claude this, get JSON
back* — and two ways to answer it. They are interchangeable, so a handler
asks without knowing which one ran:
api One call to the Claude API. Wants ANTHROPIC_API_KEY (or an
`ant auth login` profile). No local install, no subprocess,
per-token billing.
claude_code The Claude Agent SDK drives the `claude` CLI already on this
machine, on the subscription it is already signed in with.
No key, nothing to bill. This is what the server runs on
today, authenticated by CLAUDE_CODE_OAUTH_TOKEN.
`backend()` answers `""` when neither can run, and that is a failure rather
than a third way: the caller says so with a notice naming the reason — no
key, no CLI, `backend: off` — and the batch fails without asking anybody.
Nothing waits for a person to answer it by hand.
The seam is deliberately narrow: `ask_json` takes a system prompt, a payload
and a JSON schema, and returns parsed JSON. Both backends take the *same*
schema — the Agent SDK accepts the Messages API's `json_schema` output format
and hands the parsed object back on `ResultMessage.structured_output` — so
neither path is the degraded one, and moving between them is a config line
rather than a second implementation.
Both also *stream*, and hand the text out through `on_partial` as it arrives.
Nothing here does anything with it — this module still knows only "JSON in,
JSON out" — but a batch of twenty-five articles is one request that takes the
best part of a minute, and the answers inside it are finished one at a time
long before the request is. Passing the pieces up is what lets the layer that
knows what an answer looks like count them, and a progress bar move per
article instead of per batch.
What the `claude_code` backend deliberately does not get: no tools
(`tools=[]`), no filesystem settings (`setting_sources=None`, so no CLAUDE.md,
no skills, no MCP servers leak into a tagging call), no session to resume. One
text-in, JSON-out turn — the same shape as the API call it stands in for.
`thinking` is the one knob a caller turns, and it is stated to both backends
rather than left to either. It has to be: the CLI is built for agent work and
thinks unprompted, the Messages API thinks only when asked, so "say nothing"
means opposite things on the two sides. Saying `disabled` out loud is what
makes them the interchangeable pair this module claims — and it is worth
saying, because on a batch of twenty-five headlines the CLI's default cost
128s against 17s for the same tags. What to think about is the task's business
(`ModelTaskConfig.thinking`); making both backends agree on it is this one's.
"""
from __future__ import annotations
import importlib.util
import json
import logging
import os
from collections.abc import Callable
from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass, field
from typing import Any
from desk.config import AgentConfig
from desk.tools import credentials
log = logging.getLogger(__name__)
#: The backends `backend()` can name, best first. `auto` walks this list.
BACKENDS = ("api", "claude_code")
#: Where the answer goes as it arrives, a piece at a time. Called with raw
#: text, not parsed anything — half a JSON object is not a JSON object, and
#: what to make of a partial answer is the caller's business, not this
#: module's.
Partial = Callable[[str], None]
class AgentError(Exception):
"""The backend was there and the call still didn't produce an answer.
Raised for every failure mode of both paths — no SDK installed, no CLI on
PATH, an API error, a timeout, a response that isn't the shape asked for.
Callers treat it as "no answer this time", which for a job means either
moving on to the next batch or handing off to a human-driven agent.
"""
@dataclass(slots=True)
class Reply:
"""One answer, and enough about where it came from to say so in the UI."""
data: dict[str, Any]
backend: str = ""
model: str = ""
#: Filled by the `claude_code` path only, which is the reverse of what you
#: would expect: the SDK's `ResultMessage` prices the turn, so a
#: subscription that is billed nothing for it still reports a figure, while
#: the API path — the one actually billed — leaves this at zero because the
#: Messages response does not price itself. An estimate of what the run
#: would have cost on the API, then, and never a bill. `usage` is the field
#: to trust if you want to price it yourself.
cost_usd: float = 0.0
usage: dict[str, Any] = field(default_factory=dict)
# ------------------------------------------------------------ which backend
def has_api_credentials() -> bool:
"""Whether the API path can run unattended.
An unset ANTHROPIC_API_KEY isn't proof there are no credentials — the SDK
also reads ANTHROPIC_AUTH_TOKEN and an `ant auth login` profile — but env
vars are the only part we can check without importing the SDK.
"""
return any(os.environ.get(name) for name in (
"ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_PROFILE",
))
def has_claude_code() -> bool:
"""Whether the Agent SDK is here, and so whether there is a CLI to drive.
The SDK bundles its own `claude`, so having the package is enough — a
binary on PATH is a bonus, not a requirement, and checking for one would
wrongly rule out a machine where the SDK is the only install.
Not proof the call will work — the CLI may be signed out — but it is the
check that can be made in microseconds, which is what a job asking "can I
do this myself?" needs. A signed-out CLI surfaces as an `AgentError` on
the call, and the caller falls back exactly as if this had returned False.
"""
return importlib.util.find_spec("claude_agent_sdk") is not None
def backend(settings: AgentConfig) -> str:
"""Which backend will answer, or `""` for nobody.
`agent.backend: auto` prefers the API when there are credentials, because
that is the unattended path and the one production will use; it falls back
to the local Claude Code subscription, which is the one that costs nothing
while you are building. Naming a backend skips the detection — including
`off`, which is how you make everything that wants a model fail.
"""
want = settings.backend
if want == "off":
return ""
if want in BACKENDS:
return want
if has_api_credentials():
return "api"
if has_claude_code():
return "claude_code"
return ""
# ------------------------------------------------------------------ the ask
def _thinking(setting: str) -> Any:
"""One `thinking` setting in the form both SDKs take.
Returns `Any` on purpose. Each SDK declares its own TypedDict for the same
two-word object — `ThinkingConfigDisabledParam` on one side,
`ThinkingConfigDisabled` on the other — and neither can be named here
without importing an SDK this module is careful to keep optional. One
honest `Any` at the seam beats a hard dependency at the top of the file.
Anything that is not a mode we offer is off, rather than an error. This is
reached from config pydantic has already constrained to the same two words,
so a third one arriving here would be a bug in our own plumbing — and the
honest answer to that is the same one the default gives, not a failed run
the model would happily have answered.
"""
return {"type": "adaptive"} if setting == "adaptive" else {"type": "disabled"}
def ask_json(
settings: AgentConfig,
*,
system: str,
question: dict[str, Any],
schema: dict[str, Any],
model: str = "",
using: str = "",
thinking: str = "off",
on_partial: Partial | None = None,
) -> Reply:
"""Ask Claude `question`, constrained to `schema`, and parse the answer.
`system` is expected to be byte-identical across the calls in a run — it is
what the API path caches. `question` is the part that changes. `using`
forces a backend for one call; otherwise `backend()` decides. `thinking` is
`off` or `adaptive`, and defaults to off because the caller who wants it is
rarer than the caller who would be surprised to be waiting for it.
`on_partial` is called with each piece of the answer as it arrives, in
order, on the thread this was called on. It is a courtesy, not a contract:
a backend that cannot stream simply never calls it, and the return value
is the same either way.
"""
name = using or backend(settings)
model = model or settings.model
if thinking == "adaptive" and model.startswith(
("claude-haiku-4-5", "claude-sonnet-4-5", "claude-opus-4-5")):
# These models support manual extended thinking only; fail before spend.
# https://platform.claude.com/docs/en/build-with-claude/extended-thinking
raise AgentError(f"{model} does not support adaptive thinking; set thinking: off "
"or choose a model supporting adaptive thinking")
if not name:
raise AgentError("no model backend is available")
if name == "api":
return _ask_api(settings, system, question, schema, model, thinking, on_partial)
if name == "claude_code":
return _ask_claude_code(settings, system, question, schema, model, thinking,
on_partial)
raise AgentError(f"unknown backend {name!r}")
def _ask_api(settings: AgentConfig, system: str, question: dict[str, Any],
schema: dict[str, Any], model: str, thinking: str = "off",
on_partial: Partial | None = None) -> Reply:
try:
import anthropic
except ImportError as exc:
raise AgentError(
"the anthropic SDK isn't installed — `uv pip install anthropic`"
) from exc
try:
client = anthropic.Anthropic(timeout=settings.timeout)
# Streamed rather than awaited whole, always — not only when someone
# passed `on_partial`. One code path is worth more than the few lines a
# non-streaming branch would save, and a minute-long request held open
# by a single response is the shape that trips idle timeouts in
# whatever sits between here and the API.
with client.messages.stream(
model=model,
max_tokens=settings.max_tokens,
system=[{
"type": "text",
"text": system,
# The instructions are byte-identical across every batch and
# every run; only the payload below changes.
"cache_control": {"type": "ephemeral"},
}],
messages=[{"role": "user", "content": _dumps(question)}],
thinking=_thinking(thinking),
output_config={"format": {"type": "json_schema", "schema": schema}},
) as stream:
for event in stream:
if on_partial is not None and (piece := _delta(event)):
on_partial(piece)
response = stream.get_final_message()
except (anthropic.APIError, TypeError) as exc:
# The status code carried through in the text on purpose: it is what
# `notices.classify` reads to tell "your key is wrong" (401) apart from
# "you are being rate limited" (429), which want different reactions
# from you and which the message body alone does not always separate.
status = getattr(exc, "status_code", "")
raise AgentError(
f"the API call failed: {f'{status} ' if status else ''}{exc}") from exc
text = next((b.text for b in response.content if b.type == "text"), "")
return Reply(
data=_parse(text),
backend="api",
model=response.model or model,
usage=response.usage.model_dump() if response.usage else {},
)
def _ask_claude_code(settings: AgentConfig, system: str, question: dict[str, Any],
schema: dict[str, Any], model: str, thinking: str = "off",
on_partial: Partial | None = None) -> Reply:
try:
from claude_agent_sdk import (
ClaudeAgentOptions, ClaudeSDKError, ResultMessage, StreamEvent, query,
)
except ImportError as exc:
raise AgentError(
"the Claude Agent SDK isn't installed — "
"`uv pip install claude-agent-sdk`"
) from exc
options = ClaudeAgentOptions(
system_prompt=system,
model=model or None,
# A classification call, not an agent: nothing to run, nothing to
# read, and no project settings — so no CLAUDE.md, no skills and no
# MCP servers get in front of the model on the way to a tag list.
tools=[],
allowed_tools=[],
permission_mode="dontAsk",
setting_sources=None,
# Always stated, never left to the CLI's default, which is on. With
# it on the progress bar also stops meaning anything: thinking emits
# nothing `_Answered` can count, so a chunk streams no `"uid"` until
# the thinking is done, and the bar sits on the previous chunk's
# number until the answer arrives in a rush.
thinking=_thinking(thinking),
output_format={"type": "json_schema", "schema": schema},
# Only when someone is listening. The partials are the same bytes as
# the final answer sent again in pieces, and asking the CLI for them
# when nothing reads them is noise on the pipe for no one's benefit.
include_partial_messages=on_partial is not None,
cli_path=settings.cli_path or None,
# `max_tokens` has to mean the same thing on both backends or it means
# nothing. The Messages API takes it as a parameter and the CLI takes
# it only as an environment variable, so without this the setting was
# quietly API-only — which is how a call configured for 8,192 tokens
# answered with 11,706 and nothing objected. The SDK merges this into
# the inherited environment rather than replacing it, so naming one
# variable does not cost the CLI its PATH.
env={"CLAUDE_CODE_MAX_OUTPUT_TOKENS": str(settings.max_tokens),
**({"CLAUDE_CODE_OAUTH_TOKEN": oauth} if (oauth := credentials.token(settings)) else {})},
stderr=lambda line: log.debug("claude: %s", line.rstrip()),
)
async def ask() -> Reply:
answer: Reply | None = None
async for message in query(prompt=_dumps(question), options=options):
if isinstance(message, StreamEvent) and on_partial is not None:
piece = _delta(message.event)
if piece:
on_partial(piece)
continue
if not isinstance(message, ResultMessage):
continue
if message.is_error:
raise AgentError(_explain(
"; ".join(message.errors or []) or message.result
or f"the agent ended as {message.subtype}"))
data = message.structured_output
if not isinstance(data, dict):
# A run that ended without structured output — a limit, an
# interruption. `result` is the raw text if there is any, and
# that is worth one attempt at parsing before giving up.
data = _parse(message.result or "")
answer = Reply(
data=data,
backend="claude_code",
model=model,
cost_usd=message.total_cost_usd or 0.0,
usage=message.usage or {},
)
if answer is None:
raise AgentError("the agent returned no result")
return answer
try:
return _sync(ask(), settings.timeout)
except ClaudeSDKError as exc:
# The SDK has its own exception hierarchy — a CLI that exited, a line
# it could not parse, an answer that overran `max_tokens` — and none of
# it is an `AgentError`. Left alone those escape the per-chunk `except
# AgentError` in `with_model`, so one bad chunk takes down a run that
# is contractually supposed to leave its rows for next time. Every
# failure of this backend is an `AgentError` or none of them are.
#
# The text is passed through intact rather than summarised: `notices`
# matches on prose, by its own deliberate design, so the wording *is*
# the thing that decides which sentence you get told.
raise AgentError(_explain(str(exc))) from exc
# --------------------------------------------------------------- plumbing
def _field(event: Any, name: str) -> Any:
"""One field of a stream event, whichever shape it arrived in.
The two backends carry the same events in different clothes: the API SDK
parses them into objects, and the CLI passes the wire format straight
through as dicts. Reading both through here is what lets `_delta` be
written once.
"""
return event.get(name) if isinstance(event, dict) else getattr(event, name, None)
def _delta(event: Any) -> str:
"""The answer text one stream event carries, or "" for the many with none.
The events worth anything here are `content_block_delta`, whose delta is
`text` for a plain answer and `partial_json` when the schema is enforced
through a tool. Everything else — message start and stop, block
boundaries, usage — is dropped.
Deliberately reads defensively rather than by type. An event shape nobody
here recognises must be nothing, not an exception: this drives a progress
bar, and it does not get to fail a run the model is answering correctly.
"""
if _field(event, "type") != "content_block_delta":
return ""
delta = _field(event, "delta")
if delta is None:
return ""
piece = _field(delta, "text") or _field(delta, "partial_json") or ""
return piece if isinstance(piece, str) else ""
def _sync(coro: Any, timeout: float) -> Reply:
"""Run one coroutine to completion from synchronous code.
Jobs are synchronous by design and the worker runs them on a thread, so
there is normally no loop here and `asyncio.run` is exactly right. The
thread pool is for the other caller — anything asking from inside a
running loop, where `asyncio.run` would raise.
"""
import asyncio
async def bounded() -> Reply:
try:
return await asyncio.wait_for(coro, timeout)
except TimeoutError as exc:
raise AgentError(f"no answer within {timeout:g}s") from exc
try:
asyncio.get_running_loop()
except RuntimeError:
return asyncio.run(bounded())
with ThreadPoolExecutor(max_workers=1) as pool:
return pool.submit(asyncio.run, bounded()).result()
def _explain(error: str) -> str:
"""Keep the raw failure text intact for the layer that classifies it.
This used to append advice ("the `claude` login looks expired, run…"),
which was the right instinct in the wrong place: the message was built here
and then swallowed three frames up by a `except AgentError: continue`, so
the advice never reached anyone. Recognising the failure and deciding what
to say about it now lives in `desk/notices.py`, which has somewhere to
put the answer.
What stays here is the part only this module knows: the CLI can end a run
with an empty error and a subtype, and "" is not something to classify.
"""
return error.strip() or "the agent ended without saying why"
def _dumps(payload: dict[str, Any]) -> str:
return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
def _parse(text: str) -> dict[str, Any]:
"""The answer as a dict. Tolerant of a fenced or chatty response.
Both backends are asked for JSON through a schema, so this should be a
plain `json.loads`. It isn't, because "should be" is not a guarantee worth
losing a batch over — a model that wrapped its answer in a code fence has
still done the work.
"""
body = text.strip()
if body.startswith("```"):
body = body.split("\n", 1)[-1].rsplit("```", 1)[0]
start, end = body.find("{"), body.rfind("}")
if start == -1 or end <= start:
raise AgentError(f"no JSON object in the response: {text[:200]!r}")
try:
data = json.loads(body[start:end + 1])
except ValueError as exc:
raise AgentError(f"the response wasn't valid JSON: {exc}") from exc
if not isinstance(data, dict):
raise AgentError("the response wasn't a JSON object")
return data