agentworks-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{agentworks_cli-0.3.0 → agentworks_cli-0.4.0}/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.4.0](https://github.com/WayfarerLabs/agentworks/compare/v0.3.0...v0.4.0) (2026-06-01)
+
+
+### Features
+
+* **console:** configurable layout and restore-session ([73bdf68](https://github.com/WayfarerLabs/agentworks/commit/73bdf681581825c8838398bc291839ddb8cbe82f))
+* **console:** configurable layout and restore-session for accidental shell kills ([5d5ae48](https://github.com/WayfarerLabs/agentworks/commit/5d5ae487869ac31bb82bad21f1b9bc191e0aacae))
+
+
+### Bug Fixes
+
+* **console:** include console name in untagged-pane warnings and check set-option result ([a48adf8](https://github.com/WayfarerLabs/agentworks/commit/a48adf80dfb78bb6264918b55fef1072d5898b10))
+* **console:** only mirror swap-pane into local map on success ([7f33652](https://github.com/WayfarerLabs/agentworks/commit/7f336525aa27ef4eedefd0d93c0c9a517e8c1f72))
+* **console:** pass console name through _live_best_effort and refine restore-session error messages ([eec0b62](https://github.com/WayfarerLabs/agentworks/commit/eec0b62afb14cd946ccc9234ef19266f5340a6bd))
+* **console:** restore-session raises on any partial split/tag failure ([97f72aa](https://github.com/WayfarerLabs/agentworks/commit/97f72aa32c65923ffe43ff844219b3e92ef0976d))
+* **console:** shlex-quote cd-failure diagnostic and reword restore-session help ([c0fa16b](https://github.com/WayfarerLabs/agentworks/commit/c0fa16bda5c0de0348a998b27d9e4e5c8b711fb5))
+* **console:** validate restore-session tag permutation, allowlist named_console, clean docstring and sample-config ([72d3815](https://github.com/WayfarerLabs/agentworks/commit/72d3815ea7ac6a84b13e8be175f9bc6e99a47d0d))
+
+
+### Performance Improvements
+
+* **console:** single-pass tag validation, in-memory reorder, warn on missing pane id ([c8f8362](https://github.com/WayfarerLabs/agentworks/commit/c8f8362cb6f07c45744650f5ee579fc8da605696))
+
+
+### Documentation
+
+* **console:** clarify reinit_workspace docstring on detection vs always-applied steps ([b7e548b](https://github.com/WayfarerLabs/agentworks/commit/b7e548bcf3396f3fa339551c0b93485209a20890))
+
 ## [0.3.0](https://github.com/WayfarerLabs/agentworks/compare/v0.2.1...v0.3.0) (2026-06-01)
 
 

{agentworks_cli-0.3.0 → agentworks_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentworks-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: CLI for orchestrating workspace lifecycle across multiple compute targets
 Project-URL: Homepage, https://github.com/WayfarerLabs/agentworks
 Project-URL: Repository, https://github.com/WayfarerLabs/agentworks
@@ -380,7 +380,7 @@ Manage workspaces on VMs.
 | `agentworks workspace list`                 | List workspaces                     |
 | `agentworks workspace copy <source> <name>` | Copy a workspace to a new VM        |
 | `agentworks workspace rehome <name>`        | Move workspace to a new path        |
-| `agentworks workspace repair <name>`        | Repair workspace infrastructure     |
+| `agentworks workspace reinit <name>`        | Reinit workspace infrastructure     |
 | `agentworks workspace delete <name>`        | Delete a workspace                  |
 
 `workspace create <name>` takes the workspace name as a required positional. Optional flags: `--vm`,
@@ -400,19 +400,18 @@ during deletion. Pass `--yes` to skip the confirmation prompt.
 
 Manage agents (isolated Linux users) on VMs. Agents are VM-scoped and access workspaces via grants.
 
-| Command                                                      | Description                    |
-| ------------------------------------------------------------ | ------------------------------ |
-| `agentworks agent create <name> [--vm]`                      | Create an agent on a VM        |
-| `agentworks agent list [--vm <vm>]`                          | List agents                    |
-| `agentworks agent describe <name>`                           | Show agent details and grants  |
-| `agentworks agent reinit <name>`                             | Re-run agent setup             |
-| `agentworks agent workspace-grants grant <name> <ws>[,<ws>]` | Grant workspace access         |
-| `agentworks agent workspace-grants grant <name> --all`       | Grant access to all workspaces |
-| `agentworks agent workspace-grants deny <name> <ws>[,<ws>]`  | Remove workspace access        |
-| `agentworks agent workspace-grants deny <name> --all`        | Remove all explicit grants     |
-| `agentworks agent workspace-grants list <name>`              | List workspace grants          |
-| `agentworks agent shell <name> [--workspace <ws>]`           | Shell into an agent            |
-| `agentworks agent delete <name>`                             | Delete an agent                |
+| Command                                            | Description                    |
+| -------------------------------------------------- | ------------------------------ |
+| `agentworks agent create <name> [--vm]`            | Create an agent on a VM        |
+| `agentworks agent list [--vm <vm>]`                | List agents                    |
+| `agentworks agent describe <name>`                 | Show agent details and grants  |
+| `agentworks agent reinit <name>`                   | Re-run agent setup             |
+| `agentworks agent grant-workspace <name> <ws>...`  | Grant workspace access         |
+| `agentworks agent grant-workspace <name> --all`    | Grant access to all workspaces |
+| `agentworks agent revoke-workspace <name> <ws>...` | Revoke workspace access        |
+| `agentworks agent revoke-workspace <name> --all`   | Revoke all explicit grants     |
+| `agentworks agent shell <name> [--workspace <ws>]` | Shell into an agent            |
+| `agentworks agent delete <name>`                   | Delete an agent                |
 
 `agent create <name>` takes the agent name as a required positional. Optional flags: `--vm`,
 `--template`, and `--grant-all-workspaces`.
@@ -564,8 +563,9 @@ aw-console-backend
 
 The tmux session is built lazily on first `attach` (or rebuilt with `--recreate`). Adding or
 removing sessions/shells while the console is attached updates tmux immediately; when offline, only
-the DB is touched and changes appear on next attach. The console does not auto-boot the VM for live
-sync; VM start happens only on explicit `attach`.
+the DB is touched and changes appear on next attach. The mutation commands (`add-session`,
+`remove-session`, `add-shell`) never auto-boot the VM; the explicit attach/repair commands
+(`attach`, `restore-session`) do start a stopped VM, since their job is to bring live state up.
 
 #### VM console (deprecated)
 
@@ -610,17 +610,17 @@ Template commands support `{{session_name}}` and `{{workspace_name}}` variable s
 by `session restart` -- useful for tools like Claude Code where `--resume` picks up the previous
 conversation. If omitted, the regular `command` is used.
 
-### Installers
+### Catalog
 
 Browse and inspect the built-in catalog of installable tools.
 
-| Command                                | Description                        |
-| -------------------------------------- | ---------------------------------- |
-| `agentworks installer list`            | List all available catalog entries |
-| `agentworks installer describe <name>` | Show details of a catalog entry    |
+| Command                              | Description                        |
+| ------------------------------------ | ---------------------------------- |
+| `agentworks catalog list`            | List all available catalog entries |
+| `agentworks catalog describe <name>` | Show details of a catalog entry    |
 
-`installer list` accepts `--type` (apt-source, apt-package, system-install-cmd, user-install-cmd)
-and `--source` (builtin, user) filters.
+`catalog list` accepts `--type` (apt-source, apt-package, system-install-cmd, user-install-cmd) and
+`--source` (built-in, custom) filters.
 
 ### Config
 
@@ -696,7 +696,7 @@ standalone via `claude plugin marketplace add`.
 ### Built-in Catalog
 
 Agentworks ships a built-in catalog of common tools (apt sources, apt packages, system install
-commands, and user install commands). Run `agentworks installer list` to see what is available.
+commands, and user install commands). Run `agentworks catalog list` to see what is available.
 Reference catalog entries by name in `vm_templates`, `admin.config`, and `agent_templates`.
 User-defined entries in your config override built-in entries with the same name.
 

{agentworks_cli-0.3.0 → agentworks_cli-0.4.0}/README.md

@@ -363,7 +363,7 @@ Manage workspaces on VMs.
 | `agentworks workspace list`                 | List workspaces                     |
 | `agentworks workspace copy <source> <name>` | Copy a workspace to a new VM        |
 | `agentworks workspace rehome <name>`        | Move workspace to a new path        |
-| `agentworks workspace repair <name>`        | Repair workspace infrastructure     |
+| `agentworks workspace reinit <name>`        | Reinit workspace infrastructure     |
 | `agentworks workspace delete <name>`        | Delete a workspace                  |
 
 `workspace create <name>` takes the workspace name as a required positional. Optional flags: `--vm`,
@@ -383,19 +383,18 @@ during deletion. Pass `--yes` to skip the confirmation prompt.
 
 Manage agents (isolated Linux users) on VMs. Agents are VM-scoped and access workspaces via grants.
 
-| Command                                                      | Description                    |
-| ------------------------------------------------------------ | ------------------------------ |
-| `agentworks agent create <name> [--vm]`                      | Create an agent on a VM        |
-| `agentworks agent list [--vm <vm>]`                          | List agents                    |
-| `agentworks agent describe <name>`                           | Show agent details and grants  |
-| `agentworks agent reinit <name>`                             | Re-run agent setup             |
-| `agentworks agent workspace-grants grant <name> <ws>[,<ws>]` | Grant workspace access         |
-| `agentworks agent workspace-grants grant <name> --all`       | Grant access to all workspaces |
-| `agentworks agent workspace-grants deny <name> <ws>[,<ws>]`  | Remove workspace access        |
-| `agentworks agent workspace-grants deny <name> --all`        | Remove all explicit grants     |
-| `agentworks agent workspace-grants list <name>`              | List workspace grants          |
-| `agentworks agent shell <name> [--workspace <ws>]`           | Shell into an agent            |
-| `agentworks agent delete <name>`                             | Delete an agent                |
+| Command                                            | Description                    |
+| -------------------------------------------------- | ------------------------------ |
+| `agentworks agent create <name> [--vm]`            | Create an agent on a VM        |
+| `agentworks agent list [--vm <vm>]`                | List agents                    |
+| `agentworks agent describe <name>`                 | Show agent details and grants  |
+| `agentworks agent reinit <name>`                   | Re-run agent setup             |
+| `agentworks agent grant-workspace <name> <ws>...`  | Grant workspace access         |
+| `agentworks agent grant-workspace <name> --all`    | Grant access to all workspaces |
+| `agentworks agent revoke-workspace <name> <ws>...` | Revoke workspace access        |
+| `agentworks agent revoke-workspace <name> --all`   | Revoke all explicit grants     |
+| `agentworks agent shell <name> [--workspace <ws>]` | Shell into an agent            |
+| `agentworks agent delete <name>`                   | Delete an agent                |
 
 `agent create <name>` takes the agent name as a required positional. Optional flags: `--vm`,
 `--template`, and `--grant-all-workspaces`.
@@ -547,8 +546,9 @@ aw-console-backend
 
 The tmux session is built lazily on first `attach` (or rebuilt with `--recreate`). Adding or
 removing sessions/shells while the console is attached updates tmux immediately; when offline, only
-the DB is touched and changes appear on next attach. The console does not auto-boot the VM for live
-sync; VM start happens only on explicit `attach`.
+the DB is touched and changes appear on next attach. The mutation commands (`add-session`,
+`remove-session`, `add-shell`) never auto-boot the VM; the explicit attach/repair commands
+(`attach`, `restore-session`) do start a stopped VM, since their job is to bring live state up.
 
 #### VM console (deprecated)
 
@@ -593,17 +593,17 @@ Template commands support `{{session_name}}` and `{{workspace_name}}` variable s
 by `session restart` -- useful for tools like Claude Code where `--resume` picks up the previous
 conversation. If omitted, the regular `command` is used.
 
-### Installers
+### Catalog
 
 Browse and inspect the built-in catalog of installable tools.
 
-| Command                                | Description                        |
-| -------------------------------------- | ---------------------------------- |
-| `agentworks installer list`            | List all available catalog entries |
-| `agentworks installer describe <name>` | Show details of a catalog entry    |
+| Command                              | Description                        |
+| ------------------------------------ | ---------------------------------- |
+| `agentworks catalog list`            | List all available catalog entries |
+| `agentworks catalog describe <name>` | Show details of a catalog entry    |
 
-`installer list` accepts `--type` (apt-source, apt-package, system-install-cmd, user-install-cmd)
-and `--source` (builtin, user) filters.
+`catalog list` accepts `--type` (apt-source, apt-package, system-install-cmd, user-install-cmd) and
+`--source` (built-in, custom) filters.
 
 ### Config
 
@@ -679,7 +679,7 @@ standalone via `claude plugin marketplace add`.
 ### Built-in Catalog
 
 Agentworks ships a built-in catalog of common tools (apt sources, apt packages, system install
-commands, and user install commands). Run `agentworks installer list` to see what is available.
+commands, and user install commands). Run `agentworks catalog list` to see what is available.
 Reference catalog entries by name in `vm_templates`, `admin.config`, and `agent_templates`.
 User-defined entries in your config override built-in entries with the same name.
 

{agentworks_cli-0.3.0 → agentworks_cli-0.4.0}/agentworks/agents/manager.py

@@ -6,7 +6,15 @@ from typing import TYPE_CHECKING
 
 from agentworks import output
 from agentworks.config import validate_name
-from agentworks.output import AgentError, VMError
+from agentworks.errors import (
+    AlreadyExistsError,
+    AuthorizationError,
+    ExternalError,
+    NotFoundError,
+    StateError,
+    UserAbort,
+    ValidationError,
+)
 from agentworks.ssh import admin_exec_target
 
 if TYPE_CHECKING:
@@ -110,7 +118,11 @@ def create_agent(
     validate_name(name)
 
     if db.get_agent(name) is not None:
-        raise AgentError(f"agent '{name}' already exists")
+        raise AlreadyExistsError(
+            f"agent '{name}' already exists",
+            entity_kind="agent",
+            entity_name=name,
+        )
 
     vm = _require_vm(db, vm_name)
     linux_user = derive_linux_user(name)
@@ -146,7 +158,12 @@ def create_agent(
             raise
         except Exception as e:
             _safe_rollback()
-            raise AgentError(f"creating agent: {e}\nSSH log: {ssh_logger.path}") from None
+            raise ExternalError(
+                f"creating agent: {e}",
+                entity_kind="agent",
+                entity_name=name,
+                hint=f"SSH log: {ssh_logger.path}",
+            ) from e
     finally:
         ssh_logger.close()
 
@@ -178,7 +195,11 @@ def delete_agent(
     """Delete an agent from a VM."""
     agent = db.get_agent(name)
     if agent is None:
-        raise AgentError(f"agent '{name}' not found")
+        raise NotFoundError(
+            f"agent '{name}' not found",
+            entity_kind="agent",
+            entity_name=name,
+        )
 
     # Check for sessions using this agent
     all_sessions = db.list_sessions()
@@ -186,8 +207,11 @@ def delete_agent(
     if agent_sessions and not force:
         for s in agent_sessions:
             output.detail(f"{s.name}")
-        raise AgentError(
-            f"agent '{name}' has {len(agent_sessions)} session(s). Delete them first, or use --force."
+        raise StateError(
+            f"agent '{name}' has {len(agent_sessions)} session(s).",
+            entity_kind="agent",
+            entity_name=name,
+            hint="Delete the sessions first, or pass --force to also stop them.",
         )
 
     if not yes:
@@ -195,7 +219,7 @@ def delete_agent(
         if agent_sessions:
             msg += f" ({len(agent_sessions)} session(s) will also be stopped)"
         if not output.confirm(msg):
-            raise output.UserAbort("delete cancelled")
+            raise UserAbort("delete cancelled")
 
     vm = _require_vm(db, agent.vm_name)
 
@@ -232,9 +256,12 @@ def delete_agent(
             elif status == SessionStatus.UNKNOWN:
                 unstoppable.append(session.name)
         if unstoppable:
-            raise AgentError(
+            raise StateError(
                 f"cannot delete agent '{name}': {len(unstoppable)} session(s) could not be stopped "
-                f"({', '.join(unstoppable)}). Resolve manually before retrying."
+                f"({', '.join(unstoppable)}).",
+                entity_kind="agent",
+                entity_name=name,
+                hint="Resolve the stuck sessions manually before retrying.",
             )
         for session in agent_sessions:
             db.delete_session(session.name)
@@ -266,7 +293,11 @@ def reinit_agent(
 
     agent = db.get_agent(name)
     if agent is None:
-        raise AgentError(f"agent '{name}' not found")
+        raise NotFoundError(
+            f"agent '{name}' not found",
+            entity_kind="agent",
+            entity_name=name,
+        )
 
     agent_tmpl = resolve_template(config, agent.template)
     if agent.template and agent.template != "default":
@@ -290,7 +321,12 @@ def reinit_agent(
             )
             raise
         except Exception as e:
-            raise AgentError(f"reinitializing agent: {e}\nSSH log: {ssh_logger.path}") from None
+            raise ExternalError(
+                f"reinitializing agent: {e}",
+                entity_kind="agent",
+                entity_name=name,
+                hint=f"SSH log: {ssh_logger.path}",
+            ) from e
     finally:
         ssh_logger.close()
 
@@ -370,7 +406,11 @@ def describe_agent(
     """Show detailed information about an agent."""
     agent = db.get_agent(name)
     if agent is None:
-        raise AgentError(f"agent '{name}' not found")
+        raise NotFoundError(
+            f"agent '{name}' not found",
+            entity_kind="agent",
+            entity_name=name,
+        )
 
     output.info(f"Name:       {agent.name}")
     output.info(f"VM:         {agent.vm_name}")
@@ -410,7 +450,11 @@ def shell_agent(
     """Open a shell as an agent user on a VM."""
     agent = db.get_agent(name)
     if agent is None:
-        raise AgentError(f"agent '{name}' not found")
+        raise NotFoundError(
+            f"agent '{name}' not found",
+            entity_kind="agent",
+            entity_name=name,
+        )
 
     vm = _require_vm(db, agent.vm_name)
 
@@ -427,9 +471,18 @@ def shell_agent(
     if workspace_name:
         ws = db.get_workspace(workspace_name)
         if ws is None:
-            raise AgentError(f"workspace '{workspace_name}' not found")
+            raise NotFoundError(
+                f"workspace '{workspace_name}' not found",
+                entity_kind="workspace",
+                entity_name=workspace_name,
+            )
         if not db.has_any_grant(name, workspace_name):
-            raise AgentError(f"agent '{name}' does not have access to workspace '{workspace_name}'")
+            raise AuthorizationError(
+                f"agent '{name}' does not have access to workspace '{workspace_name}'",
+                entity_kind="agent",
+                entity_name=name,
+                hint=f"Run 'agent grant-workspace {name} {workspace_name}' to grant access.",
+            )
         import shlex
 
         q_path = shlex.quote(ws.workspace_path)
@@ -454,11 +507,20 @@ def exec_agent(
 
     agent = db.get_agent(name)
     if agent is None:
-        raise AgentError(f"agent '{name}' not found")
+        raise NotFoundError(
+            f"agent '{name}' not found",
+            entity_kind="agent",
+            entity_name=name,
+        )
 
     vm = _require_vm(db, agent.vm_name)
     if vm.tailscale_host is None:
-        raise AgentError(f"VM '{vm.name}' has no Tailscale IP (init may not be complete)")
+        raise StateError(
+            f"VM '{vm.name}' has no Tailscale IP",
+            entity_kind="vm",
+            entity_name=vm.name,
+            hint="VM init may not be complete. Check 'vm describe' for status.",
+        )
 
     remote_cmd = command[0] if len(command) == 1 else shlex.join(command)
     su_cmd = f"sudo -n su --login {agent.linux_user} -c {shlex.quote(remote_cmd)}"
@@ -484,9 +546,21 @@ def grant_workspaces(
     grant_all: bool = False,
 ) -> None:
     """Grant an agent explicit access to workspaces."""
+    if not grant_all and not workspace_names:
+        raise ValidationError(
+            f"grant for '{agent_name}' needs at least one workspace name "
+            f"or workspace_names empty + grant_all=True",
+            entity_kind="agent",
+            entity_name=agent_name,
+        )
+
     agent = db.get_agent(agent_name)
     if agent is None:
-        raise AgentError(f"agent '{agent_name}' not found")
+        raise NotFoundError(
+            f"agent '{agent_name}' not found",
+            entity_kind="agent",
+            entity_name=agent_name,
+        )
 
     vm = _require_vm(db, agent.vm_name)
 
@@ -509,22 +583,34 @@ def grant_workspaces(
         output.detail(f"Granted: {ws_name}")
 
 
-def deny_workspaces(
+def revoke_workspaces(
     db: Database,
     config: Config,
     *,
     agent_name: str,
     workspace_names: list[str],
-    deny_all: bool = False,
+    revoke_all: bool = False,
 ) -> None:
-    """Remove explicit workspace grants from an agent."""
+    """Revoke explicit workspace grants from an agent."""
+    if not revoke_all and not workspace_names:
+        raise ValidationError(
+            f"revoke for '{agent_name}' needs at least one workspace name "
+            f"or workspace_names empty + revoke_all=True",
+            entity_kind="agent",
+            entity_name=agent_name,
+        )
+
     agent = db.get_agent(agent_name)
     if agent is None:
-        raise AgentError(f"agent '{agent_name}' not found")
+        raise NotFoundError(
+            f"agent '{agent_name}' not found",
+            entity_kind="agent",
+            entity_name=agent_name,
+        )
 
     vm = _require_vm(db, agent.vm_name)
 
-    if deny_all:
+    if revoke_all:
         db.update_agent_grant_all(agent_name, False)
         db.delete_explicit_grants(agent_name)
         # Remove from groups where no implicit grants remain
@@ -535,7 +621,7 @@ def deny_workspaces(
                 remaining_implicit.append(ws_name)
             else:
                 _remove_from_workspace_group(vm, config, db, agent.linux_user, ws_name, logger=None)
-        output.info(f"All explicit grants removed for agent '{agent_name}'")
+        output.info(f"All explicit grants revoked for agent '{agent_name}'")
         if remaining_implicit:
             output.warn(
                 f"agent still has implicit access via sessions to: {', '.join(remaining_implicit)}"
@@ -546,39 +632,9 @@ def deny_workspaces(
         db.delete_agent_grant(agent_name, ws_name, "explicit")
         if not db.has_any_grant(agent_name, ws_name):
             _remove_from_workspace_group(vm, config, db, agent.linux_user, ws_name, logger=None)
-            output.detail(f"Denied: {ws_name}")
+            output.detail(f"Revoked: {ws_name}")
         else:
-            output.detail(f"Denied: {ws_name} (still has implicit access via sessions)")
-
-
-def list_grants(
-    db: Database,
-    *,
-    agent_name: str,
-) -> None:
-    """List workspace grants for an agent."""
-    agent = db.get_agent(agent_name)
-    if agent is None:
-        raise AgentError(f"agent '{agent_name}' not found")
-
-    if agent.grant_all:
-        output.info(f"Agent '{agent_name}' has grant-all enabled (access to all workspaces)")
-
-    grants = db.list_granted_workspaces_with_types(agent_name)
-    if not grants:
-        output.info("No workspace grants.")
-        return
-
-    output.info(f"{'WORKSPACE':<25} {'TYPE'}")
-    output.info("-" * 45)
-    for ws_name, has_explicit, has_implicit in grants:
-        if has_explicit and has_implicit:
-            grant_type = "explicit + implicit"
-        elif has_explicit:
-            grant_type = "explicit"
-        else:
-            grant_type = "implicit (via sessions)"
-        output.info(f"{ws_name:<25} {grant_type}")
+            output.detail(f"Revoked: {ws_name} (still has implicit access via sessions)")
 
 
 # -- VM operations ---------------------------------------------------------
@@ -593,7 +649,11 @@ def _resolve_ws_group(db: Database, workspace_name: str) -> str:
     """
     ws = db.get_workspace(workspace_name)
     if ws is None:
-        raise AgentError(f"workspace '{workspace_name}' not found")
+        raise NotFoundError(
+            f"workspace '{workspace_name}' not found",
+            entity_kind="workspace",
+            entity_name=workspace_name,
+        )
     return ws.linux_group
 
 
@@ -1127,19 +1187,31 @@ def _build_agent_test_command(
 def _require_vm(db: Database, vm_name: str) -> VMRow:
     vm = db.get_vm(vm_name)
     if vm is None:
-        raise VMError(f"VM '{vm_name}' not found")
+        raise NotFoundError(
+            f"VM '{vm_name}' not found",
+            entity_kind="vm",
+            entity_name=vm_name,
+        )
     return vm
 
 
 def _require_workspace(db: Database, workspace_name: str) -> WorkspaceRow:
     ws = db.get_workspace(workspace_name)
     if ws is None:
-        raise AgentError(f"workspace '{workspace_name}' not found")
+        raise NotFoundError(
+            f"workspace '{workspace_name}' not found",
+            entity_kind="workspace",
+            entity_name=workspace_name,
+        )
     return ws
 
 
 def _require_vm_for_workspace(db: Database, ws: WorkspaceRow) -> VMRow:
     vm = db.get_vm(ws.vm_name)
     if vm is None:
-        raise VMError(f"VM '{ws.vm_name}' not found")
+        raise NotFoundError(
+            f"VM '{ws.vm_name}' not found",
+            entity_kind="vm",
+            entity_name=ws.vm_name,
+        )
     return vm

{agentworks_cli-0.3.0 → agentworks_cli-0.4.0}/agentworks/catalog.py

@@ -13,11 +13,13 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from agentworks.errors import ExternalError
+
 if TYPE_CHECKING:
     from agentworks.config import Config
 
 
-class CatalogError(Exception):
+class CatalogError(ExternalError):
     """Raised when the catalog is invalid."""