UN-3702 [FEAT] Hide deprecated runner tools from new workflows and block adding them

[Deepak-Kesavan]

What

• First step of deprecating the Docker-runner tools. The registry tools (Classifier classify, Text Extractor text_extractor, and any private registry tools) can no longer be added to a workflow.
• The workflow editor's tool list only shows a registry tool if the workflow already uses it.
• Creating or updating a tool instance with a registry tool is rejected by the API, except for an instance keeping the tool it already has.

Why

• UN-3702: the runner and its tools are being removed. Stopping new usage is the first step, so the set of workflows to migrate stops growing.
• Some workflows still use these tools (including API deployments and scheduled pipelines), so they must keep working and keep showing their tool.

How

• Backend
  • GET tool/ takes an optional workflow_id query param. ToolProcessor.get_tool_list keeps a registry tool only if that workflow already has an instance of it. The workflow is looked up through Workflow.objects.for_user, and a malformed workflow_id returns a 400.
  • ToolInstanceSerializer.validate_tool_id rejects registry tools. It runs on both create and update, so a PATCH can't switch an instance to one either. It allows an instance to keep the registry tool it already has.
  • ToolProcessor.is_registry_tool decides what counts as a registry tool: the uid resolves in the tool registry (public_tools.json / private_tools.json). Prompt Studio and agentic tools are keyed by UUIDs, so they're unaffected.
• Frontend (Agency.jsx)
  • Passes workflow_id when fetching the tool list.
  • Clicking the tool the workflow already has now does nothing. The replace flow deletes the instance and creates it again, and the backend would refuse to recreate a deprecated tool, so the workflow would lose it.
  • Fetches the tool list again after a switch, whether it succeeds or fails, so a deprecated tool that was removed drops out of the list.

Can this PR break any existing features. If yes, please list possible items. If no, please explain why. (PS: Admins do not merge the PR without this section filled)

• Workflows that already use Classifier or Text Extractor: their tool instance, settings form (tool_settings_schema) and execution are unchanged. Those still resolve the tool through get_tool_by_uid, which this PR doesn't touch, and the tool stays in their list.
• Intended change: users can no longer add Classifier or Text Extractor to a new workflow or one that doesn't have it, and can't switch an existing tool to one of them.
• Irreversible replace: if a workflow replaces its deprecated tool with a Prompt Studio tool, it can't go back.
• Callers of GET tool/ without workflow_id: they no longer get registry tools. The only other caller, CreateApiDeploymentFromPromptStudio.jsx, looks for Prompt Studio tools only, so it's unaffected.

Database Migrations

• None

Env Config

• None

Relevant Docs

Related Issues or PRs

• https://zipstack.atlassian.net/browse/UN-3702 (partial: this PR only stops new usage; a deprecation notice and removing the tools and runner come later)

Dependencies Versions

• None

Notes on Testing

• New unit tests in backend/tool_instance_v2/tests/test_deprecated_registry_tools.py:
  • The tool list filter, with and without the tool already in the workflow.
  • workflow_id parsing in the view: a UUID is passed through, a missing value lists without a workflow, and a malformed value returns a 400.
  • validate_tool_id through is_valid() for create, for update switching to a registry tool (rejected), and for an instance keeping its own registry tool (allowed).
  • is_registry_tool against the repo's real public_tools.json.
• All 45 tests in tool_instance_v2 pass locally. Removing the check makes the new validation tests fail.
• I haven't deployed this or checked it in the UI.

Screenshots

• N/A (a tool is left out of the existing list; the UI is otherwise unchanged)

Checklist

I have read and understood the Contribution Guidelines.

[github-actions]

Frontend Lint Report (Biome)

✅ All checks passed! No linting or formatting issues found.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[greptile-apps]

via Greptile

Confidence Score: 4/5

The PR appears safe to merge; database-backed coverage of existing-tool visibility would strengthen the rollout.

Findings

1.  Existing-tool lookup lacks coverage ▶

Fix with agent prompt

### Issue 1
backend/tool_instance_v2/tests/test_deprecated_registry_tools.py:73-76
The retention tests mock the lookup for tool IDs in a workflow, so they check the list filter but not the new database query. A regression in that query could hide a deprecated tool from a workflow that already uses it without failing these tests. Please add a database-backed test for an accessible workflow with an existing registry tool and one without it.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR hides Docker-runner registry tools from workflows that do not already use them, rejects new registry-tool instances, and keeps existing tools visible in the editor.

