Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
01442b4
Read the custom API block of a cloud turn
tino097 Nov 10, 2026
1aa3961
Fetch custom connection fields with the turn key
tino097 Nov 10, 2026
cacaced
Prove a custom connection's values reach no log, prompt or output
tino097 Nov 10, 2026
c2ae61b
Hide every custom field but its address on turns, whatever the templa…
tino097 Nov 10, 2026
68f5d16
Keep every field auth marks secure hidden on turns too
tino097 Nov 10, 2026
b3c49c7
Never start a custom connection fetch still queued at the deadline
tino097 Nov 10, 2026
530a87e
Leave a short config value auth did not mark secure readable on turns
tino097 Nov 10, 2026
ecbc434
Hide a short custom value on turns too, whatever the template flagged
tino097 Nov 10, 2026
8959f7a
Require a check when Anton builds a connector template
tino097 Nov 10, 2026
8914494
Tell Anton what to do when a check cannot place the key
tino097 Nov 10, 2026
434e661
Test the key-in-URL check refusal by its path
tino097 Nov 10, 2026
14984de
Merge staging into the custom API block branch
tino097 Nov 12, 2026
d9cba33
Write the usage-notes example as a helper call, with the query apart …
tino097 Nov 12, 2026
0782d74
Stop fetching a custom connection's fields into the pod
tino097 Nov 12, 2026
319acd2
Hand the turn's custom API connections to the scratchpad by id and ve…
tino097 Nov 12, 2026
7d69a6b
Tell the model about its custom API connections, with their notes kep…
tino097 Nov 12, 2026
c8b39af
Add call_minds_api, the turn-key-bound custom API helper
tino097 Nov 12, 2026
6e79422
Keep every malformed gateway answer inside the helper's closed codes,…
tino097 Nov 13, 2026
2ee98cf
Merge staging
tino097 Nov 13, 2026
a61bb1e
Merge staging
tino097 Nov 13, 2026
ef276f5
Merge staging
tino097 Nov 14, 2026
12860fe
Let a template mark its key optional and give a public check path
tino097 Nov 14, 2026
bebb774
Align the optional key tool text with the parser and tighten stored B…
tino097 Nov 14, 2026
4906797
Merge staging
tino097 Nov 16, 2026
1055772
Move the optional key support to its own change
tino097 Nov 16, 2026
4f5a86d
Let a template mark its key optional and give a public check path
tino097 Nov 14, 2026
ede4e0d
Align the optional key tool text with the parser and tighten stored B…
tino097 Nov 14, 2026
fa559f4
Merge pull request #809 from mindsdb/tino097/eng-3850-optional-custom…
tino097 Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 77 additions & 1 deletion anton/cloud_turn/contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,13 @@
TURN_PROTOCOL_VERSION = 1
DATASOURCE_PROTOCOL_VERSION = 1
MAX_DATASOURCE_CONNECTIONS = 100
#: The most custom API connections one turn carries; cowork-server holds the
#: same cap.
MAX_CUSTOM_API_CONNECTIONS = 25
#: The connector id rule anton's draft parser applies, and auth's longest
#: connection name: a block outside them did not come from those writers.
_CUSTOM_CONNECTOR_ID = re.compile(r"[a-z][a-z0-9_]{1,40}")
_CUSTOM_NAME_MAX = 128
_REQUIRED_REF_KEYS = frozenset({"connection_id", "credential_version"})
# Names only, for the prompt. cowork-server's queue check allows the same two.
_OPTIONAL_REF_KEYS = frozenset({"label", "engine"})
Expand Down Expand Up @@ -286,6 +293,70 @@ def _parse_datasource_block(value: object) -> DatasourceBlockV1 | None:
return DatasourceBlockV1(DATASOURCE_PROTOCOL_VERSION, tuple(refs))


@dataclass(frozen=True)
class CustomApiConnectionRefV1:
"""One custom API connection the turn may call: auth's id and the member's own names, never a value."""

connection_id: int
connector_id: str
name: str
credential_version: int


@dataclass(frozen=True, repr=False)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TurnRequestV1 is a plain dataclass whose repr still shows the turn key through llm and oauth, so this does not keep the key out of a printed request. Also, turn_key here must equal llm.api_key and the helper never reads it, so it could be dropped.

