databricks-mason 0.1.1.dev0__tar.gz → 0.1.2.dev0__tar.gz

{databricks_mason-0.1.1.dev0 → databricks_mason-0.1.2.dev0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.5
 Name: databricks-mason
-Version: 0.1.1.dev0
+Version: 0.1.2.dev0
 Summary: Databricks integration for Mason
 Author-email: Databricks <agent-feedback@databricks.com>
 License-File: NOTICE
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1
 Requires-Dist: databricks-sdk>=0.49
+Requires-Dist: psycopg[binary]>=3.1
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.7
 Requires-Dist: tomli>=2.0
@@ -21,6 +22,14 @@ Requires-Dist: langgraph>=1.1.0; extra == 'runtime'
 Requires-Dist: mlflow>=3.10.1; extra == 'runtime'
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0; extra == 'runtime'
 Requires-Dist: uuid-utils>=0.10.0; extra == 'runtime'
+Provides-Extra: runtime-openai
+Requires-Dist: databricks-agents>=1.9.3; extra == 'runtime-openai'
+Requires-Dist: databricks-openai>=0.13.0; extra == 'runtime-openai'
+Requires-Dist: fastapi>=0.129.0; extra == 'runtime-openai'
+Requires-Dist: mlflow>=3.10.1; extra == 'runtime-openai'
+Requires-Dist: openai-agents>=0.4.1; extra == 'runtime-openai'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0; extra == 'runtime-openai'
+Requires-Dist: uuid-utils>=0.10.0; extra == 'runtime-openai'
 Provides-Extra: tracing
 Requires-Dist: mlflow[databricks]>=3.9.0; extra == 'tracing'
 Description-Content-Type: text/markdown
@@ -102,8 +111,11 @@ accessors (`store.name`) while remaining plain dicts underneath — so `store["n
 mason [-p <profile>] [-o text|json]
   login        [--profile P]
   logout
-  init         [--framework openai|langgraph] [--enable-chat-app]
+  init         [--framework openai|langgraph] [--disable-chat-app]
                [--profile P] [--repo URL] [--ref REF] [directory]
+  dev          [--source PATH] [--prepare-environment] [--app-port PORT]
+               [--memory/-m N] [--session/-s N]
+               [--with-traces C.S] [--no-create-stores]
   memory
     stores     create | list | get | update | delete
     entries    create | get | list | search | update | delete
@@ -115,19 +127,39 @@ mason [-p <profile>] [-o text|json]
     list | get | instrument
   mcp
     list             [--schema CATALOG.SCHEMA]
-  init          [--framework openai|langgraph] [--profile P] [DIRECTORY]
   tools
     add sandbox      --scope SCOPE [--scope SCOPE ...] [--source PATH]
     add mcp          SERVICE [--name NAME] [--source PATH]
     add uc-function  FUNCTION [--name NAME] [--source PATH]
     add python       NAME [--source PATH]
     list             [--source PATH]
-  deploy       <name> --source PATH [--with-memory-store N]
-               [--with-session-store N] [--actor-id ID]
-               [--with-traces C.S] [--create-stores]
+  deploy       <name> --source PATH [--memory/-m N]
+               [--session/-s N] [--actor-id ID]
+               [--with-traces C.S] [--no-create-stores]
   deployments  list | get | logs | start | stop | delete
 ```
 
+## Command help
+
+Use the conventional help flag at any command level. Every command's help includes runnable
+examples:
+
+```sh
+mason --help
+mason deploy --help
+mason sessions items append --help
+```
+
+For the shortest path from a blank directory to a running and deployed agent:
+
+```sh
+mason login --profile my-workspace
+mason init my-agent
+cd my-agent
+mason dev
+mason deploy my-agent
+```
+
 ## Agent tools
 
 `mason init` writes portable tool intent to `agent.toml` and template provenance to
@@ -168,49 +200,39 @@ arguments controlled by the model.
 
 ## Initialize the chat app demo
 
-The chat app is a LangGraph-specific init overlay, not a command that mutates an existing project:
+The chat app is a LangGraph-specific init overlay, not a command that mutates an existing project.
+It is included by default for `--framework langgraph`; pass `--disable-chat-app` to scaffold the
+API-only backend instead.
 
 ```sh
-mason init --framework langgraph --enable-chat-app \
+mason init --framework langgraph \
   --profile <profile> \
   ./my-agent
 cd ./my-agent
 uv run start-server
 ```
 
-`--enable-chat-app` always includes synchronous, SSE streaming, background polling, Session Store,
-Memory Store, HITL resume, Start App, Stop App, heartbeat, and recovery UI. There are no separate
-stop/crash flags. The base agent owns `agent/mason/durability.py`, `agent/mason/recovery.py`, and
-`agent/mason/long_running.py`; the framework-specific overlay only adds `ui/`, `runtime/ui.py`, the
-UI-enabled `runtime/main.py`, and UI tests.
+The chat app includes synchronous, SSE streaming, background polling, Session Store, Memory Store,
+and HITL resume UI. The framework-specific overlay adds `ui/`, `runtime/ui.py`, the UI-enabled
+`runtime/main.py`, and UI tests.
 
 For the full deployed demo, connect both managed stores:
 
 ```sh
 mason --profile <profile> deploy mason-agent-demo --source . \
-  --with-session-store mason-demo-sessions \
-  --with-memory-store mason-demo-memory \
-  --actor-id alice \
-  --create-stores
+  --session mason-demo-sessions \
+  --memory mason-demo-memory \
+  --actor-id alice
 ```
 
+(Missing stores are created automatically; pass `--no-create-stores` to require they already exist.)
+
 The Databricks Apps `__Host-databricks-app-router` cookie is both the sticky routing key and the
 application session id. The browser sends it automatically; API clients must reuse it as a cookie.
 Request bodies never carry `session_id`. A localhost-only `mason-local-session` cookie provides the
 same behavior outside Databricks Apps. TODO: move to `X-Routing-Key` when Apps supports it.
 
 The generated `README.md` documents every request the client makes: config discovery, sync and SSE
-invocations, background submission and polling, session transcript loading, HITL resume, memory
-entry operations, and stop/start recovery. Capability colors are automatic from `/api/demo/config`;
-only the sync/streaming/background transport selector is manual.
-
-Start App runs `tool_step_1` through `tool_step_4` in a checkpointed sequence. Each completed output
-is committed before the next node. Stop App schedules `os._exit(86)`; Databricks Apps restarts the
-process, the browser waits for a new instance and a stale heartbeat, and then starts a new attempt
-with the same routing cookie. Completed tools are restored and skipped; an interrupted tool whose
-output was not committed can run again.
-
-The ownership log is intentionally demo-grade: Session Store records append-only attempts and
-heartbeats, but the claim is last-writer-wins rather than atomic (`atomic_claim: false`). Production
-durability also needs transactional ownership, server-side stale scanning, idempotent side effects,
-and durable event replay.
+invocations, background submission and polling, session transcript loading, HITL resume, and memory
+entry operations. Capability colors are automatic from `/api/demo/config`; only the
+sync/streaming/background transport selector is manual.

{databricks_mason-0.1.1.dev0 → databricks_mason-0.1.2.dev0}/README.md

@@ -75,8 +75,11 @@ accessors (`store.name`) while remaining plain dicts underneath — so `store["n
 mason [-p <profile>] [-o text|json]
   login        [--profile P]
   logout
-  init         [--framework openai|langgraph] [--enable-chat-app]
+  init         [--framework openai|langgraph] [--disable-chat-app]
                [--profile P] [--repo URL] [--ref REF] [directory]
+  dev          [--source PATH] [--prepare-environment] [--app-port PORT]
+               [--memory/-m N] [--session/-s N]
+               [--with-traces C.S] [--no-create-stores]
   memory
     stores     create | list | get | update | delete
     entries    create | get | list | search | update | delete
@@ -88,19 +91,39 @@ mason [-p <profile>] [-o text|json]
     list | get | instrument
   mcp
     list             [--schema CATALOG.SCHEMA]
-  init          [--framework openai|langgraph] [--profile P] [DIRECTORY]
   tools
     add sandbox      --scope SCOPE [--scope SCOPE ...] [--source PATH]
     add mcp          SERVICE [--name NAME] [--source PATH]
     add uc-function  FUNCTION [--name NAME] [--source PATH]
     add python       NAME [--source PATH]
     list             [--source PATH]
-  deploy       <name> --source PATH [--with-memory-store N]
-               [--with-session-store N] [--actor-id ID]
-               [--with-traces C.S] [--create-stores]
+  deploy       <name> --source PATH [--memory/-m N]
+               [--session/-s N] [--actor-id ID]
+               [--with-traces C.S] [--no-create-stores]
   deployments  list | get | logs | start | stop | delete
 ```
 
+## Command help
+
+Use the conventional help flag at any command level. Every command's help includes runnable
+examples:
+
+```sh
+mason --help
+mason deploy --help
+mason sessions items append --help
+```
+
+For the shortest path from a blank directory to a running and deployed agent:
+
+```sh
+mason login --profile my-workspace
+mason init my-agent
+cd my-agent
+mason dev
+mason deploy my-agent
+```
+
 ## Agent tools
 
 `mason init` writes portable tool intent to `agent.toml` and template provenance to
@@ -141,49 +164,39 @@ arguments controlled by the model.
 
 ## Initialize the chat app demo
 
-The chat app is a LangGraph-specific init overlay, not a command that mutates an existing project:
+The chat app is a LangGraph-specific init overlay, not a command that mutates an existing project.
+It is included by default for `--framework langgraph`; pass `--disable-chat-app` to scaffold the
+API-only backend instead.
 
 ```sh
-mason init --framework langgraph --enable-chat-app \
+mason init --framework langgraph \
   --profile <profile> \
   ./my-agent
 cd ./my-agent
 uv run start-server
 ```
 
-`--enable-chat-app` always includes synchronous, SSE streaming, background polling, Session Store,
-Memory Store, HITL resume, Start App, Stop App, heartbeat, and recovery UI. There are no separate
-stop/crash flags. The base agent owns `agent/mason/durability.py`, `agent/mason/recovery.py`, and
-`agent/mason/long_running.py`; the framework-specific overlay only adds `ui/`, `runtime/ui.py`, the
-UI-enabled `runtime/main.py`, and UI tests.
+The chat app includes synchronous, SSE streaming, background polling, Session Store, Memory Store,
+and HITL resume UI. The framework-specific overlay adds `ui/`, `runtime/ui.py`, the UI-enabled
+`runtime/main.py`, and UI tests.
 
 For the full deployed demo, connect both managed stores:
 
 ```sh
 mason --profile <profile> deploy mason-agent-demo --source . \
-  --with-session-store mason-demo-sessions \
-  --with-memory-store mason-demo-memory \
-  --actor-id alice \
-  --create-stores
+  --session mason-demo-sessions \
+  --memory mason-demo-memory \
+  --actor-id alice
 ```
 
+(Missing stores are created automatically; pass `--no-create-stores` to require they already exist.)
+
 The Databricks Apps `__Host-databricks-app-router` cookie is both the sticky routing key and the
 application session id. The browser sends it automatically; API clients must reuse it as a cookie.
 Request bodies never carry `session_id`. A localhost-only `mason-local-session` cookie provides the
 same behavior outside Databricks Apps. TODO: move to `X-Routing-Key` when Apps supports it.
 
 The generated `README.md` documents every request the client makes: config discovery, sync and SSE
-invocations, background submission and polling, session transcript loading, HITL resume, memory
-entry operations, and stop/start recovery. Capability colors are automatic from `/api/demo/config`;
-only the sync/streaming/background transport selector is manual.
-
-Start App runs `tool_step_1` through `tool_step_4` in a checkpointed sequence. Each completed output
-is committed before the next node. Stop App schedules `os._exit(86)`; Databricks Apps restarts the
-process, the browser waits for a new instance and a stale heartbeat, and then starts a new attempt
-with the same routing cookie. Completed tools are restored and skipped; an interrupted tool whose
-output was not committed can run again.
-
-The ownership log is intentionally demo-grade: Session Store records append-only attempts and
-heartbeats, but the claim is last-writer-wins rather than atomic (`atomic_claim: false`). Production
-durability also needs transactional ownership, server-side stale scanning, idempotent side effects,
-and durable event replay.
+invocations, background submission and polling, session transcript loading, HITL resume, and memory
+entry operations. Capability colors are automatic from `/api/demo/config`; only the
+sync/streaming/background transport selector is manual.

{databricks_mason-0.1.1.dev0 → databricks_mason-0.1.2.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "databricks-mason"
-version = "0.1.1.dev0"
+version = "0.1.2.dev0"
 description = "Databricks integration for Mason"
 authors = [
     { name="Databricks", email="agent-feedback@databricks.com" },
@@ -10,6 +10,7 @@ requires-python = ">=3.10"
 dependencies = [
     "click>=8.1",
     "databricks-sdk>=0.49",
+    "psycopg[binary]>=3.1",
     "PyYAML>=6.0",
     "rich>=13.7",
     "tomli>=2.0",
@@ -20,9 +21,11 @@ dependencies = [
 tracing = [
     "mlflow[databricks]>=3.9.0",
 ]
-# The agent-side runtime helpers (databricks_mason.runtime) that a deployed agent imports. Kept as
-# an extra so a plain `pip install databricks-mason` (the CLI) stays light; the template depends on
-# `databricks-mason[runtime]`.
+# The agent-side runtime helpers a deployed agent imports. Kept as extras so a plain
+# `pip install databricks-mason` (the CLI) stays light; each template depends on the extra for its
+# framework. `runtime` = the LangGraph adapter (databricks_mason.langgraph); `runtime-openai` = the
+# OpenAI Agents SDK adapter (databricks_mason.openai). Both carry the shared framework-neutral stack
+# (databricks_mason.runtime); the framework SDKs differ, so an agent installs only the one it uses.
 runtime = [
     "databricks-langchain>=0.17.0",
     "langgraph>=1.1.0",
@@ -34,6 +37,15 @@ runtime = [
     "opentelemetry-exporter-otlp-proto-grpc>=1.25.0",
     "databricks-agents>=1.9.3",
 ]
+runtime-openai = [
+    "openai-agents>=0.4.1",
+    "databricks-openai>=0.13.0",
+    "fastapi>=0.129.0",
+    "mlflow>=3.10.1",
+    "uuid-utils>=0.10.0",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.25.0",
+    "databricks-agents>=1.9.3",
+]
 
 [project.scripts]
 mason = "databricks_mason.cli:main"

{databricks_mason-0.1.1.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/agent_project.py

@@ -291,7 +291,8 @@ class AgentProject:
         except FileNotFoundError as exc:
             raise AgentCliError(
                 f"Could not find agent.toml in {project_root}.",
-                hint="Run `mason init` or use a legacy compatibility command.",
+                hint="This command needs a Mason project. Run `mason init` to create one, "
+                "or point at an existing project with --source <dir>.",
             ) from exc
         except (OSError, ParseError) as exc:
             raise AgentCliError(f"Could not read agent manifest at {path}: {exc}.") from exc
@@ -334,7 +335,17 @@ class AgentProject:
                 continue
             if existing == spec:
                 return False
-            raise AgentCliError(f"Tool id {spec.id!r} already exists with different configuration.")
+
+            def _summary(s: ToolSpec) -> str:
+                src = s.source
+                return src.service or src.function or src.entrypoint or src.kind
+
+            raise AgentCliError(
+                f"Tool id {spec.id!r} already exists with a different configuration "
+                f"(existing: {_summary(existing)}; requested: {_summary(spec)}).",
+                hint="Use --name to add it under a different id, or remove the existing "
+                "tool from agent.toml first.",
+            )
         raw_tools = self._document.get("tools")
         if raw_tools is None:
             raw_tools = tomlkit.aot()

{databricks_mason-0.1.1.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/cli.py

@@ -10,10 +10,12 @@ from typing import Optional
 
 import click
 
+from databricks_mason import errors
 from databricks_mason.auth import load_default_profile, login, logout
 from databricks_mason.client import MasonClient
 from databricks_mason.deploy import deploy, deployments
 from databricks_mason.dev import dev
+from databricks_mason.help import configure_help
 from databricks_mason.init import init
 from databricks_mason.mcp import mcp
 from databricks_mason.memory import memory
@@ -56,6 +58,8 @@ def mason(ctx: click.Context, profile: Optional[str], output: str) -> None:
     .databrickscfg profile (pass --profile / -p, run `mason login` to save a default,
     or rely on the SDK's default resolution).
     """
+    # Let errors render to match the selected output mode (JSON errors for -o json).
+    errors.set_output_mode(output)
     ctx.obj = CliContext(profile=profile or load_default_profile(), output=output)
 
 
@@ -70,6 +74,7 @@ mason.add_command(tracing)
 mason.add_command(deploy)
 mason.add_command(deployments)
 mason.add_command(tools)
+configure_help(mason)
 
 
 def main() -> None:

{databricks_mason-0.1.1.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/client.py

@@ -36,15 +36,39 @@ def _as(cls: type, resp: Any) -> Any:
 
 
 def memory_store_path(name: str) -> str:
-    """Normalize a store id or name into the `memory-stores/{id}` resource segment."""
-    name = name.strip().strip("/")
-    return name if name.startswith("memory-stores/") else f"memory-stores/{name}"
+    """Normalize a store id or name into the `memory-stores/{id}` resource segment.
+
+    Validates client-side so an empty or wrong-typed argument raises a clear error
+    instead of building a URL like `memory-stores/` and leaking a raw ENDPOINT_NOT_FOUND.
+    """
+    raw = (name or "").strip()
+    if raw.startswith("memory-stores/"):
+        raw = raw[len("memory-stores/") :]
+    raw = raw.strip().strip("/")
+    if not raw:
+        raise AgentCliError("A memory store id or resource name is required.")
+    if "/" in raw:
+        raise AgentCliError(f"Invalid memory store id or resource name: {name!r}")
+    return f"memory-stores/{raw}"
+
+
+def session_store_path(name: str) -> str:
+    """Normalize/validate a session store name into the `session-stores/{name}` segment."""
+    raw = (name or "").strip()
+    if raw.startswith("session-stores/"):
+        raw = raw[len("session-stores/") :]
+    raw = raw.strip().strip("/")
+    if not raw:
+        raise AgentCliError("A session store name is required.")
+    return f"session-stores/{raw}"
 
 
 def memory_entry_path(store: str, entry: str) -> str:
-    entry = entry.strip().strip("/")
+    entry = (entry or "").strip().strip("/")
     if entry.startswith("memory-stores/"):
         return entry
+    if not entry:
+        raise AgentCliError("A memory entry id or resource name is required.")
     return f"{memory_store_path(store)}/entries/{entry}"
 
 
@@ -162,6 +186,8 @@ class MasonClient:
         self, name: str, display_name: Optional[str] = None, description: Optional[str] = None
     ) -> models.MemoryStore:
         body = _query(display_name=display_name, description=description)
+        if not body:
+            raise AgentCliError("No fields to update. Provide a display name and/or description.")
         mask = ",".join(body.keys())
         return _as(
             models.MemoryStore,
@@ -247,6 +273,8 @@ class MasonClient:
         description: Optional[str] = None,
     ) -> models.MemoryEntry:
         body = _query(content=content, description=description)
+        if not body:
+            raise AgentCliError("No fields to update. Provide content and/or a description.")
         return _as(
             models.MemoryEntry,
             self._do("PATCH", f"{_BASE}/{memory_entry_path(store, entry)}", body=body),
@@ -269,7 +297,7 @@ class MasonClient:
         )
 
     def get_session_store(self, name: str) -> models.SessionStore:
-        return _as(models.SessionStore, self._do("GET", f"{_BASE}/session-stores/{name}"))
+        return _as(models.SessionStore, self._do("GET", f"{_BASE}/{session_store_path(name)}"))
 
     def list_session_stores(
         self, page_size: Optional[int] = None, page_token: Optional[str] = None
@@ -287,16 +315,21 @@ class MasonClient:
         self, name: str, description: Optional[str] = None, metadata: Optional[dict] = None
     ) -> models.SessionStore:
         body = _query(description=description, metadata=metadata)
+        if not body:
+            raise AgentCliError("No fields to update. Provide a description and/or metadata.")
         mask = ",".join(body.keys())
         return _as(
             models.SessionStore,
             self._do(
-                "PATCH", f"{_BASE}/session-stores/{name}", query=_query(update_mask=mask), body=body
+                "PATCH",
+                f"{_BASE}/{session_store_path(name)}",
+                query=_query(update_mask=mask),
+                body=body,
             ),
         )
 
     def delete_session_store(self, name: str) -> dict:
-        return self._do("DELETE", f"{_BASE}/session-stores/{name}")
+        return self._do("DELETE", f"{_BASE}/{session_store_path(name)}")
 
     # --- sessions ------------------------------------------------------------
 

{databricks_mason-0.1.1.dev0 → databricks_mason-0.1.2.dev0}/src/databricks_mason/deploy.py

@@ -67,11 +67,35 @@ def _app_compute_state(name: str, profile: Optional[str]) -> Optional[str]:
         return None
 
 
+def _validate_deployment_name(name: str) -> str:
+    """Reject an empty or unsafe deployment name before it reaches a URL / workspace path."""
+    if (
+        not (name or "").strip()
+        or name != name.strip()
+        or any(token in name for token in ("/", "\\", ".."))
+        or any(character.isspace() for character in name)
+    ):
+        raise AgentCliError(
+            f"Invalid deployment name {name!r}.",
+            hint="Use a non-empty name of letters, digits, and hyphens "
+            "(no slashes, spaces, or '..').",
+        )
+    return name
+
+
+def _confirm_destroy(target: str, *, assume_yes: bool) -> None:
+    """Prompt before a destructive deployment op; --yes/-y skips it (for scripts)."""
+    if assume_yes:
+        return
+    if not click.confirm(f"{target}? This cannot be undone.", default=False):
+        raise click.Abort()
+
+
 def _wait_for_running(name: str, profile: Optional[str], timeout_s: int = 300) -> None:
-    """Block until a just-created app's compute is RUNNING (or raise on timeout).
+    """Block until a just-created app's compute is ACTIVE (or raise on timeout).
 
-    `apps create` returns before compute is provisioned, but `apps deploy` requires RUNNING — so a
-    first deploy races without this wait.
+    `apps create` returns before compute is provisioned, but `apps deploy` requires the app to be
+    ACTIVE — so a first deploy races without this wait.
     """
     deadline = time.monotonic() + timeout_s
     while time.monotonic() < deadline:
@@ -186,9 +210,10 @@ def resolve_store_env(
     """Resolve store/trace references to the AGENT_*/MLFLOW_* env vars that wire them in.
 
     Shared by `mason deploy` and `mason dev` so both wire an agent's stores into app.yaml the same
-    way. With `create_stores`, missing stores are created (idempotent); otherwise they must already
-    exist. The memory store resolves to its bare id (the runtime re-adds the `memory-stores/` prefix
-    when building the entries URL); the session store and trace destination are used verbatim.
+    way. With `create_stores` (the default), missing stores are created (idempotent); when it is off
+    they must already exist. The memory store resolves to its bare id (the runtime re-adds the
+    `memory-stores/` prefix when building the entries URL); the session store and trace destination
+    are used verbatim.
     """
     env: dict[str, str] = {}
     if memory_store:
@@ -200,13 +225,24 @@ def resolve_store_env(
             store = _resolve_memory_store(client, memory_store)
             if store is None:
                 raise AgentCliError(
-                    f"Memory store '{memory_store}' does not exist (create it with --create-stores)."
+                    f"Memory store '{memory_store}' does not exist "
+                    "(drop --no-create-stores to create it)."
                 )
         store_name = field(store, "name") or memory_store
         env[_MEMORY_ENV] = store_name.split("/", 1)[-1]
     if session_store:
         if create_stores:
             _ensure_session_store(client, session_store)
+        else:
+            # Validate existence up front so a typo fails at deploy time, not at runtime.
+            try:
+                client.get_session_store(session_store)
+            except AgentCliError as exc:
+                raise AgentCliError(
+                    f"Session store '{session_store}' does not exist "
+                    "(drop --no-create-stores to create it).",
+                    error_code=exc.error_code,
+                ) from exc
         env[_SESSION_ENV] = session_store
     if traces_destination:
         env[TRACES_DEST_ENV] = traces_destination
@@ -266,13 +302,15 @@ def _grant_store_access(
     "current directory.",
 )
 @click.option(
-    "--with-memory-store",
+    "--memory",
+    "-m",
     "memory_store",
     default=None,
     help="Memory store display name to wire in via AGENT_MEMORY_STORE.",
 )
 @click.option(
-    "--with-session-store",
+    "--session",
+    "-s",
     "session_store",
     default=None,
     help="Session store name to wire in via AGENT_SESSION_STORE.",
@@ -296,9 +334,10 @@ def _grant_store_access(
     help="MLflow experiment path to wire in via MLFLOW_EXPERIMENT_NAME.",
 )
 @click.option(
-    "--create-stores",
+    "--no-create-stores",
     is_flag=True,
-    help="Create the referenced stores if they don't exist (idempotent).",
+    help="Require referenced stores to already exist. By default missing stores are created "
+    "(idempotent).",
 )
 @click.option(
     "--pip-index-url",
@@ -323,11 +362,12 @@ def deploy(
     actor_id,
     traces_destination,
     traces_experiment,
-    create_stores,
+    no_create_stores,
     pip_index_url,
     workspace_path,
 ) -> None:
     """Deploy an agent: provision its stores, wire them in, and roll out the deployment."""
+    _validate_deployment_name(name)
     source_dir = pathlib.Path(source)
     client = obj.client()
 
@@ -339,7 +379,7 @@ def deploy(
         session_store=session_store,
         traces_destination=traces_destination,
         traces_experiment=traces_experiment,
-        create_stores=create_stores,
+        create_stores=not no_create_stores,
     )
     provisioned: dict[str, Any] = {}
     if _MEMORY_ENV in env_updates:
@@ -411,7 +451,7 @@ def deploy(
         steps.insert(
             0,
             "The app's service principal needs read/write on its store tables; that grant couldn't "
-            "be applied automatically (it requires store ownership and psql). "
+            "be applied automatically (it requires store ownership). "
             f"Cause: {grant_error}",
         )
     if grants_stores and grant_error is None:
@@ -470,6 +510,7 @@ def deployments_list(obj) -> None:
 @click.pass_obj
 def deployments_get(obj, name) -> None:
     """Get an agent deployment's details."""
+    _validate_deployment_name(name)
     result = _databricks(["apps", "get", name, "-o", "json"], obj.profile, capture=True)
     data = json.loads(result.stdout or "{}")
     if obj.output == "json":
@@ -495,6 +536,7 @@ def deployments_get(obj, name) -> None:
 @click.pass_obj
 def deployments_logs(obj, name) -> None:
     """Stream a deployment's logs."""
+    _validate_deployment_name(name)
     _databricks(["apps", "logs", name], obj.profile)
 
 
@@ -503,6 +545,7 @@ def deployments_logs(obj, name) -> None:
 @click.pass_obj
 def deployments_start(obj, name) -> None:
     """Start a deployment."""
+    _validate_deployment_name(name)
     _databricks(["apps", "start", name], obj.profile)
     if obj.output == "json":
         render.emit_json({"started": name})
@@ -512,9 +555,12 @@ def deployments_start(obj, name) -> None:
 
 @deployments.command("stop")
 @click.argument("name")
+@click.option("--yes", "-y", is_flag=True, help="Skip the confirmation prompt.")
 @click.pass_obj
-def deployments_stop(obj, name) -> None:
+def deployments_stop(obj, name, yes) -> None:
     """Stop a deployment."""
+    _validate_deployment_name(name)
+    _confirm_destroy(f"Stop deployment '{name}'", assume_yes=yes)
     _databricks(["apps", "stop", name], obj.profile)
     if obj.output == "json":
         render.emit_json({"stopped": name})
@@ -524,9 +570,12 @@ def deployments_stop(obj, name) -> None:
 
 @deployments.command("delete")
 @click.argument("name")
+@click.option("--yes", "-y", is_flag=True, help="Skip the confirmation prompt.")
 @click.pass_obj
-def deployments_delete(obj, name) -> None:
+def deployments_delete(obj, name, yes) -> None:
     """Delete a deployment."""
+    _validate_deployment_name(name)
+    _confirm_destroy(f"Delete deployment '{name}'", assume_yes=yes)
     _databricks(["apps", "delete", name], obj.profile)
     if obj.output == "json":
         render.emit_json({"deleted": name})