feat: add tool specs

specs/DESIGN.md

@@ -9,7 +9,8 @@ specs/designs/
 ├── 00-foundation/     — core server infrastructure (server lifecycle, auth, config)
 ├── 01-data/           — external data sources (Git, Kubernetes)
 ├── 10-layout/         — overall UI designs
-└── 11-models/         — model page designs
+├── 11-models/         — model page designs
+└── 12-tools/          — tool page designs
 ```
 
 ---

specs/designs/12-tools/detail.md

@@ -0,0 +1,45 @@
+# Tool Detail Page
+
+## Overview
+
+Single tool detail view. Branches on `tool.mode` for external vs managed layout.
+
+Follows the layout of `specs/designs/10-layout/detail.md`, only the details are documented in this spec.
+
+## Page Name
+
+"{tool.name}" for title and breadcrumb
+
+## Page Header (always shown)
+
+```
+[Icon] Tool Name                        [status badge] [Edit] [⋮]
+       External | Managed
+```
+
+- Icon: tool icon
+- Tool name (primary)
+- Mode label below the name: `External` or `Managed`
+- Status badge (right, when status is set)
+- Edit button: navigates to the edit page
+- ⋮ menu: includes Delete and a context action (`Test` for external or deployed tools, `Deploy` for not-deployed managed tools)
+
+## Config Panel
+
+Always shown for external tools.
+
+- endpoint URL
+- auth fields when configured
+- transport
+
+## Deployment Panel (Managed Mode)
+
+Always shown for managed tools. Shows deployment/runtime configuration.
+
+## Management Tabs
+
+Always shown.
+
+## Delete Confirmation Dialog
+
+Destructive confirmation. On success, returns to the tools list.

specs/designs/12-tools/domain.md

@@ -0,0 +1,39 @@
+# Tool Domain
+
+Tools are either external endpoints or managed deployments.
+
+## Core Fields
+
+All tools share these core fields:
+
+- identity: id, name
+- presentation: icon, description, tags
+- classification: mode
+- transport: transport
+- placement: stack
+
+## Transport
+
+Tool transport is one of:
+
+- sse
+- http
+
+## External Tool
+
+External tools define how to call a remote MCP endpoint.
+
+- endpoint
+- auth configuration
+- optional availability status
+
+## Managed Tool
+
+Managed tools define runtime/deployment configuration.
+
+- runtime template
+- optional deployment status
+
+## Tool Union
+
+- Tool = ExternalTool | ManagedTool

specs/designs/12-tools/form.md

@@ -0,0 +1,53 @@
+# Tool Form Page
+
+## Overview
+
+Shared `<ToolForm>` handles both create and edit. The `mode` toggle (External vs Managed) is chosen at the top in create mode and is locked in edit mode.
+
+Follows the form layout in `specs/designs/10-layout/form.md`, only the details are documented in this spec.
+
+## Form Layout
+
+### External
+
+Basic Information → Endpoint
+
+### Managed
+
+Basic Information → Deployment
+
+## Panels
+
+### Basic Information (shared)
+
+Beyond the standard Icon + Name + Mode fields described in the layout spec:
+
+- **Icon**: default `tool`
+- **Description**: textarea, 3 rows, placeholder `What does this tool do?`; help: "Provide a brief description that can also help AI assistant to understand the tool's functionality."
+- **Tags**: optional list input
+
+### Endpoint (external only)
+
+- **URL**: text, placeholder `e.g. https://my-tool.internal/mcp`
+- **Transport**: `Streamable HTTP` | `Server-side Events`
+- **Auth Type**: `None` | `Bearer Token` | `API Key`; default `None`
+- When auth type is `Bearer Token`:
+  - **Bearer Token**: password input
+- When auth type is `API Key`:
+  - **API Key Header**: text, placeholder `e.g. X-Api-Key`
+  - **API Key Value**: password input
+
+### Deployment (managed only)
+
+- **Transport**: `Streamable HTTP` | `Server-side Events`
+- **Launch Command**: single command input (runtime inferred from command prefix)
+- **Runtime Settings**: optional deployment/runtime configuration
+
+## Validation
+
+- Name is required
+
+## Breadcrumb
+
+- Create: `Tools / [New Tool]`
+- Edit: `Tools / {tool.name}`

specs/designs/12-tools/list.md