class CustomApiBlockV1:
"""The member's custom API connections and the turn key their grants are bound to.

``repr=False`` keeps the key out of any traceback that prints the request.
"""

turn_key: str
connections: tuple[CustomApiConnectionRefV1, ...]


def _positive_int(value: object) -> bool:
"""Whether ``value`` is an int of 1 or more, booleans excluded."""
return not isinstance(value, bool) and isinstance(value, int) and value >= 1


def _parse_custom_api_block(value: object) -> CustomApiBlockV1 | None:
"""Parse the optional ``custom_api`` block exactly, or refuse the request."""
if value is None:
return None
if not isinstance(value, dict) or set(value) != {"turn_key", "connections"}:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The block has no protocol_version and refuses any extra key, so if cowork-server ever adds a field, every turn with custom connections fails on pods running this version. Adding a version now, or dropping the block with a log line instead of failing the turn, would avoid that.

raise ValueError("custom_api must carry exactly turn_key and connections")
turn_key = value["turn_key"]
if not isinstance(turn_key, str) or not turn_key:
raise ValueError("custom_api turn key is missing")
connections = value["connections"]
if not isinstance(connections, list) or not connections or len(connections) > MAX_CUSTOM_API_CONNECTIONS:
raise ValueError("custom_api connections are invalid")
refs: list[CustomApiConnectionRefV1] = []
seen: set[int] = set()
for connection in connections:
if not isinstance(connection, dict) or set(connection) != {
"connection_id", "connector_id", "name", "credential_version",
}:
raise ValueError("custom_api connection reference is invalid")
connection_id = connection["connection_id"]
if (
not _positive_int(connection_id)
or not _positive_int(connection["credential_version"])
or not isinstance(connection["connector_id"], str)
or not _CUSTOM_CONNECTOR_ID.fullmatch(connection["connector_id"])
or not isinstance(connection["name"], str)
or not connection["name"]
or len(connection["name"]) > _CUSTOM_NAME_MAX
or connection_id in seen
):
raise ValueError("custom_api connection reference is invalid")
seen.add(connection_id)
refs.append(CustomApiConnectionRefV1(
connection_id, connection["connector_id"], connection["name"], connection["credential_version"],
))
return CustomApiBlockV1(turn_key, tuple(refs))


