[xzxiaoshan]

Resolves #3298 #1963 #3443

Summary

Multi-tenant agents currently expose the same tool/skill inventory to every user. This PR introduces a server-side capability surface: an immutable, per-call grant enumeration resolved from the caller identity and enforced at both what the model sees (schema/prompt trimming) and what it can execute (hard gates) — without mutating the shared toolkit.

/**
 * Example resolver: computes the granted skill / tool capability list
 * dynamically, based on the current logged-in user's role.
 */
public class RoleBasedCapabilityResolver implements CapabilityResolver {

    @Override
    public CapabilitySurface resolve(RuntimeContext ctx, Agent agent) {
        // Read the caller's userId from the framework's ctx (RuntimeContext)
        String userId = ctx.getUserId();

        // The project team loads the skill/tool capability list for the user's
        // role based on userId — e.g. from its own permission system / RBAC
        // service (fixed values below stand in for the lookup result)
        // Grants grants = permissionService.findGrantsByUserId(userId);

        // Wrap the list as CapabilitySurface(allowedSkills, allowedToolGroups, allowedTools)
        return new CapabilitySurface(
                Set.of("pdf_export_custom"),  // allowed skillId
                Set.of("search"),             // allowed ToolGroup
                Set.of("web_read"));          // allowed individual tool name
    }
}

// ===== Assembling the agent: new the resolver separately, then pass it as an object =====
CapabilityResolver resolver = new RoleBasedCapabilityResolver();

ReActAgent agent = ReActAgent.builder()
        .capabilityResolver(resolver)
        // ... other configuration (model, tools, skills, etc.)
        .build();

// resolver returning null → unrestricted (same as not configured); throwing → the call aborts

How it works

The grant layer is a funnel with a single decision source (CapabilitySurface query methods); gates never re-derive authorization logic.

1. Declaration — CapabilityResolver (functional interface) computes pure whitelists from RuntimeContext (userId), optionally per agent. Resolved once at call() entry and carried on the rc for the whole chain; sub-agents inherit the parent surface without re-resolving (derived rc — no parent pollution). Concurrent calls with different users never cross surfaces.
2. Tri-state surface — three dimensions (skills / tool groups / per-name tools). All-null = unrestricted; any dimension set (even to an empty set) turns the surface into a complete enumeration; default deny.
3. Read points (model-visible):
   • Toolkit.getToolSchemas(groups, requestConfig, surface) — grant-filtered compose in a single pass; trimmed backend tools are treated as non-existent; external (request-config) tools stay caller-controlled; the reset_equipped_tools enum and description are rebuilt from activatable groups only, so cut-off group names and descriptions do not leak.
   • DynamicSkillMiddleware filters visible skills fail-closed (empty set on missing surface or filter error); the filtered list drives signature, box cache, prompt and loading alike.
4. Hard gates (execution, orthogonal to activation checks):
   • tools: ToolExecutor.requireToolGranted (backend only)
   • skill loading: SkillToolFactory convergence point (allowsSkill(AgentSkill) — full decision incl. system bypass; the id-based overload remains the grant-set-only fallback)
   • group activation: resetEquippedToolsImpl
5. System capabilities — isSystem() marking chain (@Tool annotation → ToolBase / ToolGroup / SkillToolGroup / AgentSkill builders, with copy/toBuilder retention) bypasses grant trimming; framework meta tools are marked; every system=true registration leaves an INFO audit trail.
6. Missing surface = unrestricted — direct executions that never entered an agent call() are trusted assembler code (the agent funnel always writes a surface); the same stance applies at read points and gates.

Security properties

• All model-facing denials are byte-identical to not-found wording (tools, skills, groups) — the model channel cannot distinguish "exists but ungranted" from "missing", and cannot relay "no permission" to the end user. The truthful cause is logged with userId/sessionId/agentId at each gate.
• The tool grant gate runs before the activation gate, so ungranted probes never reach activation wording; the activation message only speaks for granted-but-inactive tools (the designed self-healing path).

API changes

• Toolkit.getToolSchemas(Collection, ToolRequestConfig) is now package-private — it had no external consumers and is the natural entry for unfiltered model-visible synthesis; per-call compose now goes through the 3-arg overload where the surface decision is explicit in the signature (absent → no trimming). Visibility narrowing of a published API — flagged for review.
• Legacy 0/1-arg schema getters stay public for management/enumeration planes.

Known residual exposure

• Management/observation planes (aistio adapter, example REST controllers) intentionally export the full inventory — registration-time, not per-user.
• The static skillBox() path (or dynamicSkillsEnabled(false)) has no per-call skill visibility filtering: configuring a resolver there logs a build-time ERROR and disables it for the whole agent — all top-level calls of such an agent are entirely untrimmed (tools and groups included, not just the skill prompt). This is a deliberate fail-open trade-off to keep existing single-process builds working; strict deployments should fail fast themselves (wrap the builder and assert the combination after build()). When the agent runs as a sub-agent under an inherited surface, loading and execution stay gated — only the prompt still enumerates the full catalog. Multi-tenant setups should use skillRepositories(...).
• The per-call generate_response structured-output tool executes outside the executor (system-equivalent response mechanism).

⚠️ Breaking Changes

Toolkit.getToolSchemas(Collection<String>, ToolRequestConfig) is now package-private.

The 2-arg overload composes schemas without the capability grant layer. Keeping it public would
invite external callers into untrimmed model-facing synthesis — an avoidable authorization gap —
so it is intentionally narrowed; model-facing schema synthesis now goes through the 3-arg
overload where the surface decision is explicit in the signature.

Migration guide:

• Model-facing synthesis: switch to getToolSchemas(activeGroups, requestConfig, surface),
  reading the surface from the RuntimeContext: rc.get(CapabilitySurface.class) (pass null
  on trusted direct paths with no agent context — equivalent to the old behavior).
• Management/enumeration read-only uses: switch to getToolSchemas() or
  getToolSchemas(activeGroups) — behavior unchanged (these remain public).
• Framework-internal callers (ReActAgent, the AG-UI adapter) are already migrated.

[codecov]

Codecov Report

❌ Patch coverage is 87.39946% with 47 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../agentscope/core/skill/DynamicSkillMiddleware.java	58.82%	5 Missing and 2 partials ⚠️
...ava/io/agentscope/core/skill/SkillToolFactory.java	76.00%	1 Missing and 5 partials ⚠️
...src/main/java/io/agentscope/core/tool/Toolkit.java	92.77%	0 Missing and 6 partials ⚠️
...e/src/main/java/io/agentscope/core/ReActAgent.java	91.11%	0 Missing and 4 partials ⚠️
...va/io/agentscope/core/agent/CapabilitySurface.java	90.24%	2 Missing and 2 partials ⚠️
...java/io/agentscope/core/tool/ToolGroupManager.java	77.77%	1 Missing and 3 partials ⚠️
...n/java/io/agentscope/core/skill/SkillRegistry.java	25.00%	0 Missing and 3 partials ⚠️
.../java/io/agentscope/core/tool/MetaToolFactory.java	85.00%	0 Missing and 3 partials ⚠️
...ain/java/io/agentscope/core/tool/ToolExecutor.java	83.33%	0 Missing and 3 partials ⚠️
.../java/io/agentscope/core/skill/util/SkillUtil.java	60.00%	2 Missing ⚠️
... and 4 more

📢 Thoughts on this report? Let us know!

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit eef172e.

Approve preview