@@ -0,0 +1,65 @@
+# Tools List Page
+
+## Overview
+
+Card grid list of all tools (external + managed).
+
+Follows the layout of `specs/designs/10-layout/list.md`, only the details are documented in this spec.
+
+## Page Name
+
+"Tools" for title and breadcrumb
+
+## Filters
+
+| Row  | Mode   | Values                            | Default | Extra                         |
+| ---- | ------ | --------------------------------- | ------- | ----------------------------- |
+| Mode | Single | All, External, Managed            | All     | shows count badge             |
+| Tags | Multi  | the tags present across all tools | None    | row hidden when no tags exist |
+
+## Card Anatomy
+
+Tool icon sits at the left, a fixed 48 px square, vertically centered. The rest is on the right side of the card, vertically positioned. Card height is fixed at 128 px.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ┌────────┐  Tool Name                          [status]     │
+│ │        │  Description text, clamped to two lines…         │
+│ │  icon  │                                                  │
+│ │        │                                                  │
+│ └────────┘  [tag] [tag]                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+The card is clickable as a whole and links to `/workloads/tools/[id]`. When `onselect` is provided (e.g. inside a tool picker), the card renders as a button instead and calls the handler on click / Enter.
+
+### Header
+
+- Large text for the tool name
+- Status badge (right, when status is set)
+
+### Body
+
+- Description, clamped to two lines
+
+### Footer
+
+- tags
+
+## Empty States
+
+**No tools at all:**
+
+```
+WrenchIcon (muted)
+"No tools yet."
+[New Tool button]
+```
+
+**No match:**
+
+```
+WrenchIcon (muted)
+"No tools match your filters."
+[Clear filters link]
+```

specs/designs/12-tools/testing.md

@@ -0,0 +1,116 @@
+# Tool Test Page
+
+## Overview
+
+A sandbox for testing a selected tool by listing its exposed MCP tools and invoking one with custom arguments.
+
+## Route
+
+`/utilities/testing/tool`
+
+Optional query parameter `?tool=<toolId>` pre-selects the tool on load (used when navigating from a tool's detail page).
+
+## Page Name
+
+"Tool Calling" for title and breadcrumb
+
+## Page Layout
+
+```
+[Tool Calling]                       (page title / breadcrumb)
+
+┌─────────────────────────────────────────────────────────────┐
+│  Tool                                                       │
+│  [Selected tool button]                  [Select tool]      │
+└─────────────────────────────────────────────────────────────┘
+
+ (no selection)          (tool selected)
+┌──────────────┐         ┌──────────────────────────────────────┐
+│  Select a    │   →     │  MCP Tools  +  Tool Call             │
+│  tool above  │         │  (single test surface)               │
+└──────────────┘         └──────────────────────────────────────┘
+```
+
+## Tool Selector
+
+The selected tool is shown in the top selector button (icon + name). If no tool is selected, the page shows a placeholder prompt to select one.
+
+## MCP Tools Section
+
+Shows the tool list exposed by the selected server.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  MCP Tools                                  [List Tools]    │
+│                                                             │
+│  Result                                                     │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  Tools  (3)                                           │  │
+│  │  ┌──────────────────────────────────────────────────┐ │  │
+│  │  │  get_weather   Get the weather for a location    │ │  │
+│  │  │  list_files    List files in a directory         │ │  │
+│  │  │  read_file     Read a file by path               │ │  │
+│  │  └──────────────────────────────────────────────────┘ │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Behavior:
+
+- "List Tools" fetches the current MCP tool list for the selected server.
+- The response includes latency and discovered tool entries.
+- Selecting an entry opens it in the Tool Call section.
+
+## Tool Call Section
+
+Invokes a single MCP tool by name with user-supplied arguments.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Tool Call                                                  │
+│                                                             │
+│  Tool                                                       │
+│  [get_weather ▾]   (select from discovered tools)           │
+│                                                             │
+│  Schema                                                     │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  { "type": "object",                                  │  │
+│  │    "properties": {                                    │  │
+│  │      "location": { "type": "string",                  │  │
+│  │                    "description": "City name" }       │  │
+│  │    },                                                 │  │
+│  │    "required": ["location"] }                         │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+│  Arguments                                                  │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  {                                                    │  │
+│  │    "location": "San Francisco"                        │  │
+│  │  }                                                    │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                    [Call]   │
+│                                                             │
+│  Result                                                     │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  [text] The weather in San Francisco is sunny...    │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Behavior:
+
+- A discovered tool must be selected before calling.
+- Input schema is shown read-only.
+- Arguments are edited as JSON and validated before submit.
+- Calls are blocked for invalid JSON or missing required fields.
+- Results show latency and output content.
+- Output items are rendered by type: text, image, or resource.
+
+## API Behavior
+
+`/api/workspaces/[workspaceId]/tools/[id]/test` supports:
+
+- `GET`: list available MCP tools for the selected server
+- `POST`: call one MCP tool with JSON arguments
+
+Responses include latency and may include error information.