def _usable_label(value: object) -> str | None:
"""The connection's name as one clean prompt line, or ``None`` when nothing usable is left.

Expand Down Expand Up @@ -486,6 +557,9 @@ class TurnRequestV1:
#: id), which only the prompt reads. No capability or password crosses; the
#: gateway is on the `llm` base URL's host.
datasource: DatasourceBlockV1 | None = None
#: Optional custom API connections of the member, by auth id, with the turn
#: key their grants are bound to (this turn only). No value.
custom_api: CustomApiBlockV1 | None = None
#: Optional ISO 8601 creation time of the conversation, as cowork-server
#: resolved it. The pod is new every turn and cannot derive this: history
#: rows carry no timestamps. Without it the session dates the conversation
Expand Down Expand Up @@ -522,7 +596,8 @@ class TurnRequestV1:
preview_checks: bool = False
#: Per-engine connector data cowork-server resolved for this turn:
#: {engine: {"usage_notes": str}}. Rendered only for engines the turn's
#: vault connects. Absent when no connected engine has notes.
#: vault connects and, apart and as data, for the connector ids of the
#: ``custom_api`` block. Absent when no connected engine has notes.
connectors: dict | None = None
#: Whether this turn may build connector templates with
#: `create_connector_draft`, sent back on the `connector` event. Anything
Expand Down Expand Up @@ -574,6 +649,7 @@ def from_json(raw: str) -> "TurnRequestV1":
# Same defensive isinstance check as trace, for the same reason.
oauth=d.get("oauth") if isinstance(d.get("oauth"), dict) else None,
datasource=_parse_datasource_block(d.get("datasource")),
custom_api=_parse_custom_api_block(d.get("custom_api")),
# The controller always sends the key and sends None when
# cowork-server could not resolve it, so the guard does real work.
started_at=(
Expand Down
121 changes: 86 additions & 35 deletions anton/cloud_turn/session.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
import shutil
import sys
import tempfile
import uuid
from datetime import datetime
from pathlib import Path, PurePosixPath
from typing import TYPE_CHECKING
Expand Down Expand Up @@ -175,25 +176,22 @@
_CLOUD_TURN_ENV = "ANTON_CLOUD_TURN"
_DATASOURCE_CORRELATION_ENV = "ANTON_CLOUD_DATASOURCE_CORRELATION_ID"
_DATASOURCE_CONNECTIONS_ENV = "ANTON_CLOUD_DATASOURCE_CONNECTIONS"
_CUSTOM_API_CORRELATION_ENV = "ANTON_CLOUD_CUSTOM_API_CORRELATION_ID"
_CUSTOM_API_CONNECTIONS_ENV = "ANTON_CLOUD_CUSTOM_API_CONNECTIONS"


def _datasource_workspace_env(request: TurnRequestV1, settings: AntonSettings) -> dict[str, str]:
"""Build pod-child configuration for a turn, refusing a datasource turn that could not reach the gateway.
def _carries_this_turns_inference(request: TurnRequestV1, settings: AntonSettings) -> bool:
"""Whether the child's ``OPENAI_API_KEY`` and base are this turn's own inference connection.

The scratchpad's datasource helper sends the child's own ``OPENAI_API_KEY``
to the gateway at the child's ``OPENAI_BASE_URL``, which is the inference
host the gateway is published on. That holds only while both are this turn's
own, so the turn fails here when a pod setting such as
``ANTON_OPENAI_API_KEY`` has replaced either, or the base is not https at
``/v1``. Raises ``ValueError`` in those cases.
The scratchpad's gateway helpers send the child's key to the child's base,
which is the inference host the gateways are published on. That holds only
while a pod setting such as ``ANTON_OPENAI_API_KEY`` has replaced neither,
and the base is https at ``/v1``. No side effects.
"""
overlay = {_CLOUD_TURN_ENV: "1"}
if request.datasource is None:
return overlay
llm = request.llm or {}
base = (settings.openai_base_url or "").rstrip("/")
parsed = urlsplit(base)
if (
return not (
llm.get("provider") != "minds-cloud"
or not isinstance(llm.get("api_key"), str)
or not llm["api_key"]
Expand All @@ -206,25 +204,73 @@ def _datasource_workspace_env(request: TurnRequestV1, settings: AntonSettings) -
or parsed.path != "/v1"
or parsed.query
or parsed.fragment
):
raise ValueError("the turn's inference connection cannot carry datasource reads")
if not request.correlation_id:
raise ValueError("datasource turn credentials are unavailable")
overlay.update(
{
_DATASOURCE_CORRELATION_ENV: request.correlation_id,
_DATASOURCE_CONNECTIONS_ENV: json.dumps(
[
{
"connection_id": ref.connection_id,
"credential_version": ref.credential_version,
}
for ref in request.datasource.connections
],
separators=(",", ":"),
),
}
)


def _is_canonical_uuid(value: object) -> bool:
"""Whether ``value`` is a UUID in the lowercase hyphenated form the producer sends."""
if not isinstance(value, str):
return False
try:
return str(uuid.UUID(value)) == value
except ValueError:
return False


def _cloud_turn_workspace_env(request: TurnRequestV1, settings: AntonSettings) -> dict[str, str]:
"""Build pod-child configuration for a turn, refusing a gateway turn that could not reach its gateway.

Input: the parsed request and the turn's settings. Output: the overlay for
every scratchpad child, which marks a cloud turn and, per block, carries the
datasource or custom API connections by id and version only, with the
correlation id. Raises ``ValueError`` when a datasource or custom API turn's
child would not send this turn's own key to this turn's inference host,
when the custom API block's key is not that key, or when the correlation id
is missing (or, for custom API calls, not a UUID). No side effects.
"""
overlay = {_CLOUD_TURN_ENV: "1"}
if request.datasource is not None:
if not _carries_this_turns_inference(request, settings):
raise ValueError("the turn's inference connection cannot carry datasource reads")
if not request.correlation_id:
raise ValueError("datasource turn credentials are unavailable")
overlay.update(
{
_DATASOURCE_CORRELATION_ENV: request.correlation_id,
_DATASOURCE_CONNECTIONS_ENV: json.dumps(
[
{
"connection_id": ref.connection_id,
"credential_version": ref.credential_version,
}
for ref in request.datasource.connections
],
separators=(",", ":"),
),
}
)
if request.custom_api is not None:
if not _carries_this_turns_inference(request, settings) or not hmac.compare_digest(
request.custom_api.turn_key.encode(), request.llm["api_key"].encode()
):
raise ValueError("the turn's inference connection cannot carry custom API calls")
if not _is_canonical_uuid(request.correlation_id):
raise ValueError("custom API turn credentials are unavailable")
overlay.update(
{
_CUSTOM_API_CORRELATION_ENV: request.correlation_id,
_CUSTOM_API_CONNECTIONS_ENV: json.dumps(
[
{
"connection_id": ref.connection_id,
"credential_version": ref.credential_version,
}
for ref in request.custom_api.connections
],
separators=(",", ":"),
),
}
)
return overlay


Expand Down Expand Up @@ -886,7 +932,7 @@ def build_cloud_chat_session(
from anton.config.settings import AntonSettings
from anton.core.backends.local import local_scratchpad_runtime_factory
from anton.core.llm.client import LLMClient
from anton.core.llm.identity import build_runtime_context
from anton.core.llm.identity import build_runtime_context, render_custom_api_notes
from anton.core.session import ChatSession, ChatSessionConfig, SystemPromptContext
from anton.workspace import Workspace

Expand Down Expand Up @@ -1045,6 +1091,7 @@ def build_cloud_chat_session(
extra_tools.append(draft_tool)
tool_allowlist |= {draft_tool.name}

custom_api_notes = render_custom_api_notes(request.custom_api, request.connectors)
config = ChatSessionConfig(
llm_client=llm_client,
settings=settings,
Expand All @@ -1065,13 +1112,17 @@ def build_cloud_chat_session(
# configured block is the same one desktop injects; the serving-model
# line is derived by the session from the provider's response.
system_prompt_context=SystemPromptContext(
runtime_context=build_runtime_context(settings, cloud_datasource=request.datasource),
runtime_context=build_runtime_context(
settings, cloud_datasource=request.datasource, cloud_custom_api=request.custom_api
),
# The delivery half and the credential half of the prompt context;
# the desktop harness injects its own via `_turn_style_context`.
# Org and team skills cowork marks always-on follow, so they hold
# on every turn rather than only when recalled.
# on every turn rather than only when recalled. Custom API usage
# notes are model-written, so they come first: later is stronger.
suffix=(
(_POD_PROMPT_SUFFIX_WITH_TEMPLATES if connector_drafts is not None else _POD_PROMPT_SUFFIX)
(f"{custom_api_notes}\n\n" if custom_api_notes else "")
+ (_POD_PROMPT_SUFFIX_WITH_TEMPLATES if connector_drafts is not None else _POD_PROMPT_SUFFIX)
+ render_always_on_skills(_always_on_skills(turn_skills))
),
),
Expand Down Expand Up @@ -1111,7 +1162,7 @@ def build_cloud_chat_session(
mcp_sessions=mcp_sessions, # closed in ChatSession.close()
background_memory=False, # one turn per pod: no end-of-turn LLM passes
runtime_factory=local_scratchpad_runtime_factory,
workspace_env_overlay=_datasource_workspace_env(request, settings),
workspace_env_overlay=_cloud_turn_workspace_env(request, settings),
web_search_enabled=False,
web_fetch_enabled=False,
browser=request.browser,
Expand Down
2 changes: 1 addition & 1 deletion anton/core/backends/local.py
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ def _encode_cell_payload(payload: str) -> bytes:


def _is_cloud_turn_state(key: str) -> bool:
return key == "ANTON_CLOUD_TURN" or key.startswith("ANTON_CLOUD_DATASOURCE_")
return key == "ANTON_CLOUD_TURN" or key.startswith(("ANTON_CLOUD_DATASOURCE_", "ANTON_CLOUD_CUSTOM_API_"))


def _apply_workspace_overlay(env: dict[str, str], overlay: dict[str, str] | None) -> list[str]:
Expand Down
Loading
Loading