feat: Split search-actors into data + -widget tools

[jirispilka]

🔗 PR chain — step 4 of 6 in #577

#	Issue	PR	Status
1	#714 — Rename openai → apps	#720	in review
2	#715 — Capability auto-detect + gating	#721	in review
3	#716 — fetch-actor-details split (pilot)	#722	in review
4	#717 (this issue)	#723	in review
5	#718 — call-actor split	#724	in review
6	#719 — get-actor-run split	#734	in review

Parent: #577. Depends on: #714, #715, #716.

---

Context and motivation

Child of #577. Mirrors the fetch-actor-details split (#716). Depends on #714, #715, and ideally #716 (pattern validated first).

After this PR:

• search-actors = data-only in both modes (replaces the search-actors-internal role)
• search-actors-widget = widget-only, additive in apps mode
• search-actors-internal = removed

Scope

In scope

• Align search-actors across modes to pure data (current default behavior)
• Create src/tools/apps/search_actors_widget.ts:
  • Input: keywords, limit, offset (reuse searchActorsBaseArgsSchema per refactor: Fold search-actors-internal args into shared schema #700)
  • Output: widget-shaped result list
  • _meta.ui.resourceUri, _meta.ui.visibility = ["model","app"], _meta.ui.csp
• Delete src/tools/apps/search_actors.ts (base is now mode-independent) and src/tools/apps/search_actors_internal.ts
• Add STORE_SEARCH_WIDGET to HelperTools; remove STORE_SEARCH_INTERNAL
• Update src/tools/categories.ts, src/utils/server-instructions/apps.ts
• Update references in src/tools/apps/call_actor.ts: STORE_SEARCH_INTERNAL → STORE_SEARCH

Out of scope

• Other tools (children 5–6)
• Widget UI code

Design notes

• Widget refetches server-side; input matches data tool.
• Existing searchActorsBaseArgsSchema (refactor: Fold search-actors-internal args into shared schema #700) reused for the widget input.
• Widget output schema: rename/adapt actorSearchInternalOutputSchema → actorSearchWidgetOutputSchema.

Files to modify / delete / create

File	Change
src/tools/apps/search_actors_widget.ts	create
src/tools/apps/search_actors.ts	delete (base is mode-independent)
src/tools/apps/search_actors_internal.ts	delete
src/tools/categories.ts	Register widget; drop internal; base is mode-independent
src/const.ts	Add STORE_SEARCH_WIDGET; remove STORE_SEARCH_INTERNAL
src/tools/structured_output_schemas.ts	Rename actorSearchInternalOutputSchema → widget variant
src/utils/server-instructions/apps.ts	Update references
src/tools/apps/call_actor.ts	Use base STORE_SEARCH

Internal repo impact

• STORE_SEARCH_INTERNAL removal — verify no internal-repo reference.

Testing strategy

Unit

• search-actors returns identical output in both modes
• search-actors-widget rejects extra params, returns widget shape
• Update tests/unit/tools.mode_contract.test.ts

Integration

• Add search-actors-widget case to tests/integration/suite.ts

mcpc probe (scripted — always run, compare UI vs non-UI)

Verifies the additive -widget layering: base tool stays byte-identical across modes; widget tool appears only in apps mode with correct _meta.

# Setup (one-time)
npm install -g @apify/mcpc
npm run build

# Connect both modes
APIFY_TOKEN=dummy mcpc connect "node dist/stdio.js" @default
APIFY_TOKEN=dummy mcpc connect "node dist/stdio.js --ui=true" @apps

# Capture tool shapes in both modes
mcpc --json @default tools-list \
  | jq '.tools[] | select(.name | test("^search-actors")) | {name, _meta, inputSchema, outputSchema}' \
  > /tmp/sa.default.json
mcpc --json @apps tools-list \
  | jq '.tools[] | select(.name | test("^search-actors")) | {name, _meta, inputSchema, outputSchema}' \
  > /tmp/sa.apps.json

diff /tmp/sa.default.json /tmp/sa.apps.json

Acceptance criteria:

• Default mode: exactly one tool matches search-actors; no -widget, no -internal
• Apps mode: exactly two tools — base search-actors AND search-actors-widget
• Base search-actors inputSchema + outputSchema byte-identical between modes
• Base search-actors _meta has no ui.* keys in either mode
• search-actors-widget._meta.ui.resourceUri == ui://widget/search-actors.html
• search-actors-widget._meta.ui.visibility == ["model","app"]
• search-actors-widget._meta.ui.csp is a non-empty object

Manual

• MCPJam: widget renders; ChatGPT: end-to-end parity

Verification checklist

• npm run type-check passes
• npm run lint passes
• npm run test:unit passes
• mcpc probe passes (all acceptance criteria above)
• Integration tests pass (human-run)
• MCPJam widget parity
• No -internal references remain
• Internal-repo audit complete