feat: deva_resource_run + deva_resource_inspect tools

[epanonymous]

Summary

References Bitplanet-L1/cross-eco-internal-docs#299.

Adds MCP tools for the merged generic resources rail:

• deva_resource_inspect -> GET /v1/agents/resources/catalog/{resource_id} as a safe/free catalog inspection tool.
• deva_resource_run -> POST /v1/agents/resources/{resource_id}/run with { resource_id, params } input and paid-tool policy gating.
• Updates tool inventory docs and coverage for endpoint mapping and local policy visibility.

Validation

• PASS nice -n 10 npm run build
• PASS nice -n 10 npm test -- --minWorkers=1 --maxWorkers=2 (21 passed, 7 skipped)

Note: nice -n 10 npm test -- --maxWorkers=2 was rejected by Vitest because its min/max worker settings conflicted; reran with explicit --minWorkers=1 --maxWorkers=2.

[claude]

Claude finished @epanonymous's task —— View job

---

PR Review: deva_resource_run + deva_resource_inspect

• Read changed files (balance.ts, tool-policy.ts, tests, README)
• Review code quality & best practices
• Check for bugs/issues
• Review security concerns
• Assess test coverage

Overall this is a clean, well-scoped PR. The two new tools follow existing conventions, the security policy gating is correct, and tests cover the new endpoint mappings and policy visibility. A few observations below.

---

Strengths

• Correct policy classification. deva_resource_inspect: safe() and deva_resource_run: paid() in src/tool-policy.ts:80-81 are appropriate. The test at test/tool-policy.test.ts:52,55 confirms inspect is listable by default and run is hidden until enabled.
• URL injection safety. Both tools use encodeURIComponent(resourceId) for the path segment (balance.ts:65,93), preventing path traversal / injection via resource_id.
• Input validation. asString rejects empty/non-string resource_id, and the new asObject helper rejects arrays/null/non-objects for params — good defensive validation.
• Tight schemas. additionalProperties: false on both tools with explicit required fields keeps the surface minimal.
• Tests are meaningful. test/tools.test.ts:71-76 asserts the exact method/path/body for both new tools, including that run sends params as the body (not wrapped).

---

Issues / Suggestions

1. params wrapping is plausibly wrong — worth confirming against the API. deva_resource_run sends params as the raw request body (balance.ts:94, body: params). But deva_cost_estimate for the same generic rail sends { resource_id, params } as the body (balance.ts:36, test tools.test.ts:65-69). So the two sibling tools use different body shapes for what looks like the same {resource_id, params} concept. If POST /v1/agents/resources/{resource_id}/run actually expects { params: {...} } or { resource_id, params }, this will silently send the wrong payload. Please double-check the endpoint contract in the referenced internal docs (#299). The test currently just locks in the chosen shape, so it won't catch a mismatch with the real API.

2. asObject is duplicated logic. balance.ts:3-9 defines a local asObject, while tool-policy.ts:143 has a similar asRecord. Consider centralizing object validation in src/tools/types.ts next to asString for consistency and reuse, especially since other tools may need the same params validation as the generic rail grows.

3. Empty params object is accepted. required: ["params"] + asObject allows params: {}. That may be intentional (some resources take no input), but if a resource always requires fields, the error will only surface upstream. Not blocking — just flagging the trade-off.

4. Doc count mismatch (pre-existing, not introduced here). README header says Tool Inventory (78) (README.md:178) while test/tools.test.ts:26 asserts a total of 51 tools, and the README sub-sections sum to ~73. The "Balance And Resources (5)" section is correctly updated, but the overall header count looks stale. Worth reconciling the source-of-truth count in a follow-up.

---

Test coverage

Good for what changed: endpoint mapping (tools.test.ts), inventory presence, and policy list/execute gating (tool-policy.test.ts). One gap worth adding: a negative test for deva_resource_run with a non-object params (e.g. a string/array) to lock in the asObject validation behavior.

---

Verdict: Approve-with-nits. The only item I'd want confirmed before merge is #1 (the run body shape vs. the actual API contract), since a payload-shape mismatch would be a silent runtime bug not caught by the current tests.
• Branch: feat/resources-discover-inspect-run-tools