PyPI - world-model-optimizer - Versions diffs - 0.2.0__py3-none-any.whl - Mend

world-model-optimizer 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (308) hide show

llm_waterfall/LICENSE +21 -0
llm_waterfall/__init__.py +53 -0
llm_waterfall/adapters/__init__.py +36 -0
llm_waterfall/adapters/anthropic.py +105 -0
llm_waterfall/adapters/aws_mantle.py +47 -0
llm_waterfall/adapters/azure_openai.py +71 -0
llm_waterfall/adapters/base.py +51 -0
llm_waterfall/adapters/bedrock.py +309 -0
llm_waterfall/adapters/openai.py +130 -0
llm_waterfall/classify.py +184 -0
llm_waterfall/pricing.py +110 -0
llm_waterfall/py.typed +0 -0
llm_waterfall/types.py +295 -0
llm_waterfall/waterfall.py +255 -0
wmo/__init__.py +38 -0
wmo/agents/__init__.py +7 -0
wmo/agents/default.py +29 -0
wmo/agents/meta.py +55 -0
wmo/agents/optimizer.py +55 -0
wmo/agents/project.py +928 -0
wmo/cli/__init__.py +5 -0
wmo/cli/agent_session.py +1123 -0
wmo/cli/app.py +2489 -0
wmo/cli/e2b_cmds.py +212 -0
wmo/cli/eval_closed_loop.py +207 -0
wmo/cli/harness_app.py +1147 -0
wmo/cli/harness_distill.py +659 -0
wmo/cli/hosted_session.py +880 -0
wmo/cli/ingest_cmd.py +165 -0
wmo/cli/model_roles.py +82 -0
wmo/cli/platform_cmds.py +372 -0
wmo/cli/route_app.py +274 -0
wmo/cli/session_state.py +243 -0
wmo/cli/ui.py +1107 -0
wmo/cli/workspace_sync.py +504 -0
wmo/config/__init__.py +60 -0
wmo/config/card.py +129 -0
wmo/config/config.py +367 -0
wmo/config/dotenv.py +67 -0
wmo/config/settings.py +128 -0
wmo/config/store.py +177 -0
wmo/conftest.py +19 -0
wmo/connect/__init__.py +88 -0
wmo/connect/apps.py +78 -0
wmo/connect/brave.py +284 -0
wmo/connect/connector.py +79 -0
wmo/connect/credentials.py +164 -0
wmo/connect/github.py +321 -0
wmo/connect/google.py +627 -0
wmo/connect/notion.py +790 -0
wmo/connect/oauth.py +461 -0
wmo/connect/slack.py +555 -0
wmo/connect/store.py +199 -0
wmo/connect/types.py +156 -0
wmo/core/__init__.py +21 -0
wmo/core/parsing.py +281 -0
wmo/core/render.py +271 -0
wmo/core/text.py +40 -0
wmo/core/types.py +116 -0
wmo/distill/__init__.py +14 -0
wmo/distill/agents.py +140 -0
wmo/distill/config.py +1006 -0
wmo/distill/cost.py +437 -0
wmo/distill/data.py +921 -0
wmo/distill/deadlines.py +254 -0
wmo/distill/fake_tinker.py +734 -0
wmo/distill/gate.py +122 -0
wmo/distill/loop.py +3499 -0
wmo/distill/renderers.py +399 -0
wmo/distill/rendering.py +620 -0
wmo/distill/rollouts.py +726 -0
wmo/distill/samples.py +195 -0
wmo/distill/store.py +829 -0
wmo/distill/teacher.py +714 -0
wmo/distill/tokens.py +535 -0
wmo/distill/tracking.py +552 -0
wmo/distill/tripwire.py +411 -0
wmo/distill/xtoken/byte_offsets.py +152 -0
wmo/distill/xtoken/chunks.py +457 -0
wmo/distill/xtoken/prompt_logprobs.py +475 -0
wmo/distill/xtoken/teacher_render.py +346 -0
wmo/engine/__init__.py +28 -0
wmo/engine/autoconfig.py +367 -0
wmo/engine/build.py +346 -0
wmo/engine/demo.py +77 -0
wmo/engine/eval_suites.py +245 -0
wmo/engine/grounding.py +491 -0
wmo/engine/knowledge.py +291 -0
wmo/engine/loader.py +36 -0
wmo/engine/play.py +92 -0
wmo/engine/prompts.py +99 -0
wmo/engine/replay.py +443 -0
wmo/engine/reporting.py +58 -0
wmo/engine/workspace.py +468 -0
wmo/engine/world_model.py +568 -0
wmo/env/__init__.py +22 -0
wmo/env/base.py +121 -0
wmo/env/closed_loop.py +229 -0
wmo/env/episode.py +107 -0
wmo/env/llm_agent.py +93 -0
wmo/env/scenarios.py +73 -0
wmo/evals/__init__.py +52 -0
wmo/evals/agreement.py +110 -0
wmo/evals/base.py +45 -0
wmo/evals/closed_loop.py +480 -0
wmo/evals/failover.py +96 -0
wmo/evals/gold.py +127 -0
wmo/evals/grid.py +394 -0
wmo/evals/grid_plot.py +205 -0
wmo/evals/harbor/__init__.py +27 -0
wmo/evals/harbor/agent.py +573 -0
wmo/evals/harbor/ctrf.py +171 -0
wmo/evals/harbor/e2b_environment.py +587 -0
wmo/evals/harbor/e2b_template_policy.py +144 -0
wmo/evals/harbor/scorer.py +875 -0
wmo/evals/harbor/tasks.py +140 -0
wmo/evals/open_loop.py +194 -0
wmo/evals/tasks.py +53 -0
wmo/harness/__init__.py +51 -0
wmo/harness/code_runtime.py +288 -0
wmo/harness/create.py +1191 -0
wmo/harness/delta.py +220 -0
wmo/harness/doc.py +556 -0
wmo/harness/e2b_ledger.py +342 -0
wmo/harness/e2b_reap.py +476 -0
wmo/harness/e2b_sandbox.py +350 -0
wmo/harness/environment.py +35 -0
wmo/harness/live_session.py +543 -0
wmo/harness/mutate.py +343 -0
wmo/harness/pi_e2b.py +1710 -0
wmo/harness/pi_entry/entry.ts +268 -0
wmo/harness/pi_entry/runner_frames.ts +92 -0
wmo/harness/pi_entry/runner_live.ts +587 -0
wmo/harness/pi_entry/runner_service.ts +270 -0
wmo/harness/pi_entry/runner_stdio.ts +374 -0
wmo/harness/pi_entry/runner_termination.ts +142 -0
wmo/harness/pi_local.py +262 -0
wmo/harness/pi_runtime.py +495 -0
wmo/harness/pi_vendor.py +65 -0
wmo/harness/population.py +509 -0
wmo/harness/project_proposer.py +569 -0
wmo/harness/proposer.py +977 -0
wmo/harness/runner_link.py +619 -0
wmo/harness/runtime.py +389 -0
wmo/harness/scoring.py +247 -0
wmo/harness/skills.py +116 -0
wmo/harness/source_tree.py +319 -0
wmo/harness/store.py +176 -0
wmo/harness/tools.py +105 -0
wmo/harness/vendor/manifest.sha256 +58 -0
wmo/harness/vendor/pi-agent/CHANGELOG.md +556 -0
wmo/harness/vendor/pi-agent/LICENSE +21 -0
wmo/harness/vendor/pi-agent/README.md +488 -0
wmo/harness/vendor/pi-agent/VENDOR.md +39 -0
wmo/harness/vendor/pi-agent/docs/agent-harness.md +486 -0
wmo/harness/vendor/pi-agent/docs/durable-harness.md +212 -0
wmo/harness/vendor/pi-agent/docs/hooks.md +445 -0
wmo/harness/vendor/pi-agent/docs/models.md +966 -0
wmo/harness/vendor/pi-agent/docs/observability.md +376 -0
wmo/harness/vendor/pi-agent/package.json +60 -0
wmo/harness/vendor/pi-agent/src/agent-loop.ts +748 -0
wmo/harness/vendor/pi-agent/src/agent.ts +575 -0
wmo/harness/vendor/pi-agent/src/harness/agent-harness.ts +1029 -0
wmo/harness/vendor/pi-agent/src/harness/compaction/branch-summarization.ts +261 -0
wmo/harness/vendor/pi-agent/src/harness/compaction/compaction.ts +747 -0
wmo/harness/vendor/pi-agent/src/harness/compaction/utils.ts +144 -0
wmo/harness/vendor/pi-agent/src/harness/env/nodejs.ts +550 -0
wmo/harness/vendor/pi-agent/src/harness/messages.ts +164 -0
wmo/harness/vendor/pi-agent/src/harness/prompt-templates.ts +267 -0
wmo/harness/vendor/pi-agent/src/harness/session/jsonl-repo.ts +177 -0
wmo/harness/vendor/pi-agent/src/harness/session/jsonl-storage.ts +293 -0
wmo/harness/vendor/pi-agent/src/harness/session/memory-repo.ts +50 -0
wmo/harness/vendor/pi-agent/src/harness/session/memory-storage.ts +131 -0
wmo/harness/vendor/pi-agent/src/harness/session/repo-utils.ts +51 -0
wmo/harness/vendor/pi-agent/src/harness/session/session.ts +267 -0
wmo/harness/vendor/pi-agent/src/harness/session/uuid.ts +54 -0
wmo/harness/vendor/pi-agent/src/harness/skills.ts +375 -0
wmo/harness/vendor/pi-agent/src/harness/system-prompt.ts +34 -0
wmo/harness/vendor/pi-agent/src/harness/types.ts +836 -0
wmo/harness/vendor/pi-agent/src/harness/utils/shell-output.ts +135 -0
wmo/harness/vendor/pi-agent/src/harness/utils/truncate.ts +344 -0
wmo/harness/vendor/pi-agent/src/index.ts +44 -0
wmo/harness/vendor/pi-agent/src/node.ts +2 -0
wmo/harness/vendor/pi-agent/src/proxy.ts +367 -0
wmo/harness/vendor/pi-agent/src/types.ts +428 -0
wmo/harness/vendor/pi-agent/test/agent-loop.test.ts +1351 -0
wmo/harness/vendor/pi-agent/test/agent.test.ts +699 -0
wmo/harness/vendor/pi-agent/test/e2e.test.ts +404 -0
wmo/harness/vendor/pi-agent/test/harness/agent-harness-stream.test.ts +213 -0
wmo/harness/vendor/pi-agent/test/harness/agent-harness.test.ts +608 -0
wmo/harness/vendor/pi-agent/test/harness/compaction.test.ts +655 -0
wmo/harness/vendor/pi-agent/test/harness/nodejs-env.test.ts +321 -0
wmo/harness/vendor/pi-agent/test/harness/prompt-templates.test.ts +90 -0
wmo/harness/vendor/pi-agent/test/harness/repo.test.ts +68 -0
wmo/harness/vendor/pi-agent/test/harness/resource-formatting.test.ts +24 -0
wmo/harness/vendor/pi-agent/test/harness/session-test-utils.ts +55 -0
wmo/harness/vendor/pi-agent/test/harness/session-uuid.test.ts +50 -0
wmo/harness/vendor/pi-agent/test/harness/session.test.ts +156 -0
wmo/harness/vendor/pi-agent/test/harness/skills.test.ts +116 -0
wmo/harness/vendor/pi-agent/test/harness/storage.test.ts +299 -0
wmo/harness/vendor/pi-agent/test/harness/system-prompt.test.ts +66 -0
wmo/harness/vendor/pi-agent/test/harness/truncate.test.ts +169 -0
wmo/harness/vendor/pi-agent/test/scratch/simple.ts +72 -0
wmo/harness/vendor/pi-agent/test/utils/calculate.ts +32 -0
wmo/harness/vendor/pi-agent/test/utils/get-current-time.ts +46 -0
wmo/harness/vendor/pi-agent/tsconfig.build.json +13 -0
wmo/harness/vendor/pi-agent/vitest.config.ts +19 -0
wmo/harness/vendor/pi-agent/vitest.harness.config.ts +28 -0
wmo/harness/vendor/vendor_pi.sh +59 -0
wmo/harness/workspace_patch.py +270 -0
wmo/ingest/__init__.py +47 -0
wmo/ingest/adapter.py +72 -0
wmo/ingest/base.py +114 -0
wmo/ingest/braintrust.py +339 -0
wmo/ingest/detect.py +126 -0
wmo/ingest/langfuse.py +291 -0
wmo/ingest/langsmith.py +444 -0
wmo/ingest/mastra.py +330 -0
wmo/ingest/messages.py +170 -0
wmo/ingest/normalize.py +679 -0
wmo/ingest/otel_genai.py +69 -0
wmo/ingest/otel_writer.py +100 -0
wmo/ingest/phoenix.py +150 -0
wmo/ingest/postgres.py +246 -0
wmo/ingest/posthog.py +320 -0
wmo/ingest/quality.py +28 -0
wmo/ingest/stream.py +209 -0
wmo/ingest/testdata/sample_otlp.json +60 -0
wmo/ingest/testdata/sample_spans.jsonl +3 -0
wmo/optimize/__init__.py +25 -0
wmo/optimize/base.py +143 -0
wmo/optimize/gepa.py +806 -0
wmo/optimize/judge.py +262 -0
wmo/optimize/judge_quality.py +359 -0
wmo/optimize/knn.py +468 -0
wmo/optimize/numeric.py +152 -0
wmo/optimize/outcomes.py +103 -0
wmo/optimize/policy.py +669 -0
wmo/optimize/report.py +231 -0
wmo/optimize/reward.py +129 -0
wmo/optimize/routing.py +373 -0
wmo/platform/__init__.py +6 -0
wmo/platform/auth.py +115 -0
wmo/platform/client.py +551 -0
wmo/platform/credentials.py +126 -0
wmo/platform/transfer.py +158 -0
wmo/providers/__init__.py +40 -0
wmo/providers/_bedrock_chat.py +155 -0
wmo/providers/_openai_common.py +182 -0
wmo/providers/_responses_common.py +472 -0
wmo/providers/anthropic.py +134 -0
wmo/providers/azure_openai.py +296 -0
wmo/providers/base.py +300 -0
wmo/providers/bedrock.py +312 -0
wmo/providers/models.py +205 -0
wmo/providers/openai.py +143 -0
wmo/providers/openai_responses.py +240 -0
wmo/providers/pool.py +170 -0
wmo/providers/registry.py +73 -0
wmo/providers/retry.py +151 -0
wmo/providers/tinker.py +936 -0
wmo/providers/waterfall.py +336 -0
wmo/research/__init__.py +81 -0
wmo/research/ablation.py +133 -0
wmo/research/concurrency_plot.py +523 -0
wmo/research/concurrency_run.py +240 -0
wmo/research/concurrency_scaling.py +270 -0
wmo/research/gepa_scaling.py +274 -0
wmo/research/pipeline.py +198 -0
wmo/research/scaling_split.py +82 -0
wmo/research/scenario_fidelity.py +198 -0
wmo/research/scenario_recovery.py +92 -0
wmo/research/seed_stability.py +90 -0
wmo/research/trace_scaling.py +348 -0
wmo/retrieval/__init__.py +6 -0
wmo/retrieval/embedders.py +105 -0
wmo/retrieval/leakfree.py +52 -0
wmo/retrieval/retriever.py +173 -0
wmo/scenarios/__init__.py +58 -0
wmo/scenarios/builder.py +152 -0
wmo/scenarios/mining/__init__.py +27 -0
wmo/scenarios/mining/clustering.py +171 -0
wmo/scenarios/mining/facets.py +226 -0
wmo/scenarios/mining/selection.py +220 -0
wmo/scenarios/synthesis/__init__.py +6 -0
wmo/scenarios/synthesis/scenario_set.py +63 -0
wmo/scenarios/synthesis/synthesizer.py +85 -0
wmo/scenarios/verification/__init__.py +17 -0
wmo/scenarios/verification/judge.py +97 -0
wmo/scenarios/verification/verify.py +135 -0
wmo/serving/__init__.py +5 -0
wmo/serving/builds.py +451 -0
wmo/serving/chat.py +878 -0
wmo/serving/endpoint_config.py +64 -0
wmo/serving/savings.py +250 -0
wmo/serving/server.py +553 -0
wmo/serving/traces_source.py +206 -0
wmo/telemetry.py +213 -0
wmo/tracking/__init__.py +36 -0
wmo/tracking/clock.py +24 -0
wmo/tracking/metered.py +125 -0
wmo/tracking/pricing.py +99 -0
wmo/tracking/store.py +31 -0
wmo/tracking/tracker.py +149 -0
world_model_optimizer-0.2.0.dist-info/METADATA +203 -0
world_model_optimizer-0.2.0.dist-info/RECORD +308 -0
world_model_optimizer-0.2.0.dist-info/WHEEL +4 -0
world_model_optimizer-0.2.0.dist-info/entry_points.txt +2 -0

