Coverage for src/keel/delegate.py: 100%
308 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 19:17 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 19:17 +0000
1"""How keel invokes a delegate — the pure planner behind ``keel delegate run`` (#1012).
3Nothing in keel dispatched a delegate. ``api_delegate.generate()`` had no caller; the
4``claude``/``codex``/``agy`` argv shapes, the stdin framing, the Ollama endpoint, the
5timeouts and the JSON return contract lived only as prose in ``ship.md`` s4/s7, so every
6host agent re-invented them and they drifted. This module is the single answer to *how do
7I invoke provider P for role R*, and :mod:`keel.delegaterun` is the only thing that runs
8the answer.
10The split is keel's usual one. Everything here is **pure**: it takes a
11:class:`keel.providers.Provider` (from #1011's registry) plus a role, and returns a frozen
12:class:`RunPlan` — an argv, or an HTTP request description, plus the stdin framing, the
13read-only verdict, the attribution record and any warnings. No subprocess, no network, no
14clock, no filesystem. That is what makes "a ``review`` run never carries a write-enabling
15flag" a property a unit test can assert per vendor instead of a sentence in a markdown
16file nobody can execute.
18**Role policy.** ``review``/``gate``/``chair`` are read-only: the delegate reads a diff
19and returns findings, and every mutation stays with the orchestrator. ``implement``/``fix``
20are tool-enabled. keel can *document* a read-only invocation for the three built-in CLIs
21and *offer* one (``review_args``) for a configured profile; it cannot **enforce** read-only
22for an arbitrary binary, which is why :attr:`RunPlan.read_only` reports the role's policy
23and a warning names the case where nothing backs it.
25**Why the prompt is never in argv.** Every transport that runs a binary delivers the
26prompt on stdin. A prompt carries the diff and the brief; an argv is world-readable in
27``ps`` for the life of the process, and a large diff can exceed ``ARG_MAX`` outright. The
28one exception is a profile that declares ``prompt_mode: arg`` — an operator-authored
29choice for CLIs whose usage requires it (``cursor-agent``'s is
30``agent [options] [command] [prompt...]``), where the plan carries ``stdin_mode: None`` and
31the executor appends the prompt as the final argument.
33**agy's framing.** ai-jury (``src/ai_jury/adapters.py``, read-only reference) verified two
34invocations against the shipped CLI: ``--print=<prompt>``, which takes the prompt as the
35flag's *value* because ``--print --model X`` swallows the next flag; and
36``--input-format stream-json --output-format stream-json``, which reads one NDJSON frame
37per line on stdin. keel takes the **stream-json** one. Three reasons, in order: the prompt
38stays out of ``ps`` and out of ``ARG_MAX`` (ai-jury's #287); it sidesteps the ``--print``
39arity trap entirely rather than working around it; and — decisively for this module — a
40*pure* planner is handed a prompt **path**, never the prompt text, so it could not build a
41``--print=<prompt>`` argv at all without reading a file and stopping being pure. The
42NDJSON reply is parsed back by :func:`parse_stream_json`.
44Pure and deterministic: no wall-clock, no randomness, no I/O. Failures raise
45:class:`DelegateError`, which carries a machine-readable ``code`` the executor turns into
46the fail-soft ``error_code`` of the JSON contract — a traceback never reaches an operator.
47"""
49from __future__ import annotations
51import json
52import posixpath
53import re
54from dataclasses import dataclass, field
55from typing import Any
57from . import agents
58from . import providers as providers_mod
59from .api_delegate import DEFAULT_MAX_TOKENS, OPENAI_COMPATIBLE
60from .config import DEFAULT_PROMPT_MODE, DelegateProfile
62# The effort vocabulary lives in the leaf :mod:`keel.vocab` so ``keel.team`` can validate
63# a seat's ``effort`` without importing the executor (#1050). ``EFFORT_VENDORS`` and
64# ``supports_effort`` are re-exported under the original names, which are what the rest
65# of the package and the tests read.
66from .vocab import EFFORT_VENDORS as EFFORT_VENDORS
67from .vocab import EFFORTS as EFFORTS
68from .vocab import supports_effort as supports_effort
70#: The module's public surface, in definition order (#1070). It is declared because the
71#: ``X as X`` re-exports above are read from *other* modules — a use CodeQL's
72#: ``py/unused-import`` cannot see, since it counts same-module uses only. A name listed
73#: in ``__all__`` is used by definition, so the declaration answers the scanner with the
74#: language's own statement of intent rather than with a dismissal. Being a real
75#: declaration it has to be the *whole* surface, not the re-exports alone;
76#: ``tests/test_reexport_surface.py`` holds it to that in both directions.
77__all__ = [
78 "EFFORT_VENDORS",
79 "EFFORTS",
80 "supports_effort",
81 "ROLES",
82 "READ_ONLY_ROLES",
83 "TRANSPORTS",
84 "STDIN_TEXT",
85 "STDIN_STREAM_JSON",
86 "DEFAULT_TIMEOUT_S",
87 "DEFAULT_QUOTA_WAIT_S",
88 "OLLAMA_GENERATE_URL",
89 "AGY_STREAM_ARGS",
90 "CLAUDE_ALLOWED_TOOLS",
91 "CODEX_EFFORT_CONFIG",
92 "ANTHROPIC_THINKING_BUDGET",
93 "GOOGLE_THINKING_BUDGET",
94 "THINKING_HEADROOM_TOKENS",
95 "DelegateError",
96 "Resolution",
97 "Effort",
98 "RunPlan",
99 "resolve_provider",
100 "is_safe_body_model_token",
101 "model_reaches_argv",
102 "model_token_issue",
103 "is_absolute_cwd",
104 "plan_run",
105 "stream_json_frame",
106 "parse_stream_json",
107 "parse_ollama_response",
108 "ollama_payload",
109]
111#: Roles a delegate can be dispatched for. ``chair`` is the jury's summariser; it reads
112#: reviews and writes nothing, so it sits with the read-only three.
113ROLES = ("implement", "fix", "review", "gate", "chair")
115#: Roles invoked read-only / findings-only. Everything not listed here is tool-enabled.
116READ_ONLY_ROLES = ("review", "gate", "chair")
118#: How the executor reaches a provider. ``cli`` is one of the three built-in agent CLIs,
119#: ``profile`` any other binary (a project ``delegate_profiles`` entry or a registry
120#: ``cli``/``local`` entry), ``api`` a hosted or OpenAI-compatible HTTP endpoint, and
121#: ``ollama`` the built-in local vendor served on loopback.
122TRANSPORTS = ("cli", "profile", "api", "ollama")
124#: Prompt framing on the child's stdin. ``None`` means "no stdin": the executor appends
125#: the prompt as the final argv element (a profile's ``prompt_mode: arg``).
126STDIN_TEXT = "text"
127STDIN_STREAM_JSON = "stream-json"
129#: Wall-clock seconds a delegate run may take when the caller names none. Delegated
130#: implementation is measured in tens of minutes, not in the 120 s a git call gets.
131DEFAULT_TIMEOUT_S = 1800
133#: Default maximum seconds to back off and retry on retryable quota errors (#1549).
134DEFAULT_QUOTA_WAIT_S = 60
136#: Ollama's local generation endpoint. A **hardcoded loopback constant**, exactly like
137#: :data:`keel.providers.OLLAMA_TAGS_URL` and every other URL keel dials: the executor
138#: never reaches an endpoint named by config or by the registry.
139OLLAMA_GENERATE_URL = "http://127.0.0.1:11434/api/generate"
141#: agy's NDJSON stdin/stdout framing. See the module docstring for why keel uses it
142#: rather than ``--print=<prompt>``.
143AGY_STREAM_ARGS = ("--input-format", "stream-json", "--output-format", "stream-json")
145#: A Windows absolute path (``C:\\wt`` / ``C:/wt``) or a UNC share (``\\\\host\\share``).
146#: ``posixpath.isabs`` says False for both, and a plan is a document that may be read
147#: on a platform other than the one that wrote it.
148_WINDOWS_ABSOLUTE = re.compile(r"^(?:[A-Za-z]:[\\/]|\\\\)")
150#: The only tools a read-only ``claude`` invocation may use. An **allow-list**: a denylist
151#: of write tools has to be extended every time the CLI grows one, and is wrong in the
152#: window before someone notices. Reading a diff needs no more than these three — ``Glob``
153#: is how the current CLI lists a directory, so there is no separate listing tool to name.
154CLAUDE_ALLOWED_TOOLS = "Read,Grep,Glob"
156#: How ``codex`` spells reasoning effort. Not a flag on the shipped CLI (0.152.1) — it is
157#: a config override, and an unknown key is rejected under ``--strict-config``, which is
158#: how this spelling was verified rather than assumed.
159CODEX_EFFORT_CONFIG = "model_reasoning_effort"
161#: ``anthropic-api`` extended-thinking budget per effort level, in tokens.
162ANTHROPIC_THINKING_BUDGET = {"low": 2048, "medium": 8192, "high": 32768}
164#: ``google-api`` ``thinkingBudget`` per effort level, in tokens. Gemini's floor is lower
165#: than Claude's, so ``low`` is 1024 rather than 2048.
166GOOGLE_THINKING_BUDGET = {"low": 1024, "medium": 8192, "high": 32768}
168#: Room left for the answer *above* a thinking budget. Anthropic requires
169#: ``max_tokens > thinking.budget_tokens``; a budget of 32768 against the default 16384
170#: cap is rejected by the API before a token is generated.
171THINKING_HEADROOM_TOKENS = 4096
173#: Suffixes agy spells reasoning effort with, e.g. ``gemini-3.8-flash-high``.
174_EFFORT_SUFFIXES = tuple(f"-{level}" for level in EFFORTS)
177class DelegateError(Exception):
178 """A run that cannot be planned. ``code`` is the JSON contract's ``error_code``."""
180 def __init__(self, code: str, message: str) -> None:
181 super().__init__(message)
182 self.code = code
183 self.message = message
186@dataclass(frozen=True)
187class Resolution:
188 """Which provider a ``--provider`` token names, and the model it carries."""
190 provider: providers_mod.Provider
191 #: The project ``delegate_profiles`` entry behind a ``profile``-source provider.
192 #: :class:`keel.providers.Provider` keeps only ``review_args``, so the implementer's
193 #: ``args`` and the ``prompt_mode`` are reachable only through the profile itself.
194 profile: DelegateProfile | None = None
195 #: The per-run model from ``vendor:model``, already validated. ``None`` when the
196 #: token named no model.
197 model: str | None = None
200@dataclass(frozen=True)
201class Effort:
202 """How one ``--effort`` request landed on one vendor.
204 Returned as a record rather than a tuple because the *budget* is needed twice and in
205 two shapes: inside the vendor's payload fragment, and again as the number
206 ``max_tokens`` must exceed. Re-deriving it by digging back into the fragment means
207 one parser per vendor spelling, with branches nothing can reach.
208 """
210 model: str | None
211 payload: dict[str, Any]
212 #: Thinking-token budget the fragment asks for, ``None`` when it asks for none.
213 budget: int | None
214 applied: bool
215 warnings: tuple[str, ...]
216 #: Extra argv fragment, for a vendor that spells effort on its command line.
217 argv: tuple[str, ...] = ()
220@dataclass(frozen=True)
221class RunPlan:
222 """One fully-resolved delegate invocation. Frozen, JSON-stable, never executed here."""
224 provider: str
225 #: The vendor attribution names — a built-in's own token, or a profile/registry
226 #: entry's ``vendor_label`` when it declares one (#1129). Before that field existed
227 #: this said ``cli`` for *every* configured CLI, so two entries driving different
228 #: makers through one binary were indistinguishable here and in the label derived
229 #: from it. Which executor runs the plan stays in :attr:`transport`
230 #: (``cli``/``profile``/``api``/``ollama``); a declared label costs the finer
231 #: ``cli``-vs-``local`` split, which no caller branches on — both are run as a
232 #: configured binary.
233 vendor: str
234 role: str
235 transport: str
236 prompt_path: str = ""
237 model: str | None = None
238 cwd: str | None = None
239 timeout: int = DEFAULT_TIMEOUT_S
240 #: The command line, **without** the prompt. Empty for ``api``/``ollama``.
241 argv: tuple[str, ...] = ()
242 #: The HTTP call description for ``api``/``ollama``; ``None`` for the argv transports.
243 request: dict[str, Any] | None = None
244 #: ``text`` | ``stream-json`` | ``None`` (append the prompt as the last argv element).
245 stdin_mode: str | None = None
246 #: True when the role's policy is read-only.
247 read_only: bool = False
248 #: True when something actually **backs** that policy: a built-in CLI's documented
249 #: read-only invocation, an operator's ``review_args``, or a transport with no tools
250 #: at all. False means the role says read-only and nothing enforces it — the caller
251 #: must decide whether to run at all. Split from :attr:`read_only` because a single
252 #: flag cannot distinguish "reviewer" from "reviewer holding the implementer's write
253 #: flags", and the second is the one that edits the checkout.
254 read_only_backed: bool = False
255 effort: str | None = None
256 effort_applied: bool = False
257 warnings: tuple[str, ...] = ()
258 attribution: dict[str, str | None] = field(default_factory=dict)
259 prompt: str | None = None
260 quota_wait: float = float(DEFAULT_QUOTA_WAIT_S)
262 def as_dict(self) -> dict[str, Any]:
263 """JSON-stable record (carries no secret: ``api_key_env`` is a name)."""
264 return {
265 "provider": self.provider,
266 "vendor": self.vendor,
267 "role": self.role,
268 "transport": self.transport,
269 "prompt_path": self.prompt_path,
270 "model": self.model,
271 "cwd": self.cwd,
272 "timeout": self.timeout,
273 "argv": list(self.argv),
274 "request": dict(self.request) if self.request is not None else None,
275 "stdin_mode": self.stdin_mode,
276 "read_only": self.read_only,
277 "read_only_backed": self.read_only_backed,
278 "effort": self.effort,
279 "effort_applied": self.effort_applied,
280 "warnings": list(self.warnings),
281 "attribution": dict(self.attribution),
282 "prompt": self.prompt,
283 "quota_wait": self.quota_wait,
284 }
287def resolve_provider(
288 config,
289 registry: providers_mod.Registry | None,
290 token: str,
291) -> Resolution:
292 """Resolve ``name`` / ``vendor:model`` against the built-ins, profiles, the registry.
294 Precedence is **built-in > project profile > registry**. A built-in vendor always
295 wins and can never be redefined — the invariant
296 :func:`keel.agents.resolve_delegate_profile` states and
297 :func:`keel.config.parse_config` enforces up front, and the same rule
298 :func:`keel.providers.registry_clashes` applies to a machine-level entry. Resolving a
299 profile or a registry entry first would make ``claude`` mean whatever a file in
300 ``$HOME`` said it meant, which is exactly the shadowing those two checks exist to
301 refuse; dispatch must not be the one place the rule is inverted.
303 The model half of the token is validated before anything else looks at it: it arrives
304 per run, on the command line (``--provider <name>:<model>`` or ``--model``), which is
305 a lower-trust source than the operator-authored command beside it. **Which** rule
306 applies depends on where the model lands — see :func:`model_token_issue`.
307 """
308 name, model = agents.split_delegate((token or "").strip())
309 if not name:
310 raise DelegateError("bad-provider", "--provider is empty; pass name or vendor:model")
311 profiles = {} if config is None else config.knobs.delegate_profiles
312 registry = providers_mod.Registry(path="") if registry is None else registry
313 resolution = _lookup(name, config, profiles, registry)
314 if resolution is None:
315 known = ", ".join(sorted({*profiles, *registry.names(), *agents.BUILTIN_DELEGATE_VENDORS}))
316 hint = _did_you_mean(name, profiles, registry)
317 raise DelegateError("unknown-provider", f"unknown provider {name!r}; known: {known}{hint}")
318 _check_model(resolution.provider, model)
319 return Resolution(resolution.provider, resolution.profile, model)
322def _did_you_mean(name: str, profiles, registry: providers_mod.Registry) -> str:
323 """``; did you mean 'grok'?`` for a profile/registry entry whose command is ``name``'s CLI.
325 People type the product (``cursor``), the binary is ``cursor-agent``, and the entry
326 that drives it carries an operator-chosen name (``grok``). A fixed alias table would
327 bind ``cursor`` to whatever the operator happened to name their entry, or to a CLI
328 keel does not ship; matching on the configured *command* names the operator's own
329 entry instead (#1509).
330 """
331 needle = name.lower().removesuffix(".exe")
332 matches = []
333 # Suggest only names that resolve to the entry that matched: `_lookup` prefers a
334 # built-in, then a project profile, then the registry, so a shadowed name would run
335 # something else.
336 builtins = {e.name for e in providers_mod.builtin_providers()}
337 commands = [(n, p.command) for n, p in profiles.items() if n not in builtins]
338 commands += [
339 (e.name, e.command)
340 for e in registry.providers
341 if e.name not in builtins and e.name not in profiles
342 ]
343 for entry_name, command in commands:
344 # Windows paths split on backslashes too.
345 base = posixpath.basename((command or "").replace("\\", "/")).lower()
346 base = base.removesuffix(".exe")
347 if base and (base == needle or base.startswith(needle + "-")):
348 matches.append(entry_name)
349 if not matches:
350 return ""
351 return "; did you mean " + " or ".join(repr(m) for m in sorted(set(matches))) + "?"
354def _lookup(name, config, profiles, registry: providers_mod.Registry) -> Resolution | None:
355 """The provider ``name`` means, in precedence order. ``None`` when nothing claims it."""
356 for entry in providers_mod.builtin_providers():
357 if entry.name == name:
358 return Resolution(entry, None, None)
359 if name in profiles:
360 return Resolution(_profile_provider(config, name), profiles[name], None)
361 for entry in registry.providers:
362 if entry.name == name:
363 return Resolution(entry, None, None)
364 return None
367#: Characters a model may contain when it travels in a **JSON request body**. Wider than
368#: :func:`keel.agents.is_safe_model_token` by ``:`` and ``/`` because real ids need both —
369#: an Ollama tag (``qwen2.5-coder:32b``) and a gateway's namespaced id
370#: (``deepseek/deepseek-r1``). Neither character can do anything in a JSON string value:
371#: the body is built by :func:`json.dumps`, so there is no argv to split and no URL path
372#: to retarget. A leading dash and ``..`` stay refused so the same token can never be
373#: mistaken for a flag or a path if it is later logged, echoed, or reused.
374_BODY_MODEL_OK = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._:/-")
377def is_safe_body_model_token(model: str | None) -> bool:
378 """True when ``model`` is safe as a JSON body field (``ollama``/hosted/compatible)."""
379 if not model or model.startswith("-") or ".." in model:
380 return False
381 return _BODY_MODEL_OK.issuperset(model)
384def model_reaches_argv(provider: providers_mod.Provider) -> bool:
385 """Does this provider's model end up on a command line or in a URL path?
387 Two places demand the strict ``[A-Za-z0-9._-]`` token, and only two: a **subprocess
388 argv** (``cli``/``profile``), where a stray character could read as another flag; and
389 ``google-api``'s **URL path**, the one vendor that interpolates the model into its
390 endpoint, where a ``/`` or a ``?`` could retarget the request or smuggle query
391 parameters onto a URL that also carries an API key header.
393 Everywhere else the model is a JSON string value, and applying the argv rule there is
394 not caution but breakage: it refuses ``ollama:qwen2.5-coder:32b`` and
395 ``openrouter:deepseek/deepseek-r1``, two ids this repository's own documentation tells
396 operators to use.
397 """
398 return _transport_of(provider) in ("cli", "profile") or provider.vendor == "google-api"
401def model_token_issue(provider: providers_mod.Provider, model: str | None) -> str | None:
402 """Why ``model`` may not be used with ``provider``, or ``None`` when it may."""
403 if model is None:
404 return None
405 if model_reaches_argv(provider):
406 if not agents.is_safe_model_token(model):
407 return (
408 f"model {model!r} is not a safe token for {provider.name!r}: it reaches a "
409 "command line or a URL path, so only [A-Za-z0-9._-] with no leading dash "
410 "is accepted"
411 )
412 return None
413 if not is_safe_body_model_token(model):
414 return (
415 f"model {model!r} is not a safe token for {provider.name!r}: a request-body "
416 "model accepts [A-Za-z0-9._:/-] with no leading dash and no '..'"
417 )
418 return None
421def _check_model(provider: providers_mod.Provider, model: str | None) -> None:
422 issue = model_token_issue(provider, model)
423 if issue is not None:
424 raise DelegateError("bad-model", issue)
427def _profile_provider(config, name: str) -> providers_mod.Provider:
428 """The one :class:`keel.providers.Provider` this project's profile ``name`` maps to."""
429 for provider in providers_mod.profile_providers(config):
430 if provider.name == name:
431 return provider
432 raise DelegateError( # pragma: no cover - profile_providers covers every profile key
433 "unknown-provider", f"profile {name!r} produced no provider record"
434 )
437def plan_run(
438 provider: providers_mod.Provider,
439 role: str,
440 prompt_path: str | None = None,
441 cwd: str | None = None,
442 timeout: int = DEFAULT_TIMEOUT_S,
443 effort: str | None = None,
444 model: str | None = None,
445 *,
446 profile: DelegateProfile | None = None,
447 prompt: str | None = None,
448 quota_wait: float | None = None,
449) -> RunPlan:
450 """Plan one delegate invocation. Pure; raises :class:`DelegateError` on bad input.
452 ``model`` is the per-run override (``--model``, or the ``vendor:model`` half of the
453 provider token) and wins over the provider's configured ``model``, matching the
454 precedence ship.md s4 documents. ``profile`` supplies the project profile behind a
455 ``profile``-source provider — see :attr:`Resolution.profile`.
456 """
457 if role not in ROLES:
458 raise DelegateError("bad-role", f"unknown role {role!r}; valid: {', '.join(ROLES)}")
459 if effort is not None and effort not in EFFORTS:
460 raise DelegateError("bad-effort", f"unknown effort {effort!r}; valid: {', '.join(EFFORTS)}")
461 if timeout <= 0:
462 raise DelegateError(
463 "bad-timeout", f"timeout must be a positive number of seconds: {timeout!r}"
464 )
465 if prompt is not None and prompt_path:
466 raise DelegateError("no-prompt", "pass either --prompt or --prompt-file, not both")
467 if not prompt_path and not prompt:
468 raise DelegateError("no-prompt", "--prompt or --prompt-file is required")
469 if prompt is not None and not prompt.strip():
470 raise DelegateError("no-prompt", "--prompt cannot be empty")
471 effective_quota_wait = float(DEFAULT_QUOTA_WAIT_S if quota_wait is None else quota_wait)
472 if effective_quota_wait < 0:
473 raise DelegateError("bad-timeout", f"quota-wait must be non-negative: {quota_wait!r}")
474 # Normalised once, here, because a :class:`RunPlan` is a frozen JSON document: a
475 # ``Path`` reaching this far would pass every predicate, land in ``cwd`` and in the
476 # ``--add-dir`` argv, and then raise ``TypeError: Object of type PosixPath is not
477 # JSON serializable`` out of ``as_dict`` — at the point where the contract is
478 # printed rather than where the wrong type entered. Found by the gate review of
479 # #1134.
480 cwd = None if cwd is None else str(cwd)
481 effective = model or provider.model
482 _check_model(provider, effective)
483 read_only = role in READ_ONLY_ROLES
484 transport = _transport_of(provider)
485 effort, warnings = _effective_effort(provider, effort)
486 applied = _apply_effort(provider.vendor, transport, effort, effective)
487 effective = applied.model
488 warnings = warnings + applied.warnings
489 argv: tuple[str, ...] = ()
490 request: dict[str, Any] | None = None
491 stdin_mode: str | None = None
492 backed = read_only
493 if transport == "cli":
494 argv, stdin_mode = _builtin_argv(
495 provider,
496 read_only=read_only,
497 model=effective,
498 effort_args=applied.argv,
499 cwd=cwd,
500 timeout=timeout,
501 )
502 if cwd and not is_absolute_cwd(cwd) and provider.name == "agy":
503 warnings = warnings + (
504 f"cwd {cwd!r} is relative; agy resolves --add-dir against the directory "
505 "it is started in, so it would name a path inside the worktree instead of "
506 "the worktree. The flag is omitted and agy will edit its own scratch copy "
507 "(#1134) — pass an absolute path.",
508 )
509 elif transport == "profile":
510 argv, stdin_mode, backed, profile_warnings = _profile_argv(
511 provider, profile, read_only=read_only, model=effective
512 )
513 warnings = warnings + profile_warnings
514 else:
515 request = _request(provider, transport, model=effective, timeout=timeout, effort=applied)
516 return RunPlan(
517 provider=provider.name,
518 vendor=provider.label_vendor(),
519 role=role,
520 transport=transport,
521 prompt_path=str(prompt_path) if prompt_path else "",
522 model=effective,
523 cwd=cwd,
524 timeout=timeout,
525 argv=argv,
526 request=request,
527 stdin_mode=stdin_mode,
528 read_only=read_only,
529 read_only_backed=backed,
530 effort=effort,
531 effort_applied=applied.applied,
532 warnings=warnings,
533 attribution=_attribution(provider, profile, effective),
534 prompt=prompt,
535 quota_wait=effective_quota_wait,
536 )
539def _effective_effort(
540 provider: providers_mod.Provider, effort: str | None
541) -> tuple[str | None, tuple[str, ...]]:
542 """``--effort`` if given, else the provider's own configured default.
544 ``Provider.effort`` exists so an operator can say "this entry is my high-effort seat"
545 once, in the registry or the profile, instead of on every dispatch. A per-run
546 ``--effort`` still wins. An unrecognised configured value is a **warning, not an
547 error**: the registry is fail-soft everywhere else in #1011, and a typo in a file in
548 ``$HOME`` should not make every run of an otherwise usable provider fail.
549 """
550 if effort is not None or not provider.effort:
551 return effort, ()
552 if provider.effort in EFFORTS:
553 return provider.effort, ()
554 return None, (
555 f"{provider.name}: ignoring configured effort {provider.effort!r}; "
556 f"valid: {', '.join(EFFORTS)}",
557 )
560def _transport_of(provider: providers_mod.Provider) -> str:
561 """Which executor path a provider record lands on.
563 :class:`keel.providers.Provider` records the *shape* of a provider (``cli``/``api``/
564 ``local``); this is the finer question of which code runs it. The built-in ``ollama``
565 vendor gets its own HTTP path, while a registry ``local`` entry names an arbitrary
566 binary and is run exactly like a configured CLI — keel does not dial an address a
567 file names, so a local entry's only reachable surface is its command.
568 """
569 if provider.transport == "api":
570 return "api"
571 if provider.vendor == "ollama":
572 return "ollama"
573 if provider.source == "builtin":
574 return "cli"
575 return "profile"
578def is_absolute_cwd(cwd: str | None) -> bool:
579 """Is ``cwd`` a path agy's ``--add-dir`` can be given? (pure — no filesystem)
581 The child is started **inside** ``cwd`` — :func:`keel.delegaterun._run_argv` passes it
582 to the runner — so agy resolves a relative ``--add-dir`` against that directory:
583 ``--cwd worktrees/foo`` would name ``<root>/worktrees/foo/worktrees/foo``, and the
584 real worktree would go untouched exactly as it did before #1134. ``--add-dir .`` is
585 not a way out; it was measured, and the run ended on agy's timeout with the tree
586 unchanged, the same as passing no flag at all.
588 So the path has to be absolute, and this module cannot make it so: ``abspath`` reads
589 the *host's* working directory into a :class:`RunPlan` that is frozen, JSON-stable and
590 may be executed somewhere else. The CLI resolves it; this refuses what is left, and
591 :func:`plan_run` says why in a warning. Found by the gate review of #1134.
593 Both separators are accepted, because a plan built on one platform is a document that
594 may be read on another.
595 """
596 # ``str(cwd)`` rather than ``cwd``: the annotation says ``str | None``, but
597 # ``posixpath.isabs`` accepts a ``PathLike`` while ``re.match`` does not, so a
598 # *relative* ``Path`` would fall through the first test and raise ``TypeError`` out of
599 # the second while an absolute one short-circuited to ``True``. A predicate that
600 # answers for half its inputs and crashes for the other half is worse than one that
601 # refuses both. Found by the gate review of #1134.
602 text = "" if cwd is None else str(cwd)
603 return bool(text) and (posixpath.isabs(text) or _WINDOWS_ABSOLUTE.match(text) is not None)
606def _builtin_argv(
607 provider: providers_mod.Provider,
608 *,
609 read_only: bool,
610 model: str | None,
611 effort_args: tuple[str, ...] = (),
612 cwd: str | None = None,
613 timeout: int = DEFAULT_TIMEOUT_S,
614) -> tuple[tuple[str, ...], str]:
615 """The argv + stdin framing for one of the three built-in agent CLIs.
617 **claude's read-only invocation is an allow-list, and carries no permission bypass.**
618 The first cut paired ``--disallowed-tools Edit,Write,NotebookEdit,Bash`` with
619 ``--dangerously-skip-permissions``, on the reasoning that a denylist wins over the
620 bypass. That is a denylist of four names against a tool surface that grows with every
621 release — ``WebFetch``, an MCP server's tools, whatever ships next — and it hands the
622 bypass to everything it failed to enumerate. ``--allowed-tools`` inverts the default:
623 anything not named is refused, so a new tool is refused on the day it appears rather
624 than on the day someone remembers this list. With no tool outside the read set
625 reachable there is nothing left for a permission prompt to ask about, so the bypass is
626 dropped as well. Flag spelling verified against ``claude --help``
627 (``--allowedTools, --allowed-tools <tools...>``).
629 ``agy`` keeps ``--sandbox`` plus ``--dangerously-skip-permissions``: it exposes no
630 allow-list, the sandbox is the only read-only mechanism it documents, and without the
631 skip flag an unattended reviewer stops at an approval prompt. This is the same pairing
632 ai-jury's ``privilege.enforce_read_only`` uses for the vendor, and the reason
633 :attr:`RunPlan.read_only_backed` reports what backs the promise rather than asserting
634 that writes are impossible.
635 """
636 command = provider.command or provider.name
637 if provider.name == "claude":
638 argv = [command, "-p"]
639 if read_only:
640 argv += ["--output-format", "text"]
641 if model:
642 argv += ["--model", model]
643 if read_only:
644 argv += ["--allowed-tools", CLAUDE_ALLOWED_TOOLS]
645 else:
646 argv += ["--dangerously-skip-permissions"]
647 return tuple(argv), STDIN_TEXT
648 if provider.name == "codex":
649 sandbox = "read-only" if read_only else "workspace-write"
650 argv = [command, "exec", "-s", sandbox, "--skip-git-repo-check"]
651 if model:
652 argv += ["-m", model]
653 argv += list(effort_args)
654 return tuple(argv), STDIN_TEXT
655 # agy — the only remaining built-in CLI vendor (agents.CLI_VENDORS).
656 argv = [command]
657 if read_only:
658 argv += ["--sandbox"]
659 argv += ["--dangerously-skip-permissions", *AGY_STREAM_ARGS]
660 if model:
661 argv += ["--model", model]
662 # `--add-dir` is what makes the working directory keel named the one agy edits
663 # (#1134). Without it agy works in `~/.gemini/antigravity-cli/scratch/<basename>` —
664 # its own copy — so an `implement` run returned prose about files it had changed
665 # while the worktree keel handed it stayed clean, and the first thing downstream
666 # would have seen is a pull request with no diff. Measured, not inferred: three
667 # runs of one prompt against a standalone clone, a linked worktree, and a linked
668 # worktree with this flag. Only the third edited the real file, and only it made
669 # no scratch copy — the other two never touched the directory at all and ended on
670 # agy's own print timeout.
671 # Absolute only — see :func:`is_absolute_cwd`. The caller makes it absolute; a plan
672 # that reached here with a relative one carries the warning instead of an argv the
673 # child would resolve against itself.
674 if is_absolute_cwd(cwd):
675 # ``str`` by the time it reaches here — :func:`plan_run` normalises it — and
676 # spelled again because this helper is reachable from a test with any value, and
677 # ``RunPlan.argv`` is ``tuple[str, ...]``.
678 argv += ["--add-dir", str(cwd)]
679 # And `--print-timeout` is why keel's own `--timeout` used to mean nothing here:
680 # agy's print mode defaults to 5m and stops on its own, so `--timeout 900` against
681 # a real brief died at 298s with agy's `timeout waiting for response` — keel's
682 # bound never reached the process it was bounding. Go duration spelling, per
683 # `agy --help` ("default 5m0s").
684 #
685 # Unconditional, because :func:`plan_run` refuses a non-positive timeout before
686 # reaching here — a guard on it would be a branch no input can take, which the
687 # 100 % coverage bar reports as exactly what it is. Found by the gate review.
688 argv += ["--print-timeout", f"{timeout}s"]
689 return tuple(argv), STDIN_STREAM_JSON
692def _profile_argv(
693 provider: providers_mod.Provider,
694 profile: DelegateProfile | None,
695 *,
696 read_only: bool,
697 model: str | None,
698) -> tuple[tuple[str, ...], str | None, bool, tuple[str, ...]]:
699 """The argv + framing + read-only backing for an operator-configured binary.
701 The dangerous case is a profile that has ``args`` and no ``review_args``:
702 :meth:`keel.config.DelegateProfile.role_args` **falls back to ``args``**, which is the
703 implementer's flag set — ``aider``'s ``--yes-always``, ``cursor-agent``'s ``--force``.
704 A reviewer invoked with those can edit the checkout it was asked to read.
706 So the question asked here is *"did the operator configure a read-only invocation?"* —
707 ``profile.review_args is None`` — and **not** *"is the argv empty?"*. The first cut
708 asked the second, so exactly the dangerous case produced a full implementer argv,
709 ``read_only: true``, and no warning at all: the fallback made ``role_args`` non-empty,
710 which read as "configured". A profile whose ``review_args`` is an explicit empty list
711 is a deliberate choice — "this CLI needs no flags to be a reviewer" — and is backed.
712 """
713 command = provider.command
714 if not command:
715 raise DelegateError("bad-provider", f"provider {provider.name!r} names no command")
716 if profile is not None:
717 role_args = profile.role_args(review=read_only)
718 configured = profile.review_args is not None
719 prompt_mode = profile.prompt_mode
720 else:
721 # A registry entry's `args` are the implementer's flags (#1508): applied to a
722 # write role only, and never as a fallback for `review_args`, so an empty
723 # review_args still reads as "nothing configured" rather than a fallback in disguise.
724 role_args = provider.review_args if read_only else provider.args
725 configured = bool(provider.review_args)
726 prompt_mode = DEFAULT_PROMPT_MODE
727 argv = [command, *role_args]
728 if model and provider.model_arg:
729 argv += [provider.model_arg, model]
730 warnings: tuple[str, ...] = ()
731 backed = read_only and configured
732 if read_only and not configured:
733 shared = " it is running with the implementer's own args" if role_args else ""
734 warnings = (
735 f"{provider.name}: no read-only invocation is configured (review_args), so"
736 f"{shared or ' the command runs with its default permissions'} — keel cannot "
737 "enforce read-only for an arbitrary CLI. Set review_args, treat this "
738 "reviewer's output as advisory, and re-check the worktree is clean afterwards",
739 )
740 stdin_mode = STDIN_TEXT if prompt_mode == DEFAULT_PROMPT_MODE else None
741 return tuple(argv), stdin_mode, backed, warnings
744def _request(
745 provider: providers_mod.Provider,
746 transport: str,
747 *,
748 model: str | None,
749 timeout: int,
750 effort: Effort,
751) -> dict[str, Any]:
752 """The HTTP call description for the ``api`` and ``ollama`` transports."""
753 if not model:
754 raise DelegateError(
755 "no-model",
756 f"provider {provider.name!r} generates text over HTTP and names no model; "
757 "pass --model or provider:model",
758 )
759 if transport == "ollama":
760 # Hardcoded loopback constant, never provider.endpoint: the tag listing #1011
761 # probes and the generation endpoint are two paths on the same fixed origin.
762 return {
763 "vendor": "ollama",
764 "model": model,
765 "endpoint": OLLAMA_GENERATE_URL,
766 "timeout": timeout,
767 }
768 max_tokens = DEFAULT_MAX_TOKENS
769 if effort.budget is not None:
770 # Anthropic rejects max_tokens <= thinking.budget_tokens before generating a
771 # token, and Gemini's answer shares the output cap with its thinking.
772 max_tokens = max(max_tokens, effort.budget + THINKING_HEADROOM_TOKENS)
773 return {
774 "vendor": provider.vendor,
775 "model": model,
776 "endpoint": provider.endpoint,
777 "api_key_env": provider.api_key_env,
778 "max_tokens": max_tokens,
779 "timeout": timeout,
780 "extra_payload": effort.payload,
781 }
784def _apply_effort(vendor: str, transport: str, effort: str | None, model: str | None) -> Effort:
785 """Map ``--effort`` onto the vendor's own spelling.
787 Every vendor spells reasoning effort differently and several cannot spell it at all;
788 an unsupported request is a warning plus ``applied: False``, never a silent no-op — a
789 caller that asked for ``high`` and got the default must be able to see that from the
790 JSON it parses.
791 """
792 if effort is None:
793 return Effort(model, {}, None, False, ())
794 if vendor == "agy":
795 return _agy_effort(effort, model)
796 if vendor == "codex":
797 # A config override rather than a flag: `codex exec` takes `-c key=value`, and
798 # `model_reasoning_effort` is the key it recognises (verified by round-tripping a
799 # real and a bogus key through `--strict-config`).
800 return Effort(model, {}, None, True, (), ("-c", f"{CODEX_EFFORT_CONFIG}={effort}"))
801 if vendor == "anthropic-api":
802 budget = ANTHROPIC_THINKING_BUDGET[effort]
803 payload = {"thinking": {"type": "enabled", "budget_tokens": budget}}
804 return Effort(model, payload, budget, True, ())
805 if vendor in ("openai-api", OPENAI_COMPATIBLE):
806 return Effort(model, {"reasoning_effort": effort}, None, True, ())
807 if vendor == "google-api":
808 budget = GOOGLE_THINKING_BUDGET[effort]
809 payload = {"generationConfig": {"thinkingConfig": {"thinkingBudget": budget}}}
810 return Effort(model, payload, budget, True, ())
811 return Effort(
812 model,
813 {},
814 None,
815 False,
816 (
817 f"--effort {effort} is not supported by {vendor} over the {transport} "
818 "transport; the run used the provider's default reasoning effort",
819 ),
820 )
823def _agy_effort(effort: str, model: str | None) -> Effort:
824 """agy spells effort as a model suffix (``gemini-3.8-flash-high``), not as a flag."""
825 if not model:
826 return Effort(
827 model,
828 {},
829 None,
830 False,
831 (
832 f"--effort {effort} needs a model for agy, which spells effort as a "
833 "model suffix; pass --model or provider:model",
834 ),
835 )
836 for suffix in _EFFORT_SUFFIXES:
837 if model.endswith(suffix):
838 if suffix == f"-{effort}":
839 return Effort(model, {}, None, True, ())
840 return Effort(
841 model,
842 {},
843 None,
844 True,
845 (
846 f"model {model!r} already selects effort {suffix[1:]!r}; the model's "
847 f"own suffix wins over --effort {effort}",
848 ),
849 )
850 return Effort(f"{model}-{effort}", {}, None, True, ())
853def _attribution(
854 provider: providers_mod.Provider,
855 profile: DelegateProfile | None,
856 model: str | None,
857) -> dict[str, str | None]:
858 """The attribution record, computed by :mod:`keel.agents` so a host cannot drift.
860 A configured provider also records **which** entry ran under ``delegate_profile``,
861 never ``profile``: the ship run record already means the workflow profile
862 (``standard``/``compound``) by that name, and writing the CLI's name there would
863 silently overwrite it.
865 A registry entry names its **label vendor** (#1129): ``vendor`` there is the
866 transport the schema requires — ``cli`` for every local coding-agent CLI — so two
867 entries driving Grok and GPT through the same binary both reported ``agent:cli``,
868 and ``review-vendor-distinctness``, which is the rule keel most depends on, could
869 not tell them apart. ``vendor_label`` is how an entry says which maker it reaches;
870 unset, it stays the generic token, which is what every built-in already is.
871 """
872 if profile is not None:
873 return agents.profile_attribution(provider.name, profile, model)
874 record = agents.attribution(provider.label_vendor(), model)
875 if provider.source != "builtin":
876 record["delegate_profile"] = provider.name
877 return record
880def stream_json_frame(prompt: str) -> str:
881 """One NDJSON user frame for agy's ``--input-format stream-json`` stdin.
883 Shape ported from ai-jury's ``AgyAdapter._stdin_for``, verified there against
884 agy 1.1.22.
885 """
886 return json.dumps({"event": "user", "message": {"role": "user", "content": prompt}}) + "\n"
889def parse_stream_json(raw: str) -> str:
890 """The response text out of agy's NDJSON stdout, falling back to the raw stream.
892 Falls back rather than returning empty: a truncated stream must surface as output an
893 operator can read, not as a silent abstention. An empty review counts as a review,
894 and a review read as an approval is the expensive failure (ai-jury #625).
895 """
896 response, saw_result = None, False
897 for line in (raw or "").splitlines():
898 line = line.strip()
899 if not line:
900 continue
901 try:
902 event = json.loads(line)
903 except ValueError:
904 continue
905 if isinstance(event, dict) and event.get("event") == "result":
906 saw_result = True
907 result = event.get("result")
908 if isinstance(result, dict):
909 response = result.get("response")
910 if saw_result and isinstance(response, str):
911 return response
912 return raw
915def parse_ollama_response(data: Any) -> str | None:
916 """The completion out of an Ollama ``/api/generate`` payload (``None`` if malformed)."""
917 if not isinstance(data, dict):
918 return None
919 text = data.get("response")
920 return text if isinstance(text, str) and text else None
923def ollama_payload(model: str, prompt: str) -> dict[str, Any]:
924 """The ``/api/generate`` body. ``stream: false`` — keel wants one document, not NDJSON."""
925 return {"model": model, "prompt": prompt, "stream": False}