feat: consolidate agent control-plane onto AgentClient; fix worker credential delivery

Refactors the agent runtime's server access onto the standard client stack and
fixes worker credential resolution to the server's runtimeMetadata contract.

AgentClient (interface + Orkes impl)
- Add `conductor.client.agent_client.AgentClient` (ABC) + `OrkesAgentClient`
  following the WorkflowClient/OrkesWorkflowClient pattern, built on the shared
  ApiClient (sync) / AsyncApiClient (async) so JWT mint / X-Authorization / TTL
  refresh / 401-retry are reused, not re-implemented. SSE reuses the ApiClient
  token via a new public `get_authentication_headers()`.
- `OrkesClients.get_agent_client()` returns the new client.
- Delete the duplicate transport (`client/ai/agent_api_client.py`) and the DX
  wrapper (`ai/agents/runtime/http_client.py`); AgentRuntime uses the one client
  for all /agent/* calls (start/deploy/compile/status/execution/respond/stop/
  signal/SSE), sync and async.

AgentRuntime / Configuration
- `AgentRuntime(configuration: Configuration = None, *, settings: AgentConfig = None)`:
  server config comes solely from the standard Configuration; AgentConfig carries
  runtime behaviour only. Remove the custom `to_conductor_configuration()` bridge
  and the private log-level poke.
- `Configuration` host resolution falls back CONDUCTOR_SERVER_URL -> AGENTSPAN_SERVER_URL.

Worker credentials via runtimeMetadata (conductor-oss PR #1255 contract)
- Add `Task.runtime_metadata` and `TaskDef.runtime_metadata` model fields.
- Stamp `TaskDef.runtimeMetadata` from a tool/agent's declared credentials at
  registration so the SDK's overwrite-registration no longer wipes the value the
  server compiles.
- Worker dispatch (+ langchain/langgraph/claude_agent_sdk wrappers) reads the
  host-resolved secrets off `Task.runtimeMetadata` instead of the retired
  execution-token / POST /workers/secrets path. Retire WorkerCredentialFetcher,
  `_extract_execution_token`, `_get_credential_fetcher`; `resolve_credentials(task, names)`
  now reads runtimeMetadata.

Remove server auto-start
- Delete `runtime/server.py` and the `auto_start_server` / AGENTSPAN_AUTO_START_SERVER
  config surface; runtime no longer probes or launches a local server.

CLI tools spawn-safety
- `cli_config._make_cli_tool` builds the `run_command` worker from a module-level
  `_CliCommandRunner` instance (not a <locals> closure), so registration's
  spawn-safety probe passes.

Tests / docs / examples
- New: orkes_agent_client, task/taskdef runtimeMetadata serde, runtime_metadata
  registration, e2e suite26 (worker credentials + CLI spawn-safety) unit/e2e tests.
- Update credential/dispatch/runtime/sse/signals tests to the new contracts;
  rewrite e2e suite24 for the transport-only client + runtime DX.
- Docs + examples updated (GH_TOKEN, Configuration-based AgentRuntime).

Author: v1r3n

docs/agents/advanced.md

@@ -12,31 +12,34 @@
 ## Runtime init and config
 
 `AgentRuntime` is the entry point. Use it as a context manager so workers shut down
-cleanly. Config comes from `AgentConfig.from_env()` by default, or pass overrides.
+cleanly. Server connection comes from the standard Conductor `Configuration` —
+the same object every other client uses — which resolves `CONDUCTOR_SERVER_URL`
+(falling back to `AGENTSPAN_SERVER_URL`) and `CONDUCTOR_AUTH_KEY`/`CONDUCTOR_AUTH_SECRET`
+from the environment when not passed explicitly.
 
 ```python
 from conductor.ai.agents import AgentRuntime, AgentConfig
+from conductor.client.configuration.configuration import Configuration
 
-# From env (AGENTSPAN_SERVER_URL etc.)
+# From env (CONDUCTOR_SERVER_URL → AGENTSPAN_SERVER_URL, CONDUCTOR_AUTH_*)
 with AgentRuntime() as runtime:
     runtime.run(agent, "hi")
 
-# Explicit kwargs
-with AgentRuntime(server_url="https://prod:8080/api",
-                  api_key="...") as runtime:
+# Explicit Configuration
+with AgentRuntime(Configuration(server_api_url="https://prod:8080/api")) as runtime:
     ...
 
-# Or an AgentConfig
-config = AgentConfig.from_env()
-config.auto_start_server = False
-with AgentRuntime(config=config) as runtime:
+# Runtime behaviour knobs (workers, streaming, log level) via AgentConfig
+settings = AgentConfig.from_env()
+settings.log_level = "DEBUG"
+with AgentRuntime(settings=settings) as runtime:
     ...
 ```
 
 `AgentConfig` is a dataclass; `from_env()` reads the `AGENTSPAN_*` environment
 variables (full list in [Getting started](getting-started.md#environment-variables)).
-The Conductor `Configuration` object underneath is built from `server_url` and the
-auth fields (`api_key`, or `auth_key`/`auth_secret`).
+It carries runtime *behaviour* settings only — server connection always comes from
+the `Configuration`.
 
 ### Module-level convenience functions
 
@@ -45,7 +48,7 @@ For one-off scripts, top-level functions use a shared singleton runtime:
 ```python
 import conductor.ai.agents as ag
 
-ag.configure(server_url="https://prod:8080/api", auto_start_server=False)  # before first run
+ag.configure(server_url="https://prod:8080/api")  # before first run
 result = ag.run(agent, "Hello!")
 ag.shutdown()    # explicit cleanup; not required for simple scripts
 ```

docs/agents/api-reference.md

@@ -19,7 +19,11 @@ agents](framework-agents.md), and [Advanced](advanced.md).
 
 ## AgentRuntime
 
-`AgentRuntime(*, server_url=None, api_key=None, api_secret=None, config=None)`
+`AgentRuntime(configuration=None, *, settings=None)` — `configuration` is the
+standard Conductor `Configuration` (host + auth; defaults to `Configuration()`,
+which resolves `CONDUCTOR_SERVER_URL` → `AGENTSPAN_SERVER_URL` and
+`CONDUCTOR_AUTH_*` from the environment); `settings` is an optional `AgentConfig`
+with runtime behaviour knobs (its connection fields are ignored).
 
 Context manager (sync and async: `with` / `async with`).
 
@@ -269,43 +273,46 @@ override. Pass instances via `Agent(callbacks=[...])`; they chain in list order.
 
 ## AgentClient
 
-The control-plane client (formerly `AgentHttpClient`, alias kept). Reach it via
-`runtime.client`, or construct standalone:
-`AgentClient(server_url="", api_key="", auth_key="", auth_secret="", *, runtime=None)`.
+The `/agent/*` control-plane client. `AgentClient` is an interface
+(`conductor.client.agent_client`) implemented by `OrkesAgentClient`
+(`conductor.client.orkes.orkes_agent_client`), following the same pattern as
+`WorkflowClient`/`OrkesWorkflowClient` and built on the shared `ApiClient`
+token machinery. Reach it via `runtime.client` or
+`OrkesClients(configuration).get_agent_client()`. Every method has an `*_async`
+counterpart.
 
 | Method | Signature | Purpose |
 |---|---|---|
-| `run` / `run_async` | `(agent, prompt=None, *, media=None, session_id=None, idempotency_key=None, timeout=None, context=None, static_plan=None) -> AgentResult` | Compile + start + poll (no local workers) |
-| `start` / `start_async` | same args | `-> AgentHandle` |
-| `deploy` / `deploy_async` | `(*agents) -> list[DeploymentInfo]` | Compile + register |
-| `schedule` | `(agent, schedules) -> DeploymentInfo` | Deploy + reconcile cron schedules |
-| `get_status` | `(execution_id) -> dict` | |
-| `respond` | `(execution_id, body) -> None` | |
-| `stop` | `(execution_id) -> None` | |
-| `signal` | `(execution_id, message) -> None` | |
-| `stream_sse` | `(execution_id) -> AsyncIterator[dict]` | |
-| `schedules` (property) | `-> SchedulerClient` | |
-| `close` | `() -> None` (async) | |
-
-Lower-level endpoint methods (`start_agent`, `deploy_agent`, `compile_agent`) are also
-available. The raw transport behind them is `conductor.client.ai.AgentApiClient`
-(build one with `OrkesClients.get_agent_client()`); `AgentClient` composes it and
-keeps the agent-level conveniences.
+| `start_agent` | `(payload) -> dict` | POST /agent/start |
+| `deploy_agent` | `(payload) -> dict` | POST /agent/deploy |
+| `compile_agent` | `(payload) -> dict` | POST /agent/compile |
+| `get_status` | `(execution_id) -> dict` | GET /agent/{id}/status |
+| `get_execution` | `(execution_id) -> dict` | GET /agent/execution/{id} |
+| `list_executions` | `(params=None) -> dict` | GET /agent/executions |
+| `respond` | `(execution_id, body) -> None` | POST /agent/{id}/respond |
+| `stop` | `(execution_id) -> None` | POST /agent/{id}/stop |
+| `signal` | `(execution_id, message) -> None` | POST /agent/{id}/signal |
+| `stream_sse` | `(execution_id, last_event_id=None) -> Iterator[dict]` | GET /agent/stream/{id} (SSE) |
+| `schedules` (property) | `-> SchedulerClient` | Cron schedule lifecycle |
+| `close` / `close_async` | `() -> None` | Release transport resources |
 
 ## Config and credentials
 
 `AgentConfig` (dataclass) fields: `server_url="http://localhost:8080/api"`,
 `api_key=None`, `auth_key=None`, `auth_secret=None`, `llm_retry_count=3`,
 `worker_poll_interval_ms=100`, `worker_thread_count=1`, `auto_start_workers=True`,
-`auto_start_server=True`, `daemon_workers=True`, `auto_register_integrations=False`,
+`daemon_workers=True`, `auto_register_integrations=False`,
 `streaming_enabled=True`, `secret_strict_mode=False`, `log_level="INFO"`. Classmethod
 `AgentConfig.from_env()` reads the `AGENTSPAN_*` variables (see [Getting
 started](getting-started.md#environment-variables)). Property `api_secret` aliases
-`auth_secret`.
+`auth_secret`. `AgentRuntime` uses it only for runtime *behaviour* knobs — server
+connection always comes from the Conductor `Configuration`.
 
 `get_secret(name) -> str` — read a credential inside a `@tool(credentials=[...])`
-function. `resolve_credentials(input_data, names) -> dict` — for external workers.
-Errors: `CredentialNotFoundError`, `CredentialAuthError`, `CredentialRateLimitError`,
+function. `resolve_credentials(task, names) -> dict` — for external workers; reads
+the host-resolved values the server delivers on `Task.runtimeMetadata` (declared via
+the tool/agent `credentials`, resolved at poll time). Errors:
+`CredentialNotFoundError`, `CredentialAuthError`, `CredentialRateLimitError`,
 `CredentialServiceError`.
 
 `ClaudeCode(model_name="", permission_mode=PermissionMode.ACCEPT_EDITS)` with

docs/agents/getting-started.md

@@ -60,7 +60,6 @@ the output if you prefer.
 | `AGENTSPAN_WORKER_POLL_INTERVAL` | `100` | Worker poll interval (ms) |
 | `AGENTSPAN_WORKER_THREADS` | `1` | Worker thread count |
 | `AGENTSPAN_AUTO_START_WORKERS` | `true` | Auto-start local tool workers |
-| `AGENTSPAN_AUTO_START_SERVER` | `true` | Auto-start a local server if none is reachable |
 | `AGENTSPAN_DAEMON_WORKERS` | `true` | Run workers as daemon threads |
 | `AGENTSPAN_INTEGRATIONS_AUTO_REGISTER` | `false` | Auto-register provider integrations |
 | `AGENTSPAN_STREAMING_ENABLED` | `true` | Enable SSE streaming |

e2e/conftest.py

@@ -15,11 +15,6 @@
 MODEL = os.environ.get("AGENTSPAN_LLM_MODEL", "openai/gpt-4o-mini")
 
 
-# ── Prevent runtime from auto-starting a second server ──────────────────
-
-os.environ["AGENTSPAN_AUTO_START_SERVER"] = "false"
-
-
 # ── Markers ─────────────────────────────────────────────────────────────
 
 

e2e/test_suite24_agent_client.py

@@ -1,18 +1,21 @@
-"""Suite 24: AgentClient — control-plane run + schedule surface.
+"""Suite 24: AgentClient (transport) + runtime run/start + schedule surface.
 
-Verifies the control-plane :class:`AgentClient` (formerly ``AgentHttpClient``)
-exposed via ``runtime.client``:
+``runtime.client`` is the transport :class:`AgentClient`
+(``conductor.client.orkes.orkes_agent_client.OrkesAgentClient``) — the
+``/agent/*`` control-plane endpoints built on the shared ``ApiClient``. The
+run/start DX lives on the runtime; the schedule lifecycle is reachable from both
+``runtime.schedules_client()`` and ``runtime.client.schedules``.
 
-- ``run`` on an LLM-only agent (no local tools) reaches status COMPLETED.
-  Control-plane only: no local tool workers are registered/polled.
-- ``schedule(agent, [Schedule(...)])`` deploys + reconciles; the schedule then
-  shows up in ``list_for_agent``. A counterfactual ``reconcile([])`` purges it.
-- The runtime's schedule surface (``runtime.schedules_client()``) and the
-  client's (``runtime.client.schedules``) are the *same* instance.
+Verifies:
+- ``runtime.run`` on an LLM-only agent (no local tools) reaches COMPLETED.
+- ``runtime.start`` returns a handle that joins to COMPLETED.
+- ``schedules.reconcile(agent, [Schedule(...)])`` upserts and lists; a
+  counterfactual ``reconcile([])`` purges it.
+- ``runtime.client`` is the runtime's own transport client, and both schedule
+  accessors return working ``SchedulerClient``s.
 
-No LLM is used for validation — assertions are on workflow status / schedule
-structure only (per CLAUDE.md rule 1). The scheduled "agent" target is a bare
-no-op Conductor workflow so no LLM is invoked for the schedule tests.
+The scheduled "agent" target is a bare no-op Conductor workflow so no LLM is
+invoked for the schedule tests.
 
 Targets the live Agentspan server (``AGENTSPAN_SERVER_URL``). The schedule
 tests are skipped automatically if the server's Conductor lacks the scheduler
@@ -63,24 +66,22 @@ def test_run_llm_only_agent_completes(self, runtime, model):
             instructions="You are a calculator. Reply with only the number.",
         )
 
-        result = runtime.client.run(agent, "What is 2 + 2? Reply with only the number.")
+        result = runtime.run(agent, "What is 2 + 2? Reply with only the number.")
 
         assert result.status == Status.COMPLETED, (
             f"expected COMPLETED, got {result.status} (error={result.error})"
         )
         assert result.execution_id
-        # No local tool workers were started for this control-plane run.
-        assert runtime._workers_started is False
 
     def test_start_returns_handle_then_joins(self, runtime, model):
-        """AgentClient.start returns a handle that joins to a COMPLETED result."""
+        """runtime.start returns a handle that joins to a COMPLETED result."""
         agent = Agent(
             name=f"e2e_client_start_{uuid.uuid4().hex[:8]}",
             model=model,
             instructions="Reply with the single word: ok",
         )
 
-        handle = runtime.client.start(agent, "Say ok")
+        handle = runtime.start(agent, "Say ok")
         assert handle.execution_id
         result = handle.join(timeout=120)
         assert result.status == Status.COMPLETED
@@ -145,16 +146,22 @@ def test_schedule_then_list_then_purge(self, runtime, noop_agent_name):
         assert not schedules.get_all_schedules(workflow_name=noop_agent_name)
 
 
-# ── structural consistency: runtime + client share one schedule surface ──
+# ── structural consistency: transport client + schedule accessors ────────
 
 
 class TestScheduleSurfaceConsistency:
-    def test_runtime_and_client_share_schedule_client(self, runtime):
-        """runtime.schedules_client() and runtime.client.schedules are identical."""
-        from_runtime = runtime.schedules_client()
-        from_client = runtime.client.schedules
-        assert from_runtime is from_client
-
-    def test_client_is_bound_to_runtime(self, runtime):
-        """runtime.client is the runtime's own control-plane client (not a copy)."""
-        assert runtime.client is runtime._http
+    def test_both_schedule_accessors_are_scheduler_clients(self, runtime):
+        """Both runtime.schedules_client() and runtime.client.schedules return a
+        working SchedulerClient (the transport client builds its own from the same
+        Configuration; they are no longer required to be the same instance)."""
+        from conductor.client.scheduler_client import SchedulerClient
+
+        assert isinstance(runtime.schedules_client(), SchedulerClient)
+        assert isinstance(runtime.client.schedules, SchedulerClient)
+
+    def test_client_is_the_runtime_agent_client(self, runtime):
+        """runtime.client is the runtime's own transport AgentClient (not a copy)."""
+        from conductor.client.agent_client import AgentClient
+
+        assert runtime.client is runtime._agent_client
+        assert isinstance(runtime.client, AgentClient)