wmo/connect/oauth.py ADDED Viewed

@@ -0,0 +1,461 @@
+"""Provider-agnostic OAuth building blocks: PKCE, loopback and device flows, refresh.
+Connectors compose these instead of reimplementing OAuth per service. Everything user-visible is
+injected (`open_url`, `present`, `sleep`, an httpx `transport`), so this module never prints and
+tests never touch the network or wait on real clocks.
+"""
+from __future__ import annotations
+import base64
+import hashlib
+import logging
+import re
+import secrets
+import threading
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import cast
+from urllib.parse import parse_qsl, urlencode, urlsplit
+import httpx
+from pydantic import BaseModel, Field
+from wmo.connect.credentials import save_connector_auth
+from wmo.connect.types import ConnectError, ConnectorAuth, transport_errors
+from wmo.core.types import JsonObject, JsonValue
+logger = logging.getLogger(__name__)
+# Refresh when the access token expires within this window (seconds).
+REFRESH_LEEWAY_SECONDS = 60.0
+_TOKEN_TIMEOUT_SECONDS = 30.0
+_DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+_CALLBACK_HTML = (
+    '<!doctype html><html><body style="font-family: sans-serif; padding: 2rem;">'
+    "<p>Authorization received. You can close this tab and return to the terminal.</p>"
+    "</body></html>"
+)
+class OAuthApp(BaseModel):
+    """One provider's OAuth application: endpoints, client credential, default scopes.
+    Attributes:
+        name: Provider name (matches the connector name, e.g. "github").
+        client_id: The registered OAuth client id.
+        client_secret: Client secret, for providers whose token endpoint requires one.
+        auth_url: Browser authorization endpoint.
+        token_url: Token exchange/refresh endpoint.
+        device_url: Device authorization endpoint (RFC 8628), when the provider has one.
+        scopes: Default scopes requested when a flow is run without an explicit list.
+        extra_auth_params: Additional authorize-URL query params (e.g. Google's
+            access_type=offline).
+    """
+    name: str
+    client_id: str
+    client_secret: str | None = None
+    auth_url: str
+    token_url: str
+    device_url: str | None = None
+    scopes: list[str] = Field(default_factory=list)
+    extra_auth_params: dict[str, str] = Field(default_factory=dict)
+def pkce_challenge() -> tuple[str, str]:
+    """A fresh PKCE S256 pair (RFC 7636): (verifier, challenge).
+    The verifier is 43-128 chars of URL-safe randomness; the challenge is the unpadded
+    base64url-encoded SHA-256 of the verifier.
+    """
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+class LoopbackServer(HTTPServer):
+    """A single-use localhost server that captures the OAuth redirect."""
+    def __init__(self) -> None:
+        super().__init__(("127.0.0.1", 0), _LoopbackHandler)
+        self.timeout = 0.1  # handle_request wakes this often so the serve loop can exit
+        self.callback_params: dict[str, str] | None = None
+        self.received = threading.Event()
+class _LoopbackHandler(BaseHTTPRequestHandler):
+    """Answers the provider redirect with a close-this-tab page; ignores stray requests."""
+    def do_GET(self) -> None:
+        server = cast(LoopbackServer, self.server)
+        params = dict(parse_qsl(urlsplit(self.path).query))
+        if not params:
+            # Stray request (favicon and friends), not the callback: keep waiting.
+            self.send_response(404)
+            self.end_headers()
+            return
+        body = _CALLBACK_HTML.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+        server.callback_params = params
+        server.received.set()
+    def log_message(self, format: str, *args: object) -> None:
+        logger.debug("oauth loopback server: %s", format % args)
+def serve_until(server: LoopbackServer, deadline: float) -> None:
+    """Handle requests until the callback arrives or the deadline passes."""
+    while not server.received.is_set() and time.monotonic() < deadline:
+        server.handle_request()
+def run_loopback_flow(
+    app: OAuthApp,
+    *,
+    scopes: list[str] | None = None,
+    open_url: Callable[[str], None],
+    timeout: float = 300.0,
+    transport: httpx.BaseTransport | None = None,
+) -> ConnectorAuth:
+    """Run the browser authorization-code flow against a localhost redirect (PKCE S256).
+    Binds an ephemeral `http://127.0.0.1:<port>/callback` server in a thread, hands the
+    authorize URL to `open_url` (the CLI layer prints/opens it; this module never does), waits
+    for exactly one callback, verifies the `state`, then exchanges the code at `app.token_url`.
+    Args:
+        app: The provider's OAuth application config.
+        scopes: Scopes to request; defaults to `app.scopes`.
+        open_url: Called once with the authorize URL (open a browser, print it, ...).
+        timeout: Seconds to wait for the browser callback.
+        transport: Injected httpx transport for the token exchange (tests); None = real network.
+    Returns:
+        The normalized oauth-kind credential.
+    Raises:
+        ConnectError: On denied consent, a state mismatch, a callback timeout, or a failed
+            token exchange.
+    """
+    requested = list(scopes) if scopes is not None else list(app.scopes)
+    verifier, challenge = pkce_challenge()
+    state = secrets.token_urlsafe(16)
+    server = LoopbackServer()
+    deadline = time.monotonic() + timeout
+    thread = threading.Thread(
+        target=serve_until, args=(server, deadline), name="wmo-oauth-loopback", daemon=True
+    )
+    port = int(server.server_address[1])
+    redirect_uri = f"http://127.0.0.1:{port}/callback"
+    try:
+        thread.start()
+        params: dict[str, str] = {
+            "client_id": app.client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "state": state,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+            **app.extra_auth_params,
+        }
+        if requested:
+            params["scope"] = " ".join(requested)
+        open_url(f"{app.auth_url}?{urlencode(params)}")
+        received = server.received.wait(timeout)
+    finally:
+        server.received.set()
+        thread.join(2.0)
+        server.server_close()
+    if not received:
+        raise ConnectError(
+            f"timed out after {timeout:g}s waiting for the {app.name} OAuth callback; "
+            "re-run the command and approve access in the browser"
+        )
+    callback = server.callback_params or {}
+    if "error" in callback:
+        raise ConnectError(
+            f"{app.name} authorization failed: {_describe_callback_error(callback)}; "
+            "re-run the command and approve access"
+        )
+    if callback.get("state") != state:
+        raise ConnectError(
+            f"OAuth state mismatch in the {app.name} callback (a stale browser tab or a "
+            "forged request); re-run the command and use the freshly opened tab"
+        )
+    code = callback.get("code")
+    if not code:
+        raise ConnectError(
+            f"the {app.name} callback carried no authorization code; re-run the command"
+        )
+    data = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": redirect_uri,
+        "client_id": app.client_id,
+        "code_verifier": verifier,
+    }
+    if app.client_secret:
+        data["client_secret"] = app.client_secret
+    response, payload = _token_request(app.token_url, data, transport=transport)
+    _raise_on_token_error(app, response, payload, doing="token exchange")
+    return _auth_from_token_response(payload, requested)
+def run_device_flow(
+    app: OAuthApp,
+    *,
+    scopes: list[str] | None = None,
+    present: Callable[[str, str], None],
+    timeout: float = 900.0,
+    transport: httpx.BaseTransport | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> ConnectorAuth:
+    """Run the RFC 8628 device authorization flow (for headless/SSH sessions).
+    Requests a device code, hands `(verification_uri, user_code)` to `present`, then polls
+    `app.token_url` honoring the server's `interval` and `slow_down` (+5s) responses.
+    Args:
+        app: The provider's OAuth application config (must define `device_url`).
+        scopes: Scopes to request; defaults to `app.scopes`.
+        present: Called once with the verification URI and user code to show the user.
+        timeout: Polling budget in seconds, measured against the injected `sleep` amounts.
+        transport: Injected httpx transport (tests); None = real network.
+        sleep: Injected sleeper so tests never wait on real clocks.
+    Returns:
+        The normalized oauth-kind credential.
+    Raises:
+        ConnectError: When the provider has no device endpoint, the user denies access, the
+            device code expires, or polling exceeds `timeout`.
+    """
+    if not app.device_url:
+        raise ConnectError(
+            f"{app.name} defines no device authorization endpoint; "
+            "use the browser flow (run_loopback_flow) instead"
+        )
+    requested = list(scopes) if scopes is not None else list(app.scopes)
+    data = {"client_id": app.client_id}
+    if requested:
+        data["scope"] = " ".join(requested)
+    response, payload = _token_request(app.device_url, data, transport=transport)
+    device_code = payload.get("device_code")
+    if response.status_code != 200 or not isinstance(device_code, str) or not device_code:
+        raise ConnectError(
+            f"device authorization at {app.device_url} failed "
+            f"(HTTP {response.status_code}): {response.text[:200]}; "
+            "check the OAuth app's client id and retry"
+        )
+    user_code = str(payload.get("user_code") or "")
+    verification_uri = str(payload.get("verification_uri") or payload.get("verification_url") or "")
+    interval_value = payload.get("interval")
+    interval = float(interval_value) if isinstance(interval_value, int | float) else 5.0
+    present(verification_uri, user_code)
+    poll = {"grant_type": _DEVICE_GRANT, "device_code": device_code, "client_id": app.client_id}
+    if app.client_secret:
+        poll["client_secret"] = app.client_secret
+    elapsed = 0.0
+    while True:
+        if elapsed + interval > timeout:
+            raise ConnectError(
+                f"timed out after {timeout:g}s waiting for {app.name} device authorization; "
+                "re-run the command and enter the code sooner"
+            )
+        sleep(interval)
+        elapsed += interval
+        response, payload = _token_request(app.token_url, poll, transport=transport)
+        error = payload.get("error")
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval += 5.0  # RFC 8628 section 3.5
+            continue
+        if error == "access_denied":
+            raise ConnectError(
+                f"{app.name} authorization was denied; re-run the command and approve access"
+            )
+        if error == "expired_token":
+            raise ConnectError(
+                f"the {app.name} device code expired before it was approved; "
+                "re-run the command for a fresh code"
+            )
+        _raise_on_token_error(app, response, payload, doing="device token poll")
+        return _auth_from_token_response(payload, requested)
+def refresh_auth(
+    app: OAuthApp,
+    auth: ConnectorAuth,
+    *,
+    transport: httpx.BaseTransport | None = None,
+) -> ConnectorAuth:
+    """Exchange the refresh token for a fresh access token.
+    Keeps the old refresh token when the response omits one (providers commonly rotate only the
+    access token) and carries the stored `account`/`extra` identity forward.
+    Raises:
+        ConnectError: When no refresh token is stored or the provider rejects the refresh.
+    """
+    if not auth.refresh_token:
+        raise ConnectError(
+            f"no refresh token stored for {app.name}; the connection must be reauthorized"
+        )
+    data = {
+        "grant_type": "refresh_token",
+        "refresh_token": auth.refresh_token,
+        "client_id": app.client_id,
+    }
+    if app.client_secret:
+        data["client_secret"] = app.client_secret
+    response, payload = _token_request(app.token_url, data, transport=transport)
+    _raise_on_token_error(app, response, payload, doing="token refresh")
+    refreshed = _auth_from_token_response(payload, auth.scopes)
+    return refreshed.model_copy(
+        update={
+            "refresh_token": refreshed.refresh_token or auth.refresh_token,
+            "account": auth.account,
+            "extra": auth.extra,
+        }
+    )
+def ensure_fresh(
+    app: OAuthApp,
+    name: str,
+    auth: ConnectorAuth,
+    *,
+    transport: httpx.BaseTransport | None = None,
+) -> ConnectorAuth:
+    """Refresh `auth` iff it expires within `REFRESH_LEEWAY_SECONDS` and can be refreshed.
+    A refreshed credential is persisted via `save_connector_auth(name, ...)` so the next
+    invocation starts fresh. Credentials without a refresh token or expiry pass through
+    unchanged (an unparseable `expires_at` is treated as already expired).
+    """
+    if not auth.refresh_token or not auth.expires_at:
+        return auth
+    expires = _parse_expiry(auth.expires_at)
+    if expires is not None:
+        remaining = (expires - datetime.now(UTC)).total_seconds()
+        if remaining > REFRESH_LEEWAY_SECONDS:
+            return auth
+    refreshed = refresh_auth(app, auth, transport=transport)
+    save_connector_auth(name, refreshed)
+    return refreshed
+def _parse_expiry(value: str) -> datetime | None:
+    """Parse an ISO-8601 expiry; naive timestamps are taken as UTC, garbage becomes None."""
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+def _token_request(
+    url: str, data: dict[str, str], *, transport: httpx.BaseTransport | None
+) -> tuple[httpx.Response, JsonObject]:
+    """POST a form-encoded OAuth request and parse the JSON object response (or {}).
+    Raises:
+        ConnectError: When the endpoint is unreachable (DNS, refused connection, timeout).
+    """
+    host = httpx.URL(url).host or url
+    with httpx.Client(timeout=_TOKEN_TIMEOUT_SECONDS, transport=transport) as client:
+        with transport_errors(host):
+            response = client.post(url, data=data, headers={"Accept": "application/json"})
+    try:
+        raw = response.json()
+    except ValueError:
+        raw = None
+    payload = cast(JsonObject, raw) if isinstance(raw, dict) else {}
+    return response, payload
+def _raise_on_token_error(
+    app: OAuthApp, response: httpx.Response, payload: JsonObject, *, doing: str
+) -> None:
+    """Turn OAuth error payloads and non-200 responses into actionable ConnectErrors."""
+    error = payload.get("error")
+    if error:
+        raise ConnectError(
+            f"{app.name} {doing} failed: {_describe_oauth_error(payload)}; "
+            "the connection must be reauthorized (check the OAuth app's client id/secret if it "
+            "keeps failing)"
+        )
+    if response.status_code != 200:
+        raise ConnectError(
+            f"{app.name} {doing} returned HTTP {response.status_code}: {response.text[:200]}; "
+            "check the OAuth app configuration and retry"
+        )
+def _describe_oauth_error(payload: JsonObject) -> str:
+    """'error: error_description' when a description is present, else just the error code."""
+    error = payload.get("error")
+    description = payload.get("error_description")
+    return f"{error}: {description}" if description else str(error)
+def _describe_callback_error(callback: dict[str, str]) -> str:
+    """Same shape as `_describe_oauth_error` for redirect-callback query params."""
+    error = callback.get("error", "unknown_error")
+    description = callback.get("error_description")
+    return f"{error}: {description}" if description else error
+def _auth_from_token_response(payload: JsonObject, fallback_scopes: list[str]) -> ConnectorAuth:
+    """Normalize an OAuth token response into a `ConnectorAuth`.
+    Handles the provider quirks the harness has to care about: `expires_in` as int or numeric
+    string (turned into an absolute ISO-8601 `expires_at`), `scope` as a space or comma
+    separated string or a list, and responses that omit scopes entirely (falls back to what was
+    requested).
+    """
+    access_token = payload.get("access_token")
+    if not isinstance(access_token, str) or not access_token:
+        raise ConnectError(
+            "the token response carried no access_token; "
+            "check the OAuth app's client id/secret and retry"
+        )
+    refresh_token = payload.get("refresh_token")
+    expires_in = payload.get("expires_in")
+    if isinstance(expires_in, str) and expires_in.isdigit():
+        expires_in = int(expires_in)
+    expires_at: str | None = None
+    if isinstance(expires_in, int | float) and not isinstance(expires_in, bool):
+        moment = datetime.now(UTC) + timedelta(seconds=float(expires_in))
+        expires_at = moment.isoformat(timespec="seconds")
+    scopes = _parse_scopes(payload.get("scope"))
+    return ConnectorAuth(
+        kind="oauth",
+        access_token=access_token,
+        refresh_token=refresh_token if isinstance(refresh_token, str) else None,
+        expires_at=expires_at,
+        scopes=scopes if scopes is not None else list(fallback_scopes),
+    )
+def _parse_scopes(value: JsonValue | None) -> list[str] | None:
+    """Scope fields arrive as a space/comma separated string or a list; None means absent."""
+    if isinstance(value, str):
+        return [scope for scope in re.split(r"[\s,]+", value) if scope]
+    if isinstance(value, list):
+        return [scope for scope in value if isinstance(scope, str)]
+    return None