feat(secrets): add sync and async exact ID handles (#11)

* feat(secrets): add sync and async ID handles preserving name behavior

* refactor(secrets): trim ID handle changes to focused SDK scope

* test(secrets): consolidate SDK lifecycle coverage

Author: sid-rl

README-SDK.md

@@ -10,6 +10,7 @@ The `RunloopSDK` builds on top of the underlying REST client and provides a Pyth
 - [Core Concepts](#core-concepts)
   - [RunloopSDK](#runloopsdk)
   - [Available Resources](#available-resources)
+  - [Secrets: names and exact IDs](#secrets-names-and-exact-ids)
   - [Devbox](#devbox)
     - [Command Execution](#command-execution)
     - [Execution Management](#execution-management)
@@ -128,6 +129,20 @@ The SDK provides object-oriented interfaces for all major Runloop resources:
 - **`runloop.secret`** - Secret management (create, update, list, delete encrypted key-value pairs)
 - **`runloop.api`** - Direct access to the underlying REST API client
 
+### Secrets: names and exact IDs
+
+`Secret` / `AsyncSecret` objects from `create()`, `list()`, and `from_name()` always operate by name, even when they carry a captured `.id`. Use a separate `SecretById` / `AsyncSecretById` handle for one exact row:
+
+```python
+created = runloop.secret.create(name="API_TOKEN", value="synthetic-example")
+assert created.id is not None
+exact = runloop.secret.from_id(created.id)  # Lazy; never falls back to a name.
+exact.update("synthetic-rotated")  # Returns SecretView, as do get_info() and delete().
+exact.delete()  # Deletes only this row.
+```
+
+For `AsyncRunloopSDK`, await the operations but not `from_id()`. The handle types are exported from `runloop_api_client.sdk`. ID handles have `.id`, not `.name`; use their instance methods rather than name-only manager helpers. Environment-secret maps still take names; pass `exact.id` explicitly for an ID-based gateway/MCP binding. Name reads/updates select the greatest ID; name deletion removes selected matches nonatomically. IDs identify mutable rows, not value versions, and existing retries can replay writes. Rotation does not rewrite running devbox environments or issued tokens. Avoid debug request logging with real credentials.
+
 ### Devbox
 
 Object-oriented interface for working with devboxes. Created via `runloop.devbox.create()`, `runloop.devbox.create_from_blueprint_id()`, `runloop.devbox.create_from_blueprint_name()`, `runloop.devbox.create_from_snapshot()`, or `runloop.devbox.from_id()`:

docs/api/secret.rst

@@ -8,7 +8,13 @@ Secret
       .. automodule:: runloop_api_client.sdk.async_secret
          :members:
 
+      .. automodule:: runloop_api_client.sdk.async_secret_by_id
+         :members:
+
    .. tab:: Sync
 
       .. automodule:: runloop_api_client.sdk.secret
          :members:
+
+      .. automodule:: runloop_api_client.sdk.secret_by_id
+         :members:

src/runloop_api_client/sdk/__init__.py

@@ -43,6 +43,7 @@
 from .async_agent import AsyncAgent
 from .async_devbox import AsyncDevbox, AsyncNamedShell
 from .async_secret import AsyncSecret
+from .secret_by_id import SecretById
 from .async_snapshot import AsyncSnapshot
 from .gateway_config import GatewayConfig
 from .network_policy import NetworkPolicy
@@ -51,6 +52,7 @@
 from .async_execution import AsyncExecution
 from .async_mcp_config import AsyncMcpConfig
 from .execution_result import ExecutionResult
+from .async_secret_by_id import AsyncSecretById
 from .async_gateway_config import AsyncGatewayConfig
 from .async_network_policy import AsyncNetworkPolicy
 from .async_storage_object import AsyncStorageObject
@@ -98,6 +100,8 @@
     "Blueprint",
     "AsyncBlueprint",
     "Secret",
+    "SecretById",
+    "AsyncSecretById",
     "AsyncSecret",
     "Snapshot",
     "AsyncSnapshot",

src/runloop_api_client/sdk/async_.py

@@ -45,6 +45,7 @@
 from .async_blueprint import AsyncBlueprint
 from .async_mcp_config import AsyncMcpConfig
 from ..types.secret_view import SecretView
+from .async_secret_by_id import AsyncSecretById
 from ..lib.context_loader import TarFilter, build_directory_tar
 from .async_gateway_config import AsyncGatewayConfig
 from .async_network_policy import AsyncNetworkPolicy
@@ -1006,7 +1007,7 @@ async def create(self, name: str, value: str, **options: Unpack[LongRequestOptio
             ... )
             >>> print(f"Created secret: {secret.name}")
 
-        :param name: Globally unique secret name (must be a valid env var name)
+        :param name: Account-scoped secret name (must be a valid env var name)
         :type name: str
         :param value: Secret value to store (encrypted at rest)
         :type value: str
@@ -1027,13 +1028,17 @@ def from_name(self, name: str) -> AsyncSecret:
             >>> info = await secret.get_info()
             >>> print(f"Secret ID: {info.id}")
 
-        :param name: The globally unique name of the secret
+        :param name: The literal account-scoped name of the secret
         :type name: str
         :return: An AsyncSecret instance (no API call made)
         :rtype: AsyncSecret
         """
         return AsyncSecret(self._client, name)
 
+    def from_id(self, id: str) -> AsyncSecretById:
+        """Get a lazy exact-ID handle; its operations never fall back to a name."""
+        return AsyncSecretById(self._client, id)
+
     async def update(
         self,
         secret: "AsyncSecret | str",

src/runloop_api_client/sdk/async_secret.py

@@ -13,8 +13,10 @@ class AsyncSecret:
     """Asynchronous wrapper around a secret resource.
 
     Secrets are encrypted key-value pairs that can be securely stored and injected
-    into Devboxes as environment variables. Secrets are identified by their globally
-    unique name.
+    into Devboxes as environment variables. This wrapper always operates by its account-scoped
+    name, even if it contains an ID from an earlier response. Reads and updates
+    select the greatest ID at lookup; deletion removes all selected matches,
+    nonatomically. Use ``sdk.secret.from_id(id)`` for exact row operations.
 
     Example:
         >>> runloop = AsyncRunloopSDK()
@@ -36,7 +38,7 @@ def __init__(
 
         :param client: Generated AsyncRunloop client
         :type client: AsyncRunloop
-        :param name: The globally unique name of the secret
+        :param name: The literal account-scoped name of the secret
         :type name: str
         :param id: The secret ID (optional, may not be known until get_info is called)
         :type id: str | None
@@ -53,7 +55,7 @@ def __repr__(self) -> str:
     def id(self) -> str | None:
         """Return the secret ID.
 
-        :return: Secret ID, or None if not yet fetched from API
+        :return: Captured response ID, or None. Fetching metadata does not refresh this property.
         :rtype: str | None
         """
         return self._id
@@ -62,7 +64,7 @@ def id(self) -> str | None:
     def name(self) -> str:
         """Return the secret name.
 
-        :return: Globally unique secret name
+        :return: Literal account-scoped secret name
         :rtype: str
         """
         return self._name
@@ -93,7 +95,9 @@ async def update(
         value: str,
         **options: Unpack[LongRequestOptions],
     ) -> SecretView:
-        """Update this secret's value.
+        """Update the greatest-ID row matching this name at lookup.
+
+        This wrapper remains name-bound and its captured ID is unchanged.
 
         Example:
             >>> updated = await secret.update("new-secret-value")
@@ -115,7 +119,9 @@ async def delete(
         self,
         **options: Unpack[LongRequestOptions],
     ) -> SecretView:
-        """Delete this secret. This action is irreversible.
+        """Delete every selected row matching this name, nonatomically.
+
+        A concurrent create can survive. This action is irreversible.
 
         Example:
             >>> await secret.delete()

src/runloop_api_client/sdk/async_secret_by_id.py

@@ -0,0 +1,44 @@
+"""Exact-ID Secret operations, separate from legacy name selectors."""
+
+from __future__ import annotations
+
+from typing_extensions import Unpack, override
+
+from ._types import BaseRequestOptions, LongRequestOptions
+from .._client import AsyncRunloop
+from ..types.secret_view import SecretView
+
+
+class AsyncSecretById:
+    """An exact Secret row, obtained with ``sdk.secret.from_id(id)``.
+
+    Construction makes no request. The ID never changes, but another writer can
+    change the value. Requests retain the generated client's retry policy and are
+    not exactly-once operations. Use ``get_info()`` for the name and metadata;
+    values are never returned.
+    """
+
+    def __init__(self, client: AsyncRunloop, id: str) -> None:
+        self._client = client
+        self._id = id
+
+    @override
+    def __repr__(self) -> str:
+        return f"<AsyncSecretById id={self._id!r}>"
+
+    @property
+    def id(self) -> str:
+        """The exact row ID, not a name or an immutable value-version identifier."""
+        return self._id
+
+    async def get_info(self, **options: Unpack[BaseRequestOptions]) -> SecretView:
+        """Retrieve this row's metadata. Missing IDs never fall back to names."""
+        return await self._client.secrets.retrieve_by_id(self._id, **options)
+
+    async def update(self, value: str, **options: Unpack[LongRequestOptions]) -> SecretView:
+        """Replace this row's value, without changing running devbox environments or issued tokens."""
+        return await self._client.secrets.update_by_id(self._id, value=value, **options)
+
+    async def delete(self, **options: Unpack[LongRequestOptions]) -> SecretView:
+        """Delete only this row. Name readers may then see an older same-name row."""
+        return await self._client.secrets.delete_by_id(self._id, **options)

src/runloop_api_client/sdk/secret.py

@@ -13,8 +13,10 @@ class Secret:
     """Synchronous wrapper around a secret resource.
 
     Secrets are encrypted key-value pairs that can be securely stored and injected
-    into Devboxes as environment variables. Secrets are identified by their globally
-    unique name.
+    into Devboxes as environment variables. This wrapper always operates by its account-scoped
+    name, even if it contains an ID from an earlier response. Reads and updates
+    select the greatest ID at lookup; deletion removes all selected matches,
+    nonatomically. Use ``sdk.secret.from_id(id)`` for exact row operations.
 
     Example:
         >>> runloop = RunloopSDK()
@@ -36,9 +38,9 @@ def __init__(
 
         :param client: Generated Runloop client
         :type client: Runloop
-        :param name: The globally unique name of the secret
+        :param name: The literal account-scoped name of the secret
         :type name: str
-        :param id: The secret ID (optional, may not be known until getInfo is called)
+        :param id: An optional ID captured from the response that constructed this wrapper
         :type id: str | None
         """
         self._client = client
@@ -53,7 +55,7 @@ def __repr__(self) -> str:
     def id(self) -> str | None:
         """Return the secret ID.
 
-        :return: Secret ID, or None if not yet fetched from API
+        :return: Captured response ID, or None. Fetching metadata does not refresh this property.
         :rtype: str | None
         """
         return self._id
@@ -62,7 +64,7 @@ def id(self) -> str | None:
     def name(self) -> str:
         """Return the secret name.
 
-        :return: Globally unique secret name
+        :return: Literal account-scoped secret name
         :rtype: str
         """
         return self._name
@@ -93,7 +95,9 @@ def update(
         value: str,
         **options: Unpack[LongRequestOptions],
     ) -> SecretView:
-        """Update this secret's value.
+        """Update the greatest-ID row matching this name at lookup.
+
+        This wrapper remains name-bound and its captured ID is unchanged.
 
         Example:
             >>> updated = secret.update("new-secret-value")
@@ -115,7 +119,9 @@ def delete(
         self,
         **options: Unpack[LongRequestOptions],
     ) -> SecretView:
-        """Delete this secret. This action is irreversible.
+        """Delete every selected row matching this name, nonatomically.
+
+        A concurrent create can survive. This action is irreversible.
 
         Example:
             >>> secret.delete()

src/runloop_api_client/sdk/secret_by_id.py

@@ -0,0 +1,44 @@
+"""Exact-ID Secret operations, separate from legacy name selectors."""
+
+from __future__ import annotations
+
+from typing_extensions import Unpack, override
+
+from ._types import BaseRequestOptions, LongRequestOptions
+from .._client import Runloop
+from ..types.secret_view import SecretView
+
+
+class SecretById:
+    """An exact Secret row, obtained with ``sdk.secret.from_id(id)``.
+
+    Construction makes no request. The ID never changes, but another writer can
+    change the value. Requests retain the generated client's retry policy and are
+    not exactly-once operations. Use ``get_info()`` for the name and metadata;
+    values are never returned.
+    """
+
+    def __init__(self, client: Runloop, id: str) -> None:
+        self._client = client
+        self._id = id
+
+    @override
+    def __repr__(self) -> str:
+        return f"<SecretById id={self._id!r}>"
+
+    @property
+    def id(self) -> str:
+        """The exact row ID, not a name or an immutable value-version identifier."""
+        return self._id
+
+    def get_info(self, **options: Unpack[BaseRequestOptions]) -> SecretView:
+        """Retrieve this row's metadata. Missing IDs never fall back to names."""
+        return self._client.secrets.retrieve_by_id(self._id, **options)
+
+    def update(self, value: str, **options: Unpack[LongRequestOptions]) -> SecretView:
+        """Replace this row's value, without changing running devbox environments or issued tokens."""
+        return self._client.secrets.update_by_id(self._id, value=value, **options)
+
+    def delete(self, **options: Unpack[LongRequestOptions]) -> SecretView:
+        """Delete only this row. Name readers may then see an older same-name row."""
+        return self._client.secrets.delete_by_id(self._id, **options)

src/runloop_api_client/sdk/sync.py

@@ -43,6 +43,7 @@
 from .blueprint import Blueprint
 from .mcp_config import McpConfig
 from .._constants import DEFAULT_API_POOL_SHARDS, DEFAULT_TRANSFER_POOL_SHARDS, DEFAULT_BACKGROUND_POOL_SHARDS
+from .secret_by_id import SecretById
 from .gateway_config import GatewayConfig
 from .network_policy import NetworkPolicy
 from .storage_object import StorageObject
@@ -1031,7 +1032,7 @@ def create(self, name: str, value: str, **options: Unpack[LongRequestOptions]) -
             ... )
             >>> print(f"Created secret: {secret.name}")
 
-        :param name: Globally unique secret name (must be a valid env var name)
+        :param name: Account-scoped secret name (must be a valid env var name)
         :type name: str
         :param value: Secret value to store (encrypted at rest)
         :type value: str
@@ -1052,13 +1053,17 @@ def from_name(self, name: str) -> Secret:
             >>> info = secret.get_info()
             >>> print(f"Secret ID: {info.id}")
 
-        :param name: The globally unique name of the secret
+        :param name: The literal account-scoped name of the secret
         :type name: str
         :return: A Secret instance (no API call made)
         :rtype: Secret
         """
         return Secret(self._client, name)
 
+    def from_id(self, id: str) -> SecretById:
+        """Get a lazy exact-ID handle; its operations never fall back to a name."""
+        return SecretById(self._client, id)
+
     def update(
         self,
         secret: "Secret | str",