• Adds workflow-aware tool listing and serializer validation.
• Updates editor selection and refresh behavior.
• Adds unit coverage, but not an end-to-end check of the workflow-scoped lookup.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  UI[Workflow editor] -->|GET tool/?workflow_id| List[Tool list]
  List --> Scope[Accessible workflow instances]
  Scope -->|existing registry IDs| List
  UI -->|Create or update instance| Validation[Tool ID validation]
  Validation -->|new registry tool| Reject[Reject]
  Validation -->|unchanged existing tool| Keep[Allow]

Loading

_{Reviews (1) · Last reviewed commit: "UN-3702 [FIX] Self-review: gate tool_id ..."}

[greptile-apps]

Existing-tool lookup lacks coverage The retention tests mock the lookup for tool IDs in a workflow, so they check the list filter but not the new database query. A regression in that query could hide a deprecated tool from a workflow that already uses it without failing these tests. Please add a database-backed test for an accessible workflow with an existing registry tool and one without it.

Prompt To Fix With AI

This is a comment left during a code review.
Path: backend/tool_instance_v2/tests/test_deprecated_registry_tools.py
Line: 73-76

Comment:
**Existing-tool lookup lacks coverage** The retention tests mock the lookup for tool IDs in a workflow, so they check the list filter but not the new database query. A regression in that query could hide a deprecated tool from a workflow that already uses it without failing these tests. Please add a database-backed test for an accessible workflow with an existing registry tool and one without it.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[github-actions]

Unstract test results

Per-group results

Status	Group	Tier	Passed	Failed	Errors	Skipped	Duration (s)
❌	frontend	unit	0	1	0	0	0.0
❌	unit-backend	unit	1328	7	0	1	35.9
✅	unit-connectors	unit	72	0	0	0	8.7
✅	unit-core	unit	237	0	0	0	2.5
✅	unit-platform-service	unit	15	0	0	0	2.4
✅	unit-rig	unit	120	0	0	0	3.5
✅	unit-runner	unit	10	0	0	0	2.7
✅	unit-sdk1	unit	587	0	0	0	26.6
✅	unit-workers	unit	1373	0	0	1	125.9
	TOTAL		3742	8	0	2	208.1

Critical paths

⚠️ Critical paths not yet covered

• workflow-execution-fan-out — Multi-file workflow execution fans out to file-processing workers and rejoins. (declared coverage: no groups declared)

💤 Covered, but not exercised in this build

• auth-login — User can log in and obtain a session cookie. (covered by e2e-login; no result reported in this build)
• adapter-register-llm — Register and validate an LLM adapter. (covered by integration-backend; no result reported in this build)
• workflow-author — Create a workflow; its source+destination endpoints materialise and are configurable. (covered by integration-backend; no result reported in this build)
• co-owner-manage — Add/remove co-owners of a shared resource; enforce the last-owner guard. (covered by integration-backend, e2e-coowners; no result reported in this build)
• workflow-create-execute — Create a workflow, configure source+destination, execute, poll, fetch result. (covered by e2e-workflow; no result reported in this build)
• api-deployment-provision — Deploying a workflow as an API mints a usable key and a resolvable endpoint. (covered by integration-backend; no result reported in this build)
• api-deployment-auth — Unauthenticated or mis-scoped API-deployment calls are rejected before dispatch. (covered by integration-backend; no result reported in this build)
• api-deployment-run — Deploy a workflow as an API, POST a document, receive structured JSON. (covered by e2e-api-deployment; no result reported in this build)
• mcp-server-auth — Unauthenticated or mis-scoped hosted-MCP calls are rejected before any tool runs. (covered by integration-backend; no result reported in this build)
• mcp-platform-auth — The org-scoped MCP endpoint stays behind the platform-API-key middleware; unauthenticated or mis-scoped calls reach no tool. (covered by integration-backend; no result reported in this build)
• platform-key-whoami — A platform API key resolves its own organisation over the org-less whoami endpoint; the org comes from the key row, not the URL. (covered by integration-backend; no result reported in this build)
• prompt-studio-author — Create a Prompt Studio project and add a prompt to it. (covered by integration-backend; no result reported in this build)
• prompt-studio-fetch-response — Prompt Studio: create project, add prompt, run a prompt, get response. (covered by e2e-prompt-studio; no result reported in this build)
• connector-register-test — Connector credentials are validated against the live system and stored encrypted. (covered by integration-backend; no result reported in this build)
• pipeline-etl-execute — Run an ETL pipeline from source connector to destination. (covered by e2e-etl; no result reported in this build)
• usage-aggregate-read — Per-run token usage aggregates correctly and stays scoped to its organization. (covered by integration-backend; no result reported in this build)
• usage-token-tracking — Per-execution token usage is recorded and retrievable. (covered by e2e-api-deployment; no result reported in this build)
• callback-result-delivery — Async results are posted back via the callback worker. (covered by e2e-api-deployment; no result reported in this build)