keystone-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{keystone_cli-0.4.0 → keystone_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keystone-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Keystone CLI — build, test, deploy and operate pro-code agents, and manage knowledge bases, prompts, tool credentials and skills on the Keystone platform.
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -8,7 +8,7 @@ Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: keystone-agent-sdk<0.14,>=0.13.20
+Requires-Dist: keystone-agent-sdk<0.14,>=0.13.27
 Requires-Dist: keystone-request-context<0.4,>=0.3
 Requires-Dist: typer<1,>=0.12
 Requires-Dist: httpx<1,>=0.27
@@ -72,6 +72,72 @@ keystone --version
 
 To see the fields of `agent.yaml`, run `keystone agent manifest`. Every command has `--help`.
 
+## CI with a service account
+
+Use a platform service account in CI. The CLI sends its API key as `Authorization: Bearer <key>`.
+A CI job does not run `keystone login`.
+
+Before you start, an admin gives the service account three permissions on its workspace, one time:
+
+| Permission | Resource | Why |
+| --- | --- | --- |
+| `agent:register` | the workspace of the service account | Register a new agent |
+| `agent-vb:version:create` | the workspace of the service account | Upload a bundle |
+| `agent:read` | the workspace of the service account | Find an agent by name (`delete`, `versions`, `status` and others) |
+
+In the portal, open **Settings → Service Accounts**, open the access dialog of the account, and
+select **This workspace** as the resource.
+
+`deploy --publish`, `invoke`, `runs` and `threads` work without `agent:read` on the workspace. A
+service account can not read agent logs: `keystone agent logs` needs `trace:read`, which only a user
+can hold.
+
+When the service account deploys a new agent, it gets all other permissions on that agent
+automatically: read, invoke, and version create, deploy, publish and retire. To invoke an agent that
+another user created, an admin must give `agent:invoke` on that agent.
+
+Set these variables in the CI job:
+
+| Variable | Value |
+| --- | --- |
+| `KEYSTONE_API_KEY` | The API key of the service account. Keep it in a masked CI secret. |
+| `KEYSTONE_WORKSPACE_ID` | The UUID of the target workspace. |
+| `KEYSTONE_API_BASE` | Optional. The platform API URL. The default is the URL of your CLI package. |
+| `KEYSTONE_AGENT_API_BASE` | Optional. The agent API URL for `invoke`, `runs` and `threads`. |
+
+Then do these steps:
+
+1. Make sure that the CLI uses the service account.
+
+   ```bash
+   export KEYSTONE_API_KEY=<sa-api-key>
+   export KEYSTONE_WORKSPACE_ID=<workspace-uuid>
+   keystone whoami
+   ```
+
+2. Deploy the agent.
+
+   ```bash
+   keystone agent deploy my-agent --publish --wait
+   ```
+
+3. Call the agent.
+
+   ```bash
+   keystone agent invoke my-agent --input '{"prompt": "ping"}'
+   ```
+
+Do not put the API key on the command line. The shell history and the CI log can show it.
+
+These rules apply when `KEYSTONE_API_KEY` is set:
+
+- The key has priority over `KEYSTONE_TOKEN` and over a saved login.
+- The CLI does not save the key to a file, and it does not show the key.
+  `keystone whoami` shows only the key ID.
+- The CLI does not select a workspace for you. `--workspace-id` has priority over `KEYSTONE_WORKSPACE_ID`.
+  `KEYSTONE_WORKSPACE_ID` has priority over the saved workspace.
+- `keystone workspace list` and `keystone workspace use` do not operate with a key.
+
 ## Commands
 
 | Command | What it does |

keystone_cli-0.5.0/README.md

@@ -0,0 +1,140 @@
+# keystone-cli
+
+`keystone` is the command-line tool of the Keystone platform. Use it to build, test, deploy and operate
+pro-code agents. You can also manage knowledge bases, prompts, tool credentials and skills with it.
+
+The CLI includes the Keystone agent SDK (`keystone-agent-sdk`). An agent project that you create with
+the CLI uses that SDK.
+
+## Install
+
+The CLI needs Python 3.12 or later.
+
+```bash
+pip install keystone-cli
+keystone --version
+```
+
+## Get started
+
+1. Log in. The command opens your browser and keeps your session for later commands.
+
+   ```bash
+   keystone login
+   ```
+
+2. Select the workspace that your commands use.
+
+   ```bash
+   keystone workspace use <name>
+   ```
+
+3. Create an agent project from a template, then check it.
+
+   ```bash
+   keystone agent init my-agent --template llm
+   keystone agent validate my-agent
+   ```
+
+4. Run the unit tests of the agent on your computer.
+
+   ```bash
+   keystone agent test my-agent
+   ```
+
+5. Deploy the agent, make the new version Live, and call it.
+
+   ```bash
+   keystone agent deploy my-agent --publish --wait
+   keystone agent invoke my-agent --input '{"prompt": "hi"}'
+   ```
+
+To see the fields of `agent.yaml`, run `keystone agent manifest`. Every command has `--help`.
+
+## CI with a service account
+
+Use a platform service account in CI. The CLI sends its API key as `Authorization: Bearer <key>`.
+A CI job does not run `keystone login`.
+
+Before you start, an admin gives the service account three permissions on its workspace, one time:
+
+| Permission | Resource | Why |
+| --- | --- | --- |
+| `agent:register` | the workspace of the service account | Register a new agent |
+| `agent-vb:version:create` | the workspace of the service account | Upload a bundle |
+| `agent:read` | the workspace of the service account | Find an agent by name (`delete`, `versions`, `status` and others) |
+
+In the portal, open **Settings → Service Accounts**, open the access dialog of the account, and
+select **This workspace** as the resource.
+
+`deploy --publish`, `invoke`, `runs` and `threads` work without `agent:read` on the workspace. A
+service account can not read agent logs: `keystone agent logs` needs `trace:read`, which only a user
+can hold.
+
+When the service account deploys a new agent, it gets all other permissions on that agent
+automatically: read, invoke, and version create, deploy, publish and retire. To invoke an agent that
+another user created, an admin must give `agent:invoke` on that agent.
+
+Set these variables in the CI job:
+
+| Variable | Value |
+| --- | --- |
+| `KEYSTONE_API_KEY` | The API key of the service account. Keep it in a masked CI secret. |
+| `KEYSTONE_WORKSPACE_ID` | The UUID of the target workspace. |
+| `KEYSTONE_API_BASE` | Optional. The platform API URL. The default is the URL of your CLI package. |
+| `KEYSTONE_AGENT_API_BASE` | Optional. The agent API URL for `invoke`, `runs` and `threads`. |
+
+Then do these steps:
+
+1. Make sure that the CLI uses the service account.
+
+   ```bash
+   export KEYSTONE_API_KEY=<sa-api-key>
+   export KEYSTONE_WORKSPACE_ID=<workspace-uuid>
+   keystone whoami
+   ```
+
+2. Deploy the agent.
+
+   ```bash
+   keystone agent deploy my-agent --publish --wait
+   ```
+
+3. Call the agent.
+
+   ```bash
+   keystone agent invoke my-agent --input '{"prompt": "ping"}'
+   ```
+
+Do not put the API key on the command line. The shell history and the CI log can show it.
+
+These rules apply when `KEYSTONE_API_KEY` is set:
+
+- The key has priority over `KEYSTONE_TOKEN` and over a saved login.
+- The CLI does not save the key to a file, and it does not show the key.
+  `keystone whoami` shows only the key ID.
+- The CLI does not select a workspace for you. `--workspace-id` has priority over `KEYSTONE_WORKSPACE_ID`.
+  `KEYSTONE_WORKSPACE_ID` has priority over the saved workspace.
+- `keystone workspace list` and `keystone workspace use` do not operate with a key.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `keystone login`, `keystone whoami` | Log in, and show your user. |
+| `keystone workspace` | List and select the workspace that your commands use. |
+| `keystone agent` | Develop and test an agent locally (`init`, `validate`, `run`, `test`, `manifest`), ship it (`deploy`, `publish`, `status`, `retire`, `delete`), and operate and debug it (`invoke`, `logs`, `fetch`, `doctor`, `runs`, `hitl`, `traces`, `threads`). |
+| `keystone dev` | Run the graph of the agent locally again each time you save a file. |
+| `keystone kb` | Create and manage knowledge bases. |
+| `keystone prompt` | Manage the prompts of a workspace. |
+| `keystone tool-credentials` | Manage the credentials that the catalogue tools of your agents use. |
+| `keystone skills` | Install Claude Code skills for work on agents. |
+| `keystone version` | Show the CLI version, the target environment and the version of the bundled agent SDK. |
+
+## When a run fails
+
+Start with this command. It shows the steps, the errors and the logs of one run.
+
+```bash
+keystone agent runs debug <agent> <run_id>
+```

{keystone_cli-0.4.0 → keystone_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keystone-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Keystone CLI — build, test, deploy and operate pro-code agents, and manage knowledge bases, prompts, tool credentials and skills on the Keystone platform."
 # The PyPI project page shows this file (it had no description before 0.4.0). It is public: no internal
 # hosts, entity ids or workspace ids in it.
@@ -19,8 +19,11 @@ classifiers = [
 dependencies = [
     # Pinned to a compatible range: on an index (Artifact Registry) an unpinned name resolves to
     # ANY published version — the wheel's metadata is the only pin that travels with it.
-    # 0.4.0 needs 0.13.20: the file client of FDP-6964 and the A2UI chat blocks of FDP-7060.
-    "keystone-agent-sdk>=0.13.20,<0.14",
+    # 0.4.2 needs 0.13.22: `ui.generative_ui_tools` for the generative-ui template (FDP-6967).
+    # 0.4.3 needs 0.13.23: the file-tools template's nine tools, `attachments_as_content()` and
+    # `testing.FakeFileArtifact` (FDP-6967).
+    # 0.4.5 needs 0.13.26: `clients.kb_tools()` gives two KB tools, kb_search + kb_read_around (FDP-7133).
+    "keystone-agent-sdk>=0.13.27,<0.14",
     # Transitive (the SDK's building-block clients) + used directly by `run` to set a local
     # caller-identity ContextVar and to patch the clients for --offline. uv sources are NOT
     # transitive, so declare it directly (cf. services/llm-gateway).
@@ -52,6 +55,10 @@ keystone = "keystone_cli.__main__:app"
 [tool.uv.sources]
 keystone-agent-sdk = { path = "../agent_sdk" }
 keystone-request-context = { path = "../request_context" }
+# The SDK's dependency since 0.13.22 (FDP-6967); uv sources are NOT transitive.
+keystone-agui = { path = "../agui" }
+# The SDK's dependency since 0.13.23 (FDP-6967); uv sources are NOT transitive.
+keystone-agent-tools = { path = "../agent_tools" }
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -61,7 +68,7 @@ where = ["src"]
 keystone_cli = ["templates/*/*.tmpl", "templates/*/pkg/*.tmpl", "templates/*/tests/*.tmpl", "skills/*/SKILL.md"]
 
 [tool.ruff]
-target-version = "0.4.0"
+target-version = "0.5.0"
 line-length = 120
 
 [tool.ruff.lint]

{keystone_cli-0.4.0 → keystone_cli-0.5.0}/src/keystone_cli/__main__.py

@@ -41,8 +41,11 @@ Environment:
                            use one file per environment
   KEYSTONE_API_BASE        platform API URL (overrides the saved one)
   KEYSTONE_AGENT_API_BASE  agent API URL: invoke, runs, hitl, threads
+  KEYSTONE_API_KEY         service-account API key for CI; used as given,
+                           never saved, wins over every other credential
+  KEYSTONE_WORKSPACE_ID    workspace UUID (overrides the saved one;
+                           required with KEYSTONE_API_KEY)
   KEYSTONE_TOKEN           access token, used as given and never renewed
-                           (for CI)
   KEYSTONE_ISSUER          login: Keycloak realm URL
   KEYSTONE_CLIENT_ID       login: client id
   KEYSTONE_CLIENT_SECRET   login --client-credentials: client secret

keystone_cli-0.5.0/src/keystone_cli/auth/api_key.py

@@ -0,0 +1,48 @@
+"""Platform service-account API key from the environment — the CI credential (FDP-7177 G6).
+
+A platform SA API key (``ak_<env>_<id>.<secret>``, minted in the portal) goes on the wire as
+``Authorization: Bearer <key>``. Kong validates it and stamps ``X-Service-Account-ID``; the CLI never
+decodes it, renews it, or talks to Keycloak for it.
+
+Rules this module exists to keep in ONE place:
+
+* It is read ONLY from ``KEYSTONE_API_KEY`` — never a flag (argv shows up in ``ps``, shell history
+  and CI logs) and never the config file (a persisted key outlives the job that owns it).
+* It is never printed. :func:`describe` returns the key id (the part before the dot, which the portal
+  and every audit event already show) or a short masked prefix — never the secret.
+* An API key has no ``/users/me`` (platform refuses it), so the workspace cannot be picked
+  interactively: it must come from ``--workspace-id`` / ``KEYSTONE_WORKSPACE_ID`` / the config.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+# An env var NAME, not a value (same suppressions as device_flow.ENV_TOKEN, for the same reason).
+ENV_API_KEY = "KEYSTONE_API_KEY"  # noqa: S105  # pragma: allowlist secret  # nosec B105
+
+_MASKED_CHARS = 6
+
+
+def from_env(env: Mapping[str, str] | None = None) -> str:
+    """The API key from ``KEYSTONE_API_KEY``, stripped; ``""`` when unset or blank."""
+    env = os.environ if env is None else env
+    return (env.get(ENV_API_KEY) or "").strip()
+
+
+def in_use(env: Mapping[str, str] | None = None) -> bool:
+    """True when this process authenticates with a service-account API key."""
+    return bool(from_env(env))
+
+
+def describe(key: str) -> str:
+    """A printable handle for ``key`` that never contains the secret.
+
+    Platform keys are ``<key id>.<secret>`` and the key id (``ak_<env>_<random>``) is public: the
+    portal lists it and audit events carry it. Anything else is shown as a short masked prefix.
+    """
+    key_id, sep, secret = key.partition(".")
+    if sep and key_id.startswith("ak_") and secret:
+        return key_id
+    return f"{key[:_MASKED_CHARS]}…" if len(key) > _MASKED_CHARS * 2 else "…"

{keystone_cli-0.4.0 → keystone_cli-0.5.0}/src/keystone_cli/auth/device_flow.py

@@ -2,8 +2,10 @@
 
 Pure-ish transport logic (takes an ``httpx.Client`` + injectable ``sleep``/``now``/``env`` for tests).
 The Typer command in ``commands/login`` handles printing + storing. :func:`get_access_token` is the
-read path every command uses, and it knows three ways to produce a bearer:
+read path every command uses, and it knows four ways to produce a bearer:
 
+0. ``KEYSTONE_API_KEY`` — a platform service-account API key (FDP-7177). Highest precedence, used
+   verbatim, never refreshed, never written to disk. The recommended CI path (see ``auth/api_key``).
 1. ``KEYSTONE_TOKEN`` in the environment — used verbatim, never refreshed, never written to disk.
    The CI escape hatch for when something else already minted a token.
 2. the cached access token, while it is still fresh;
@@ -20,6 +22,7 @@ from typing import Any
 
 import httpx
 
+from keystone_cli.auth import api_key
 from keystone_cli.auth.token_store import AuthConfig
 
 _DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
@@ -35,6 +38,8 @@ ENV_TOKEN = "KEYSTONE_TOKEN"  # noqa: S105  # nosec B105
 # The client-credentials secret is read ONLY from the environment, never from a flag: a value on
 # argv is visible in `ps`, lands in shell history, and CI runners echo command lines into build logs.
 ENV_CLIENT_SECRET = "KEYSTONE_CLIENT_SECRET"  # noqa: S105  # pragma: allowlist secret  # nosec B105
+# Platform service-account API key (FDP-7177) — re-exported so callers have one auth namespace.
+ENV_API_KEY = api_key.ENV_API_KEY
 
 MODE_DEVICE = "device"
 MODE_CLIENT_CREDENTIALS = "client_credentials"
@@ -155,12 +160,20 @@ def get_access_token(
 ) -> str:
     """Return a valid bearer. Every command goes through here.
 
-    Order, and why: an explicitly injected ``KEYSTONE_TOKEN`` wins over the cache, because in CI a
-    stale ``~/.keystone/config.json`` left in the image would otherwise silently deploy as the wrong
-    identity. Then the cache while fresh, then renewal per :attr:`AuthConfig.auth_mode`.
+    Order, and why: a service-account ``KEYSTONE_API_KEY`` first (FDP-7177 — the CI identity is the
+    one the job was given, never a person's), then an explicitly injected ``KEYSTONE_TOKEN``. Both win
+    over the cache, because in CI a stale ``~/.keystone/config.json`` left in the image would
+    otherwise silently deploy as the wrong identity. Then the cache while fresh, then renewal per
+    :attr:`AuthConfig.auth_mode`.
     """
     env = os.environ if env is None else env
 
+    key = api_key.from_env(env)
+    if key:
+        # Same contract as KEYSTONE_TOKEN below: verbatim, no request, nothing saved — not even onto
+        # the in-memory config, so a later save() for another reason cannot carry it to disk.
+        return key
+
     injected = (env.get(ENV_TOKEN) or "").strip()
     if injected:
         # Used verbatim: we hold no refresh token for it and it is not ours to renew. Deliberately
@@ -185,7 +198,8 @@ def get_access_token(
         else:
             if not cfg.refresh_token:
                 raise DeviceFlowError(
-                    f"not logged in — run `keystone login`, or set {ENV_TOKEN} / use --client-credentials for CI"
+                    f"not logged in — run `keystone login`; for CI set {ENV_API_KEY} (service account, "
+                    f"recommended), or set {ENV_TOKEN} / use --client-credentials"
                 )
             token = refresh_access_token(client, cfg.issuer, cfg.client_id, cfg.refresh_token)
     finally:

{keystone_cli-0.4.0 → keystone_cli-0.5.0}/src/keystone_cli/auth/token_store.py

@@ -14,6 +14,7 @@ from dataclasses import asdict, dataclass, fields
 from pathlib import Path
 
 from keystone_cli._build_env import BUILD_ENV
+from keystone_cli.auth import api_key
 
 # Baked platform defaults so `keystone login` works with NO flags (like `aws sso login`), PER ENV.
 # NOT secrets — client id is a public identifier, issuer/api are public URLs. The env is stamped into
@@ -155,6 +156,36 @@ def platform_base(cfg: AuthConfig, override: str | None = None) -> str:
     return (override or os.environ.get("KEYSTONE_API_BASE") or cfg.api_base or DEFAULT_API_BASE).rstrip("/")
 
 
+def agent_platform_base(cfg: AuthConfig, control_base: str) -> str:
+    """Agent data-plane URL (invoke/runs/hitl/threads): ``KEYSTONE_AGENT_API_BASE``, then the saved
+    one, then ``control_base`` (FDP-3072 §11.4b)."""
+    return (os.environ.get("KEYSTONE_AGENT_API_BASE") or cfg.agent_api_base or control_base).rstrip("/")
+
+
+# FDP-7177 — workspace from the environment, for CI. A service-account API key cannot reach
+# `/users/me`, so it has no picker: this (or --workspace-id, or a saved one) is how it names its workspace.
+ENV_WORKSPACE_ID = "KEYSTONE_WORKSPACE_ID"
+
+
+def resolve_workspace(cfg: AuthConfig, override: str | None = None) -> str:
+    """Workspace a command targets: ``override`` (``--workspace-id``), then ``KEYSTONE_WORKSPACE_ID``,
+    then the one saved by ``keystone workspace use``. ``""`` when none. The one place this order is written."""
+    return (override or os.environ.get(ENV_WORKSPACE_ID, "").strip() or cfg.workspace_id).strip()
+
+
+def no_workspace_message() -> str:
+    """The error for "no workspace" — with an API key there is no picker, so say what to set instead."""
+    if api_key.in_use():
+        return (
+            f"✗ no workspace — {api_key.ENV_API_KEY} is set and a service account cannot pick one; "
+            f"set {ENV_WORKSPACE_ID}=<workspace-uuid> (or pass --workspace-id)."
+        )
+    return (
+        f"✗ no workspace selected — run `keystone workspace use <name|id>` "
+        f"(or pass --workspace-id, or set {ENV_WORKSPACE_ID})."
+    )
+
+
 def load() -> AuthConfig:
     path = config_path()
     if not path.exists():

{keystone_cli-0.4.0 → keystone_cli-0.5.0}/src/keystone_cli/commands/agent.py

@@ -429,12 +429,9 @@ def deploy(
     # Workspace is caller-supplied (not in the JWT — the user picks it): --workspace-id wins, else the
     # one saved by `keystone workspace use`. entity/user are edge-injected from the token, so they are
     # NOT sent here (a client-set X-Entity-ID would be spoofable; the edge overrides it anyway).
-    workspace = workspace_id or cfg.workspace_id
+    workspace = ts.resolve_workspace(cfg, workspace_id)
     if not workspace:
-        typer.secho(
-            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
-            fg=typer.colors.RED,
-        )
+        typer.secho(ts.no_workspace_message(), fg=typer.colors.RED)
         raise typer.Exit(1)
     try:
         token = df.get_access_token(cfg, save=ts.save)  # cached, or refreshed via the stored refresh token
@@ -504,7 +501,11 @@ def deploy(
         pub_headers = _header_source(cfg, {"X-Workspace-ID": workspace})
         try:
             with httpx.Client(timeout=60) as client:
-                agent_id = _resolve_agent_id(client, base, pub_headers(), name)
+                # FDP-7177: agent-hub returns the agent id with the version, so publish needs no
+                # list call — that call needs agent:read on the WORKSPACE, which a CI service
+                # account otherwise has no reason to hold. An older agent-hub omits the field:
+                # fall back to the lookup by name.
+                agent_id = str(body.get("agent_id") or "") or _resolve_agent_id(client, base, pub_headers(), name)
                 status = _wait_for_staged(client, base, pub_headers, agent_id, str(version_id))
                 if status == "live":
                     typer.echo(f"  {version} is already live — nothing to publish.")
@@ -598,12 +599,9 @@ def invoke(
     if not base:
         typer.secho("✗ no --api-base (or KEYSTONE_API_BASE) configured", fg=typer.colors.RED)
         raise typer.Exit(1)
-    workspace = workspace_id or cfg.workspace_id
+    workspace = ts.resolve_workspace(cfg, workspace_id)
     if not workspace:
-        typer.secho(
-            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
-            fg=typer.colors.RED,
-        )
+        typer.secho(ts.no_workspace_message(), fg=typer.colors.RED)
         raise typer.Exit(1)
     try:
         token = df.get_access_token(cfg, save=ts.save)  # cached, or refreshed via the stored refresh token
@@ -840,7 +838,7 @@ def _agent_api_base(cfg: ts.AuthConfig, control_base: str) -> str:
     lands the new domain this falls back to the control-plane base, so behavior is unchanged.
     Resolution: ``KEYSTONE_AGENT_API_BASE`` env → ``agent_api_base`` in the config file → fallback.
     """
-    return (os.environ.get("KEYSTONE_AGENT_API_BASE") or cfg.agent_api_base or control_base).rstrip("/")
+    return ts.agent_platform_base(cfg, control_base)
 
 
 HeaderSource = agent_logs.HeaderSource
@@ -867,6 +865,11 @@ def _header_source(cfg: ts.AuthConfig, extra: dict[str, str]) -> HeaderSource:
 
 def _token_refused_hint() -> str:
     """What to do about a 401 that a just-renewed token still gets."""
+    if (os.environ.get(df.ENV_API_KEY) or "").strip():
+        return (
+            f"  {df.ENV_API_KEY} was refused — check that the service-account key is not revoked, belongs to "
+            "this environment, and that the service account holds the permission for this action."
+        )
     if (os.environ.get(df.ENV_TOKEN) or "").strip():
         return (
             f"  {df.ENV_TOKEN} is used as given and cannot be renewed — supply a token that lives "
@@ -879,9 +882,12 @@ def _gateway_auth(api_base: str | None, workspace_id: str | None) -> tuple[str,
     """Like :func:`_gateway_ctx`, but returns a header SOURCE for loops that outlive one token."""
     cfg = ts.load()
     base = ts.platform_base(cfg, api_base)
-    workspace = workspace_id or cfg.workspace_id
-    if not base or not workspace:
-        typer.secho("✗ need an api base + workspace — run `keystone workspace use` first.", fg=typer.colors.RED)
+    workspace = ts.resolve_workspace(cfg, workspace_id)
+    if not base:
+        typer.secho("✗ no --api-base (or KEYSTONE_API_BASE) configured", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    if not workspace:
+        typer.secho(ts.no_workspace_message(), fg=typer.colors.RED)
         raise typer.Exit(1)
     extra = {"X-Workspace-ID": workspace, "X-Correlation-ID": str(uuid.uuid4())}
     return _agent_api_base(cfg, base), _header_source(cfg, extra)
@@ -1213,6 +1219,13 @@ def hitl_respond(
                 "platform user ids — `keystone whoami` prints yours.",
                 fg=typer.colors.RED,
             )
+        elif code == "GW_HITL_USER_ONLY":
+            # FDP-7177: a grant does not help here — only a person can approve.
+            typer.secho(
+                f"✗ a service account cannot answer an approval (run {run_id}). A person listed as an "
+                "approver must answer it, from the portal or with their own `keystone login`.",
+                fg=typer.colors.RED,
+            )
         else:
             typer.secho(
                 f"✗ respond refused ({code or 403}): you lack the permission to answer this agent's "
@@ -1434,9 +1447,12 @@ def _control_auth(api_base: str | None, workspace_id: str | None) -> tuple[str,
     """Like :func:`_control_ctx`, but returns a header SOURCE for loops that outlive one token."""
     cfg = ts.load()
     base = ts.platform_base(cfg, api_base)
-    workspace = workspace_id or cfg.workspace_id
-    if not base or not workspace:
-        typer.secho("✗ need an api base + workspace — run `keystone workspace use` first.", fg=typer.colors.RED)
+    workspace = ts.resolve_workspace(cfg, workspace_id)
+    if not base:
+        typer.secho("✗ no --api-base (or KEYSTONE_API_BASE) configured", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    if not workspace:
+        typer.secho(ts.no_workspace_message(), fg=typer.colors.RED)
         raise typer.Exit(1)
     return base, _header_source(cfg, {"X-Workspace-ID": workspace, "X-Correlation-ID": str(uuid.uuid4())})
 
@@ -2100,7 +2116,7 @@ def fetch_cmd(
     manifest = {
         "agent": agent,
         "agent_id": agent_id,
-        "workspace_id": workspace_id or ts.load().workspace_id,
+        "workspace_id": ts.resolve_workspace(ts.load(), workspace_id),
         "api_base": base,
         "fetched_at": agent_logs.iso(now),
         "cli_version": cli_version(),
@@ -2921,12 +2937,9 @@ def publish(
     """
     cfg = ts.load()
     base = ts.platform_base(cfg, api_base)
-    workspace = workspace_id or cfg.workspace_id
+    workspace = ts.resolve_workspace(cfg, workspace_id)
     if not workspace:
-        typer.secho(
-            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
-            fg=typer.colors.RED,
-        )
+        typer.secho(ts.no_workspace_message(), fg=typer.colors.RED)
         raise typer.Exit(1)
     try:
         token = df.get_access_token(cfg, save=ts.save)
@@ -3058,9 +3071,9 @@ def doctor(
     out = _DoctorOut(agent, json_out)
     cfg = ts.load()
     base = ts.platform_base(cfg, api_base)
-    workspace = workspace_id or cfg.workspace_id
+    workspace = ts.resolve_workspace(cfg, workspace_id)
     if not workspace:
-        out.fail("✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).")
+        out.fail(ts.no_workspace_message())
     try:
         token = df.get_access_token(cfg, save=ts.save)
     except df.DeviceFlowError as exc:
@@ -3396,12 +3409,9 @@ def status(
     """
     cfg = ts.load()
     base = ts.platform_base(cfg, api_base)
-    workspace = workspace_id or cfg.workspace_id
+    workspace = ts.resolve_workspace(cfg, workspace_id)
     if not workspace:
-        typer.secho(
-            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
-            fg=typer.colors.RED,
-        )
+        typer.secho(ts.no_workspace_message(), fg=typer.colors.RED)
         raise typer.Exit(1)
     try:
         token = df.get_access_token(cfg, save=ts.save)
@@ -3453,12 +3463,9 @@ def _hub_auth(api_base: str | None, workspace_id: str | None) -> tuple[str, dict
     """(base, headers) for agent-hub lifecycle calls — the login/workspace dance."""
     cfg = ts.load()
     base = ts.platform_base(cfg, api_base)
-    workspace = workspace_id or cfg.workspace_id
+    workspace = ts.resolve_workspace(cfg, workspace_id)
     if not workspace:
-        typer.secho(
-            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
-            fg=typer.colors.RED,
-        )
+        typer.secho(ts.no_workspace_message(), fg=typer.colors.RED)
         raise typer.Exit(1)
     try:
         token = df.get_access_token(cfg, save=ts.save)

{keystone_cli-0.4.0 → keystone_cli-0.5.0}/src/keystone_cli/commands/login.py

@@ -49,9 +49,10 @@ def login(
         False,
         "--client-credentials",
         help=(
-            f"Non-interactive service-account login for CI. Reads the secret from ${df.ENV_CLIENT_SECRET} "
+            f"Non-interactive Keycloak client login. Reads the secret from ${df.ENV_CLIENT_SECRET} "
             f"only — there is deliberately no --client-secret flag, because a secret on argv is visible in "
-            f"`ps`, shell history and CI build logs."
+            f"`ps`, shell history and CI build logs. For CI, the recommended path is a platform "
+            f"service-account API key in ${df.ENV_API_KEY} (no login step needed)."
         ),
     ),
 ) -> None:
@@ -66,7 +67,17 @@ def login(
       keystone login
       keystone login --no-browser
       KEYSTONE_CLIENT_SECRET=... keystone login --client-credentials
+
+    For CI, prefer a service-account API key: set KEYSTONE_API_KEY and
+    KEYSTONE_WORKSPACE_ID, and skip `keystone login`.
     """
+    if (os.environ.get(df.ENV_API_KEY) or "").strip():
+        # FDP-7177: the key outranks any cached login, so this session would be shadowed anyway.
+        typer.secho(
+            f"  ⚠ {df.ENV_API_KEY} is set — later commands use that service-account key, not this login. "
+            f"Unset it to use the login.",
+            fg=typer.colors.YELLOW,
+        )
     # Precedence: --flag / KEYSTONE_* env (typer) > cached config (SAME env only) > baked per-env default.
     # Per-env packages own their endpoints, so a cross-env cached config must NOT shadow them: if the
     # cached config was written for a different env (its stamped `env` differs, or — pre-env configs —
@@ -111,7 +122,7 @@ def login(
     if not interactive:
         typer.secho(
             "  (no TTY — not opening a browser; the device grant still needs a human to approve the URL below. "
-            f"For unattended runs use --client-credentials or set ${df.ENV_TOKEN}.)",
+            f"For unattended runs set ${df.ENV_API_KEY} (service account) — no login needed.)",
             fg=typer.colors.YELLOW,
         )