Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 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
0aaa885
Merge remote-tracking branch 'origin/tino097/eng-3850-use-a-members-c…
tino097 Nov 11, 2026
81281e5
Merge the connector template branch with its auth section into the in…
tino097 Nov 12, 2026
8a60e8e
Merge staging into the integration branch
tino097 Nov 12, 2026
4ce1b82
Merge the versioned-path tool texts into the integration branch
tino097 Nov 12, 2026
4e9b0a6
Merge staging into integration
tino097 Nov 12, 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
5a12666
Merge staging into integration
tino097 Nov 13, 2026
49a7634
Merge reworked custom API helper branch into integration
tino097 Nov 13, 2026
2ee98cf
Merge staging
tino097 Nov 13, 2026
a61bb1e
Merge staging
tino097 Nov 13, 2026
aa02672
Merge the custom API helper branch, now carrying staging, into the in…
tino097 Nov 13, 2026
ef276f5
Merge staging
tino097 Nov 14, 2026
0283ed1
Merge the custom API helper branch, now carrying staging, into the in…
tino097 Nov 14, 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)
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"}:
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 @@ -571,6 +646,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